Kitty shaders: compose Kitty 0.49 shipped effects with the user's own (stacked on #515)

CHANGELOG.md

@@ -8,6 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- **Kitty shaders in `/appearance`** (Kitty 0.49 or newer; [#399](https://github.com/raiseCatError/notMyShell/issues/399)). In Kitty, `/appearance` › **Kitty shaders** offers the GPU effects Kitty itself ships — Default, Blaze, Lightning and Motion-blur cursor trails (one at a time), Northern Lights, Matrix, Fireworks, Pond Ripple, Spotlight, Focus highlight, Dim inactive windows, Tab change and CRT — read from the installed Kitty, with the settings each installed shader really declares (durations, colors, intensity, speed…) in safe ranges. Effects are off until you choose them; Enter toggles, ←→ adjusts, Shift+↑↓ orders, and **S** shows the exact files and the resulting `custom_shaders` list before anything is written. Your own `custom_shaders` are kept exactly as written and in order, with NMSh's pipeline after (or before) them; NMSh refuses instead of guessing when it cannot prove that (dynamic includes, Kitty launch overrides, unreadable pipelines, a shader of yours replacing a shipped one, shared textures, a second cursor trail, more than 16 shader groups). **R** removes NMSh's files and its one include line, restoring your file byte for byte. Reduced Motion, Decorative effects Off and a Portable cursor take NMSh's effects (or its trail) back out of Kitty's pipeline. Effects cover the whole Kitty window, not only NMSh; saving configuration is not proof of GPU output. In `/cursor`, Host native setup on Kitty opens this screen, and a Kitty trail shader means NMSh never draws a second trail.
 - **Console for the browser preview** ([#466](https://github.com/raiseCatError/notMyShell/issues/466); [design](docs/design/document-workspace.md#console-runtime-diagnostics-of-the-browser-preview)). In the Chromium preview of a Markdown or HTML document, **`C`** lists what the page itself reported for the document now loaded: script exceptions, `console` errors, warnings and messages, failed loads and HTTP errors, Content Security Policy refusals and requests NMSh refused. It works like Problems — newest first, Tab filters by severity, typing searches, Shift+↑↓ marks, Del clears, Ctrl+C shows exactly what would be copied before copying — and Enter goes to the line in the file when that is certain (an HTML document unchanged since the page loaded); otherwise it says why. The Console only reads: it never turns scripts or the network on (with scripts off, only loading and policy messages appear), accepts no expressions, and ignores `/browser` pages and the Mermaid renderer. Entries stay in memory for the current load, bounded, with the preview's address, query values, tokens and likely secrets redacted before they are kept. The status line counts errors and warnings.
 - **`/doctor` reports document rendering** ([#462](https://github.com/raiseCatError/notMyShell/issues/462)). A Documents section names the Chrome or Chromium the previews would use (its version once a browser surface has checked it this session, and whether it is running), the Mermaid it found (path, version, a warning for a major version other than the tested 12), the Mermaid setting and, when diagrams would not be drawn, why. Nothing is launched and the Mermaid bundle is not read, so it says what was found, not that drawing works.
 - **Mermaid diagrams in Markdown** ([#462](https://github.com/raiseCatError/notMyShell/issues/462); [design](docs/design/diagrams.md)). A ```` ```mermaid ```` fence is drawn as a real diagram — flowcharts, sequence, class, state, ER, Gantt, pie, journey, git graph, mind map, timeline, quadrant, XY, requirement, Sankey, block and C4 diagrams — in Preview (NMSh's renderer and the Chromium preview), Split's preview pane, the viewer and Hybrid's inactive blocks, with the image backend your terminal supports (Kitty graphics, iTerm2, Sixel, or character art); `i` opens it in the image viewer to zoom and pan. NMSh uses the Mermaid you installed (`npm install -g mermaid`, or `NMSH_MERMAID`) inside the real browser it already drives, and downloads nothing. The page that draws runs no document script, loads nothing from the network or disk and returns only pixels; Mermaid's security settings are locked against directives. Settings → General → **Mermaid diagrams**: *On request* (default: press `D`, or F1 › Diagrams while editing — opening a document never starts a browser), *Automatic*, or *Off*. The fence stays the source: in Hybrid the block under the caret is its exact text, edits are drawn after a pause, and anything not drawn (not asked yet, no browser or Mermaid, a syntax error, too large, a timeout) shows the fence as written with `(diagram not drawn: reason)`. Drawings are cached by content and theme, bounded in number, bytes and time, and the renderer page closes when no document shows a diagram.
@@ -25,6 +26,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - **Markdown editing helpers in `/edit`** ([#463](https://github.com/raiseCatError/notMyShell/issues/463), first slice; Markdown files only). **Enter** continues a bullet, numbered or task list (same marker and indentation, next number, unchecked box) and splits an item at the caret; on an empty item it ends the list (a nested one steps out a level). **Tab / Shift+Tab** on list items indent or outdent the item with its children (selected items together); elsewhere Tab is a tab as before. **F1** opens the Markdown actions: toggle a task checkbox, renumber the list at the caret, insert a link or image around the selection, wrap the selection in bold, italic, code or strikethrough (again to unwrap). Every action changes only the lines it names and is one undo step; text is never reflowed or regenerated.
 - **Crash recovery for `/edit` and the document workspace** ([#469](https://github.com/raiseCatError/notMyShell/issues/469)). Unsaved changes are written, a moment after you stop typing, to a private draft in NMSh's data folder (`recovery/`, mode 0700; files 0600). After a crash, a kill or a closed window, opening the file offers **Restore draft**, **Compare with file**, **Discard draft** or **Keep for later**; nothing is applied until you choose, a draft made from an older version of the file says so, and the file itself is only ever written by the editor's normal checked save (which also retires the draft). Two windows on one file keep separate drafts, and a draft of a window that is still running is never offered. Drafts are bounded (2 MiB each, 50 in all, 30 days) and are never sent anywhere.
 
+### Fixed
+
+- With the Portable cursor renderer, NMSh's Kitty cursor setup no longer leaves Kitty's own `cursor_trail` on, which drew two trails.
+
 ## [0.23.0] - 2026-10-21 — Vespyr Arcade
 
 The Arcade grows from five games to 33, and it can now be played while a command keeps running.

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

@@ -0,0 +1,14 @@
+{
+  "phase": "Slice 2 (Kitty native shaders) implemented, reviewed, canonically verified (1 load-induced live timeout, passes alone); committed on feature/kitty-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)",
+    "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"},
+  "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."
+}

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

@@ -1,5 +1,16 @@
 # Architecture findings and recommended direction
 
+## Slice 2 rulings (Kitty native shaders, 2026-10-28)
+
+- NMSh generates its OWN pipeline file (absolute path under NMSh's config folder) rather than naming shipped pipelines: each preset's shipped group structure (events, curve, step, textures, attach, output) is copied from the installed resource, and shipped pipeline-level vars move into each group. NMSh never emits pipeline-level vars (Kitty would apply them to the user's shaders). User pipeline-level vars that would leak into NMSh's groups are pinned back to the shipped source literal inside NMSh's groups.
+- One NMSh-owned `custom_shaders` line holds the user's effective value VERBATIM (raw text, original quoting) plus NMSh's quoted pipeline path, after (default) or before it. A simulation through the real configuration graph must show that exact list as effective, from NMSh's fragment, or the plan is refused. Earlier shadowed lines are disclosed, not refused (Kitty's semantics are deterministic).
+- Refuse (no write) when preservation or safety cannot be established: dynamic includes, Kitty launch overrides (`-o custom_shaders|cursor_trail`, `--config`; `ps` of KITTY_PID and `macos-launch-services-cmdline`; unreadable launch state also refuses), unbalanced quoting/control characters, user pipelines that are unreadable/unparseable/outside home, a user `.slang` that would replace a shipped shader NMSh tunes, named-texture overlap, a second cursor trail, more than 16 groups, an unrecorded or duplicated hook, edited/unowned NMSh files. A user entry Kitty cannot find is kept as written with a note (Kitty already skips it).
+- Drift: the ledger records the user's value composed with. If it changes later (Kitty keeps loading NMSh's reviewed copy), the studio says so and sync refuses; a new review recomposes. This is the unavoidable cost of Kitty's single value; it is disclosed rather than hidden.
+- Parameters: NMSh curates labels and SAFE bounds; a parameter is offered only if the installed shader declares it with the expected type and a literal default (the shipped pipeline's own value wins). Values are validated, never clamped at plan time. Presets without exposed constants say so.
+- Gates: Reduced Motion and Decorative Effects Off write nothing new and, after setup, sync removes every NMSh group (the fragment then sets no custom_shaders, so the user's own value applies). A Portable cursor renderer removes NMSh's Kitty trail group. Sync rewrites only NMSh-owned files after the reviewed setup, mirroring the existing /cursor managed-file contract, and refuses on drift.
+- One cursor engine: /cursor still decides whether there is a trail (Motion) and its color; the Kitty studio decides Kitty's trail style. A written Kitty trail shader makes Kitty native own the trail (Portable skips motion); the Lightning trail also owns the Lightning effect. Fixed an existing bug: NMSh's Kitty cursor fragment kept `cursor_trail 3` with the Portable renderer (two trails).
+- First offered presets: Default/Blaze/Lightning/Motion-blur trails (one at a time), Northern Lights, Matrix, Fireworks, Pond Ripple, Spotlight, Focus highlight, Dim inactive windows (exclusive with Focus highlight: same shader), Tab change, CRT (opacity note). Other installed pipelines are listed as "installed, not offered yet".
+
 The human explicitly approved this implementation direction and waived the design-document approval gate. Recommendations below guide implementation; meaningful trade-offs are recorded here.
 
 - Reuse PromptConfiguration and current canonical editors. AppearanceHub launches canonical editors, not copies. Extend cursor/native and existing host integration rather than create contradictory persistence.

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

@@ -1,5 +1,13 @@
 # Native appearance and Welcome Studio handoff
 
+## 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.
+- Code map: `src/appearance/kittyShaderCatalog.ts` (Kitty-parity parser, constants, curated presets, `kitty +runpy` discovery), `src/appearance/kittyShaders.ts` (inspection, composition, refusals, ledger, plan/apply/remove, sync, launch inspection, `writtenKittyTrail`), `src/appearance/kittyShaderSettings.ts` (persisted `hostShaders.kitty`), `src/appearance/KittyShaderPanel.ts` (studio UI), wiring in `TerminalApp.ts` (`openKittyShaders`, `handleKittyShaderKey`, `syncKittyShaderFiles`, `addKittyShaderRow`), hub row in `AppearanceHub.ts`, cursor ownership in `cursor/backends.ts` (`kittyTrail`, `KITTY_LIGHTNING_BACKEND`) and the Portable `cursor_trail` fix in `cursor/native.ts`.
+- Owned files (macOS default): `~/Library/Application Support/notMyShell/host-appearance/kitty-shaders.{conf,pipeline,json}` plus one recorded hook `# NMSh Kitty shaders …` / `include …kitty-shaders.conf` at the end of the effective kitty.conf.
+- Next slices (all still required): Ghostty GLSL backend enhancements; GPU-enhanced prompt/Chroma/Clean-Rich/completion feedback (only where documented targeting exists); full Shader Studio (remaining catalog: crt-blue, fireworks-rockets, bloom/tft/water/underwater/negative shaders, per-preset viewport); animated Fastfetch/Neofetch and imported logos; Welcome Studio; real full-terminal animated welcome preview; integration, performance and physical QA.
+- Physical Kitty/Ghostty/Zed QA: NOT RUN. GPU rendering: NOT verified (headless compile only).
+
 ## Objective and required scope
 
 Implement native GPU Shader Studio and host appearance, plus a comprehensive Welcome Studio under /appearance. /cursor and /welcome must open canonical editors. Preserve persistent zsh/Bash/Fish PTY, input ownership, raw output, copy, viewport and existing settings. No duplicate engines or contradictory Clean/Rich, Chroma, cursor or welcome settings.

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

@@ -17,3 +17,16 @@ No blocker. Both new fixes verified correct by reading (`withoutHook` LF/CRLF/em
 - should-fix 2 (plausible): Kitty on macOS also reads `~/Library/Preferences/kitty/kitty.conf`; Kitty uses the FIRST existing config directory, unlike Ghostty's all-roots load. Verify against installed Kitty 0.49.2 (`kitty.constants.config_dir` logic) before changing hostPaths/readHostConfiguration.
 - minor: removal preview omits a restored line break; hub guidance not re-rendered after async read when hub closed; tiny window after apply where hub shows pre-write values; rename drops hardlinks/xattrs; stale XDG path blocks removal (fails closed). Recorded, not fixed in Slice 1.
 - Resolution: should-fix 1 FIXED (removal with the hook already absent deletes only the hash-verified fragment and ledger; the host file is a dependency, not changed). should-fix 2 CONFIRMED by probing installed Kitty (kitty-config-dir-evidence.md) and FIXED (worse than reported: Kitty would have loaded a new hook-only XDG file instead of the user's Preferences config). Minor items remain documented.
+
+## Slice 2 review (2026-10-28, separate read-only Sonnet reviewer, uncommitted diff on 4abd014d)
+
+Reviewer read the diff against Kitty v0.49.2 `slang.py`, ran tsc and the two focused files (pass). No blocker.
+
+Should-fix, all FIXED with regressions:
+1. Removal refused when an owned fragment/pipeline was missing or hand-edited; and sync refused (drift, launch, inspection problems) even when the gates left no NMSh effect, so Reduced Motion could not turn effects off. → removal is lenient (deletes intact owned files, keeps an edited one unreferenced, skips a missing one, removes hook + ledger); taking every NMSh effect out writes NMSh-owned files directly, regardless of drift or launch state; adding reviewed groups back skips the launch re-check but still refuses on drift.
+2. A written Kitty trail with cursor_trail 0 made Portable stop drawing while Kitty drew nothing. → `writtenKittyTrail` requires the recorded hook present, an active fragment, a trail group AND effective cursor_trail > 0; cursor facts are refreshed when NMSh's Kitty cursor fragment changes.
+3. A failed/unsupported catalog read was cached for the process (and a rejection could leave the panel stuck). → only supported catalogs are cached; failures retry; rejections become an unsupported catalog.
+4. One failing build disables the whole shared `end` slot (user shaders too). → disclosed in the review guidance; leaked vars that NMSh cannot pin (multi-line or repeated declarations) now refuse instead of being missed.
+
+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).

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

@@ -20,10 +20,10 @@ Interfaces: readHostAppearance(host,context) returns true values/origins/problem
 
 ## Slice2: real native shader backends
 Files: cursor/backends.ts/native.ts, new appearance shader catalog and host-specific pipeline generators; deterministic backend/config tests.
-- [ ] Test version detection, installed catalog checks, controls, ordering/texture/event validation, opacity conflicts and no duplicate trail.
-- [ ] Implement Kitty Slang/pipeline and Ghostty GLSL as distinct generators, referencing installed shipped sources when safe; original/community sources require provenance/individual license review.
-- [ ] Add curated controls/persistence and safe ownership-based configuration plans; unknown/unconfigured hosts and Portable choice remain truthful.
-- [ ] Verify host compilation in private configs where possible; distinguish files/compilation from physical rendered output. Review and open separate PR.
+- [x] Test version detection, installed catalog checks, controls, ordering/texture/event validation, opacity conflicts and no duplicate trail. (Kitty)
+- [x] Kitty Slang/pipeline generator referencing installed shipped shaders by name (kittyShaderCatalog.ts, kittyShaders.ts). [ ] Ghostty GLSL enhancements: next Ghostty slice (separate PR).
+- [x] Curated controls/persistence and safe ownership-based plans for Kitty (KittyShaderPanel.ts, /appearance row, /cursor link); Portable/unsupported states truthful.
+- [x] Kitty headless compile in private config (tests/kittyShadersLive.test.ts); NOT GPU rendering. Review and stacked PR: see TEST_RESULTS/HANDOFF.
 
 ## Slice3: semantic animation integration
 Files: motion/transitions.ts, existing Chroma/motion/cursor/queue/prompt/notification/idle call sites and tests.