Files
orca/config/scripts
Jinwoo-H 3db9459d14 refactor(mobile): thread the document scope and bundle the page's script
Ruling 25. The terminal document stops being a string the build machinery assembles
and becomes ordinary TypeScript: every module function that reads document state takes
`scope: TerminalDocumentScope` as its first parameter, `document-scope.ts` exports the
types and `createTerminalDocumentScope(host)` and nothing else, and `tsc` is the oracle
that the threading is whole (a missed parameter is a type error).

`create-terminal-document.ts` is hand-written, not emitted: it builds the scope, runs the
eleven starts inside a try that unwinds on a throw, stops the ten in reverse with
`cancelDocumentFrames` last, and returns `{ send, stop }`. `native-document-entry.ts` is
one statement. The concatenator becomes an esbuild IIFE bundle of that entry at the
Chrome 74 floor, written as a string the same way the engine artifact is.

The byte pin cannot survive that and does not try to: esbuild merges module scopes and
renames the threaded parameter (`scope` -> `scope2` where two modules collide), so the
document's text is no longer a stable artifact and the behavioural suites are the proof.
`native-document-bundle.test.ts` evaluates the real bundle and reads three behaviours the
phone depends on: it announces `web-ready`, an init message opens the engine inside
`#terminal-surface`, a ping is answered, and a missing engine global reports fatally
instead of starting.

Rewritten tests, old oracle -> new oracle:

- host-seams, write-queue, document-frame-registry, document-parse-time-effects:
  evaluated a region of the generated text -> import the module and pass a scope the case
  builds.
- terminal-webview-engine (WebGL recovery), terminal-webview-theme,
  terminal-webview-text-zoom, terminal-webview-query-reply,
  terminal-keyboard-avoidance-webview: a `vm` evaluation with injected globals -> the
  imported functions over a scope whose seams are the case's own doubles.
- terminal-webview-url-tap: a function extracted out of the document's text and evaluated
  -> the document's `osc-link-tap` exports imported directly.
- terminal-webview-reflow, terminal-webview-scroll-routing, terminal-path-tap,
  terminal-webview-tap-routing, terminal-webview-wheel-scroll: assertions over the
  assembled document text -> the same assertions over the module's own source, read
  through `document-module-source.test-support.ts` (TypeScript, so no semicolons).
- document-host-root, document-start-unwind: imported the generated factory -> import
  `create-terminal-document`.
- terminal-webview-consumer-census: the generated factory was a census exception -> it no
  longer exists.
- config/scripts closure tests: re-measured for the bundled document.

Deleted with the machinery they served: the concatenator's emit/substitute/order code,
`terminal-document-module-order.mjs`, the document fixture builder,
`generated-document-region.test-support.ts`, the byte golden and its identity test, the
payload-hash pin, `document-factory-emit`, `document-factory-artifacts`,
`document-module-order`, and the generated factory artifact with its gitignore and
lint-ignore lines.

Two assertions the tests no longer need: the published contrast floor arrives unvalidated
from a host of unknown version, so `TerminalDocumentThemeMessage` types it the way the
router types its other wire fields and `normalizeTerminalContrastOverride` remains what
decides it is a number; the recovery harness holds its timer callback in a wrapper rather
than asserting a narrowing.

Claude-Session: https://claude.ai/code/session_01JNnE9qzUZMMnqpZWCqM3nb
2026-09-20 21:31:16 -04:00
..
2026-05-15 05:44:25 -04:00