diff options
Diffstat (limited to 'docs/macos.md')
| -rw-r--r-- | docs/macos.md | 33 |
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` |
