[raiseCatError]

Stacked PR. Base is feature/appearance-welcome-20261028 (#515, draft, unmerged), so this diff is Slice 2 only. After #515 merges, this will be rebased or retargeted to dev after review. That step is not automatic. Do not merge before #515.

Refs #399

What it adds

• /appearance › Kitty shaders, shown in Kitty only. It covers the shipped effects read from the installed Kitty 0.49+ through its packaged-resource API:
  • four cursor trails (Default, Blaze, Lightning, Motion blur), one at a time
  • Northern Lights, Matrix, Fireworks
  • Pond Ripple, Spotlight
  • Focus highlight, Dim inactive windows, Tab change
  • CRT
• Settings: each one is offered only when the installed shader declares it with the expected type. It starts from the shipped value and is checked against NMSh's bounds. Presets with nothing adjustable say so, and other installed pipelines are listed as not offered yet.
• Controls: toggle, adjust, reorder (Shift+↑↓), and place NMSh's effects before or after the user's own. S shows the exact files and the resulting effective custom_shaders list before any write. R removes NMSh's part.
• Generated files:
  • NMSh's own .pipeline copies the shipped group structure and keeps every value group-scoped, because Kitty leaks pipeline-level vars into every chained pipeline.
  • One owned custom_shaders line keeps the user's effective value verbatim and in order.
  • A simulation through the real config graph must show exactly that list, or setup refuses.
• Refusals:
  • dynamic includes
  • -o custom_shaders|cursor_trail or --config launch overrides (read from ps of KITTY_PID and macos-launch-services-cmdline)
  • unreadable or unknown user pipelines
  • a user .slang that would replace a shipped shader
  • shared named textures, a second cursor trail, more than 16 groups
  • an unrecorded or duplicated hook, edited or unowned files
• Writes: Slice 1's snapshot-verified transaction and an ownership ledger. Removal restores the user's bytes, even when an owned file was deleted or hand-edited.
• Motion gates: Reduced Motion, Decorative effects Off and a Portable cursor take NMSh's effects, or its trail, out of the pipeline. Taking effects out never waits for a review. Drift in the user's own custom_shaders is reported, and adding effects back then needs a new review.
• /cursor: Host native setup on Kitty opens the studio. A written Kitty trail with cursor_trail on makes Kitty own the trail (and Lightning), so Portable never draws a second one.
• Fix: NMSh's Kitty cursor fragment kept Kitty's own trail on with the Portable renderer, which drew two trails.

Testing

• tests/kittyShaders.test.ts, tests/kittyShaderPanel.test.ts: grammar parity, catalog and version gate, validation, composition and preservation, the refusal matrix, symlink and permission paths, drift, gates, removal, stale files and rollback, launch parsing, panel keys and rendering, and the TerminalApp flow. They run in private homes.

• tests/kittyShadersLive.test.ts runs only when Kitty 0.49+ is installed, so CI skips it. In a private HOME, config and cache, Kitty 0.49.2's own load_config sees exactly the composed list, through an include and a path containing a space. Kitty's bundled slangc compiles the 7 merged groups. This is headless compilation, not GPU rendering.

• Canonical npm run verify locally on the frozen source, results below. Not a clean pass.

  Tests	Pass	Fail	Skipped	Todo
  4636	4621	1	13	1

  • The failure is outputSelectionLive "live fish: new Copy navigation…", a startup timeout waiting for echo READY under suite load. That file passes 3/3 alone.
  • The todo is the existing Arcade one.

• An independent review found no blocker. Its four should-fix items were fixed with regressions (see docs/development/native-appearance-welcome/INDEPENDENT_REVIEW.md).

Not done / not verified

• Physical Kitty, Ghostty and Zed QA: NOT RUN. GPU output: not verified.
• Still required in later slices: Ghostty GLSL enhancements, GPU prompt/Chroma/Clean-Rich/completion feedback, the full Shader Studio (the rest of the catalog), animated fetch logos, Welcome Studio, a full-terminal welcome preview, and performance and physical QA.