diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/macos.md | 33 | ||||
| -rw-r--r-- | docs/shared-libs.md | 8 | ||||
| -rw-r--r-- | docs/typ/building.typ | 27 | ||||
| -rw-r--r-- | docs/web.md | 157 |
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. |
