diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-05 11:40:11 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-05 12:41:36 -0300 |
| commit | 3f1533813b6692a736251e4d467a7f108229ddee (patch) | |
| tree | 37a32c5ebbf9d3af08923856fd6fa516f3b33a39 /docs/web.md | |
| parent | cfd2b993feda1b3f7474225bb32db8cac8edc5ae (diff) | |
| download | pardes-3f1533813b6692a736251e4d467a7f108229ddee.tar.gz pardes-3f1533813b6692a736251e4d467a7f108229ddee.zip | |
targets: the DOM web shell goes (src/web.zig and src/web/, its harnesses web_harness, web_snapshot, web_driver_test and web-snapshots/, tools/web_fixture.py, -Dplatform=web, -Ddump, and the web, web-harness, web-snap, web-e2e and web-driver-test steps), and with it what only a freestanding build needed: `hosted` and every guard on it (every build has a host now), memory's stack-fallback arenas and reduced_target sizes, the emscripten main, the tree-sitter libc shim and the stb stub, lsp's has_client, the web arms of the platform switches (-Dplatform is tui, gui or macos); the macOS files pass zig ast-check; docs/web.md is a paragraph on what it was
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_016Y9MNAtZenFv4weoMD3cge
Diffstat (limited to 'docs/web.md')
| -rw-r--r-- | docs/web.md | 157 |
1 files changed, 14 insertions, 143 deletions
diff --git a/docs/web.md b/docs/web.md index 26646a38..9e064d6e 100644 --- a/docs/web.md +++ b/docs/web.md @@ -1,144 +1,15 @@ -# DOM web backend +# The DOM web shell (gone) -The web backend keeps the existing Pardes core and replaces the old -Emscripten/SDL/WebGL shell. Zig produces a `wasm32-freestanding` module whose -only imports are the four browser capabilities listed below — no libc, no WASI, -no runtime. JavaScript owns `requestAnimationFrame`, browser input and window -sizing; the CORE owns the loop and JavaScript calls one iteration of it per -frame. HTML and CSS render selectable, accessible text. There is no canvas. - -The default web build links Tree-sitter's C runtime and the Zig grammar inside -that same import-free module. A small freestanding compatibility layer supplies -the C ABI locally, so source panes retain the core's Tree-sitter highlighting -without Emscripten, WASI, or browser libc imports. Other grammar tiers remain -selectable with `-Dtree-sitter=minimal` or `-Dtree-sitter=full`. - -`src/web.zig` is the narrow WASM ABI. Events enter through exported functions -that hand them straight to `Pardes.update`. `pardes_tick` is one -`Pardes.pump` — queued input, effects, render, present — and the host's -`present` packs the canonical `Surface` into a 20-byte cell array that -`pardes_frame`/`_ptr`/`_cols`/`_rows` describe. `src/web/app.mjs` reads that -array in one linear pass and patches stable DOM nodes. - -Animated time is JavaScript's alone. `pardes_animation_tick` spends one fixed -60 Hz step and is the only entry that advances a transition, exactly as the -AppKit shell keeps its display clock apart from its pumps: if every input pump -also advanced a fade, a burst of keys would collapse ten frames into one. -`pardes_tick` never advances animated time itself, and no longer has to undo -anything to avoid it: `Pardes.pump` does not post a tick for its caller, since -only the host knows when a real frame interval has passed. - -Cell attribute bit 7 carries the core's tagline font role. The DOM keeps every -cell at the body grid's fixed width and height, but scales and centres the -tagline glyph using the build-time `gui_tagline_font_percent`; the percentage is -exported by the module rather than duplicated in JavaScript. Animation time is -also host-independent: `requestAnimationFrame` time is accumulated into 60 Hz -core ticks, so 120/144 Hz displays do not accelerate frame-count transitions -and a returning background tab has bounded catch-up work. - -The `web` platform is deliberately not one of the shader-capable native GUI -shells, and two comptime capability flags say so once each. It exposes no -`Panel*` transition builtins (`PanelSlide`, `PanelZoom`, `PanelDissolve`, -`PanelAscii`, `PanelVertical`, `PanelEdges`, `PanelFall`, `PanelWave`, -`PanelCurtain`, `PanelScramble`, `PanelType`) because -`capabilities.panel_transitions` is `pardes.hosted`, and no -`Crt` or `Shader` because `capabilities.scene_shaders` is -`platform == .gui or platform == .macos` (`builtins.capabilities`; the words -themselves carry those availabilities in `config.Runtime.settings`). -Applying either faithfully would require a second canvas renderer and give up -the DOM renderer's selectable/accessibility contract. Theme fades and the -delayed, side-effect-free Look hover remain grid animations and continue to use -the fixed 60 Hz ticks above. - -Build a replay from a dump: - -```sh -zig build web \ - -Dplatform=web \ - -Dtarget=wasm32-freestanding \ - -Dtree-sitter=zig \ - -Ddump=test/web-snapshots/touch.dump -``` - -The output is in `zig-out/web`. Serve that directory over HTTP; browsers do not -allow a useful WASM module load from `file:` URLs. - -The browser shell has no argv: every command-line flag `src/main.zig` parses — -`--tty`, `--tty-toggle`, `-n`, `-l`, `--9p=<name>`, `--mount=<name>=<dial>`, `--nested`, -`--detach[=<name>]`, `--attach[=<name>]`, `-h`/`--help`, `--version`, and the -positional file-or-directory — is native-only, because the wasm module roots at -`src/web.zig` and never links `main.zig`. State comes from the embedded dump -instead, and there is nothing here to answer `--version` with even though -`pardes.version` and `pardes.commit` are compiled in like everywhere else. - -Web LOOK's source archive follows Git's working-tree view: tracked `.zig` files -plus new, nonignored ones, sorted by path. The checked-in browser replay is a -real native TTY dump of that same selection; its top and bottom launcher -snapshots jointly cover the complete list before opening `build.zig`. - -What is genuinely absent is narrower than "no IO". The module has no threads -and no host filesystem, so there is no startup config directory, init file, -ThemeFile, or DumpThemes; LOOK resolves -against the build-generated source archive rather than disk, and no language -BACKEND is compiled in (there is none for wasm — which also means -`lsp.supports` is empty, so the core never even raises a language query there, -and the host leaves `lsp` null). - -Replay terminals retain the same core shape but use Zig's failing IO value; -this keeps the module freestanding without instantiating POSIX threaded IO that -the browser can never call. - -`Attach` and `Detach` are absent for the same structural reason and behind the -same gate: both are `enabled = pardes.hosted` (`src/builtins.zig`, and -`pardes.hosted` is `tty or gui or macos`), because a detached session is a unix -socket and a page has none. Nothing in this shell speaks -`src/wire.zig`, and `detach` is one of the null vtable methods -below. - -`src/web.zig` fills in six methods of `Host.VTable` and leaves the rest null, -and a null method is answered by the core itself rather than forwarded to a -page that could not honour it. The six are `present`, `write_file`, -`write_dump`, `set_clipboard`, `read_clipboard` and `open_link`; the last five -are backed by four imports from the module `pardes` that JavaScript supplies at -instantiation, because a written file and a written dump are both a download: - -| import | effect behind it | -|---|---| -| `host_open_link(url, len)` | `open_link` — `window.open` | -| `host_set_clipboard(text, len)` | `set_clipboard` — `navigator.clipboard.writeText` | -| `host_read_clipboard()` | `read_clipboard` — answered later, or never, by `pardes_paste` | -| `host_download(path, path_len, bytes, len)` | `save_file`, `save_text` and `write_dump`: a file a page writes is a download | - -What the core answers instead of asking: `spawn`, `pty_write` and `pty_resize` -land in the per-instance fallback, so a pane with no child is SILENT rather -than synthetic; `tty_taken` is never taken; any save the page declines resolves -against the core's virtual filesystem, which is also where every read comes -from — the core reads files itself and never asks a host; `watch_file` records -the request; `lsp` answers an empty row set at once (no backend is built for -wasm, so the core never raises a query there anyway) and `pipe` answers -failure; `wait_input` is null because wasm must never block, and `watch_theme` -and `dump_themes` are not reachable without a config directory. Of the -remaining nulls, `post_present` and `poll_frame` are per-frame host bookkeeping -a page has none of, `detach` has no session to leave, `gpio_toggle` belongs to -the ESP32-P4 board, and native filesystem replies are delivered by the 9P -listener. `quit` sets the -core's flag, which `pardes_should_quit` reports so the page can stop its frame -loop. - -Two dependency-free test layers cover the boundary: - -```sh -# Real WASM in Node plus a small DOM double. -zig build web-harness \ - -Dplatform=web \ - -Dtarget=wasm32-freestanding \ - -Dtree-sitter=zig \ - -Ddump=test/web-snapshots/touch.dump - -# Real headless Chrome, DOM rendering, and browser touch input. -zig build web-e2e -``` - -Set `PARDES_CHROME` when Chrome/Chromium is not on `PATH`, in a normal -Playwright/Puppeteer cache, or — on macOS, where a browser's executable lives -inside an application bundle and never on `PATH` — under `/Applications`. +pardes had a browser shell until 2026-11-05: the core built as a +`wasm32-freestanding` module rooted at `src/web.zig` (a handful of exports, +four imports, no libc, a C shim for tree-sitter), `src/web/app.mjs` +patching DOM cells from one packed cell array each `requestAnimationFrame`, +and a replay of an embedded dump with no ptys, no host filesystem, no +threads and no language server, under its own steps (`web`, `web-harness`, +`web-snap`, `web-e2e`, `web-driver-test`) that no gate ran. It went with +the ESP32-P4 board (`.scratch/clean-room/architecture.md` §9.3, §9.4 step +10): nothing used it, it rotted between fixes, and every build carried its +`hosted` guards, its freestanding arenas and its stb shim. The arch base +`qkvytkrn` is the last change with it, the place to start again from if +the website wants a replay viewer, or a freestanding build to prove the +core imports no I/O. |
