improvise/context/code/clients.md

Clients: the browser client, the two hosts, and the harness

The arguments that used to live in the comment headers of improvise-wasm-client, improvise-ws-server, improvise-worker-server, web/ and harness/. Written for a reader with the code open. Bug narratives keyed by test name are in context/test-evidence/clients.md.

Repo-map gotchas 42, 44, 45, 46, 47 and 48 cover the same ground from the "where" side; this file is the "why", at the density the comments had.

---

improvise-worker-server/src/worker.rs — the message loop

Worker is the whole browser host minus the two things a browser has to supply — self.onmessage/self.postMessage, and OPFS. Both are in crate::bindings, which is cfg(target_arch = "wasm32") and has no decisions in it. Everything that could be wrong about what the main thread is told is in worker.rs, where cargo test can drive it.

It is the socket's Host, not a second one

Host is App + Sessions + handle(id, ClientFrame) -> Vec<Addressed>. Nothing in it is a socket, and improvise-9x6 is what made that load-bearing rather than tidy: the worker needs the same session loop and cannot depend on improvise-ws-server, which is tokio and tungstenite. So Host moved down to improvise_command::ui::host and both deployments name the one type. Re-implementing it here would have been a mirror, and improvise-xks6 had just finished deleting the last one: a second copy of a decision layer drifts, and the drift is invisible until a client sees it.

What the worker adds on top is only what a MessagePort differs in:

• One client, by construction. A MessagePort is point to point, so the SessionId is not an address the transport has to carry — it is a field. Addressed is still honoured rather than assumed away (Worker::frames_for), because a SharedWorker would make it matter again and the honest filter costs one line. Host::relay addresses a broadcast to every session it knows, and with one session that is always this one — a loop that assumed it away would be silently wrong at that point rather than obviously incomplete.
• A handshake with no close. ClientFrame::Viewport must come first, for the reason it must on the socket: a Snapshot seeds the visible cells, so one built at extent zero is an empty grid. A socket enforces that by closing the connection; a worker has nothing to close, so a frame that arrives before the handshake is dropped, which is the same outcome without a mechanism that does not exist here.

ClientFrame::Key is answered with nothing, and that is not laziness

A worker holds the authoritative App, so ui::reduce::reduce_key really is callable here where it is not on a socket. Calling it would still be wrong, and the reason is not about transports at all: nothing in the projection stream carries the host's own ViewState. A client's view slice moves only by folding Commands, and a keypress resolved against the App moves the App's slice — its mode, its cursor, its minibuffer — with no Command produced that any client could fold. ClientSession::project emits document projections, a grid diff and a basis; none of the three is a mode change.

So a half-wired Key arm does not under-deliver, it diverges: the host would believe it is in AppMode::Editing while the client draws Normal, and ClientSession::viewport() reads the mirror's cursor, so the grid would not even scroll to follow.

improvise-bpq2 answered it, and not by deriving Commands from a ViewState delta. The user's ruling is that a keymap is UI and the server must not know it, so resolution moves to the client: a key the client can answer arrives here already resolved, as a ClientFrame::Commands batch it has folded itself, and this arm's emptiness stops being a gap and becomes the statement. What remains upstream is the set of bindings a client still cannot compose — prefix keys, anything naming a row's category or a group, anything touching Storage — and those are closed by enriching the projection, one at a time, not by wiring this arm up. The list lives in keys.rs (see below).

Persistence is the worker's, whether or not anybody asks

There is no ModelCommand::Save, and that is not an oversight: effect::Save is EffectKind::ViewOnly (it writes the document to this host's file path and clears this host's dirty flag; it mutates no document state), so the derivation that produces ModelCommand from the model effects cannot reach it (decision(improvise-cqi, command_set_derived_not_invented)). Saving was therefore unreachable from any client on any transport until improvise-368h added ClientFrame::Save — a request to the host, framed rather than commanded precisely because it mutates nothing shared.

A browser still never sends it, and that is the right answer rather than a gap: there is no file the user owns and no Ctrl-S semantics to honour, so asking would be the wrong question — the document is the OPFS entry, and a page that loses an edit because nobody pressed a key has simply lost it. So the worker persists on its own behalf: Worker::persist runs the one existing Save effect through App::apply_effects, so effects remain the only mutation site and the save path is not duplicated. A worker with no file_path silently does nothing, which is what Save already does; a failed save leaves its message in the status and aborts the batch.

The trigger is an observation of the document, not a table of command variants. It used to be the latter, and the reason was honest: a wire ModelCommand::SetCell reached effect::SetCell, which did not raise model_state.dirty — that was a separate MarkDirty effect only the key path composed — so "save if dirty" was a trigger that never fired (improvise-gv9r). With dirtiness raised by App::apply_effects off the same EffectKind the Dirty is, the flag is the observation, and asking it is better than enumerating variants for the same reason the cursor reset watches cursor_epoch rather than matching on CycleAxis, and the rebase watches document_generation rather than matching on LoadModel: a table of variants is a second description of which commands change the document, free to disagree with the first. It is also strictly tighter — a refused batch changes nothing, so it raises nothing, and the "was anything rejected" special case that used to guard this went with it.

One cost remains and is stated rather than hidden: Storage is whole-document by construction, so OPFS rewrites the file per accepted model command — correct, not yet cheap. And a failed write leaves the flag raised, so the next frame retries: right for a transient failure, and harmless for a permanent one (a worker with no file_path) because the only thing a failed Save produces is a status line, and nothing in a worker renders one.

The one frame on_frame does not auto-persist after is ClientFrame::Save: a client that asked to save has already been answered, and a failed write leaves dirty set — so retrying would repeat the I/O and, on a transient failure, tell the client SaveFailed about a document that is now on disk. The automatic write exists for edits nobody asked to save.

So this is the browser's own answer, and ClientFrame::Save is the other one — for a socket client editing a TUI-hosted document, where there is a file somebody owns.

Ordering

Worker::on_frame returns the frames for one inbound frame, in order, and a ServerFrame::Commands batch must reach the client whole and in sequence: a GridUpdate::Cells that overtakes the labels framing it is dropped, not replayed. That is a property of the fold, so a postMessage transport owes it exactly as a socket does — never coalesce two batches, never split one.

Malformed frames are loud

Worker::on_message returns Err on a frame that will not parse rather than swallowing it. A worker that silently ignores a malformed frame leaves the client waiting forever for an answer that is never coming.

Worker is not Debug, for the reason Host is not: it owns the whole document.

---

improvise-ws-server — the socket host

Three layers, and the split is the point — the frames are a fourth thing this crate speaks but does not own:

• the frames are not here. ClientFrame/ServerFrame are improvise-protocol's, because the same envelopes frame the worker deployment and a browser bundle cannot depend on this crate (improvise-xks6). This crate speaks them and owns none of them.
• host — the session loop: one authoritative App, one Sessions, and a handle(id, msg) -> Vec<Addressed> that is where every decision is made and every test is pointed. Not here either, and for the same reason the frames are not: the browser worker hosts the same loop over a MessagePort and cannot depend on tokio. src/host.rs is a re-export of improvise_command::ui::host, kept rather than deleted so improvise_ws_server::host::Host still resolves. Host knowing nothing about sockets was always true — the file used to say "a websocket is awkward to test, so nothing that decides anything lives in one" — and improvise-9x6 made it load-bearing. A second copy is a mirror, and a mirror drifts; that is the same answer improvise-xks6 gave for the frames one ticket earlier.
• registry — the documents: a map of Hosts keyed by document id, the lifecycle rules, and the one place a per-document SessionId becomes a server-wide address. Socket-free. It stayed on the server because a worker hosts exactly one document.
• transport — tokio and tungstenite: framing, JSON, the handshake rule, and reading the requested document off the URL path. No decisions about what a client is told.

Native-only: tokio's networking does not build for wasm32-unknown-unknown, and it should not.

The registry's grain

Sessions editing independent documents are trivially non-conflicting, which is why ADR 001's basis tiers — document_generation, layout_version, record_versions — live on the App and scope per document for free. A registry that let two documents share any of that would throw the free scoping away, so the registry owns no state of its own beyond the map: there is nothing here for two documents to share.

A SessionId is not unique server-wide. Sessions mints ids from a counter it owns, so every document's first client is SessionId(0). The server-wide address is therefore the pair, ClientId, and Registry::route is the one place a Host's SessionId acquires the document it came out of. That is the whole cross-document isolation argument, and it is structural rather than checked: a Host can only name its own sessions, and the only tag route can apply is the document whose Host produced the frames. In particular an Applied::Rebased fans a fresh Snapshot out to every client of that document and cannot reach further, because the ids it returns are meaningless anywhere else.

Lifecycle

Open happens at startup, from the documents the host names. A client cannot ask the server to open a path it was not told about, and that is not an oversight: deciding which paths a client may open is access control, which improvise-j31x puts explicitly out of scope. Serving only what was named leaves the question unanswered rather than answering it badly. A stem collision is fatal rather than resolved: two files with the same stem are two documents a client could not tell apart, and silently serving one is worse than saying so.

Close does not happen when the last session leaves. A document stays resident for the life of the server. Evicting it was considered and rejected twice over:

• Unsaved edits would vanish. The server has no autosave obligation, so a reconnect would silently roll the document back to what is on disk.
• It would rewind the basis tiers. document_generation and record_versions start at zero in a fresh App, so a client that reconnected holding a stale basis would have it accepted as current — a correctness hole in the exact mechanism ADR 001 is building, paid for with a memory saving nobody asked for.

An idle document therefore costs its App, and Registry::is_idle exists so a future eviction policy has somewhere to ask the question from — nothing calls it to evict, because nothing evicts.

The transport's two rules

A client names its document in the URL (improvise-j31x): ws://host:port/quarterly asks for quarterly, and ws://host:port/ asks for whichever one there is when there is exactly one. The path was chosen over a new ClientFrame variant for two reasons: a document is a resource, which is what a URL path is for, and ClientFrame stays exactly as it was, so every client written against the single-document server keeps working unchanged. Which document a name resolves to is Registry::resolve's decision, not the transport's; all that happens there is path -> Option<&str>. It is not a path walker — everything after the leading slashes is the name.

The other rule is that the first frame of a connection reports the extent, because the bootstrap Snapshot cannot be built without it.

A refused connection is closed with a websocket close frame carrying the reason. No ServerFrame::Error was added: the frame vocabulary is derived from the mutations that need it, and "this connection is not happening" is a fact about the connection, which the protocol already has a frame for.

A Registry is not Send (a Host's App owns a Box<dyn Storage>), and must not be shared anyway: it holds the authoritative documents, and one owner is the point. So it sits in a single task on a LocalSet and every connection talks to it over a channel. That is also what serializes the clients — commands arrive in one order, and the projections each client gets are produced in that order, which matters because a GridUpdate::Cells that overtakes its labels is dropped. One task for the whole registry rather than one per document is a throughput choice and nothing more: the runtime is single-threaded either way, and no state is shared between documents by sharing a queue.

No auth, no TLS, localhost only. A deliberate MVP limit (improvise-q08), not an oversight: anyone who can open a socket to this port can rewrite every document it serves, so it binds a loopback address by default and serve says so. --bind exists so the limit is a choice you can see rather than one buried in the code. ADR 001 owns what multi-writer safety becomes.

Origin

src/origin.rs is the handshake's one access control, and the reason it cannot be delegated: a websocket handshake is exempt from the same-origin policy. There is no CORS preflight, so any page a user visits can open a socket to the endpoint from that user's own address, and read and edit every document the server holds — cross-site websocket hijacking (improvise-kc7n). An address check cannot see it, because the request genuinely comes from an allowed address; an IP allow-list, a private network and loopback binding all answer "may this client reach the endpoint", and the attacker's answer is honestly yes. Only Origin says what is driving the client, which is doctrine(who_may_connect_is_two_questions). Loopback is the least protected case, not the safest: there is no proxy in front of it to check anything, and loopback is not a boundary a browser enforces, so while the server runs any page open in that browser can reach ws://127.0.0.1:8787.

The default allows loopback pages and nothing else, because a default that fails open is worth nothing and a default that breaks the shipped recipe is a different bug. The two shipped paths were the constraint. The local pairing recipe serves the page with python3 -m http.server 8080 --directory web, so its origin is http://localhost:8080 while the socket is on another loopback port — loopback is therefore the default, not a flag, or the one case worth optimising for would need configuring. The deployed Pages page sends https://fiddlerwoaroof.github.io and can only reach the server through a TLS proxy (improvise-ws-server speaks plain ws://), which is already a multi-step setup with an Origin allow-list in it; one --allow-origin is therefore an honest cost there and the project's own deployment origin is not hard-coded as a default. OriginPolicy::permits is the whole decision, and the transport's admitted is the only caller.

An absent Origin is allowed, decided rather than defaulted. Every browser sends one on a handshake, unconditionally — unlike fetch, there is no no-Origin mode to fall into — so an absent one is a non-browser client: curl, a native client, this crate's own tests/socket.rs. Refusing those would break the repo's own tests and every scripted client while buying nothing, since an attacker who can run a non-browser client already has direct network access, which is the question --bind and a proxy answer. The cost is stated rather than hidden: a proxy that strips Origin turns this check off, so the proxy's own Origin allow-list stays in the recipe as defence in depth.

Two shapes state no origin a policy can answer for, and both are refused rather than read as absent: an Origin that is not valid text, and two Origin headers. HeaderMap::get is first-wins, and the deployment this README recommends puts a proxy in front of the socket — one that appends rather than sets the header leaves two, and answering from the first lets the second be anything at all. No browser sends two.

What this does not buy is authentication. It answers "what page is driving this client", never "who is connecting"; anything that is not a browser page sends no Origin and is unaffected by any of it. improvise-kpnr is still open and is a different question.

---

improvise-protocol/src/resolve.rs — one keypress → Commands

It is not the browser's module any more (improvise-0yq8)

resolve/step and ClientState were improvise-wasm-client's, and nothing about either was a browser fact: both depend on ViewState, the protocol widget caches and the announced window, every one of which is already a protocol type. Being in the wasm crate meant a second front end could reach them only by depending on a cdylib built for a browser, so the move cost no new dependency and bought the rule design-principles §5 states — a new front end needs exactly two things: its own event → KeyEvent mapping, and painting. BrowserKey is the first of those two and is the only thing left in improvise-wasm-client/src/keys.rs; ClientState is now improvise_protocol::client, and typed_cell_command went with step, which calls it.

What did not become trivial is tests/lockstep.rs. It drives improvise_command::ui::reduce::reduce_key — the host's Cmd/Effect path — against resolve, and those are still two derivations of the same answer, in two crates, one of which cannot be reached from a browser. Moving resolve changed which crate it is spelled in, not that it is a mirror, so doctrine(a_consolidation_that_keeps_its_compatibility_test_is_unfinished) does not fire and the test stays.

The keymap is not this module's

It used to be. improvise-bpq2 gave this file a hand-written classifier that decided, per key and per mode, what a keypress meant — a second spelling of default_keymaps(), kept in step by a lockstep test over a hand-written list. The user's ruling is that the web front end uses the same keymap as the TUI, not a mirror of it, and doctrine(a_consolidation_that_keeps_its_compatibility_test_is_unfinished) says why: two definitions held honest by a compatibility test are one definition waiting to be made.

So the table moved to improvise_protocol::keymap and this module reads it. Which key means what is now correct by construction: a rebinding in default_keymaps() reaches the browser with no change here, and a new binding for a command this module can already execute simply works.

What is left here, and why it is the better boundary

A lookup yields a command name and arguments. Turning that into something that runs needs a CmdContext — a Model, a GridLayout, an App — which this client does not have. So key → intent is shared and intent → Command is ours, for the subset we can compose. step is that subset, and it is the list that replaces the old list of keys. That is a list of names rather than of keys, which is strictly better in two ways: it is enumerable, and it does not go stale when a binding moves.

What this client can execute, and what each one needed:

• Text entry (append-char, pop-char, clear-buffer). The buffer is the binding's own argument now — no longer read off AppMode::minibuffer() and hoped to agree with what the host's keymap named. TextEntry::new derives one from the other, so the two were equal; they are now the same string. The pair read_buffer/write_buffer mirrors cmd::core's, which are the only code on the host that knows a runtime-named buffer may not be an entry in buffers at all (improvise-gdl): the name "search" is ViewState::search_query. The shared keymap binds append-char ["search"] in SearchMode, so this client needs the same pair — and having it is what lets search typing resolve here for the first time.
• Mode entry (enter-mode), decoded through AppMode::from_name, which moved next to AppMode for the same reason the keymap did.
• Grid, panel and tile cursors, which needed GridExtent and the window this client announced.
• Entering an edit (edit-or-drill), which needed ADR 002: the branch EditOrDrill takes on "is this cell aggregated" is exactly the CellId variant the server already projects.
• Committing one (commit-cell-edit, commit-and-advance-right), which needed the record surrogate — again ADR 002 — and nothing else for the plain-grid case.

The second tranche, and the three it could not reach (improvise-e24v)

Fifteen more command names resolve here: cycle-panel-focus; the category panel's cycle-axis-at-cursor, open-item-add-at-cursor, filter-to-item, toggle-cat-expand and delete-category-at-cursor; the view panel's switch-view-at-cursor, create-and-switch-view and delete-view-at-cursor; tile select's set-axis-for-tile and cycle-axis-for-tile; the help overlay's help-page-next/help-page-prev; commit-buffer in all three of its kinds; and the two cell writes clear-cell and paste.

Each is Cmd-for-Cmd, including the parts that look like noise: the status sentence a command writes beside its mutation is part of the answer, and a client that emitted the mutation alone would diverge on the status line and nowhere else — which is precisely the sort of divergence nobody notices. Two orderings are load-bearing and copied rather than rationalised. CommitBuffer writes its optimistic status first so the add's own failure message wins (improvise-6t3), and TileAxisOp writes the axis first and the status after.

Three of the tranche's own list turned out to need enrichment after all (improvise-4bwa), and the reasons are worth more than the code:

• toggle-prune-empty words its status off View::prune_empty, which is in the Workbook, in no cache, and not in ViewState.
• delete-formula-at-cursor needs (target, target_category); FormulaCache carries the formula's raw text, and recovering the two from it means reimplementing parse_formula on the client.
• view-back was listed here too, and improvise-cfly removed it: once PR #115 put Command::ViewBack in the view half there was nothing left to enrich. See "The three improvise-e24v listed as free" below.

The lockstep harness these are tested through (both_ends in tests/lockstep.rs) is worth two sentences, because two of its choices were wrong first. It compares the document as .improv text, not as Debug: Debug prints the symbol table's HashMaps, so two byte-identical documents print differently per process (gotcha 18), and the first version failed on nothing but hash order. And it applies the client's composed commands to a second authoritative host rather than eyeballing them, restating the basis against that host with caught_up — the claim was published by the first host, and the basis is the only thing that legitimately differs between two hosts holding the same document.

How the client claims, and why there is nothing here to keep in step. A client must answer the same question the server does — which records does this ModelCommand write — to build its Basis. The first version of this answered it again, in two helpers (structural, claiming nothing, and record_write, claiming the cell's own record), and the adversarial review of PR #50 showed that nothing tested them: lockstep.rs's apply_on restates the basis against the twin with caught_up, which re-derives it with the server's records_named and throws the client's claim away before anything is compared. Emptying record_write's claim left the workspace green.

The fix is not a test. records_named is pure — &ModelCommand -> Vec<RecordHash>, no App — and RecordHash is an improvise-core type the protocol already re-exports, so it moved down into improvise-protocol beside the enum it reads, and improvise-command re-exports it. resolve.rs has one model() that claims records_named(&cmd). The client's claim is now right by construction, and the guard is the one that was always there: records_named is an exhaustive match, so a new record-writing variant fails the build.

What the old shape would have cost is worth recording, because it is not a compile error: structural accepted any variant and claimed [], so a new record-writing command would have compiled clean on the client with the wrong answer, and the symptom is Rejection::RecordUnstated — the browser binding becomes a dead key, refused, with nothing failing.

both_ends compares every cursor, not only the document, the mode and the status. Three of the resolvers' decisions are a cursor move and nothing else — delete_view_at_cursor's step-back is the sharpest — so a comparison that stopped at the document would agree while the panel cursor diverged.

Mirror the Cmd line for line, including where siblings disagree

doctrine(mirror_the_cmd_line_for_line). Move emits SetSelected even when it clamps and MovePanelCursor returns nothing when the cursor does not move; MoveTileCursor emits regardless, like Move. Tidying that into one rule would make this a second derivation, which is exactly what tests/lockstep.rs exists to rule out. Which widgets say nothing about a move that goes nowhere is not a rule of this module — it is whatever the Cmd being mirrored does, and the three differ.

Two more places the mirroring is literal. panel_cursor clamps a cursor past the end before applying the delta, and derives the category panel's length from flatten_cat_tree — which depends on expanded_cats, per-client, which is why it is derived rather than sent and why the derivation lives in improvise-protocol where both ends reach it (improvise-edp). And commit mirrors change_mode(exit_mode_for(edit_mode)), then EnterAdvance — which aborts the rest of the batch at the bottom-right corner, so the re-entry is skipped and the user lands in normal mode — then EnterEditAtCursor, which seeds the edit buffer from the cell it landed on. The trailing clear-buffer the keymap welds to every commit then empties that buffer again. That ordering looks wrong and is exactly what the TUI does; mirroring it is the point.

GridMove is a hand-spelled mirror of navigation.rs's MoveKind, because the command crate is not on a browser's dependency list and never will be. The keys that reach it are no longer spelled twice. scrolled_to mirrors navigation.rs::viewport_effects over the window this client announced.

The three outcomes

KeyOutcome::Local(Vec<Command>) — resolved here; the caller folds them locally and sends them, as one frame and in this order (the asker's own fold is its own; the host forwards only to the others). A Vec because one keypress is one binding but several Effects: a cursor move is SetSelected plus whichever scroll offsets follow, and a Binding::Sequence is several commands to begin with. Never empty — a keypress this client can answer with nothing is Ignored, and KeyOutcome::of is the one constructor so that contract is a property of the type's users rather than a rule each resolver remembers.

Upstream(KeyEvent) — bound to a command this client cannot compose. Ignored — nothing bound, or what is bound resolves to no change. Nothing bound is not "the host might know better": the host looks the key up in this same table. That is new; it used to go upstream into an empty vec.

A Binding::Sequence is all or nothing: half of Esc — clearing the buffer without leaving the mode — is worse than none of it. Each step is resolved against the unchanged state, because the host resolves every step against one immutable CmdContext; the commands are then folded in order.

What still needs the host

the_command_names_that_still_need_the_host_are_these names them, and Host::handle answers a Key frame with an empty vec, so each one is a binding that does nothing at all in a browser (doctrine(an_upstream_key_is_a_black_hole)).

An upstream key that the app also ADVERTISES is a different severity, and it had its own class of defect (improvise-rmvx). A key nobody offers doing nothing is a gap; a key named in the mode's own hint line doing nothing reads as broken. The two are crossed by every_advertised_command_answers_in_its_own _mode, which asks help::advertised — a table of command names, so the cross-reference is exact and nothing tokenises the rendered string — against resolve in every mode, over a fixture furnished enough that an Upstream can only mean an unhandled name. The old guard asked only about Normal, which is why add-record-row and delete-formula-at-cursor were outside its reach entirely; view-back in RecordsNormal was a seventh instance nobody had noticed.

Ignored is a black hole too, and the guard watches both variants. KeyOutcome::of turning an empty Local into an honest Ignored is good design and also a laundering step — every wrong answer that composes nothing arrives wearing the variant that is usually innocent. A guard's discriminator must therefore be state (did anything the user can see change) and never the shape of the return value. Watching only Upstream let three of the six declines go completely silent with 1397 Rust, 19 harness and 26 node tests green, because no browser spec presses those three keys (PR #71 review).

nothing_declined_is_also_composed closes the other direction: step reaches declined first, so an arm in composed for a declined name is unreachable, and the browser would go on saying "not available yet" over working code. It is derived from declined itself over every bound (name, args) in every mode, so a seventh decline is covered without editing it. enter-mode was a real overlap on its first run; rather than move the check, both halves hold the rule — composed returns None for a stranded mode — so removing one fails towards Upstream rather than towards a dead room.

declined is the answer, and it is one list rather than an arm apiece: six command names, each with its own true subject. Wording matters here more than it looks — the > fix was nearly routed through a message about aggregates, which would have been true-sounding about the wrong thing and worse than silence, because a reader who is told something plausible stops looking. step checks declined first, so composed has no arm for any of them and the two lists cannot overlap.

A declining step takes its whole sequence with it: o in RecordsNormal is [add-record-row, enter-edit-at-cursor], and the second step's premise is false once the first has declined. Returning only the decline, rather than the decline plus whatever composed before it, is what keeps Binding::Sequence's "every step or none of them" true — an abort is not a rollback (gotcha 21), and this client has no way to undo a Command it has already put on the wire.

The classes that remain:

• Prefix keys. Command::SetTransientPrefix exists and this client could arm one; what it cannot do is what the second key then runs, which is yank, wq and toggle-col-group-under-cursor. Arming a prefix whose payload is unreachable is worse than not arming it.
• Anything naming a row, column, item or group — hide-selected-row-item, toggle-group-under-cursor, delete-formula-at-cursor. The first two are no longer blocked and are simply not built here yet (improvise-e24v): since improvise-anr9 GridCache carries an AxisFrame per axis, so cats[0] + label(idx, 0) is exactly what HideSelectedRowItem reads off GridLayout, and group_of(idx) is exactly ToggleGroup's (category, group). The one thing to get right is that the frame is windowed and the cursor is absolute, so a client must reconcile the scroll offset first, as render.rs does for the selection. delete-formula-at-cursor stays: it names a position in the formula panel, not in the grid.
• Anything touching storage or an arbitrary command line. The host's by definition.
• The records-mode commit — except the two creating columns. A wide-records row is one coordinate tuple and editing a category column moves every measure cell in it; commit_plain_records_edit needs GridLayout::record_col to know which. A CellId::Create does not: it commits the typed NAME as one existing ModelCommand (AddItem into _Measure, or AddCategory), reads no record_col and writes no cell, so improvise-gcvb narrowed the early return rather than removing it. The +cat half must not advance: an inserted column renumbers every index to its right and the advance was computed from the pre-commit layout (gotcha 23), so CommitAndAdvance returns straight after it and a client that advanced anyway would land one column off, silently. AddCategory can also be refused by the 12-category limit and sets abort_effects; the mode change therefore goes first, where an abort cannot reach it (gotcha 21).
• Drill. Session-local residue, and the one case that does not go upstream silently — see below.

The three improvise-e24v listed as free, and what each really costs

improvise-4bwa. Each of the three is short exactly one fact, and the three answers are different in kind — which is the point, because "needs enrichment" read as one bucket is what let them be listed as free.

view-back was declined, and the decline outlived its reason by one wave — improvise-cfly. What the passage below argued, kept because the argument is still the right shape and only its conclusion moved: ViewNavigate { forward: false } emits ApplyAndClearDrill before ViewBack, and ApplyAndClearDrill is deliberately off the wire — its operand is drill_state.pending_edits, session-local residue belonging to whoever staged it, and a Command::Model is routed with no SessionId (gotcha 38, improvise-3x3u). A client that mirrored view-back by reconstructing the drill commit would commit somebody else's uncommitted typing. The sharper reading still holds: mirror_the_cmd_line_for_line is a rule about resolvers, and a Cmd whose first effect is unaddressable is not one a thin client may mirror whole.

What changed is that mirroring it whole was never the only option. PR #115 made ViewBack a Command in the view half, folded by reduce_view into the asker's own slice and nobody else's — so the half that matters is composable, and the half that is not is unrepresentable rather than merely forbidden: the resolver could not emit ApplyAndClearDrill if it tried. Nor is it owed one. No browser path stages a drill at all: drill-into-cell is declined, and edit_or_drill's CellId::Aggregate arm answers out loud. So the divergence from the Cmd is confined to a state this client cannot enter, which is the narrowest form this doctrine's exceptions come in and is stated rather than hidden. The real asymmetry to mirror turned out to be elsewhere — stepped is silent on an empty stack where the Cmd speaks — and that is what step_history answers. Evidence: context/test-evidence/clients.md.

toggle-prune-empty needs one bool on a per-view projection. TogglePruneEmpty::execute reads ctx.view.prune_empty only to word its status — "Showing all rows/columns" against "Hiding empty rows/columns". The ModelCommand itself is composable today; it is the sentence beside it that a client cannot write, so mirroring it would put the two ends out of step on the status line in exactly half of all presses. View::prune_empty is on the View inside the Workbook, in no widget cache and not in ViewState.

delete-formula-at-cursor needs an element-type change, and the shape of the change is the whole decision. The effect is RemoveFormula { target, target_category }; FormulaCache carries the formula's raw text ("Profit = Revenue - Cost"), from which neither field is recoverable without reimplementing parse_formula in the client. Adding a targets vector beside formulas would be two answers to "what is in the formula panel", which is improvise-edp's disease and the mistake improvise-anr9 had to pay a type change to undo. So the element type grows the fields; it does not acquire a parallel array.

Both of those are ordinary projection additions and both live in improvise-protocol (render.rs, resolve.rs) and improvise-command (ui/project.rs) — not in this crate, which is why this section records the design and the work lands with whoever owns those files. Whatever lands, the named list the_command_names_that_still_need_the_host_are_these shrinks by exactly what closed.

What a client that could parse would cost: measured

improvise-cl7y asks a client to stop claiming "Formula added" for text only the host can parse. Its own note says the two routes are a dependency decision or a status addressed back to the composer, and leaves the cost of the first unmeasured. It is measured now, by adding improvise-formula to this crate, calling parse_formula from an exported method so nothing is stripped, and building the bundle both ways:

	improvise_wasm_client_bg.wasm	gzipped
today	503,854	191,613
with improvise-formula	634,515	238,973
cost	+130,661 (+25.9%)	+47,360 (+24.7%)

The raw column is exact and byte-verified; the gzipped one is a gzip -9 proxy and not what a visitor downloads, since GitHub Pages serves brotli. The conclusion is unaffected — the raw figure alone carries it — but do not quote "+47,360 gzipped" as a transfer size.

A quarter of the download, for a status string. That is the evidence for the other route — the host addressing a status back to the composer, the way ClientFrame::Save's rejection already does — and it costs no dependency.

Note what the measurement does not settle, because it is the more interesting half: a client that could parse would be a second derivation of whether a formula is well formed, agreeing with the host only for as long as both call the same function. The status line is not the only thing that wants it, so the number above is a floor rather than the price of a feature.

stranding: a prompt this client can enter but cannot commit

enter-mode is trivially resolvable here, and that is the trap: the user reaches the prompt, types a path, presses Enter — and the commit resolves to nothing, because Host::handle answers a Key frame with an empty vec. A dead room is worse than a locked door: the door costs one inert key, the room swallows work the user believes was done.

SavePrompt and ExportPrompt are host-only by construction, not by omission: effect::Save, SaveAs and ExportCsv are all EffectKind::ViewOnly, so the derivation that builds ModelCommand from the model effects cannot name them. Closing this is not a resolver to add; it is a wire operation that does not exist. In a browser it is also close to meaningless: the worker persists on its own behalf whenever the document is dirty, so the document is the OPFS entry and there is no Ctrl-S semantics to offer.

It returns the subject rather than a bool (improvise-rmvx): the refusal is right and the silence was not, so : now says the command line is unavailable instead of doing nothing at all. The predicate is named as a property rather than matched at the call site (doctrine(two_questions_one_enum)): "can this client finish what entering the mode starts" is not the same question as "is this a text-entry mode", and a third such prompt belongs here. Found by Copilot on PR #27 against the newly added SavePrompt; ExportPrompt had the identical trap already and was fixed with it — fixing one arm of a rule with two is the shape doctrine(one_arm_of_a_symmetric_rule_is_evidence_about_that_arm_only) names.

CommandMode is dead by omission, and listed anyway. Copilot found it on the next round, and it was a false negative in the predicate's first version — which mattered more than its severity, because a_prompt_this_client_cannot_commit_is_never_entered used : as the negative arm that stops "refuse every mode" from passing. An arm asserting something false does not merely fail to guard; it certifies the behaviour it was added to rule out. : resolves locally into CommandMode and typing appends locally, but Enter is [execute-command, clear-buffer] and step has no execute-command arm, so resolve returns Upstream and the frame is dropped. Every ex-command behind : is inert for the same reason, so refusing the mode removes no working surface, only a room that swallows typing.

The distinction from the two prompts is worth keeping visible, because it says who removes that line. They are dead by construction: no ModelCommand can ever name Save/SaveAs/ExportCsv, so no resolver would help. CommandMode is dead by omission: execute-command is implementable client-side and improvise-e24v is scheduled to do it. Listing it is therefore also the named gap gotcha 47 asks for — closing e24v has to come to that line and delete it.

Per-arm notes that would otherwise be re-derived wrongly

• enter-tile-select. EnterTileSelect gates on model.category_names().len() > 0, which counts the virtual categories too — _Index, _Dim and _Measure always exist — so the gate is invariantly true and there is nothing here to mirror it against. Re-deriving it from CategoryTreeCache, which carries the panel's rows rather than category_names(), would be a second derivation that disagrees on exactly the empty document.
• transpose. It used to be emitted alongside a mark_dirty this client had no wire variant for; since improvise-gv9r dirtiness is raised by the host off the effect's own EffectKind, so there is nothing to mirror and nothing missing. The cursor reset is not this client's to send either: the effect calls App::reset_cursor, and adopt_cursor_epoch broadcasts Command::ResetCursor to every client on a view the batch reshaped (improvise-nynk) — so sending one here would be a second, differently-addressed copy.
• toggle-panel-and-focus. The interactive arm of TogglePanelAndFocus: open-and-focus unless this panel is already both, in which case close and unfocus. The decision is made in registry.rs on the host and here on the client, from the same two ViewState facts.
• edit-or-drill. The host asks whether a regular category sits on Axis::None and whether the cursor is on a synthetic records cell. This client asks neither: the server already published the answer as the CellId variant, and doctrine(a_demo_is_checked_against_the_type_not_the_axes) says to read the type rather than re-derive the rule. It reads edit_text, never text: the drawn text has been through format_f64, so a stored 1200 reads "1,200" under a comma-grouping format and committing it would store the string "1,200". tests/lockstep.rs found exactly that.
• Drill does not go upstream — by either door. Every Upstream is a black hole, and a key that visibly does nothing is the worst of the three answers. Drill is session-local residue and reaching it needs a CellKey this client cannot build, so the honest answer is to say so: a SetStatus, which is a view-half command — Sessions::apply folds it into the asker's own mirror and broadcasts nothing, so it reaches this user and no one else. This argument arrived as edit_or_drill's, i.e. about i/a on an aggregate, and for a while it read as doctrine for > while > was still silent. Both doors now refuse, and they refuse with different sentences on purpose: "this key is not built yet" and "this cell is not yours to write" are different facts.
• The commit's write is not spelled again here. It is Client::typed_cell's, the same one click-to-edit uses, so a browser keyboard commit and a browser mouse commit cannot disagree about what "" or "42" means.
• cell_at_cursor returns None when the selection is scrolled out of the window — not a state the cursor keys can produce, since they scroll to follow, but one a projection race can.
• grid_move's two empty shapes are kept apart from "not ours": an empty grid has nowhere to move to, and a client that has not announced a viewport has been sent no grid either. Neither is a key the host could answer better.
• Quit has no keymap, on purpose: ModeKey::from_app_mode is exhaustive so that a new mode without bindings is a compile error rather than a mode that swallows every key.

Browser key → improvise key

to_key_event returns None for two cases the host must never see. A bare modifier press ("Shift", "Control", …) is not a keypress. And anything held with the platform meta key is left to the browser: KeyModifiers has no bit for Meta, so forwarding Cmd-R would arrive as a plain r and type into a cell instead of reloading the page.

Two conversions are not obvious. A terminal reports Shift-Tab as its own code and the keymaps bind that code; the browser reports Tab plus a shift flag. And shift is deliberately dropped for character keys: the browser already applied it ("A", not shift+"a"), and the shared keymap's lookup_local retries character keys without modifiers for that very reason, so keeping the flag would only make an exact binding miss.

The pointer: Click, and the four rules it obeys

A click is resolved here for the same reason a keypress is — a front end paints and wires, it does not decide (design-principles §5). resolve::click takes a Click naming a widget and an index, and returns the Commands. web/app.js attaches listeners and knows nothing else; there is one entry point per widget on Client, which was the user's ruling on improvise-7ybz.

Rule 1 — a click navigates to what was clicked, and activates it where activation is something the client can express. Every arm composes the same shape: focus the panel, SetPanelCursor to the row, then whatever Enter does on that row. The activation is resolved against the clicked index, never against the cursor, because the SetPanelCursor ahead of it has not been folded when the resolver runs — the trap that reads as "the cursor lands on Plan and the document switches to Default", silent and wrong in the half a user does not watch.

The second clause of rule 1 is what makes the formula panel look inconsistent and is in fact the rule holding. ModeKey::ViewPanel binds Enter to switch-view-at-cursor; ModeKey::FormulaPanel binds a/n/o and d/Delete and no Enter at all. So a view-row click switches and a formula-row click only navigates. Opening the editor on a formula click would be an activation invented for the pointer that the keyboard does not have — a second derivation of what a formula row means, which is the disease §5 names. The guard for this must be aimed at the keymap, not at the click: asserting that the click emits no FormulaEdit only restates the author's reading, and a reviewer demonstrated the gap by adding Enter -> enter-mode formula-edit to FormulaPanel and watching the whole workspace stay green while the click and the keyboard disagreed. the_formula_panel_has_no_enter_to_mirror_and_the_view_panel_does asserts the binding's absence and names click_formula_row as what must change if it ever appears.

The browser assertion that PR #60 dropped stays dropped, and improvise-qf57 is the decision rather than the oversight. #grid input toHaveCount(0) was argued to be redundant with the #mode assertion on the grounds that toHaveText("FORMULAS") is exact and AppMode::FormulaEdit labels as "FORMULA" — a coincidence of two strings differing by one character, which would be a thin reason to leave it out. Measuring it gives a better one: it is not redundant, it is unreachable. web/app.js creates a grid <input> in exactly one place, the grid cell's own mousedown, gated on cell.editable; no repaint creates one and no panel handler can reach it. And an invented formula-row activation opens the minibuffer, not a grid editor. Injecting Command::ChangeMode(AppMode::formula_edit()) into click_formula_row and running the spec: #grid input toHaveCount(0) passes, and the run fails on the #mode assertion below it. Restoring it would add an assertion that cannot fail — the same defect this file already records one line down, where an explanatory assert! was removed for never being able to be the failing one.

Rule 2 — a click is all of its intents or none of them (improvise-hkr8). Each click_* returns Option<Vec<Command>> and click does the single unwrap_or_default. The case that matters is an activation the client cannot compose: filter_to_item_at goes through model, which goes through BasisCache::claim, which returns None until the server has published a basis (gotcha 43). Before the fix the None was swallowed per-intent, so the click kept its navigation prefix, dropped its activation, and reported success — while the keyboard handled the identical None correctly by answering KeyOutcome::Upstream. Note that None at the click level means something different and benign: the whole click composed nothing, which is the invariant rather than a breach of it.

Rule 3 — a click on an unselected tile never mutates the document. The user's ruling on the tile bar. The cost accepted is two clicks for the common action and a deliberate divergence from the keyboard, where Enter cycles directly — record it as chosen, not as an inconsistency to tidy, or someone will read the binding and "fix" the pointer to match. What it buys is worth more than the keystroke: a tile cycle is a LayoutGeometry change, which bumps cursor_epoch and therefore resets every connected client's cursor (gotcha 24), so a stray click used to cost every other viewer their position.

State the rule this precisely, because the looser wordings are false. The implemented rule is "clicking the already-selected tile cycles it; clicking any other selects it", where already selected is mode == TileSelect and tile_cat_idx == index. The tempting summaries — "a click never mutates on its own", "a second click cycles" — both have the same counterexample, found on review: T enters TileSelect leaving tile_cat_idx at 0, so a click on the leftmost tile is a click on the already-selected one and cycles on the first gesture. Two adjacent tiles therefore answer the identical first click differently, and that is correct rather than a hole — a click does what Enter does there, and Enter in TileSelect cycles the tile under the cursor. The resolver cannot see how the state arose and must not try to.

The mode conjunct is still load-bearing in the other direction: without it, tile_cat_idx == 0 in Normal mode would read tile 0 as already selected, and the very first click of a session on the leftmost tile would cycle it.

Rule 4 — the shared helper is the idiom, and breaking it is how the two arms drift. click_category_row calls filter_to_item_at, click_tile calls tile_axis_at, click_view_row calls switch_view_at — each is foo_at(index) with the keyboard's foo_at_cursor calling foo_at(cursor). click_view_row originally re-spelled SwitchView + ChangeMode(Normal) inline, so a host-side change to SwitchViewAtCursor was forced into the keyboard arm by tests/lockstep.rs and left the click behind silently. A helper that returns only the name rather than the whole activation is what invites that.

The category panel opens at launch, in both front ends

ViewState::default() sets category_panel_open: true. The user ruled this twice: first that the sidebar be visible at launch, then — asked whether the terminal was collateral — that it applies to both. improvise model.improv opening with the sidebar showing is intended, not a side effect of sharing a default. It is the shared default for the reason wsaw gives: a browser-only default would be "the page overrides the flag", which is the same defect as "the page ignores the flag" wearing different clothes.

A launch default disarms every test that asserted the thing it now supplies, and that is the expensive part. Three tests asserted category_panel_open was true after doing something to make it true; all three then passed without the code under them working. The worst was set_panel_open_and_cursor: with it vacuous, effect::SetPanelOpen's Category arm could be replaced by a no-op — C doing nothing in the terminal — with the whole workspace green. The rule this leaves: assert the direction the default cannot supply. Closing the panel is the discriminating move; opening it proves nothing.

Note the two mappings that had to be repaired separately. effect::SetPanelOpen and reduce_view's Command::SetPanelOpen are two three-way matches in two crates — the TUI folds one and the browser the other — so a guard on either says nothing about the other. That is a derivation done twice (§5), pre-existing and filed rather than fixed here.

Two tests, because either alone passes against the bug wsaw fixed: the panel is visible with no keypress, and C still hides it. Injecting "the page ignores the flag" fails the second; injecting "the default is false" fails the first. A test that only asserts the sidebar is visible cannot tell the flag being honoured from the flag being ignored.

A black hole that leaves the keyboard in a mutating mode (improvise-koh6)

This file's list of what a client cannot compose used to read as a list of keys that do nothing. N was on it, and it is worse than nothing. N is advertised on the browser's own help overlay ("Quick-add a new category, from anywhere"), it resolved Upstream, Host::handle answers a Key frame with an explicit empty vec — so the DOM was byte-identical — and the user then typed the category name into NORMAL, where i is bound to edit-or-drill and opens the grid editor pre-filled with the cell's current value. Measured on web/demo.improv: N R e g i o n Enter turned 18,400 into the text 18400on, with no category created. A dead key in a modal editor is a data loss, not a papercut, and that distinction now belongs on the list.

The decision it forced. SearchOrCategoryAdd::execute is a conditional: a non-empty search_query delegates to SearchNavigate, which a browser cannot compose (it would have to search a grid it holds only a viewport of); an empty one emits two commands this client already has. Composing the second arm and returning None for the first would make whether the host is needed depend on client state, which enter_in_an_empty_view_panel_resolves_locally_rather_than_upstream exists to forbid.

The resolution is that the rule is about Upstream, not about outcomes. The name is now answered in composed in both arms — the composable one builds the pair, the other declines through not_yet with its own true subject — so the host-needed list stays a property of the name. The outcome varying with state is what cycle-axis-at-cursor and paste already do a few arms above; what must not vary is whether an answer exists at all. declined() could not express this, being keyed on the name alone, which is why the sentence moved into not_yet and the arm lives in composed: step reaches declined first, so the two lists still cannot overlap and nothing_declined_is_also_composed still holds.

Note the arm mirrors the Cmd line for line, including that it uses a plain mode change rather than EnterMode and so does not clear the minibuffer on the way in. Tidying that would be a divergence, not a tidy.

A cursor that does not follow a shrinking list (improvise-uej8)

d on the last item of an expanded category shrank the tree under a cursor that stayed put, so the row beneath it became the next category's header — and one more d removes a whole category, which is LayoutGeometry and rewrites every view's axis map. The same Cmd backs the same key in the TUI; this was never browser-specific.

The rival fix is the one delete-view-at-cursor and delete-formula-at-cursor already use — step back whenever the cursor is above zero — and on this list it is worse than the bug: the first item of a category would retreat onto that category's own header, the same escalation one row earlier, and holding d would walk backwards instead of clearing the category out. Those two panels are right to do it because their lists are homogeneous; a cursor that does not move on a one-kind list cannot escalate. That is the property to check before copying a cursor rule between panels, not the panel's name.

The first fix was the adjacent-only one — step back when the row below is not a sibling — and a ChatGPT Codex review of PR #114 found it wrong for a category with exactly ONE item. That is the configuration in which the conditional rule degenerates into the unconditional one: no sibling below, so it steps back onto the category's own header, and the escalation returns. The paragraph above had already named that shape as the reason not to copy the other panels' rule; it just did not notice that the singleton reaches it too.

CatTreeEntry has two variants and flatten_cat_tree emits a header then its items, so the enumeration is short. After deleting the item at i: if the row below is a sibling the list closes up and the cursor stays; if the row above is a sibling it steps back; and if neither, the category is now empty and BOTH neighbours are Category rows — there is no safe adjacent landing at all. That third case is structural rather than an oversight, and it is why the rule could not be patched in place.

So the landing is the nearest Item row, preferring above, then below. d there deletes an item, never a category, which is the criterion the review asked for. The cost is real and is not hidden: the cursor may cross into another category, and a held d then deletes one item per press — each with its own status line — walking upward rather than escalating. Landing on the emptied category's own header was rejected even though RemoveCategory on an empty category is cheap (no cells, and a non-measure formula target is an item, so no formulas): that is a harm-magnitude argument, and this repo prefers making the bad state unreachable.

One residual, stated rather than guarded: if the deleted item was the only item in the whole tree there is no Item row anywhere, so the cursor does not move. Every category is empty at that point, so the escalation it leaves is the cheap one, and no landing exists that would avoid it.

One operation, two routes, one sentence (improvise-25bf)

cycle-axis-at-cursor from the category panel emitted no status where the tile route emitted Product → None, so the same operation told the user only down one of its two paths — design-principles §5 in miniature. The wording now has one home, viewmodel::axis_change_status, called by both routes here and by both in the TUI.

This also pays for improvise-z336's third finding, which is the more interesting half: the Filter: X = Y status persisted after the axis had moved to None, Row and Col, so the one piece of feedback about a filter was wrong exactly while the user was trying to be rid of it. A user who had cleared it correctly was told for the rest of the session that it was still on — a mechanism that manufactures a bug report out of a working code path. It needed no separate fix: a route that writes a fresh status writes over the stale one.

---

improvise-wasm-client — the crate, the fold, the render model

What the crate is, structurally

One wasm32 artifact, reused literally in both deployments: the thin client talking to a server over a WebSocket and the standalone app talking to a worker that hosts the App over the worker's own port. Only the JS bootstrap differs — nothing in the crate knows what the transport is.

It is a fold and a key classifier, and nothing else. It holds a ViewState plus one widget cache each — there is no aggregate render cache — and it moves them by folding the same Command stream the host folds. The fold is state.rs; the key classifier is keys.rs.

The argument that shaped it: a keymap binding names an intent resolved against a CmdContext; a Command is the resolved mutation. A thin client holds no Model and no GridLayout, so it cannot do that resolution. (Since improvise-bpq2 the table is shared and the resolution of the composable subset happens here; what is left upstream is the subset keys.rs names.)

That is why the command crate is a dev-dependency and not a dependency: its keymap could not be used here even if the bundle could afford App, Workbook, persistence and the import wizard. What the dev-dependency buys is tests/lockstep.rs, which drives the authoritative host and this client over the same keypress and asserts the two ViewStates agree — the correspondence is checked rather than asserted in prose.

The boundary is JSON, so the JS side needs no generated structural bindings and the same strings go on a socket unchanged. No std::fs (it compiles for wasm and fails in a browser) and no clock: nothing here calls Instant::now(), so the web-time shim the command crate needs is not needed. Both are structural, not disciplined — this crate depends only on improvise-protocol, serde, serde_json and wasm-bindgen, none of which reaches a filesystem or a clock.

Ordering. The JS bootstrap must deliver frames to Client::on_frame in arrival order, one at a time. The grid fold is deliberately not commutative — a GridUpdate::Cells that overtakes the labels framing it is dropped — so batching or reordering silently loses cells. For the same reason a locally-resolved command and a forwarded keypress must go out on the same ordered channel, in the order Client::on_key_event returned them.

Why the wasm_bindgen surface is a thin wrapper over a plain-Rust one. wasm_bindgen methods cannot take or return the protocol's types, so there is one code path serialized at the edge. The split is not only ergonomic: JsError::new panics off wasm, so every fallible path has to be reachable without it or its failure arm cannot be tested at all.

Client::viewport vs Client::set_viewport. viewport is associated rather than a method, because a page must send the handshake before it has anything to fold. But it builds the frame and forgets it, so a client driven only through it never learns its own window and therefore resolves no cursor key locally — a truthful subset (those keys go upstream and the host answers nothing) but a whole feature quietly off. set_viewport is the one a page should call. The window is not derivable from anything the host sends: the row frame's own length is min(window, grid − offset), so it agrees with the window except near the bottom edge, which is precisely where the scroll arithmetic matters. viewport is kept because web/app.js already spells it and retiring it is a co-ordinated change.

improvise-protocol/src/client.rs — the two properties this dispatch owes

Both are tested in state.rs rather than assumed from the protocol crate's own tests, because the dispatch between them is this crate's.

• The stream is not reordered. Every fold path is a for over arrival order; there is no batching, sorting or coalescing.
• Bootstrap is a compaction, not a replay. ClientState::bootstrap folds Snapshot::seed exactly as the steady stream is folded, so there is no second code path that could disagree with the incremental one. GridCache::seed puts the labels before the cells for the same ordering reason.

window is deliberately not reset by bootstrap: the browser window did not change size because the document was replaced, and clearing it would silently stop this client resolving its own cursor keys until the next resize.

last_rejection is kept as a value, not a sentence. A rejection is the input to force, and force is a re-composition against the republished basis — which needs to know which record and which kind. RecordGone cannot be forced at all; RecordMoved can be forced with one keystroke. A string cannot carry that. It is session-local: it belongs to whoever composed the refused batch, so it is not part of the portable slice and does not survive a bootstrap.

window is session-local and not portable for the same family of reasons: it is a fact about a browser window, which is why no Command carries it and why it is not on ViewState. (0, 0) means this client has not announced one yet, and a client in that state resolves no cursor key — it has been sent no grid either.

socket.rs — the frames, the wording, and the one composition

Where the frames live: not here. ClientFrame/ServerFrame are improvise-protocol's, and the same pair frames both deployments. This crate used to carry two envelope pairs of its own: one mirroring improvise-ws-server, because a native crate cannot be a dependency of a wasm bundle, and one written for the worker before the projection architecture landed. The mirror was held honest by two tests round-tripping every variant through the server's own types; with one definition there is nothing left for them to compare, which is what improvise-xks6 was for.

rejection_message is spelled here rather than on Rejection for the reason AxisColor is not a ratatui colour: the protocol carries the fact, and each front end words it. The wording tracks ADR 001's force table, because "try again" and "this cannot be forced" are the two different things a user must be able to tell apart — a RecordGone has nothing to write to, and offering force there would promise something the design refuses to deliver (force never creates structure). Two wordings are load-bearing: DocumentReplaced must not say "reloading", because nothing here reloads, and the two save failures are not staleness so neither offers a retry — retrying changes nothing about the host's storage.

typed is a rule that genuinely lives in two places. It is the same three-way split commit_regular_cell_value makes — empty clears, a parseable number is a number, anything else is text. It is duplicated here for the reason the whole client exists: the browser has no App to ask, and ModelCommand::SetCell takes a CellValue, so somebody on this side must decide. Putting it in Rust rather than in the page's JavaScript is what makes it testable and keeps one spelling per language boundary instead of two.

This is the only answer the client gives to "what does a typed string mean" (improvise-r4lo), and it holds on every deployment including the worker: a host's App sits behind the frame boundary and is handed a value, not a string, so no host ever classifies a string that arrived over the wire. The careful half: a host does classify its own local keystrokes, which is why this is a duplicate of that split rather than a call to it — the command crate is deliberately not a dependency, and reaching it would drag App, Workbook and persistence into the browser bundle.

So a_typed_string_is_classified_as_the_host_classifies_it states the obligation without discharging it: it asserts the three outcomes by hand rather than comparing with the host's function, so the two could drift and stay green. That is doctrine(a_consolidation_that_keeps_its_compatibility_test_is_unfinished) still open, one layer below what improvise-r4lo closed — the real fix is a shared split in improvise-protocol, which both crates already depend on. Filed rather than done.

typed's None means "clear this cell", which is a different command, not a different value — hence the Option rather than a CellValue::Text("").

typed_cell_frame is the composition improvise-q08 found a thin client could not do. It holds no Model, so it cannot build a CellKey — but it does not need to: the id on the cell it is already drawing is the address, and it is echoed back unread (ADR 002). It takes the user's string, not a CellValue, for the reason above; there is no deployment for which a pre-classified entry point would be right. A sibling taking a serialized CellValue used to sit beside it and claim the opposite; it was deleted rather than re-documented, because it could not express ClearCell and was therefore a strictly weaker duplicate.

None on four shapes, each a different fact the client already holds: the position is outside the grid; the position holds no settable cell (id: None — padding, or a records-mode column that renames a coordinate rather than writing one); the cell is an aggregate, which is the pattern failing to bind rather than a check; or this client has not been told the document's basis and so has nothing truthful to say about what it composed against (BasisCache::claim withholds rather than invents).

Nothing is folded there. The new value comes back as a GridUpdate::Cells from the host, which is the side that formats it; guessing it locally is how the two ends drift apart.

typed_cell_command is the one composition shared by the mouse path (typed_cell_frame) and the keyboard path (keys::commit). Writing it twice is how a browser commit by Enter and a browser commit by click would come to disagree about what an empty string means.

render.rs — the four decisions that are silent when wrong

The DOM half of this client is JavaScript. The split is drawn to make that acceptable rather than comfortable: every question with a wrong answer is answered here, in Rust, under test, and what crosses to the page is a list of rows of cells that each already know whether they are editable, numeric, erroneous and selected. The page's job is document.createElement.

• Editable is a fact about the id, not about the text. Only CellId::Record may be written (ADR 002), and there are now four kinds, each naming a permission. CellId::Aggregate is a drill target and Drill is not on the wire yet, so it renders as non-editable rather than as a control that does nothing. CellId::Derived { target } is a cell a formula owns (improvise-ir7l): i on one names the formula rather than opening an editor, because a write there lands and is then shadowed forever by formula_cache. CellId::Create(kind) is a records-mode +/+cat column (improvise-poia), where what the user types is a name, not a value. And None is not any of those — it is "no projected cell here": a padded slot, a blanked one, or a records-mode column that renames a coordinate across the whole row rather than writing one.
• The selection is absolute and the grid is not. GridCache is indexed by position within the viewport, while selected and row_offset/col_offset are positions within the whole grid. Reconciling the offset is the entire conversion, and the trap is that forgetting it looks right at the top of a document and wrong after the first scroll. render.rs does it by adding — r + cursor.row_offset == sel_row — so there is no underflow path and a selection above the window simply never matches.
• The category panel is flatten_cat_tree, not a second walk of the cache. That function exists in improvise-protocol precisely so this end and move-panel-cursor share one flattening (improvise-edp); the page never sees CategoryTreeCache at all.
• The grid's frame is AxisFrame, and every header decision is made here (improvise-anr9). The multi-level header levels, the repeat suppression, the group runs and their collapse state come off the same AxisFrame methods the TUI widget calls, so the page receives labels already blanked where they repeat and group runs already spanned. Until this landed the protocol carried GridLayout::row_label's slash-joined tuple and the page drew Food/Alice where the TUI drew two header columns — a derivation the TUI's own test says is wrong, shipped to the other front end.

Nothing in RenderModel is on the wire. It is a projection of a projection — the client's own caches shaped for one renderer — so it may change freely without a protocol conversation.

Four smaller decisions that would be re-derived wrongly:

• RenderRow is an enum, not a label plus an is_group flag, so a group header cannot carry cells and a data row cannot carry a collapse state. It is serialized with a kind tag because the consumer is JavaScript. labels() is empty for a group header, which carries its label in its own variant rather than in a one-element tuple — so a caller walking labels() over the whole model sees the data rows and nothing else, which is exactly what neither_front_end_produces_a_slash_joined_label wants. A caller that means "every label on screen" has to match on the variant.
• RenderColGroup::label is an Option, not an empty string. An empty string is a legal group name — Category::add_item_in_group accepts one, and the TUI draws its indicator like any other — so a sentinel would serialize that group identically to an ungrouped run and the page would drop its indicator (raised by Copilot on PR #23). None for an ungrouped run also keeps the runs a partition of the columns: the spans sum to the column count, so a page laying them out as colspan cannot leave a hole.
• Column group runs coalesce by NAME alone, which is what src/ui/grid.rs does (group_name != prev_group), and the two must agree. Collapse is category-scoped, so two adjacent groups from different categories may legally share a name and differ in it; keying on the pair would start a second run the TUI suppresses. The run's indicator is its FIRST group's, again as the TUI paints it. col_groups returns nothing at all when no column is in a group, because "this grid has no column groups" and "every column's group is blank" are different statements and the page draws a line for only one of them — the same asymmetry GridCache::totals has.
• hint and editing are decided here, not in the page. hint is AppMode::hint_text(), the same string the TUI's footer draws, so the page spells no keys of its own — which is what keeps a second front end from growing its own idea of the bindings, and makes the modes this client can enter but not yet draw (Help above all) state what they are instead of looking like a broken grid. editing is AppMode::is_editing() plus the edit buffer: without it, a browser that resolved i locally would change its mode indicator and then swallow every keystroke invisibly.
• minibuffer is the same argument, for the other six text-entry modes (improvise-fdt6). editing drives the inline cell editor, so it is scoped to the two cell-editing modes and reads the "edit" buffer by name — which left FormulaEdit, CategoryAdd, ItemAdd, SavePrompt, ExportPrompt and CommandMode opening a prompt and swallowing every character typed into it. minibuffer is AppMode::minibuffer() plus the buffer that config names, read with improvise_protocol::read_buffer so the "search" special case keeps its one home (gotcha 11); None is "no text-entry mode is open", so the page asks nothing about the mode. The colour stays semantic — MinibufColor crosses and the CSS class is the page's last translation, exactly as draw.rs::minibuf_fg is the TUI's (gotcha 26). It is drawn as a line of its own rather than in place of #status as the TUI's bottom bar does, because #status also carries the transport's failures and a repaint must not erase one (gotcha 48).

RenderCell::edit_text is the stored value, not the formatted one: seeding an editor from text and committing turns 1200 into the string "1,200". The numeric/error flags are the server's answers, echoed — the client must not re-derive them from the text, which is how the two ends drift.

render_model builds header_labels(0) once for the whole frame, because the per-position accessors scan and asking them inside the row loop is quadratic.

---

render.rs and the help overlay (improvise-ktv1)

RenderModel carries help, help_page and help_titles, and the decision the page must not make is whether the overlay is open: an empty help is what says it is closed. That is the shape col_groups already uses for "this grid has no column groups" — an absent list rather than a flag the page has to interpret alongside a mode it would then have to understand.

The rows themselves are improvise_protocol::help::pages(), the same ones src/ui/help.rs draws. RenderHelpRow carries a kind string (heading, keys, accent, …) which is a semantic name the page maps to a CSS class — the AxisColor → axis_fg shape again, and the reason the page can style a heading without knowing what makes a line a heading. Where the content comes from and what is derived from the keymap is context/code/protocol.md §8.

web/app.js — the page

The browser half of improvise-cr3, kept as thin as it can be made, now talking to either of two peers (improvise-djm). The boundary is JSON strings in and out, so this file holds no protocol knowledge at all: it never inspects a Command, never builds a CellId, never decides whether a cell is editable or whether a typed string is a number. Five calls are the whole harness:

call	what it is
client.set_viewport(rows, cols)	the handshake frame, and every resize; also records the window so keys resolve here
client.on_frame(json)	fold one frame, in arrival order
client.render_model()	everything to paint, already decided
client.typed_cell(r, c, s)	the frame for "the user typed s here"
client.on_key_event(k,c,a,s,m)	the frame for a keypress, folded locally first where this client may answer it

The two rules this file must not break are ordering and framing: frames are folded one at a time in the order they arrive (a cell update that overtakes its labels is dropped, not replayed), and the first frame out must be the viewport, because the server builds the snapshot at it.

Everything in this file that is a decision rather than a paint now lives in web/shell.js — socketUrl, the #status composition, the watchdog, the extent arithmetic and gridPlan — so that node --test can reach it without a browser. The sections below describe those rules; the code is one file over.

Two transports, one client

The wasm bundle is the SAME artifact either way (improvise-xks6: one envelope pair, two deployments). Only where the strings come from differs, so the difference is confined to openTransport and nothing below it knows which peer it has:

• default — an in-page Web Worker hosting the whole App over OPFS (improvise-9x6). No server process; this is what makes a GitHub Pages copy of the directory a working application.
• ?ws=host:port — a websocket to improvise-ws-server. That process is how a document opened in the TUI is shared, so the path is kept; the presence of the parameter is the whole selection mechanism, because a second knob naming the same fact is a second thing to get wrong.

Neither is reachable silently. Every transport writes what it is doing to #status — "starting", "connected", "cannot reach …", "disconnected" — so a peer that never arrives reads differently from one that went away. "disconnected" means exactly the second: a socket that opened and then closed. A socket that never opened keeps saying "cannot reach …", because the close event there is the tail of the failure and not news.

#status carries two independent facts — what the transport is doing and what the document last said — so it composes them rather than letting a repaint quietly erase a connection error.

socketUrl: wss:// is the default

A bare host:port gets wss://, because the address that works from where this page is actually served is the one it should be easiest to write. The page ships to GitHub Pages, which is https, and an https origin refuses a ws:// address as mixed content — so a ws:// default would hand the browser a URL that cannot work and report it as a connection failure, which reads like "the server is not running".

An explicit ws:// is honoured only where it can function: a page served over plain http, which is the local python3 -m http.server case that pairs with improvise-ws-server (which speaks plain ws:// only — it has no TLS, so reaching it from https means terminating TLS in front of it). From an https page an explicit ws:// is upgraded rather than passed through, since passing it through can only produce a failure the user cannot act on.

set_viewport, and the twin that is gone

Same frame, but it also records the window. A client learns its window only from what it announced — the row frame's own length is the window clipped to the grid, so the two differ exactly at the bottom edge, which is where the scroll arithmetic matters. Without it the client cannot clamp, so every cursor key goes upstream into Host::handle's empty vec and the arrow keys silently do nothing (improvise-bpq2).

There used to be a frame-only twin, Client::viewport, exported beside it and called by nobody. Its doc said it was kept because web/app.js already spelled it — and web/app.js called set_viewport in the same wave, so the reason was false before it was read (improvise-seik). That matters more than an ordinary unused function, because the two are one letter apart and the wrong one fails silently: it sends an identical frame and simply forgets the window, which turns every cursor key into the black hole above. It is deleted, along with the exported init() free function that duplicated new Client().

A deletion is not the guard, though — the next export with no caller arrives the same way. web/tests/bundle/wasm_surface.test.js now reads the generated .d.ts and requires every declared method to be one app.js calls, or to be named in an UNCALLED table with its reason. free and initSync are wasm-bindgen's own; revision is there because on_frame returns it. Proved by injecting a spare static viewport(...) declaration into the built .d.ts and watching it fail by name.

frameCost: what the grid's own frame costs, in whole cells

One header row and one header column was right until improvise-anr9: the column header is now one row PER LEVEL plus an optional group row, the row header is row_levels columns wide, and inline group headers take a row each. Reserving one of each announces a viewport the page cannot show, and #grid has overflow: auto, so the DOM would acquire a scroll position of its own while the client's cursor offsets were computed from the larger window — putting the selected cell off screen.

It is measured off the painted model rather than predicted, and defaults to the old one-and-one before the first paint, which is the only moment there is nothing to measure.

The totals strip IS reserved, unlike the inline group rows below, and the difference is what makes it countable: it is chrome on the same terms as a header level — present exactly when totals is non-empty, once, never interleaved with the data — so counting it is neither a feedback loop nor a ratchet. The page bar is not reserved and needs no rule, because #pages sits outside #grid and so is already absent from the box extentOf measures.

Inline group ROWS are deliberately NOT reserved. They take real height, but how many are in view depends on how many rows the window asked for, so every way of counting them is either a feedback loop (count the current ones: a smaller window crosses fewer groups and asks for a larger one) or a ratchet (keep the maximum: a group-dense grid stores an oversized cost on its first oversized projection and never lets it fall — one group header per row clamps the grid to a single row, permanently). Both were tried. What is left is an over-request bounded by the groups in view: a grouped grid asks for a few rows more than the table shows, which matters only for a selection near the bottom edge — and that gap is not new and not specific to groups, since nothing in this page calls scrollIntoView at all. Filed as its own ticket rather than answered with a heuristic in a file the harness only partly executes.

The watchdog, and the two close arms

The handshake watchdog is about the first frame, not about either peer's own failure modes. The socket has an error event for a peer that never answers; the worker has none that fires, because worker.js catches its own start() rejection — so a browser with no OPFS, or a worker bundle that failed to load, would leave the page saying "in-page worker" over an empty grid forever. "The peer never answered the handshake" is the one condition that means the same thing in both deployments, and a check aimed at each peer's own failure modes would have missed exactly this one.

A peer that failed loudly has already said something more precise, so the watchdog must be DISARMED and not merely pre-empted: it fires later and would overwrite the better message with "did not answer" (PR #13 review). The watchdog is for silence only, and setShellFailure clears the timer.

Did this socket ever open? The page has to record that itself, because nothing on the close event carries it: readyState is already CLOSED by the time a close listener runs, whichever happened, and a refused connection and a mid-session network drop are BOTH code 1006 with wasClean: false. So "never connected" and "was connected and went away" are distinguishable only by remembering — an opened flag is the only discriminator.

A socket that never opened did not "disconnect": it failed to connect, and the close event is the tail of that failure rather than a second, vaguer thing that happened (improvise-taxx). Writing "disconnected" there unconditionally replaced the error listener's precise message with the least informative of the two facts.

That is the same family as the watchdog bug and NOT the same fix. The watchdog is disarmed because it is for silence only, whereas suppressing close outright would hide a genuine mid-session disconnect, which is the one thing that listener is really for. Hence the split rather than a guard. Both arms go through setShellFailure, which disarms the watchdog — and that half is the one that keeps getting lost. It matters on the opened path: the watchdog is armed after transport.ready resolves, i.e. on open, so a socket that opened and then dropped before its first frame reaches the close listener with the timer still pending, and "disconnected" is more precise than the guess it would otherwise fire 8s later. On the never-opened path there is no timer yet and the clear is a no-op. Neither arm leaves one armed.

Painting

• The column-group line is drawn only when there is one: an empty col_groups means this grid has no column groups at all, not that every group is blank. label is null for a run in no group, and an empty STRING is a legal group name that still gets its indicator — which is why the page does a null check and not a truthiness test.
• One header line per level, and a blank entry is repeat suppression decided in Rust, never an absent label.
• The cell coordinates a click sends are DATA row indices, and a group header is not a data row, so the page counts rows rather than trusting the position in model.rows.
• r is one binding shared by every closure in the row loop, so a click handler that captured it would fire with the LAST row's index. It is snapshotted.
• A keyboard edit is open when model.editing is a string, and it holds what has been typed so far. Both facts are decided in Rust — the page does not know which modes are editing modes or which buffer they type into. Without it the mode indicator would say INSERT while every keystroke vanished into a buffer nobody drew.
• editable is the server's answer relayed through Rust: a stored cell. An aggregate is a drill target and drill is not on the wire yet, so it is simply not offered.
• The inline editor seeds from RenderCell::edit_text — the STORED value, not the drawn one: td.textContent has been through the number format, so a stored 1200 reads "1,200" and committing that stores the string "1,200". Enter removes the focused <input>, which fires blur, which calls close again: harmless, but only by accident.
• The title bar is three fields and one joining. doc_name, doc_dirty and doc_stored_as come off the cache src/draw.rs::draw_title folds; the joining — name (stored_as) [+], in that order — is shell.js::documentTitle, which is the TUI's own spelling minus the improvise · chrome and the right-hand key strip. The three were projected by improvise-z754 and painted by nothing for a wave, and render_surface.test.js could not see it: that check is a substring search, so a field named by a function nothing calls reads as painted. What sees it is contract.spec.js, which loads the page and asserts the text (improvise-5jna). The marker itself is a node test rather than a harness one, because the standalone deployment persists on every accepted batch and clears the flag in the same round trip, so [+] is transient there.

The selection scrolls itself into view

web/app.js called scrollIntoView nowhere at all, so a selection driven past the bottom of #grid stayed there, invisible, with no way back but scrolling by hand (improvise-jq8l). Two things about it are easy to get wrong.

It is not a projection bug and not a row_offset bug. The row had been sent: #grid has overflow: auto and the page announces an extent from ROW_PX/ COL_PX, which under-estimate — a real row is 28.6px against the assumed 26 — and inline group rows are deliberately not charged for at all. So the page renders more rows than its own box can show, and the overflow is the DOM's, not the window's. Measured on harness/fixtures/tall.improv: 105px of overflow, the selected cell 96px below the visible bottom, scrollTop still 0.

block: "nearest" is the whole option. It scrolls only when the element is actually out of view, and it scrolls the nearest scroll container rather than the document, which is what keeps the page itself from moving sideways.

The reason this was untestable until now is the fixture: web/demo.improv is four rows and harness/fixtures/grouped.improv is eight, and neither overflows a 484px box. tall.improv is thirty rows in three groups, and the spec asserts the overflow exists before asserting anything about the scroll — without that line the whole test passes on a page that never scrolls.

The pointer takes cells on mousedown

A cell's handler is mousedown with preventDefault(), not click, and the reason is an ordering trap worth the paragraph (improvise-0x9u). From an editing state a click never arrived at all: the mousedown moved focus, the <input>'s blur ran close, close repainted, replaceChildren destroyed the <td> the mousedown had landed on, and no click was ever dispatched. The pointer was dead until the user pressed Escape or clicked outside the grid.

Three things had to move together, and each is load-bearing:

• mousedown, so the handler runs before any focus change.
• preventDefault(), so no focus change happens at all. Otherwise the default action focuses #grid after the handler has called input.focus() on the new editor, and blurs it immediately. The keyboard listener is on window, so nothing needs #grid focused.
• close no longer repaints, and blur checks closed first. Removing a focused <input> fires blur synchronously, so a close that repainted from inside itself detached the very <td> the handler was about to open an editor on. This is the same repair one level down, and it is why the first attempt at the fix still failed: the blur arm re-entered and rebuilt the table. close restores the drawn text rather than the seed, since nothing repaints behind it any more.

The state the old spec could not see is the whole point: it pressed Escape before clicking the second cell, so it only ever clicked from a non-editing page — this repo's characteristic defect, a test that passes while the thing it names is broken in a neighbouring state.

One handler per surface, and the node carries the answer

improvise-b8ot, on the user's ruling: one handler outside the area that gets redrawn, and dispatch events there. The five clickable surfaces — the grid, the category tree, the two side panels and the tile bar — had one listener per node, created inside the render loops and reallocated on every repaint.

The roots were already stable and that is what made it cheap: replaceChildren replaces an element's children, not the element, so every el.* entry survives every repaint and needed no new wrapper.

Not a performance change, and it must not be argued as one. The cell count is bounded by the announced viewport rather than by the document, and nothing leaked — replaceChildren drops the nodes and their listeners together. The argument is design-principles §5: paint and wire, applied to the dispatch as well as to the paint.

The operands are carried on the node, never re-derived from the DOM. gridPlan already decides row, col, editable and the class map, and its row counts data rows because a group header is not one. A delegated handler that walked up the table counting <tr>s would be a second derivation of exactly that, and it would disagree the moment a group header appeared. So the plan writes data-row/data-col/data-edit, cellAction reads them back, and the handler is a lookup. The split follows the bead's own division: data attributes for operands, the existing editable class for the predicate, and ids only for the surfaces, which they already were — a row or cell id would have to be unique per document and these are rebuilt per frame.

Four behaviours a naive rewrite loses, all silent, all asserted in harness/tests/contract.spec.js: mousedown rather than click (above), preventDefault() and only over a cell — a header carried no listener before, so a blanket handler on the root is a behaviour change — the repaint that is skipped when an editor opens, and closing a live editor first, before the click is composed.

The editor's own keydown and blur stay direct, deliberately: one transient node, one at a time, attached at creation and gone with it. blur does not bubble, so delegating it would need a root that does not own the input.

The page bar and the totals strip

improvise-p7lh, and the shape is worth more than the fix. GridCache has carried page_coords and totals since improvise-n10; the server projected both to every session, every client folded both correctly, the TUI painted both — and RenderModel had no field for either, so the browser painted neither. The shipped front page is Quarter: page, Q1, so it drew a grid filtered to Q1 with nothing saying so, while [/] — which resolve locally off that same page_coords — changed every number in silence.

Why the parity guard did not see it. web/tests/render_surface.test.js asks that every field RenderModel exposes is painted. Its domain is RenderModel, which is the thing under test: a fact that never reaches it is outside the domain, so the check was closed under the defect. The honest question is one level up — every field of every widget cache reaches a front end, or is named as debt — and that is now asserted too. It would have fired when the fields were added.

Two rules the painting itself owes. The totals are relayed, never summed here: the total runs over every row including ones a viewport scrolled past, which is why it is projected at all (gotcha 44), and an empty strip means "this grid has no totals" rather than a row of blanks (gotcha 33). And the Page/Filter split is asked of PageAxis::cycle, the one home of it: the plausible alternative, items.is_some(), agrees on both common cases and disagrees on an empty list, which is how a rule gets quietly respelled (invariant(the_page_filter_split_lives_in_the_type)).

Two residuals, named rather than left to be discovered. The word Total is now spelled twice — src/ui/grid.rs and web/shell.js::gridPlan — which fails §5's own test, would a third front end write this again. It is kept local on the indicator() precedent (the collapse glyph is spelled in both ends while the fact is shared) and because the alternative is a protocol-level string table for one word; invariant(a_ui_string_is_keyed_by_a_command_never_by_a_key) is where it belongs if a second such string ever appears.

The page bar is a control (improvise-rw6l)

It was display-only until improvise-rw6l, and this file said so, naming the missing click_page on the wasm surface as the reason. That is now built, and it cost less than the note implied: PageAxis::items was already projected and ModelCommand::SetPageSelection was already on the wire. The only gap was that RenderPageAxis dropped the names — it carried a position and a count, which is everything improvise-p1ym needed for [/] and nothing a menu needs.

The widening puts items inside cycle, not beside it. That is the whole design: one predicate, not two. A Filter axis has no cycle, so it has no items, no down-arrow, is painted as a <span> rather than a <button>, and composes nothing if a click somehow reaches it — four answers off the one home gotcha 27 already named. The tempting alternative, a separate items field on RenderPageAxis, gives the page a second thing to test and a way to disagree with itself.

The arrow follows navigable, never "is this on the page bar". A Filter axis is on the bar and must get no arrow: offering a menu that cannot do anything is worse than offering none, because the user spends a click finding out. A fixture with only a Page axis cannot see that distinction, which is why every test of it — Rust, node --test, and the two in the harness — carries a Filter axis beside the Page one wherever the shape allows.

The menu lives outside #pages, in its own #page-menu element. #pages has its children replaced on every repaint, and a menu rebuilt under the pointer is a menu that closes itself mid-click. Being outside also means a repaint is free to close it explicitly, which is the honest answer: the chip it was anchored to has just been rebuilt, and re-anchoring would be a guess.

Two surfaces, one meaning. improvise-b8ot's ruling is one delegated handler per surface on a stable root, operands off data attributes, no structural inference — so the chip carries data-axis and a menu row carries data-axis and data-item, and shell.js::pageItemAction is one function over both. That single attribute is the entire disambiguation. The case that has to be got right is an empty data-item: Number("") is 0, so a naive read turns "no item" into "item zero", and clicking the chip of an axis already on its first item would silently re-pick it instead of opening anything.

The menu owns the keyboard while it is open, which is the third state of the kind editing already was. app.js's window keydown handler returns early for editing; it now returns early for pageMenu too, into menuKey. That is the same mechanism rather than a new one, and the reason is specific: the menu hangs over the grid, so letting hjkl through would scroll the thing it is pointing at out from under it. menuKey therefore answers every key, with ignore as the default — an unlisted key is swallowed, not passed on — and count: 0 closes rather than wrapping modulo zero, because a repaint can empty an axis under an open menu.

active and selected are two different facts and both are drawn: selected is what the document is fixed to (a check mark), active is where the keyboard is. They start together and part on the first arrow key.

The tile bar says "Page", not "Pag" (improvise-771e)

Axis::short_label returns three characters so the TUI's tile bar aligns in a fixed-width terminal (gotcha 26); "·" for None is an answer there and not a truncation. A browser has no column to fit, so the abbreviation buys nothing and reads to a user as a rendering defect — it was spotted in PR #120's screenshots as "Quarter Pag". render.rs now asks plain_label, which is the other vocabulary already on Axis: the decision stays in the shared layer and only the choice of vocabulary is local, exactly the AxisColor → ratatui::Color shape §5 blesses. short_label is untouched, because the TUI's width is load-bearing.

Where the truncation was actually pinned is the useful part. The ticket says to check tests/grid_frame_agreement.rs first, in case it fixes the tile bar's vocabulary. It does not mention the tile bar at all. What held "Quarter Pag" in place was harness/tests/drill.spec.js, which asserts the tile's text exactly — a Playwright spec in a directory the ticket never names, asserting the bug as its expected value. A rendered string is pinned wherever anything reads the screen, so the search is for the string, not for the function that makes it.

The keyboard

Client::on_key_event classifies the event and folds it locally where this client may answer it — text entry, and since improvise-bpq2 the grid, panel and tile cursors too, which is why sendViewport must call set_viewport and not Client.viewport. Anything it cannot answer becomes a ClientFrame::Key, which Host::handle answers with an empty vec: those keys are sent and do nothing. That is settled rather than unfinished — the host must not know the keymap — and closing one means teaching the client, not that arm.

The page does not claim a key it did not answer: a frame means the page claimed it, so the browser must not also act on it — an arrow that both moves the cursor and scrolls the page is the worse of the two errors. Combinations under Ctrl or Alt are left alone regardless: those are the browser's own shortcuts, and the client resolves nothing under them. BrowserKey drops anything held with the platform meta key precisely so Cmd-R does not arrive as a bare r; the page does not claim it either.

The deployment notice, and the one thing this page remembers

#backend-notice is a <details>. The collapsing is therefore the browser's — keyboard operable, and correct with app.js absent, still loading, or thrown — and the only thing the page adds is remembering the answer. That split is the whole design: a static notice is what it was, and a notice whose open state is decided in JavaScript would be a fourth thing that can be wrong on a page whose job is not to be wrong about its own peer.

It starts collapsed for a visitor who has never answered, and the argument is that collapsing withholds nothing. The one fact a first-time visitor needs — the document lives in this tab, is saved to this browser's private storage, and never leaves the machine — is the <summary>, which never collapses. What is behind the disclosure is ?doc=, ?seed=, ?ws=, the wss:// default and the reverse proxy a plain-ws:// server needs: configuration reference, looked up rather than read, and irrelevant until a visitor has decided they want a second document or a shared one. Expanded, it cost about 230px of an 820px window and pushed the tile bar, the category tree and the grid below the fold on every visit. The page is an application; it should open as one.

The state is read through shell.js and stored in app.js, on the usual split: what a stored value means is a decision and is noticeOpen, while touching localStorage is a browser API and stays in the page. localStorage throws in a private window and in a context with site data blocked, and returns null having simply forgotten, so every access is wrapped and there are exactly two recognised spellings. Everything else — absent, empty, a value an older page wrote — is unanswered, which is the default rather than a third state: a page that treated forgetting as its own case would have to decide what to do about it, and there is nothing to decide.

What is stored is per-viewer and per-origin by construction. It never reaches Rust, never crosses to a peer, and is not state the application has any opinion about — which is exactly the class browser storage is for, and exactly why it is not a ViewState field (gotcha 30).

The page's own keydown listener must not claim the summary's keys. Enter is claimed by the client (it is forwarded upstream), and the listener calls preventDefault() on anything claimed — so without an explicit guard the disclosure would open by pointer and be dead by keyboard, which is the whole reason for using <details> rather than a <button> and a class. The guard is the same shape as the inline editor's: the control that has focus owns its keys.

Where the minibuffer is drawn, and why that is not a second derivation

The TUI draws the minibuffer on the bottom line, instead of the status line. The browser has always drawn it in its own element, because #status carries the transport's failures and a repaint must not erase one (gotcha 48) — but it drew it as a 14px line in the page's bottom-left corner, which in a terminal is a convention with decades behind it and in a browser window is where nothing is read. With the grid scrolled, the cell being typed into can be 800px from the text showing what is being typed.

So it is now a raised bar: fixed, centred over the grid, larger, bordered in the mode's own colour and shadowed. Every part of that is paint. The content is RenderMinibuffer, built in render.rs from state.view.mode.minibuffer() — the same semantic value the TUI reads — and the colour is MinibufColor resolved to a concrete colour exactly as draw.rs::minibuf_fg resolves it for the terminal. Nothing here asks which mode is open, which buffer is being typed into, or what the prompt says; a second answer to any of those is the disease design-principles §5 is about. The caret is drawn as a CSS ::after rather than appended to the text for the same reason: the text is the host's, and the page adds nothing to it.

pointer-events: none is load-bearing — the prompt floats over #grid, and one that ate a click meant for a cell would be a new bug introduced by paint. Since improvise-n6t8 it sits on #bottom-dock rather than on #minibuffer itself, because the dock is now what covers the grid; the property is unchanged and the declaration moved up one level rather than being duplicated.

The bar is reserved, not fitted, and the toast is out of flow (improvise-n6t8)

The user's report was two symptoms and one rule. The symptoms: "the top bar jumps around a lot" when a message arrives, and "the normal/categories/etc. pill changes sizes constantly". The rule, which is the deliverable: "there shouldn't be motion of layout elements I expect to be fixed."

Four things in <header> were sized by their own content, and they compounded, because they all change on the same event. #mode is help::mode_label, and NORMAL, CATEGORIES and NEW CATEGORY are 6, 10 and 12 characters. #hint is help::hint_line, one line per mode. #doc-name gains and loses [+] on every edit. #view-name had :empty { display: none }, so it appeared out of nothing on the first frame. So the bar reflowed on a mode change with no message at all, which is why a toast alone would not have fixed the complaint.

The answer is a reserve: every child that changes with the user's own keystrokes has an allocated width, and #hint is the single elastic child, so nothing is positioned by it.

The mode pill's reserve is a floor and deliberately not a cap, and that is the part worth carrying. min-width: 21ch holds sixteen characters where the longest label today is fourteen (RECORDS INSERT) — but a width or a max-width would absorb a seventeenth character silently, by overflowing inside a box that never grows. A floor lets an over-long label push the bar, which is the only thing a bounding-box measurement can see. A reserve that caps is a reserve that hides its own failure.

That matters because of where the seam is. AppMode's per-variant facts are exhaustive-match methods, so the compiler makes you write mode_label for a new variant — and nothing anywhere checks that the CSS still fits what you wrote. harness/tests/header.spec.js is that check, and it is the deliverable as much as the stylesheet is.

The status line was the compounding one, and it was not the pill. #status was flex: 0 1 auto beside a flex: 1 1 auto hint, so a longer hint took the shrink out of #status, which wrapped to a second and then a third line and grew the whole header by a row. This was not predicted; the spec found it on its first run. The fix is flex: 1 1 0 on the hint — from a zero basis it absorbs the remainder and contributes nothing to the overflow — and white-space: nowrap plus flex: 0 0 auto on #status, because a second line there is a taller bar, which is the one thing this whole section exists to prevent. app.js puts the whole text on title, so the max-width backstop loses nothing.

The two status facts now go to two elements, and composeStatus is gone. #status carries the transport's fact alone — "in-page worker", "connected", "disconnected", "cannot reach …" — which is not transient and never auto-hides. ViewState::status_msg is the toast's. That is a stronger form of the rule gotcha 46 records than the · join was: a repaint reaches createShell's onModel and cannot address onShell at all, so a connection error cannot be erased by construction rather than by a convention the join kept. The join's own unit test was replaced rather than deleted — a separation with no guard is how one silently regresses into a single sink.

The toast is out of flow entirely. #bottom-dock is position: fixed, so nothing inside it can push the header or the grid, and it is anchored at its bottom and stacks upward. That is what answers "what happens when the minibuffer and a toast coincide": the minibuffer sits exactly where it sat, the toast appears above it, and the prompt is neither covered nor displaced. A top-anchored stack, or a toast positioned by an offset from the minibuffer's height, would both have moved the prompt.

Dismissal keys off message identity, and two identical messages show once

This is the trap, and a timer alone walks straight into it. ViewState::status_msg is state, not an event: repaint() calls shell.setModel(model.status) unconditionally, and it runs on every revision bump — which is every keypress that moves anything. Nothing in Rust clears the string; it is replaced only when a later command sets one. So a toast hidden by setTimeout resurrects the moment the user touches the keyboard, which is worse than a message that simply stays, because it reads as a new event.

createToasts therefore keeps what it last accepted, and keeps it after the toast hides. An offer equal to it is recognised as a repaint and dropped.

The cost is stated rather than hidden: two identical messages in a row show once. Pressing : twice re-shows nothing. That is a real miss, and it is forced, because the browser cannot distinguish the two cases — nothing in the projection stream carries a sequence or a timestamp beside status_msg, and model.revision moves for a cursor key as readily as for a re-issued command. Given an ambiguous offer there are two choices, and only one of them does not reintroduce the reported bug: showing it again is exactly the resurrection. Making both show is a protocol change — a sequence number beside the string — and that is the thing improvise-n6t8's scope deliberately forbids, because the TUI draws status_msg in a bottom bar where it costs no layout at all and nothing here forecloses the split later.

Note what the toast does not do when it hides: it does not empty itself. The element is the record of what was last said, and drill.spec.js's discrimination between two refusals — > must not talk about aggregates — reads that text. An emptied node cannot tell "nothing was said" from "something else was said", and the assertion would pass vacuously the moment the timer fired.

What the styling is, and what no test here can see

web/style.css stopped being "legibility only" and is now a small design system: layered surfaces, one accent, a filled badge for the mode (the single most consequential fact on the page, since every key means something different in each), chips for the two axis strips, and one selection treatment used everywhere a selection can occur. The palette is deliberately the landing page's (docs/index.html), so the two read as one product.

Two things in it are worth naming because they look like derivations and are not. The selected row's header lights up through tbody tr:has(td.selected), which is the selection already decided in Rust being read off the DOM by the stylesheet rather than the page working out which row is selected. And .notice-toggle's glyph is chosen by [open], which is the one piece of state on this page that genuinely is the browser's and that nothing else knows.

One rule in it is load-bearing and is the stylesheet's own failure mode. td.error is the only place on this page where colour carries meaning rather than emphasis — a circular reference or a mixed aggregate reading as an ordinary number is worse than it reading as nothing. It used to coexist with the dimming of unsettable cells because they set different properties (color against opacity); once both are color at the same specificity, only source order separates them, and nothing in any language fails when the order is wrong. So the dimming sits above the semantic colours, and a selection is a ring and a tint and never a colour. That is the class of defect a stylesheet has and a program does not, and it is why the one assertion this file makes about colour is about which rule wins rather than about a value.

The harness cannot see most of this, and that is the honest scope. Playwright asserts what a browser can answer: that the notice starts collapsed and remembers, that it opens from the keyboard, that the minibuffer is inside the viewport, overlaps #grid and is larger than body text, that an error cell wins the cascade — and, since improvise-n6t8, that the app bar holds still across every mode the browser can reach. That last one is the first assertion here about layout rather than about one element's placement, and it is the shape to imitate: it measures bounding boxes, which a browser can answer exactly, rather than asking whether the page "looks stable", which it cannot.

What it still cannot see: colour, contrast, spacing, weight, the grouped or multi-level header DOM, and either theme — prefers-color-scheme is not exercised anywhere, so the dark palette is read and looked at and never run. So the rest of the styling is argued and not tested, on the same terms as the rest of this section, and a change to it is reviewed by reading and by looking at the page.

---

web/worker.js — the worker half

It hosts the authoritative App. Everything it decides is decided in Rust — the file only moves strings between self.onmessage/self.postMessage and WorkerServer::on_message, which is the same shape web/app.js has on the main thread and for the same reason: the less JavaScript there is, the less can be silently wrong.

Two rules it must not break:

1. Post every reply, in the order the Rust returned them, one message per frame. A GridUpdate::Cells that overtakes the labels framing it is DROPPED by the client's fold, not replayed. Never batch two calls' replies together and never reorder them.
2. Await flush() after each message. Storage::delete is visible to read/list immediately but only reaches OPFS there.

Rule 1 is about frames within one call's replies AND about the calls themselves, which is why every message is chained onto one tail promise rather than handled by an async listener: an async listener does not serialize. The event loop is free to start the next message while an earlier one is suspended at an await, so two on_message/flush pairs interleave and a later frame's replies can be posted before an earlier frame's. The chain is also what makes "frames that arrived before start() finished" an ordinary case of the same rule instead of a second code path with its own drain loop — and that loop had the race in it twice over, since server was set before it ran.

The chaining itself is web/serial.js::serialize, which is promise plumbing and nothing else, so web/tests/serial.test.js can force the interleaving a browser cannot be asked to produce on demand — including the negative arm, which runs the same two handlers without the chain and shows them coming back swapped.

The document is named in the worker's own URL — new Worker('worker.js?doc=demo.improv') — the analogue of the socket server naming it in the ws:// path. It is deliberately not a ClientFrame: the envelope pair is shared with the socket deployment and stays exactly as it is (improvise-xks6). The seed is fetched and handed to Rust, which writes it through the VFS and then reads it back like any other document — not injected past storage. A missing seed is not an error: with none, the worker creates an empty model under DOC.

An unhandled rejection inside a message listener reaches the devtools console and nothing else, so it is caught there — naming which frame it was, which the main thread cannot see and has no way to ask — rather than left on the chain, where one bad frame would poison every later one.

---

docs/ — the landing page and its casts

The casts are recorded by a script, not by asciinema rec

docs/record-casts.py drives improvise on a pty it owns and writes asciicast v2 itself. asciinema rec records a shell, and the shell it records is the recorder's own: every previous cast opened and closed on (0) Mac:<hostname> ~gf/u/edwlan/improvise, on what improvise-kh8 had since made the site root, and formulas.cast and import.cast showed that prompt as their visible opening frame (improvise-2oxt).

The repair is structural rather than careful: improvise is the pty's only child, so there is no shell for a prompt to leak from — nothing to remember to clean, and nothing that comes back when somebody re-records on a different machine. Three other things stopped being accidents at the same time. The geometry is an input (120×37, the numbers docs/index.html already spelled, which is why they were not changed — a 30-row player over a 37-row cast clips the tile bar and the status line, exactly where the output is). The pacing is a per-step table rather than typing speed. And the header carries no env and no timestamp: the first held $SHELL, the second the recording machine's clock, and neither is anything a visitor is owed.

Two decisions inside the scripts that are not obvious and cost a re-record each:

• No :q is typed at the end. The player loops, so the last frame is also the frame before the first, and a minibuffer reading :q is what it would show. The process is signalled instead.
• Each scenario has to be arranged so the thing it names is visible. The drill cast drilled into a cell with no records behind it — a true frame about nothing — so it now moves Customer off the page axis first, which makes the cell an aggregate over nine customers and gives the records grid more than one row. The pivot cast pressed c on a category that was already on the column axis, which is a no-op with a status line. Neither was visible from the keystrokes; both were found by rendering the recording back and reading it.

That last point is the method, and it is reusable: a cast can be replayed through a small ANSI reconstruction and read as text, so "what does frame N actually show" is a question with an answer rather than a guess. It is how the +cat and + columns in drill.cast — improvise-2oxt's substantive complaint, since the old recording predated both — were confirmed present.

What the harness can check, and does: landing.spec.js asserts over the cast files that no header carries env or timestamp, that the geometry is the one the page configures, and that no chunk contains an OSC window-title sequence, which is the leak's signature — improvise emits none and a shell emits one per prompt, carrying the cwd. Asserted over the file rather than the rendering because that is where the leak lives: a player draws a prompt as ordinary text, and a screenshot assertion would have to know what the hostname had been.

---

harness/ — the browser instrument

Why it exists, and what belongs in it

Before harness/ there was no JavaScript test infrastructure in the repository at all — no package.json, no runner, nothing in CI running a single line of web/app.js or web/worker.js — so every bug in them was found by reading and the bug-first rule could not be honoured for a change to either. PR #21 declined to add regression tests for its close-listener fix on exactly that ground, and that decline is only honest because those assertions live here instead.

Playwright rather than a headless-DOM runner because what goes wrong in these files is a real Worker, a real WebSocket, real OPFS and real event ordering, none of which a DOM shim has. That still holds, and it is why no shim was added; what changed is the scope — see the section below, which is now the answer to "where does a change to web/*.js belong". It is deliberately small (improvise-vvl3): the point is to be able to run storage_contract against OpfsFs and to read #status out of a real page, not to grow a second test framework beside cargo test. The server root is harness/serve, built by build.sh — the assembled site plus the harness's own page; a module script will not load from file://, so an http server is not optional.

Engine coverage

improvise-xf1's acceptance criterion names Chrome, Firefox and Safari, and the OPFS spec is the reason: createSyncAccessHandle is the one API the whole design rests on, its sync read/write/truncate signatures were added later than the handle itself, and each engine implemented it separately. Chromium alone would be one engine's opinion.

Result today: Chromium and Firefox run the whole battery and pass. Playwright's WebKit provides no OPFS at all — getDirectory() itself rejects with UnknownError — so Safari is NOT covered and xf1's criterion is met for two engines of three. The project is kept rather than deleted so that it starts running the day that build gains OPFS; opfs.spec.js skips on a runtime probe, not on the browser name, so if Chromium or Firefox ever stops providing OPFS it fails rather than skipping. An unexpected skip on any other engine is a failure — a silently skipped check is exactly what this harness exists to prevent.

The shell spec's mocked-peer block is Chromium-only on purpose: it is about web/app.js's own logic, which is engine-independent, and routeWebSocket is slower and flakier to no benefit across three. That argument is about those four tests and was never made about the two beside them: the standalone block mocks nothing, it is the deployment improvise-bck's criterion (1) names in so many words ("Chrome and Firefox"), and the engine's OPFS is already exercised by opfs.spec.js, so the path is known to be there. It runs on Firefox too since improvise-zkkw — testMatch widened, grepInvert: /@mocked-peer/ — measured at 2.0s for the pair and 10/10 green under --repeat-each=5. The split is a tag rather than a third copy of the file, and widening the whole file and then quieting what flaked would be adopting a reason nobody gave.

Every other spec is Chromium-only, including the three added by improvise-plcx, 78v6 and bgtf: a fixture document, a help overlay and a landing page decide nothing per engine.

harness/opfs-contract

A harness crate, not part of the application: it ships in no bundle and is not a workspace member. OpfsFs had been compile-checked and never run; this is the instrument that changed that (improvise-vvl3, absorbing improvise-xf1).

Why a worker. FileSystemFileHandle.createSyncAccessHandle() exists only in a dedicated Web Worker, and it is the whole reason Storage could stay synchronous. A check that ran on the main thread would fail for a reason that has nothing to do with OpfsFs.

Why a report rather than a panic. Every check runs and its outcome is reported, so a failure names which step and the rest still run. More importantly it is what lets the spec check the checker: Playwright asserts the report contains exactly the checks it expects, so a worker that never started, or a build that dropped a check, is a failure rather than a silent pass. The list of expected check names is spelled in opfs.spec.js as well as in Rust on purpose: a check deleted on one side has to be deleted on both, which is what stops the battery quietly shrinking.

wipe uses only the backend's own vocabulary — refresh, delete, commit_deletes — rather than reaching for removeEntry directly, so a broken delete shows up there as well as in the contract. It therefore cannot clear a zero-byte entry, because list no longer names one. That is deliberate and costs nothing: attach recreates and write fills whatever a previous run left behind, and a leftover empty entry is invisible to every assertion for the same reason it is invisible to a document picker.

opfs_root/make_directory exist only in the harness: OpfsFs has no directory vocabulary at all — it stores one flat entry per document — so making a directory, to check that refresh skips one, has to happen outside it.

---

Where a change to web/*.js is tested

E2E and integration tests are rare and pin boundary contracts; unit tests assume those contracts and test between them. (User ruling, 2026-09-20.) So the question is not "can this assertion be made cheaper" but "which boundary is it about", and the browser half has seven:

boundary	the contract	where it is pinned
RenderModel → DOM	every field the render model projects reaches an element	web/tests/render_surface.test.js (statically) and harness/tests/contract.spec.js (on the screen)
JS → wasm	the calls the page makes exist, with the arity the bundle declares, and their answers are painted	web/tests/bundle/wasm_surface.test.js (the surface) and contract.spec.js's pointer test (the wiring)
page → peer	the handshake goes out first, a frame is answered whole, a failure is named, and the page routes each failure through the call that disarms the watchdog	harness/tests/shell.spec.js, harness/tests/drill.spec.js
key → screen	a key the mode's hint line ADVERTISES produces something the user can see, and a text-entry mode paints what is typed into it	harness/tests/keys.spec.js
help::pages() → DOM	the overlay's rows are the shared content — the keys off the keymap and the words beside them — and not the right number of blank rows	harness/tests/help.spec.js
worker → OPFS	storage_contract, run against a real OpfsFs	harness/tests/opfs.spec.js
AxisFrame → DOM	the grid's frame — header levels, group spans, the collapse indicator and the group row that carries no cells — is drawn as the frame says, not slash-joined	harness/tests/grouped.spec.js, over harness/fixtures/grouped.improv; web/tests/grid_plan.test.js pins the plan it draws from
the site → the app	the landing page's casts are really fetched and really play, and its front door reaches ./app/	harness/tests/landing.spec.js

A unit test of a rule does not test the wiring that reaches it, and the sharpest case in this file is the watchdog. shell.test.js proves that createShell.fail() disarms rather than pre-empts; it cannot prove that app.js's socket close and error listeners call fail() rather than setShell(). That routing is PR #21's other half, the one gotcha 48 says keeps getting lost — and PR #61 lost it a third time by keeping the unit test and dropping the browser assertion, with 26/26 and 13/13 green. Restored, and the rule generalises: when a unit test replaces a boundary test, ask which of the two the regression would have been in. Here it is the routing, so the guard stays in Playwright.

The faked clock is faithful outside the window and silent inside it. shell.spec.js walks past the 8s handshake watchdog with page.clock, and the question that owes an answer is whether collapsing ten seconds into one synchronous step flattens an ordering rather than merely skipping the wait. Probed for the sharpest case — a peer that opens, stays silent past the window and is closed afterwards — the #status transcript is byte-identical under the fake clock and under a real nine-second wait: four states, same order, same text. What that does not cover is an event landing strictly inside the collapsed window, which a synchronous runFor gives no opportunity to deliver; that is a race whose outcome the page does not promise, so there is nothing to assert. State it rather than re-derive it.

A negative assertion must demonstrate the denied event is reachable on that exact code path — not on a sibling path, and not in the rule's own unit test. This file's worked example cost four review rounds. shell.arm runs only after await transport.ready, so on a socket that never opens the watchdog is never armed; a test denying "sent no document" there denies nothing, and passed against both the routing revert and the disarm regression. outlastTheWatchdog now asks the page timesArmed() > 0 first, which turns that review finding into a failure by name. Note ever armed and not armed now: a correct page has already disarmed by the time the disconnect test jumps — that is the property — so the obvious spelling would have denied the passing case.

And a constant a test must exceed has one home. HANDSHAKE_TIMEOUT_MS lived in web/app.js and again in the spec, under a comment saying a silent disagreement "would pass for the wrong reason". It did: the spec at 1000 against the page's 8000 made the suite green over the reverted routing, because the jump landed inside the window. It is exported from web/shell.js and imported by both, so the disagreement is unconstructible rather than discouraged.

Everything between those seams is node --test web/tests, and it may assume the boundary holds rather than re-establishing it: transport selection from ?ws=, the two facts #status composes, the watchdog's arm and disarm, the frameCost/extent arithmetic, the collapse glyph, the grid's plan, and the worker's tail-promise ordering. None of it needs a DOM, so none of it is Playwright's.

The seam that makes this possible is web/shell.js and web/serial.js: pure modules that return a description rather than take a DOM double. gridPlan(model) answers every question gridTable used to answer while it was creating elements — which row index a click carries when group headers are interleaved, what a group header spans, whether a null group label is a name, whether an empty edit buffer means an editor is open — and app.js is then a loop that creates elements from it. Painting stays untested by Node; the decision about what to paint stopped being untestable.

Why the four widgets were one bug

The tile bar, the view list, the formula panel and the category sidebar ignoring category_panel_open were reported as four broken features and fixed as four. They were one failure at one boundary: a RenderModel field with no element painting it. Four per-feature specs cost four page loads and catch the fifth only if somebody writes a fifth spec; one assertion that every projected field is painted catches it by construction. That assertion is cheap enough to make twice, from different sides:

• render_surface.test.js reads the pub fields off improvise-wasm-client/src/render.rs and requires each one to be read by app.js or shell.js — or named in UNPAINTED with a reason. It needs no browser, no bundle and no build, so it fails in seconds. The list is not an escape hatch: it is the debt, written down, and it currently holds doc_name/doc_dirty/doc_stored_as (improvise-5jna — the fifth instance, found by writing this test).
• contract.spec.js drives the demo document into each state that fills a widget and asserts the element is on the screen. Node cannot see that, and the moment a reduction would have to weaken it, it stays here.

And the static half is weaker than it reads, which is worth knowing before leaning on it. render_surface.test.js asks whether the string model.<field> occurs anywhere in the page's code — so a field mentioned by a function nothing ever calls passes. That happened on improvise-fdt6: the new minibuffer field had a paintMinibuffer reading it, and the call site and the getElementById were both missing, so the node suite went green over a page that still painted nothing. keys.spec.js failed on its first run, in Chromium, naming the hidden element. The static check is a completeness check — it tells you a field was not forgotten — and never an execution check; only harness/ is that (gotcha 48).

What is deliberately not in Playwright any more is what each key or click means: improvise_protocol::resolve decides that and its tests are where the meaning is pinned. One instance of "a resolved change repaints" is kept, because the repaint is the boundary; the other seven were the same instance again.

Two numbers, and neither is the other

Measured on one machine, in one session, on a private IMPROVISE_HARNESS_PORT, with both trees clean — 1af51c9 reached by a full checkout rather than by restoring paths over a working branch (see the trap below). Two runs each; the pair is the variance.

suite	chromium	all projects	execution	whole job
Playwright, before (1af51c9)	23	26 passed + 3 skipped	36.2s / 36.3s	~4m30s in CI
Playwright, after	14	17 passed + 3 skipped	15.1s / 14.9s	~4m30s in CI
Playwright, + wave 4	21	26 passed + 3 skipped	34.4s / 33.7s	~4m30s in CI
node --test web/tests	—	26	0.12s	seconds

The last row is improvise-78v6/igxp/plcx/bgtf/zkkw: seven more Chromium tests and two Firefox ones. Most of the 19 seconds is one test — the landing page's four asciinema casts are played until each terminal draws, which is the only assertion that can tell a cast from a 404 (evidence file). The Firefox pair is 2.0s of it.

Two columns because one number was ambiguous three times. Firefox runs opfs.spec.js and the standalone half of shell.spec.js and every other spec is Chromium-only, so a count taken off a run is five larger than the chromium count, with three more skipped (WebKit's OPFS battery). The columns must also agree: chromium + 3 is the passed total, and a row where they do not is a row built from two different trees. npx playwright test --list prints the per-project truth; quote which one, and this is the same "two numbers, not one" the Rust suite learned in design-principles.md §7.

The trap that made the first before figure wrong. It was taken by git checkout 1af51c9 -- harness web inside a working branch — which restores tracked files and leaves untracked ones where they are, so the branch's own contract.spec.js stayed and the "baseline" ran main's 23 tests plus three of the branch's. A baseline taken by checking paths out over your own work measures a tree that never existed. The full checkout above is the repair.

What gave it away was the count, not the clock — and that is the lesson. The contaminated run read 29 passed where a clean 1af51c9 reads 26, because three extra tests really were there; but it read 36.9s against the clean tree's 36.2s, because those three cost under a second between them. A wall clock absorbs a contaminated tree without a trace; an arithmetic identity does not. The same error survived three separate corrections — it reached PR #61's body as "26 chromium" (23 + the 3), survived a fix that corrected the chromium column and left the run count beside it, and was caught each time only by someone checking that the columns add up.

Where the saving actually came from, since the obvious answer is wrong. The eleven per-widget tests that were deleted cost 2.7 seconds of test time between them — restored verbatim and re-measured — against 1.55s for the three contract tests replacing them. Those are the per-test sums, not the two wall clocks, which read 3.3s and 3.4s and flattered the replacements: they were separate npx playwright test invocations, so each paid its own cold start (~0.6s and ~1.9s) and a near-tie appeared between two things not measured the same way. Warm inside a full suite those three cost under a second, which is why the contaminated baseline's clock barely moved.

Eleven tests at 2.7s cannot buy a twenty-second saving, and they did not. Essentially all of 36.2s → 15s was two shell.spec.js tests that waited out the 8s watchdog in real time, and one of those two was the routing guard this section explains should never have gone. So the deletion of the eleven bought shape, not speed; the speed came from a deletion that cost coverage. Both are back at ~75ms each, because page.clock fakes the page's timers — the honest version of the trade: the wait was the cost, not the test.

Cutting Playwright tests barely moves the CI number in any case, because roughly four minutes of that job is three wasm-pack builds, npm ci and a browser download — not test execution. The feedback-time win is the js job, which needs no Rust toolchain and no wasm bundle at all, and that is a constraint rather than an accident: the moment a web/tests/*.test.js file needs web/pkg/, it inherits the four-minute build and the argument for it evaporates. That is why the one test that does need the bundle lives in web/tests/bundle/ and runs in the browser job instead.

Until improvise-4ktt the mechanism was a directory convention and a glob, and nothing checked it. bundle_freedom.test.js does now: it reads its own sibling files and refuses one that names the bundle directory, and its companion asserts web/tests/bundle/ still holds a test that does — a scoping rule is uninteresting if nothing falls outside it. Evidence in context/test-evidence/tooling.md.