Skip to content

[M11] Web app scaffold and Pyodide worker bridge (M11.2) - #91

Merged
ssoufii merged 2 commits into
mainfrom
auto/m11.2-web-scaffold-pyodide-bridge
Nov 16, 2026
Merged

ssoufii merged 2 commits into
mainfrom
auto/m11.2-web-scaffold-pyodide-bridge

Conversation

@ssoufii

@ssoufii ssoufii commented Nov 16, 2026

Copy link
Copy Markdown
Owner

web/ is a Vite + React + TypeScript app that boots the repository's own Python engine in a Web Worker through Pyodide, behind a typed bridge. The page is deliberately plain: the design is M11.3.

What changed

  • web/package.json: exact pinned versions (vite 8.3.5, react 19.3.1, typescript 6.0.3, eslint 10.14.0, typescript-eslint 8.72.0, @playwright/test 1.63.0, pyodide 314.0.7) with package-lock.json committed, and scripts dev, build, preview, lint, typecheck, test, plus sync-assets wired to predev and prebuild.
  • web/scripts/sync-assets.mjs: copies the pinned Pyodide runtime (pyodide.mjs, pyodide.asm.mjs, pyodide.asm.wasm, python_stdlib.zip, pyodide-lock.json) and every src/ledgerlog/*.py into web/public/, writing a manifest with each module's size and sha256. Nothing is fetched from a CDN at runtime, and the copies are generated, so they are gitignored.
  • web/src/engine/worker.ts: loads Pyodide from the copied runtime, writes the engine source into its filesystem, puts it on sys.path, runs session.py and then moves JSON strings. No engine behaviour lives in TypeScript.
  • web/src/engine/session.py: the only Python the demo adds. It opens LedgerLog("/data", fsync_policy="never", flush_in_background=False), encodes text to UTF-8 bytes and back, and returns ledgerlog.introspect output as JSON. Ruff-clean.
  • web/src/engine/bridge.ts and protocol.ts: the typed door (put, get, delete, flush, compactOnce, snapshot, reset) plus the TypeScript shapes of a snapshot, and a boot-status subscription.
  • src/ledgerlog/engine.py: LedgerLog.flush() freezes the active memtable and writes every frozen one out. Needed because flush_pending only writes tables the size threshold already froze, so a browser engine that never reaches the threshold had no way to flush. Seven pytest tests cover it, including one with a writer thread and a flusher thread.
  • CLAUDE.md web commands, docs/ROADMAP.md M11 bullet, story_contexts.md note.

Acceptance criteria

  • web/ is Vite + React + TypeScript with dev, build, preview, lint, typecheck and test scripts, exact pinned versions, package-lock.json committed
  • Pyodide comes from the pyodide npm package and is served from the app's own build output; a build step copies src/ledgerlog/*.py into the bundle
  • Pyodide runs in a Web Worker; web/src/engine/bridge.ts exposes the seven calls with typed results; the engine is built with flush_in_background=False and fsync_policy="never" on Pyodide's in-memory filesystem
  • A Playwright test against vite preview shows the engine boots within 30 seconds, a put then get round-trips, and the snapshot lists the key in the memtable
  • The web job in CI runs npm ci, lint, typecheck, build, npx playwright install --with-deps chromium and npx playwright test, and uploads web/test-results/ (added in Add Milestone 11 web demo stories, design spec, and merge-gate CI #89; this branch is the first to exercise it)
  • CLAUDE.md's Commands section lists the web commands

Decisions recorded

  • typescript is pinned at 6.0.3 rather than 7.0.2 because typescript-eslint 8.72.0 declares a peer range of >=4.8.4 <6.1.0, and npm refuses the tree otherwise. Linting the TypeScript is worth more here than being on the newest compiler.
  • @playwright/test is pinned at 1.63.0, the version whose browser build this sandbox already has, so the suite can be run locally as well as in CI.
  • Chromium is launched with --no-sandbox: both the CI container and this dev container run the browser as root, where Chromium's own sandbox cannot start.
  • The bridge is a module-level singleton. A component-owned worker would boot a second 9 MB interpreter under React StrictMode and throw a visitor's database away on unmount.

What ran locally

  • web/: npm ci, npm run lint, npm run typecheck, npm run build all clean; npx playwright test ran locally and passed, 6 of 6 against vite preview of the production build (the engine booted in about 2.5 s)
  • Python: pytest 1244 passed (7 new), ruff check src tests and ruff format --check src tests clean, and ruff check web/src/engine/session.py clean

Closes #80


Generated by Claude Code

web/ is a Vite, React and TypeScript app with exact pinned dependencies and a
committed lockfile. A build step copies the pinned pyodide package's runtime
and this repository's src/ledgerlog source into the app's own output, with a
manifest, so the page serves its interpreter and its engine itself and a
visitor runs the commit they are looking at rather than whatever a CDN holds.

A Web Worker loads Pyodide, writes the engine source into its filesystem and
runs web/src/engine/session.py, which opens a LedgerLog with
flush_in_background=False and fsync_policy="never" (Pyodide has no threads and
its filesystem is memory) and answers one JSON call at a time. The typed bridge
in web/src/engine/bridge.ts exposes put, get, delete, flush, compactOnce,
snapshot and reset, and is the page's only way to reach the engine, so nothing
about storage can be reimplemented in TypeScript. The page itself stays bare;
the design arrives in M11.3.

LedgerLog.flush() is new: it freezes the active memtable and writes every
frozen one out, which is the flush a caller asks for rather than the one a full
memtable causes, and is what a visitor pressing flush means.

Playwright runs against vite preview of the production build and covers the
boot inside thirty seconds, a put and get round trip, the key appearing in the
memtable with its tower level, the log record, a flush producing a table, and a
reset emptying the database.

Claude-Session: https://claude.ai/code/session_01QWNkuNaLsrxqkKrLQixfS5

Co-Authored-By: Claude <noreply@anthropic.com>
The CI web job timed out waiting for config.webServer: vite preview defaults
to the host name localhost, which binds IPv6 only where the resolver answers
::1 first, while Playwright polls 127.0.0.1. Bind and poll the same address,
and pipe the server's output so a server that starts without serving says why.

Claude-Session: https://claude.ai/code/session_01QWNkuNaLsrxqkKrLQixfS5

Co-Authored-By: Claude <noreply@anthropic.com>
@ssoufii
ssoufii merged commit 9d243f2 into main Nov 16, 2026
16 of 18 checks passed
@ssoufii
ssoufii deleted the auto/m11.2-web-scaffold-pyodide-bridge branch November 16, 2026 06:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[M11] Web app scaffold and Pyodide worker bridge (M11.2)

2 participants