summaryrefslogtreecommitdiff
path: root/docs/macos.md
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/macos.md
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/macos.md')
-rw-r--r--docs/macos.md33
1 files changed, 15 insertions, 18 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`