Ghostty native shaders (Slice 3, stacked on #516)

docs/development/native-appearance-welcome/CHECKPOINT.json

@@ -1,14 +1,51 @@
 {
-  "phase": "Slice 2 (Kitty native shaders) implemented, reviewed, canonically verified (1 load-induced live timeout, passes alone); committed on feature/kitty-native-shaders-20261028",
+  "phase": "Slice 3 (Ghostty native shaders) implemented, independently reviewed, fixed, canonically verified clean; committed on feature/ghostty-native-shaders-20261028",
   "updated": "2026-10-28",
-  "slice1": {"branch": "feature/appearance-welcome-20261028", "head": "4abd014d3bee8c19f2a1c25c5271cc6f5b3fe474", "pr": 515, "ci": "run 40640910786 success (not re-run)", "state": "draft, unmerged, unchanged"},
-  "slice2": {"branch": "feature/kitty-native-shaders-20261028", "base": "4abd014d3bee8c19f2a1c25c5271cc6f5b3fe474", "pr": "stacked draft PR targeting feature/appearance-welcome-20261028 (see HANDOFF/progress for number)",
+  "slice1": {
+    "branch": "feature/appearance-welcome-20261028",
+    "head": "4abd014d3bee8c19f2a1c25c5271cc6f5b3fe474",
+    "pr": 515,
+    "ci": "run 40640910786 success (not re-run)",
+    "state": "draft, unmerged, unchanged"
+  },
+  "slice2": {
+    "branch": "feature/kitty-native-shaders-20261028",
+    "base": "4abd014d3bee8c19f2a1c25c5271cc6f5b3fe474",
+    "pr": "stacked draft PR targeting feature/appearance-welcome-20261028 (see HANDOFF/progress for number)",
     "source_manifest_sha256": "a658e9704941d4588014f137d22fc2129f3c72d9650e27e9e5ab113db6620519",
     "tests": "canonical 4621/4636 pass, 1 fail (outputSelectionLive fish startup timeout; 3/3 alone), 13 skipped, 1 todo; Kitty focused 26/26; tsc clean; diff --check pass",
-    "review": "independent Sonnet review: no blocker; 4 should-fix fixed with regressions"},
+    "review": "independent Sonnet review: no blocker; 4 should-fix fixed with regressions"
+  },
   "evidence": "/Volumes/T7Tmp/ai-dev/nmsh-native-appearance-welcome-20261028 (CHECKPOINT.json, slice2-probe/, slice2-canonical-verify.log, slice2-live-rerun.log)",
   "physical_qa": "NOT RUN",
-  "gpu_validation": "NOT RUN (headless Kitty parse + slangc compile only)",
-  "unrelated_prs_untouched": [513, 514],
-  "next": "Human: physical Kitty QA of /appearance › Kitty shaders (enable Blaze/Lightning trail with /cursor Motion Tail, Northern Lights, CRT; check user custom_shaders still run; R restores). Agents: Ghostty GLSL slice next (separate stacked PR); never merge automatically; after #515 merges, rebase/retarget only after review."
+  "gpu_validation": "NOT RUN (headless Kitty parse, Ghostty +validate-config, slangc proxy compile only)",
+  "unrelated_prs_untouched": [
+    513,
+    514
+  ],
+  "next": "Slice 4: render routing (src/motion/renderRouting.ts) + Chroma-driven Aurora colors; then Slices 5-7. Human: physical Ghostty QA of /appearance \u203a Ghostty shaders.",
+  "slice3": {
+    "branch": "feature/ghostty-native-shaders-20261028",
+    "base": "de2afd0254327390205a5cde62af5d886f8efaaf",
+    "pr": "stacked draft PR targeting feature/kitty-native-shaders-20261028 (see progress)",
+    "source_manifest_sha256": "4f0f9e10b9a98000bb2d1d38b13f665c42235e5f91aa5597f1fca02b6404d063",
+    "tests": "canonical 4648/4662 pass, 0 fail, 13 skipped, 1 todo; focused 132/132; live 1.3.1+1.4.0 12/12; tsc clean",
+    "review": "Codex gpt-6.1-sol read-only: no blocker; 5 should-fix + 2 minor fixed with regressions"
+  },
+  "animated_decode": {
+    "branch": "feature/animated-image-decode-20261028",
+    "commits": [
+      "86aad528",
+      "ca90b2bc"
+    ],
+    "tests": "graphics 113/113 under guard",
+    "review": "Sonnet: no blocker; should-fix items fixed by Codex follow-up"
+  },
+  "mermaid_ci": {
+    "failure": "#516 run 40656373289 browserConsoleChrome.test.ts:106 (not rerun)",
+    "diagnosis": "mermaid-diag/REPORT.md (Codex + lead addendum)",
+    "local": "pinned mermaid@12.2.0, 3/3 pass at dev c690de05+diag and at #516 de2afd02",
+    "diag_commit": "9270894 on local diag/mermaid-ci-20261028 (unpushed)",
+    "verdict": "not reproduced; deadline-under-load hypothesis unproven"
+  }
 }

docs/development/native-appearance-welcome/DECISIONS.md

@@ -31,3 +31,16 @@ Ruling: Ghostty version-tagged source loads legacy config before preferred confi
 Ruling: preserve the existing Theme Bridge ledger design concept but isolate host ownership records; Theme Bridge targets and current write primitives do not provide this transaction/dependency contract. Use exclusive staging, captured file identity/content, checks before staging and immediately before rename, and rollback of only unchanged task writes. POSIX rename is not atomic compare-and-swap; do not claim protection against arbitrary concurrent malicious directory swaps. Group/world-writable paths are refused.
 
 Ruling: preserve valid unchanged numeric blur above the normal UI range during unrelated saves. Require nonnegative safe integers in generated data; UI normally caps increases at50 but can decrease a larger existing value incrementally. Display bars clamp without changing stored values.
+
+## Slice 3 rulings (Ghostty native shaders, 2026-10-28)
+
+- NMSh writes its OWN GLSL (GPL-3.0-only, original code) generated from validated settings; no third-party shader is copied or downloaded. Seven presets: Smear and Comet trails (one at a time), Aurora (background-only tint), Dim when unfocused, Vignette, Scanlines, Text glow. Every parameter is compiled in as a constant and a test proves each one changes the source. Values are validated, never clamped.
+- Version gates come from the uniforms each generated shader actually reads (scanned, comments stripped), against a table verified byte-for-byte: 1.2 = cursor uniforms; 1.3/1.4 add focus, cursor style/visibility and terminal colors (identical prefix in 1.3.0, 1.3.1, 1.4.0). No reported version (tmux, ssh: *hidden*), <1.2, or anything newer than 1.4.x (an unverified interface) fails closed for new setup. Sync substitutes the version recorded at review only when the running version is hidden; a running version known to be unsupported makes sync remove NMSh's passes and say why.
+- Composition: Ghostty's custom-shader list is append-only and NMSh's fragment is an optional include (`config-file = ?…`) appended to the effective root file, so NMSh's passes run after every pass in the person's root files. NMSh never writes a `custom-shader =` reset, never re-lists or reorders the person's passes, and never sets `custom-shader-animation` (the older /cursor fragment did; the studio only reads and discloses it). A simulation of the whole configuration graph must show the person's passes unchanged and in order and NMSh's passes present in order, or the plan is refused (e.g. a later include that clears the list).
+- Placement: Kitty's Before/After choice has no Ghostty equivalent without re-listing the person's passes (which would make NMSh own lines it did not write); Ghostty always runs NMSh's passes after. Disclosed in the studio.
+- Never two trails: a trail pass refuses when any of the person's shaders reads the cursor-change uniforms, or when one cannot be read (outside the home, symlink). NMSh's older /cursor Ghostty shader is paused (its own managed file, exact content checked) while a studio trail is written; the ledger records `legacyPaused`, and the reviewed removal resumes it inside the same transaction only if the file still holds exactly the paused content and /cursor's settings still want it (otherwise the review says it is left alone). The studio never calls /cursor's writer outside its transaction. Cursor backends: a written studio trail makes Ghostty draw Smear/Tail and Portable draw effects.
+- Reload: Ghostty never reloads its config by itself and NMSh never signals it. A trail NMSh stops writing (Portable chosen, motion off, Reduced Motion, removal, the older /cursor shader paused) is recorded as pending; while pending, Portable draws no cursor motion (and no effects if the older /cursor shader drew them) so a not-yet-reloaded Ghostty trail is never doubled. Pending trails accumulate across changes until a reload (legacy → Smear → Comet keeps the older /cursor shader, and its effects, pending). Pending clears when the person presses L in the studio, or when the Ghostty process found among NMSh's parents started after the change. If the record cannot be saved, the controller keeps it in memory for this process. A studio trail still written while Portable is chosen (a refused update) also suppresses Portable motion.
+- Launch: the Ghostty process among NMSh's parents is read (one bounded `ps`); `--custom-shader`, `--config-file`, `--config-default-files` on its command line refuse. Not finding Ghostty (tmux, ssh, session service) is a disclosed note, not a refusal (GUI launches carry no flags).
+- Architecture: TerminalApp must not mention host products (existing guard test). All Ghostty wiring lives in `src/appearance/glslStudio.ts`; the Kitty panel and the Ghostty panel are one shared `ShaderStudioPanel` with host wording supplied per host. The footer wraps with the shared `renderControlRows`.
+- Sync: gate changes rewrite only NMSh-owned files; removing passes never waits for review; adding reviewed passes back re-simulates. Inside tmux (hidden version) sync uses the version recorded at review, so it never strips passes for an unrelated reason. NMSh also syncs once at startup (no process-table read), so gate changes made while it was not running (OS Reduced Motion, an edited config) reach the written passes.
+- Animation disclosure: Ghostty runs its animation loop whenever any custom shader is listed (focused surface by default; `always` = every surface; `false` = only on terminal updates). Every plan discloses this; no preset claims to redraw "only while it fades".

docs/development/native-appearance-welcome/HANDOFF.md

@@ -1,5 +1,14 @@
 # Native appearance and Welcome Studio handoff
 
+## Slice 3 state (Ghostty native shaders) — read first
+
+- Branch `feature/ghostty-native-shaders-20261028` (worktree `/Volumes/T7Tmp/ai-dev/worktrees/notMyShell/ghostty-native-shaders-20261028`) is stacked on Slice 2 `feature/kitty-native-shaders-20261028` @ de2afd02 (PR #516, draft). Its draft PR targets the Slice 2 branch; retarget only after review, never automatically.
+- Code map: `src/appearance/ghosttyShaderCatalog.ts` (version table, uniforms, presets, GLSL generation), `src/appearance/ghosttyShaders.ts` (inspection, effective-list simulation, compose/plan/apply/remove, sync, reload-pending, launch inspection), `src/appearance/glslStudio.ts` (app controller; TerminalApp never names hosts), `src/appearance/ShaderStudioPanel.ts` (shared Kitty/Ghostty studio), `GhosttyShaderPanel.ts`, cursor integration in `cursor/backends.ts` (`GHOSTTY_TRAIL_BACKEND`, pending suppression) and `cursor/native.ts` (legacy fragment pause).
+- Owned files (host-appearance dir): `ghostty-shaders.conf`, `ghostty-shaders/<id>.glsl`, `ghostty-shaders.json` (ledger), `ghostty-reload.json` (pending trails), plus one hook `config-file = ?…ghostty-shaders.conf` at the end of the effective root config.
+- Next slices (all still required): 4 render routing (semantic surfaces → native/portable/off with reasons; native only for cursor trail and host focus) + Chroma-driven native colors via `idleStops`; 5 Shader Studio UX with previews; 6 Welcome Studio (uses the animation decoder branch); 7 integration, performance, QA, docs.
+- Known follow-up (Slice 2 scope, not fixed here): Kitty integrated with motion Smear may draw Kitty's tail while Portable draws smear.
+- Physical Ghostty/Kitty/Zed QA: NOT RUN. GPU rendering: NOT verified.
+
 ## Slice 2 state (Kitty native shaders) — read first
 
 - Slice 2 branch `feature/kitty-native-shaders-20261028` (worktree `/Volumes/T7Tmp/ai-dev/worktrees/notMyShell/kitty-native-shaders-20261028`) is stacked on Slice 1 `feature/appearance-welcome-20261028` @ 4abd014d (PR #515, draft, unmerged). Its PR targets the Slice 1 branch so the diff is Slice 2 only; after #515 merges, rebase/retarget to `dev` only after review — never automatically.

docs/development/native-appearance-welcome/INDEPENDENT_REVIEW.md

@@ -30,3 +30,15 @@ Should-fix, all FIXED with regressions:
 
 Minor, handled: `~user/` entries refuse (not guessed); R works on unsupported Kitty; confirmation re-plans and refuses if gates/files changed since the review; opening the studio applies gate changes made while NMSh was not running.
 Minor, documented only: symlinked user pipelines refuse (safe, by design of Slice 1 reads); `ps` launch check can block up to 2 s on open/review/sync; Unicode-space splitting in `shellWords` differs from shlex (resolution only; raw value preserved); `unitPair` accepts hex numbers Kitty rejects (user pipelines only; NMSh never emits them).
+
+## Slice 3 (Ghostty native shaders) — Codex gpt-6.1-sol, read-only, 2026-10-28
+
+Full review: evidence `slice3-review/REVIEW.md`. No blocker. All items fixed by the lead with regressions:
+
+1. Should-fix: successive trail changes replaced the pending record (legacy → Smear → Comet lost the /cursor shader). Fixed: pending trails accumulate; 'nmsh-cursor' wins.
+2. Should-fix: a refused sync or unsaved reload record let Portable draw over a written trail. Fixed: a written studio trail suppresses Portable motion whenever native does not handle motion; in-memory fallback in the controller.
+3. Should-fix: studio confirm called /cursor's writer outside the reviewed transaction. Fixed: removed; ledger `legacyPaused`; removal resumes the exact paused fragment in the same transaction, or says it was left alone.
+4. Should-fix: no startup reconciliation. Fixed: one sync at app construction (no process-table read).
+5. Should-fix: sync substituted the recorded version for an explicitly unsupported running version. Fixed: `hidden` capability; >1.4.x fails closed; sync removes passes with the reason.
+6. Minor: Smear note claimed redraws only while fading. Fixed; every plan discloses Ghostty's animation loop.
+7. Minor: short windows hid the reload warning. Fixed: compact pending line.

docs/development/native-appearance-welcome/RESEARCH.md

@@ -54,3 +54,13 @@ Correction from independent source review: the Ghostty1.4.0 default roots load l
 Installed/staged host apps remain untouched. The attempted staged +show-config invocation does not accept generic configuration CLI flags in this action; its exit1 is retained and is not host parse/GPU validation. Do not retry it and claim validation from docs alone.
 
 Kitty0.49.2 installed catalog probe (headless, private HOME): read_kitty_resource("shaders/custom/pond-ripple.pipeline") returns the shipped event-driven pipeline even though loose .pipeline files are absent. kitty.constants lists list_kitty_resources(package='kitty') and read_kitty_resource(name,package_name='kitty'); top-level listing does not recurse. pkgutil.get_data returned no pipeline, and inspect.getsource failed for frozen code. A future bounded helper should use the terminal's packaged resource API or native named catalog lookup, not advertise missing capability based solely on loose paths. Direct read succeeded; no GPU compile/render/physical QA claim.
+
+## Slice 3 research (verified 2026-10-28; evidence slice3-probe/)
+
+- Installed Ghostty 1.3.1 and staged signature-verified 1.4.0: the compiled-in shadertoy prefix (`strings`) matches source `src/renderer/shaders/shadertoy_prefix.glsl` at v1.3.0, v1.3.1 and v1.4.0 (sha256 8cb58b8b…, identical). v1.2.0 (887bffa3…) lacks iCurrentCursorStyle, iPreviousCursorStyle, iCursorVisible, iTimeFocus, iFocus, iPalette[256], iBackgroundColor, iForegroundColor, iCursorColor, iCursorText, iSelectionForegroundColor, iSelectionBackgroundColor and the CURSORSTYLE defines. Release notes: 1.3.0 "custom shaders have many new uniforms"; 1.4.0 "no longer receive swapped selection foreground and background color uniforms" (a value fix, same interface).
+- `custom-shader` is a RepeatablePath (src/config/path.zig, same semantics 1.2.0–1.4.0): an empty value clears the list; `?` marks optional; surrounding quotes stripped; `?` alone or `""` is ignored (no reset); relative paths resolve against the defining file's directory (realpath), `~/` expands with HOME. Config.zig declaration text identical in 1.3.1 and 1.4.0. `custom-shader-animation` = true (default; focused only) | false | always.
+- Shader compile errors are logged on Ghostty's render thread, never as config errors; NMSh cannot observe them and says so.
+- `ghostty +validate-config --config-file=<f>` loads only that file and its includes (validate_config.zig v1.3.1/v1.4.0): a safe, isolated syntax check used by tests/ghosttyShadersLive.test.ts. `+show-config` on macOS read the REAL `~/Library/Application Support/com.mitchellh.ghostty/config` despite a private HOME (observed: font-size 14 and an existing NMSh appearance include appeared); read-only, nothing written, and NOT used by tests.
+- Observed ordering with `+show-config` (both versions): root `config` → root `config.ghostty` → macOS roots → include queue in encounter order; relative include and shader paths resolved per file.
+- Compile check: Kitty's bundled `slangc -lang glsl -allow-glsl -stage fragment -target spirv` compiles prefix+shader (rejects re-declaring gl_FragCoord, so that one prefix line is dropped). It accepts every NMSh preset and rejects a 1.3-only preset against the 1.2 prefix and real type errors. It is a PROXY: Ghostty uses glslang + SPIRV-Cross/Metal; GPU output is not verified.
+- Third-party shaders (sahaj-b/cursor-shaders MIT, hackrdotsh/ghostty-shaders unverified) were not downloaded, executed or used; NMSh's presets are original.

docs/development/native-appearance-welcome/TEST_RESULTS.md

@@ -52,3 +52,17 @@ Source: branch feature/kitty-native-shaders-20261028 from 4abd014d. All Kitty ru
 - Source manifest unchanged after verify (only docs edited since).
 
 NOT RUN: physical Kitty/Ghostty/Zed QA, GPU rendering, performance measurement, Ghostty shader work.
+
+## Slice 3 — Ghostty native shaders (Claude, 2026-10-28)
+
+Source: branch feature/ghostty-native-shaders-20261028 from de2afd02. Every automated run used private HOME/XDG/NMSH config dirs; no real Ghostty config, window or installed app was touched. Evidence: `/Volumes/T7Tmp/ai-dev/nmsh-native-appearance-welcome-20261028/` (slice3-probe/, logs below).
+
+- `t7run --check`: PASSED (after clearing regenerable caches on T7 at the user's request: node-compile, pycache, clang-module).
+- Probes: shader prefixes of Ghostty v1.2.0/v1.3.0/v1.3.1/v1.4.0 compared (1.3.0–1.4.0 identical); path.zig / validate_config.zig / Config.zig read; installed 1.3.1 and staged signature-verified 1.4.0 used headlessly (`+validate-config --config-file`) only.
+- Live (tests/ghosttyShadersLive.test.ts, both binaries via NMSH_TEST_GHOSTTY_BINARIES): uniform table equals each binary's compiled-in prefix; `+validate-config` accepts NMSh's composed config; slangc (Kitty-bundled) compiles every preset against its prefix and rejects a 1.3-only preset against the 1.2 prefix. PROXY compile only: Ghostty's own glslang/SPIRV-Cross/Metal path and GPU output NOT verified.
+- Independent Codex review: no blocker; 7 items fixed with regressions (INDEPENDENT_REVIEW.md).
+- Focused after fixes: ghosttyShaders, ghosttyShaderPanel, ghosttyShadersLive, kittyShader*, cursor*, appearanceHub, hostAppearance*, hostIntegration — 132/132 (slice3-fixes-2.log); live on 1.3.1 + 1.4.0 with hostProfiles 12/12 (slice3-fixes-live.log); tsc clean; diff --check pass.
+- Canonical `npm run verify` on source manifest 4f0f9e10… (slice3-canonical-verify.log): build and typecheck passed; tests 4662, pass 4648, fail 0, skipped 13, todo 1 (existing Arcade TODO); diff --check passed; exit 0. Manifest unchanged afterwards. A clean local canonical pass.
+- Mermaid (#516 run 40656373289, browserConsoleChrome.test.ts:106): not rerun in CI; local controlled runs 3/3 pass at dev+diagnostic and at #516 (mermaid-diag/REPORT.md). Unexplained in CI; deadline-under-load hypothesis, not proven.
+
+NOT RUN: physical Ghostty/Kitty/Zed QA, GPU rendering, performance measurement.