feat(core): classify subset rules as guarantee or deferred

Every NS rule in the diagnostics catalogue carries class: "guarantee" | "deferred". Guarantee rules protect a core invariant (determinism and replay, fixed shapes, immutability of shared data, the one text representation) and are permanent; deferred rules (NS1011, NS1019, NS1040, NS1042, NS1044) wait on an easing decision and their diagnostics say the capability is deliberately deferred, not impossible. Fix text names the concrete service alternative where one exists: NS1002 (network via the generated client), NS1005 (clock reads), NS1011 (Map/Set transforms), NS1040 (regex matching), NS1041 (JSON parsing returning a typed record). Docs and skills frame the core and services by role: the core is the app's deterministic logic; services do the app's imperative work.
Upgrade scriptc to 0.0.29 (#344 )
2026-08-13 14:08:26 -05:00 · 2026-08-13 13:56:28 -05:00 · 2026-08-13 13:14:16 -05:00 · 2026-08-13 02:00:28 -05:00 · 2026-08-13 01:28:42 -05:00 · 2026-08-12 23:51:19 -05:00
726 changed files with 364944 additions and 45569 deletions
@@ -1,14 +1,14 @@
 #!/usr/bin/env bash
 # Windows canvas smoke under Wine.
 #
-# Exercises the Windows gpu_surface software path (src/platform/windows/
-# webview2_host.cpp: child HWND, WM_TIMER frame events, SetDIBitsToDevice
-# blits) without Windows hardware: cross-compiles examples/ui-inbox for
+# Exercises the Windows gpu_surface Direct2D path (src/platform/windows/
+# webview2_host.cpp: child HWND, WM_TIMER frame events, retained binary
+# packets) under Wine: cross-compiles examples/ui-inbox for
 # x86_64-windows-gnu, runs the .exe under Xvfb + Wine, and asserts against
 # the automation snapshot:
 #
 #   1. snapshot ready=true            (app booted, automation server live)
-#   2. gpu_backend=software           (the SetDIBitsToDevice path is active)
+#   2. gpu_backend=direct2d           (the retained packet path is active)
 #   3. gpu_nonblank=true              (real pixels were presented)
 #   4. widget-click "Add task" -> '4 open'   (automation input mutates state)
 #   5. real X11 click + typing lands in the draft textbox (XTEST -> Wine ->
@@ -116,9 +116,9 @@ app_pid=$!
 poll 180 'ready=true' || fail "snapshot never became ready"
 echo "== ready: $(head -1 "$snap" | cut -d'|' -f1)"

-# ---- 2 + 3: software backend presented non-blank pixels --------------------
+# ---- 2 + 3: Direct2D backend presented non-blank pixels --------------------
 poll 60 'gpu_nonblank=true' || fail "gpu_nonblank never became true"
-poll 10 'gpu_backend=software' || fail "gpu_backend is not software"
+poll 10 'gpu_backend=direct2d' || fail "gpu_backend is not direct2d"
 echo "== canvas: $(grep -o 'gpu_backend=[a-z]*' "$snap" | head -1)" \
  "$(grep -o 'gpu_nonblank=[a-z]*' "$snap" | head -1)" \
  "$(grep -o 'gpu_sample=0x[0-9a-f]*' "$snap" | head -1)" \
@@ -9,7 +9,7 @@
 # the app's trace log:
 #
 #   1. snapshot ready=true                (app booted, automation server live)
-#   2. gpu_backend=software + nonblank    (the canvas presented real pixels)
+#   2. gpu_backend=direct2d + nonblank    (the canvas presented real pixels)
 #   3. widget-click "Start stream"        (fx.spawn launches cmd.exe under
 #                                          Wine; streamed lines land in the
 #                                          model and grow the snapshot)
@@ -118,9 +118,9 @@ app_pid=$!
 poll 180 'ready=true' || fail "snapshot never became ready"
 echo "== ready: $(head -1 "$snap" | cut -d'|' -f1)"

-# ---- 2: software backend presented non-blank pixels ------------------------
+# ---- 2: Direct2D backend presented non-blank pixels ------------------------
 poll 60 'gpu_nonblank=true' || fail "gpu_nonblank never became true"
-grep -q 'gpu_backend=software' "$snap" || fail "gpu_backend is not software"
+grep -q 'gpu_backend=direct2d' "$snap" || fail "gpu_backend is not direct2d"
 echo "== canvas: $(grep -o 'gpu_backend=[a-z]*' "$snap" | head -1)" \
  "$(grep -o 'gpu_nonblank=[a-z]*' "$snap" | head -1)"
 grep -q 'idle' "$snap" || fail "probe did not start idle"
@@ -49,7 +49,7 @@ jobs:
    steps:
      - uses: actions/checkout@v4

-      - uses: mlugg/setup-zig@v2
+      - uses: vercel-labs/setup-zig@v1
        with:
          version: 0.16.0

@@ -15,26 +15,63 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
-      - uses: mlugg/setup-zig@v2
+      - uses: vercel-labs/setup-zig@v1
        with:
          version: 0.16.0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
-      # The TypeScript core suites transpile at build/test time; without
-      # node they skip silently, so CI must provide it.
+      # TypeScript cores compile through the external core compiler at
+      # build/test time; the compiler and the frontend's toolchain both
+      # arrive with this one install (without it the ts-core suites skip
+      # silently, so CI must provide it). No SCRIPTC_NO_CACHE and no
+      # cache action on purpose: hosted runners are ephemeral, so any
+      # per-run compiler cache dies with the VM and runs stay hermetic
+      # across commits by machine lifecycle.
      - run: npm ci --prefix packages/core
+      - name: Service surface tooling and claims
+        run: node --test packages/core/test/surface_tools.test.ts
      - run: zig build test
      - run: zig build validate

+  core-compiler-fences:
+    name: Core Compiler Fences
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: vercel-labs/setup-zig@v1
+        with:
+          version: 0.16.0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      # The exact-pinned external core compiler and the frontend's
+      # toolchain, one install (packages/core/package.json is the one
+      # place the pin lives).
+      - run: npm ci --prefix packages/core
+      # Per-fixture contract artifacts the fixture driver consumes: the effective sidecar plus its generated entry module and compiler profile, under zig-out/core-contracts.
+      - run: zig build stage-core-contracts
+      # Determinism-fence negative control: the pristine markup fixture compiles and its co-emitted sidecar attests deterministic: true, then one injected ambient read (Date.now() in update) must be refused by the profile's fences — proving the fences fire, not merely that clean cores pass under them. The positive batteries (every fixture's e2e suite over its real archive) ride `zig build test` in the Zig Core job; this job holds the refusal half.
+      - name: Determinism fences fire (negative control)
+        run: tests/compiled-core/fence_check.sh .zig-cache/fence-check
+
  macos-webview:
    name: macOS WebView
    runs-on: macos-14
    steps:
      - uses: actions/checkout@v4
-      - uses: mlugg/setup-zig@v2
+      - uses: vercel-labs/setup-zig@v1
        with:
          version: 0.16.0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      # gpu-components is a TypeScript-core app, so its smoke build needs
+      # the frontend compiler and exact-pinned TypeScript toolchain.
+      - run: npm ci --prefix packages/core
+      # The mobile aggregate runs on Linux for Android. Exercise the other
+      # store-capable cross-target here against the real iPhone simulator SDK.
+      - run: zig build test-example-mobile-canvas-lib-ios-store
      - run: zig build test-webview-system-link
      - run: zig build test-webview-smoke
      # Signed-package seal pin: an ad-hoc signed package must pass
@@ -59,12 +96,12 @@ jobs:
    runs-on: macos-14
    steps:
      - uses: actions/checkout@v4
-      - uses: mlugg/setup-zig@v2
+      - uses: vercel-labs/setup-zig@v1
        with:
          version: 0.16.0
      # Percentile perf check: 5 cold launches asserting p90
-      # first-frame latency under NATIVE_SDK_PERF_BUDGET_MS, then 5 steady-state
-      # widget clicks asserting p90 input latency under NATIVE_SDK_PERF_INPUT_BUDGET_MS.
+      # first-frame latency, 5 steady-state widget clicks asserting p90 input
+      # latency, then a reset-scoped retained-animation cadence sample.
      # Its own job so a shared-runner slowdown is visible in isolation and
      # never blocks the correctness smokes.
      # Shared macos-14 runners are far noisier than a dev box (first CI run
@@ -75,13 +112,20 @@ jobs:
        env:
          NATIVE_SDK_PERF_BUDGET_MS: "1500"
          NATIVE_SDK_PERF_INPUT_BUDGET_MS: "500"
+          # The virtual display is commonly 25-35 Hz even though AppKit
+          # reports the window visible. Keep physical/dev defaults at the
+          # strict 60 Hz-class 45/20/34; this hosted job remains a
+          # step-function regression sentinel rather than a display gate.
+          NATIVE_SDK_PERF_ANIMATION_MIN_FRAMES: "30"
+          NATIVE_SDK_PERF_ANIMATION_P90_MS: "50"
+          NATIVE_SDK_PERF_ANIMATION_MAX_MS: "100"

  linux-webkitgtk:
    name: Linux WebKitGTK
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
-      - uses: mlugg/setup-zig@v2
+      - uses: vercel-labs/setup-zig@v1
        with:
          version: 0.16.0
      - name: Install WebKitGTK dependencies
@@ -102,7 +146,7 @@ jobs:
    runs-on: windows-2022
    steps:
      - uses: actions/checkout@v4
-      - uses: mlugg/setup-zig@v2
+      - uses: vercel-labs/setup-zig@v1
        with:
          version: 0.16.0
      # Builds the WebView example with the system engine, compiling the
@@ -112,6 +156,10 @@ jobs:
      # include path, or a conformance error in the embedded layer — is a
      # compile failure here, not a silent WebViewNotFound at runtime.
      - run: zig build test-webview-system-link -Dplatform=windows
+      # Effects.spawn is a pipe-backed background transport. Run its
+      # Windows-only PowerShell probe natively so removing CREATE_NO_WINDOW
+      # cannot leave the platform-neutral and Wine lanes green.
+      - run: zig build test-windows-effects-no-console
      # The registered-font receipt, natively on Windows: runs the
      # font-registry suite — registration validation, the glyph-budget
      # gate, present/reference pixel parity, and the Chinese-receipt
@@ -128,14 +176,15 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
-      - uses: mlugg/setup-zig@v2
+      - uses: vercel-labs/setup-zig@v1
        with:
          version: 0.16.0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
-      # The TypeScript core suites transpile at build/test time; without
-      # node they skip silently, so CI must provide it.
+      # The TypeScript core suites compile through the external core
+      # compiler at build/test time; without the install they skip
+      # silently, so CI must provide it.
      - run: npm ci --prefix packages/core
      - run: zig build test-tooling

@@ -167,14 +216,15 @@ jobs:
            step: test-examples-native-shard-4
    steps:
      - uses: actions/checkout@v4
-      - uses: mlugg/setup-zig@v2
+      - uses: vercel-labs/setup-zig@v1
        with:
          version: 0.16.0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
-      # The TypeScript examples transpile at build time; the transpiler
-      # needs its installed dependency.
+      # The TypeScript examples compile through the external core
+      # compiler at build time; the compiler and the frontend toolchain
+      # arrive with this install.
      - run: npm ci --prefix packages/core
      # Every example test uses the null backend, so this lane needs no
      # GTK/WebKitGTK packages. The root build owns the round-robin shard
@@ -186,7 +236,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
-      - uses: mlugg/setup-zig@v2
+      - uses: vercel-labs/setup-zig@v1
        with:
          version: 0.16.0
      # Declare-to-use, proven on real Windows executables: the
@@ -218,7 +268,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
-      - uses: mlugg/setup-zig@v2
+      - uses: vercel-labs/setup-zig@v1
        with:
          version: 0.16.0
      # Deliberately NO libwebkitgtk-6.0-dev: ui-inbox declares no web
@@ -244,7 +294,7 @@ jobs:
      # C diagnostics on failure, which is exactly the escalation this
      # step pins against. The throwaway cache dir keeps the compile
      # cold: on a cache hit zig replays nothing, stderr included, so a
-      # warm cache (setup-zig restores one) would hide the diagnostics
+      # warm compiler cache would hide the diagnostics
      # this step exists to catch.
      - name: WebKitGTK stub compile is diagnostic-free
        run: |
@@ -300,14 +350,14 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
-      - uses: mlugg/setup-zig@v2
+      - uses: vercel-labs/setup-zig@v1
        with:
          version: 0.16.0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
-      # The scaffold default is the TypeScript core; its transpiler runs
-      # under node at build time from this checkout's packages/core.
+      # The scaffold default is the TypeScript core; its frontend and
+      # compiler run at build time from this checkout's packages/core.
      - run: npm ci --prefix packages/core
      # No WebKitGTK dev package, same as linux-canvas-smoke: the scaffold
      # declares no web use, so its host compiles with the stub seam.
@@ -330,7 +380,7 @@ jobs:
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
-      - uses: mlugg/setup-zig@v2
+      - uses: vercel-labs/setup-zig@v1
        with:
          version: 0.16.0
      - name: Install Wine, Xvfb, and xdotool
@@ -352,8 +402,8 @@ jobs:
            exit 1
          fi
      # Cross-compiles ui-inbox for x86_64-windows-gnu and drives the
-      # gpu_surface software path (child HWND + WM_TIMER + SetDIBitsToDevice)
-      # under Wine: snapshot ready, gpu_backend=software, gpu_nonblank=true,
+      # retained Direct2D packet path (child HWND + WM_TIMER) under Wine:
+      # snapshot ready, gpu_backend=direct2d, gpu_nonblank=true,
      # automation widget-click, and real XTEST pointer/keyboard input.
      # Wineprefix init happens inline in the script (measured 21s from
      # scratch in an ubuntu-24.04 container, so no cache step).
@@ -366,7 +416,7 @@ jobs:
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
-      - uses: mlugg/setup-zig@v2
+      - uses: vercel-labs/setup-zig@v1
        with:
          version: 0.16.0
      - name: Install Wine and Xvfb
@@ -385,7 +435,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
-      - uses: mlugg/setup-zig@v2
+      - uses: vercel-labs/setup-zig@v1
        with:
          version: 0.16.0
      - run: zig build test-examples-frontends
@@ -395,7 +445,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
-      - uses: mlugg/setup-zig@v2
+      - uses: vercel-labs/setup-zig@v1
        with:
          version: 0.16.0
      - run: zig build test-examples-mobile
@@ -405,14 +455,15 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
-      - uses: mlugg/setup-zig@v2
+      - uses: vercel-labs/setup-zig@v1
        with:
          version: 0.16.0
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      # The default scaffold is a TypeScript core: its build runs the
-      # @native-sdk/core transpiler from this checkout's own install.
+      # @native-sdk/core frontend and the external core compiler from
+      # this checkout's own install.
      - run: npm ci --prefix packages/core
      - run: zig build
      - name: Scaffold and test the zero-config native app
@@ -92,7 +92,7 @@ jobs:
        uses: actions/checkout@v4

      - name: Setup Zig
-        uses: mlugg/setup-zig@v2
+        uses: vercel-labs/setup-zig@v1
        with:
          version: 0.16.0

@@ -22,6 +22,7 @@ packages/native-sdk/build.zig.zon
 packages/native-sdk/app.zon
 packages/native-sdk/third_party/
 packages/native-sdk/packages/
+packages/native-sdk/tools/
 packages/native-sdk/LICENSE
 # npm pack output
 packages/native-sdk/*.tgz
@@ -2,6 +2,15 @@

 Guidance for agents (and humans) working on this repository.

+## App authoring default
+
+Native SDK itself is implemented in Zig, but Native SDK **apps are authored in TypeScript + Native markup by default**. Do not infer the app-authoring language from this repository's implementation language or from older Zig-core examples.
+
+- For a new app, use `native init <path>` and expect `src/core.ts`, `src/app.native`, and `app.zon`. Ordinary compiled TypeScript work that needs filesystem, process, JSON, regex, classes, or other static-tier APIs belongs under optional `src/services/`, reached from the core with `Cmd.request`; do not import a service from the core. Do not add Zig app code unless the user explicitly chooses `--template zig-core` or the feature requires a toolkit extension.
+- Before changing an existing app, inspect its tree. A `src/core.ts` app stays TypeScript; a `src/main.zig` app stays Zig unless the task is specifically a migration.
+- For default app work, read `skill-data/native-ui/SKILL.md` and `skill-data/ts-core/SKILL.md`; also read `skill-data/ts-services/SKILL.md` when the tree has `src/services/` or the task needs ordinary TypeScript beyond the core subset. `skill-data/core/SKILL.md` covers shared/runtime concerns; `skill-data/zig/SKILL.md` is for Zig-core apps and SDK implementation work.
+- The `-ts` suffix on a few examples only distinguishes ports from older Zig originals. New TypeScript apps need no suffix because TypeScript is the default.
+
 ## Build, test, and gate

 ```bash
@@ -20,7 +29,7 @@ Pinned goldens (pixel signatures, schema fingerprints, command counts) are updat

 ## Changelog

-Do not edit `CHANGELOG.md` directly. Each user-visible change ships a fragment in `changelog.d/` — see `changelog.d/README.md` for the format and voice. Internal-only polish needs no fragment.
+Do not edit `CHANGELOG.md` as part of regular feature or fix work. The release agent reviews the git history since the previous release and writes the complete changelog entry during release preparation; see [RELEASING.md](./RELEASING.md).

 ## Where things live

@@ -2,12 +2,215 @@

 All notable changes to the Native SDK (formerly zero-native) will be documented in this file.

-## 0.7.0
+## 0.9.0

 <!-- release:start -->

 ### New Features

+- **Ordinary TypeScript services behind a typed boundary**: Apps can place filesystem, process, JSON, regex, class, and exact-vendored npm work under `src/services/`; Native SDK generates the checked client and codecs, compiles a pinned static service executable, and carries keyed requests, typed streaming, cooperative cancellation, deadlines, supervision, and deterministic replay across the isolated boundary (#317, #321).
+- **Optional in-process TypeScript services**: Services can use the same boundary through a linked, runtime-localized worker pool with per-key FIFO ordering, parallel independent keys, streaming, timeout and trap isolation, and replay that never starts the carrier; the explicit opt-in now follows the compiler's Windows, Linux, macOS, and cross-target matrix while the isolated child remains the automatic default (#334, #337).
+- **Engine-owned model persistence**: TypeScript cores can persist committed models through capability-gated, atomically replaced snapshots with generated codecs, debounced writes, backup recovery, explicit restore and migration routes, rollback safety, and journal/replay support (#316).
+- **SQLite record storage**: TypeScript and Zig apps can use a capability-gated record store for deterministic atomic CRUD effects backed by bundled SQLite across desktop and mobile hosts, with devhost parity and a complete Record Store example (#320).
+- **Checked relational SQLite**: Append-only migrations, build-validated named SQL, transactions, generated typed commands and live-query subscriptions, replay, and the Relational Notes example make relational SQLite a first-class offline data layer across desktop and mobile (#326).
+- **Model-driven menu-bar apps**: TypeScript apps can derive status-item labels, icons, tooltips, and rich menus from committed model state, while new macOS effects control hidden startup, fullscreen, Dock visibility, and launch-at-login behavior across both native hosts (#311, #314).
+- **Platform services for TypeScript cores**: Typed effects now open external URLs, reveal filesystem paths, and format local time through validated macOS, Linux, and Windows backends (#315).
+- **App-scoped credentials**: TypeScript and Zig cores can store, load, and delete credentials through capability- and permission-gated native providers, with redacted journals, deterministic replay placeholders, and hermetic devhost stores across desktop and mobile (#335).
+- **Cross-compiled TypeScript cores**: The external core compiler now builds Linux and Windows GNU targets from macOS, Linux, or Windows and macOS targets from macOS, with target-independent contracts and cross-platform end-to-end batteries for Windows and Linux musl (#340).
+
+### Bug Fixes
+
+- **Working documentation root**: `/docs`, `/docs/`, and the matching Markdown route now resolve to the Introduction instead of ending at a 404 (#338).
+
+### Improvements
+
+- **Faster retained desktop frames**: Animation pumping and Windows wake scheduling now avoid stalled or redundant work, profiling uses monotonic frame-correlated telemetry, and physical macOS and Windows performance gates protect input latency and frame budgets (#313).
+- **Measured, compiler-truth service tooling**: A dedicated TypeScript Services reference documents the two-tier model and failure semantics; production-carrier benchmarks measure cold start, latency, and throughput; generated compiler-surface references and manifest diffs keep capability claims mechanically honest; and scriptc advances through 0.0.28 with refreshed contracts and calibration (#325, #327, #328, #329, #333, #336).
+
+### Contributors
+
+- @ctate
+- @carvalab
+- @Railly
+- @camilocbarrera
+
+<!-- release:end -->
+
+## 0.8.4
+
+### New Features
+
+- **Streaming fetch responses for TypeScript cores**: `Cmd.fetch` can now deliver line-framed HTTP responses through typed message arms with deterministic terminal errors, loud cancellation, duplicate-key rejection, and bounded line sizes; the rebuilt Chatbot example streams Vercel AI Gateway replies with live model selection and a Stop action (#300).
+- **Desktop audio capture**: TypeScript cores can start bounded, timestamped microphone or system-output PCM streams on macOS and Windows with explicit lifecycle, permission, drop-count, and replay handling; the new Voice Memo example records, saves, and plays WAV files (#303).
+- **Customizable macOS DMG packaging**: `native package` now creates polished drag-to-Applications disk images with generated or custom Retina backgrounds, configurable Finder geometry, positioned app and Applications entries, and staged files, directories, or links (#304).
+- **Live TypeScript theme packs**: zero-config TypeScript apps can export `themePack(model)` to switch the built-in theme pack from app state without losing live system scheme, accessibility, accent, or scale inputs (#308).
+
+### Bug Fixes
+
+- **Smooth macOS dialog blur**: Host backdrop blur now uses an optimized three-pass Gaussian approximation and correct dirty-region invalidation, eliminating flat or stale dialog backgrounds while preserving the established scrim treatment (#299).
+- **Byte-accurate PTY event keys**: TypeScript PTY event routes now expose echoed session keys as `Uint8Array`, matching the byte-text host, generated facade, and external-core contract (#307).
+- **Reliable keyboard widget navigation**: Interactive canvas lists, trees, menus, and anchored controls now retain logical focus across clipped rows, scroll keyboard targets into view, and paint active and focus-visible states consistently (#308).
+
+### Improvements
+
+- **TypeScript component gallery**: The GPU component showcase is now a TypeScript core and Native markup app with isolated interactive specimens, model-driven Default and Geist switching, clearer navigation, and dedicated smoke coverage (#308).
+
+### Contributors
+
+- @ctate
+- @marcusschiesser
+- @NyxTools-M
+
+## 0.8.3
+
+### Bug Fixes
+
+- **Packaged TypeScript app assets**: Runtime asset lookup now finds bundled macOS resources before the process working directory, so Native markup boot images such as the Kanban agent avatars render after launch (#297).
+- **Unclipped drag landing motion**: Dropped cards now stay in the lifted drag layer through their landing animation while neighboring reflow remains clipped within its swimlane (#297).
+
+### Improvements
+
+- **Denser Kanban showcase**: The seeded board now includes twice as many Jira-style tickets and removes redundant issue glyphs from card metadata (#297).
+
+### Contributors
+
+- @ctate
+
+## 0.8.2
+
+### New Features
+
+- **Native drag and drop for TypeScript apps**: Native markup's new `on-drag` channel delivers live, release, and cancellation geometry to compiled cores while the renderer lifts the source under the pointer, preserves one globally keyed insertion slot, animates neighboring items, and supports Escape cancellation; TypeScript cores can also map native multi-file drops into ordinary deterministic messages through `dropMsg` (#285).
+- **Desktop notifications from model cores**: TypeScript apps can return fire-and-forget `Cmd.showNotification` effects and Zig apps can call `fx.showNotification`, with bounded validation and suppression during fake execution and session replay (#283).
+
+### Bug Fixes
+
+- **Explicit zero canvas padding**: Programmatic and compiled or interpreted Native markup views now preserve `padding="0"` instead of replacing it with the widget kind's default padding (#288).
+
+### Improvements
+
+- **TypeScript-first app authoring guidance**: Repository instructions, bundled skills, examples, package documentation, and the docs site now consistently lead with TypeScript cores and Native markup for new apps while keeping Zig as the explicit alternative and toolkit-extension tier (#284).
+- **Agent ticket Kanban showcase**: The TypeScript Kanban example now presents numbered OpenAI- and Claude-assigned tickets, uses an icon-only add action, keeps columns scrollable, and extends its end-to-end coverage for the updated drag geometry (#295).
+
+### Contributors
+
+- @ctate
+- @johnlindquist
+- @Railly
+
+## 0.8.1
+
+### New Features
+
+- **Safe presentational HTML in Markdown**: Markdown now lowers common GitHub-style inline and block HTML into native widgets, including links, details, aligned containers, and caller-resolved images, while scripts, styles, forms, embeds, event attributes, and unsupported or malformed markup remain inert literal text (#280).
+
+### Bug Fixes
+
+- **Reliable resolved Markdown images**: image discovery now follows renderable block starts, canonicalizes entity-encoded URLs consistently between loading and lookup, preserves aspect ratios within declared bounds, honors centered and end alignment, and ignores images inside comments, unsupported markup, code, and preformatted blocks (#281).
+- **Payload-free HTTP write requests**: `Effects.fetch` now sends an explicit zero-length body for POST, PUT, and PATCH requests without a payload, preventing debug-build crashes and emitting the required `Content-Length: 0` header (#277).
+
+### Improvements
+
+- **History-driven release notes**: release preparation now builds the complete changelog entry and contributor list from the commits since the previous release, replacing the per-change fragment workflow (#278).
+
+### Contributors
+
+- @ctate
+- @Railly
+
+## 0.8.0
+
+### New Features
+
+- **Compiler-truth checks for TypeScript cores**: `native check` now ends with the pinned external core compiler's analyzer over the entry with the shipped SDK declarations mapped, so check and build share one compiler verdict. Type errors the frontend's own line would miss fail with the compiler's diagnostics verbatim; an analyzer that cannot reach a verdict defers to the build instead of wedging check.
+- **TypeScript cores compile through the external core compiler**: the frontend checks `src/core.ts` and emits its contract sidecar, the exact-pinned compiler builds a native archive, and the app links a generated mirror over it — no JS runtime in the binary, nothing to configure.
+- **The TS-to-Zig transpiled lane is removed** (a deliberate pre-1.0 break): `core_compiler = "transpiler"` in app.zon (and `-Dcore-compiler=transpiler`) is refused with a teaching, and `native check` runs the checker and contract only — no emitted Zig lands under `.native/check/`.
+- **The compiler is a package dependency**: it ships exact-pinned with the SDK's `packages/core` (repo checkouts install it with `npm ci` there; an npm-installed CLI carries it automatically).
+- **The core dev loop is restart-shaped**: markup hot reload and the instant `native dev --core` node loop are unchanged, and a core edit now pays a native compile measured in seconds on rebuild.
+- **TypeScript cores are desktop-only for now**: a mobile target with `src/core.ts` is taught before lane selection (the external toolchain does not target mobile yet); Zig and markup cores stay fully supported on mobile.
+- **Shipped type declarations**: `@native-sdk/core` now ships generated `sdk/*.d.ts` declaration files beside its TypeScript sources, so external tooling can resolve the SDK's types without compiling them.
+
+### Improvements
+
+- **Leaner TypeScript toolchain installs**: the unused `@typescript/typescript6` compatibility wrapper is no longer a dependency of `@native-sdk/cli` or `@native-sdk/core`. The frontend already imports its compiler directly through the exactly pinned `@typescript/old` alias, while consumer trees carrying their own wrapper remain unaffected.
+
+### Contributors
+
+- @ctate
+
+## 0.7.2
+
+### New Features
+
+- **Geist-style code diffs**: `ui.code` and `<code>` can mark added and removed logical lines with theme-aware full-row washes, renderer-owned `+`/`-` markers, optional line numbers, and unchanged syntax-highlighted clipboard source.
+
+### Improvements
+
+- **Verified Zig setup**: repository and generated CI workflows now install Zig with `vercel-labs/setup-zig`, including signed archive and checksum verification.
+
+### Bug Fixes
+
+- **Theme-accurate disabled buttons**: disabled buttons now keep shadcn's knockout label treatment in the default theme and use Geist's gray-100/gray-700 swap, gray-400 edge, and distinct half-opacity tertiary register in the Geist theme.
+- **Canonical documentation routes**: documentation now lives under `/docs/`, with permanent redirects from every previous URL, explicit canonical metadata, `.md` siblings, and a generated `llms.txt` that stays aligned with each page's canonical MDX source.
+- **Geist primary tabs match the design system**: tab strips now use the reference 50px row, full-width bottom rail, content-hugging 14px triggers, 24px spacing, and 16px icon treatment without changing default-theme pill tabs; the GPU component gallery now pairs a compact theme picker with a scrollable component tree and focused specimen views.
+- **Quiet Windows subprocesses**: `Effects.spawn` no longer opens or flashes a console window when a GUI or tray app launches a console-subsystem helper such as `node.exe`; interactive terminal children remain on the separate PTY API.
+- **Responsive Windows GPU surfaces**: Windows now renders retained binary canvas packets with Direct2D and DirectWrite, applies dirty-region patches (including edge-safe GPU-resident backdrop blur), and limits RGBA-to-BGRA conversion and invalidation to dirty pixels when software fallback is required.
+- **Exact Windows packet text and chrome**: Packet rendering now refuses when the bundled/custom font path cannot preserve engine-planned metrics, preserves explicitly positioned glyph runs, prevents system glyph substitution, and samples a covered, changed hidden-titlebar pixel for native caption contrast.
+- **Truthful GPU backend types**: TypeScript creation options now expose only portable backend requests while view and frame state can report the concrete Direct2D renderer; explicit software requests bypass packet encoding and image uploads and stay on the reference renderer and pixel presenter.
+- **Reliable registered-image replacement**: Unregistering and then re-registering identical pixels now recreates the removed GPU resource instead of retaining a stale cache key and silently omitting the image.
+
+### Contributors
+
+- @ctate
+- @oshtz
+
+## 0.7.1
+
+### New Features
+
+- **Declarative folder-to-code editor example**: `examples/code-editor` authors its complete view in hot-reloadable `.native` markup, unifies its titlebar, file pane, tab-strip canvas, and editor background, centers the opened folder name beside a trailing ghost Save icon in a custom titlebar, opens or replaces the focused window's folder with Cmd+O, creates independent editor windows with Cmd+N, builds a clean bounded folders-first disclosure tree with outline-free selection-only Up/Down navigation, leaf-to-parent Left movement, Left/Right expansion, in-place disk-backed Enter rename, Cmd+Enter permanent tabs, and folder focus independent from the active editor, and presents editable syntax-highlighted files (including `.mjs` and large practical sources) in a resizable second pane with flat VS Code-style tabs whose active tab has no top accent and breaks the baseline to meet the editor, replaceable italic previews that pin when double-clicked, dirty dots, active/hover close buttons, native Close/Close Others tab menus, wrapping Cmd+Shift+[/] tab cycling, Cmd+W tab-or-empty-window closing, and serialized disk-backed Save/Cmd+S.
+- **Generated compiled-core facade**: `corewire --facade` now emits the complete compiler entry and matching profile from the contract sidecar, including explicit `--f64-slot` demotions, authored type provenance, and signed or unsigned integer proofs at every host ingress.
+- **Facade contract hardening**: generated entries preserve subdirectory module paths, reconstruct private reachable types without invalid imports, preserve Model-first resolution for homonymous unbound bindings, decode optional and composite record fields with a running cursor, prove nullable integer helpers, handle signed and unsigned text-selection sentinels consistently, and refuse legacy sidecars that lack the authored facts a facade requires.
+- **Effective sidecar projection**: `corewire --effective-sidecar` emits the contract after explicit slot demotions, and staged facade/profile/sidecar triples now describe one compiled layout.
+- **Editable highlighted code**: `ui.code` and `<code>` keep their read-only default, while `editable` plus `on-input` opts into a syntax-colored multiline editor in both retained and direct rendering, with selection, caret-row highlighting, IME, clipboard, undo/redo, indentation-aware Tab input (tabs or inferred 2–8-space widths, defaulting to two spaces), and no textarea chrome.
+- **Markdown source highlighting**: `markdown`/`md` joins the code lexer names with themed headings, lists, emphasis, links, inline and fenced code, and comments; the code-editor example selects it for Markdown files.
+- **Stable line-number gutter**: numbered code reserves at least three marker columns, so short files keep a useful gutter while larger line counts still expand it.
+- **Double-click messages in Native markup**: `on-double-press` exposes the canvas runtime's additive double-click channel to `.native` views, so the first click can select or preview and the second can perform or pin without a timer. Multi-click chains stay scoped to one control and physical pointer, and a third click returns to the ordinary press action instead of repeating the double action.
+
+### Improvements
+
+- **Composable code presentation**: `ui.code` and `<code>` now provide bare highlighted content without their own background, border, radius, shadow, or padding; wrap them in a panel or card when surface chrome is wanted. An enabled line-number gutter remains opaque while horizontally scrolling so source glyphs cannot clash with its pinned markers.
+- **Flat tree keyboard hierarchy**: `treeitem` rows can declare a one-based `tree-level`, letting Left/Right find logical parents and children in loop-rendered flat trees, while `on-change` can keep arrow-key selection distinct from pointer activation.
+
+### Bug Fixes
+
+- **Live code docs preview**: The Code component page now loads its real WASM-backed engine scene instead of silently remaining on the static screenshot fallback.
+- **Reliable large-code editing**: editable code now repaints only visible selected glyphs and caches longest-line width measurements, keeping large selections and steady-state no-wrap rendering inside bounded display-list and host-measurement budgets.
+- **Complete wrapped long lines**: scrolling a single logical line beyond 128 wrapped rows now pages its visible glyphs instead of leaving the remainder blank.
+- **Stable code-editor reads**: switching tabs no longer cancels a pinned file's load, and reopened secondary windows keep monotonic file-effect keys so late completions cannot populate a newer document.
+- **Unsaved-edit protection**: opening another folder or closing a secondary editor window now refuses while that window still has dirty documents.
+- **Steady editor tabs**: active and inactive tabs now share the same background and label alignment, so filenames no longer shift when selection changes.
+- **Balance explorer rows**: file-tree hover and selection backgrounds now keep even visual gutters beside the sidebar edge and split handle while preserving compact label alignment.
+- **Complete repository roots**: the explorer now indexes a folder when it expands instead of spending its bounded tree budget in an eager depth-first walk, so large subtrees cannot hide root files or unexplored sibling folders; `.next` and `.pnpm-store` remain visible but are not recursively indexed.
+- **Familiar file opening**: Command+Down Arrow now opens the selected tree file as a persistent tab; Command+Enter remains available to the focused control.
+- **Visible active tabs**: inactive tabs retain their bottom divider, and opening, clicking, or keyboard-cycling to a tab now minimally scrolls it into view horizontally without shifting an already visible tab.
+- **Distinct new windows**: Command+N now opens each editor window slightly down and to the right of the active window so the new window is immediately apparent.
+- **Clear empty-window title**: editor windows now show “Code Explorer” in the title bar until a folder is opened.
+- **Stable editable-code repainting**: syntax-highlighted editors now keep unique retained command IDs while edited text and highlighted spans occupy different runtime storage, preventing a selected editor from crashing when the app deactivates.
+- **Safe large widget text**: views keep their ordinary 64 KiB text pools inline and allocate practical source-file capacity only when a large layout or edit needs it, while edit, presentation, and context-menu workspaces stay off constrained native stacks and large single-line pastes continue stripping line breaks.
+- **Folder-only macOS open dialogs**: `allow_directories = true` now matches Linux and Windows by selecting directories rather than allowing files alongside them in AppKit and CEF hosts.
+- **Code-editor presentation polish**: JavaScript and TypeScript object keys and typed bindings now use the same syntax color as variables, while CSS declaration names retain their property color; numbered editors also use their full trailing width so fitting lines do not produce false horizontal scrolling.
+- **Complete JSX and TSX syntax highlighting**: JSX-family code blocks now combine JavaScript or TypeScript token coloring with JSX tags and attributes instead of treating the whole file as plain HTML outside `{…}` expressions.
+- **YAML syntax highlighting**: code surfaces, Markdown fences, and the code-editor example now recognize `yaml` and `yml`, coloring mapping keys, scalars, document markers, anchors, tags, and comments.
+
+### Contributors
+
+- @ctate
+
+## 0.7.0
+
+### New Features
+
 - **Code component**: `ui.code` and markup `<code>` render highlighted source with the Geist Code Block palette in both built-in themes, wrapping by default, opt-in logical line numbers, unwrapped horizontal scrolling, and vertical scrolling for height-constrained surfaces; Markdown fences share the same component.

 ### Bug Fixes
@@ -19,8 +222,6 @@ All notable changes to the Native SDK (formerly zero-native) will be documented

 - @ctate

-<!-- release:end -->
-
 ## 0.6.3

 ### Bug Fixes
@@ -123,6 +123,6 @@ Branch from `main` (fork first if you don't have push access), keep the change f
 scripts/gate.sh fast    # root suites + the example suites your diff touches
 ```

-If the change is user-visible, add a changelog fragment in `changelog.d/` (see [changelog.d/README.md](./changelog.d/README.md)) instead of editing `CHANGELOG.md`. Open the PR against `main` describing what changed and why; for larger changes, open an issue first so the design can be discussed.
+Do not edit `CHANGELOG.md` as part of a feature or fix PR; the release agent writes the complete entry from the release-range history. Open the PR against `main` describing what changed and why; for larger changes, open an issue first so the design can be discussed.

-Commits must be cryptographically signed (`git commit -S`, or set `commit.gpgsign = true`) so they show as **Verified** — the `Signed-off-by` trailer from `git commit -s` is a DCO attestation, not a signature.
+Commits must be cryptographically signed (`git commit -S`, or set `commit.gpgsign = true`) so they show as **Verified** — the `Signed-off-by` trailer from `git commit -s` is a DCO attestation, not a signature.
@@ -93,17 +93,20 @@ Read the full guide at [native-sdk.dev/quick-start](https://native-sdk.dev/quick

 ## Examples

-The apps pictured above live in [examples/](./examples), most as zero-config projects — `app.zon` plus `src/`, no build files — run straight from their directory with `native dev`.
+The apps pictured above live in [examples/](./examples), most as zero-config projects — `app.zon` plus `src/`, no build files — run straight from their directory with `native dev`. Start with the TypeScript examples when learning the primary authoring path. The `-ts` suffix on `soundboard-ts` and `system-monitor-ts` is historical because those apps are ports kept beside older Zig originals. Chatbot is TypeScript-only and follows the unsuffixed naming used by new apps created with `native init`.

 | Example | What it shows |
 | --- | --- |
+| [`chatbot`](./examples/chatbot) | TypeScript + Native markup end to end: modules, a text editor, streaming fetch effects, and replay-safe configuration. |
+| [`soundboard-ts`](./examples/soundboard-ts) | The full music-player showcase in TypeScript + Native markup: audio, search, assets, timers, and context menus. |
+| [`system-monitor-ts`](./examples/system-monitor-ts) | A live process monitor in TypeScript + Native markup: subprocess effects, tables, charts, and timers. |
 | [`calculator`](./examples/calculator) | A complete small app: markup keypad, keyboard input, chrome shortcuts, theming. |
 | [`notes`](./examples/notes) | Persistence through the effects channel: debounced writes, restore on boot, dialogs, search. |
 | [`soundboard`](./examples/soundboard) | Album grid with decoded cover art, context menus, timers, and a custom theme. |
 | [`deck`](./examples/deck) | The soundboard player rebuilt as a dense hardware chassis: two windows, same widgets, different tokens. |
 | [`feed`](./examples/feed) | A 100,000-row list, virtualized with runtime-owned scrolling. |

-The full catalog in [examples/README.md](./examples/README.md) also covers guarded OS capabilities, GPU surfaces, WebView composition, web-frontend shells, and the iOS/Android embed hosts.
+The unsuffixed showcase apps above predate the TypeScript default and retain their Zig cores as first-class alternative implementations. The full catalog in [examples/README.md](./examples/README.md) also covers guarded OS capabilities, GPU surfaces, WebView composition, web-frontend shells, and the iOS/Android embed hosts.

 ## Platforms

@@ -7,11 +7,16 @@ To prepare a release:
 1. Create a branch (e.g. `prepare-v1.2.0`)
 2. Bump the version in `packages/native-sdk/package.json`
 3. Run `npm --prefix packages/native-sdk run version:sync` to update all version references
-4. Run `scripts/changelog-merge.sh` to fold any pending `changelog.d/` fragments into the `## Unreleased` section
-5. Write the changelog entry in `CHANGELOG.md`, wrapped in `<!-- release:start -->` and `<!-- release:end -->` markers
-6. Populate the entry's `### Contributors` from commit authors and `Co-authored-by` trailers in the release range, using GitHub handles when available; this marked block is also the GitHub release body
-7. Remove the `<!-- release:start -->` and `<!-- release:end -->` markers from the previous release entry; only the latest release should have markers
-8. Open a PR and merge to `main`
+4. Review the git history since the previous release and write the complete changelog entry at the top of `CHANGELOG.md`, under a new `## <version>` heading wrapped in `<!-- release:start -->` and `<!-- release:end -->` markers
+5. Populate the entry's `### Contributors` from commit authors and `Co-authored-by` trailers in the release range, using GitHub handles when available; this marked block is also the GitHub release body
+6. Remove the `<!-- release:start -->` and `<!-- release:end -->` markers from the previous release entry; only the latest release should have markers
+7. Open a PR and merge to `main`
+
+## Writing the changelog
+
+Follow the existing format and voice. Group changes under descriptive headings such as `### New Features`, `### Bug Fixes`, and `### Improvements`. Give each bullet a bold lead-in followed by a concise description, and include PR numbers when available. Do not prefix entries with commit hashes.
+
+The release entry should cover the complete git range since the previous release, including changes whose individual PRs did not touch `CHANGELOG.md`.

 CI compares the version in `packages/native-sdk/package.json` to what's on npm. If it differs, it cross-builds the CLI for every platform, creates the GitHub release with the binaries, publishes the per-platform binary packages (`packages/native-sdk/npm/*`), and publishes `@native-sdk/cli` last — so the main package only lands once every binary package it pins is live. If npm already has the version but the GitHub release is missing assets, CI recreates the GitHub release from the marked changelog entry.

@@ -27,6 +27,7 @@
        "src",
        "templates",
        "tests",
+        "third_party/sqlite",
        "tools",
    },
 }
@@ -61,15 +61,13 @@ if (typeof module.registerHooks !== 'function') {
    load(url, context, nextLoad) {
      if (url.startsWith('file:') && url.endsWith('.ts')) {
        const filePath = fileURLToPath(url);
-        // The transpiler's own pinned compiler, resolved from the target
+        // The frontend's own pinned compiler, resolved from the target
        // module's location (packages/core/node_modules after the taught
-        // `npm ci`, or the dependency npm installed beside the CLI). The
-        // ALIAS is required directly — not the @typescript/typescript6
-        // wrapper — because the wrapper's re-export resolves
-        // "@typescript/old" from the WRAPPER's own location, where a
-        // consumer tree's conflicting hoisted copy would win nearest-wins
-        // over our exact pin; resolving from the target finds our own
-        // nested/hoisted pin first (same reasoning as typed_ast.ts).
+        // `npm ci`, or the dependency npm installed beside the CLI):
+        // resolving from the target finds our own nested/hoisted exact
+        // pin first, so a consumer tree's conflicting hoisted typescript
+        // never wins nearest-wins over it (same reasoning as
+        // typed_ast.ts).
        if (ts === null) {
          try {
            ts = createRequire(targetPath)('@typescript/old');
@@ -1,29 +0,0 @@
-# Changelog fragments
-
-Agents and feature branches do not edit `CHANGELOG.md` directly — concurrent work would conflict on every merge. Instead, each change lands with a small fragment in this directory, and `scripts/changelog-merge.sh` folds all fragments into the `## Unreleased` section of `CHANGELOG.md` (typically during release prep, see RELEASING.md).
-
-## Writing a fragment
-
-Add `changelog.d/<slug>.md`, where `<slug>` names your change (e.g. `gpu-dashboard-smoke-budget.md`). The file holds a bullet or two for one changelog section:
-
- The first line starts with a section tag: `feature:`, `improvement:`, or `fix:`, followed by the first bullet's text.
- Any further lines are additional bullets (start them with `- `; bare lines get `- ` prefixed for you).
- One tag per fragment. A change that touches multiple sections ships multiple fragments.
- Match the CHANGELOG voice: bold lead-in, then the story. One line per bullet — never hard-wrap.
-
-Example (`changelog.d/faster-frobnication.md`):
-
-```
-improvement: **Faster frobnication**: the frobnicator now memoizes per-frame, cutting rebuild time ~40% on the kanban example.
- **Frobnication telemetry**: automation snapshots report `frob_cache_hits=`.
-```
-
-Tags map to sections: `feature:` → `### New Features`, `improvement:` → `### Improvements`, `fix:` → `### Bug Fixes`.
-
-## Merging
-
-```sh
-scripts/changelog-merge.sh
-```
-
-appends every fragment's bullets to the end of its section under `## Unreleased` (creating the section — or the whole `## Unreleased` block — when missing), then deletes the merged fragments. This `README.md` is never merged or deleted. The script refuses unknown tags loudly instead of guessing.
@@ -1,5 +1,8 @@
 import createMDX from "@next/mdx";
 import { createRequire } from "node:module";
+import { readdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";

 // Resolve the plugin to an absolute path (still a string, so the config
 // stays serializable for Turbopack). A bare "remark-gfm" is require()d
@@ -7,6 +10,19 @@ import { createRequire } from "node:module";
 // module isolation cannot see this app's dependencies — production
 // builds resolved it, the Turbopack dev server did not.
 const require = createRequire(import.meta.url);
+const docsContentDir = fileURLToPath(new URL("./src/app/docs", import.meta.url));
+
+function docsSlugs(dir = docsContentDir, segments = []) {
+  const slugs = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      slugs.push(...docsSlugs(path.join(dir, entry.name), [...segments, entry.name]));
+    } else if (entry.name === "page.mdx" && segments.length > 0) {
+      slugs.push(segments.join("/"));
+    }
+  }
+  return slugs;
+}

 const withMDX = createMDX({
  options: {
@@ -30,9 +46,26 @@ const nextConfig = {
    ignored: ["**/.next-gate/**", "**/.next-check/**"],
  },
  async redirects() {
+    // Config redirects preserve the request query string. Keeping these out
+    // of the prerendered catch-all route avoids baking a query-less Location
+    // header into every legacy URL's static response.
+    const legacyDocsRedirects = docsSlugs().flatMap((slug) => [
+      { source: `/${slug}`, destination: `/docs/${slug}`, permanent: true },
+      { source: `/${slug}.md`, destination: `/docs/${slug}.md`, permanent: true },
+      { source: `/md/${slug}`, destination: `/docs/${slug}.md`, permanent: true },
+    ]);
+
    return [
      // The Philosophy page became the Introduction, the opening page of the docs.
-      { source: "/philosophy", destination: "/introduction", permanent: true },
+      { source: "/philosophy", destination: "/docs/introduction", permanent: true },
+      // docsSlugs() only yields nested slugs, so the /docs segment itself has
+      // neither a route nor a generated redirect and 404s. It is the parent of
+      // every documentation link on the site and the likeliest hand-typed entry
+      // point, so open it on the Introduction instead. The .md sibling keeps the
+      // Markdown surface whole for agents that reach for it.
+      { source: "/docs", destination: "/docs/introduction", permanent: true },
+      { source: "/docs.md", destination: "/docs/introduction.md", permanent: true },
+      ...legacyDocsRedirects,
    ];
  },
 };
@@ -9,7 +9,7 @@
    "build": "next build",
    "start": "next start",
    "typecheck": "tsc --noEmit",
-    "check": "pnpm typecheck && pnpm build && node scripts/check-code-toggle.mjs"
+    "check": "pnpm typecheck && pnpm build && node scripts/check-doc-routes.mjs && node scripts/check-code-toggle.mjs && node scripts/check-wasm-preview.mjs"
  },
  "dependencies": {
    "@mdx-js/loader": "^3",
@@ -41,4 +41,4 @@
      "postcss@<8.5.10": ">=8.5.10"
    }
  }
-}
+}
@@ -0,0 +1,203 @@
+// SEO regression gate for the /docs migration. Every page.mdx must build at
+// one canonical HTML URL and one canonical Markdown sibling; the former route
+// must redirect permanently rather than render duplicate content. Canonical
+// metadata, sitemap entries, llms.txt, and rendered internal links must all
+// point directly into /docs so crawlers never have to choose between copies.
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const docsDir = join(dirname(fileURLToPath(import.meta.url)), "..");
+const sourceDir = join(docsDir, "src", "app", "docs");
+const distDir = join(docsDir, process.env.NEXT_DIST_DIR || ".next");
+const appOutputDir = join(distDir, "server", "app");
+const siteUrl = "https://native-sdk.dev";
+
+function* mdxPages(dir) {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) yield* mdxPages(full);
+    else if (entry === "page.mdx") yield full;
+  }
+}
+
+function readRequired(file, route) {
+  if (!existsSync(file)) {
+    throw new Error(`${route}: missing build output ${file}`);
+  }
+  return readFileSync(file, "utf8");
+}
+
+const routesManifest = JSON.parse(
+  readRequired(join(distDir, "routes-manifest.json"), "redirect manifest"),
+);
+
+function assertConfiguredRedirect(source, destination) {
+  const redirect = routesManifest.redirects.find((candidate) => candidate.source === source);
+  if (!redirect || redirect.statusCode !== 308 || redirect.destination !== destination) {
+    throw new Error(
+      `${source}: expected a query-preserving 308 config redirect to ${destination}, got ${JSON.stringify(redirect)}`,
+    );
+  }
+}
+
+function proseLines(markdown) {
+  const lines = [];
+  let fence = null;
+  for (const line of markdown.split("\n")) {
+    const marker = line.trimStart().match(/^(```|~~~)/)?.[1];
+    if (marker) {
+      if (fence === marker) fence = null;
+      else if (fence === null) fence = marker;
+      continue;
+    }
+    if (fence === null) lines.push(line);
+  }
+  return lines;
+}
+
+function headings(markdown) {
+  return proseLines(markdown)
+    .map((line) => line.match(/^(#{1,6})\s+(.+?)\s*#*\s*$/))
+    .filter(Boolean)
+    .map((match) => `${match[1]} ${match[2]}`);
+}
+
+function assertCleanMarkdown(source, markdown, route) {
+  // Generic type spellings such as `Sub<Msg>` are legitimate inside inline
+  // code and must not be mistaken for unresolved MDX components.
+  const prose = proseLines(markdown).join("\n").replace(/`[^`\n]*`/g, "");
+  const unresolved = prose.match(/<[A-Z][A-Za-z0-9]*(?:\s|\/?>)/)?.[0];
+  if (unresolved) {
+    throw new Error(`${route}: unresolved MDX component in Markdown output: ${unresolved}`);
+  }
+  const unresolvedExpression = prose.match(/\{"[^"\\\r\n]*"\}|\{'[^'\\\r\n]*'\}/)?.[0];
+  if (unresolvedExpression) {
+    throw new Error(
+      `${route}: unresolved MDX string expression in Markdown output: ${unresolvedExpression}`,
+    );
+  }
+
+  const renderedHeadings = new Set(headings(markdown));
+  for (const heading of headings(source)) {
+    if (!renderedHeadings.has(heading)) {
+      throw new Error(`${route}: Markdown output dropped source heading ${heading}`);
+    }
+  }
+
+  for (const component of source.matchAll(/<EjectSection\s+components=\{\[([\s\S]*?)\]\}\s*\/>/g)) {
+    if (!renderedHeadings.has("## Eject")) {
+      throw new Error(`${route}: EjectSection did not render its heading`);
+    }
+    for (const name of component[1].matchAll(/"([^"]+)"/g)) {
+      const command = `native eject component ${name[1]}`;
+      if (!markdown.includes(command)) {
+        throw new Error(`${route}: EjectSection did not render command ${command}`);
+      }
+    }
+  }
+}
+
+const pageFiles = [...mdxPages(sourceDir)];
+const canonicalPaths = new Set(
+  pageFiles.map((page) => {
+    const slug = relative(sourceDir, dirname(page)).split(sep).join("/");
+    return `/docs/${slug}`;
+  }),
+);
+const canonicalUrls = new Set([...canonicalPaths].map((route) => `${siteUrl}${route}`));
+const canonicalMarkdownUrls = new Set(
+  [...canonicalPaths].map((route) => `${siteUrl}${route}.md`),
+);
+let pages = 0;
+
+for (const page of pageFiles) {
+  pages += 1;
+  const slug = relative(sourceDir, dirname(page)).split(sep).join("/");
+  const canonicalPath = `/docs/${slug}`;
+  const canonicalUrl = `${siteUrl}${canonicalPath}`;
+  const output = join(appOutputDir, "docs", slug);
+  const html = readRequired(`${output}.html`, canonicalPath);
+  const source = readFileSync(page, "utf8");
+
+  if (!html.includes(`<link rel="canonical" href="${canonicalUrl}"/>`)) {
+    throw new Error(`${canonicalPath}: missing its exact canonical link tag`);
+  }
+  if (!html.includes(`<meta property="og:url" content="${canonicalUrl}"/>`)) {
+    throw new Error(`${canonicalPath}: Open Graph URL is not canonical`);
+  }
+
+  for (const match of html.matchAll(/<a\b[^>]*\bhref="([^"]+)"/g)) {
+    const href = match[1];
+    if (href?.startsWith("/") && href !== "/" && !href.startsWith("/docs/")) {
+      throw new Error(`${canonicalPath}: rendered internal link bypasses /docs: ${href}`);
+    }
+    if (href?.startsWith("/docs/")) {
+      const target = href.split(/[?#]/, 1)[0];
+      if (target && !canonicalPaths.has(target)) {
+        throw new Error(`${canonicalPath}: rendered internal link targets no docs page: ${href}`);
+      }
+    }
+  }
+
+  const markdownMeta = JSON.parse(readRequired(`${output}.md.meta`, `${canonicalPath}.md`));
+  if (
+    markdownMeta.status !== 200 ||
+    markdownMeta.headers?.["content-type"] !== "text/markdown; charset=utf-8"
+  ) {
+    throw new Error(`${canonicalPath}.md: expected a static text/markdown response`);
+  }
+  if (markdownMeta.headers?.link !== `<${canonicalUrl}>; rel="canonical"`) {
+    throw new Error(`${canonicalPath}.md: missing its exact canonical HTTP Link header`);
+  }
+  const markdown = readRequired(`${output}.md.body`, `${canonicalPath}.md`);
+  assertCleanMarkdown(source, markdown, `${canonicalPath}.md`);
+
+  assertConfiguredRedirect(`/${slug}`, canonicalPath);
+  assertConfiguredRedirect(`/${slug}.md`, `${canonicalPath}.md`);
+  assertConfiguredRedirect(`/md/${slug}`, `${canonicalPath}.md`);
+
+  for (const legacyOutput of [
+    join(appOutputDir, `${slug}.html`),
+    join(appOutputDir, `${slug}.meta`),
+    join(appOutputDir, `${slug}.md.meta`),
+    join(appOutputDir, "md", `${slug}.meta`),
+  ]) {
+    if (existsSync(legacyOutput)) {
+      throw new Error(`/${slug}: legacy URL was prerendered instead of using its config redirect`);
+    }
+  }
+}
+
+if (pages === 0) throw new Error("no docs page.mdx files found");
+
+const sitemap = readRequired(join(appOutputDir, "sitemap.xml.body"), "/sitemap.xml");
+const sitemapUrls = new Set([...sitemap.matchAll(/<loc>([^<]+)<\/loc>/g)].map((match) => match[1]));
+for (const match of sitemap.matchAll(/<loc>([^<]+)<\/loc>/g)) {
+  const url = match[1];
+  if (url !== `${siteUrl}/` && !canonicalUrls.has(url)) {
+    throw new Error(`/sitemap.xml: non-canonical documentation URL ${url}`);
+  }
+}
+for (const url of canonicalUrls) {
+  if (!sitemapUrls.has(url)) throw new Error(`/sitemap.xml: missing canonical page ${url}`);
+}
+
+const llms = readRequired(join(appOutputDir, "llms.txt.body"), "/llms.txt");
+const llmsUrls = new Set();
+for (const line of llms.split("\n")) {
+  if (!line.startsWith("- [")) continue;
+  const url = line.match(/^- \[[^\]]+\]\(([^)]+)\)$/)?.[1];
+  if (!url || !canonicalMarkdownUrls.has(url)) {
+    throw new Error(`/llms.txt: non-canonical documentation link: ${line}`);
+  }
+  llmsUrls.add(url);
+}
+for (const url of canonicalMarkdownUrls) {
+  if (!llmsUrls.has(url)) throw new Error(`/llms.txt: missing canonical page ${url}`);
+}
+
+console.log(
+  `docs route check passed: ${pages} canonical pages, Markdown siblings, and query-preserving legacy redirects verified`,
+);
@@ -0,0 +1,63 @@
+// Regression pin for the Code component docs previews. ComponentPreview
+// deliberately keeps a webp fallback under its live canvas, so a stale
+// or incompatible wasm scene can otherwise fail silently and leave the
+// page looking correct while it is only showing the screenshot.
+//
+// Require the checked-in module to instantiate the exact `code` and
+// `code-diff` scenes used by /components/code. Runs after `next build`
+// as part of `pnpm check`.
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const docsDir = join(dirname(fileURLToPath(import.meta.url)), "..");
+const wasmPath = join(docsDir, "public", "wasm", "component-preview.wasm");
+const vocabPath = join(docsDir, "src", "lib", "component-vocab.json");
+const bytes = readFileSync(wasmPath);
+const vocab = JSON.parse(readFileSync(vocabPath, "utf8"));
+const { instance } = await WebAssembly.instantiate(bytes, {});
+const exports = instance.exports;
+const sceneNames = ["code", "code-diff"];
+
+if (
+  typeof exports.preview_code_diff_metadata_round_trip !== "function" ||
+  exports.preview_code_diff_metadata_round_trip() !== 1
+) {
+  throw new Error(
+    "the checked-in component-preview.wasm truncates code-diff metadata above line 96 on wasm32",
+  );
+}
+
+for (const sceneName of sceneNames) {
+  const scene = new TextEncoder().encode(sceneName);
+  const scenePtr = exports.preview_alloc(scene.length);
+
+  if (!scenePtr) {
+    throw new Error(`${sceneName} WASM preview check could not allocate its scene name`);
+  }
+
+  new Uint8Array(exports.memory.buffer).set(scene, scenePtr);
+  const handle = exports.preview_create(scenePtr, scene.length, 0);
+  exports.preview_free(scenePtr, scene.length);
+
+  if (!handle) {
+    throw new Error(
+      `the checked-in component-preview.wasm cannot create the \`${sceneName}\` scene; rebuild it with \`zig build docs-wasm-preview\``,
+    );
+  }
+
+  const width = exports.preview_logical_width(handle);
+  const height = exports.preview_logical_height(handle);
+  exports.preview_destroy(handle);
+  const expectedWidth = vocab.previews[sceneName].width / 2;
+  const expectedHeight = vocab.previews[sceneName].height / 2;
+
+  if (width !== expectedWidth || height !== expectedHeight) {
+    throw new Error(
+      `the ${sceneName} WASM preview is ${width}x${height}; expected the catalog's ${expectedWidth}x${expectedHeight} scene`,
+    );
+  }
+
+  console.log(`${sceneName} WASM preview check passed: live scene instantiated at ${width}x${height}`);
+}
@@ -0,0 +1,63 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { mdxToCleanMarkdown } from "@/lib/mdx-to-markdown";
+import { siteUrl } from "@/lib/site";
+
+/**
+ * Serve every canonical docs page as clean Markdown beside its HTML route.
+ * Legacy URLs are config redirects so Next can preserve each request's query
+ * string; this route stays fully static and only emits the canonical siblings.
+ */
+
+export const dynamic = "force-static";
+export const dynamicParams = false;
+
+const docsDir = () => path.join(process.cwd(), "src", "app", "docs");
+
+export async function generateStaticParams(): Promise<{ slug: string[] }[]> {
+  const params: { slug: string[] }[] = [];
+  async function walk(dir: string, slug: string[]): Promise<void> {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        await walk(path.join(dir, entry.name), [...slug, entry.name]);
+      } else if (entry.name === "page.mdx" && slug.length > 0) {
+        const markdownSlug = [...slug];
+        markdownSlug[markdownSlug.length - 1] += ".md";
+        params.push({ slug: ["docs", ...markdownSlug] });
+      }
+    }
+  }
+  await walk(docsDir(), []);
+  return params;
+}
+
+export async function GET(_request: Request, context: { params: Promise<{ slug: string[] }> }) {
+  const { slug } = await context.params;
+  if (slug[0] !== "docs") return new Response("Not found", { status: 404 });
+  const sourceSlug = slug.slice(1);
+  const filename = sourceSlug.at(-1);
+  if (!filename?.endsWith(".md") || filename === ".md") {
+    return new Response("Not found", { status: 404 });
+  }
+
+  sourceSlug[sourceSlug.length - 1] = filename.slice(0, -3);
+  const canonicalUrl = `${siteUrl}/docs/${sourceSlug.join("/")}`;
+  const filePath = path.join(docsDir(), ...sourceSlug, "page.mdx");
+  // Static params come from the filesystem walk above, but never follow
+  // a path that escapes src/app/docs.
+  if (!filePath.startsWith(docsDir() + path.sep)) {
+    return new Response("Not found", { status: 404 });
+  }
+  try {
+    const source = await readFile(filePath, "utf8");
+    return new Response(mdxToCleanMarkdown(source) + "\n", {
+      headers: {
+        "Content-Type": "text/markdown; charset=utf-8",
+        Link: `<${canonicalUrl}>; rel="canonical"`,
+      },
+    });
+  } catch {
+    return new Response("Not found", { status: 404 });
+  }
+}
@@ -1,47 +0,0 @@
-import { ComponentPreview } from "@/components/component-preview";
-import { AttrTable } from "@/components/attr-table";
-
-# Code
-
-Presents source text in a themed monospace surface with deterministic syntax highlighting. Code wraps by default. Set `wrap="false"` to preserve logical lines inside one horizontal scroll region, and opt into logical line numbers with `line-numbers`.
-
-HTML-family highlighting understands HTML, XML, SVG, JSX, and TSX structure: element or component tags, attributes, strings, comments, numbers, and JavaScript/TypeScript expressions receive distinct theme-token colors.
-
-<ComponentPreview name="code" alt="A JSX code sample with syntax highlighting and line numbers" caption="JSX tags, attributes, strings, expressions, and an unwrapped horizontal viewport" />
-
-## Markup
-
-```html
-<code
-  source="{component_source}"
-  language="tsx"
-  line-numbers
-  wrap="false"
-  width="480"
-  label="Accordion example"
-/>
-```
-
-`source` is required and must be one `{binding}` producing text. `language` is a literal lexer name; unknown names are validation errors. Line numbers are off by default and remain decorative, so selecting and copying a numbered block returns only the source text. Numbered presentation is limited to 128 logical lines; longer sources keep all code and omit the gutter.
-
-## Programmatic construction (Zig)
-
-```zig
-ui.code(.{
-    .language = .html,
-    .line_numbers = true,
-    .wrap = false,
-    .width = 480,
-    .semantics = .{ .label = "Accordion example" },
-}, model.component_source)
-```
-
-The public lexer model is `native_sdk.canvas.code`. `languageFromName` resolves markup spellings, `languageFromFence` reads a Markdown info string, and `highlight` produces the same bounded, theme-colored span runs both renderers use.
-
-## Languages
-
-Zig; JavaScript and TypeScript; JSX and TSX; JSON; shell; Python; Rust; C, C++, C#, Java, Kotlin, and Swift; Go; HTML, XML, and SVG; CSS, SCSS, and Less; and SQL. An omitted language renders plain monospace.
-
-## Attributes
-
-<AttrTable element="code" attrs={["source", "language", "line-numbers", "wrap", "width", "height", "min-width", "grow", "key", "global-key", "label"]} />
@@ -1,31 +0,0 @@
-import { ComponentPreview } from "@/components/component-preview";
-import { AttrTable } from "@/components/attr-table";
-
-# Markdown
-
-Renders a markdown string (a GFM subset, pipe tables included) as native widgets through the same text pipeline as every other component — deterministic layout, selectable text. `source` is required and must be one `{binding}`; the element takes no children. Links dispatch `on-link` with the URL as payload (bare URLs autolink), `<details>` blocks toggle through `on-details` plus a model-owned `details-expanded` flag list, and `#123` references linkify through `issue-link-base`. Fenced blocks lower through the reusable [Code](/components/code) component, so indentation and syntax behavior stay identical.
-
-<ComponentPreview name="markdown" alt="A markdown document rendered by the engine" caption="headings, emphasis, inline code, lists, links, and a code block" />
-
-## Markup
-
-```html
-<markdown source="{release_notes}" on-link="open_link" issue-link-base="https://github.com/native-sdk/native/issues/"></markdown>
-```
-
-## Programmatic construction (Zig)
-
-The builder is the `canvas.markdown` module, parameterized over the app's Msg type; `on_link` pairs with `Ui.linkMsg(.tag)`.
-
-```zig
-const Md = native_sdk.canvas.markdown.Markdown(Msg);
-
-Md.view(ui, model.release_notes, .{
-    .on_link = Ui.linkMsg(.open_link),
-    .issue_link_base = "https://github.com/native-sdk/native/issues/",
-})
-```
-
-## Attributes
-
-<AttrTable element="markdown" attrs={["source", "on-link", "on-details", "details-expanded", "issue-link-base"]} />
@@ -1,62 +0,0 @@
-import { ComponentPreview } from "@/components/component-preview";
-import { AttrTable } from "@/components/attr-table";
-
-# Tree
-
-A disclosure-tree container. The rows are ordinary elements (usually [list items](/components/list)) carrying `role="treeitem"`, and every such descendant joins one roving keyboard focus set: Up/Down walk the visible rows, Left collapses a row or moves to its parent, Right expands or moves to the first child, Home/End jump to the edges. Expandable rows bind `expanded` and dispatch `on-toggle`; selection follows each row's `on-press`. The model owns both states — children of a collapsed row are simply not rendered.
-
-<ComponentPreview name="tree" alt="A file tree with an expanded folder and a selected row rendered by the engine" caption="an expanded folder, indented children, and a collapsed sibling" />
-
-## Markup
-
-```html
-<tree width="340" gap="2">
-  <list-item icon="folder-open" role="treeitem" expanded="{src_open}" on-toggle="toggle_src" on-press="select_src">src</list-item>
-  <if test="{src_open}">
-    <row>
-      <column width="20" />
-      <column gap="2" grow="1">
-        <list-item icon="file-text" role="treeitem" selected="{file == main}" on-press="select_main">main.zig</list-item>
-        <list-item icon="file-text" role="treeitem" selected="{file == view}" on-press="select_view">view.zig</list-item>
-      </column>
-    </row>
-  </if>
-  <list-item icon="folder" role="treeitem" expanded="{assets_open}" on-toggle="toggle_assets" on-press="select_assets">assets</list-item>
-</tree>
-```
-
-The indent is plain layout — a fixed-width spacer column beside the children. Omit `expanded` on leaf rows; only rows that bind it participate in Left/Right disclosure.
-
-## Programmatic construction (Zig)
-
-In a Zig view, the `canvas.Ui` builder constructs the same tree programmatically:
-
-```zig
-ui.tree(.{ .width = 340, .gap = 2 }, .{
-    ui.listItem(.{
-        .icon = "folder-open",
-        .expanded = model.src_open,
-        .on_toggle = .toggle_src,
-        .on_press = .select_src,
-        .semantics = .{ .role = .treeitem },
-    }, "src"),
-    if (model.src_open) ui.row(.{}, .{
-        ui.column(.{ .width = 20 }, .{}),
-        ui.column(.{ .gap = 2, .grow = 1 }, .{
-            ui.listItem(.{ .icon = "file-text", .selected = model.file == .main, .on_press = .select_main, .semantics = .{ .role = .treeitem } }, "main.zig"),
-            ui.listItem(.{ .icon = "file-text", .selected = model.file == .view, .on_press = .select_view, .semantics = .{ .role = .treeitem } }, "view.zig"),
-        }),
-    }) else ui.stack(.{}, .{}),
-    ui.listItem(.{
-        .icon = "folder",
-        .expanded = model.assets_open,
-        .on_toggle = .toggle_assets,
-        .on_press = .select_assets,
-        .semantics = .{ .role = .treeitem },
-    }, "assets"),
-})
-```
-
-## Attributes
-
-<AttrTable attrs={["role", "expanded", "selected", "on-toggle", "on-press", "gap", "label"]} />
@@ -11,7 +11,7 @@ A Native SDK app is one loop with four parts:

 The runtime owns everything else: window creation, GPU presentation, resize, pointer and keyboard dispatch, timers, accessibility, and hot reload. Your code never handles a raw event — input lands on a widget, the widget's bound message dispatches into `update`, the view rebuilds from the new model, and the engine repaints what changed.

-The loop is the same in both authoring languages. By default the core is TypeScript (`src/core.ts`, compiled to native code at build time — [TypeScript Cores](/typescript) covers that tier in depth); a Zig core (`src/main.zig`, from `native init --template zig-core`) is first-class by choice, and the rest of this page — wiring, identity, hot reload — applies to both. The Zig-specific wiring sections below are exactly what the build generates for a TypeScript app, so they double as its eject story.
+The loop is the same in both authoring languages. By default the core is TypeScript (`src/core.ts`, compiled to native code at build time — [TypeScript Cores](/docs/typescript) covers that tier in depth); a Zig core (`src/main.zig`, from `native init --template zig-core`) is first-class by choice, and the rest of this page — wiring, identity, hot reload — applies to both. The Zig-specific wiring sections below are exactly what the build generates for a TypeScript app, so they double as the blueprint for porting a core to Zig by hand.

 ## The loop in full

@@ -81,7 +81,7 @@ Markup can never mutate state. `{count}` is a read; `on-press="increment"` names

 ## Wiring

-`native_sdk.UiApp(Model, Msg)` ties the loop to the runtime. A zero-config app never writes this — the build graph generates it (for a TypeScript core, over the transpiled model) — but it is ordinary code you can own any time. From the Zig template's `main`:
+`native_sdk.UiApp(Model, Msg)` ties the loop to the runtime. A zero-config app never writes this — the build graph generates it (for a TypeScript core, over the compiled core's model) — but it is ordinary code you can own any time. From the Zig template's `main`:

 ```zig
 const CounterApp = native_sdk.UiApp(Model, Msg);
@@ -103,15 +103,15 @@ pub fn main(init: std.process.Init) !void {
 }
 ```

-`create` requires every `Model` field to carry a default; the model starts as `.{}` and boot state is assigned through the returned pointer. The `scene` declares the native window and its GPU surface view — see [Windows](/windows) and [Native Surfaces](/native-surfaces) for multi-view scenes.
+`create` requires every `Model` field to carry a default; the model starts as `.{}` and boot state is assigned through the returned pointer. The `scene` declares the native window and its GPU surface view — see [Windows](/docs/windows) and [Native Surfaces](/docs/native-surfaces) for multi-view scenes.

 ## Rebuilds and widget identity

 After every `update`, the runtime rebuilds the view from the model. Rebuilds are cheap and safe by design:

 - **Widget identity is structural.** A widget keeps its id across rebuilds, reorders, and hot reloads, so engine-owned state — scroll offsets, text carets, focus — survives. List items carry `key` (or `global-key` for items that move between containers) to keep identity through reorders. Unkeyed same-kind siblings take positional identity (sibling index), so an `<if>` that inserts or removes an earlier same-kind sibling re-disambiguates the trailing ones — engine-owned state like carets and scroll can hop; keyed items and keyed ancestors hold identity.
- **The source wins.** Engine-retained state (a scroll offset, a toggle) survives rebuilds until the model asserts a different value; then the model's value applies. This is why controlled patterns echo runtime-applied values back through the model — see [State & Data Flow](/state).
- **Errors degrade, they never crash.** A failing `update` arm is caught, recorded in a bounded error ring (visible in [automation](/automation) snapshots as `dispatch_errors=`), and the app keeps running.
+- **The source wins.** Engine-retained state (a scroll offset, a toggle) survives rebuilds until the model asserts a different value; then the model's value applies. This is why controlled patterns echo runtime-applied values back through the model — see [State & Data Flow](/docs/state).
+- **Errors degrade, they never crash.** A failing `update` arm is caught, recorded in a bounded error ring (visible in [automation](/docs/automation) snapshots as `dispatch_errors=`), and the app keeps running.

 ## Hot reload in development

@@ -156,8 +156,8 @@ A Zig-root app keeps dev-time hot reload for its embedded fragments too: build w

 ## Side effects

-`update` stays pure by routing anything asynchronous — subprocesses, HTTP, file persistence, timers, clipboard — through the effects channel, and results come back as ordinary messages. In a TypeScript core, effects are `Cmd` data returned from `update` and recurring timers are declared `Sub` data — see [TypeScript Cores: Effects](/typescript#effects-are-cmd-data). In a Zig core, declare `.update_fx` instead of `.update` and spawn from message arms; boot-time work goes in `.init_fx`, which runs exactly once before the first paint. See [Native UI: Effects](/native-ui#effects).
+`update` stays pure by routing anything that leaves the model — subprocesses, HTTP, file persistence, timers, clipboard, desktop notifications — through the effects channel, and routed results come back as ordinary messages. In a TypeScript core, effects are `Cmd` data returned from `update` and recurring timers are declared `Sub` data — see [TypeScript Cores: Effects](/docs/typescript#effects-are-cmd-data). In a Zig core, declare `.update_fx` instead of `.update` and spawn from message arms; boot-time work goes in `.init_fx`, which runs exactly once before the first paint. See [Native UI: Effects](/docs/native-ui#effects).

 ## Dropping down

-`UiApp` is a layer over the lower-level `App`/`Runtime` pair, which any app can use directly — for custom lifecycle callbacks, imperative window and view management, or embedding [web content](/frontend). The [App & Runtime](/runtime) reference documents that layer, and [Embedded App](/embed) covers driving the runtime from an existing host (including iOS and Android).
+`UiApp` is a layer over the lower-level `App`/`Runtime` pair, which any app can use directly — for custom lifecycle callbacks, imperative window and view management, or embedding [web content](/docs/frontend). The [App & Runtime](/docs/runtime) reference documents that layer, and [Embedded App](/docs/embed) covers driving the runtime from an existing host (including iOS and Android).
@@ -45,7 +45,7 @@ The manifest `native init` generates — identity, one shell window with a GPU s

 ## Example: app with web content, menus, and shortcuts

-A fuller manifest for an app that also [embeds web content](/frontend) and declares commands, shortcuts, menus, and packaging metadata:
+A fuller manifest for an app that also [embeds web content](/docs/frontend) and declares commands, shortcuts, menus, and packaging metadata:

 ```zig:app.zon
 .{
@@ -148,25 +148,33 @@ A fuller manifest for an app that also [embeds web content](/frontend) and decla
      <td><code>platforms</code></td>
      <td>Target platforms: <code>macos</code>, <code>linux</code>, <code>windows</code></td>
    </tr>
+    <tr>
+      <td><code>dmg</code></td>
+      <td>Optional macOS DMG presentation: volume name, PNG/JPEG/TIFF background (with automatic adjacent <code>@2x</code> discovery), usable Finder canvas and icon sizes, simple app/Applications positions, or an explicit positioned <code>items</code> list of the app, Applications alias, project files/directories, and absolute links. The zero-config defaults produce a complete drag-to-Applications layout.</td>
+    </tr>
    <tr>
      <td><code>permissions</code></td>
-      <td>Runtime permissions (see <a href="/security">Security</a>)</td>
+      <td>Runtime permissions (see <a href="/docs/security">Security</a>). Audio capture uses <code>microphone</code> and <code>system_audio</code>; macOS packaging emits the matching microphone, audio-capture, and screen-capture usage descriptions only when declared</td>
    </tr>
    <tr>
      <td><code>capabilities</code></td>
-      <td>Feature declarations (see <a href="/security">Security</a>)</td>
+      <td>Feature declarations (see <a href="/docs/security">Security</a>). <code>"store"</code> links the engine-owned record store; <code>"sqlite"</code> links relational SQL effects. They share one capability-shed SQLite object but use separate databases; see <a href="/docs/record-store">Record Store</a> and <a href="/docs/sqlite">Relational SQLite</a></td>
+    </tr>
+    <tr>
+      <td><code>persist</code></td>
+      <td>Engine-owned Model snapshot config: monotonic <code>version</code>, optional <code>debounce_ms</code>, and the <code>restore</code> Msg routes (<code>ok</code>/<code>none</code>/<code>err</code>). Requires <code>"persist"</code> in capabilities — see <a href="/docs/persistence">Model Persistence</a></td>
    </tr>
    <tr>
      <td><code>bridge</code></td>
-      <td>Bridge command policies (see <a href="/bridge">Bridge</a>)</td>
+      <td>Bridge command policies (see <a href="/docs/bridge">Bridge</a>)</td>
    </tr>
    <tr>
      <td><code>security</code></td>
-      <td>Navigation and external link policies (see <a href="/security">Security</a>)</td>
+      <td>Navigation and external link policies (see <a href="/docs/security">Security</a>)</td>
    </tr>
    <tr>
      <td><code>web_engine</code></td>
-      <td><code>system</code> or <code>chromium</code>; Chromium is currently supported for macOS builds (see <a href="/web-engines">Web Engines</a>)</td>
+      <td><code>system</code> or <code>chromium</code>; Chromium is currently supported for macOS builds (see <a href="/docs/web-engines">Web Engines</a>)</td>
    </tr>
    <tr>
      <td><code>webview_layer</code></td>
@@ -174,7 +182,7 @@ A fuller manifest for an app that also [embeds web content](/frontend) and decla
    </tr>
    <tr>
      <td><code>theme</code></td>
-      <td>Built-in theme pack: <code>house</code> (default) or <code>geist</code>; an unknown name is a build/check error (see <a href="/theming">Theming</a>)</td>
+      <td>Built-in theme pack: <code>house</code> (default) or <code>geist</code>; an unknown name is a build/check error (see <a href="/docs/theming">Theming</a>)</td>
    </tr>
    <tr>
      <td><code>theme_accent</code></td>
@@ -190,7 +198,7 @@ A fuller manifest for an app that also [embeds web content](/frontend) and decla
    </tr>
    <tr>
      <td><code>windows</code></td>
-      <td>Window definitions (see <a href="/windows">Windows</a>)</td>
+      <td>Window definitions (see <a href="/docs/windows">Windows</a>)</td>
    </tr>
    <tr>
      <td><code>shell</code></td>
@@ -202,11 +210,11 @@ A fuller manifest for an app that also [embeds web content](/frontend) and decla
    </tr>
    <tr>
      <td><code>shortcuts</code></td>
-      <td>Keyboard shortcuts delivered as <code>shortcut</code> events (see <a href="/keyboard-shortcuts">Keyboard Shortcuts</a>)</td>
+      <td>Keyboard shortcuts delivered as <code>shortcut</code> events (see <a href="/docs/keyboard-shortcuts">Keyboard Shortcuts</a>)</td>
    </tr>
    <tr>
      <td><code>menus</code></td>
-      <td>Native menu declarations delivered through the command event path (see <a href="/menus">Menus</a>)</td>
+      <td>Native menu declarations delivered through the command event path (see <a href="/docs/menus">Menus</a>)</td>
    </tr>
    <tr>
      <td><code>file_associations</code></td>
@@ -218,7 +226,7 @@ A fuller manifest for an app that also [embeds web content](/frontend) and decla
    </tr>
    <tr>
      <td><code>frontend</code></td>
-      <td>Frontend build/dev config (see <a href="/frontend">Frontend Projects</a>)</td>
+      <td>Frontend build/dev config (see <a href="/docs/frontend">Frontend Projects</a>)</td>
    </tr>
  </tbody>
 </table>
@@ -269,15 +277,15 @@ For a scene-first app — a `UiApp` passing its Zig scene (`shell_scene`) to the
 },
 ```

-Each window takes a `label` plus optional `title`, `width`, `height`, `x`, `y`, `resizable`, `restore_state`, `restore_policy` (`clamp_to_visible_screen` or `center_on_primary`), `min_width`/`min_height` (a content min-size floor the window itself enforces — macOS `contentMinSize`; the first shell window's declaration threads through the startup create like `titlebar`, negative values are a manifest error, 0 means no floor), and `titlebar` (`standard`, `hidden_inset`, `hidden_inset_tall` — the tall variant centers macOS's traffic lights in the 52pt unified band for toolbar-height headers — or `chromeless`, the fully-skinned opt-in that removes all OS chrome including the system buttons; only for apps that draw their own working window controls, see `examples/deck`). `titlebar = "hidden_inset"` hides the titlebar and extends content under it (macOS keeps the traffic lights) — the first shell window's declaration threads through the STARTUP window create, so the main window's chrome is right from the first frame; the app's own header then takes over dragging and inset padding through the `window-drag` attribute and the `on_chrome` hook (see <a href="/native-ui">Native UI</a>). Platforms without the concept keep standard chrome. The same `titlebar` field is accepted on top-level `windows` entries.
+Each window takes a `label` plus optional `title`, `width`, `height`, `x`, `y`, `resizable`, `restore_state`, `restore_policy` (`clamp_to_visible_screen` or `center_on_primary`), `initially_hidden` (default false; create the native window ordered out until an explicit show/focus), `allows_fullscreen` (default true; false disables native fullscreen on macOS without disabling ordinary resizing), `min_width`/`min_height` (a content min-size floor the window itself enforces — macOS `contentMinSize`; the first shell window's declaration threads through the startup create like `titlebar`, negative values are a manifest error, 0 means no floor), and `titlebar` (`standard`, `hidden_inset`, `hidden_inset_tall` — the tall variant centers macOS's traffic lights in the 52pt unified band for toolbar-height headers — or `chromeless`, the fully-skinned opt-in that removes all OS chrome including the system buttons; only for apps that draw their own working window controls, see `examples/deck`). `titlebar = "hidden_inset"` hides the titlebar and extends content under it (macOS keeps the traffic lights) — the first shell window's declaration threads through the STARTUP window create, so the main window's chrome is right from the first frame; the app's own header then takes over dragging and inset padding through the `window-drag` attribute and the `on_chrome` hook (see <a href="/docs/native-ui">Native UI</a>). Platforms without the concept keep standard chrome. The same fields are accepted on top-level `windows` entries.

-Overlay presentation is also fixed at create time: `transparent` makes the top-level window alpha-capable, `always_on_top` selects its floating/topmost level, `click_through` passes pointer input to windows underneath, and `activate_on_show = false` reveals it without activating the app or taking focus. Canvas windows already use present-before-show, so these flags are applied while the window is hidden and its first alpha-correct frame becomes the first visible frame. Pair `transparent = true` with a non-opaque `gpu_alpha_mode`; `UiApp.WindowDescriptor` makes that canvas-alpha choice and uses an alpha-zero clear automatically. See the <a href="/windows#overlay-windows">overlay window recipe</a>. These fields are accepted on top-level `windows`, `shell.windows`, runtime `WindowCreateOptions`, and `UiApp.WindowDescriptor`.
+Overlay presentation is also fixed at create time: `transparent` makes the top-level window alpha-capable, `always_on_top` selects its floating/topmost level, `click_through` passes pointer input to windows underneath, `activate_on_show = false` reveals it without activating the app or taking focus, and `allows_fullscreen = false` removes macOS fullscreen participation while keeping the window resizable. Canvas windows already use present-before-show, so these flags are applied while the window is hidden and its first alpha-correct frame becomes the first visible frame. `initially_hidden = true` is stronger: it suppresses that reveal until `Cmd.showWindow` or explicit focus. Pair `transparent = true` with a non-opaque `gpu_alpha_mode`; `UiApp.WindowDescriptor` makes that canvas-alpha choice and uses an alpha-zero clear automatically. See the <a href="/docs/windows#overlay-windows">overlay window recipe</a>. These fields are accepted on top-level `windows` and `shell.windows`. Runtime `WindowCreateOptions` exposes the same controls but spells the hidden mode `.show = .hidden`; `UiApp.WindowDescriptor` exposes the overlay controls but not the initially-hidden mode.

-Windows also take `close_policy` (`quit`, the default — the close affordance really closes, behavior unchanged for every existing app — or `hide`, the menu-bar-app shape: close hides the window and the app keeps running behind its status item). Like `titlebar`, close handling is host window state fixed at create, and the first shell window's declaration threads through the startup create. `hide` is supported on macOS and Windows — on Windows it additionally requires the `"tray"` capability (the tray icon is the only re-show affordance there; a declaration without it is refused at build time with a teaching). Linux has no status item to bring a hidden window back, so the declaration is refused at build time with a teaching. See <a href="/windows#close-policy">Windows</a> and the <a href="/tray#the-menu-bar-app-lifecycle">tray lifecycle recipe</a>. The same `close_policy` field is accepted on top-level `windows` entries.
+Windows also take `close_policy` (`quit`, the default — the close affordance really closes, behavior unchanged for every existing app — or `hide`, the menu-bar-app shape: close hides the window and the app keeps running behind its status item). Like `titlebar`, close handling is host window state fixed at create, and the first shell window's declaration threads through the startup create. `hide` is supported on macOS and Windows — on Windows it additionally requires the `"tray"` capability (the tray icon is the only re-show affordance there; a declaration without it is refused at build time with a teaching). Linux has no status item to bring a hidden window back, so the declaration is refused at build time with a teaching. See <a href="/docs/windows#close-policy">Windows</a> and the <a href="/docs/tray#the-menu-bar-app-lifecycle">tray lifecycle recipe</a>. The same `close_policy` field is accepted on top-level `windows` entries.

 Supported `kind` values are `webview`, `toolbar`, `titlebar_accessory`, `sidebar`, `statusbar`, `split`, `stack`, `button`, `icon_button`, `list_item`, `checkbox`, `toggle`, `segmented_control`, `text_field`, `search_field`, `label`, `spacer`, `gpu_surface`, and `progress_indicator`.

-Each view has a required `label` and `kind`. WebView views require `url`. Optional layout fields are `parent`, `edge`, `axis`, `x`, `y`, `width`, `height`, `min_width`, `min_height`, `max_width`, `max_height`, `fill`, and `layer`. Optional behavior and accessibility metadata are `visible`, `enabled`, `role`, `accessibility_label`, `text`, and `command`. `gpu_surface` views may also set `gpu_backend`, `gpu_pixel_format`, `gpu_present_mode`, `gpu_alpha_mode`, `gpu_color_space`, and `gpu_vsync`; those fields are rejected on non-GPU view kinds. The currently implemented macOS system-WebView backend uses `metal`, `bgra8_unorm`, `timer`, `opaque`, `srgb`, and `gpu_vsync = true`. `gpu_backend` also accepts `software` (the CPU reference-renderer path); on Linux and Windows system-WebView hosts any declared backend falls back to software presentation rather than erroring. The `axis` field accepts `row` or `column` on parent containers such as `toolbar`, `sidebar`, `split`, and `stack`; it defaults to `row`.
+Each view has a required `label` and `kind`. WebView views require `url`. Optional layout fields are `parent`, `edge`, `axis`, `x`, `y`, `width`, `height`, `min_width`, `min_height`, `max_width`, `max_height`, `fill`, and `layer`. Optional behavior and accessibility metadata are `visible`, `enabled`, `role`, `accessibility_label`, `text`, and `command`. `gpu_surface` views may also set `gpu_backend`, `gpu_pixel_format`, `gpu_present_mode`, `gpu_alpha_mode`, `gpu_color_space`, and `gpu_vsync`; those fields are rejected on non-GPU view kinds. The macOS system-WebView host presents with Metal, while the Windows host presents representable binary canvas packets with Direct2D/DirectWrite; frame events expose the concrete `metal` or `direct2d` backend. `gpu_backend` accepts `metal` or `software` as portable requests; omit it to select the default. Linux falls back to software presentation, and Windows uses software for unrepresentable commands, transparent layered windows, or when Direct2D is unavailable. The `axis` field accepts `row` or `column` on parent containers such as `toolbar`, `sidebar`, `split`, and `stack`; it defaults to `row`.

 `createShellWindow` and `createShellViews` dock `edge` views against the remaining window content, let one or more top-level `fill` views use the final remaining rectangle, clamp resolved frames with any min/max size fields, and lay out parented controls such as toolbar buttons with small native defaults when explicit `x`, `y`, `width`, or `height` values are omitted. Parent containers flow omitted child positions horizontally with `axis = "row"` and vertically with `axis = "column"`. `split` containers use the same axis without inner spacing, so fixed-size children can sit beside a `fill` child. The runtime keeps the shell view slice as a layout binding and reapplies it when the window is resized, so pass data that lives for the lifetime of the window.

@@ -146,8 +146,8 @@ The runtime watches the command queue and processes these actions:
      <td>Dispatch a shortcut command event for the main window</td>
    </tr>
    <tr>
-      <td><code>tray-action &lt;item-id&gt;</code></td>
-      <td>Select a status-item dropdown row (ids from the snapshot's <code>tray-item #id</code> lines)</td>
+      <td><code>tray-action &lt;item-id&gt;</code> or <code>tray-action &lt;status-item-id&gt; &lt;item-id&gt;</code></td>
+      <td>Select a status-item dropdown row. The one-id form targets primary status item <code>#1</code>; multiple-item snapshots print <code>tray #id</code> headers</td>
    </tr>
    <tr>
      <td><code>focus &lt;view-label&gt;</code></td>
@@ -49,7 +49,7 @@ Native controls can also bind a `command` when created with `runtime.createView(
  </tbody>
 </table>

-Platform support queries are available through `window.zero.platform.supports(...)` when `js_window_api` is `true`. The command accepts every feature name from `PlatformFeature`: `main_webview`, `child_webviews`, `native_views`, `native_control_commands`, `menus`, `tray`, `shortcuts`, `dialogs`, `clipboard_text`, `clipboard_rich_data`, `open_url`, `reveal_path`, `notifications`, `recent_documents`, `credentials`, `file_drops`, `app_activation_events`, `gpu_surfaces`, `gpu_surface_scroll_drivers`, `context_menus`, `view_surface_adoption`, `audio_playback`, `audio_streaming`, `audio_spectrum`, and `window_hide_on_close`. JavaScript callers can also use the camelCase aliases — `mainWebView`, `childWebViews`, `nativeViews`, `nativeControlCommands`, `clipboardText`, `clipboardRichData`, `openUrl`, `revealPath`, `recentDocuments`, `fileDrops`, `appActivationEvents`, `gpuSurfaces`, `gpuSurfaceScrollDrivers`, `contextMenus`, `viewSurfaceAdoption`, `audioPlayback`, `audioStreaming`, `audioSpectrum`, and `windowHideOnClose`. The helper accepts either a string or a selector object with `feature` or `name`; raw bridge payloads may use the same fields. Use an explicit `builtin_bridge` policy when you want per-command origin lists.
+Platform support queries are available through `window.zero.platform.supports(...)` when `js_window_api` is `true`. The command accepts every feature name from `PlatformFeature`: `main_webview`, `child_webviews`, `native_views`, `native_control_commands`, `menus`, `tray`, `shortcuts`, `dialogs`, `clipboard_text`, `clipboard_rich_data`, `open_url`, `reveal_path`, `notifications`, `recent_documents`, `credentials`, `file_drops`, `app_activation_events`, `gpu_surfaces`, `gpu_surface_scroll_drivers`, `context_menus`, `view_surface_adoption`, `audio_playback`, `audio_streaming`, `audio_spectrum`, `microphone_capture`, `system_audio_capture`, and `window_hide_on_close`. JavaScript callers can also use the camelCase aliases — `mainWebView`, `childWebViews`, `nativeViews`, `nativeControlCommands`, `clipboardText`, `clipboardRichData`, `openUrl`, `revealPath`, `recentDocuments`, `fileDrops`, `appActivationEvents`, `gpuSurfaces`, `gpuSurfaceScrollDrivers`, `contextMenus`, `viewSurfaceAdoption`, `audioPlayback`, `audioStreaming`, `audioSpectrum`, `microphoneCapture`, `systemAudioCapture`, and `windowHideOnClose`. The helper accepts either a string or a selector object with `feature` or `name`; raw bridge payloads may use the same fields. Use an explicit `builtin_bridge` policy when you want per-command origin lists.

 ## Window commands

@@ -497,4 +497,4 @@ await window.zero.credentials.delete({
 });
 ```

-See also: [Multiple WebViews](/webviews) for frame and layer semantics, [Dialogs](/dialogs) for the full dialog type reference, [Capabilities](/capabilities) for OS capability support, and [Security](/security) for policy details.
+See also: [Multiple WebViews](/docs/webviews) for frame and layer semantics, [Dialogs](/docs/dialogs) for the full dialog type reference, [Capabilities](/docs/capabilities) for OS capability support, and [Security](/docs/security) for policy details.
@@ -1,6 +1,6 @@
 # Bridge

-For apps that [embed web content](/frontend), the bridge connects JavaScript in the WebView to native Zig handlers via JSON messages. Native-rendered apps have no bridge — markup dispatches typed messages straight into `update` (see [App Model](/app-model)).
+For apps that [embed web content](/docs/frontend), the bridge connects JavaScript in the WebView to native Zig handlers via JSON messages. Native-rendered apps have no bridge — markup dispatches typed messages straight into `update` (see [App Model](/docs/app-model)).

 ## Architecture

@@ -175,4 +175,4 @@ try {
  </tbody>
 </table>

-See also: [Builtin Commands](/bridge/builtin-commands) for `native-sdk.command.*`, `native-sdk.window.*`, `native-sdk.view.*`, `native-sdk.webview.*`, `native-sdk.dialog.*`, `native-sdk.os.*`, `native-sdk.clipboard.*`, and `native-sdk.credentials.*`.
+See also: [Builtin Commands](/docs/bridge/builtin-commands) for `native-sdk.command.*`, `native-sdk.window.*`, `native-sdk.view.*`, `native-sdk.webview.*`, `native-sdk.dialog.*`, `native-sdk.os.*`, `native-sdk.clipboard.*`, and `native-sdk.credentials.*`.
@@ -1,6 +1,6 @@
 # Building Components

-The library's built-ins cover the common register, and [theming](/theming) restyles all of them at once. This page is about the pieces the library does not hand you: how to build a component of your own — first as a markup template, then as a Zig view function when the shape needs one — how it themes, and how component files spread across an app. Component code is toolkit-extension territory, so the Zig here applies whatever language the app core is written in: a TypeScript app that needs one custom widget writes that widget in Zig and keeps its core in TypeScript. The mechanics (template grammar, import rules, slots) are specified in [Native UI](/native-ui#templates); this page builds one real component end to end.
+The library's built-ins cover the common register, and [theming](/docs/theming) restyles all of them at once. This page is about the pieces the library does not hand you: how to build a component of your own — first as a markup template, then as a Zig view function when the shape needs one — how it themes, and how component files spread across an app. Component code is toolkit-extension territory, so the Zig here applies whatever language the app core is written in: a TypeScript app that needs one custom widget writes that widget in Zig and keeps its core in TypeScript. The mechanics (template grammar, import rules, slots) are specified in [Native UI](/docs/native-ui#templates); this page builds one real component end to end.

 The ownership model in one line: **use and theme the built-ins by default; eject a library composite when you need to own its shape; build new composites from primitives when the library has no shape for it.** The last two are this page.

@@ -89,11 +89,11 @@ Args carry values; a `<slot/>` carries markup. A template body may mark one inse
 </column>
 ```

-This is the container-component pattern: the template owns the frame, the caller owns the content. The full rules (one slot per body, children without a slot are an error, ids hash as if inlined) are in [Native UI § Components](/native-ui#components).
+This is the container-component pattern: the template owns the frame, the caller owns the content. The full rules (one slot per body, children without a slot are an error, ids hash as if inlined) are in [Native UI § Components](/docs/native-ui#components).

 ## When a component needs Zig

-The markup grammar is deliberately closed, and a few shapes sit outside it — the honest list is in [Native UI § Elements](/native-ui#elements): components that carry **image ids** (pixels registered at runtime; the avatar's `image="{binding}"` is the one declarative exception), **per-cell templates** (a data grid's arbitrary render-per-column callbacks), and **Zig-side floating surfaces** (`popover`, `menu_surface`; the anchored `dropdown-menu` covers the declarative case). Beyond those, anything needing per-state styling past tokens (`ElementOptions.style`) or logic past the expression language belongs in Zig.
+The markup grammar is deliberately closed, and a few shapes sit outside it — the honest list is in [Native UI § Elements](/docs/native-ui#elements): components that carry **image ids** (pixels registered at runtime; the avatar's `image="{binding}"` is the one declarative exception), **per-cell templates** (a data grid's arbitrary render-per-column callbacks), and **Zig-side floating surfaces** (`popover`, `menu_surface`; the anchored `dropdown-menu` covers the declarative case). Beyond those, anything needing per-state styling past tokens (`ElementOptions.style`) or logic past the expression language belongs in Zig.

 A Zig component is just a function that takes the view builder and returns a node — the same primitives markup lowers to, with the same structural identity rules:

@@ -159,7 +159,7 @@ Zig components distribute the ordinary Zig way: a file per component (or a `comp

 Three moves, in order of preference:

-**Theme it.** Every built-in reads the token register, and [theme packs, overrides, and full design systems](/theming) reach every visual decision — colors, radii, control metrics, state washes, type. If your need is "the stepper, but in our palette," that is a token change, not a component.
+**Theme it.** Every built-in reads the token register, and [theme packs, overrides, and full design systems](/docs/theming) reach every visual decision — colors, radii, control metrics, state washes, type. If your need is "the stepper, but in our palette," that is a token change, not a component.

 **Eject it.** When you need to own a composite's *shape* — reorder its parts, change its structure, grow it a feature — `native eject component <name>` writes the library composite's canonical source into `src/components/`, and from then on it is your code: edit freely, SDK updates never touch it. The ejectable set is exactly the library views that are honest compositions of primitives — today `stepper` and `timeline-item` (Zig view functions; their conditional structure and formatted text sit outside the markup grammar) and `timeline` (a markup template, since the container is pure composition). Each ejected file builds a widget tree identical to its library form at the moment of ejection — held by tests in the SDK — so ejecting changes ownership, never pixels. Ejected templates are reached through `<use template="timeline" ...>`, never a new element name, so the built-in element keeps working at unmigrated call sites; ejecting twice errors instead of overwriting your edits. Engine controls (buttons, text fields, tabs, ...) are deliberately not on the menu: their behavior lives in the runtime, and the way to change them is the token system, not a fork.

@@ -0,0 +1,7 @@
+import { pageMetadata } from "@/lib/page-metadata";
+
+export const metadata = pageMetadata("built-in-components");
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return children;
+}
@@ -1,7 +1,7 @@
 # Built-in Components

-This page moved. The catalog now has a full [Components section](/components) — one page per component with engine-rendered light/dark previews, validated Native markup, the Zig builder equivalent, and attribute tables generated from the markup vocabulary.
+This page moved. The catalog now has a full [Components section](/docs/components) — one page per component with engine-rendered light/dark previews, validated Native markup, the Zig builder equivalent, and attribute tables generated from the markup vocabulary.

 The short version: the Native SDK ships a native-rendered component catalog with house-style defaults — neutral surfaces, Geist typography, subtle borders, focus states, and token-driven color, radius, shadow, blur, and motion — owned by the SDK and rendered through the retained canvas surface, not platform widget skins. Every component is expressible in Native markup through its element and programmatically through the `canvas.Ui` builder.

-The canonical catalog lives in `native_sdk.canvas.builtin_component_kinds` and `builtin_component_names`; each descriptor reports its style, root widget kind, semantic role, and composite flag, and `native_sdk.canvas.builtinComponentWidget(...)` constructs a component's default foundation directly. See [Native UI](/native-ui) for markup semantics and the runtime contract.
+The canonical catalog lives in `native_sdk.canvas.builtin_component_kinds` and `builtin_component_names`; each descriptor reports its style, root widget kind, semantic role, and composite flag, and `native_sdk.canvas.builtinComponentWidget(...)` constructs a component's default foundation directly. See [Native UI](/docs/native-ui) for markup semantics and the runtime contract.
@@ -0,0 +1,7 @@
+import { pageMetadata } from "@/lib/page-metadata";
+
+export const metadata = pageMetadata("capabilities");
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return children;
+}
@@ -1,8 +1,8 @@
 # Capabilities

-Native SDK capabilities are native OS services and app events exposed through `PlatformServices`, runtime methods, lifecycle events, and — for apps that [embed web content](/frontend) — guarded bridge commands. Native code reaches them directly; web content does not receive capability access by default. In a [`UiApp`](/app-model), clipboard access rides the effects channel (`fx.writeClipboard` / `fx.readClipboard`) so `update` never needs a runtime handle.
+Native SDK capabilities are native OS services and app events exposed through `PlatformServices`, runtime methods, lifecycle events, and — for apps that [embed web content](/docs/frontend) — guarded bridge commands. Native code reaches them directly; web content does not receive capability access by default. In a [model core](/docs/app-model), OS work rides the effects channel (`Cmd.*` in TypeScript and `fx.*` in Zig) so `update` never needs a runtime handle.

-Web content itself is declare-to-use: an app ships the embedded web layer only when it declares web intent — `"webview"` in `.capabilities`, a `.frontend` block, a `.shell` webview view, or a web engine resolved to Chromium (`.web_engine = "chromium"` in app.zon, or the `-Dweb-engine`/`--web-engine` flags) — and an app that declares none of them builds native-only, where any attempt to create a webview fails with a teaching error instead of loading a layer the app never asked for. The [`webview_layer`](/app-zon) manifest field overrides the inference in either direction. Native-only builds shed the platform web stack for real: the Windows executable carries no `WebView2Loader.dll` reference, and the Linux host neither links WebKitGTK nor requires `libwebkitgtk` on user machines.
+Web content itself is declare-to-use: an app ships the embedded web layer only when it declares web intent — `"webview"` in `.capabilities`, a `.frontend` block, a `.shell` webview view, or a web engine resolved to Chromium (`.web_engine = "chromium"` in app.zon, or the `-Dweb-engine`/`--web-engine` flags) — and an app that declares none of them builds native-only, where any attempt to create a webview fails with a teaching error instead of loading a layer the app never asked for. The [`webview_layer`](/docs/app-zon) manifest field overrides the inference in either direction. Native-only builds shed the platform web stack for real: the Windows executable carries no `WebView2Loader.dll` reference, and the Linux host neither links WebKitGTK nor requires `libwebkitgtk` on user machines.

 ## Current capability pack

@@ -10,7 +10,7 @@ Web content itself is declare-to-use: an app ships the embedded web layer only w
  <thead>
    <tr>
      <th>Capability</th>
-      <th>Zig API</th>
+      <th>Native API</th>
      <th>JavaScript command</th>
      <th>Bridge permission</th>
      <th>Current native support</th>
@@ -19,17 +19,38 @@ Web content itself is declare-to-use: an app ships the embedded web layer only w
  <tbody>
    <tr>
      <td>Open URL in system browser</td>
-      <td><code>runtime.openExternalUrl(url)</code></td>
+      <td><code>Cmd.openExternalUrl(url)</code> / <code>runtime.openExternalUrl(url)</code></td>
      <td><code>native-sdk.os.openUrl</code></td>
      <td><code>network</code></td>
-      <td>macOS, Linux, and Windows system WebView; macOS Chromium</td>
+      <td>macOS, Linux, and Windows model cores and system WebView; macOS Chromium</td>
    </tr>
    <tr>
      <td>System notification</td>
-      <td><code>runtime.showNotification(options)</code></td>
+      <td><code>Cmd.showNotification(spec)</code> / <code>fx.showNotification(options)</code> / <code>runtime.showNotification(options)</code></td>
      <td><code>native-sdk.os.showNotification</code></td>
      <td><code>notifications</code></td>
-      <td>macOS, Linux, and Windows system WebView; macOS Chromium</td>
+      <td>macOS, Linux, and Windows model cores and system WebView; macOS Chromium</td>
+    </tr>
+    <tr>
+      <td>Model persistence</td>
+      <td><code>Cmd.persist()</code> / <code>fx.persist()</code></td>
+      <td>None. Model-core effect only.</td>
+      <td>None. Gated by the <code>persist</code> build capability.</td>
+      <td>Generated TypeScript app runners on every app-data platform; Zig-core hosts receive the same named <code>core.persist</code> effect seam</td>
+    </tr>
+    <tr>
+      <td>Record store</td>
+      <td><code>Cmd.store.set/get/delete/scan/setMany</code> / <code>fx.storeSet/storeGet/storeDelete/storeScan/storeSetMany</code></td>
+      <td>None. Model-core effect only.</td>
+      <td>None. Gated by the <code>store</code> build capability.</td>
+      <td>SQLite-backed engine store in the per-app data directory; replay remains offline and the core devhost uses a process-local map</td>
+    </tr>
+    <tr>
+      <td>Relational SQLite</td>
+      <td><code>Cmd.q&lt;Name&gt;</code> / <code>Cmd.qTx</code> / <code>Sub.q&lt;Name&gt;</code> / raw <code>Cmd.db.query/exec</code> / <code>fx.dbQuery/dbExec/dbSubscribe</code></td>
+      <td>None. Model-core effect only.</td>
+      <td>None. Gated by the <code>sqlite</code> build capability.</td>
+      <td>Checked migrations and named SQL over engine-owned <code>app.db</code>; real in-memory SQLite in check, devhost, and tests; journal-only replay</td>
    </tr>
    <tr>
      <td>Native dialogs</td>
@@ -40,10 +61,10 @@ Web content itself is declare-to-use: an app ships the embedded web layer only w
    </tr>
    <tr>
      <td>Reveal path in file manager</td>
-      <td><code>runtime.revealPath(path)</code></td>
+      <td><code>Cmd.revealPath(path)</code> / <code>runtime.revealPath(path)</code></td>
      <td><code>native-sdk.os.revealPath</code></td>
      <td><code>filesystem</code></td>
-      <td>macOS, Linux, and Windows system WebView; macOS Chromium</td>
+      <td>macOS, Linux, and Windows model cores and system WebView; macOS Chromium</td>
    </tr>
    <tr>
      <td>Recent documents</td>
@@ -82,10 +103,17 @@ Web content itself is declare-to-use: an app ships the embedded web layer only w
    </tr>
    <tr>
      <td>Credential store</td>
-      <td><code>runtime.setCredential(options)</code> / <code>runtime.getCredential(key)</code> / <code>runtime.deleteCredential(key)</code></td>
+      <td><code>Cmd.credentials.set/get/delete</code> / <code>fx.credentialsSet/Get/Delete</code> / runtime equivalents</td>
      <td><code>native-sdk.credentials.set</code> / <code>native-sdk.credentials.get</code> / <code>native-sdk.credentials.delete</code></td>
-      <td><code>credentials</code></td>
-      <td>macOS system WebView and macOS Chromium through Keychain; Linux system WebView through Secret Service/libsecret when available; Windows system WebView through Credential Manager</td>
+      <td><code>credentials</code>. Model cores require both the build capability and permission; WebView commands require the bridge permission.</td>
+      <td>macOS model cores, system WebView, and Chromium through Keychain; Linux model cores and system WebView through Secret Service/libsecret when available; Windows model cores and system WebView through Credential Manager; iOS toolkit apps through generic-password Keychain entries; Android toolkit apps through an AndroidKeyStore AES-GCM key and authenticated ciphertext in app-private preferences. Core dev and test hosts use hermetic memory.</td>
+    </tr>
+    <tr>
+      <td>Local date/time formatting</td>
+      <td><code>Cmd.formatLocalTime(timestampMs, style, route)</code> / <code>runtime.formatLocalTime(...)</code></td>
+      <td>None. Effects/runtime API.</td>
+      <td>None. No bridge surface.</td>
+      <td>macOS, Linux, and Windows model cores; locale- and time-zone-aware, with results captured by session recording</td>
    </tr>
    <tr>
      <td>App activation events</td>
@@ -132,6 +160,8 @@ const support = {
  audioPlayback: await window.zero.platform.supports("audio_playback"),
  audioStreaming: await window.zero.platform.supports("audio_streaming"),
  audioSpectrum: await window.zero.platform.supports("audio_spectrum"),
+  microphoneCapture: await window.zero.platform.supports("microphone_capture"),
+  systemAudioCapture: await window.zero.platform.supports("system_audio_capture"),
 };
 ```

@@ -220,4 +250,82 @@ window.zero.on("app:activate", () => {
 });
 ```

-See also: [Builtin Commands](/bridge/builtin-commands) and [Security](/security).
+Use the `app.zon` app id as `service` when WebView code and a model core need to address the same entry. Core credential effects apply that namespace automatically; their key corresponds to the bridge `account` field.
+
+## Model cores
+
+Model-driven apps request notifications as effects. Delivery is fire-and-forget because OS focus modes and user settings remain authoritative after the host accepts the request; fake-executor tests and session replay do not display notifications.
+
+### TypeScript
+
+```ts
+case "build_finished":
+  return [model, Cmd.showNotification({
+    title: asciiBytes("Build finished"),
+    subtitle: asciiBytes("native-sdk"),
+    body: asciiBytes("All checks passed."),
+  })];
+```
+
+### Zig
+
+```zig
+.build_finished => fx.showNotification(.{
+    .title = "Build finished",
+    .subtitle = "native-sdk",
+    .body = "All checks passed.",
+}),
+```
+
+Apps using the lower-level runtime can call the same platform seam directly with `try runtime.showNotification(options)`.
+
+### Credentials
+
+Credentials are app-scoped effects, not Model data. Declare both gates; `native check` reports NS1071 for a missing capability and NS1072 for a missing permission when a TypeScript core uses `Cmd.credentials.*`. NS1073 reserves the underlying `core.credentials.*` request names for these typed factories:
+
+```zig:app.zon
+.capabilities = .{ "credentials" },
+.permissions = .{ "credentials" },
+```
+
+The manifest app id is the OS keychain service namespace and is bounded at 128 bytes, so authored code supplies only a key. Keys are NUL-free UTF-8 through 256 bytes and secrets are bounded at 2,560 bytes, the largest binary value every first-party OS backend can store whole. A get miss routes the error arm with `miss`; the other closed outcomes are `denied`, `locked`, `io_failed`, `over_bound`, and `rejected`. Set and delete route empty bytes on success, and delete is idempotent.
+
+```ts
+case "save_token":
+  return [model, Cmd.credentials.set("api-token", msg.token, {
+    key: "save-token",
+    ok: "token_saved",
+    err: "credential_failed",
+  })];
+case "load_token":
+  return [model, Cmd.credentials.get("api-token", {
+    key: "load-token",
+    ok: "token_loaded",
+    err: "credential_failed",
+  })];
+case "token_loaded":
+  // Consume msg.token immediately to construct the next effect. Do not
+  // copy it into Model, where persistence and state fingerprints can see it.
+  return [model, Cmd.fetch({
+    url: asciiBytes("https://api.example.com/me"),
+    headers: { authorization: msg.token },
+  }, { ok: "profile_loaded", err: "profile_failed" })];
+```
+
+```zig
+.save_token => |token| fx.credentialsSet(.{
+    .key = 41,
+    .credential_key = "api-token",
+    .secret = token,
+    .on_result = Effects.credentialsMsg(.credential_result),
+}),
+.load_token => fx.credentialsGet(.{
+    .key = 42,
+    .credential_key = "api-token",
+    .on_result = Effects.credentialsMsg(.credential_result),
+}),
+```
+
+Credential results still cross the effect boundary, but recording never writes secret bytes to the journal or blob store. A successful recorded get keeps only its length, a per-session salt, and a placeholder digest that is deliberately independent of the secret (so the artifact is not a password-guessing oracle). Replay supplies deterministic placeholder bytes of the same length and never opens the live keychain. Consequently, replay is suitable for control-flow verification but cannot perform a new authenticated exchange with the original token. The core devhost also stores credentials only in process memory and prints `<redacted, N bytes>`.
+
+See also: [Builtin Commands](/docs/bridge/builtin-commands) and [Security](/docs/security).
@@ -29,11 +29,11 @@ native dev [dir] --core [--script msgs.ndjson] [--watch]
 native dev --binary <path> [--manifest app.zon] [--url <url>] [--command "<cmd>"] [--timeout-ms <n>]
 ```

-Build and run the app in the current (or given) app directory — a Debug build by default, printing a one-line completion and naming any failing step. The markup hot-reload watcher and the Debug-only teaching diagnostics are compiled in only in Debug; pass `-Doptimize=...` to override. Apps with a frontend dev config also get the managed dev server — see [Dev Server](/cli/dev).
+Build and run the app in the current (or given) app directory — a Debug build by default, printing a one-line completion and naming any failing step. The markup hot-reload watcher and the Debug-only teaching diagnostics are compiled in only in Debug; pass `-Doptimize=...` to override. Apps with a frontend dev config also get the managed dev server — see [Dev Server](/docs/cli/dev).

 <dl>
  <dt><code>--core</code></dt>
-  <dd>Run the TypeScript core's logic loop under node instead of building the app: dispatch Msgs as JSON lines on stdin, watch the committed model and effect transcript, advance a virtual clock to fire timers. Honestly not a renderer — plain <code>native dev</code> runs the real app. See <a href="/typescript#the-dev-loop">TypeScript Cores</a>.</dd>
+  <dd>Run the TypeScript core's logic loop under node instead of building the app: dispatch Msgs as JSON lines on stdin, watch the committed model and effect transcript, advance a virtual clock to fire timers. Honestly not a renderer — plain <code>native dev</code> runs the real app. See <a href="/docs/typescript#the-dev-loop">TypeScript Cores</a>.</dd>
  <dt><code>--script</code></dt>
  <dd>With <code>--core</code>: replay a newline-delimited JSON message file instead of reading stdin.</dd>
  <dt><code>--watch</code></dt>
@@ -72,7 +72,7 @@ Run the app's test suite, printing the zig build summary (step/test tally) plus
 native check [dir] [--strict]
 ```

-Validate the whole tree without building the app. A TypeScript core (`src/core.ts`) runs the subset checker first — real tsc semantics plus the app-core rules, diagnostics verbatim — then every `src/**.native` markup file and `app.zon` are checked as before. With a fresh model contract (`zig-out/model-contract.zon`, refreshed by `native test`) it also checks bindings, iterables, and message tags against your `Model`/`Msg` — for a TypeScript core, against its emitted model — and warns on model state no view uses. Without the artifact it degrades to structural checking and says so loudly: "model contract: not yet built - bindings checked structurally only; run `native test` to enable typed checks". Markup accessibility findings are reported per file in full, and a failing `src/*.native` file that no Zig source embeds gets a leftover-file hint.
+Validate the whole tree without building the app. A TypeScript core (`src/core.ts`) runs the subset checker first — real tsc semantics plus the app-core rules, diagnostics verbatim — then every `src/**.native` markup file and `app.zon` are checked as before. With a fresh model contract (`zig-out/model-contract.zon`, refreshed by `native test`) it also checks bindings, iterables, and message tags against your `Model`/`Msg` — for a TypeScript core, against its model contract — and warns on model state no view uses. Without the artifact it degrades to structural checking and says so: "model contract: not yet built - bindings checked structurally only; run `native test` to enable typed checks". Markup accessibility findings are reported per file in full, and a failing `src/*.native` file that no Zig source embeds gets a leftover-file hint.

 <dl>
  <dt><code>--strict</code></dt>
@@ -87,7 +87,7 @@ Validate the whole tree without building the app. A TypeScript core (`src/core.t
 native eject [dir]
 ```

-Write an owned `build.zig`/`build.zig.zon` into the app (once); the verbs then drive your files via `zig build`. Ejecting is only for owning the build files — it is never a prerequisite: zero-config apps build, test, and [package](/packaging) directly (`native package` works on the zero-config build as-is).
+Write an owned `build.zig`/`build.zig.zon` into the app (once); the verbs then drive your files via `zig build`. Ejecting is only for owning the build files — it is never a prerequisite: zero-config apps build, test, and [package](/docs/packaging) directly (`native package` works on the zero-config build as-is).

 ### `native eject component`

@@ -95,7 +95,7 @@ Write an owned `build.zig`/`build.zig.zon` into the app (once); the verbs then d
 native eject component <name> [dir]
 ```

-Write an owned copy of a library composite into `src/components/` (once, never overwriting — ejecting again errors with the file to delete first). Ejectable today: `stepper`, `timeline`, `timeline-item` — the library views that are honest compositions of primitives; engine controls are not on the menu (theme them through [tokens](/theming) instead). `timeline` lands as a markup template (use it via `<use template="timeline" ...>`), the others as Zig view functions; each file opens with a header comment walking through the call-site migration, and each builds a widget tree identical to its library form at the moment of ejection. Unknown names get a did-you-mean plus the full ejectable list. See [Building Components](/building-components#use-eject-or-build).
+Write an owned copy of a library composite into `src/components/` (once, never overwriting — ejecting again errors with the file to delete first). Ejectable today: `stepper`, `timeline`, `timeline-item` — the library views that are honest compositions of primitives; engine controls are not on the menu (theme them through [tokens](/docs/theming) instead). `timeline` lands as a markup template (use it via `<use template="timeline" ...>`), the others as Zig view functions; each file opens with a header comment walking through the call-site migration, and each builds a widget tree identical to its library form at the moment of ejection. Unknown names get a did-you-mean plus the full ejectable list. See [Building Components](/docs/building-components#use-eject-or-build).

 ### `native doctor`

@@ -103,7 +103,7 @@ Write an owned copy of a library composite into `src/components/` (once, never o
 native doctor [--strict] [--manifest app.zon] [--web-engine system|chromium] [--cef-dir path] [--cef-auto-install]
 ```

-Check host environment, WebView, manifest, and CEF. See [native doctor](/debugging/doctor) for what each check means.
+Check host environment, WebView, manifest, and CEF. See [native doctor](/docs/debugging/doctor) for what each check means.

 ### `native validate`

@@ -151,19 +151,20 @@ Package the app for distribution. The manifest is picked up at `app.zon` and the
  <dt><code>--team-id</code></dt>
  <dd>Apple Developer Team ID.</dd>
  <dt><code>--archive</code></dt>
-  <dd>Create a distributable archive.</dd>
+  <dd>Create a distributable archive. On macOS this is a styled DMG with the app, an Applications alias, a generated or custom background, and the Finder layout declared by <code>app.zon</code>.</dd>
 </dl>

 ### Platform shortcuts

 ```sh
-native package-windows [--output path] [--binary path]
-native package-linux [--output path] [--binary path]
+native package-windows [--output path] [--binary path] [--service-binary path]
+native package-linux [--output path] [--binary path] [--service-binary path]
 native package-ios [--output path] [--binary path]
 native package-android [--output path] [--binary path]
 ```

 Per-platform shortcuts for `native package --target <platform>`.
+The desktop shortcuts use an explicit `--service-binary` when supplied; otherwise, service-bearing projects discover the normal `zig-out/bin/<app>_services[.exe]` build output just like the canonical command.

 ### `native bundle-assets`

@@ -200,7 +201,7 @@ Work with Native markup files directly, outside the app verbs.
 native automate <command>
 ```

-Interact with the automation server of a running automation-enabled app. See [Automation](/automation) for the full workflow.
+Interact with the automation server of a running automation-enabled app. See [Automation](/docs/automation) for the full workflow.

 <dl>
  <dt><code>automate list</code></dt>
@@ -237,8 +238,8 @@ Interact with the automation server of a running automation-enabled app. See [Au
  <dd>Dispatch a trackpad pinch gesture at a gpu-surface view (<code>scale</code> is the final multiplicative zoom for the gesture; the anchor point defaults to the view center).</dd>
  <dt><code>automate shortcut &lt;id&gt;</code></dt>
  <dd>Dispatch a shortcut command event.</dd>
-  <dt><code>automate tray-action &lt;item-id&gt;</code></dt>
-  <dd>Select a status-item dropdown row.</dd>
+  <dt><code>automate tray-action &lt;item-id&gt;</code> / <code>automate tray-action &lt;status-item-id&gt; &lt;item-id&gt;</code></dt>
+  <dd>Select a status-item dropdown row; the one-id shorthand targets primary status item <code>#1</code>.</dd>
  <dt><code>automate focus &lt;view-label&gt;</code></dt>
  <dd>Focus a native or WebView-backed view.</dd>
  <dt><code>automate focus-next</code> / <code>automate focus-previous</code></dt>
@@ -259,7 +260,7 @@ native skills get <name> [--full]
 native skills get --all [--full]
 ```

-List and print the built-in AI agent skills the CLI ships — the version-matched content the `npx skills add vercel-labs/native` discovery skill loads from. See [Agent Skills](/skills) for the one-command agent install, what each skill covers, and how to deliver one to an agent.
+List and print the built-in AI agent skills the CLI ships — the version-matched content the `npx skills add vercel-labs/native` discovery skill loads from. See [Agent Skills](/docs/skills) for the one-command agent install, what each skill covers, and how to deliver one to an agent.

 <dl>
  <dt><code>skills list</code></dt>
@@ -4,7 +4,7 @@ import { CodeToggle } from "@/components/code-toggle";

 # Accordion

-A disclosure surface with a header. The header label comes from the `text` attribute, children show while `selected` is true, and a header press dispatches `on-toggle` — the model owns the open state, in the usual [model–message loop](/native-ui). Items render the house accordion look — borderless rows divided by hairline separators, with the chevron on the trailing edge rotating as the item expands — and size themselves: the header band alone while closed, header plus content while open, so a toggle reflows the column with no hand-managed heights.
+A disclosure surface with a header. The header label comes from the `text` attribute, children show while `selected` is true, and a header press dispatches `on-toggle` — the model owns the open state, in the usual [model–message loop](/docs/native-ui). Items render the house accordion look — borderless rows divided by hairline separators, with the chevron on the trailing edge rotating as the item expands — and size themselves: the header band alone while closed, header plus content while open, so a toggle reflows the column with no hand-managed heights.

 <ComponentPreview name="accordion" alt="Open and closed accordion items rendered by the engine" caption="an open item and a closed one" />

@@ -18,7 +18,7 @@ An inline callout surface. The title comes from the `text` attribute and renders
 </column>
 ```

-For a message the user can dismiss, render the alert under an `if` and clear the flag from a button inside it — the model owns the visibility, as with every surface. For modal interruptions reach for [dialog](/components/dialog), [drawer](/components/drawer), or [sheet](/components/sheet) instead.
+For a message the user can dismiss, render the alert under an `if` and clear the flag from a button inside it — the model owns the visibility, as with every surface. For modal interruptions reach for [dialog](/docs/components/dialog), [drawer](/docs/components/drawer), or [sheet](/docs/components/sheet) instead.

 ## Programmatic construction (Zig)

@@ -3,7 +3,7 @@ import { AttrTable } from "@/components/attr-table";

 # Badge

-A text leaf for counts and statuses: the content is the label (with `{}` interpolation), `variant` picks the color treatment, and an optional `icon` draws a built-in vector icon inline before the text. Badges are not interactive — for a pressable chip see [toggle-button](/components/toggle) or [button](/components/button).
+A text leaf for counts and statuses: the content is the label (with `{}` interpolation), `variant` picks the color treatment, and an optional `icon` draws a built-in vector icon inline before the text. Badges are not interactive — for a pressable chip see [toggle-button](/docs/components/toggle) or [button](/docs/components/button).

 <ComponentPreview name="badge" alt="Badge variants rendered by the engine" caption="default, secondary, outline, destructive, and icon badges" />

@@ -3,7 +3,7 @@ import { AttrTable } from "@/components/attr-table";

 # Breadcrumb

-A row container for a hierarchy trail — children flow horizontally, and the trail is plain composition: muted `text` leaves for the ancestors, a muted `chevron-right` [icon](/components/icon) between them, and an unmuted leaf for the current page. Binding `on-press` on a text leaf makes it pressable, so each ancestor can navigate.
+A row container for a hierarchy trail — children flow horizontally, and the trail is plain composition: muted `text` leaves for the ancestors, a muted `chevron-right` [icon](/docs/components/icon) between them, and an unmuted leaf for the current page. Binding `on-press` on a text leaf makes it pressable, so each ancestor can navigate.

 <ComponentPreview name="breadcrumb" alt="A breadcrumb trail rendered by the engine" caption="muted ancestors, chevron separators, and the current page" />

@@ -3,9 +3,9 @@ import { AttrTable } from "@/components/attr-table";

 # Button Group

-A row container that attaches related action [buttons](/components/button) into one segmented bar. At the default gap of 0 the engine collapses the group into a single shape: the first segment keeps its leading corners, the last its trailing corners, middles square off, and each interior boundary is drawn by exactly one shared 1px seam. Every segment stays its own button — its own label, its own `on-press`, its own disabled state.
+A row container that attaches related action [buttons](/docs/components/button) into one segmented bar. At the default gap of 0 the engine collapses the group into a single shape: the first segment keeps its leading corners, the last its trailing corners, middles square off, and each interior boundary is drawn by exactly one shared 1px seam. Every segment stays its own button — its own label, its own `on-press`, its own disabled state.

-For an exclusive active segment use a [toggle-group](/components/toggle) (pressed state is the toggle family's job) or [tabs](/components/tabs); a button group is attached *actions*, never a choice.
+For an exclusive active segment use a [toggle-group](/docs/components/toggle) (pressed state is the toggle family's job) or [tabs](/docs/components/tabs); a button group is attached *actions*, never a choice.

 <ComponentPreview name="button-group" alt="A flush button group rendered by the engine" caption="three outline actions attached into one bar with shared seams" />

@@ -33,7 +33,7 @@ Grouped buttons keep their variant's fill — a primary or secondary group reads

 ## Spacing out

-`gap` above 0 opts out of the attached treatment: the children render as ordinary separate buttons with full corners and borders. Use a plain [row](/components/layout) if the actions are not related enough to attach.
+`gap` above 0 opts out of the attached treatment: the children render as ordinary separate buttons with full corners and borders. Use a plain [row](/docs/native-ui) if the actions are not related enough to attach.

 ```html
 <button-group gap="8">
@@ -58,4 +58,4 @@ ui.el(.button_group, .{}, .{

 <AttrTable attrs={["gap", "cross"]} />

-Children are ordinary buttons; see the [button attributes](/components/button) for the per-segment surface.
+Children are ordinary buttons; see the [button attributes](/docs/components/button) for the per-segment surface.
@@ -36,7 +36,7 @@ Four sizes: `sm`, `default`, `lg`, and `icon` — the icon size renders a square

 ## Icons

-`icon` names a built-in vector icon (see the [icon registry](/components/icon)) drawn inline before the label — one hit target, one enabled/disabled tint.
+`icon` names a built-in vector icon (see the [icon registry](/docs/components/icon)) drawn inline before the label — one hit target, one enabled/disabled tint.

 <ComponentPreview name="button-icons" alt="Buttons with inline icons rendered by the engine" />

@@ -56,7 +56,7 @@ Hover and press styling is engine-owned render state; `disabled` is a source att

 ## Button Group

-[`button-group`](/components/button-group) attaches related action buttons into one segmented bar — flush segments, one shared corner language, one interior seam. It has its own page.
+[`button-group`](/docs/components/button-group) attaches related action buttons into one segmented bar — flush segments, one shared corner language, one interior seam. It has its own page.

 ## Programmatic construction (Zig)

@@ -3,7 +3,7 @@ import { AttrTable } from "@/components/attr-table";

 # Card

-`card` is the bordered, elevated surface container. It is a stacking container — children layer on top of each other and `gap` is rejected — so put a single `column` (or `row`) inside for flow. Cards carry 24px of content padding by default (the house inset; 16 at `size="sm"`) — set `padding` explicitly to override it. Binding `on-press` makes the whole surface pressable, the list-of-cards pattern. For the plain surface with the same stacking contract, see [panel](/components/panel).
+`card` is the bordered, elevated surface container. It is a stacking container — children layer on top of each other and `gap` is rejected — so put a single `column` (or `row`) inside for flow. Cards carry 24px of content padding by default (the house inset; 16 at `size="sm"`) — set `padding` explicitly to override it. Binding `on-press` makes the whole surface pressable, the list-of-cards pattern. For the plain surface with the same stacking contract, see [panel](/docs/components/panel).

 <ComponentPreview name="card" alt="A card rendered by the engine" />

@@ -4,7 +4,7 @@ import { CodeToggle } from "@/components/code-toggle";

 # Checkbox

-A binary value control: the label rides the `text` attribute — checkbox is not a text-bearing element, so text content between the tags is rejected with a teaching error (`label="..."` alone names one for accessibility without a visible label). The model binds `checked`, and `on-toggle` dispatches its Msg — the engine never flips state on its own. For a single choice among options, use [radio](/components/radio); for an on/off setting rendered as a sliding thumb, use [switch](/components/switch).
+A binary value control: the label rides the `text` attribute — checkbox is not a text-bearing element, so text content between the tags is rejected with a teaching error (`label="..."` alone names one for accessibility without a visible label). The model binds `checked`, and `on-toggle` dispatches its Msg — the engine never flips state on its own. For a single choice among options, use [radio](/docs/components/radio); for an on/off setting rendered as a sliding thumb, use [switch](/docs/components/switch).

 <ComponentPreview name="checkbox" alt="Checkboxes rendered by the engine" caption="checked, unchecked, and disabled checkboxes" />

@@ -0,0 +1,105 @@
+import { ComponentPreview } from "@/components/component-preview";
+import { AttrTable } from "@/components/attr-table";
+
+# Code
+
+Presents source text as bare monospace content with deterministic, theme-aware syntax highlighting. The component supplies no background, border, radius, shadow, or padding; wrap it in a `panel`, `card`, or another container when the surrounding design calls for chrome. Code is selectable and read-only by default. Add `editable` and `on-input` to opt into the multiline editor without losing syntax colors. Code wraps by default. Set `wrap="false"` to preserve logical lines inside one horizontal scroll region, and opt into logical line numbers with `line-numbers`.
+
+HTML-family highlighting understands HTML, XML, SVG, JSX, and TSX structure: element or component tags, attributes, strings, comments, numbers, and JavaScript/TypeScript expressions receive distinct theme-token colors.
+
+<ComponentPreview name="code" alt="A bare JSX code sample with syntax highlighting and line numbers" caption="Bare highlighted content with JSX tags, attributes, strings, expressions, and an unwrapped horizontal viewport" />
+
+## Markup
+
+```html
+<code
+  source="{component_source}"
+  language="tsx"
+  line-numbers
+  wrap="false"
+  width="480"
+  label="Accordion example"
+/>
+```
+
+`source` is required and must be one `{binding}` producing text. `language` is a literal lexer name; unknown names are validation errors. Line numbers are off by default and remain decorative, so selecting and copying a numbered block returns only the source text. Numbered presentation is limited to 128 logical lines; longer sources keep all code and omit the gutter.
+
+## Added and removed lines
+
+Diff presentation follows Geist Code Block in the default and Geist theme packs, across light and dark appearances. `added-lines` and `removed-lines` apply full-width green/red washes and renderer-owned `+`/`-` markers while the underlying source, syntax highlighting, selection, and copied text stay unchanged.
+
+<ComponentPreview name="code-diff" alt="A JavaScript configuration diff with green added and red removed lines" caption="Geist-style added and removed lines over ordinary JavaScript highlighting" />
+
+```html
+<code
+  source="{migration_source}"
+  language="javascript"
+  line-numbers
+  added-lines="5"
+  removed-lines="2-4"
+  wrap="false"
+  width="480"
+  label="Configuration migration"
+/>
+```
+
+Line specs are one-based comma lists and inclusive ranges: `added-lines="5, 9-11"`. They annotate clean source—the `+` and `-` are decoration, not bytes callers must splice into the model. This keeps the selected/copied result usable and lets `language` continue highlighting the real grammar. A line cannot be both added and removed. Diff metadata is bounded to lines 1–128; read-only sources longer than 128 lines keep every source byte and omit the diff treatment.
+
+For editable code, apply each `TextInputEvent` to the same model-owned buffer that supplies `source`:
+
+```html
+<code
+  source="{document}"
+  language="tsx"
+  editable
+  on-input="edit_document"
+  line-numbers
+  wrap="false"
+  grow="1"
+  label="Document editor"
+/>
+```
+
+The editor path includes multiline selection, caret navigation, IME, clipboard, and undo/redo behavior. It does not add textarea background, border, focus ring, or padding.
+
+Surface styling belongs to a wrapper:
+
+```html
+<panel padding="12">
+  <code source="{component_source}" language="tsx" />
+</panel>
+```
+
+## Programmatic construction (Zig)
+
+```zig
+ui.code(.{
+    .language = .javascript,
+    .line_numbers = true,
+    .added_lines = &.{5},
+    .removed_lines = &.{ 2, 3, 4 },
+    .wrap = false,
+    .width = 480,
+    .semantics = .{ .label = "Configuration migration" },
+}, model.migration_source)
+```
+
+The editable path uses the same `added_lines` and `removed_lines` options when an editor needs annotations; keep those line numbers synchronized as edits change the document.
+
+The Zig builder composes the same way when chrome is wanted:
+
+```zig
+ui.panel(.{ .padding = 12 }, .{
+    ui.code(.{ .language = .html }, model.component_source),
+})
+```
+
+The public lexer model is `native_sdk.canvas.code`. `languageFromName` resolves markup spellings, `languageFromFence` reads a Markdown info string, and `highlight` produces the same bounded, theme-colored span runs both renderers use.
+
+## Languages
+
+Zig; JavaScript and TypeScript; JSX and TSX; JSON; YAML; shell; Python; Rust; C, C++, C#, Java, Kotlin, and Swift; Go; HTML, XML, and SVG; CSS, SCSS, and Less; SQL; and Markdown. An omitted language renders plain monospace.
+
+## Attributes
+
+<AttrTable element="code" attrs={["source", "language", "editable", "on-input", "line-numbers", "added-lines", "removed-lines", "wrap", "width", "height", "min-width", "grow", "key", "global-key", "label"]} />
@@ -3,7 +3,7 @@ import { AttrTable } from "@/components/attr-table";

 # Combobox

-`combobox` is a trigger-only primitive like [select](/components/select), but the trigger is a text entry with a menu affordance: `on-input` names a Msg variant that receives every edit as a text-input event (`canvas.TextInputEvent` in a Zig core; the `TextInputEvent` union from `@native-sdk/core/text` in a TypeScript core), and the model filters the options as the user types. The options themselves are composed the same way as the select's — an anchored [dropdown-menu](/components/dropdown-menu) of menu-items beside the trigger in a `stack`, rendered under an `if`, with `on-dismiss` clearing the model's open flag when Escape or a click outside closes the surface.
+`combobox` is a trigger-only primitive like [select](/docs/components/select), but the trigger is a text entry with a menu affordance: `on-input` names a Msg variant that receives every edit as a text-input event (`canvas.TextInputEvent` in a Zig core; the `TextInputEvent` union from `@native-sdk/core/text` in a TypeScript core), and the model filters the options as the user types. The options themselves are composed the same way as the select's — an anchored [dropdown-menu](/docs/components/dropdown-menu) of menu-items beside the trigger in a `stack`, rendered under an `if`, with `on-dismiss` clearing the model's open flag when Escape or a click outside closes the surface.

 <ComponentPreview name="combobox" alt="A combobox rendered by the engine" caption="a combobox trigger with its search placeholder" />

@@ -4,7 +4,7 @@ import { CodeToggle } from "@/components/code-toggle";

 # Dialog

-A modal dialog surface rendered in place: the title comes from the `text` attribute, and visibility is model-owned — wrap the dialog in an `if` on an open flag. `on-dismiss` dispatches when Escape or a click outside dismisses the surface, so `update` clears the flag; the engine hides the surface immediately as an optimistic echo, and the source tree wins on the next rebuild. The title is drawn by the surface chrome and children stack over the full content box, so lead the body column with a fixed-height spacer that clears the title line. For edge-anchored surfaces with the same contract, see [drawer](/components/drawer) and [sheet](/components/sheet).
+A modal dialog surface rendered in place: the title comes from the `text` attribute, and visibility is model-owned — wrap the dialog in an `if` on an open flag. `on-dismiss` dispatches when Escape or a click outside dismisses the surface, so `update` clears the flag; the engine hides the surface immediately as an optimistic echo, and the source tree wins on the next rebuild. The title is drawn by the surface chrome and children stack over the full content box, so lead the body column with a fixed-height spacer that clears the title line. For edge-anchored surfaces with the same contract, see [drawer](/docs/components/drawer) and [sheet](/docs/components/sheet).

 <ComponentPreview name="dialog" alt="A modal dialog rendered by the engine" caption="title chrome, body content, and a trailing action row" />

@@ -3,7 +3,7 @@ import { AttrTable } from "@/components/attr-table";

 # Drawer

-A side-anchored surface with the same contract as [dialog](/components/dialog): rendered in place, title via the `text` attribute, visibility model-owned behind an `if`, and `on-dismiss` dispatched on Escape or click-outside so `update` clears the open flag. As with the dialog, the title chrome is engine-drawn and children stack over the full content box, so lead the body column with a fixed-height spacer. For the bottom-edge variant, see [sheet](/components/sheet).
+A side-anchored surface with the same contract as [dialog](/docs/components/dialog): rendered in place, title via the `text` attribute, visibility model-owned behind an `if`, and `on-dismiss` dispatched on Escape or click-outside so `update` clears the open flag. As with the dialog, the title chrome is engine-drawn and children stack over the full content box, so lead the body column with a fixed-height spacer. For the bottom-edge variant, see [sheet](/docs/components/sheet).

 <ComponentPreview name="drawer" alt="A drawer surface rendered by the engine" caption="a side drawer with a title and stacked controls" />

@@ -24,7 +24,7 @@ A vertical menu surface whose children are `menu-item` elements. Setting `anchor
 </stack>
 ```

-Handle the item's Msg in `update` and clear the open flag there — a menu press does not dismiss implicitly. [Select](/components/select) and [combobox](/components/combobox) build their option lists from exactly this pattern (with `anchor-alignment="stretch"` for the select-menu width).
+Handle the item's Msg in `update` and clear the open flag there — a menu press does not dismiss implicitly. [Select](/docs/components/select) and [combobox](/docs/components/combobox) build their option lists from exactly this pattern (with `anchor-alignment="stretch"` for the select-menu width).

 ## Programmatic construction (Zig)

@@ -63,7 +63,7 @@ ui.el(.menu_surface, .{ .min_width = 220 }, .{
 })
 ```

-Right-click context menus are a separate channel with its own element: a `<context-menu>` child on a pressable element (or `ElementOptions.context_menu` in Zig views) presents the platform's native menu — `NSMenu` on macOS, `TrackPopupMenu` on Windows, `GtkPopoverMenu` on Linux — and falls back to an anchored surface at the click point on hosts without one; selections dispatch typed Msgs. The anchored `dropdown-menu` here is for app-designed surfaces you open yourself (pickers, button dropdowns, hold-reveal menus) — see [Menus](/menus).
+Right-click context menus are a separate channel with its own element: a `<context-menu>` child on a pressable element (or `ElementOptions.context_menu` in Zig views) presents the platform's native menu — `NSMenu` on macOS, `TrackPopupMenu` on Windows, `GtkPopoverMenu` on Linux — and falls back to an anchored surface at the click point on hosts without one; selections dispatch typed Msgs. The anchored `dropdown-menu` here is for app-designed surfaces you open yourself (pickers, button dropdowns, hold-reveal menus) — see [Menus](/docs/menus).

 ## Attributes

@@ -4,7 +4,7 @@ import { IconGallery } from "@/components/icon-gallery";

 # Icon

-A vector icon leaf: `name` selects the icon, tint comes from the `foreground` color token, and size from `width`/`height` (square by default). A bare literal name is one of the curated built-in stroke icons — the markup compiler and the Zig builder both validate it at comptime against the registry, so icon references never rot. The same grammar powers the inline `icon` attribute on [button](/components/button), toggle-button, list-item, menu-item, and badge, where the icon draws as part of the control's single hit target.
+A vector icon leaf: `name` selects the icon, tint comes from the `foreground` color token, and size from `width`/`height` (square by default). A bare literal name is one of the curated built-in stroke icons — the markup compiler and the Zig builder both validate it at comptime against the registry, so icon references never rot. The same grammar powers the inline `icon` attribute on [button](/docs/components/button), toggle-button, list-item, menu-item, and badge, where the icon draws as part of the control's single hit target.

 <ComponentPreview name="icon" alt="Built-in vector icons rendered by the engine" caption="a row of registry icons at the default size and tint" />

@@ -3,7 +3,7 @@ import { AttrTable } from "@/components/attr-table";

 # Input Group

-The composer shape: one bordered field wrapping a [textarea](/components/textarea) plus an accessory row of controls inside the same border — attach on the bottom-left, send on the bottom-right. The group wears the focus ring whenever focus is on any control inside it, and the textarea's own chrome dissolves automatically, so the whole group reads as a single field. The textarea keeps its full behavior: `text` and `placeholder` bind from the model, `on-input` hears every edit, `on-submit` rides the primary chord, and `autofocus` lands the keyboard on mount.
+The composer shape: one bordered field wrapping a [textarea](/docs/components/textarea) plus an accessory row of controls inside the same border — attach on the bottom-left, send on the bottom-right. The group wears the focus ring whenever focus is on any control inside it, and the textarea's own chrome dissolves automatically, so the whole group reads as a single field. The textarea keeps its full behavior: `text` and `placeholder` bind from the model, `on-input` hears every edit, `on-submit` handles submission, `submit-on-enter="true"` opts a chat composer into plain-Enter submission, and `autofocus` lands the keyboard on mount.

 <ComponentPreview name="input-group" alt="An input group rendered by the engine" />

@@ -13,7 +13,7 @@ The textarea comes first (document order is focus order), then the optional `inp

 ```html
 <input-group label="Message composer" height="120">
-  <textarea placeholder="Type a message" text="{draft}" on-input="draft_edited" on-submit="send" />
+  <textarea placeholder="Type a message" text="{draft}" submit-on-enter="true" on-input="draft_edited" on-submit="send" />
  <input-group-actions>
    <button icon="plus" variant="ghost" size="icon" on-press="attach" label="Attach"></button>
    <spacer grow="1" />
@@ -33,6 +33,7 @@ ui.inputGroup(.{
 }, ui.el(.textarea, .{
    .placeholder = "Type a message",
    .text = model.draft,
+    .submit_on_enter = true,
    .on_input = Ui.inputMsg(.draft_edited),
    .on_submit = .send,
    .semantics = .{ .label = "Message" },
@@ -18,7 +18,7 @@ Single-line text entry. `input` and `text-field` are the same foundation under t
 </column>
 ```

-The core side is a text field the control renders and one arm reducing each edit over it — [Native UI § Messages](/native-ui#messages) walks the whole contract:
+The core side is a text field the control renders and one arm reducing each edit over it — [Native UI § Messages](/docs/native-ui#messages) walks the whole contract:

 <CodeToggle>

@@ -45,7 +45,7 @@ pub fn email(model: *const Model) []const u8 {

 ## Search field

-`search-field` renders the search affordance but binds exactly like an input; pair it with a model-filtered list. Whenever the field holds text it also shows a built-in clear affordance — a small x inside its trailing edge — and pressing it (or pressing Escape while focused) clears through the standard text-edit path, so the `on-input` handler receives the clear like any other edit and a model-owned buffer empties with it. No attribute enables or disables this; searchable fields simply carry it. For text entry that opens a menu of suggestions, see [combobox](/components/combobox).
+`search-field` renders the search affordance but binds exactly like an input; pair it with a model-filtered list. Whenever the field holds text it also shows a built-in clear affordance — a small x inside its trailing edge — and pressing it (or pressing Escape while focused) clears through the standard text-edit path, so the `on-input` handler receives the clear like any other edit and a model-owned buffer empties with it. No attribute enables or disables this; searchable fields simply carry it. For text entry that opens a menu of suggestions, see [combobox](/docs/components/combobox).

 <ComponentPreview name="search-field" alt="A search field rendered by the engine" />

@@ -20,7 +20,18 @@ A vertical stack of items. The rows are `list-item` text leaves — the label is

 ## Selection and activation

-When selection is model state — the accent row your app owns — rows use the desktop gesture split: a single click selects (`on-press`), and the primary action (open the record, play the track) rides the double click and Enter. Bind the primary action twice — `on_double_press` for the pointer (Zig builder only; markup has no double-click event) and `on-submit` for the keyboard:
+When selection is model state — the accent row your app owns — rows use the desktop gesture split: a single click selects (`on-press`), and the primary action (open the record, play the track) rides the double click and Enter. In markup, bind the primary action to both `on-double-press` and `on-submit`:
+
+```html
+<list-item
+  selected="{selected_id == track.id}"
+  on-press="select_track:{track.id}"
+  on-double-press="play_track:{track.id}"
+  on-submit="play_track:{track.id}"
+>{track.title}</list-item>
+```
+
+The Zig builder spells the same channels with underscores:

 ```zig
 ui.listItem(.{
@@ -33,11 +44,11 @@ ui.listItem(.{

 The double click is additive, never a delay: the first click dispatches the select on its own release, the second release dispatches the play — select-then-act, with no press timer. On the keyboard, a bound `on-submit` makes plain Enter the row's primary action while Space keeps select; rows without one resolve Enter as select, unchanged.

-The arrows stay app-owned after clicking around: pointer focus on a plain list row is quiet (no ring), and a quietly focused row routes no keys — arrows and Enter fall through to the app-level key fallback, where a selection-owning app moves its own selection. Tab onto a row draws the ring and restores the row's full keymap (arrows walk the rows, Space selects, Enter submits), and rows carrying `role="treeitem"` keep the [tree](/components/tree)'s roving keymap under either register. The full routing order is in [Native UI § Keyboard routing](/native-ui#keyboard-routing-focus-registers-quiet-list-rows-and-the-app-level-fallback); `examples/soundboard`'s track lists are the live reference for the whole pattern.
+The arrows stay app-owned after clicking around: pointer focus on a plain list row is quiet (no ring), and a quietly focused row routes no keys — arrows and Enter fall through to the app-level key fallback, where a selection-owning app moves its own selection. Tab onto a row draws the ring and restores the row's full keymap (arrows walk the rows, Space selects, Enter submits), and rows carrying `role="treeitem"` keep the [tree](/docs/components/tree)'s roving keymap under either register. The full routing order is in [Native UI § Keyboard routing](/docs/native-ui#keyboard-routing-focus-registers-quiet-list-rows-and-the-app-level-fallback); `examples/soundboard`'s track lists are the live reference for the whole pattern.

 ## Virtualization

-For long row sets, turn on `virtualized` and give each row a fixed `virtual-item-extent` — the engine lays out only the rows in view. Loop the model data with a keyed `for` and dispatch a payload per row. The rows still all BUILD (this bounds layout and paint, not the tree), so it suits row sets the model already holds — hundreds, not hundreds of thousands. For dataset-scale rows where the view should only ever build the visible window, use the builder's [virtual list](/components/virtual-list).
+For long row sets, turn on `virtualized` and give each row a fixed `virtual-item-extent` — the engine lays out only the rows in view. Loop the model data with a keyed `for` and dispatch a payload per row. The rows still all BUILD (this bounds layout and paint, not the tree), so it suits row sets the model already holds — hundreds, not hundreds of thousands. For dataset-scale rows where the view should only ever build the visible window, use the builder's [virtual list](/docs/components/virtual-list).

 ```html
 <list virtualized="true" virtual-item-extent="28" grow="1">
@@ -68,4 +79,4 @@ List:

 List-item:

-<AttrTable attrs={["text", "icon", "selected", "disabled", "on-press", "on-submit"]} />
+<AttrTable attrs={["text", "icon", "selected", "disabled", "on-press", "on-double-press", "on-submit"]} />
--- a/Show More
+++ b/Show More