summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-05 11:40:11 -0300
committerGabriel Schneider <[email protected]>2026-11-05 12:41:36 -0300
commit3f1533813b6692a736251e4d467a7f108229ddee (patch)
tree37a32c5ebbf9d3af08923856fd6fa516f3b33a39 /docs
parentcfd2b993feda1b3f7474225bb32db8cac8edc5ae (diff)
downloadpardes-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')
-rw-r--r--docs/macos.md33
-rw-r--r--docs/shared-libs.md8
-rw-r--r--docs/typ/building.typ27
-rw-r--r--docs/web.md157
4 files changed, 44 insertions, 181 deletions
diff --git a/docs/macos.md b/docs/macos.md
index 5542ac14..9b8f82ec 100644
--- a/docs/macos.md
+++ b/docs/macos.md
@@ -6,7 +6,7 @@ hand-written C ABI, `src/macos/pardes.h`, built as a static library that the app
links; the Swift half is ordinary AppKit that pumps events in and reads one
packed cell buffer out. There is exactly one core per process, so the ABI has no
handles — the state is a file-scoped singleton and every function names it
-implicitly, exactly like the browser backend.
+implicitly.
The research this design came out of is written down separately in
`docs/ghostty-macos-notes.md` — how ghostty wires Zig to Swift, what its build
@@ -53,23 +53,20 @@ cell ABI is unchanged, but shader effects draw that same frame into a retained
bitmap and feed it through Core Image kernels on one Metal context.
There is no second glyph atlas, pane renderer, or view pointer in the ABI.
-## Why the ABI mirrors src/web.zig
+## Why the ABI is flat
-The browser and a Cocoa app are the same host, and the browser proved the shape
-first. In both, someone else owns the clock and the event loop; events arrive
+The browser shell (gone since 2026-11-05, `docs/web.md`) proved the shape
+first: someone else owns the clock and the event loop; events arrive
through flat functions that take scalars and borrowed byte ranges; one call
renders, and the result is one contiguous array of packed cells the host walks
-linearly. `pardes_cell_s` is byte-for-byte `WebCell`: seven UTF-8 bytes of
+linearly. `pardes_cell_s` is the browser's `WebCell` as it was: seven UTF-8 bytes of
grapheme plus a guaranteed zero, tagged `fg`/`bg` words (`0x01000000` default,
`0x02000000 | index` for the palette, otherwise `0x00RRGGBB`), an attribute
bitfield with the underline style in the high bits, and a `flags` bit meaning
"the core never painted this cell" so a host can draw background only and skip
-the glyph. Two hosts spelling the same encoding is not duplication worth
-removing; it is the encoding being right.
+the glyph.
-The one real difference is IO. The browser has no ptys, so `src/web.zig`
-forwards every effect out to JavaScript as a numbered code plus a byte payload,
-and JavaScript performs it. macOS has `forkpty`, `read` and `write` right
+IO stays on the Zig side: macOS has `forkpty`, `read` and `write` right
there, so almost no effect crosses the boundary at all: `pardes_tick` runs
`while (core.nextEffect()) |e| core.perform(e)` (`src/macos.zig:1154`) and each
effect lands on this host's own `Host.VTable`, of whose twenty-one methods
@@ -116,12 +113,12 @@ confused with a real codepoint arriving as text. `pardes_mouse` speaks acme's
vocabulary: three buttons, where 1 selects, 2 executes and 3 looks, with wheel
directions as ordinary buttons rather than a separate axis. Ctrl is the only
modifier the core consults (a left press with ctrl is goto-definition), but the
-full mask is passed anyway to keep the signature identical to the web one.
+full mask is passed anyway to keep the signature whole.
`pardes_scroll` carries fractional row and column deltas from a trackpad; the
Zig side accumulates each axis separately and synthesizes whole
`wheel_up`/`wheel_down`/`wheel_left`/`wheel_right` presses, because the core
-scrolls on button events. `src/gui/gui.zig` (`takeScrollTicks`) and
-`src/web/app.mjs` both do exactly this already. A real mouse notch skips the
+scrolls on button events. `src/gui/gui.zig` (`takeScrollTicks`) does
+exactly this already. A real mouse notch skips the
smoothing and goes through `pardes_mouse`. `pardes_rotate` is the same shape for
a two-finger twist, spent as `n`/`N` — see the trackpad section.
`pardes_command` runs one builtin command line through the core's own `command`
@@ -165,7 +162,7 @@ to input. An unintegrated shell has no reliable readiness signal, so it skips
the cosmetic greeting; an explicit command still releases after its successful
fork. Setting `Options.cols`/`rows` alone
never bumps that counter, so init must turn its arguments into an actual resize
-event the way `src/web.zig` does immediately after construction — and the size
+event immediately after construction — and the size
must be true, because the first `forkpty` takes its winsize from the core's
current grid and a shell booted at a placeholder draws its first prompt at the
wrong width. **Call `pardes_tick` after every input function.** The input calls
@@ -827,7 +824,7 @@ directory the benchmark binaries install into likewise never appears in this
backend; nothing here is a dev binary.
`-Dplatform=macos` is the one platform that overrides the repo's default
-target. The tty, SDL and web shells default to the Steam Deck (x86_64 linux-gnu, glibc
+target. The tty and SDL shells default to the Steam Deck (x86_64 linux-gnu, glibc
pinned to 2.38), and that default is not survivable here: swiftc links this
archive, so a Steam Deck build hands ld64 ELF objects inside a GNU archive and
the app link dies with `archive member '/SYM64/' not a mach-o file`. On a Mac
@@ -1128,9 +1125,9 @@ used for the table and is not folded into the direct-path claim.
- **The `pipe` effect.** Selection filters need `pipeRequest(id)` copied into a
job, a worker to run the command, and a `pipe_resp` event back. Same shape as
`lsp`, one more response type.
-- **Detached sessions.** `Attach` (`SPC s a`) and `Detach` (`SPC s D`) exist on
- every hosted platform, this one included, because `Builtin.enabled` is
- `pardes.hosted`. Neither works here. `Detach` emits `Effect.detach`, this
+- **Detached sessions.** `Attach` (`SPC s a`) and `Detach` (`SPC s D`) are
+ the tui's and the window's alone (`Builtin.enabled` is `pardes.can_attach`);
+ were they built here, neither would work. `Detach` emits `Effect.detach`, this
host fills in no `detach`, and `Pardes.perform` therefore reports
`error.NotAttached` on the pane's message row (`src/pardes.zig:6837`).
`Attach` emits `Effect.attach`, which `perform` turns into an `attach_req`
diff --git a/docs/shared-libs.md b/docs/shared-libs.md
index 412c2474..662579ea 100644
--- a/docs/shared-libs.md
+++ b/docs/shared-libs.md
@@ -58,8 +58,8 @@ Text section: tty 61,369,343 → 61,294,855 bytes (**−74,488**); gui
- **PNG and JPEG are wuffs's**, the decoders ghostty itself uses. image.zig
calls them wherever ghostty-vt is in the build (`wuffs_images`). Each image
- is sized from its header first: PNG's IHDR, JPEG's first SOF. Other formats,
- and builds without ghostty-vt (web), stay on stb_image.
+ is sized from its header first: PNG's IHDR, JPEG's first SOF. Other formats
+ stay on stb_image.
- **zstbi is compiled with `-DSTBI_NO_PNG -DSTBI_NO_JPEG`.** That also drops
stb's inflate, which only PNG used. Its `stb_image_write` include is patched
out (one count-checked anchor), with a no-op `stbi_flip_vertically_on_write`
@@ -81,8 +81,8 @@ Text section: tty 61,369,343 → 61,294,855 bytes (**−74,488**); gui
- **Two JPEG decoders: MuPDF's libjpeg and wuffs.** MuPDF's `DCTDecode` filter
(`filter-dct.c`) is written against libjpeg's streaming source-manager API.
Moving PDFs onto wuffs means a new DCT filter for fitz. Moving image panes
- onto libjpeg instead would leave the build without MuPDF (web)
- with no JPEG decoder.
+ onto libjpeg instead would leave a `-Dmupdf=false` build with no JPEG
+ decoder.
- **MuPDF's fitz image loaders** (`fz_load_png`, `_jpeg`, `_gif`, `_bmp`,
`_tiff`, `_pnm`, `_psd`; 16.7 KiB together). They are compiled because
mupdf.zig builds all of `source/fitz`. They are reachable only through
diff --git a/docs/typ/building.typ b/docs/typ/building.typ
index da704fe8..972b8a97 100644
--- a/docs/typ/building.typ
+++ b/docs/typ/building.typ
@@ -18,7 +18,6 @@ builds MuPDF and is on by default (`-Dmupdf=false` drops it).
[`zig build`], [the terminal shell and the SDL window together, *installed into `~/.local/bin`* (`pardes` and `pardes-gui`)],
[`zig build -Dplatform=tui`], [the terminal shell alone],
[`zig build -Dplatform=gui`], [the SDL3 window alone],
- [`zig build web -Dplatform=web -Dtarget=wasm32-freestanding -Ddump=<file>`], [a freestanding wasm core plus vanilla JavaScript (`docs/web.md`)],
[`zig build -Dplatform=macos`], [an AppKit and CoreText app over a static `libpardes.a` (`docs/macos.md`)],
)
@@ -37,11 +36,11 @@ must share with its session; `pardes --help` lists every flag.
`zig build --help` lists the options for the selected platform.
#pairs(
- [`-Dplatform`], [`tui`, `gui`, `web`, `macos`; absent: the tui and SDL shells together, installed into `~/.local`],
+ [`-Dplatform`], [`tui`, `gui`, `macos`; absent: the tui and SDL shells together, installed into `~/.local`],
[`-Dstatic`], [bool, `false`],
- [`-Dmupdf`], [bool; on natively, off for web],
+ [`-Dmupdf`], [bool, `true`],
[`-Djpx`], [bool, `true`: JPEG 2000, and with it scanned PDFs],
- [`-Dtree-sitter`], [`disabled`, `zig`, `minimal`, `full`; `full` natively, `zig` for web],
+ [`-Dtree-sitter`], [`disabled`, `zig`, `minimal`, `full`; `full`],
[`-Dembed-sources`], [bool, `false`: serve the sources under #file("/src")],
[`-Dhome-install`], [bool: a bare `zig build` also copies the binaries into `~/.local/bin`; default true],
[`-Dstamp-commit`], [bool: the git commit in `--version` and crash records; on for release builds and the `~/.local` install],
@@ -50,7 +49,6 @@ must share with its session; `pardes --help` lists every flag.
[`-Dprebuilt-shaders`], [bool: embed the committed SPIR-V; on for a bare `zig build`, off with `-Dplatform`; `zig build shaders` refreshes it with glslc],
[`-Dtracy`], [path to a Tracy checkout; off],
[`-Dmacos-identity`], [codesigning identity for `pardes.app`; `-` (ad hoc)],
- [`-Ddump`], [a Dump to embed in the web shell],
[`-Dtest-filter`], [run only tests whose name contains it; a filter that matches nothing fails],
[`-Dtest-rebuild`], [bool: fresh Zig test compilation],
[`-Dhelix-harness`], [reference executable for live differential tests; `HX_HARNESS`, else `hx-harness` on `PATH`],
@@ -84,8 +82,6 @@ zig build hxparity file-pane vs pty-pane editing parity
zig build hxgolf every helix-golf example, step by step, against helix
zig build perf-gate a gesture on the 50k-line file over 3x its baseline fails
zig build mupdf-check compile, link, render and search docs/design.pdf
-zig build web-snap browser highlighting and touch interactions
-zig build web-e2e Chrome-driven DOM end-to-end suite
zig build cheatsheet render the cheatsheet PDF (needs typst)
```
@@ -121,7 +117,7 @@ zig build cheatsheet render the cheatsheet PDF (needs typst)
A release passes all of these first: `unit-test` with `-Dplatform=tui` and
with `-Dplatform=gui`, `core-test`, `behaviour-test`, `process-test`, `snap`, the GUI goldens
(`zig build gui-golden -Dplatform=gui`, a hidden window; `PARDES_GUI_GOLDEN=update` rewrites them),
-`web`, and the ReleaseSafe tui and ReleaseFast gui builds. The committed
+and the ReleaseSafe tui and ReleaseFast gui builds. The committed
`docs/typ/cheatsheet-a4.pdf` is rendered again when the docs change.
= Sending patches <patches>
@@ -134,7 +130,7 @@ Mail patches to the list `~gbrls/[email protected]`; it is the preferred way to
= The core and its shells
-One core, four shells (tui, gui, web, macos). The core owns
+One core, three shells (tui, gui, macos). The core owns
editing, layout, rendering and the virtual filesystem it serves over 9P; a shell turns native
input into `pardes.Event`, presents `pardes.Surface`, and performs host
effects such as spawning processes.
@@ -155,15 +151,14 @@ effects such as spawning processes.
- `host_io.Host` is a context pointer and a vtable of optional callbacks; a
null method is not an error, and `Host{}` is a complete in-process pardes
that the tests use. Comptime decides what a build has (`pardes.platform`,
- `hosted`, `can_attach`, `pdf_enabled`); the vtable
+ `can_attach`, `pdf_enabled`); the vtable
decides who serves it.
- The root module is chosen by platform: `main.zig` (tui, gui),
- `web.zig`, `macos.zig`. The web and macOS shells are
- libraries whose host owns `main()`.
+ `macos.zig`. The macOS shell is a library whose host owns `main()`.
- `memory.limits` is the one home for the core's capacities (selections,
the tag's bytes, undo, the arenas' regions). Each core
- allocator is a thread-safe stack-fallback allocator, under a
- DebugAllocator in Debug builds.
+ allocator is a DebugAllocator over its arena's reserved region, thread
+ safe, its checks in Debug builds only.
Code map: `src/panes.zig` and the pane kinds it names (`src/File.zig`,
`src/Terminal.zig`, ...), `src/layout.zig`, `src/fs.zig` (host access,
@@ -188,7 +183,7 @@ selection-pipe workers post completions through a bounded mailbox; a
`host_io.Lsp.Job` owns copies of the source, path and arguments, never
reading the live core, and a request id, the pane's serial and (for an
edit) the file's revision reject a stale reply. A process that never calls
-`turn.start` (the tests, the browser) has no second thread.
+`turn.start` (the tests) has no second thread.
== The daemon and detached sessions
@@ -310,7 +305,7 @@ the hint.
= Other notes
`docs/` keeps the platform and design notes beside this book:
-`web.md` and `macos.md` (the browser and macOS shells), `effects.md` and
+`macos.md` (the macOS shell; `web.md` says what the browser shell was), `effects.md` and
`render-pipeline.md` (visual effects), `helix-keys.md` and `selections.md` (helix parity),
`lsp-evaluation.md`, `ui-review.md`, `divergences.md` (bookmarks off
`main`) and `open-questions.md`. `next-steps.txt` is a wishlist and
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.