Open any picture thumbnail in the shared picview

AI Assisted
This commit is contained in:
jparkerweb committed 2026-11-03 03:24:39 -08:00
1 parent 1eef797dc0
commit c26759fd88
10 files changed
+495 -254

No files matched your search

+64 -14
View File
@@ -39,6 +39,7 @@ plan2code/
│ └── statusline-config.json # Default config template
├── src/launcher/ # Global `plan2code` command (Node.js, zero deps)
│ ├── plan2code.js # Opens /plan2code in Claude Code or Devin in the cwd (or a picked folder)
│ ├── agents.json # Shipped agent list (built-ins + starter templates with per-OS install data), copied to ~/.plan2code/bin/ on install
│ ├── models.json # Curated model menu, copied to ~/.plan2code/bin/ on install
│ └── plan2code.ico # Desktop shortcut icon (Windows)
├── src/web-console/ # Local browser UI bundled into every skill (Node.js, zero deps, no build)
@@ -66,7 +67,7 @@ plan2code/
├── .husky/ # Git hooks (husky)
│ └── pre-commit # Runs character count validation
├── .claude/ # Repo-local Claude Code config (NOT installed by install.js)
│ └── skills/ # Maintainer-only dev skills, e.g. plan2code-publish/, plan2code-model-update/
│ └── skills/ # Maintainer-only dev skills, e.g. plan2code-publish/, plan2code-launcher-update/
├── .github/ISSUE_TEMPLATE/ # bug.yml, idea.yml, config.yml (target of the console's feedback button)
├── .readme/ # User guides linked from README (web-console.md, web-console-design.md, walkthrough.md, metrics.md, status-line.md, test-bot.md)
├── docs/ # Landing page `index.html` served at plan2code.jparkerweb.com (GitHub Pages, `CNAME`) and assets
@@ -92,22 +93,24 @@ plan2code/
| `version.json` | Version metadata (name, version, description) |
| `QUICK-REFERENCE.md` | User quick-reference card |
| `src/statusline-claude/` | Claude CLI status bar (see Status Line below) |
| `src/launcher/plan2code.js` | Global `plan2code` command that opens the dashboard skill in Claude Code, Devin or Codex (installed by `I` and Advanced → `E`; also via Advanced → `D`). When the desktop app is installed (`~/.plan2code/app/plan2code-app[.exe]`, or the file `PLAN2CODE_APP` names) and a display exists (Windows and macOS always; Linux needs `DISPLAY` or `WAYLAND_DISPLAY`), it opens the app after the agent and model questions with `--project <folder> --agent <id> [--model <id>]` and exits; `--classic` (never forwarded to the CLI) and a failed spawn keep the terminal flow. The app reads all three (`project::launch_choice`): the picker starts on `--agent`, and `--model` applies to that agent on every start and Restart (`AgentManager::set_model`); a model never applies to another agent |
| `src/launcher/plan2code.js` | Global `plan2code` command that opens the dashboard skill in Claude Code, Devin or Codex (installed by `I` and Advanced → `E`; also via Advanced → `D`). When the desktop app is installed (`~/.plan2code/app/plan2code-app[.exe]`, or the file `PLAN2CODE_APP` names) and a display exists (Windows and macOS always; Linux needs `DISPLAY` or `WAYLAND_DISPLAY`), it opens the app after the agent and model questions with `--project <folder> --agent <id> [--model <id>]` and exits; `--classic` (never forwarded to the CLI) and a failed spawn keep the terminal flow. The app reads all three (`project::launch_choice`): the picker starts on `--agent`, and `--model` applies to that agent on every start and Restart (`AgentManager::set_model`); a model never applies to another agent. Its menu, lookup and no-agent flow come from `agents.json` through `agent-lookup.mjs`, loaded by dynamic `import()` from `~/.plan2code/bin/` (the launcher's one stated exception to its Node-built-ins-only rule; a missing copy falls back to the plain printed install steps) |
| `plan2code-app/` | Tauri desktop app (Rust host, xterm panel, the console's dashboard in a frame; its own README). `RELEASE-CHECKLIST.md` lists the by-hand checks before each release. `src-tauri/src/versions.rs` compares the app's version (`tauri.conf.json`) with the installed skills' (`~/.plan2code/bin/version.json`) for the bar's **Update skills** line, which runs `node ~/.plan2code/bin/plan2code.js update` only when pressed |
| `plan2code-app/src-tauri/src/attention.rs` | The taskbar signal's rules, pure and knowing nothing about Tauri: `Signal` (`busy`, `ready`, `attention`, `plain`), `badge_for(signal, os, enabled)` (Windows: green dot on `ready`, red on `attention`; macOS: red `!` on `attention` only; Linux: count 1 on `attention`), `should_flash(prev, next, focused, enabled)` (once, only on a change into `ready` or `attention` while unfocused) and `dot_rgba()` (the dot's pixels, in the favicon's colors, which a test checks against `public/favicon.js`). `main.rs` applies the result through `set_attention`, `set_taskbar_signal` and `clear_attention_cmd`; the page asks with the `attention` and `taskbar` messages (`public/app-bridge.js`) and the switch is `taskbarSignal` in the app's own `~/.plan2code/app.json`. |
| `plan2code-app/src-tauri/src/quit_prompt.rs`, `task_dialog.rs` | The quit check shown while an agent runs. `quit_prompt(last_signal)` is pure: the page's last taskbar signal `ready` or `plain` is the waiting case ("Done for now?", Info icon), and `busy`, `attention` or none yet is the working case ("Leave while your agent is busy?", Warning icon). `task_dialog.rs` (Windows only) draws it with `TaskDialogIndirect` through `winapi`: a heading, Stay as the default, and the app's icon in the title bar, since the dialog plugin has no heading and Windows copies its icon into the title bar (the warning once showed twice). `confirm_quit` in `main.rs` runs it on its own thread; macOS and Linux use the plugin box with the same words, where Quit stays the default button (putting Stay first would make Esc quit). A page reload or an unanswered page clears the signal to none (`clear_attention`), so the box stays on the working words until the page reports again; `QUIT_OPEN` keeps a second box from stacking |
| `plan2code-app/src-tauri/src/loop_driver.rs` | The Implementation Loop's driver. Its decisions are pure functions and carry the unit tests: `phase_prompt()` (the prompt each fresh phase session starts on), `judge_outcome()` (the skill's `loopOutcome` against the spec's marks and the setup), `silence_expired()`, `should_retry()` (one retry for a crash or silence, never for a real failure), `open_question()` and `stop_line()`. Around them sit the running record (app memory only), the watch thread and the stop and resume entry points. **The app, not the agent, marks a loop phase done and commits it**; the skill only builds and reports |
| `plan2code-app/src-tauri/src/loop_driver.rs` | The Implementation Loop's driver. Its decisions are pure functions and carry the unit tests: `phase_prompt()` (the prompt each fresh phase session starts on), `judge_outcome()` (the skill's `loopOutcome` against the spec's marks and the setup), `expect_patch()` (the `loopExpect` judging criteria stamped into the session so the console refuses a bad report at post time), `silence_expired()`, `should_retry()` (one retry for a crash or silence, never for a real failure), `open_question()` and `stop_line()`. Around them sit the running record (app memory only), the watch thread and the stop and resume entry points. **The app, not the agent, marks a loop phase done and commits it**; the skill only builds and reports |
| `plan2code-app/src-tauri/src/loop_commit.rs` | The loop's commit step, called by `handle_outcome` in a fixed order: prepare (subject, message), stage and check the staged names and sizes against a denylist (`.env*` except `.example`, `.sample`, `.template`; oversized files; a bad list unstages all and stops), save the phase file text, mark done, commit with its own limit, and on a failed commit restore the saved text only if the file still equals what the loop wrote (else stop with "marked, not committed", kept in the reports store). Stop now never commits; `judge_outcome` refuses missing task data and failed tests; the watcher runs under `catch_unwind` and counts unreadable sessions as silence; `loop_state` in `main.rs` redraws the strip after a reload |
| `plan2code-app/src-tauri/src/loop_notify.rs` | The loop's notification: `NotifyKind` (query string, JSON body, Discord, Slack, Teams, Google Chat; its comment lists what a new service needs), `valid_url()`, `valid_param()` (mirrored in `loop-setup.mjs` and `screens/loop-setup.js`), `request_for()` (each kind's address and body) and `send()`, with a 10 second limit and errors that never hold the address. The driver writes the message and calls it from `observe()`, `stop_loop()` and `finish()`. |
| `plan2code-app/src-tauri/src/loop_report.rs` | The loop's report on everything done for the person: one `LoopReport` per build, entries in order (passed, stopped, retried) with findings fixed, skipped and left open, assumptions read from the phase file, and reported decisions. Saved in the console's `loop-reports.json` after every entry, because a project file would dirty the tree Resume needs clean; `finish()` writes it to `LOOP-SUMMARY-<date>.md` and removes the entry. |
| `plan2code-app/src-tauri/src/loop_tools.rs` | What the loop runs on its own, each call with a time limit and its output kept: the spec scripts (`specs.mjs status`, `mark --to done`), `commit-msg.mjs`, git (`add`, `commit`, `status`, the short head), the console's `post` and `open --resume`, and the person's quick check. No shell runs here except the quick check, whose text comes only from `loop-setup.json`, never from a page message |
| `plan2code-app/src-tauri/src/agents.rs` | Custom agents in the app: `CustomAgent`, the `Agent` handle over built-ins and custom entries, `load_custom_agents`, reading the Agents file below; the console side is `src/web-console/agents.mjs` |
| `plan2code-app/src-tauri/src/agents.rs` | Agents in the app: `CustomAgent`, the `Agent` handle over built-ins and custom entries, `load_custom_agents`, reading the Agents file below; the shipped `agents.json` read at run time with the baked copy as fallback; `find_on_path`, the Rust twin of `agent-lookup.mjs`'s `findAgent` (PATH, PATHEXT, the saved PATH from `node_check::resolved_path()`, npm's global folder, the install folders), held to `scripts/fixtures/agent-lookup-cases.json`. The console side is `src/web-console/agents.mjs` |
| Desktop app install (`install.js`) | `installDesktopApp()` downloads `plan2code-app-<version>-<windows\|macos\|linux>-<x64\|arm64>[.exe]` and `plan2code-app-<version>-SHA256SUMS.txt` from the GitHub release (`PLAN2CODE_RELEASE_BASE` replaces the URL; the tests serve a stand-in), checks the SHA-256 and places the file in `~/.plan2code/app/` (the old file is renamed aside first, since Windows cannot overwrite a running exe). `app` is an install piece (`INSTALL_PIECES`, after `launcher`), so `plan2code update` updates it with the rest. `install()` asks for it after the command (default yes; a no is kept as `skipped` in `install.json`); unattended it installs it unless it is already recorded or was declined. A failed app never fails the install. `.github/workflows/release-app.yml` builds one file per system (`tauri build --no-bundle`) and the checksum list on a published release, after `scripts/check-versions.mjs --tag` |
### Agents file
`~/.plan2code/agents.json` holds the person's custom agent CLIs. The web console is its only writer (User Preferences → Agents & models, through `POST /agents`); the `plan2code` launcher and the desktop app only read it. Each reader carries its own copy of the rules (`src/web-console/agents.mjs` for the console, a copy in `src/launcher/plan2code.js`, `agents.rs` in the app), and `scripts/fixtures/agents-cases.json` is the contract all three readers' tests load: file normalization with its warnings, `buildArgs` command lines and `makeId` ids. Change a rule in the fixture first.
`src/launcher/agents.json` is the shipped list: `kind: "builtin"` entries (Claude Code, Devin, Codex) with `installUrl`, per-OS `install` lines and `installDirs`, and `kind: "template"` entries other CLIs can be saved from. `install.js` copies it to `~/.plan2code/bin/agents.json` beside `agent-lookup.mjs`, which all JS readers share: `loadAgentList()` reads it, `findAgent()` gives a command its `found` / `outside` / `missing` state (PATH, the saved Windows PATH, npm's global bin, the entry's `installDirs`). The app reads the same JSON with `serde_json` at run time (`include_str!` of the repo file baked in as fallback) and `find_on_path` in `agents.rs` is its Rust twin: `scripts/fixtures/agent-lookup-cases.json`, loaded by `scripts/test-agent-lookup.mjs` and by `cargo test` through `include_str!`, is the contract both lookups are held to.
- **File:** `{ "schema": 1, "agents": [...] }`. Any other schema, text that is not JSON, or `agents` that is not a list gives no custom agents and one warning. A missing file is an empty list with no warning. More than 50 entries: the first 50 are used. Unknown keys, in the file and in an entry, are kept when the console saves.
- **Entry:** `id`, `name` and `command` are required; `args` (default `[]`), `prompt` (default `"/plan2code"`, blank allowed), `bypassArgs` (`[]`), `modelArgs` (`["--model", "{model}"]`) and `models` (`[]`, each `{ id, label? }`) are optional. The three argument fields are lists of text, one list item per argument.
- **Rules:** `id` matches `^[a-z0-9][a-z0-9-]{0,31}$`, is not `claude`, `devin` or `codex`, and is unique; `name` is at most 60 characters and unique ignoring case; `command` is not blank. `makeId(name, taken)` makes the id from the name in kebab case (`agent` when nothing is left), with `-2`, `-3` on a clash, at most 32 characters.
@@ -192,7 +195,7 @@ Maintainer-only skills committed to the repo but deliberately excluded from the
- `plan2code-publish/` — publishes a GitHub Release after version files agree.
- `plan2code-changelog/` — validates release classification and keeps version files synchronized.
- `plan2code-model-update/` — refreshes the launcher's curated model menu (`src/launcher/models.json`) from `devin models list` and Claude Code's documented model aliases: shows a diff, applies only the changes the maintainer approves, validates the file and runs `npm test`. Terminal only, and it never commits.
- `plan2code-launcher-update/`: refreshes the launcher's shipped data: the curated model menu (`src/launcher/models.json`) from `devin models list` and Claude Code's documented model aliases, and the agent list's install data (`src/launcher/agents.json`) re-checked against each vendor's docs, including a re-check of the agents left out as templates (Cursor CLI, Aider) against the template rule. Shows a diff, applies only the changes the maintainer approves, validates both files and runs `npm test`. Terminal only, and it never commits.
- `sync-repo/` — decrypts the protected upstream-sync workflow in memory.
Do not run `skills add` against the repository root: recursive discovery also finds these maintainer skills. `install.js` targets `skills/` and passes explicit workflow names instead. Global install/uninstall cleanup removes `plan2code-*` workflow skills from user skill directories; it never operates on this repository's `.claude/skills/` directory, and `sync-repo` intentionally has no `plan2code-` prefix.
@@ -216,6 +219,7 @@ Optional local browser UI shipped with **every** skill. Source lives in `src/web
| `cmd-small.mjs` | the small commands: keep, forget, delete-spec, handoff, delete-handoff, status and stop; `handoff new` refuses an unknown `--workflow` the same way `open` does |
| `files.mjs` | where the console's files live, how they are written safely, and the argument parser both command lines share |
| `agents.mjs` | the rules of `~/.plan2code/agents.json` (see Agents file above), console side: `normalizeAgents()` reads the file into clean entries and warnings, never throwing; `validateForSave()` checks what User Preferences sends and names the first bad entry and field; `makeId()`, `buildArgs()` (the command line from an entry) and `resolveCommand()` (where a command runs from, never running it). Served by `GET` / `POST /agents` and `POST /agents/test` in `routes.mjs` |
| `agent-lookup.mjs` | where an agent lives on this machine: `loadAgentList()` reads the shipped `bin/agents.json` (built-in agents and starter templates; `optional` keeps an absent file silent); `findAgent()` gives one command its `found` / `outside` / `missing` state, the path and which search found it (PATH, the Windows saved PATH, npm's global bin, the entry's `installDirs`), with `{bypass}` / `{model}` placeholders expanded to the user's picks. Used by `GET /agents`, `POST /agents/use-path`, the launcher's `chooseCli()` and the Windows picker |
| `inbox.mjs` | the Quick question chat's inbox beside the card slot |
| `console-docs.md` | the topic file for `docs` in a patch (tabs of blocks), named by the console at the first patch that carries `docs`; not read up front. Byte-budgeted with the card and the notes in `scripts/test-console-wire-budgets.mjs` |
| `pointers.mjs` | which topic file the console names and when: once per session per topic, remembered in the session folder (`pointers.json`), reset by a resume |
@@ -273,6 +277,12 @@ Optional local browser UI shipped with **every** skill. Source lives in `src/web
| `public/activities/ghoul-cart.js` | Ghoul Rush's Runaway Cart, the Mine's ride room, its rules (no imports; draws no random number): the first room where a pack takes Planny's movement over. It adds the pack fields `ride` (a list of `(round, ms, k) => true` hooks run each slice before the walking rules; one that returns true has moved him) and `place` (a list of `(round, k)` hooks run whenever he is put down in a room: a room set up, a respawn), uses `target` (the crates), and `round.camLead` (units the camera leads further). The cart (`round.cart`, null elsewhere) rides the room's `ride.track` polylines (slope speed, lean and brake, jump, air steering, ramp launch, landing on the line under it, derail into the chasm), ducks under `ride.beams`, wrecks on `rubble` and unbroken `crates` (two bolts break one), is chased by the boulder, passes `checks` (a life lost puts it back at the last) and halts at `stop` where the door opens; a ledge imp (`ledgeimp`) leaps into it and steals light, a canary's scream drops a slide of rubble on the track ahead. Exports `flight`, `trackY`, `linesAt` and `linesOf` for the unit suite. Events `cartJump`, `cartLand`, `cartLaunch`, `cartBrake`, `cartDuck`, `crateHit`, `crateBreak`, `cartCrash`, `boulderNear`, `checkpoint`, `cartStop`, `ledgeLeap`, `slideWarn`, `slideFall`; causes `derail`, `beam`, `crash`, `boulder` |
| `public/activities/ghoul-cart-draw.js` | The Runaway Cart's art: `LOOKS` (`custom: true`, `pack: "cart"`, always dark), `cartArt(d)` returning `backdrop`, `ground`, `moving` (every frame: the cave in cached parallax tiles over a chasm, the trestled track, ledge pillars, signal posts, rubble and the buffer stop in cached chunks, hanging lamps, signal lamps, crates, a slide's dust and pour; the cart too once it has stopped, so Planny walks out past it), `front` (the cart over Planny, the beams, the boulder, flying splinters, speed streaks, the foreground rock), `lights` (headlamp, hanging and far lamps, signals, beams), `monsters` (the ledge imp) and `react`; its `VOICES` (borrowed tones), `EVENT_VOICE`, `LOSE_WORDS` and `LOSE_SOUNDS`. It keeps its own offscreen layer cache (keyed by scale), draws no random numbers (a hash) and leaves short-lived bits in the view's `fx` (`cartBits`, `cartPours`, `cartLand`, `cartStop`). Its header lists every field the art reads off the rules |
| `public/activities/ghoul-sfx-mine.js` | The Mine's own sounds as data (no imports): `MINE_SFX` with an empty `tones` and `music` until the user picks them; merged by `ghoul-sfx.js` via `STAGE_SFX` (its rooms play existing tracks, set in `ROOM_MUSIC`) |
| `public/activities/ghoul-bog.js` | Ghoul Rush's Gallows Bog stage pack, its rules (no imports; a pack `ghoul.js` plugs in through `PACKS`, handed the kit `k`): the lurker, leech swarm, will-o'-wisp and bog body (`MONSTERS`, with `walkers`/`zombies` sets), `act`, `solid`, `swoops`, `unseen`, `move`, `kill`, `horde`, `tick` (the wisp's lure), `bosses`/`boss`, `weak`, `cause` and `hazards`, and Old Mother Bog (`BOSSES`). Its header notes the movers, the lure and the boss fight land in a later phase: this file stands the pack up so the stage's rooms can be walked. The stage's second twist lives in the engine, not here: a room field `mud` (frozen `[x0, x1]` spans), `mudAt` in `ghoul.js`, `you.mud` and `you.mudMs` (the run sags from `WATER_SPEED` toward `MUD_SPEED_MIN` and a jump toward `MUD_JUMP_MIN` over `MUD_MS`; a shelf, the air and Stilt Boots (`round.effects.boots`) let go of it) |
| `public/activities/ghoul-bog-draw.js` | The Gallows Bog's drawing: `LOOKS` for its rooms (`outdoor: true`, `pack: "bog"`) and `bogArt(d)`, handed `ghoul-draw.js`'s helpers, returning the night swamp rooms (boardwalk planks over black water, moss veils, fireflies, the hag's lit stilt house and her open-water arena), `monsters` (a lurker's eyes, a leech swarm, a will-o'-wisp, a bog body), `bosses` (Old Mother Bog and her cauldron), `hazards` (the mud wave, the muck patches), the Stilt Boots' and Harpoon's badges and the events' looks and sounds; its `VOICES` are borrowed house tones until the sound page's vote, `LOSE_WORDS` and `LOSE_SOUNDS` already named |
| `public/activities/ghoul-bogboat.js` | The Bog Runner (Gallows Bog's bonus round) as a pack (`BOGBOAT`), modeled on the Midnight Hearse for its lanes and the Torch Mob for its pursuit meter: pack fields `ride`, `place` and `target`; state in `round.runner` (`id: "bogboat"`); a flat channel of two lanes (open water and the mud flats) switched at banks, with sunken snags and cypress knees to jump, moss veils and low limbs to duck, the hag's charms and gas pockets to shoot, and the wake (a leech swarm `gap` units behind that closes on slow or stalled riding and catches you at `WAKE_CATCH`). Its checkpoints and grade (3 to 9 dice) run through the Cart's bonus machinery. Adds no monster, boss or hazard kind and draws no random number; every event starts with `bogboat` and every number is an exported constant documented in its header |
| `public/activities/ghoul-bogboat-draw.js` | The Bog Runner's art: `LOOKS`, `VOICES`, `EVENT_VOICE`, `LOSE_WORDS`, `LOSE_SOUNDS`, `telegraphMarks`/`telegraphs` (JUMP, DUCK, SHOOT and SWITCH glyphs for the ride's lanes) and `bogboatArt(d)` (pale moon, drowned cypresses, mist, black channel and mud flats by `moving`, the bow, the signs and the wake meter by `front`); no random numbers, everything from a hash |
| `public/activities/ghoul-sfx-bog.js` | Gallows Bog's own sounds as data (no imports): `BOG_SFX` with `tones` (a `ghoul<Kind><Act>` tone for each act of the lurker, leech, wisp, bog body and Old Mother Bog) and an empty `music` until the music vote is wired in (the rooms play borrowed tracks through `ROOM_MUSIC`); the tones are first drafts (option 1 of each act) until the sound vote; merged by `ghoul-sfx.js` via `STAGE_SFX` |
| `public/activities/ghoul-sfx-bogboat.js` | The Bog Runner's own sounds as data (no imports): `BOGBOAT_SFX` with `tones` (`ghoulBogboat<Act>`) and the ride's `music` track; first drafts until the vote; merged by `ghoul-sfx.js` via `STAGE_SFX` |
| `public/activities/ghoul-carnival.js` | Ghoul Rush's Midnight Carnival stage pack, its rules (no imports; draws no random number): uses `tick` (the ring of samples Mirror You reads and its bolts in `round.twist`), `shot` (Cotton Candy's slow, a marionette's string at the top of its body), `target` (a bolt crossing a marionette's string or one of the puppet's three), `guard` (the Ringmaster is open only with the puppet down), `swoops` (a balloon, a circus hound's leap), `solid`, `kill` and `fourLegged`. Grinner and its acid balloons, marionette (drops when you pass under), Mirror You (copies you 500 ms late, mirrored, its bolts cancel yours), strongman (barbells), circus hound, and the Ringmaster (a gantry over the ring that follows its puppet at a lag, the puppet stalking you and working to a fixed script of leap, stomp, whip and charge, three strings from the gantry to its head and hands that move with it, open 4 s when they are cut, rage with hounds from the cages); `CARNIVAL_ROOMS` lists the stage's rooms, with a place before the Big Top for the dark ride. The room field `belts` and Planny's `you.belt` (the funhouse's conveyor floors) are run by `ghoul.js`. |
| `public/activities/ghoul-carnival-draw.js` | The Carnival's art: `LOOKS` (`custom: true`, `pack: "carnival"`), `carnivalArt(d)` returning the world's hooks (from `ghoul-carnival-world.js`) plus `monsters`, the `ringmaster` boss (gantry, puppet in each pose, strings, whip), `missiles` (barbell), `hazards` (foot, whip, charge), `waves` (the puppet's), `powers` (Cotton Candy), `front` (Mirror You's bolts, Cotton Candy's glow), `lights` and `react`, and `VOICES` (borrowed tones), `EVENT_VOICE`, `LOSE_WORDS`, `LOSE_SOUNDS`. Its header lists what the art reads off the rules. |
| `public/activities/ghoul-carnival-world.js` | The Carnival's world (no imports; `carnivalWorld(d)` takes ghoul-draw.js's helpers): the night sky with a Ferris wheel (`sky`), tents, booths and swagged bulbs on the Midway, the Hall of Mirrors' gilded panels and glints, the Funhouse's crooked walls, spiral discs and clown-mouth door, the Big Top's striped canvas, ring curb, crowd, trapeze boards, gantry rail and cages (open once the Ringmaster rages), and the belts' chevrons (`moving`). |
@@ -292,9 +302,36 @@ Optional local browser UI shipped with **every** skill. Source lives in `src/web
| `public/activities/ghoul-frozen-world.js` | The Frozen Lake's world (no imports; `frozenWorld(d)` takes ghoul-draw.js's helpers): the night sky with moon, aurora and far mountains (`sky`), the huts, the Lodge's fallen roof, the Black Ice and the Widow's web (`backdrop`, `ground` with the ice's gloss, `shelf`), and `moving` (open water in the holes, thin ice drawn from `round.thin`, never from `spec.ground`, the faces under the Black Ice, falling snow) and `lights`. Draws no random number |
| `public/activities/ghoul-flare.js` | The Road Flare's rules (`useFlare`, `stepFlareFly`, `stepRoadFire`; no imports, handed the helpers by `ghoul-arms.js`): a lob that lands as a patch of fire, burns monsters on a tick, melts a Frozen Ghoul at once, shows a shade and melts the Widow's veil; never hurts Planny |
| `public/activities/ghoul-sled.js` | The Coffin Sled (the Frozen Lake's bonus round) as a pack (`SLED`), modeled on the Runaway Cart (`ghoul-cart.js`): pack fields `ride`, `place` and `target`; the track of ice lines with cracks, headstones, drifts, low branches, hands, icicles and popping ghouls, checkpoints, hearts through the Cart's bonus machinery and the grade (3 to 9 dice). Adds no monster, boss or hazard kind and draws no random number; every number is an exported constant documented in its header |
| `public/activities/ghoul-hearse.js` | The Midnight Hearse (the Graveyard's bonus round) as a pack (`HEARSE`), modeled on the Coffin Sled: pack fields `ride`, `place` and `target`; state in `round.runner` (`id: "hearse"`); a flat road of two lanes (road and verge) switched with LEFT/RIGHT inside the lane gates, open graves, headstones and crosses to jump, low branches and the lychgate arch to duck, hands and crows to shoot, closed stretches to go round, lanterns that keep the lamp lit (an unbroken lamp is the grade's `steady` die), and coffins thrown out by each hit with a ghoul to shoot in each. Adds no monster, boss or hazard kind and draws no random number; every number is an exported constant documented in its header |
| `public/activities/ghoul-hearse-draw.js` | The Midnight Hearse's art: `LOOKS` (`pack: "hearse"`), `VOICES`, `EVENT_VOICE`, `LOSE_WORDS`, `LOSE_SOUNDS`, `telegraphMarks`/`telegraphs` (JUMP, DUCK, SHOOT and SWITCH glyphs for the hearse's lane) and `hearseArt(d)` (sky, hills, cemetery, road, verge, things and the hearse by `moving`; the cab door, lows, fog, glyphs and lamp gauge by `front`; `dim` when the lamp is out); no random numbers. Its header lists what the art reads off the rules |
| `public/activities/ghoul-sled-draw.js` | The Coffin Sled's art: `LOOKS`, `VOICES` (borrowed tones), `EVENT_VOICE`, `LOSE_WORDS`, `LOSE_SOUNDS` and `sledArt(d)` (the sky, hills, ice and things by `moving`, the lid, the lows and foreground flakes by `front`); no random numbers. Its header lists what the art reads off the rules |
| `public/activities/ghoul-gurney.js` | Code Blue (Blackmoor Sanatorium's bonus round) as a pack (`GURNEY`), modeled on the Coffin Sled: pack fields `ride`, `place` and `target`; the gurney along `ride.track` (shafts are the gaps), wheelchairs that roll, IV stands, lamps and doors overhead, orderlies in doorways, the lights-out waves (`lightsAt`), the surge lamps and the heartbeat monitor's beat; its state is `round.runner` (`pack: "codeblue"`, put back if another pack's `place` clears the shared slot); draws no random number; imports the cart's track helpers |
| `public/activities/ghoul-gurney-draw.js` | Code Blue's art: `LOOKS`, `VOICES`, `EVENT_VOICE`, `LOSE_WORDS`, `LOSE_SOUNDS`, `telegraphMarks`/`telegraphs` and `gurneyArt(d)` (the corridors, shafts and floors by `moving`; the gurney, lows, glyphs, countdown and monitor by `front`; `dim` and `lights` for the blackouts); no imports but the Sled's glyph colors |
| `public/activities/ghoul-mower.js` | The Gardener's Revenge (the Grounds' bonus round) as a pack (`MOWER`), modeled on the Coffin Sled: pack fields `ride`, `place` and `target`; state in the shared `round.runner` slot (id `mower`); a flat lawn run on a ride-on mower with gaps (ponds, ha-ha ditches), junk, hedge arches, clothes lines of gloves and snapping topiary beasts, and the twist: holding fire lowers the blades, which cut tall grass, weeds and thorn hedges in the zone ahead (the blades heat and jam, so they are pulsed); the lawn-cut share is the grade's steady die; hearts through the Cart's bonus machinery; no random numbers |
| `public/activities/ghoul-mower-draw.js` | The Gardener's Revenge's art: `LOOKS`, `VOICES`, `EVENT_VOICE`, `LOSE_WORDS`, `LOSE_SOUNDS`, `telegraphMarks`/`telegraphs` (JUMP, DUCK and CUT glyphs) and `mowerArt(d)` (sky, manor, topiary and railings by `moving`, the lawn with its ponds and ditches, the mower with its blades and heat gauge, the lows and the lawn gauge by `front`); no random numbers |
| `public/activities/ghoul-sfx-frozen.js` | The Frozen Lake's own sounds as data (no imports): `FROZEN_SFX` with an empty `tones` and `music` until the user picks them; merged by `ghoul-sfx.js` via `STAGE_SFX` (its rooms play existing tracks, set in `ROOM_MUSIC`) |
| `public/activities/ghoul-sfx-mower.js` | The Gardener's Revenge's own sounds as data (no imports): `MOWER_SFX` with first-draft `tones` (`ghoulMower<Act>`, each under 1.2 s) and the `ghoulMowerRide` track (sound and music picks still pending); merged by `ghoul-sfx.js` via `STAGE_SFX`, the track set in `ROOM_MUSIC` |
| `public/activities/ghoul-pew.js` | Holy Roller (the Chapel's bonus round) as a pack (`PEW`): a Subway-Surfers style endless-runner seen from behind, pack fields `ride`, `place` and `target`; state in the shared `round.runner` slot (id `pew`). `you.x` is only the distance run; the pew's own `lane` (a float to `laneTo`), `h`, `slide`, `combo` and `magnet` live in `round.runner`. Left/right presses change lane (a wall bump at the edge), up jumps, down slides (fast-fall in the air), fire shoots down the lane; a speed ramp by distance (`speedAt`); `KINDS` (switch: pillar, confessional, pewx; jump: kneeler, stand, cracks, hatch; slide: censer, banner, beam; shoot: garg with 2 hp, bell rope), wax souls and halos, the combo and the steady die (souls share); a hit shoves the pew to a calm lane. Pure rules, no random numbers |
| `public/activities/ghoul-pew-course.js` | Holy Roller's seeded course (no imports): written in seconds and laid by the speed ramp (`xAt`, `speedAt`, `V0`, `ACC`), `COURSE` { items [x, lane, kind, len], souls, checks, finish } |
| `public/activities/ghoul-pew-draw.js` | Holy Roller's art: `LOOKS`, `VOICES`, `EVENT_VOICE`, `LOSE_WORDS`, `LOSE_SOUNDS` and `pewArt(d)`, whose `field(ctx, view)` draws the WHOLE field (ghoul-draw.js has a `round.runner.id === "pew"` branch like the dark ride's `round.gallery` one, then adds the hearts, flash, banner, cards and HUD pills) plus the progress track, souls and combo strip, and the events' effects |
| `public/activities/ghoul-pew-world.js` | Holy Roller's pseudo-3D nave: `worldArt(d)` with `paint(ctx, view)`; the projection `(lane, depth, height)` to the screen with scale = near / (near + depth) toward a vanishing point, far-to-near cells with fog as alpha, stained glass, pillars and ribs, pews, candlelight and god rays pulsing on the organ's beat (`pulse`, `BPM`), every thing's art and telegraph glyph, the souls, bolts, the pew and hero from behind, speed streaks and vignette. A reusable pattern for "run into the screen" rides. No random numbers (hashes) |
| `public/activities/ghoul-sfx-pew.js` | Holy Roller's own sounds as data (no imports): `PEW_SFX` with 17 tones (lane, bump, jump, land, slide, dive, soul, halo, crash, check, finish, speed swell, gargoyle and bell) and the driving `ghoulPewDirge` track at 132 BPM (first drafts, merged by `ghoul-sfx.js`) |
| `public/activities/ghoul-sfx-hearse.js` | The Midnight Hearse's own sounds as data (no imports): `HEARSE_SFX` with 19 first-draft `ghoulHearse<Act>` tones (none over 1.2 s) and the `ghoulHearseRide` track (a funeral march at a gallop, built from three four-bar parts); merged by `ghoul-sfx.js`, named in `ROOM_MUSIC`. Sounds and music still to be picked by ear |
| `public/activities/ghoul-sfx-sled.js` | The Coffin Sled's own sounds as data (no imports): `SLED_SFX` with an empty `tones` and `music` until the user picks them; merged by `ghoul-sfx.js` (the room plays the Graveyard's `ghoulGraves`) |
| `public/activities/ghoul-banister.js` | The Grand Banister (the Manor's bonus round) as a pack (`BANISTER`), modeled on the Coffin Sled: pack fields `ride`, `place` and `target`; state in the shared `round.runner` slot (id `banister`); YOU slide down a grand staircase's banister along `ride.track` (the first `rails` lines are the handrail, the breaks between them gaps to jump; the rest are brass under-rails beside it, the split track: a jump with DOWN held dives onto one, a jump off its end lands back on the handrail), vases and candlesticks to jump, hanging portrait frames to duck, chandeliers on a pendulum (`swingAt`: a wall from the bob to the roof, lethal to a ducking rider while the bob is mid-swing, so you brake or lean (LEFT/RIGHT) to time them or take the under-rail), ghostly butlers that lunge (jump or two bolts) and cobwebs to shoot. Adds no monster, boss or hazard kind; no random numbers. Its header documents the room fields |
| `public/activities/ghoul-banister-draw.js` | The Grand Banister's art: `LOOKS` (`pack: "banister"`), `VOICES`, `EVENT_VOICE`, `LOSE_WORDS`, `LOSE_SOUNDS`, `telegraphMarks`/`telegraphs` (JUMP, DUCK and DIVE glyphs) and `banisterArt(d)` (damask wall, moonlit windows, a zig-zag of staircase flights, portraits whose eyes follow YOU, the rails, props, butlers and webs by `moving`; the hanging frames, the chandeliers with the arc they swing through, sparks and glyphs by `front`); no random numbers. Its header lists what the art reads off the rules |
| `public/activities/ghoul-sfx-banister.js` | The Grand Banister's own sounds as data (no imports): `BANISTER_SFX` with 14 first-draft `ghoulBan<Act>` tones (each under 1.2 s) and the `ghoulBanister` track (a harpsichord waltz at a gallop, built from three four-bar parts); merged by `ghoul-sfx.js` via `STAGE_SFX`, named in `ROOM_MUSIC` (sound and music picks still pending) |
| `public/activities/ghoul-wagon.js` | The Torch Mob (Hollow End Village's bonus round) as a pack (`WAGON`), modeled on the Coffin Sled: pack fields `ride`, `place` and `target`; a hay wagon along `ride.track` (ditches and the collapsed bridge are the gaps, a rising line end a ramp), barrels and crates, washing lines and inn signs, villagers who hurl pitchforks (duck) and torches (jump), spooked horses, and the pursuit meter (`gap`: the mob runs at `MOB_V`, DOWN is a duck and the brake, a hit, a burning hay load and the surge close it, a shot torch or fork opens it, inside `PANIC_ON` the horses bolt, at `CATCH_GAP` it is a heart); its state is `round.runner` (`id: "wagon"`); draws no random number; imports the cart's track helpers |
| `public/activities/ghoul-wagon-draw.js` | The Torch Mob's art: `LOOKS` (`pack: "wagon"`), `VOICES`, `EVENT_VOICE`, `LOSE_WORDS`, `LOSE_SOUNDS`, `telegraphMarks`/`telegraphs` and `wagonArt(d)` (the sky, rooftops, street, cobbled road, ditches, the bridge and river, the things, the mob and the wagon by `moving`; the lows, throws in the air, the hay fire, glyphs and the mob's meter by `front`); no random numbers; imports the Sled's glyph colors and the rules' constants |
| `public/activities/ghoul-sfx-wagon.js` | The Torch Mob's own sounds as data (no imports): `WAGON_SFX` with 18 first-sketch `ghoulWagon<Act>` tones and the `ghoulWagonRide` track (a D minor gallop built from three 4-bar patterns); merged by `ghoul-sfx.js`, the room's track named in `ROOM_MUSIC` (`wagon`) |
| `public/activities/ghoul-story.js` | Ghoul Rush's intro story: the pages' text as data and the rules (lockout, reveal, skip) as plain functions over a round; drawn by `ghoul-story-draw.js`, sounded by `ghoul-sfx-story.js`, the lore bible in `prototypes/Ghoul-Rush-TODO.md` |
| `public/activities/ghoul-story-draw.js` | The intro story's drawing (`storyArt(d)`): eight animated scenes in canvas shapes (the road, the house on the hill, the hunger, the long arms, the farthest rooms, why YOU, no way back, the door to The Long Hall) with the heading, the lines typing out, the page dots, the always-visible skip hint with its hold bar and the pulsing continue hint; drawn over the field while `round.phase === "story"`; reuses the intro card's helpers (`poly`, `dot`, `stroke`, `faint`, `flame`, `titleLayout`, `dropAt`); no gradients |
| `public/activities/ghoul-story-draw.js` | The intro story's drawing: `ghoulStoryDraw(d)` scenes for the pages in `ghoul-story.js` |
| `public/activities/ghoul-sfx-story.js` | The intro story's own sounds as data (no imports): `STORY_SFX` tones for the pages' `cues` (wind, a bell, a heartbeat, a door creak, knocks, a whisper, the flashlight click, the page turn) and the `hums` drone under the whole story; merged by `ghoul-sfx.js` |
| `public/activities/ghoul-sfx-gurney.js` | Code Blue's own sounds as data (no imports): `GURNEY_SFX`, 18 first-pick `ghoulBlue<Act>` tones and the track `ghoulBlueRide`; merged by `ghoul-sfx.js` (the room plays it via `ROOM_MUSIC.codeblue`) |
| `public/activities/ghoul-tray.js` | The Servants' Back Stairs (the East Wing's bonus round) as a pack (`TRAY`), modeled on the Coffin Sled: pack fields `ride`, `place` and `target`; the track of shelves and stair flights with gaps, rolling pots and cutlery, hams and pans, cooks who fling dishes, the courses (silver domes and flying plates, seven is the grade's acts die), the cherries, grease stretches, checkpoints and the grade (3 to 9 dice). State is `round.runner` (id `tray`), the shared slot for a rolling bonus ride. Adds no monster, boss or hazard kind and draws no random number; every number is an exported constant documented in its header |
| `public/activities/ghoul-tray-draw.js` | The Servants' Back Stairs' art: `LOOKS`, `VOICES`, `EVENT_VOICE`, `LOSE_WORDS`, `LOSE_SOUNDS`, the telegraph glyphs (`telegraphMarks`, `telegraphs`: JUMP, DUCK, SHOOT) and `trayArt(d)` (the kitchen, shelves and stairs, things and cooks by `moving`; the tray, hams and pans, flour and glyphs by `front`); no random numbers |
| `public/activities/ghoul-sfx-tray.js` | The Servants' Back Stairs' sounds and music as data (no imports): `TRAY_SFX` with 13 first-draft tones and the `ghoulTrayRide` track; merged by `ghoul-sfx.js` |
| `public/activities/ghoul-sfx-chapel.js` | The Chapel's own sounds as data (no imports): `CHAPEL_SFX`, its `tones` (the 35 picked `ghoul<Kind><Act>` sounds of the gargoyles, choir ghosts, monks, bell bats, the Choirmaster, the bell and Holy Water's splash) and `music` (`ghoulNave`, `ghoulTower`, `ghoulLoft`, `ghoulChoir`, named in `ROOM_MUSIC`), merged by `ghoul-sfx.js` via `STAGE_SFX` |
| `public/activities/ghoul-sfx-sanatorium.js` | Blackmoor Sanatorium's own sounds as data (no imports): `SANATORIUM_SFX`, its `tones` (the 38 picked `ghoul<Kind><Act>` sounds of the orderlies, gurneys, flickers, specimen bloaters, the Night Matron, the lamps, Smelling Salts and the Bone Saw) and `music` (`ghoulAdmissions`, `ghoulBaths`, `ghoulTheater`, `ghoulWard`, named in `ROOM_MUSIC`), merged by `ghoul-sfx.js` via `STAGE_SFX` |
| `public/activities/ghoul-sfx-village.js` | Hollow End Village's own sounds as data (no imports): `VILLAGE_SFX`, its `tones` (the 42 picked `ghoul<Kind><Act>` sounds of the torch mob, hanged men, shutter ghouls, moonhounds, the Beast, the full moon and Wolfsbane) and `music` (`ghoulStreet`, `ghoulInn`, `ghoulSquare`, `ghoulGreen`, named in `ROOM_MUSIC`), merged by `ghoul-sfx.js` via `STAGE_SFX` |
@@ -304,6 +341,8 @@ Optional local browser UI shipped with **every** skill. Source lives in `src/web
| `scripts/test-web-console-activities-ghoul-mine.mjs` | The Mine's suite: the rooms and the cage rows, rockfall timing, aim and crush, the Hard Hat (stage-only, bounce), the imp's light steal (no life, ended by a shot or a stomp, blocked by the hat), the canary's scream and its three rocks, the miner's dig and swing, the blind crawler losing and hearing you (and the water's louder steps), water slowing you, the cage carrying Planny, Dynamite (a double tap, the bag, the blast), every Tommyknocker move including the dark, the decoy, the burst, the dazed double damage and the rage cap on imps, no random draws, endless lives for every new cause, and a voice for every act and event |
| `scripts/test-web-console-activities-ghoul-carnival.mjs` | The Carnival's suite: the rooms and the belts, grinners and their balloon cap, balloons and their acid, the marionette's drop and its string, Mirror You (the delay, the mirrored moves, jumps, its bolts and their canceling, stunned by a pie), the strongman, the circus hound (a swoop, duckable), Cotton Candy, the Custard Pie, every Ringmaster move (stalk, leap, charge, stomp, whip, the strings following, open, rage, hounds, the script), no random draws, endless lives for every new cause, and a voice for every act |
| `scripts/test-web-console-activities-ghoul-grounds.mjs` | The Grounds' suite: each monster's behavior, the shears, the Groundskeeper's moves and phases, a voice for every act, each event playing exactly one picked sound, and every picked tone present in the merged tones |
| `scripts/test-web-console-activities-ghoul-bog.mjs` | Gallows Bog's suite: the stage row and its rooms, the mud (slow, sink, jump, shelf, boots), each monster's behavior (the lurker's eyes and snap, the leech's latch, the wisp's light, the bog body's rise), the wisp lure and its fairness cap, the harpoon under the water, Old Mother Bog's wave, weak cauldron, muck, sink and resurface, a voice for every act with exactly one picked sound per event, words and a sound for every cause, both cards, the round flow, drawing dark and lit, and a seeded bot on a draw that throws if the pack asks for a random number |
| `scripts/test-web-console-activities-ghoul-bogboat.mjs` | The Bog Runner's suite: the ride's course, the lanes and banks, jumping, ducking and shooting, the wake and its panic, checkpoints, the grade, endless lives, the telegraphs, drawing, and bots that dodge and do not |
| `public/activities/ghoul-picker-draw.js` | The choice of stage, its drawing: `pickerArt(d)`, handed `ghoul-draw.js`'s helpers (`lookOf`, `label`, `roundRect`, `circle`, `BOSS_ART`, `drawGourdFire`, `GOLD`), returning `drawPicker` (a card per stage offered: its picture of its rooms with its boss standing there, its name, line and boss, the pick raised and edged in gold, and how to choose), `drawSelect` (the stage select for testing: every stage in a list, two columns past 8, the one picked out with its picture and a chip per room) and `stageColor` (a stage's boss room's color, also the tally dots'). Split from `ghoul-draw.js` to keep it under the 3,000-line cap |
| `public/activities/ghoul-powers.js` | Ghoul Rush's power-ups and pickups (no imports: `ghoul.js` hands its rules a kit, `POWER_KIT`, of `landing`, `MAX_LIVES` and the numbers they need): `POWERS` (each power-up's name, line, color, `ms` if timed, drop `weight`, and its rule, the Lantern's `dark`), `TIMED`, `PILL_WORDS`, `FLAP_CLEAR`, `HOURGLASS_MS`, `CANDY_POINTS`, `POWER_POINTS`, `CRYSTAL_POINTS`, `powerHere(round, kind)` (whether a power-up can turn up in the room as it is now; a new rule, such as a stage-only power-up, goes in `POWERS` and is checked here), `pickPower`, `applyPower(round, kind, kit)` (`ghoul.js` exports it bound to its kit as `applyPower(round, kind)`) and `pickups` (candy, placed and dropped power-ups, crystals up high and the key, taken by touch; drops fall and fade). Split from `ghoul.js` to keep it under the 3,000-line cap |
| `public/activities/ghoul-arms.js` | Ghoul Rush's secondary weapons (imports only `ghoul-powers.js`; a pack in `PACKS`, `ARMS`): the double tap (`pressFire`, `releaseFire`, called from the game's `key()` and `release()`, never from `round.input.fire`, so bots never throw), the bag `round.arms` (`useArm`, `armOnTop`: a ride room skips what needs a floor), each weapon's rule (a shot with `arm` through `moveShots`, or a hazard), and `armBossDamage` (scaled to depth, capped at `ARM_BOSS_SHARE` of a boss's hp a fight). Weapons' names, bundles and caps are in `POWERS` (`arm: true`, weight 0), the stage's own in `STAGE_ARMS`, the kill drop band in `armDrop`, all in `ghoul-powers.js`. |
@@ -319,6 +358,10 @@ Optional local browser UI shipped with **every** skill. Source lives in `src/web
| `public/activities/ghoul-bonus-draw.js` | The bonus rounds' art (`bonusArt(d, die)`): `card` ("BONUS CLEARED! +N LUCKY DICE" with the dice tumbling in, or the short "BONUS LOST"), `react` (the intro banner, the end, the hearts-left float) and `tick` (a click for each die landed) |
| `public/activities/ghoul-dice-draw.js` | The Lucky die's art (`diceArt(d)`: the small drop, the rolling die on a panel placed away from Planny, the sweeping "LUCKY-SAVE" word, and `react` for the dice events, which plays `ghoulLuckySave` once on the revive) |
| `public/activities/ghoul-gameover-draw.js` | The lost end screen's "G A M E - O V E R" (`gameOverBanner(d)`, `dropAt`): nine letters dropping in with a stagger and one bounce, then bobbing on a sine wave under a slow pulse, red and bone with a dark shadow, drawn above the score panel and never on a win. `ghoul.js` keeps ticking the clock on the lost end screen (`view.overMs`) and plays the mechanical laugh track there: `ghoulLaughTrack`, `ghoulLaughTrack2` and `ghoulLaughTrack3` in `ghoul-sfx.js`, one second apiece (a tone may not pass 1.2 s). |
| `public/activities/ghoul-intros.js` | The stage intro cards' words and colors: `INTROS` per stage id (`title`, `palette` {a, b, glow}, `kicker`, 3 or 4 `lines` of flavor text at most `MAX_LINE` characters, `boss`), `introFor(id)`. Always addressed to YOU. A test fails for a stage in `STAGES` with no card. |
| `public/activities/ghoul-intro-draw.js` | The intro card's drawing (`introArt(d)`, `titleLayout`, `dropAt`): the title's letters dropping in and glowing, one themed flourish per stage (frost crystals, bunting, pickaxe sparks, leaves, candle flames, ...), the lines fading in, the boss and the pulsing "Press any move key or fire to enter". Drawn over the field while `round.phase === "intro"`. The phase itself lives in `ghoul-run.js` (`startIntro`, `stepIntro`, `takeIntro`, `INTRO_MIN_MS` 1.2 s: any fresh move key, fire or a click moves on after it, repeats never, and the card never moves on by itself); the tone is `ghoulStageIntro`. |
| `public/activities/ghoul-boss-intros.js` | The boss intro cards' words: `BOSS_INTROS` per boss id (`name`, which must equal the boss's `name` in its pack's `bosses` table, an `epithet` of at most `MAX_EPITHET` characters and an optional `accent` color), `bossIntroFor(id)`. A test fails for a boss room whose boss has no entry. |
| `public/activities/ghoul-bossintro-draw.js` | The boss intro card's drawing (`bossIntroArt(d)`): a "BOSS FIGHT" title whose letters slam in with a screen shake and a heartbeat pulse, the boss drawn from its own art (`BOSS_ART`, the way the stage pick does) at a big scale in a spotlight on the stage's palette, its name, the epithet and the pulsing "Press any move key or fire to start the fight"; a boss whose art throws falls back to a silhouette. Drawn over the field while `round.phase === "bossintro"`. The phase lives in `ghoul-run.js` (`startBossIntro`, run by `enter` on every boss room, and `onCard`; it shares `introMs`, `stepIntro`, `takeIntro` and `INTRO_MIN_MS` with the stage card, and a respawn never shows it); the tone is `ghoulBossIntro`. |
| `public/activities/ghoul-monsters-draw.js` | The generic monsters' art (`monsterArt(d)`, no imports; `ghoul-draw.js` hands it its helpers `ellipse`, `circle`, `line`, `rotate`, `turned`, `eye` and the colors): `drawZombie`, `drawZombieKin`, `drawHuntsman`, `drawCrawler`, `drawBat`, `drawGhost`, `drawSkeleton`, `drawGourdling`, `drawHound`, `drawSpider`, `drawWraith`, `drawSpitter` and the missiles `drawBoneShape` and `drawGlob`. Split from `ghoul-draw.js` to keep it under the 3,000-line cap |
| `public/activities/pills.js` | The pills every game but Mini golf draws along its top (no imports): `drawPill(ctx, x, y, w, h, text, color, fill, textY)` on one opaque dark backing, `PILL`, the same in light and dark and over any scene, a timer's share still left tinted at `PILL_TINT`, and the text in `pillInk(color, tinted)`: the pill's own color when it reads at `PILL_CONTRAST` (4.5:1) on the backing (and on the tint while a timer runs), else the least step toward white that does, so warnings stay red; lives are the one solid pill: a pill in the `LIVES` color is drawn on `LIVES_BACK` in white (`LIVES_INK`), its text from `livesText(n)` (a heart per life up to five, `♥ xN` past that, `♡` at none); `pillTint` and `pillContrast` for the unit suite |
| `public/activities/golf.js` | Mini golf: six eighteen-hole courses, one round at a time; its rules and physics as plain exported functions (`newRound(courseId)`, `holesOf`, `coursePar`, `strike`, `advance` on a fixed 4 ms sub-step, `nextHole`, `total`, `toPar`, `predictPath` for the spyglass, `moverAt`, `gateShut`, plus ice that barely slows the ball and wells that pull it in or push it away), the `POWERUPS` held for the next putt (`round.held`, then `round.active` for that putt), the arcade swing (`startSwing`, `setPower`, `meterAt`, `meterZone`, `swingShot`: a ping-pong power meter, slow at the bottom and fast at the top, with a MAX band that boosts and an overswing band that shanks; a shot clock in `advance()` that starts the meter after `SHOT_CLOCK_MS` and dribbles the ball after `METER_TRIPS` trips; all on the round's own clock), the pop-up gags, and the game contract with `pointer()` (the aim follows the pointer, a press swings, a press held on a roll fast-forwards), `release()` (held arrows turn the aim, held space fast-forwards) and `lowerIsBetter`, `courses` (the dashboard's cards), `preview(canvas, id, w, h)` (a course's card art) and `setCourse(id)`; deterministic (no `Math.random()`), a read-only `round` getter for the unit suite only |
@@ -357,7 +400,7 @@ Optional local browser UI shipped with **every** skill. Source lives in `src/web
| `public/activities/snake-sfx.js` · `public/activities/golf-sfx.js` · `public/activities/trails-sfx.js` · `public/activities/bugs-sfx.js` · `public/activities/drive-sfx.js` · `public/activities/stack-sfx.js` · `public/activities/bumper-sfx.js` · `public/activities/rapids-sfx.js` · `public/activities/fuse-sfx.js` · `public/activities/hop-sfx.js` · `public/activities/bounce-sfx.js` · `public/activities/ghoul-sfx.js` | each game's own sound effects as data, `{ tones, hums }` in the shapes `tones.js` documents, every name prefixed with the game id (`driveEngine`, `ghoulMoan`), merged and frozen by `tones.js`; no imports, but for `ghoul-sfx.js`, which merges each Ghoul Rush stage's own `ghoul-sfx-<stage>.js` into its `tones`, `hums` and `music` |
| `public/activities/ghoul-sfx-graveyard.js` | The Graveyard's own sounds as data (no imports): `GRAVEYARD_SFX`, its `tones` (the picked `ghoul<Kind><Act>` sounds of the grasping hands, mourners, grave robbers, rotters and their legs, carrion crows and Mother Mourning) and `music` (`ghoulLychgate`, `ghoulGraves`, `ghoulMausoleums`, `ghoulAngel`, named in `ROOM_MUSIC`), merged by `ghoul-sfx.js` after the house's own. Every new stage gets its own `ghoul-sfx-<stage>.js`, listed in `STAGE_SFX` there |
| `public/activities/ghoul-sfx-grounds.js` | The Grounds' own sounds as data (no imports): `GROUNDS_SFX`, its `tones` (the 32 picked `ghoul<Kind><Act>` sounds of the topiary beasts, rootlings, lantern moths, mulch crawlers, the Groundskeeper and the Hedge shears' snip) and `music` (`ghoulMaze`, `ghoulTopiary`, `ghoulGazebo`, `ghoulYard`, named in `ROOM_MUSIC`), merged by `ghoul-sfx.js` after the house's own via `STAGE_SFX` |
| `public/uploads.js` | pictures and documents attached to a note: chips, trays, re-encoding, upload, retry |
| `public/uploads.js` | pictures and documents attached to a note: chips, trays, re-encoding, upload, retry, and the page's shared full-screen picture preview (`openPicview`, the `#picview` dialog every thumbnail opens) |
| `public/screens/ask.js` | the Ask chat, the Subagents tab, and attaching files to notes |
| `public/screens/cards.js` | question cards: every kind, the pager, settled and in-flight records |
| `public/screens/cleanup.js` | User Preferences' Cleanup section, on the System tab |
@@ -369,8 +412,13 @@ Optional local browser UI shipped with **every** skill. Source lives in `src/web
| `public/screens/git-host.js` | hosts the git board: tabs, panels and what each click sends |
| `public/screens/help-dialog.js` | the Help dialog and the first-run Welcome (named so it is never confused with the pure help.js). Help reads right in both modes: a phrase that differs under the desktop app carries its app wording in `data-app` (swapped in by `renderAppWording()`), and a paragraph that differs is a `.for-browser` / `.for-app` sibling pair, switched by `:root.in-app` (set in `core.js` from `page.inApp`, rule in `help.css`). The older `render*Help()` functions patch a few ids the same way. `scripts/test-web-console-page-help.mjs` sweeps every topic's visible text in each mode for the other mode's wording |
| `public/screens/looks.js` | User Preferences: the look and sound controls, which save as they change |
| `public/screens/agents-view.js` | User Preferences' Agents & models tab: a summary table (Claude, Devin, Codex, added agents, a v3 orchestrator row) with Found / Not found on PATH badges, and Edit opening one agent's form. Each form edits a draft; Save sends the saved list with only that draft swapped in (`POST /models` or `POST /agents`), Discard drops it. `hasUnsaved`, `saveOpen` and `discardOpen` feed the dialog's unsaved prompt |
| `public/screens/prefs-dialog.js` | User Preferences as a dialog: its four tabs (wired by `tabs.js` from `PREFS_TABS`), `openPrefs(tab)` (the one way in, loading Agents & models each time), the fading Saved mark beside a fieldset (`markSaved`), Back to default for the tab on screen, and `confirmUnsaved()`, the in-dialog Save / Discard / Keep editing prompt before Close, Esc, a backdrop click, a tab switch or Back to summary leaves an unsaved agent edit. Other screens reach it through `hooks` |
| `public/screens/agents-view.js` | the agents view's mount, state and server calls, serving both User Preferences' Agents & models tab and the setup page as a master-detail split: the pickable list on the left, the picked agent's form or state in the right pane. Picking a row is the navigation; a dirty form asks the dialog's unsaved prompt first. Each form edits a draft; Save sends the saved list with only that draft swapped in (`POST /models` or `POST /agents`), Discard drops it. `hasUnsaved`, `saveOpen` and `discardOpen` feed the dialog's unsaved prompt. `mountAgentsView(container, {mode, forCli, onStart})` hands its renderers one `ctx` (state plus callbacks); `mode: "prefs"` draws the agent rows with Found / Not found on PATH badges and a v3 orchestrator placeholder, `mode: "setup"` draws the pick list (found / outside-PATH / missing states, install lines, Use it from here, templates, Start) inside a caller-supplied container |
| `public/screens/agents/agents-data.js` | PURE, no imports, `node --test` importable: the agents view's data helpers. `MODEL_CLIS`/`BUILT_IN` (the built-in rows, pinned to `src/launcher/agents.json` by a test), `emptyLists`, `newAgent`, `normalizeAgent`, `cliOf`/`agentId` draft keys, `savedEntry`, `canonical`/`isDirty`, `nameOf`, `modelNames`, `summaryRows`, `serverStateFor`, `cleanAgent` and `templateDraft` |
| `public/screens/agents/agents-list-editor.js` | the one row-list editor behind the three argument lists and the models list: `listEditor({list, kind, field, placeholder, addLabel, optionalName, aria, onChange})` draws `div.agent-rows` (a Remove per row, an Add that appends and focuses the new row, edits written into the live list) |
| `public/screens/agents/agents-summary.js` | the agents view's collection side: `renderSummary(ctx)` draws the left column for both modes (prefs rows with found badges, the shipped templates under "Or start from a template" and the orchestrator placeholder; setup pick rows, badges and templates), `drawSummaryPane(ctx)` draws the right pane while nothing is open (empty text, a picked template's note and Use this template, or the picked setup entry's state area: Start, Use it from here, install lines), plus `BADGES`/`drawBadge` |
| `public/screens/agents/agents-form.js` | the agents view's per-agent form: `drawForm(ctx)` draws the detail pane (the built-in's Models fold, or an added agent's identity fields plus folded Models and Command-line arguments sections), `renderDirty(ctx)` toggles the Unsaved badge and Save/Discard; the foot (Save, Discard, Save anyway on 409, Delete with inline confirm), `input.invalid[data-field]` marking and the `FORM_FOCUSABLE` focus save/restore |
| `public/screens/setup.js` | the agent-less setup screen (`workflow === "setup"`, opened by `plan2code` or the app when no agent can run): the "No agent yet" headline, Planny's setup pose, the agent list from `mountAgentsView` in setup mode, Check again, and the "Starting <Label>..." pane after a Start send (`{i:"__start"}` via `/submit`). `setupMoved(url)` disarms the 2-minute no-page notice once the `move` event lands |
| `public/screens/prefs-dialog.js` | User Preferences as a dialog: its four tabs (wired by `tabs.js` from `PREFS_TABS`), `openPrefs(tab)` (the one way in, loading Agents & models each time), the fading Saved mark beside a fieldset (`markSaved`), Back to default for the tab on screen, and `confirmUnsaved()`, the in-dialog Save / Discard / Keep editing prompt before Close, Esc, a backdrop click, a tab switch or picking another agent leaves an unsaved agent edit. Other screens reach it through `hooks` |
| `public/screens/starting.js` | the launching, starting and waiting screens, with Planny's poses |
| `public/screens/workspace.js` | the read-only Workspace of extra folders, and @mentions |
| `public/styles/ask.css` | The Ask pane and its Quick question chat |
@@ -380,7 +428,8 @@ Optional local browser UI shipped with **every** skill. Source lives in `src/web
| `public/styles/git.css` | The git board |
| `public/styles/help.css` | The help dialog, its diagrams and its tabs |
| `public/styles/looks.css` | The looks button and the highlight swatches |
| `public/styles/prefs.css` | User Preferences' side list of tabs, the strip below 720 px, the Saved mark, the Agents & models table (its Models column hidden below 720 px), badges and one-agent form (one column below 720 px), and the in-dialog unsaved prompt (new classes only: the Subagents dialog shares `.looks`) |
| `public/styles/prefs.css` | User Preferences' side list of tabs, the strip below 720 px, the Saved mark, the setup screen's own chrome, and the in-dialog unsaved prompt (new classes only: the Subagents dialog shares `.looks`) |
| `public/styles/agents.css` | the Agents & models view: the master-detail `.split` (list column, pickable `.split-row`s with `aria-current`, the `.split-pane`), badges, the form's fields, folds and foot, the models lists, the setup pane's state area, and the under-720 px single-column treatment |
| `public/styles/pieces.css` | Shared pieces: cards, options, settled answers, pager, forms, checklist, markdown and the modal |
| `public/styles/planny.css` | Planny the mascot: the flight, his moods and variants, and the wake-up |
| `public/styles/poses.css` | The start-screen poses, one per skill. After the dashboard on purpose: its narrow-window rules override the dashboard's |
@@ -428,7 +477,7 @@ Key design points:
- **First-run Welcome.** The first dashboard a person sees (after the wake-up finishes) opens `#welcome-modal`. Any close (button, Esc, backdrop) saves `looks.welcomeSeen: true` to `looks.json`, which survives "Back to default". Help's first tab has a **Show the welcome again** link (`data-action="welcome"`). Logic: `maybeWelcome()` / `openWelcome()` in `screens/help-dialog.js`.
- **Top-bar icons.** `#btn-looks` (gear) opens `#looks-modal`, titled User Preferences (see User Preferences below). `#btn-feedback` (megaphone) is a plain link to `https://github.com/jparkerweb/plan2code/issues/new/choose`, backed by `.github/ISSUE_TEMPLATE/bug.yml` and `idea.yml` (`config.yml` sets `blank_issues_enabled: false`). `DEFAULT_ACCENT` in `palette.js` is `ocean`.
- **Version in Help.** `GET /version` reads `version.json` beside `server.mjs`, falling back to `../../version.json` for a run from `src/` (the `/version` route in `routes.mjs`). `renderHelpVersion()` in `screens/help-dialog.js` fills `#help-version`. `computeExpectedSkills()` in `install.js` injects the root `version.json` into every `references/web-console/`, so a version bump changes every skill.
- **User Preferences is four tabs in a side list.** Appearance (Theme, Card width, Highlight color, Role), Agents & models, System (Cleanup, and Desktop app inside the app only) and Sounds & activities (Sounds, Activities), a sideways strip below 720 px. The tabs are the static `<section class="prefs-panel">` panels in `#looks-modal`, each fieldset in exactly one (its `data-section`, listed in `PREFS_TABS`), wired by the shared `public/tabs.js` (`wireTabs()`, the same helper Help uses: `helpKeyTarget()` re-exports its `tabKeyTarget()`). `public/prefs.js` is the pure part: `PREFS_TABS`, `prefsOpenTab()` (the gear and the dashboard's Set up preferences both open Appearance; nothing is remembered between opens) and `prefsResetScope()` (Back to default resets only the shown tab's looks keys, and is hidden on Agents & models and System). `screens/prefs-dialog.js` owns `openPrefs(tab)`, the one way in, the Saved mark and the unsaved prompt; `screens/looks.js` keeps the look and sound controls, which save to `looks.json` as they change; `screens/agents-view.js` is the Agents & models tab, a summary table over today's `models.json` and `agents.json` (formats unchanged) whose per-agent form has its own Save and Discard: Save sends the last saved list with only that form's draft swapped in, so another form's half-typed edit is never written.
- **User Preferences is four tabs in a side list.** Appearance (Theme, Card width, Highlight color, Role), Agents & models, System (Cleanup, and Desktop app inside the app only) and Sounds & activities (Sounds, Activities), a sideways strip below 720 px. The tabs are the static `<section class="prefs-panel">` panels in `#looks-modal`, each fieldset in exactly one (its `data-section`, listed in `PREFS_TABS`), wired by the shared `public/tabs.js` (`wireTabs()`, the same helper Help uses: `helpKeyTarget()` re-exports its `tabKeyTarget()`). `public/prefs.js` is the pure part: `PREFS_TABS`, `prefsOpenTab()` (the gear and the dashboard's Set up preferences both open Appearance; nothing is remembered between opens) and `prefsResetScope()` (Back to default resets only the shown tab's looks keys, and is hidden on Agents & models and System). `screens/prefs-dialog.js` owns `openPrefs(tab)`, the one way in, the Saved mark and the unsaved prompt; `screens/looks.js` keeps the look and sound controls, which save to `looks.json` as they change; `screens/agents-view.js` mounts the Agents & models tab, a master-detail split over today's `models.json` and `agents.json` (formats unchanged) whose per-agent form has its own Save and Discard: Save sends the last saved list with only that form's draft swapped in, so another form's half-typed edit is never written. The split's components live under `screens/agents/` (data, list editor, summary, form); the mount owns all state and every fetch and hands them one `ctx`.
- **Models in User Preferences.** `GET` / `POST /models` in `routes.mjs` read the shipped `~/.plan2code/bin/models.json` and read/write the user's `~/.plan2code/models.json` (`SHIPPED_MODELS_FILE` / `USER_MODELS_FILE` in `files.mjs`), edited from each built-in agent's form on the Agents & models tab. `PLAN2CODE_MODELS_DIR` relocates both for tests. The launcher reads the same two files for its model menu.
- **The wait is bounded.** `wait --seconds 240` exits `0` (answers), `10` (still waiting, `message: "Waiting on your answer in the web console"` to relay), `20` (server gone, resume it) or `30` (canceled). The agent loops. Nothing blocks for the whole time a person takes.
- **A turn is one command, and the CLI does the bookkeeping.** Agent speed is model round trips and typed tokens, not the console (`bench-web-console.mjs --roundtrip`: Send→agent ~70 ms, post→page ~180 ms), so the CLI absorbs every step with one right answer: `consume()` marks the agent `working` when it hands over a submit (`markWorking()`), and `wait` hands the turn back (`markWaiting()`) when it starts with an open question, a finish, or on the dashboard or git board; `post --wait <N>` posts and waits in one process; `settle: true | [ids]` (`settleItems()` in `patches.mjs`) records the latest send's cards as answered from their `submitted`; a new or reopened question with no stated status sets `waiting` and waiting drops `quietMinutes` (`settleAgent()`); a doc whose content changed with no `version` moves up one (`mergeDocs()`); a chat reply with no `id` is `r<re>`; doc blocks with `file` (and `select: "tasks"`, doc-level `refresh: true`) are read from the worktree by `resolveDocFiles()` before the merge, refusing paths outside it; and a hop (`__launch`, `__dashboard`, `__commit`, `__pickup`) comes with `resume` (the exact `open --resume` command) and `skillFile` (`hopFor()`), a pick-up also with `handoffFile`. The wait loop's health check runs beside the 50 ms polling instead of blocking it, and is aborted on exit. `help <topic>` prints any contract file; `help topics` lists them. `token` defaults to the option key in the page's `tokenFor()`, and nothing reads `fallbackText`, so the contract no longer asks for either.
@@ -521,7 +570,7 @@ src/statusline-claude/
## Global `plan2code` Command
Typing `plan2code` in any directory opens the dashboard skill against the current project, **in that directory**, in one of three CLIs (the `CLIS` table in the launcher):
Typing `plan2code` in any directory opens the dashboard skill against the current project, **in that directory**, in one of the built-in CLIs (the shipped `src/launcher/agents.json`, plus any custom entries in `~/.plan2code/agents.json`):
| CLI | Runs |
| --- | --- |
@@ -531,13 +580,14 @@ Typing `plan2code` in any directory opens the dashboard skill against the curren
The bracketed flags (each entry's `bypassArgs`; a custom agent's own `bypassArgs`) go in only when permission prompts are off. Right after the agent is chosen, and only when it has such a flag, `chooseBypass()` asks `Turn <CLI>'s permission prompts off?` with Yes as the default; `--keep-permissions` (never forwarded) answers no, and with no TTY on stdin the prompts are off, as before. When the desktop app will take over, the question is skipped (its launch card has its own tick) and asked only if the app fails to start. The installer prints no warning about it.
On a terminal it first prints a Planny banner (`renderBanner()`). With more than one on `PATH` it asks `Plan2Code opens inside an AI coding agent. Pick which one to use:` as a numbered menu, the last pick pre-selected and marked `(last used)` (Enter keeps it; a number or a CLI id also works); with one installed it uses that without asking, printing `Opening with <CLI>…` (as does a `--cli` pick); with none it exits 127 and prints `SKILL_STEPS`: how to install an agent, `cd` into the project, and type `/plan2code` (`$plan2code` in Codex). An uninstalled `--cli` pick prints that CLI's own steps after its error (its install command, `cd` into the project, then `plan2code --cli <id>` or its prompt). `--cli claude` / `devin` / `codex` (or `--cli=<name>`) skips the menu and is never forwarded; an unknown name exits 2, an uninstalled one 127. The pick is saved as `lastCli` in `~/.plan2code/launcher.json`, merged beside `lastFolder`. Before spawning, unless the forwarded args carry `--model` / `--model=` (or, for Codex, `-m`), it asks `Which model should <CLI> use?` from `models.json` plus the user's additions, Enter keeping the model the CLI last used — Ctrl+C at any launcher prompt exits 130. With no TTY on stdin there is no menu (last pick, else the first installed) and no model question: it prints that the CLI will use the model last used in it (switch it in that CLI on its own, or pass `--model <name>`). Headings, numbers, defaults, retry lines and the `plan2code:` error prefixes are colored with `paint()` (the escape values of `install.js`'s `COLORS`, copied), stdout only when stdout is a TTY and stderr only when stderr is, and never when `NO_COLOR` is set; piped runs print plain text and no banner. Other arguments are forwarded to the CLI (`plan2code --model opus`), and its exit code is passed back. `plan2code update` is the one subcommand: it is never forwarded and opens no agent, it runs `npx --yes --allow-git=all git+https://github.com/jparkerweb/plan2code.git --update`, so `install.js --update` reinstalls what `~/.plan2code/install.json` lists. On every other start, before spawning the CLI, it prints one line when a newer release is out (`Plan2Code v<latest> is out (you have v<installed>). Run: plan2code update`), compared against `~/.plan2code/bin/version.json` and read from the console's cached release check (`~/.plan2code/console/update-check.json`); it never waits on the network, and when the cache is missing or stale it refreshes it in a detached background process so the next start knows. Tests: `scripts/test-launcher.mjs` (run by `npm test`) spawns the launcher against stand-in `claude`/`devin`/`codex` commands and a temp home.
On a terminal it first prints a Planny banner (`renderBanner()`). With more than one on `PATH` it asks `Plan2Code opens inside an AI coding agent. Pick which one to use:` as a numbered menu, the last pick pre-selected and marked `(last used)` (Enter keeps it; a number or a CLI id also works); with one installed it uses that without asking, printing `Opening with <CLI>…` (as does a `--cli` pick); with none it runs the setup flow when a person can see a page (`hasDisplay()` and a TTY or the shortcut; the desktop app first when it is installed, else the console's agent-less `setup` page in the browser) and otherwise prints the install steps (`printNoAgentGuidance()`: each built-in's install command and page, how to add another agent in `~/.plan2code/agents.json`, and to run `plan2code` again) and exits 127. An uninstalled `--cli` pick goes to the same setup flow on that agent when a page can open, else prints that CLI's own steps after its error. `--cli claude` / `devin` / `codex` (or `--cli=<name>`) skips the menu and is never forwarded; an unknown name exits 2, an uninstalled one 127. The pick is saved as `lastCli` in `~/.plan2code/launcher.json`, merged beside `lastFolder`. Before spawning, unless the forwarded args carry `--model` / `--model=` (or, for Codex, `-m`), it asks `Which model should <CLI> use?` from `models.json` plus the user's additions, Enter keeping the model the CLI last used — Ctrl+C at any launcher prompt exits 130. With no TTY on stdin there is no menu (last pick, else the first installed) and no model question: it prints that the CLI will use the model last used in it (switch it in that CLI on its own, or pass `--model <name>`). Headings, numbers, defaults, retry lines and the `plan2code:` error prefixes are colored with `paint()` (the escape values of `install.js`'s `COLORS`, copied), stdout only when stdout is a TTY and stderr only when stderr is, and never when `NO_COLOR` is set; piped runs print plain text and no banner. Other arguments are forwarded to the CLI (`plan2code --model opus`), and its exit code is passed back. `plan2code update` is the one subcommand: it is never forwarded and opens no agent, it runs `npx --yes --allow-git=all git+https://github.com/jparkerweb/plan2code.git --update`, so `install.js --update` reinstalls what `~/.plan2code/install.json` lists. On every other start, before spawning the CLI, it prints one line when a newer release is out (`Plan2Code v<latest> is out (you have v<installed>). Run: plan2code update`), compared against `~/.plan2code/bin/version.json` and read from the console's cached release check (`~/.plan2code/console/update-check.json`); it never waits on the network, and when the cache is missing or stale it refreshes it in a detached background process so the next start knows. Tests: `scripts/test-launcher.mjs` (run by `npm test`) spawns the launcher against stand-in `claude`/`devin`/`codex` commands and a temp home.
**Design constraints:**
- **Stable copy, not the package dir** — the installer normally runs from an npx cache directory npm may delete, so `installLauncher()` copies `src/launcher/plan2code.js` to `~/.plan2code/bin/plan2code.js` and the shims point there. Beside it go `update-check.mjs` (the web console's release check, for the terminal notice) and a `version.json` (the installed version). (The metrics/bot wrappers point into `__dirname` and don't have this protection.)
- **Stable copy, not the package dir** — the installer normally runs from an npx cache directory npm may delete, so `installLauncher()` copies `src/launcher/plan2code.js` to `~/.plan2code/bin/plan2code.js` and the shims point there. Beside it go `update-check.mjs` (the web console's release check, for the terminal notice), `agents.json` and `agent-lookup.mjs` (the shared agent list and lookup rule; `plan2code update` restores a missing copy) and a `version.json` (the installed version). (The metrics/bot wrappers point into `__dirname` and don't have this protection.)
- **The setup flow and hand-over.** With no runnable agent, `runSetupFlow()` finds `console.mjs` (the order the app's `find_console_dir` uses) and runs `open --workflow setup [--for-cli <id>]` as a child process, then `wait` in 240-second slices (the agent-less console keeps its app variables out, NFR-2). An `__start` action ends the wait with the pick; the launcher spawns that agent with `PLAN2CODE_SETUP_ANNOUNCE` (the setup server's base URL) and `PLAN2CODE_SETUP_TOKEN`, and the new agent's `open` POSTs its sign-in URL to `POST /handover` on the setup server, which broadcasts a `move` event the waiting tab follows. The post failing or the wait ending unmoved falls back to opening a browser / the printed steps.
- **npm-style shims** — written into npm's global bin (`npm config get prefix`; `<prefix>/bin` off Windows): an sh shim everywhere, plus `.cmd` and `.ps1` on Windows, so cmd.exe, PowerShell and Git Bash all resolve it. On macOS/Linux, when the npm bin isn't writable (system Node), it falls back to `~/.local/bin`.
- **Marker-based ownership** — every shim contains `plan2code-launcher`; `uninstallLauncher()` removes only files carrying it, leaving any other `plan2code` bin alone.
- **Resolving the CLI** — the launcher walks `PATH` (+ `PATHEXT` on Windows) itself. An `.exe` is spawned directly; a `.cmd`/`.bat` wrapper goes through `cmd.exe /d /s /c` with quoted args, since Node refuses to spawn batch files without a shell. The installer warns only when neither `claude` nor `devin` is on `PATH`.
- **Resolving the CLI** — `findAgent()` in the shared `agent-lookup.mjs` does the lookup: `PATH` (+ `PATHEXT` on Windows), the saved Windows PATH from the registry (`addSavedWindowsPath()`), npm's global bin and each entry's `installDirs`, giving `found` / `outside` / `missing` (the desktop app's `find_on_path` in `agents.rs` is its twin, held to `scripts/fixtures/agent-lookup-cases.json`). An `.exe` is spawned directly; a `.cmd`/`.bat` wrapper goes through `cmd.exe /d /s /c` with quoted args, since Node refuses to spawn batch files without a shell. The installer warns only when neither `claude` nor `devin` is on `PATH`.
- **No bin-name overlap** — the installer's own bin in `package.json` is `plan2code-install` (→ `install.js`), so `plan2code` belongs to the launcher alone. npx runs a package's only bin whatever it's named, so the README's `npx … plan2code.git` command is unaffected; keep it the only bin, or npx will need `-c plan2code-install`.
- **`--pick-folder` is shortcut-only** — the launcher strips it before building the CLI's args. The shortcut runs the CLI menu, then the folder picker, then the model menu. With it, a native folder picker chooses the cwd instead: on Windows, the Explorer-style `IFileOpenDialog` (`FOS_PICKFOLDERS`) via `powershell -STA -EncodedCommand`, its C# interop (`WINDOWS_PICKER_SOURCE`) passed in an env var and compiled with `Add-Type` (~0.5s), with a TopMost owner form so it doesn't open behind the console — Windows PowerShell's `FolderBrowserDialog` is the old tree-only dialog, and is kept only as the fallback when `Add-Type` is blocked (Constrained Language Mode, AppLocker); `osascript choose folder` on macOS, and `zenity` then `kdialog` on Linux (only when `DISPLAY`/`WAYLAND_DISPLAY` is set). If there's no picker, or the picker fails, it falls back to a typed `Project folder [last]:` prompt. A picker that exits 0/1 with nothing printed means the person canceled, so the launcher exits 0. The picker starts on the last pick, stored in `~/.plan2code/launcher.json`. From the shortcut, a non-zero exit other than Ctrl+C (130 / `0xC000013A`) waits for Enter so the error doesn't vanish with the window. Typed in a terminal, `plan2code` behaves exactly as before.