fiddlerwoaroof/improvise
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(web): the page spawns the worker, opens a demo, and reads a key

Browse Source 
Three pieces of the standalone deployment, all in web/.

improvise-djm — app.js picks its peer instead of assuming a socket. The
wasm bundle is the same artifact either way (improvise-xks6), so the
difference is confined to one factory: `?ws=` selects the websocket, its
absence spawns `new Worker('./worker.js?doc=&seed=', {type:'module'})`.
The websocket path is KEPT, because improvise-ws-server is how a
TUI-hosted document is shared and nothing else can reach it; the presence
of the parameter is the whole selection mechanism, since a second knob
naming the same fact is a second thing to get wrong.

improvise-bck — web/demo.improv, built against an assertion rather than
by flipping an axis. examples/demo.improv leaves Customer/Date on None,
so every cell is an Aggregate and nothing is editable. The new demo puts
exactly one category on each visible axis (Product on row, _Measure on
column, Quarter on page) and carries Profit = Revenue - Cost, so a
visitor sees the formula move beside the cell they typed in, with no
keystroke and no scrolling. Two tests hold it: tests/web_demo_model.rs
projects the whole grid through grid_of and asserts every CellId is
Record (ADR 002 — that is what `editable` means), and post_message.rs
drives the shipped bytes through the real seed -> VFS -> open -> Snapshot
chain. The first was proved discriminating by pointing it at
examples/demo.improv, where it names the aggregate at (0,0).

One category per axis is asserted too: GridCache slash-joins a
multi-level tuple (gotcha 44), so a second category on an axis puts that
known gap on the front page.

improvise-hwpi — all four. A keydown listener on window feeds
Client::on_key_event, so the classifier is reachable at last; a frame
that will not fold now writes to #status instead of only the console; the
socket has an error listener, so "not running" no longer reads like
"still connecting"; and close() has a re-entry guard. Plus one the ticket
could not have predicted: a worker whose start() rejects is caught inside
worker.js and fires no `error` on the main thread, so the same silence
was about to be rebuilt in the new path — a first-frame watchdog covers
both deployments, because "the peer never answered" is the one condition
that means the same thing on each.

Verified: cargo test --workspace 1159 passing (1155 + 4), clippy clean,
fmt clean, actionlint clean, ./web/build.sh end to end (345 KB / 123 KB
gzipped client, 1.33 MB / 498 KB gzipped worker), every call present in
the generated .d.ts with the right arity, every relative reference in the
assembled site resolving. NOT verified: there is no browser here. No line
of JavaScript in this commit has ever run.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EoW5BB87ZZdm96SvBTWawH
This commit is contained in:
Edward Langley
2026-09-19 19:28:21 -07:00
parent 4286bcc4fc
commit a550201fae
8 changed files with 448 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files
web/app.js
+181 -24
View File
@@ -1,24 +1,49 @@
// The browser half of improvise-cr3, kept as thin as it can be made.
// 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.
// Four calls are the whole harness —
// Five calls are the whole harness —
//
// Client.viewport(rows, cols) -> the handshake frame, and every resize
// client.on_frame(json) -> fold one socket 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.viewport(rows, cols) -> the handshake frame, and every resize
// 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
//
// — and 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.
//
// # 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 this directory a working application.
// ?ws=URL 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.
import init, { Client } from "./pkg/improvise_wasm_client.js";
const params = new URLSearchParams(location.search);
const WS_URL = params.get("ws") ?? `ws://${location.hostname || "127.0.0.1"}:8787`;
const WS_URL = params.get("ws"); // present => socket, absent => in-page worker
const DOC = params.get("doc") ?? "demo.improv";
const SEED = params.get("seed") ?? "demo.improv";
// Rough character metrics, used only to turn the window size into an extent.
// Being wrong here costs a row of over- or under-fetch, nothing more.
@@ -35,7 +60,19 @@ const el = {
await init();
const client = new Client();
const socket = new WebSocket(WS_URL);
// `#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.
let shellStatus = "";
let modelStatus = "";
function paintStatus() {
el.status.textContent = [shellStatus, modelStatus].filter(Boolean).join(" · ");
}
function setShellStatus(text) {
shellStatus = text;
paintStatus();
}
/** The extent this window can show, in whole cells. */
function extent() {
@@ -47,21 +84,110 @@ function extent() {
}
function sendViewport() {
if (socket.readyState !== WebSocket.OPEN) return;
const { rows, cols } = extent();
socket.send(Client.viewport(rows, cols));
transport.send(Client.viewport(rows, cols));
}
// A peer that never answers the handshake. The socket has an `error` event
// for this; 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 watchdog is deliberately about the *first frame* rather
// than about either peer's own failure modes: it is the one condition that
// means the same thing in both deployments.
const HANDSHAKE_TIMEOUT_MS = 8000;
let watchdog = null;
function armWatchdog(message) {
clearTimeout(watchdog);
watchdog = setTimeout(() => setShellStatus(message), HANDSHAKE_TIMEOUT_MS);
}
/** One frame, one fold, in arrival order. Never batch or reorder these. */
function onFrame(text) {
clearTimeout(watchdog);
try {
client.on_frame(text);
} catch (err) {
// `on_frame` returns a Result, which wasm-bindgen throws. Thrown in a bare
// listener it reached the devtools console and nothing else, and the grid
// simply stopped updating with nothing on screen saying why (improvise-hwpi).
setShellStatus("bad frame — the grid has stopped updating (see console)");
console.error("improvise: frame rejected", text, err);
return;
}
repaint();
}
// ── transports ───────────────────────────────────────────────────────────
/** The in-page worker: the standalone deployment, no server process. */
function workerTransport() {
const query = new URLSearchParams({ doc: DOC, seed: SEED });
// `type: "module"` is not optional: worker.js is an ES module (it `import`s
// the worker bundle), and a classic worker would fail to parse it.
const worker = new Worker(`./worker.js?${query}`, { type: "module" });
worker.addEventListener("message", (event) => onFrame(event.data));
worker.addEventListener("messageerror", () =>
setShellStatus("the worker sent a frame this page could not read"),
);
worker.addEventListener("error", (event) => {
setShellStatus(`worker failed to start: ${event.message ?? "see console"}`);
console.error("improvise: worker error", event);
});
setShellStatus(`in-page worker · ${DOC}`);
// Frames posted before the worker has finished `start()` are held by
// worker.js and replayed in order, so the handshake can go out immediately.
return { send: (text) => worker.postMessage(text), ready: Promise.resolve() };
}
/** A websocket to `improvise-ws-server`: how a TUI-hosted document is shared. */
function socketTransport() {
const socket = new WebSocket(WS_URL);
const ready = new Promise((resolve) => {
socket.addEventListener("open", () => {
setShellStatus(`connected · ${WS_URL}`);
resolve();
});
});
socket.addEventListener("message", (event) => onFrame(event.data));
// Without this, a connection that never opens left #status blank and
// "server not running" read exactly like "still connecting" (improvise-hwpi).
socket.addEventListener("error", () =>
setShellStatus(`cannot reach ${WS_URL} — is improvise-ws-server running?`),
);
socket.addEventListener("close", () => setShellStatus("disconnected"));
setShellStatus(`connecting to ${WS_URL}…`);
return {
send: (text) => {
if (socket.readyState === WebSocket.OPEN) socket.send(text);
},
ready,
};
}
const transport = WS_URL ? socketTransport() : workerTransport();
// ── painting ─────────────────────────────────────────────────────────────
let painted = -1;
let editing = null; // {row, col} while an input is open, so a repaint cannot steal it
function repaint() {
const model = JSON.parse(client.render_model());
if (model.revision === painted || editing) return;
if (editing) return;
let model;
try {
model = JSON.parse(client.render_model());
} catch (err) {
setShellStatus("cannot render the current state (see console)");
console.error("improvise: render failed", err);
return;
}
if (model.revision === painted) return;
painted = model.revision;
el.mode.textContent = model.mode;
el.status.textContent = model.status;
modelStatus = model.status;
paintStatus();
el.viewName.textContent = model.view_name;
el.grid.replaceChildren(gridTable(model));
el.categories.replaceChildren(categoryList(model));
@@ -114,13 +240,18 @@ function edit(td, row, col) {
input.focus();
input.select();
// Enter removes the focused <input>, which fires `blur`, which calls
// `close` again. Harmless before, but only by accident (improvise-hwpi).
let closed = false;
const close = (commit) => {
if (closed) return;
closed = true;
editing = null;
if (commit) {
const frame = client.typed_cell(row, col, input.value);
// null only if the grid moved under the editor; the repaint that
// follows restores whatever the server now says is there.
if (frame) socket.send(frame);
if (frame) transport.send(frame);
}
td.replaceChildren(original);
painted = -1;
@@ -130,6 +261,8 @@ function edit(td, row, col) {
input.addEventListener("keydown", (e) => {
if (e.key === "Enter") close(true);
else if (e.key === "Escape") close(false);
// The editor owns the keyboard while it is open; the page-level handler
// below must not also see these.
e.stopPropagation();
});
input.addEventListener("blur", () => close(false));
@@ -149,19 +282,43 @@ function categoryList(model) {
return list;
}
socket.addEventListener("open", () => {
sendViewport(); // the handshake: the snapshot is built at this extent
el.status.textContent = "connected";
});
// ── the keyboard ─────────────────────────────────────────────────────────
//
// `Client::on_key_event` classifies the event and folds it locally where this
// client may answer it (text entry, and nothing else — see keys.rs); anything
// else becomes a `ClientFrame::Key` for the peer to resolve against the real
// App. Until improvise-bpq2 lands, `Host::handle` answers that frame with an
// empty vec, so an upstream key is sent and correctly does nothing yet. That
// is a gap in the peer, not in this listener.
socket.addEventListener("message", (event) => {
// One frame, one fold, in arrival order. Never batch or reorder these.
client.on_frame(event.data);
window.addEventListener("keydown", (e) => {
// The inline editor owns the keyboard while it is open. It stops
// propagation, so this is belt and braces for a focus we did not predict.
if (editing) return;
// BrowserKey drops anything held with the platform meta key precisely so
// Cmd-R does not arrive as a bare `r`; do not claim it here either.
if (e.metaKey) return;
const frame = client.on_key_event(e.key, e.ctrlKey, e.altKey, e.shiftKey, e.metaKey);
if (frame) {
// A frame means the page claimed the key, 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 this
// client resolves nothing under them anyway.
if (!e.ctrlKey && !e.altKey) e.preventDefault();
transport.send(frame);
}
repaint();
});
socket.addEventListener("close", () => {
el.status.textContent = "disconnected";
});
// ── start ────────────────────────────────────────────────────────────────
await transport.ready;
sendViewport(); // the handshake: the snapshot is built at this extent
armWatchdog(
WS_URL
? `${WS_URL} accepted the connection but sent no document`
: "the in-page worker did not answer — this browser may not allow it (see console)",
);
new ResizeObserver(sendViewport).observe(el.grid);
web/build.sh
+9 -6
View File
@@ -22,14 +22,17 @@ wasm-pack build "$root/crates/improvise-worker-server" \
--target web --out-dir "$root/web/worker-pkg"
cat <<'MSG'
Built. To run the thin client against a real server:
Built. Serve the directory and open it — that is the whole application:
improvise-ws-server your-model.improv --port 8787
python3 -m http.server 8080 --directory web
then open http://127.0.0.1:8080/ (override the socket with ?ws=ws://host:port).
then open http://127.0.0.1:8080/. The document lives in an in-page Web
Worker and persists to this browser's private storage (OPFS). It is seeded
on first load from web/demo.improv; ?doc= and ?seed= name other documents.
worker-pkg/ is built and web/worker.js will load it, but nothing instantiates
that worker yet: the main-thread bootstrap that spawns it and wires the
MessageChannel is improvise-djm. Until then the worker bundle ships unused.
To point the same page at a separate server process instead:
improvise-ws-server your-model.improv --port 8787
then reload with ?ws=ws://127.0.0.1:8787.
MSG
web/demo.improv
+57
View File
@@ -0,0 +1,57 @@
v2025-04-09
# Corner Coffee — 2025
Initial View: Plan
## View: Plan
Product: row
_Measure: column
Quarter: page, Q1
_Index: none
_Dim: none
format: ,.0
## Formulas
- Profit = Revenue - Cost
## Category: _Measure
- Revenue, Cost
## Category: Product
- Espresso, Latte, |Cold Brew|, Pastry
## Category: Quarter
- Q1, Q2, Q3, Q4
## Data
Product=Espresso, Quarter=Q1, _Measure=Revenue = 18400
Product=Espresso, Quarter=Q1, _Measure=Cost = 6200
Product=Espresso, Quarter=Q2, _Measure=Revenue = 17100
Product=Espresso, Quarter=Q2, _Measure=Cost = 5900
Product=Espresso, Quarter=Q3, _Measure=Revenue = 15800
Product=Espresso, Quarter=Q3, _Measure=Cost = 5400
Product=Espresso, Quarter=Q4, _Measure=Revenue = 20300
Product=Espresso, Quarter=Q4, _Measure=Cost = 6900
Product=Latte, Quarter=Q1, _Measure=Revenue = 24600
Product=Latte, Quarter=Q1, _Measure=Cost = 9100
Product=Latte, Quarter=Q2, _Measure=Revenue = 23800
Product=Latte, Quarter=Q2, _Measure=Cost = 8800
Product=Latte, Quarter=Q3, _Measure=Revenue = 22400
Product=Latte, Quarter=Q3, _Measure=Cost = 8300
Product=Latte, Quarter=Q4, _Measure=Revenue = 27900
Product=Latte, Quarter=Q4, _Measure=Cost = 10200
Product=|Cold Brew|, Quarter=Q1, _Measure=Revenue = 9200
Product=|Cold Brew|, Quarter=Q1, _Measure=Cost = 3400
Product=|Cold Brew|, Quarter=Q2, _Measure=Revenue = 14600
Product=|Cold Brew|, Quarter=Q2, _Measure=Cost = 5300
Product=|Cold Brew|, Quarter=Q3, _Measure=Revenue = 17300
Product=|Cold Brew|, Quarter=Q3, _Measure=Cost = 6200
Product=|Cold Brew|, Quarter=Q4, _Measure=Revenue = 8100
Product=|Cold Brew|, Quarter=Q4, _Measure=Cost = 3000
Product=Pastry, Quarter=Q1, _Measure=Revenue = 11500
Product=Pastry, Quarter=Q1, _Measure=Cost = 5200
Product=Pastry, Quarter=Q2, _Measure=Revenue = 10900
Product=Pastry, Quarter=Q2, _Measure=Cost = 4900
Product=Pastry, Quarter=Q3, _Measure=Revenue = 10200
Product=Pastry, Quarter=Q3, _Measure=Cost = 4600
Product=Pastry, Quarter=Q4, _Measure=Revenue = 13400
Product=Pastry, Quarter=Q4, _Measure=Cost = 6000
web/index.html
+30 -27
View File
@@ -8,24 +8,28 @@
</head>
<body>
<!--
The browser shell for improvise-ws-server (improvise-cr3).
The browser shell (improvise-cr3, improvise-djm).
Deliberately three elements and no framework. Everything that could be
Deliberately four elements and no framework. Everything that could be
*wrong* — what a cell is, whether it may be typed into, where the
selection sits, how the category tree flattens — is decided in Rust and
arrives already decided (see `render.rs`). This page paints it.
Build the wasm module into ./pkg first:
Build both wasm bundles first:
wasm-pack build crates/improvise-wasm-client --target web --out-dir ../../web/pkg
./web/build.sh
then serve this directory over http (a module script will not load from
file://) and run the server beside it:
file://):
improvise-ws-server bank-info.improv --port 8787
python3 -m http.server 8080 --directory web
The socket address can be overridden with ?ws=ws://host:port.
That is the whole standalone deployment: the document lives in an
in-page Web Worker and persists to this browser's private storage.
?doc= and ?seed= name the document and the file it is first seeded from.
To talk to a separate `improvise-ws-server` process instead — which is
how a document open in the TUI is shared — pass ?ws=ws://host:port.
-->
<header>
<h1>improvise</h1>
@@ -35,29 +39,28 @@
</header>
<!--
This page is the *client* half and nothing else. It holds no model: what
a cell is, what it says and whether it may be typed into is decided by a
server and arrives already decided. So a copy served from a static host
— GitHub Pages included — paints an empty grid and says "disconnected"
until it is pointed at one.
This page is the *client* half and nothing else: it holds no model. What
it now has is a peer it can always reach — a Web Worker in this same tab
hosting the whole App over OPFS (improvise-9x6, improvise-djm) — so a
copy served from a static host, GitHub Pages included, is a working
application rather than a client with nowhere to connect.
Two servers are possible. `improvise-ws-server`, which exists, is a
native process you run yourself; pass its address as ?ws=ws://host:port.
The in-page worker (improvise-9x6), which does not exist yet, is what
makes this page standalone. Until it lands the honest description of a
Pages deployment is "the delivery pipeline, carrying a client with
nowhere to connect" — which is why this notice is static HTML rather
than something app.js decides: it is true on every load, and a page that
cannot reach a server cannot be trusted to explain why.
The notice below stays static HTML rather than something app.js decides,
for the same reason as before: it is true on every load in either mode,
and a page that cannot reach its peer cannot be trusted to explain why.
What the peer is actually *doing* — starting, connected, unreachable,
gone — is live, and app.js writes it to #status.
-->
<p id="backend-notice">
improvise in the browser is a thin client: the document lives in a
server. Run <code>improvise-ws-server model.improv --port 8787</code>
and reload with <code>?ws=ws://127.0.0.1:8787</code>. Served over
https, a <code>ws://</code> address is blocked as mixed content — use
<code>wss://</code> or a local http server. Running with no separate
process at all is the in-page worker (improvise-9x6), and it is not
built yet.
Everything here runs in this tab: the document lives in a Web Worker
and is saved to this browser's private storage, so edits survive a
reload and never leave the machine. Load a different document with
<code>?doc=name.improv</code>, seeded from
<code>?seed=url</code>. To open a document hosted by a separate
process instead, run
<code>improvise-ws-server model.improv --port 8787</code> and reload
with <code>?ws=ws://127.0.0.1:8787</code> — note that from an https
origin a <code>ws://</code> address is blocked as mixed content.
</p>
<main>