# 🤖 Breaking shell.js into modules — the ladder and the shellstate seam

shell.js (the chat page host) started 2026-07-14 at ~12,000 lines. It is being
split into plain ES modules — no build step, verbatim moves, one PR per slice,
each verified on a pinned canary before the next. This doc records the method
and the one real design decision (the state seam), so any session can continue
the ladder without re-deriving it.

## Done

- **Dead code first** (never move what you can delete): the legacy typing
  pipeline (#911), the feed-cache cluster + `#feed` div (#919), the hidden
  legacy composer + its staging chain (#931). The "retired original chat"
  CLAUDE.md used to fence off is now fully gone.
- **Leaf extractions** (sections with little/no shared state):
  `theme.js` (#913), `lightbox.js` (#928 — deduplicated the byte-identical
  copy chat.js carried), `media.js` (#933).

## The shellstate seam

Seven mutable bindings are read all over the shell (~700 references):
`session`, `threads`, `threadKeys`, `activeId`, `ws`, `roster`, `myUserId`.
They are why the remaining sections can't just move: an ES-module import can
*read* a live binding but never assign it.

Measured (2026-07-14): only **~14 sites assign a whole binding**; everything
else reads it or mutates properties (`threadKeys[id] = k`), both of which work
unchanged through an imported live binding.

So the seam is `web/static/shellstate.js`:

- It **owns** the seven bindings: `export let activeId = null;` etc.
- Whole-binding writes go through exported setters (`setActiveId(v)`,
  `setThreads(v)`, …) — one setter per binding, assignment-only, no logic.
- Every reader — shell.js and each extracted module — imports the bindings
  **under their existing names**; the ~700 reads don't change. Property
  mutations on the imported objects/maps stay as they are.
- Nothing else lives in shellstate.js. It is a place for shared *state*, not
  shared *behaviour*; helpers keep moving into their own modules.

## The verbs seam

The state seam unblocked modules that *read*; the remaining clusters also
*act* — they open threads, reload the list, raise modals. Those verbs can't be
imported from shell.js (it's the entry module; importing it back is a cycle),
and injecting them per-module scales into hook soup.

So the same trick again: `web/static/shellverbs.js` exports one empty
registry object, and shell.js populates it in a single `Object.assign` at
boot. Modules call `verbs.openThread(id)`. Registration only — no logic in
the seam, nothing imported by it, no cycles. When a verb's implementation
later moves into its own module, the registry entry moves with it and no
caller churns. (searchui.js's `wireSearch` predates this seam and stays as
is.)

## Rules for a slice

1. Verbatim move — refactor in a separate PR from relocation, never both.
2. `node --check` every touched file; `npm test`; `go build` (go:embed).
3. One PR per slice, squash-merged, then deployed to the pinned session
   canary and exercised before the next slice starts.
4. Live tenants get traced, not assumed: a "dead" section can house live
   functions (`openMentionMenu`, `typeaheadItems`) and vice versa.
5. CLAUDE.md's frontend module list gains one line per new module.

## Outcome (2026-07-15)

The ladder completed over two overnight runs: 13 modules out of shell.js
(12,057 → ~7,650 lines), the state seam (`shellstate.js`) and the behaviour
seam (`shellverbs.js`, ~43 registered verbs) both in place, every slice
deployed to a pinned canary and verified before the next.

Two lessons paid for in bug reports, now structural:

- **A verbatim slice's failure mode is the dropped identifier** — reads that
  worked in the old module throw `ReferenceError` in the new one, at runtime
  only, on paths tests don't walk. Call-site audits are not enough: bare
  *references* (`if (embed)`, `sealedBranding.name`) crash the same way.
  `test/module-refs.test.mjs` now scans every extracted module for unresolved
  identifiers and runs in `npm test`. **Write that checker before the first
  slice of any future effort like this.**
- **The boot smoke** (`tools/boot-smoke.mjs`) walks sign-in → boot → send →
  search → picker headlessly and fails on any page error; each escape became
  a new step. Run it against a `--clean` dev server for anything touching the
  shell's boot or module graph.

## Remaining ladder

All done (see Outcome). What deliberately stays in shell.js: boot, keys,
data loading, the WebSocket dispatch, and the render plumbing the verbs
registry fronts. Possible future work, none owed: verb implementations
gaining module homes (the registry entry moves with them), and searchui's
pre-seam `wireSearch` migrating to `verbs.*`.