Skip to content

R5: simulator CLI, worker-backed web host, real Electron shell - #22

Open
CodeByBryant wants to merge 1 commit into
claude/kind-edison-2locd1-r4-pixifrom
claude/kind-edison-2locd1-r5-apps
Open

CodeByBryant wants to merge 1 commit into
claude/kind-edison-2locd1-r4-pixifrom
claude/kind-edison-2locd1-r5-apps

Conversation

@CodeByBryant

Copy link
Copy Markdown
Owner

Summary

Sixth PR of the restructure stack, stacked on #21 (R4). Merge bottom-up; retarget to main once the PRs below it merge.

Makes the three apps real: a headless CLI, a web app whose simulation lives in a worker behind a testable host, and a working Electron shell. This closes the restructure's key exit criterion: the same seed produces the same hash in Node, in the worker, and in the CLI.

Stack: #17 R0 → #18 R1 → #19 R2 → #20 R3 → #21 R4 → R5 (this PR) → R6 tests/CI → R7 docs.

Changes

apps/simulator-cli

pnpm sim --seed N --ticks N [--config f.json] [--save f | --load f] [--json | --summary] [--validate]. run(argv, io) is a pure function over an injected Io (37 tests). It prints the state hash by default; --config reproduces a pinned scenario from the golden file; exit codes are 0 ok, 1 request failed (invalid config, bad save), 2 usage error. Errors are one clean line, never a stack trace.

apps/web

  • MapView no longer assembles a world by hand. SimulationHost runs World in a worker (world.worker.ts); the host takes an injected worker, so it is tested with a fake (21 tests).
  • readyMessage.ts builds the worker→app message as a pure function. Design point: the worker must keep its World (later phases step it there), so it sends copies of the tile layers and transfers only buffers made for the occasion. A test runs the message through structuredClone with transfer and shows the sender's buffers are detached while the world still hashes, validates and steps.
  • Generation failure now returns to the title screen instead of hanging on "generating" forever. Nations are the contract's NationSnapshot (the UI never needed the engine class).

apps/desktop

A real Electron shell (CJS main/preload, contextIsolation, no Node in the page). The window may show only the app: navigation to the web or to any other file, and window.open, are blocked through pure, tested helpers (isAppUrl, resolveWebEntry, with injectable path rules so Windows paths are tested on Linux). electron-builder ships the web build as resources/web.

Workflows

release.yml ported from the old npm scripts to a pnpm matrix job (Windows/Linux/macOS).

Verification

  • Cross-runtime hash (the exit criterion): the full 2000×2000 seed-1337 world from the real worker through the real SimulationHost in Chromium hashes to 6b461ddd6eb60e50262f93eca686be6a, identical to the CLI's (Node 22). The same run showed an invalid config rejected cleanly and the host reusable afterwards.
  • No regression vs R4: 0 differing map pixels in all 7 scripted states, identical hover text and identical click/nation-panel results, even though the world is now produced by World.create inside the worker.
  • The real CLI binary (not just the in-memory tests): reproduces golden hash 08009323… from the golden config, saves and loads through real files, uses the documented exit codes, 2000×2000 in 4.6 s.
  • The real Electron app, run under Xvfb and driven over the DevTools protocol: loads the web build, window.sovereign is exposed, no require/process in the page, the world generates (the module worker works from file://, which I had specifically worried about), no console errors; navigation to https://example.com, to file:///etc/hostname and window.open are all blocked while the app stays responsive.
  • The packaged app: built with electron-builder --dir, then launched from release/linux-unpacked/: it loads resources/web/index.html (the packaged branch of the path logic) and generates a world.
  • 572 tests across the workspace (config 50, renderer 39, simulation 416, CLI 37, web 21, desktop 9), all mutation-checked; full pnpm build passes.

Bugs this verification found (and that unit tests could not)

  1. The real CLI choked on pnpm start -- --seed 1: pnpm forwards the literal -- and my parser treated it as an unknown option. Fixed with a test-first change (a bare -- means "end of options").
  2. The packaged Linux binary was named @sovereigndesktop (from the scoped package name). Windows already set executableName; Linux now does too.

Known and intentional

  • Not verified: installers for Windows and macOS (nsis, dmg) and the release.yml workflow itself. I can't run GitHub Actions or those OSes here; the YAML is syntax-checked and the Linux unpacked build was exercised. Treat the first real release run as the test.
  • Electron was run with --no-sandbox --disable-gpu under Xvfb (the container has neither a display nor a GPU), so WebGL ran in software; the shipped app does not pass --no-sandbox and sets sandbox: true on the window.
  • The shell loads from file://. That worked, including the worker; a custom app:// protocol would be the next hardening step if remote content is ever introduced.
  • No auto-update (electron-updater was an unused dependency in the original; removed in R0).
  • SimulationHost exposes create and hash only; stepping and time controls arrive with the first simulation systems (roadmap Phase 3).

Related Issues

Part of the R0-R7 restructure stack.

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Refactor / cleanup (no functional changes)
  • Documentation update

Checklist

  • Code compiles without errors (pnpm build)
  • Linting passes (pnpm lint, now with zero warnings)
  • Type checking passes (pnpm typecheck)
  • Tested locally in both Electron and web modes (Electron under Xvfb, web in Chromium; no real GPU)
  • Updated documentation / JSDoc where applicable (JSDoc yes; architecture docs are written in R7)

Generated by Claude Code

…l (R5)

Three apps, each testable on its own.

apps/simulator-cli: `pnpm sim --seed N --ticks N [--config f] [--save f | --load f]
[--json | --summary]`. run(argv, io) is a pure function over an injected Io (37
tests, mutation-checked). Prints the 32-char state hash by default; --config
reproduces a pinned scenario. The real binary reproduces a golden hash, round-trips
through real files, and uses the documented exit codes (0 ok, 1 failed, 2 usage).
Running it found a bug in-process tests could not: pnpm forwards a literal "--".

apps/web: MapView no longer hand-assembles a world. SimulationHost runs World in a
worker (world.worker.ts); readyMessage.ts builds the message as a pure function,
sending COPIES of tile layers so the worker keeps its World, and transferring only
buffers made for the occasion (a structuredClone-with-transfer test proves the
world survives). The host takes an injected worker (21 tests). Generation failure
now returns to the title screen instead of hanging. Nations are the contract's
NationSnapshot. Verified identical to R4: 0 differing map pixels in all 7 states,
identical hover/click results. The real worker's hash for a full 2000x2000 seed-1337
world equals the CLI's: 6b461ddd6eb60e50262f93eca686be6a.

apps/desktop: real Electron shell (CJS main/preload, contextIsolation, no Node in
the page, navigation and window.open locked to the app via pure, tested helpers).
Launched under Xvfb and driven over CDP: loads the web build, generates a world,
blocks navigation to the web and to other files. electron-builder packs the web
build as resources/web; the unpacked package was built and run (found and fixed an
executable name of "@sovereigndesktop"). release.yml ported to pnpm (YAML validated;
not run here).

Also fixes the last MapView hooks lint warning; lint is now warning-free.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Cn5qp59UwGNst3umuaQf6u
Copilot AI balanced review requested due to automatic review settings November 20, 2026 03:42

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants