diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/config.md | 132 | ||||
| -rw-r--r-- | docs/design.typ | 216 | ||||
| -rw-r--r-- | docs/helix-keys.md | 4 | ||||
| -rw-r--r-- | docs/macos.md | 176 | ||||
| -rw-r--r-- | docs/web.md | 24 |
5 files changed, 437 insertions, 115 deletions
diff --git a/docs/config.md b/docs/config.md index 30962ddb..7e27216b 100644 --- a/docs/config.md +++ b/docs/config.md @@ -16,15 +16,39 @@ still resolves, because "nothing is there yet" is the answer `Config` exists to give. There is one case with no path at all: a native launch with no `HOME` set, which `Config` reports as such. -`Config` (`SPC f c`, or the word executed anywhere) prints the resolved path -into a `+Config` output pane, so the machine answers this rather than the list -above. The path is printed whether or not a file is there — that is the case -you ask in — and the row is ordinary text, so a right click on it opens the -file. +`Config` (`SPC f c`, or the word executed anywhere) opens one refreshable +`+Config` pane. It reports the startup path and every live config-like value: +theme, colors, wrapping, tag position, debug mode, the requested shell and the +executable actually resolved at the last spawn, requested/effective GUI font +and size, tagline scale, panel transition, +scene effects, hover delay, platform, native-image support, and (on SDL) whether +the executable uses live-built shaders or the paired prebuilt shader snapshot. +Platform-dependent rows say `unsupported` instead of looking like an off or +empty supported setting: TTY reports Font and scene shaders as unsupported; +web reports Font, panel transitions, and scene shaders as unsupported. Tagline +font size is its own row and capability — GUI font selection is native-only, +while the browser still applies the compiled tagline percentage to its DOM. +The startup path is printed whether or not a file exists — that is usually when +it is most useful — and is ordinary selectable text, so a right click on it +opens the file. Shell follows the same requested/effective/pending model as +Font. `Compiled default shell` is the command built into the binary; `Shell +effective (last spawn)` is the executable the native host really chose after +installation lookup and fallback. A changed request remains pending until a +terminal is spawned, because the core does not resolve native executables. + +The mutable global values live together in the plain `runtime_config.State` record. +One plain capability record gates the setting registry, leader table, +`EffectCode`, and report; the compile-time setting table generates both setter +builtins and their `Config` rows. Exhaustive checks require every table-backed +toggle, transition, and scene-effect switch to occur exactly once, so those +generated setting builtins cannot quietly lose their query row or leave a +renderer switch unnamed. Manual pane-local actions remain with their payload (for +example an image tag reports its renderer choices); they are not global +configuration. The browser build has no local user-config path and does not load this file. -(Nor does it have the `Font` builtin, or a language backend, or ptys of its -own — see `docs/web.md`.) +(Nor does it have `Font`, the effect builtins or `EffectCode`, a language +backend, or ptys of its own — see `docs/web.md`.) The format is one existing builtin command per line, using the same spelling and argument parsing as commands executed inside pardes: @@ -32,14 +56,16 @@ and argument parsing as commands executed inside pardes: ```text Theme acme Font DejaVuSansMono-Regular +TaglineSize 82 Shell zsh Wrap ``` A line matches a builtin whose name takes NO argument only as that whole word: `Kill` runs, `Kill something` does not. Builtins that take one (`Theme`, -`Font`, `Shell`, `Restore`, `Find`, `Grep`, `Rename`, `WsSymbols`, `Look`, -`Exec`) take everything after the name as the argument. +`Font`, `TaglineSize`, `Shell`, `Restore`, `Find`, `Grep`, `Rename`, +`WsSymbols`, `Look`, `Exec`, `EffectCode`) take everything after the name as +the argument. `Theme <name>` wants one of the 228 names in the ring. Do not derive the spelling — read it off `ThemeSel` (`SPC t t`), which lists every one as the @@ -60,6 +86,20 @@ terminal's font belongs to its emulator and a browser's to the page — so a resolve the name by walking the font directories on every lookup, so a face installed a moment ago is findable. +`Font` is asynchronous at the renderer boundary. `Config` therefore keeps +requested name/path, pending state, and the effective face/point-or-pixel size +as separate facts; a failed request never gets reported as the face on screen. +Taglines use a distinct face size in both native GUI renderers. Execute +`TaglineSize <percent>` to change it live, for example `TaglineSize 70`; the +accepted range is 1 through 100 and the default comes from +`gui_tagline_font_percent` in `src/config.zig` (82). The native renderer +remeasures both the glyph and its visible tag band while retaining the body's +cell grid. The 100% ceiling is deliberate: a tagline remains exactly one +logical grid row, so a larger face or band would overlap its pane body or a +neighbour instead of leaving the body grid stable. `Config` reports the active +percentage. The browser applies the same compiled percentage to its DOM glyphs +but has no runtime setter. + What happens to a codepoint the chosen face has no glyph for differs by shell. The SDL GUI falls back through a chain it builds itself: embedded Adwaita Mono, then installed `NotoSansMono-Regular`, `DejaVuSansMono`, @@ -76,3 +116,77 @@ bad line does not prevent later lines from running. Top-level text that is not a builtin is not sent to a shell. (`Exec ...` remains an ordinary builtin and therefore keeps its normal behavior.) Key bindings remain compile-time choices in `src/config.zig`; this startup file does not remap them. + +## Panel and scene effects + +Exactly one panel transition is selected at a time. Executing its builtin a +second time turns it off; selecting another replaces it: + +```text +PanelSlide +PanelZoom +PanelDissolve +PanelAscii +PanelVertical +``` + +All panel transitions start off. Slide uses cubic ease-out and zoom uses an +overshooting ease-out-back. Dissolve and ASCII compare the last successfully +presented grid with the new one: cells which did not change are immediately +canonical, while changed cells cross from old to new through smoothstep or +stable themed punctuation. Vertical is a pane-lifecycle effect: a newly added +pane rises from below inside its own fixed box, and a deleted pane's frozen +content rises out; surviving panes are never animated. The TTY implementation +performs those operations directly on a copy of the canonical cell grid. +The SDL and native macOS GUI implementations pass plain panel tracks to their +GPU shaders, including native image/PDF pixels; layout itself commits +immediately and remains the one authoritative geometry. DOM web intentionally +does not expose these builtins: its renderer is selectable HTML/CSS and has no +canvas or shader stage. + +The scene effects are independent switches and can be combined: + +```text +Crt +Ripple +Glitch +``` + +They share one full-scene shader pass in SDL and macOS. With all three off the +pass is bypassed. CRT works in linear light with restrained scanlines, mask, +bloom, curvature, and noise rather than remapping the theme to a strong fixed +palette; Ripple and Glitch primarily perturb sample coordinates. + +`EffectCode <effect-builtin>` opens the build-embedded effect math, host +paint/submission path, and backend shader/grid sources, for example +`EffectCode PanelAscii` or, in a GUI build, `EffectCode Crt`. TTY exposes it +for its grid transitions; native GUI builds +expose it for transitions and scene shaders. It is absent on web, where no +effect argument could succeed. Shared +passes are shown as shared source segments rather than manufactured per-effect +copies. The command works from an installed binary and does not need the source +checkout beside it. SDL output also labels its shader provenance. An ordinary +build prints the live GLSL that `glslc` compiled for that executable; +`-Dprebuilt-shaders` prints the tracked GLSL snapshot paired with the committed +SPIR-V instead and labels those segments with their `shaders/prebuilt/` paths. +`zig build shaders` refreshes both files of every pair together, +so editing live GLSL without that explicit refresh changes neither half of a +prebuilt executable. + +## Delayed Look preview + +The preview is enabled by default. Moving the pointer onto selectable text and +leaving it still for `look_preview_delay_frames` (2 animation ticks, roughly +33 ms at the 60 Hz animation cadence) paints a +subtle theme-derived preview of the exact operand a right-click Look would receive. +Repeated motion reports in the same semantic grid cell do not restart the +delay. The preview uses the same side-effect-free word/path expansion as Look; +it does not focus a pane, move a cursor, install a selection, activate a PDF +page, or execute anything. Motion to another operand, pointer leave, input, +pane teardown, and relevant content changes cancel it. + +Set this compile-time option in `src/config.zig` to disable the feature: + +```zig +pub const look_preview_delay_frames: ?u16 = null; +``` diff --git a/docs/design.typ b/docs/design.typ index 7ee9f1ac..8dd14cdf 100644 --- a/docs/design.typ +++ b/docs/design.typ @@ -43,21 +43,35 @@ its own renderer; the core owns everything the user would recognize as pardes. effect and back; everything with a lifetime — a pty, a window, the clipboard — is still asked for.], [*shell*], [one MODULE per platform (tty is one file; gui adds the CRT and - gamepad files, a C font loader and twelve GLSL shaders; web and macOS each + gamepad files, a C font loader and eight GLSL shaders; web and macOS each add a host language). Owns the event loop, translates native input into core events, renders the core's surface, and performs the core's requested effects (spawn a shell, write a pty, open a link).], ) +Native shells share `shell_bin`'s OSC 133 startup snippets, but not their +files. Each host owns a private `mkstemp` pair for its lifetime, writes and +closes both before the first fork, passes those unpredictable paths directly +in child argv, and unlinks them at teardown. Concurrent tty, SDL and macOS +launches therefore cannot truncate, source, or replace one another's startup +files. + This also collapses the prototype's *two* applications into one: the browser build today is a separate 800-line read-only replay viewer. In the rewrite, loading a dump of another instance is a first-class feature of the one application, the way acme handles dumps: `pardes -l state.zon` on every -platform reconstructs the panes (terminals by replaying their raw VT streams -into fresh emulators, files, images and PDFs from their bytes — a PDF rides the -dump's `image` kind, carrying its path, its bytes and the page it was on). The web shell embeds -a dump and leaves `spawn` unanswered. Same core, no viewer fork. +platform reconstructs the panes—terminals by replaying their raw VT streams +into fresh emulators, files, images and PDFs from their bytes. Editable tag +tails are stored separately from their dynamic live prefixes, and image records +retain PETSCII, palette, and ASCII renderer choices. A PDF rides the dump's +`image` kind, carrying its path, its bytes and the page it was on. The web shell embeds +a dump and leaves `spawn` unanswered. The reader validates weights, scroll +ranges, pane references, and bounded tag tails before constructing anything; +invalid base64 fails instead of silently becoming empty content. A PDF record +whose path cannot be opened—or a build without MuPDF—falls back to an ordinary +file pane with those exact embedded bytes and its original editable tail. Same +core, no viewer fork. The boundary is two data types, both plain values: @@ -76,7 +90,8 @@ motion plus buttons. The shells do this translation and nothing else with input: one event vocabulary, four dialects translated at the door. *Surface* (out): `cols`, `rows`, a grid of cells — grapheme, fg, bg, attrs — a -cursor, and the pixel attachments. This is the *canonical interface*: it is literally what the +cursor, pixel attachments, and a bounded list of plain panel-transition tracks. +This is the *canonical interface*: it is literally what the tty shell hands to vaxis, cell by cell. SDL rasterizes the same grid through a glyph atlas; the browser reads a packed copy and patches native DOM cells. If it cannot be expressed in the surface, it does not @@ -84,8 +99,9 @@ exist in pardes. (Pixel images ride along as a list of PLACEMENTS rather than one per pane — a PDF pane contributes every page its viewport intersects, and pages can be arbitrarily short. The SDL shells blit RGBA, the tty shell falls back to the petscii matcher, kitty -graphics when available. The per-pane rectangles live on `Pardes`, not on the -surface: a shell that wants them asks the core.) +graphics when available. Transition tracks identify their pane by slot and +serial and carry only phase, effect, frame, and from/to cell boxes. Canonical +layout is committed immediately; tracks are finite presentation data.) *Effect* (out, queued): `spawn{pane, cwd}`, `write{pane, bytes}`, `resize_pty{pane, cols, rows}`, `open_link`, `new_file{pane, serial}`, @@ -95,9 +111,18 @@ The core never performs IO for any of these; it asks — and four of the asks ha answer coming back: `read_clipboard` returns an ordinary `paste` event (or nothing at all when the shell cannot read the clipboard — most terminals refuse the OSC 52 read), `lsp` returns `lsp_resp`, `pipe` returns `pipe_resp`, and -`watch` returns `file_changed` whenever the shell notices the file moved under -it. This -is what makes the browser build honest instead of a +`watch` returns `file_changed` whenever the shell notices a text file or PDF +moved under it. The tty and SDL hosts currently implement that path with Linux +inotify; the native macOS host watches both each file and its parent directory +with debounced DispatchSources, then restats the exact path under a pane-generation +guard. The file catches in-place writes while the parent follows rename-over +saves. Text snapshots are filtered by their content hash; PDFs use bounded +inode/size/time identity and commit it only when equal stats bracket a +successful transactional MuPDF reopen. A mismatched transaction gets one +bounded self-retry. This catches rename-over saves without reading a large PDF +merely to notice it changed or spinning on a malformed one. Web has no +filesystem watcher. A PDF response retains its +reading position and pane settings. This is what makes the browser build honest instead of a fork: a wasm shell simply answers `spawn` differently (or not at all) — the core does not know. @@ -111,10 +136,20 @@ if (platform == .web and target.kind == .url) return .{ .open_link = target.text }; ``` -There is one such file by design: `look.zig` holds *what a click on text means* — -expansion of the word under the click (acme's `isfilec`), path/`:line` -resolution, url detection, and the per-platform outcomes, kept adjacent so the -divergence is visible in one screenful. +There is one such file by design: `look.zig` holds path/`:line` resolution, +URL detection, and the per-platform outcomes. The core's one `pointerOperand` +primitive owns click-word expansion and is shared verbatim by right-click and +the delayed hover preview; that policy stays beside input because it also +observes live pane selections and wrapped grid coordinates. + +Pane implementations are similarly flat and direct: `file_pane.zig`, +`term_pane.zig`, `image_pane.zig`, `output_pane.zig`, and `pdf_pane.zig` own +their kind-specific storage and operations. `pardes.zig` keeps the layout, +input dispatch, cross-pane invariants, and the small calls joining those +modules. There is no pane vtable or callback layer; the kind is already plain +data, so a direct switch/call is the shortest boundary. +The large end-to-end PDF cases live in `pdf_pane_integration_test.zig`, keeping +pane-specific fixtures and raster assertions out of that core file as well. = Data structures @@ -123,24 +158,76 @@ heap-allocated on demand and their contents (file bytes, the yank register, PDF rasters, tree-sitter state) grow with what you open; everything else is sized at init. +User-settable runtime choices are one plain `runtime_config.State`: booleans, +theme index, owned bounded shell/font strings, requested/effective font facts, +one panel-transition enum, and scene-effect booleans. A compile-time `settings` +array generates each setting builtin and the rows of the single `Config` +query. It has no callbacks and no parallel query registry to drift from it. + +Horizontal layout weights are fixed-point integers and geometry rounds +cumulative boundaries. Splitting a column replaces only its weight `W` by +`A+B=W` at the same position. Therefore every boundary outside the source +column is bit-identical before and after the split, including at awkward +non-dyadic screen widths; only the source and new column can receive movement +tracks. Vertical splits apply the corresponding rule to the source pane's +weight. + += Presentation animation + +`panel_animation.zig` is backend-neutral data and math: five transitions, +their easing, exact endpoint progress, stable per-cell noise, and a POD track. +The core detects opening/moving rectangles when it commits layout and publishes +only active tracks. It retains the last successfully presented canonical grid +and a semantic old/new cell mask; unused grapheme bytes do not manufacture a +change. A separate dense closing-track list is presentation-only state for a +pane whose functional lifetime has already ended. Pointer input inverts the +presented slide/zoom/vertical rectangle back to the canonical grid, lets +unchanged dissolve/ASCII cells through immediately, and rejects closing +pixels, so pixels and gestures cannot disagree during a transition. + +TTY copies the canonical `Surface` grid into a compositor scratch grid, clears +slide/zoom destinations, then paints moving, opening, and closing panels in +order. +Cleared geometry uses the theme page color when it is explicit and the host +terminal default only for transparent themes, so a light theme cannot flash a +dark gap. Slide/zoom change the copied rectangle. Dissolve changes only diff +cells from their old value to their new value; ASCII takes the same cells +through punctuation; vertical raises only an opening or frozen closing pane +inside its own clip. SDL supplies old/new glyph data, diff flags, +final/presented boxes, and effect parameters to the glyph and native-image +shaders. macOS passes the same records across its plain C ABI and composites +old/new panel images in Metal/Core Image. Scene `Crt`, `Ripple`, and +`Glitch` bits share one full-window pass in each native GUI. DOM web is a +separate platform, not a shader GUI: retaining selectable HTML/CSS is more +important than duplicating the renderer in canvas, so it exposes neither +effect family. + +`EffectCode <effect>` writes the actual backend math, host submission, and +shader/grid source segments embedded by the build into an ordinary output +pane. This makes the implementation inspectable +after installation and makes sharing explicit: several builtins can quite +honestly print the same shader with different uniform bits. + ```zig Pardes ncol + col_weight[6], col_terms[6][16], col_n[6] // columns as flat arrays panes: [16]?*Pane // slot array; id = index active: usize drag: Drag // none | select | move | border_v | border_h | tag - theme_idx: usize // index into themes (228 of them) - colors_on: bool + settings: runtime_config.State // theme, shell/font, display/effect choices rects: [16]Rect // where each pane landed, this frame + panel_tracks: [16]?Track // live panes, serial-guarded + closing_panel_tracks: [16]Track // dense visual tombstones, no pane owner + presented_cells + changed_cells // acknowledged baseline + semantic diff effects: [4096]Effect + head/len // a fixed ring Pane tag: TagLine // live prefix (cwd/path) + editable tail - kind: enum { terminal, file, image, pdf } // + independent optional payloads vt, stream: ghostty-vt Terminal and its stream — on EVERY pane, not just terminals, which is what lets the same keys and the same parity suite drive a file and a shell - file: ?File / image: ?Image / pdf: ?PdfView + file: ?file_pane.State / image: ?image_pane.State / pdf: ?pdf_pane.State + // payload presence is the kind; none = terminal vweight: f32 mode: enum { normal, insert, tty } // helix-modal; tty = raw to the pty // `v` adds a fourth thing to DISPLAY, "select", @@ -148,13 +235,14 @@ Pane cursor: absolute body position // rides the scrollback, not the screen sel: [3]Sel + msel/vsel + sels[63] // per-button block sels, the line and // char modal ones, and up to 64 cursors - ovl: ?Ovl // ONE typed run, anchored to an absolute row - undo: two stacks, not one — ed_undo[64] of overlay snapshots for a terminal, - // and File.undo of content snapshots for a file + ovl: ?term_pane.EditBuffer // ONE typed run, anchored to an absolute row + undo: two stacks, not one — term_pane.Snapshot history for an edit buffer, + // and file_pane.State history for file content -File = path + bytes + line index + Syn (tree-sitter highlight bytes) -Image = decoded RGBA + petscii grid cache -PdfView = MuPDF document + per-page rasters + cached outline +file_pane.State = path + bytes + line index + Syn (tree-sitter highlight bytes) +image_pane.State = decoded RGBA + petscii grid cache +pdf_pane.State = MuPDF document + continuous layout + search/selection/outline + + bounded per-page raster relay + frame placement decisions ``` Layout is arithmetic, not objects: columns are weights over the width, panes are @@ -170,35 +258,11 @@ big `update` dispatch, not handler objects; no one-line helpers — inline the four-line scan; assert invariants at entry (`assert(vsum > 0)`); static allocation at init, arenas per frame. -The metric was lines of code, and for the rewrite itself it held: 7,626 lines -replaced the prototype's 12,072 with three backends instead of one and a half. -It has not held since, and the table below is the honest version rather than -the flattering one. Everything after the rewrite — PDF, a language backend, a -fourth shell, 228 themes, multiple cursors — was added, not traded for -something removed: - -#table( - columns: (auto, auto, auto, 1fr), - stroke: 0.4pt, - [*module*], [*at the rewrite*], [*now*], [], - [core and the pieces that grew out of it — 25 files: pardes, look, syntax, image, dump, builtins, config, output/file/term panes, normal\_input, nested, fonts, themes, …], [4,289], [22,220], [all semantics, all platforms], - [modal.zig + petscii.zig (pure, unit-testable)], [1,410], [2,569], [carried over], - [pdf.zig], [—], [1,581], [MuPDF, `-Dmupdf`], - [lsp/ (seam + in-process ZLS backend)], [—], [1,663], [`.zig` only], - [shells: tty 1,396; gui 4,968; web 601; macos.zig 1,579], [2,768], [8,544], [translate + render only], - [main.zig + build.zig], [484], [1,471], [four targets, four codegen passes], - [*application total* — every `.zig` under `src/`, plus `build.zig`], [*7,626*], [*38,048*], [vs the prototype's 12,072], -) - -Those six rows are a partition: no file is in two of them and none is left out, -which the old table could not say (its rows summed to 1,325 more than its own -total, and twenty-six files were in no row at all). What the total deliberately -does NOT count, because none of it is Zig under `src/`: 2,250 lines of Swift for -the macOS app and its icon generator, 1,541 lines of C bridging MuPDF, 549 of -JavaScript, HTML and CSS for the web shell, 216 of C for the SDL font loader, -`mupdf.zig` (355) at the root, and `tools/` + `build/` (896). The test tree is -another 5,234 lines of Zig across eight harnesses, plus 1,028 of Swift and 610 -of JavaScript — against 831 at the rewrite. +The rewrite used source size as a pressure toward direct code, and that remains +useful when a refactor deletes duplicate policy or state. A checked-in line-count +inventory does not: it goes stale whenever a pane kind, backend, or generated +asset moves. Measure the current tree when making that comparison; keep this +document about ownership and invariants that should survive the next edit. Two things that number is not. It is not one program's worth of growth — the macOS and web shells and the PDF and language work are four products sharing a @@ -214,14 +278,18 @@ captures the rendered grid — text, cursor, and per-cell style runs — through its own ghostty terminal. Goldens are generated from the old binary (`zig build snap -- --update`); the new binary must reproduce them byte for byte (`pardes-snap pardes/zig-out/bin/pardes`). Eighteen scripts covered the -checklist in Appendix A at the rewrite; eighty-seven cover it and everything +checklist in Appendix A at the rewrite; ninety cover it and everything since. All pass. Determinism pins: fixed workdir paths (they appear in tags), a controlled `$HOME` with `PS1='$ '`, `LC_ALL=C`, and a grid-stability sync primitive instead of timing guesses. Three deliberate deviations surfaced by the oracle, kept after review: the -greeting `ls` waits for the shell's first output (the prototype raced bash's -startup and won only by allocator luck); dump files compare with base64 pty +greeting `ls` waits for the exact OSC 133 B input mark after the real resize +(the prototype raced bash's startup and won only by allocator luck); shells +without prompt integration omit that cosmetic greeting rather than guessing. +Commands which create a fresh shell are owned by its terminal pane until the +host reports the actual prompt capability, then wait for the same mark when it +exists. Dump files compare with base64 pty history elided (it encodes prompt-redraw micro-timing, not state — the cleaned text fields are the contract); and typed insert runs don't survive a dump replay (they are an overlay, not pty bytes — the prototype's replay viewer had @@ -252,12 +320,14 @@ everywhere but the web, lazy), ZLS, mvzr (the regex engine behind `s`/`S`), and zig-tree-sitter + 26 grammars — all pinned through `zig fetch` and wired in `build.zig`. Generated during the build: `highlights.scm` → an options module; the vendored helix/zed theme -sources → the generated half of the theme ring; the tracked `.zig` sources → +sources → the generated half of the theme ring; working-tree `.zig` sources → the web shell's read-only archive; eight GLSL shaders → SPIR-V. That last one is the only build input wanting a tool a stock machine lacks (`glslc`), so it is -also the only one whose output is committed: `zig build shaders` writes -`shaders/prebuilt/*.spv` and `-Dprebuilt-shaders` embeds that copy rather than -shelling out, which is what lets a gui build need nothing but a C toolchain. The +also the only one whose output is committed: `zig build shaders` refreshes each +paired `shaders/prebuilt/*.spv` binary and `.glsl` source snapshot together. +`-Dprebuilt-shaders` embeds that exact pair rather than shelling out, so +`EffectCode` cannot describe different shader text from the binary on screen; +this is also what lets a gui build need nothing but a C toolchain. The tutor and the embedded font are plain `@embedFile`s, not codegen. Debug builds are incremental for the seconds-loop; release builds are the product. @@ -292,7 +362,8 @@ everything below that the prototype never had. *Layout.* Columns by weight (≤6), panes by vweight (16 panes in total, not per column); global topbar; per-pane gutter (move box + scrollbar) and tag row; `splitBelow` shrinks only -the source (cursor row kept visible); dying pane's weight absorbed by one +the source (cursor row kept visible); `Newcol` takes width only from the source +column and cannot resize any unrelated column; dying pane's weight absorbed by one sibling; emptied column hands width to a neighbor; border-drag resize on a pane's own trailing edge (v and h), hover shows `╎`/`╌` glyph-only hints; move-drag via the gutter box with preview; Alt-n new shell below, Alt-c move @@ -321,8 +392,10 @@ has beyond a path: `` @`ls -la` `` is taken WHOLE and runs as a command rather than opening as a file, and `@p7:10:5` addresses a live pane by number for the things — terminals, output buffers — that have no path to name. Middle+left chord: kept -left selection appended as trailing CLI argument. Wheel: scroll hovered pane, -batched. +left selection appended as trailing CLI argument. A stationary pointer gets a +delayed, theme-derived highlight of the exact side-effect-free selection that +Look would expand; it neither focuses nor installs that selection, and pointer +leave/input/content invalidation cancels it. Wheel: scroll hovered pane, batched. *Modes.* normal: helix motions (`h j k l w b e W B E 0 $ ^`, `f F t T` and `Alt-.`, counts, `gg ge gh gs gl g| G`, `Ctrl-d/u/f/b`, `zt zz zb zj zk`), @@ -349,9 +422,10 @@ cannot clobber what the desktop was holding. A paste from an outer terminal arrives bracketed, as one `paste` event. *Tag.* Live prefix (mode indicator, cwd or path) + editable tail with the -full modal editor; defaults `New Del` / `Save New Del`; an image tag is -`img <path> New Del` like any other (its renderer toggles are builtins under -`SPC t p/l/a`). Topbar: +full modal editor; defaults `New Del` / `Save New Del`; an image tag reports +`img petscii:<on|off> palette:<commodore|terminal> ascii:<on|off> <path>` +before the ordinary tail (its renderer toggles are builtins under `SPC t +p/l/a`). Topbar: `New Newcol Find Grep Help Tutor Dump NextColor Debug Kill` — execute-only (left click inert); Colors and Crt left it for their leader paths. @@ -408,10 +482,12 @@ scrollbar, Colors/NextColor, and link-LOOK opening a new tab (new — the prototype has no web link handling). One-finger touch is deliberately complete by itself: tap = LOOK; drag past a small slop = natural scroll, with no LOOK on release. A build-generated read-only archive lets LOOK -open the current contents of Git-tracked Pardes `.zig` files despite the web +open the current contents of tracked or new/nonignored Pardes `.zig` files despite the web shell having no host filesystem. The published launcher dump is captured from -a running Pardes TTY after `git ls-files '*.zig'`, so its complete terminal -listing is the set the user can open. The freestanding module carries no host +a running Pardes TTY after +`git ls-files --cached --others --exclude-standard -- '*.zig' | sort`, so its +complete terminal listing is the same tracked-plus-new/nonignored set the user +can open. The freestanding module carries no host libc, SDL, or WebGL; Tree-sitter's C runtime and the selected parsers link into the module through a tiny local ABI shim (Zig is the compact web default). A body gesture retains tap-LOOK/drag-scroll, but finger-down on diff --git a/docs/helix-keys.md b/docs/helix-keys.md index addc23da..2aff75cd 100644 --- a/docs/helix-keys.md +++ b/docs/helix-keys.md @@ -95,7 +95,7 @@ language-backend queries, and the shell pipe. | `Ctrl-w` + `h/j/k/l`/arrows | directional pane focus prefix — normal/tty modes only | pardes' own window handling (helix window mode skipped, section C). Runs the SAME `Left`/`Down`/`Up`/`Right` builtins `SPC w h/j/k/l` runs; kept alongside the leader because a pane in raw **tty** mode never sees `SPC` (the shell owns it), so this is the only keyboard way out of one. Insert mode owns `Ctrl-w` = delete-word-back, so a tag being TYPED into swallows it; from a tag in normal mode (`:`) it moves focus to the neighbour's BODY, while the bare letters `h/j/k/l` there move to its TAGLINE (next row) | pardes-specific | | `Alt-n` | new terminal below (any mode) | shadows helix `Alt-n` TS sibling-select — skipped anyway (tree-sitter) | pardes-specific | | `Alt-c` | move active terminal to a fresh column (any mode) | helix `Alt-c` is change-noyank; the pardes window op wins (do-not-touch contract). `Alt-d` + `i` covers the behavior | waived (`alt-c-window-op`) | -| `Space` (normal, body) | the pardes LEADER: a key path from here runs a BUILTIN with no arguments — the same builtins the topbar and the tags hold. `SPC k` Kill, `SPC d` Del, `SPC f s` Save, `SPC f n` New (an empty temporary file focused in the calling pane's column), `SPC f f` Find (fd over the pane's directory, results into `+Search`), `SPC f g` Grep (grep -R over the CONTENTS of every pane's directory, the ones another pane already covers dropped, rows relative to the asking pane's own directory, results into `+Search`; like Find it takes an ARGUMENT — `Grep foo` executed, or a selection chorded onto the word, searches that and skips the input), `SPC h t` Tutor, `SPC c n`/`SPC c d` Newcol/Delcol, `SPC y/Y/p/P/R` the five clipboard words (next row), `SPC t d/c/n/r` Debug/Colors/NextColor/Crt, `SPC t t` ThemeSel (the whole theme ring as `Theme <name>` rows in an output buffer — rows that are COMMANDS rather than places, so a theme is previewed by EXECUTING one, Tab or a middle click; `n`/`N` do not run them, they step past to the next look-able text on the ring), `SPC t p/l/a` Petscii/Palette/Ascii (an image pane's renderer toggles — the words its tag used to spell out, so the bar stays a bar), `SPC s d`/`SPC s r` Dump/Restore, `SPC w h/j/k/l` Left/Down/Up/Right (directional pane focus — the `Ctrl-w` prefix's four moves as builtins), `SPC j o`/`SPC j i`/`SPC j j`/`SPC j l` Back/Forward/Last/Jumplist (the jump stack: walk it back, walk it forward, hop to the pane before this one — what body-normal Esc runs — and read the stack as a clickable buffer). `?` at ANY depth opens the Help builtin listing what the prefix can still reach (`SPC ?` = all, `SPC h ?` = the docs group), into a `+Help` output buffer. The pending path shows at the right edge of the active pane's tag; Esc — or any unmapped key — abandons it | helix spends Space on pickers/LSP (section C); pardes has neither, and acme's builtins are what a leader is for. Enum-derived: the paths, the Help lines and the execute dispatch all fold out of one `Builtin` enum at comptime. Normal mode on a BODY only — tags are always insert, tty keys belong to the program | pardes-specific | +| `Space` (normal, body) | starts the pardes LEADER: a key path runs the same builtin words used by tags and the topbar. The main groups are `f` files, `h` docs, `c` columns, `t` toggles/effects, `a` panel animations, `s` session, `j` jumps, `l` language, and `w` directional focus; `SPC ?` lists every path and `<prefix> ?` lists one group in `+Help`. The pending path appears on the active pane's transient body/message row. Esc or an unmapped key abandons it. Paths, Help rows, and dispatch are all generated from the builtin registry at comptime; the leader applies only to a BODY in normal mode because tags and tty programs own their input | pardes-specific; helix spends Space on pickers/LSP (section C), while pardes uses acme-style executable words | | `SPC y` `SPC Y` `SPC p` `SPC P` `SPC R` | helix's clipboard menu on helix's own letters: yank the selection to the system clipboard (`ClipYank`) or the PRIMARY selection alone (`ClipYankMain`), paste the system clipboard after (`ClipPaste`) / before (`ClipPasteBefore`) the selection, replace the selection with it (`ClipReplace`) | the ONLY five words in pardes that touch the desktop's clipboard — `y`/`d`/`c`/`p`/`P`/`R` and the acme cut/paste chords are the internal register alone. Builtins rather than bare chords because a leader path names a builtin: they land in Help's index and are executable words like every other verb. One divergence: pardes keeps a single register VALUE where helix keeps one per range, so `SPC y` at N cursors joins them with newlines (`Pardes.setYank`, the divergence `msel-yank-paste` already waives). On a tty the write is OSC 52 out and the READ is OSC 52 back, which many terminals refuse or gate — so `SPC y` works there and `SPC p` can be a no-op | out of corpus | | a paste from the OUTER terminal | one `Event.paste`, spliced in at the cursor | the tty shell enables bracketed paste and coalesces `paste_start`..`paste_end` into a single event; before that the bytes arrived as individual key presses and normal mode RAN them, which is how a pasted `d` deleted a line. The bytes deliberately never enter the yank register — clipboard and default register are separate stores in both directions | pardes-specific | | `/` (any pane) | pardes' own plain-substring search into a `+Search` output buffer: the tag takes the pattern, Enter fills the buffer, and its rows are ordinary look targets. Enter also GOES to the first row — the buffer is focused and then the step `n` is and the look Enter is run in it (`Pardes.lookFirstHit`), so `/foo` lands on the first hit with the matched span selected. A pattern that matched nothing opens its empty buffer and moves nothing | KEEP, do not touch; not in the corpus (helix `/` is regex search). Find and Grep answer with OTHER files and deliberately do NOT jump. The stepping half is the next row | pardes-specific | @@ -348,7 +348,7 @@ Files (all in `test/hxcases/`): (one yank register, not one value per range), and `sel-regex-caret` / `sel-regex-dot-newline` (mvzr is not the Rust regex crate: no multi-line `^`/`$`, and `.` matches a newline). -- `test/hxdiff.zig` builds `pardes-hxdiff`, which drives the sans-IO core +- `test/hxdiff.zig` builds `pardes-hxdiff`, which drives the core headlessly at 80x24 (22 body rows, matching helix's 22 text rows). Run it: diff --git a/docs/macos.md b/docs/macos.md index 12e598b5..b800513f 100644 --- a/docs/macos.md +++ b/docs/macos.md @@ -44,6 +44,11 @@ the view and drives its own frame clock, and the ABI grows a `platform` pointer field carrying the `NSView*` — one field, because the rest of the seam does not change. Nothing here is designed to make that harder. +That does not rule out a *postprocess*. CoreText is still the renderer and the +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 The browser and a Cocoa app are the same host, and the browser proved the shape @@ -78,6 +83,11 @@ asking for a thin insert caret instead of a block. `Surface.images` crosses separately as `pardes_frame_images` / `pardes_frame_image_list` — see "Pixel attachments" below. +`pardes_scene` is the matching full-window snapshot: a bit each for CRT, +ripple, and glitch, plus the 60 Hz time/frame that animates them. It is returned +by value, so the renderer never holds a pointer into live core state. A zero +flags word is also the fast-path contract: draw the CoreText frame directly. + **Input.** `pardes_key` takes a codepoint and the host's already-composed text, because composition is AppKit's job and the core only ever wants finished characters. Keys that carry no text are the four ASCII controls (enter, escape, @@ -123,15 +133,19 @@ because it owns the filesystem side too. **Lifecycle.** `pardes_init` returns 0 or an opaque nonzero code, `pardes_deinit` tears down, `pardes_tick` drains pty output plus the effect queue and returns whether anything changed, `pardes_should_quit` reports the -Exit builtin or the last pane closing, and `pardes_animating` says a theme -transition wants ~60 Hz ticks until it settles — the one thing in an otherwise -event-driven frontend that redraws on a clock, handled in `tty.zig` by sleeping -the loop and forcing a tick. +Exit builtin or the last pane closing, and `pardes_animating` says +`pardes_animation_tick` wants a ~60 Hz call until it settles — the one thing in +an otherwise event-driven frontend that redraws on a clock. A persistent scene +effect deliberately keeps that clock armed until its builtin turns it off. +Ordinary input and pty pumps never count as elapsed animation frames. The ordering contract is the part a header cannot enforce. **Init with the real -grid size.** The core defers each shell's greeting until it has seen a resize: -`sync()` in `src/pardes.zig` only emits the opening `ls` once `resize_count > 0` -and the pty has produced its first prompt. Setting `Options.cols`/`rows` alone +grid size.** The core defers each integrated shell's greeting until it has seen +a resize: `sync()` in `src/pardes.zig` only emits the opening `ls` once +`resize_count > 0` and parsed OSC 133 B says the prompt has handed the cursor +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 must be true, because the first `forkpty` takes its winsize from the core's @@ -252,12 +266,12 @@ most deliberate twist there is and the one a stale velocity sample would fling hardest. And a finger back down (`pardes_rotate(0)`) catches a coast in progress, the way a hand catches a dial. -The coast itself is spent by `pardes_tick`, one fixed 1/60 step per tick with a -0.94 decay, and it makes `pardes_animating` true for as long as it lasts — so -it rides the same 16 ms re-pump a theme transition does and needs no clock of -its own. Fixed rather than measured on purpose: one fling then spends the same -travel every time, which is what lets `rotate.snap` assert it instead of -asserting the machine's timer jitter. +The coast itself is spent by `pardes_animation_tick`, one fixed 1/60 step per +scheduled frame with a 0.94 decay, and it makes `pardes_animating` true for as +long as it lasts — so it rides the same 16 ms re-pump a theme transition does +and needs no clock of its own. Fixed rather than measured on purpose: one fling +then spends the same travel every time, which is what lets `rotate.snap` assert +it instead of asserting the machine's timer jitter. Both halves are goldens. `rotate.snap` turns the dial at 4° per 100 ms (40°/s, under the floor) and asserts the screen is byte-identical across the release, @@ -471,14 +485,18 @@ can disagree. `pardes_font_take` hands it over once, the same take-and-clear shape as the haptic, and the view loads it with `CTFontManagerCreateFontDescriptorsFromURL`, picks the untraited cut out of a collection, derives bold and italic from it, and re-measures. A file it cannot -wear leaves the screen exactly as it was — a terminal that cannot draw has no -way back out of itself. +wear crosses back through `pardes_font_reject` and leaves the old metrics +exactly as they were. Success crosses through `pardes_font_ack` with the +effective PostScript name and point size. Requested and effective values are +therefore distinct, queryable facts rather than a request being mistaken for +what is on screen. -Zoom does not touch the core at all. Cmd+=, Cmd- and Cmd+0 change the point size, -`Metrics` is rebuilt, and the new cell is reported through the same resize path -a window drag uses; the core reflows to a different number of columns and knows -nothing about points. Cmd+= rather than Cmd++ because AppKit matches the -character and `=` is what is under the finger. +Cmd+=, Cmd- and Cmd+0 change the point size, rebuild `Metrics`, and report the +new cell through the same resize path a window drag uses. They also observe the +effective face/point tuple through `pardes_font_observe`, so the single `Config` +report follows a host-owned zoom without resolving a pending face request. The +initial system face is observed the same way. Cmd+= rather than Cmd++ because +AppKit matches the character and `=` is what is under the finger. Both are machine-checked in `test/macos-snapshots/font.snap`, which needs two different kinds of assertion because a snapshot is the core's cell buffer and @@ -551,18 +569,40 @@ Turning this on also changes what an IMAGE pane is here: it was the PETSCII glyph-art fallback, the same one a terminal without kitty graphics gets, and it is now the real pixels. +## Live file reload + +`FileWatcher.swift` gives each watched pane a vnode source on the file and one +on its parent directory. The file catches in-place writes; the parent is +essential because editors commonly save by renaming a fresh inode over the +path. After the 45 ms debounce the file source is rearmed on the current inode, +then the event returns to Zig with the pane's watch generation. Replacing or +closing a pane advances that generation, so a callback already queued for the +old occupant cannot reload the new one. + +The callback only wakes the ordinary main-thread pump. `pardes_tick` checks the +exact owned path, filtering unrelated changes in the same directory, duplicate +vnode events, and Pardes's own saves. Text panes compare and adopt a bounded +byte snapshot by content hash. PDFs can be much larger than that bound, so they +compare inode/size/time metadata and let MuPDF reopen the pathname directly. +That identity is committed only when equal stats bracket a successful +transactional reopen; a mismatch receives one self-scheduled retry, so it does +not depend on a second vnode edge and cannot spin forever on a malformed stable +file. Reading settings survive and derived page data is regenerated. A +malformed PDF therefore leaves the last good document usable and remains +retryable after the next real write. + ## Themes, live Two bugs lived here, and they were the same bug. `ChromeTheme` fades between themes over ten 16 ms steps, advanced by a `.tick` -event. The tty and SDL loops call `core.update(.tick)` on their own clocks; -this host has no loop of its own, so nothing advanced it — `pardes_tick` -drained ptys and reported `themeAnimationActive()` back without ever stepping -the transition. The fade therefore never moved and never ended: every tagline -kept the *previous* theme's colours until the next launch, and the 16 ms -re-pump in `AppDelegate.pump` spun at 60 Hz for the rest of the session. The -pump is the clock, so `pardes_tick` steps it. +event. The tty and SDL loops call `core.update(.tick)` on their own clocks; the +native host schedules the same clock explicitly through +`pardes_animation_tick`. `pardes_tick` only drains work: if every input pump +also advanced the transition, a burst of key or pty events could collapse a +ten-frame fade into one display frame. The scheduled callback advances once, +then pumps effects and redraws, and re-arms itself only while +`pardes_animating` remains true. `pardes_theme_bg` is the other half. The window background behind the titlebar and behind a live resize was a hand-agreed `#121212` in two files; it is now @@ -571,6 +611,65 @@ chrome's, because document backgrounds switch the instant the theme does while chrome fades. `window.appearance` follows its luminance, so wearing `acme` no longer leaves a dark titlebar over a cream grid. +## Scene effects + +`Crt`, `Ripple`, and `Glitch` are three switches over one postprocess, not three +stacked filters. Their canonical macOS source is `shaders/crt.ci.metal`, which +the build installs as `pardes.app/Contents/Resources/crt.ci.metal`. The Swift +shell loads that exact asset with `CIKernel.kernels(withMetalString:)` and runs +it through a `CIContext` created from the system Metal device. The source is +also a Zig build import, so `EffectCode` can print what the app executes when +the source checkout is absent. + +The ordinary CoreText/attachment/cursor pass is one function. With any scene +bit or panel track it targets a retained, backing-scale bitmap; kernels then +sample the complete frame into the flipped view. PDFs, image panes, taglines, +rules, and the caret therefore receive the same effect. With every bit off and +no panel track the bitmap and Core Image context are bypassed entirely. Ripple +and glitch alter sample coordinates only, preserving theme colors; CRT works +in linear light with restrained bloom, scan/mask, vignette, hum, and noise +instead of applying a broad color remap. + +The scene kernel alone receives a `clampedToExtent` image and the final output +is cropped back to the original finite extent. Coordinate tears and chroma +samples therefore clamp to the edge exactly like SDL's scene sampler instead +of acquiring transparent-black seams from Core Image's finite source image. + +The Zig side owns the clock. `pardes_animation_tick` increments its wrapped +60 Hz frame only while a scene bit is active, and `pardes_scene` derives seconds +from that integer. Input bursts cannot accelerate the shader. + +Pointer input follows the same destination-to-source transform as the last +presented scene frame before it is divided by the cell metrics. The view keeps +that exact `pardes_scene_s` snapshot and mirrors the Metal barrel, ripple and +glitch sampling arithmetic in `ScenePostprocessor.sourcePoint`; pixels outside +the CRT tube have no cell. The resulting displayed-grid cell then reaches the +core, whose panel-track mapping resolves it to canonical pane content. + +## Panel transitions + +`pardes_frame_panel_track_list` publishes the core's plain `Track` records +without a host-side animation model: pane serial/id, phase, effect, frame, and +logical-cell `from`/`to` boxes. The C layout and every field offset are asserted +against the Zig extern struct on Linux. The exported list is already stable +paint order—moving panes by slot, then opening panes by slot—so Swift only +consumes it. + +CoreText still renders one canonical complete frame. When tracks exist, the +same retained bitmap used by scene effects is fed through two kernels in +`shaders/crt.ci.metal`: `pardesPanelClear` removes every final target first, +then `pardesPanel` samples each target into its eased presented box. Slide uses +ease-out cubic, zoom uses ease-out-back, dissolve uses stable pane/cell noise, +and ASCII materialization replaces not-yet-revealed cells with procedural +punctuation. Because the input is the finished bitmap rather than a glyph-only +batch, backgrounds, glyphs, taglines, rules, the caret, PDF pages, and image +panes move and dissolve together. Scene CRT/ripple/glitch runs once after the +panel composition. + +With no scene bit and no panel track the retained bitmap, Core Image context, +and Metal passes are bypassed. `EffectCode Panel*` embeds this actual Metal +file plus its direct Swift owner, the same files the app executes. + ### Transparent themes A theme with `bg = null` — the curated `dark`, and every vendored @@ -794,7 +893,12 @@ vocabulary (`start`, `wait`, `stable`, `text`, `key`, `snap`, `command`, exists here: `fingers <n>`, `force`, `rotate <degrees> [gap_ms]`, `rotate_end`, `drop <path> <col> <row>`, `scroll <rows> <col> <row>`, `haptic <none|exec|look>`, `nsclick` (the AppKit-event path, as opposed to -`click`'s direct entry-point call), `font <name>`, `zoom` and `clipboard`. +`click`'s direct entry-point call), `font <name>`, `font-size <points>`, `zoom`, +`tracks <phase:effect>...`, `draw-effect`, and `clipboard`. The boot script uses +`tracks` followed by `draw-effect` to assert the moving/opening ABI order and +that the runtime Metal owner actually accepted the panel frame (a raw fallback +fails); the font script checks every initial/adopted/zoomed effective point +size without changing its grid goldens. The dial's two extras are what make momentum testable at all: the optional gap is a real sleep before the event, so a script can say how FAST the dial is being turned, and `rotate_end` @@ -815,6 +919,11 @@ every pixel comes out identical, which is what keeps `draw(_:)` honest — `snap reads the core's cell buffer and would be perfectly happy with a `draw` that returned on its first line. +The Linux loop proves the new C layout, flag encoding, clock wrap, embedded +kernel source, header syntax, and static library. Compiling Swift, runtime Metal +kernel compilation, and comparing processed pixels remain `macos-e2e` work on +a Darwin host; Linux has neither AppKit nor Apple's Metal runtime. + Goldens are hermetic: a fake `$HOME` with a pinned `PS1`, `Shell bash` in the config (fish's prompt carries a hostname), `LC_ALL=C`, `PARDES_NOTIME=1`, and `TMPDIR` inside the per-script world so that `New`'s document has a reproducible @@ -851,6 +960,11 @@ this matter, are both in `pardes_frame` rather than in the view — it re-render every cell of the grid on every frame, and `draw(_:)` ignores its `dirtyRect` for exactly that reason. +Those figures are the direct path with all scene bits off. An enabled scene +adds an offscreen CoreGraphics frame, one Core Image/Metal kernel, and +presentation of its result. That opt-in cost has not been measured on the M2 +used for the table and is not folded into the direct-path claim. + ## Not implemented - **The `lsp` effect.** Needs a worker plus a snapshot of the pane's path and @@ -862,12 +976,6 @@ for exactly that reason. - **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. -- **The `watch` effect.** `watchPane` is inotify and returns silently off Linux - (`ponytail:` at `src/tty/tty.zig:1183`). macOS wants the FSEvents half of - `std.Build.Watch`, which the standard library already has as - `Build/Watch/FsEvents.zig`. Without it the core simply never receives - `file_changed`, a state it tolerates because the browser has no filesystem - either. - **IME and marked text.** Only finished characters reach `pardes_key`, so a dead key composes nothing and Option is Alt rather than a compose modifier. Real composition means implementing `NSTextInputClient` *and* giving the core diff --git a/docs/web.md b/docs/web.md index ddc09d35..a6e2e923 100644 --- a/docs/web.md +++ b/docs/web.md @@ -18,6 +18,22 @@ array. `src/web/app.mjs` reads that array in one linear pass and patches stable DOM nodes. Core effects become browser operations (links, downloads, clipboard) or `pardes-io` custom events for a process-capable embedding host. +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. It exposes no `PanelSlide`/`PanelZoom`/`PanelDissolve`/`PanelAscii`/ +`PanelVertical` or `Crt`/`Ripple`/`Glitch` builtins: applying those 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 @@ -37,12 +53,20 @@ 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. +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 file, LOOK resolves against the build-generated source archive rather than disk, and no language BACKEND is compiled in (`zls_backend` is off for wasm — which also means `lsp.supports` is empty, so the core never even raises a language query there; `web.zig`'s prong for it is waiting for a host that links one). +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. The EFFECTS themselves are all still emitted, each as a numbered code across the ABI: `spawn` 1, `write` 2, `resize_pty` 3, `open_link` 4, `save_file` 5, |