{"owner":"vercel-labs","repo":"native","hasSkills":true,"totalSkillsCount":69,"totalTokensCount":67073,"categories":["anthropic-skill","root-instruction","plugin-manifest","cursor-rule"],"hasMcp":false,"mcpConfig":null,"found":["skill-data/automation/SKILL.md","skill-data/ts-services/SKILL.md","skill-data/zig/SKILL.md","skill-data/ts-core/SKILL.md","skill-data/native-ui/SKILL.md","AGENTS.md","skills/native-sdk/SKILL.md","evals/package.json","docs/AGENTS.md","evals/pnpm-lock.yaml","evals/README.md","skill-data/core/SKILL.md","evals/tsconfig.json","packages/native-sdk/package.json","packages/native-sdk/README.md","packages/core/package.json","packages/core/package-lock.json","packages/core/pnpm-lock.yaml","tools/guest-mac/agents.md","tools/guest-mac/README.md","tools/linux-truth/README.md","tools/windows-truth/README.md","evals/cases/ts-tag-input-core/eval.json","evals/cases/ts-habits-core/eval.json","evals/cases/ts-expenses-filter/eval.json","evals/cases/ts-countdown-bugfix/eval.json","evals/cases/templates-settings-app/eval.json","evals/cases/settings-picker/eval.json","evals/cases/release-dashboard/eval.json","evals/cases/process-monitor/eval.json","evals/cases/playlist-row-actions/eval.json","evals/cases/metrics-dashboard/eval.json","evals/cases/kanban-board/eval.json","evals/cases/inspector-window/eval.json","evals/cases/habits-tracker/eval.json","evals/cases/file-browser-panes/eval.json","evals/cases/expenses-table/eval.json","evals/cases/dual-sysinfo-panel/eval.json","evals/cases/dual-pomodoro-timer/eval.json","evals/cases/dual-notes-autosave/eval.json","evals/cases/dual-list-delete-fix/eval.json","evals/cases/dual-ledger-csv-split/eval.json","evals/cases/dual-feed-table/eval.json","evals/cases/disk-status-spans/eval.json","evals/cases/chat-composer/eval.json","evals/cases/brand-icon-package/eval.json","skill-data/ts-services/references/service-surface.md","skill-data/core/references/app-model-runtime.md","skill-data/core/references/bridge-security-native-capabilities.md","skill-data/core/references/frontend-assets.md","skill-data/core/references/project-anatomy.md","skill-data/core/references/web-engines-packaging-debugging.md","packages/native-sdk/npm/win32-x64/package.json","packages/native-sdk/npm/win32-x64/README.md","packages/native-sdk/npm/win32-arm64/package.json","packages/native-sdk/npm/win32-arm64/README.md","packages/native-sdk/npm/linux-x64-musl/package.json","packages/native-sdk/npm/linux-x64-musl/README.md","packages/native-sdk/npm/linux-x64-gnu/package.json","packages/native-sdk/npm/linux-x64-gnu/README.md","packages/native-sdk/npm/linux-arm64-musl/package.json","packages/native-sdk/npm/linux-arm64-musl/README.md","packages/native-sdk/npm/linux-arm64-gnu/package.json","packages/native-sdk/npm/linux-arm64-gnu/README.md","packages/native-sdk/npm/darwin-x64/package.json","packages/native-sdk/npm/darwin-x64/README.md","packages/native-sdk/npm/darwin-arm64/package.json","packages/native-sdk/npm/darwin-arm64/README.md",".cursorrules (knative-istio-typesense-gpu-cursorrules-prompt-fil.mdc)"],"skills":{"skill-data/automation/SKILL.md":"---\nname: automation\ndescription: Automation and verification guide for running Native SDK apps. Use when the user asks to test a running app, inspect runtime state, list windows, wait for readiness, drive widgets, take deterministic screenshots, send bridge commands, debug why automation is not connected, create smoke tests, or verify a Native SDK example in a GUI-capable session.\n---\n\n# Automate Native SDK apps\n\nEvery Native SDK app embeds an automation server — native-rendered apps and WebView-shell apps alike. It works through file-based IPC in `.zig-cache/native-sdk-automation/` and is intended for smoke tests, CI checks with a GUI session, and quick runtime inspection: accessibility snapshots, widget driving through the real input paths, deterministic reference-renderer screenshots, readiness/state assertions, and bridge round-trips.\n\nAutomation is not browser DOM automation. It reports runtime/window/widget state, drives retained-canvas widgets, and can ask the runtime to reload or dispatch bridge requests. For DOM testing of the optional WebView path, use the frontend framework's tests or a browser automation tool against the dev server.\n\n## What automation can verify\n\n- An automation-enabled app started and published `ready=true`.\n- The runtime loaded the expected app name, source kind, and window metadata.\n- The main window exists and is focused/open.\n- The JavaScript-to-Zig bridge can round-trip a request through `native automate bridge`.\n- Builtin window/WebView commands work when exercised by a smoke test.\n- Reload requests are accepted by the runtime.\n- Real pixels of retained-canvas (`gpu_surface`) views: `native automate screenshot ` renders the view's current canvas frame through the deterministic CPU reference renderer and writes a PNG artifact. Two captures of an unchanged scene are byte-identical, so screenshots can back golden-image or \"did the UI change\" checks.\n\n## What automation cannot verify\n\n- Screenshots of WebView content. `screenshot` covers `gpu_surface` canvas views only; there is no DOM/WebView pixel capture.\n- Arbitrary DOM queries and clicks.\n- Browser network assertions.\n\n## Prerequisites\n\nBuild/run an app with automation enabled. Generated examples usually expose `-Dautomation=true`:\n\n```bash\nzig build run -Dplatform=macos -Dautomation=true\n```\n\nRepository examples may have specialized steps:\n\n```bash\nzig build run-webview -Dplatform=macos -Dautomation=true\nzig build test-webview-smoke -Dplatform=macos\n```\n\nThe runner must pass an automation server into `RuntimeOptions`:\n\n```zig\nconst server = native_sdk.automation.Server.init(io, \".zig-cache/native-sdk-automation\", \"My App\");\nvar runtime = native_sdk.Runtime.init(.{\n .platform = my_platform,\n .automation = server,\n});\n```\n\nApps built without `-Dautomation=true` usually ignore automation files.\n\n## Commands\n\n```bash\nnative automate wait\nnative automate assert 'gpu_nonblank=true' 'role=button name=\"Reset\"'\nnative automate assert --absent 'error event='\nnative automate list\nnative automate snapshot\nnative automate reload\nnative automate screenshot inbox-canvas\nnative automate screenshot inbox-canvas 2\nnative automate widget-action canvas 2 press\nnative automate widget-click canvas 3\nnative automate widget-hold canvas 3\nnative automate widget-context-press canvas 3\nnative automate widget-drag canvas 4 0.25 0.82\nnative automate widget-wheel canvas 5 18\nnative automate widget-key canvas tab\nnative automate widget-key canvas cmd+c\nnative automate widget-pinch canvas 1.5\nnative automate widget-pinch canvas 0.5 120 80\nnative automate profile on\nnative automate profile off\nnative automate bridge '{\"id\":\"smoke\",\"command\":\"native.ping\",\"payload\":{\"source\":\"automation\"}}'\n```\n\nIf using the repository-built CLI:\n\n```bash\nzig-out/bin/native automate wait\nzig-out/bin/native automate snapshot\n```\n\n## Snapshot assertions (`automate assert`)\n\nPrefer `native automate assert` over `snapshot | grep` chains: it polls, so no sleeps, and its failure output carries the evidence (each missing pattern plus the snapshot tail).\n\n```bash\nnative automate assert 'gpu_nonblank=true' 'role=button name=\"Reset\"' 'count: 0'\nnative automate assert --timeout-ms 10000 '4 open'\nnative automate assert --absent 'error event=' 'dispatch_errors=[1-9]'\n```\n\nSemantics:\n\n- Every argument is a regex that must match somewhere in `snapshot.txt`. The command polls (100ms interval) until all match, then exits 0.\n- `--timeout-ms ` bounds the polling (default 30000). On timeout it prints `missing: ` for each unmatched pattern, the last 20 snapshot lines, and exits non-zero — CI-friendly, no wrapper script needed.\n- `--absent` inverts the whole invocation: every pattern must NOT match (poll until gone). Mix presence and absence by running two invocations.\n- Supported regex subset: literals, `.`, postfix `*` `+` `?`, line anchors `^`/`$`, classes `[a-z]`/`[^0-9]`, and `\\d \\w \\s` (with uppercase negations). No groups or alternation — pass multiple patterns instead.\n- Quote patterns in single quotes so the shell leaves `\"`, `$`, and `\\d` alone.\n\n## Standard workflow\n\n1. Start the app with automation enabled.\n2. Run `native automate wait` to block until `snapshot.txt` contains `ready=true`.\n3. Run `native automate assert '' ...` for state checks, or `native automate snapshot` to eyeball app/window/source metadata.\n4. Run `native automate list` to inspect window summaries.\n5. Run `native automate bridge '...'` for bridge round-trip checks.\n6. Use `native automate widget-action [value]` to exercise retained canvas widget actions. `set_text` routes through the SAME input path real typing uses (focus, select-all, then a text-input event), so a TEA app's `on_input` mirror receives the edits and model state stays consistent with the on-screen field — it is not a presentation-only write.\n7. Use `native automate widget-click ` to exercise pointer-style retained widget routing. `widget-hold ` drives a press-and-hold through the same path — pointer down, the reserved hold timer fired, then the suppressed release — so `on_hold` Msgs are live-drivable (a target without `on_hold` degrades to the click a real long press is). `widget-context-press ` is the secondary click: it presents the widget's context menu, or dispatches `on_hold` immediately when the route declares none.\n8. Use `native automate widget-drag [start-y-ratio end-y-ratio]` for continuous pointer controls.\n9. Use `native automate widget-wheel ` for retained widget scroll input. Wheel targets must be interactive/scrollable widgets — a plain layout column or text node is not a wheel target; aim at the scroll/list widget id from the snapshot. Failures land in the snapshot as named reasons: `error event=automation.widget_wheel name=WheelTargetUnknown|WheelTargetNotInteractive|WheelTargetHasEmptyBounds detail=\"\"`.\n10. Use `native automate widget-key [text]` for focused retained widget keyboard input. The key accepts modifier chords — `cmd+a`, `cmd+c`, `cmd+v`, `cmd+x`, `ctrl+shift+arrowleft` (`cmd` sets the primary shortcut modifier on every platform) — so select-all/copy/cut/paste and shift-extended selection are drivable; after a copy, widget lines in the snapshot show the live selection as `selection=a..b`, and the copied text lands on the real system clipboard (`pbpaste` on macOS).\n11. Use `native automate widget-pinch [x y]` for trackpad pinch gestures against a gpu-surface view: the runtime dispatches the real `pinch_begin`/`pinch_change`/`pinch_end` platform events, with one change carrying `scale - 1`. `` is the FINAL multiplicative zoom for the gesture — the cumulative gesture scale (the product of `1 + delta`) lands exactly on it — `1.5` zooms in 50%, `0.5` zooms out to half. The optional anchor point is view-local points, defaulting to the view center. Apps hear it through the pinch channel (`Options.on_pinch` / the TS core's `pinchMsg`).\n12. Use `native automate screenshot [scale]` to capture the named `gpu_surface` view's canvas as `screenshot-.png` (the CLI prints the artifact path and waits for the file).\n13. Before driving an app-menu command, inspect the snapshot's `command id=\"...\"` catalog and `app-menu` / `app-menu-item` rows to prove the running app loaded the expected `app.zon` or runner declarations. Then use `native automate menu-command ` to dispatch the same `.menu_command` platform event a real selection emits; the verb remains a raw event injector, so the snapshot receipt is what validates registration.\n14. Use `native automate tray-action ` for the primary status item, or `native automate tray-action ` for an explicit item. Both select a dropdown row through the same platform event a real menu-bar click emits (command dispatch with source `.tray`). Live items appear in `snapshot.txt` as `tray #status-id title=\"...\" visible=... items=N` followed by ` tray-item #item-id ...` rows — the menu bar is outside every window capture, so this is the automation evidence for every model-driven item. Unknown id pairs degrade into the dispatch-error ring as `automation.tray_action`.\n15. Use `native automate reload` to request a WebView reload.\n16. Use `native automate profile on` to enable per-stage frame timing: while on, `snapshot.txt` carries a `frame_profile` line with rolling p50/p90/max microseconds per pipeline stage (`rebuild`, `layout`, `reconcile`, `emit`, `a11y`, `plan`, `patch`, `encode`, `present`, `host_decode`, `host_draw`), each with a lifetime sample count (`_n=`). Drive some interactions, then `native automate snapshot | grep -o 'frame_profile.*'` to read where frame time goes; `profile off` stops recording and drops the line. Turning it on starts a fresh sample window.\n\n## Screenshots\n\n`screenshot [scale]` asks the runtime to rasterize the view's\ncurrent retained canvas frame through the deterministic CPU reference\nrenderer — the same pixel path the Linux software presentation uses — and\npublish it as an uncompressed PNG at\n`.zig-cache/native-sdk-automation/screenshot-.png`. The file is\nwritten atomically (temp file + rename), so its presence means the PNG is\ncomplete.\n\nDeterminism semantics:\n\n- Screenshots render at scale 1 by default regardless of the display's\n backing scale, so an unchanged scene produces byte-identical PNGs from\n capture to capture on the same machine. Pass an explicit scale (for\n example `2`) for high-DPI pixel dimensions.\n- Screenshots use the live retained scene, including live design tokens and\n platform text measurement (CoreText on macOS): the layout matches what is\n on screen. Glyphs are rasterized by the reference renderer from the\n bundled faces, not by the platform's font rasterizer, so screenshots are a\n deterministic layout/structure/color signal rather than a platform\n font-rendering signal.\n- Cross-machine byte-identity is only guaranteed where text metrics are\n deterministic (the null platform's estimator). On platforms with a native\n text measurement provider, text widths can differ between OS versions, so\n compare screenshots taken on the same machine or assert on properties\n (dimensions, changed/unchanged) rather than exact bytes across machines.\n- OS-level captures (`screencapture -x` on macOS) are NOT a substitute: in a\n shell without Screen Recording permission they exit 0 and silently return\n wallpaper-only images with no app window in them. If you shell out for a\n real-pixel capture, verify the image is not blank/wallpaper before trusting\n it; `automate screenshot` plus a semantics snapshot is the reliable pair.\n\n## Bridge smoke test pattern\n\nThe request must be JSON with an ID, command, and payload:\n\n```bash\nnative automate bridge '{\"id\":\"smoke\",\"command\":\"native.ping\",\"payload\":{\"source\":\"automation\"}}'\n```\n\nAutomation sends the request with origin `zero://inline`. The app's bridge policy must allow that origin or the call will reject with `permission_denied`. For packaged asset origins, app code often allows `zero://app`; for automation smoke tests, add `zero://inline` only when the test needs it.\n\nExpected response shape depends on the handler. A typical `native.ping` handler returns:\n\n```json\n{\"id\":\"smoke\",\"ok\":true,\"result\":{\"message\":\"pong\",\"count\":1}}\n```\n\nIf the command fails, inspect the bridge error code:\n\n- `unknown_command`: no handler registered or wrong command name.\n- `permission_denied`: origin or permission policy blocked it.\n- `handler_failed`: Zig handler returned an error or invalid JSON.\n- `payload_too_large`: request exceeded bridge limits.\n\n## File protocol\n\nThe default directory is `.zig-cache/native-sdk-automation/`, resolved against the CLI's CURRENT WORKING DIRECTORY — run `native automate` from the app project's directory (where the app was launched). The dir is created by the running app, never by the CLI: a command sent from the wrong cwd fails loudly (`error: no automation dir at `) instead of queueing into a dir no app reads, and every queued command prints the absolute dir it wrote to — check that line when a command seems to do nothing.\n\nFiles:\n\n- `snapshot.txt`: app name, readiness, source kind, source size, window metadata, accessibility summary. The `ready=true` line also carries `protocol=` (the CLI/app handshake: the CLI refuses snapshots — and command queues to a live app — whose protocol version is not its own, naming both versions; the fix is rebuilding whichever binary is stale and comparing `native version`), `dispatch_errors=` and `dropped_trace_records=`, and recent degraded handler/update errors appear as ` error event= name= timestamp_ns=...` lines — a handler error no longer exits the app, so grep these to notice one happened. While `profile on` is active, a `frame_profile _p50_us=... _p90_us=... _max_us=... _n=...` line follows the header with per-stage frame timing. The header also carries `markup_watch=armed|off` — whether the markup hot-reload watch is armed (armed only in builds where the app wired `.markup` with a `watch_path` and `io`, or registered compiled fragments through `fragment_watch` — i.e. Debug dev builds).\n- `windows.txt`: window list.\n- `command.txt`: command input written by CLI and consumed by runtime. The slot is single-entry and the app consumes one command per presented frame: `native automate ` WAITS for the running app to consume it and prints `delivered -> ` on success — it refuses/fails loudly instead of silently overwriting an unconsumed command, and exits non-zero if the app never consumes it.\n- `bridge-response.txt`: last bridge response.\n- `screenshot-.png`: deterministic reference-rendered PNG of a `gpu_surface` view, written by the `screenshot` command.\n\nThe runtime polls `command.txt`. After processing a command, it writes `done`.\n\n## Debugging automation failures\n\nIf `native automate wait` times out with NO snapshot file at all, it prints a teaching error naming the automation dir it watched and pointing at `-Dautomation=true` and the working directory — start from that message. Otherwise:\n\n1. Confirm the app is still running.\n2. Confirm it was built with `-Dautomation=true`.\n3. Confirm the runner passes `automation` into `Runtime.init`.\n4. Check `.zig-cache/native-sdk-automation/snapshot.txt`.\n5. Delete stale files in `.zig-cache/native-sdk-automation/` and restart the app.\n6. Run with more tracing, for example `zig build run -Dtrace=all`.\n\nIf the CLI reports an automation protocol mismatch (or a snapshot with no protocol version): the `native` binary and the app were built from different framework versions — rebuild the older side (stale `zig-out/bin` copies of the CLI are the classic cause; `native version` prints the commit the binary was built from).\n\nStale INSTANCES are called out too: automate verbs print a LOUD warning when the publishing app's process started BEFORE the newest binary in `zig-out/bin` was built — a leftover instance from an earlier run impersonating the new build. Kill it and relaunch the fresh binary before trusting any snapshot.\n\nIf `snapshot` says no app connected:\n\n- The automation directory may not exist yet.\n- The app may be running from a different working directory.\n- The app may be built without automation.\n- The app may not have reached runtime startup.\n\nIf bridge automation fails:\n\n- Check command name spelling.\n- Check app handler registration.\n- Check bridge policy origins for `zero://inline`.\n- Check runtime permissions.\n- Check that the handler returns valid JSON.\n\n## CI and smoke tests\n\nUse automation for minimal integration confidence:\n\n```bash\nzig build test-webview-smoke -Dplatform=macos\n```\n\nA good smoke test:\n\n1. Builds an example with `-Dautomation=true` and `-Djs-bridge=true`.\n2. Starts the app in a GUI-capable session.\n3. Waits for readiness.\n4. Verifies snapshot metadata (`automate assert` with the patterns that matter).\n5. Sends `native.ping`.\n6. Exercises builtin windows/WebViews if the app enables them.\n7. Fails on timeout or unexpected bridge response.\n\nApps scaffolded with `native init --full` ship this as `.github/workflows/ci.yml` (the zero-config default scaffold skips CI): a null-platform `zig build test` job plus a Linux Xvfb smoke job that launches the binary, runs `automate wait`, asserts on the snapshot with `automate assert`, and checks a non-empty `automate screenshot` artifact. Extend that file rather than writing grep chains by hand.\n\nDo not use automation for exhaustive UI testing. It is a runtime and bridge smoke layer.\n\n## Notes\n\n- Automation is compile-time gated: apps built without `-Dautomation=true` ignore automation files.\n- Screenshots cover retained-canvas (`gpu_surface`) views only; WebView pixels are not captured.\n- WebView DOM interaction is intentionally out of scope for this file-based automation layer.\n- Use `native skills get core --full` for app architecture, bridge policy, packaging, and debugging context.\n","skill-data/ts-services/SKILL.md":"---\nname: ts-services\ndescription: Authoring guide for Native SDK TypeScript services under src/services: ordinary scriptc static-tier TypeScript reached through generated typed Cmd clients, shared record shapes, hermetic vendored npm, streaming, deadlines, cancellation, devhost simulation, authority, replay, and the two carriers (in-process thread pool, child subprocess). Use when adding or modifying src/services modules, moving Node/JSON/regex/Map/Date/class work out of a core, or fixing NS1065-NS1067.\n---\n\n# Author TypeScript services behind the effect boundary\n\nUse `src/services/**/*.ts` for imperative work that needs ordinary TypeScript beyond the deterministic core subset: `fs`, `path`, `process`, `os`, `child_process`, `fetch`, regexes, JSON, `Map`/`Set`, `Date`, and classes supported by the pinned scriptc static tier. Both classes compile with the exact scriptc version in `packages/core/package.json`; neither enables `--dynamic` or ships a JavaScript engine. The exact verdict for every surface the compiler currently projects — with each status and refusal code, plus the manifest's explicit coverage limits — is `references/service-surface.md`, generated from the pinned compiler's own manifest; consult it rather than guessing compiler capability.\n\nThe class line is hard:\n\n- `src/core.ts` and its imports outside `src/services/` retain NS1001–NS1064 and `deterministic: true`.\n- The core never imports a service file, even type-only (NS1065). It imports generated command constructors from `@native-sdk/services`.\n- A service may import shared, subset-legal declarations from the core class. Put every boundary record, enum, or union there so one declaration is authoritative on both sides.\n- A service may import compiler-supported Node built-ins and exact packages declared by app.zon. Undeclared bare imports teach NS1066.\n\n## Typed operation surface\n\nEvery directly exported, non-default named function is an operation named `.`. It must be synchronous, have a body, take zero or one explicitly annotated request, and explicitly return a contract-encodable result. Boundary data may use booleans, numbers, integer-class numbers, bytes, optionals, readonly slices, and named records/enums/kind-unions. Functions and behavior-bearing classes do not cross.\n\n```ts\n// src/shared.ts — core-class file, imported by both classes\nexport type ParseRequest = {\n readonly source: Uint8Array;\n readonly caseSensitive: boolean;\n};\n\nexport type ParseResult = {\n readonly bytes: Uint8Array;\n readonly matched: boolean;\n};\n\n// src/services/feeds.ts\nimport type { ParseRequest, ParseResult } from \"../shared.ts\";\n\nexport function parse(request: ParseRequest): ParseResult {\n const text = new TextDecoder().decode(request.source);\n const matched = request.caseSensitive ? /feed/.test(text) : /feed/i.test(text);\n return { bytes: new TextEncoder().encode(JSON.stringify({ matched })), matched };\n}\n```\n\n`services.contract.json` carries the complete type table, operation names, exact compiler pin, source hashes, package facts, deadlines, streaming declarations, and `deterministic: false`. Generated host codecs, the Zig registry/result decoders, and the typed client consume that sidecar; none re-read source to infer a second truth.\n\nExplicit boundary throws must be exactly inline `{ kind, message }` shapes with a string-valued message and must escape the operation. They arrive as UTF-8 JSON bytes on the error arm. Do not throw `new Error(...)` from the exported surface.\n\n## Call through the generated client\n\nImport from `@native-sdk/services`; `native check` derives this virtual module, and build/dev stage the same projection without writing `src/services.gen.ts` into the author tree. The editor copy lives under ignored `node_modules/@native-sdk/services`.\n\n```ts\nimport { feedsParse } from \"@native-sdk/services\";\nimport type { ParseRequest, ParseResult } from \"./shared.ts\";\n\nexport type Msg =\n | { readonly kind: \"parse\"; readonly request: ParseRequest }\n | { readonly kind: \"parsed\"; readonly result: ParseResult }\n | { readonly kind: \"parse_failed\"; readonly error: Uint8Array };\n\ncase \"parse\":\n return [model, feedsParse(msg.request, {\n key: \"feed-parse\",\n ok: \"parsed\",\n err: \"parse_failed\",\n })];\n```\n\nThe generated route type proves that `ok` names the one Msg arm carrying exactly the declared result and `err` names a one-bytes-field arm. Raw `Cmd.request(name, bytes, route)` remains available as the low-level byte seam.\n\nKeys share the engine effect-key space. A duplicate live service key rejects with `rejected` through `err`. Same-key requests run strictly FIFO on both carriers; the in-process carrier runs different keys in parallel across its pool instances. Terminal results and stream events are journaled; replay feeds the recorded events without starting a child process or a pool thread.\n\n## Hermetic npm\n\nResolve packages only with an explicit author action:\n\n```bash\nnative vendor . escape-string-regexp@5.0.0\n```\n\nThe command installs with lifecycle scripts disabled in a temporary directory, copies the flattened package graph into `src/services/vendor/`, retains package/license files, computes canonical tree hashes, and rewrites app.zon's `service_packages` with exact names, `X.Y.Z` versions, and hashes. Check those bytes and manifest facts into source control.\n\nBuilds never run npm or use the network. They verify package identity and every vendored byte, stage only declared packages, and invoke scriptc with `--npm-static `. `auto`, dynamic-island fallback, and `--dynamic` are refused. Anything below 100% static coverage fails: `native check` preserves the coverage note verbatim and names the three options—choose another exact package, port/vendor a suitable implementation, or wait for compiler support. The checked-in package spike (`tests/ts-services/npm-static-spike.json`) passed four of five deliberately small candidates and refused `micromark`; npm support is selective.\n\n## Streaming, cancellation, and deadlines\n\nA last `emit` capability declares a stream. Each typed chunk becomes canonical bytes on the existing external channel; the operation still returns one typed terminal result.\n\n```ts\nimport type { ServiceCancellation } from \"@native-sdk/core\";\n\nexport type ParseChunk = { readonly bytes: Uint8Array; readonly index: number };\n\n/**\n * @deadlineMs 5000\n * @streamBuffer 8\n */\nexport function parseLarge(\n request: ParseRequest,\n emit: (chunk: ParseChunk) => void,\n cancellation: ServiceCancellation,\n): ParseResult {\n for (let index = 0; index < request.source.length; index += 4096) {\n cancellation.throwIfCancelled();\n emit({ bytes: request.source.slice(index, index + 4096), index });\n }\n return parse(request);\n}\n```\n\nImport `ServiceCancellation` as a type from `@native-sdk/core`; it is legal only as the final capability parameter. The generated client route additionally requires `channelKey` and a channel-event Msg arm. `@streamBuffer` is a 1–64 in-flight contract cap (default 8); `@deadlineMs` is a 1–86400000 operation deadline. A terminal result closes the channel after its interim frames. `Cmd.cancel(key)` flips the token, closes a streaming channel, sends `cancelled` through `err`, and drops every later chunk. Deadline expiry flips the same token and sends JSON with `kind: \"timeout\"`. Poll `cancelled()` or call `throwIfCancelled()` at bounded intervals; a short cooperative grace period follows the token, and an operation that unwinds inside it keeps its instance (child process or pool instance) warm. Ignoring the token has a per-carrier hard edge: the child is killed and the next request starts a clean host; the in-process carrier abandons that instance's thread, routes the failure, and adds a fresh instance to the pool. The abandoned dispatch keeps its key reserved until it physically stops, so a same-key replacement cannot overlap its side effects. A detected runtime trap routes `kind: \"service_trap\"` and poisons only the instance it fired in.\n\n## Dev loop, authority, and current limits\n\n`native dev --core` imports service modules in an isolated Node worker, verifies the same package hashes, decodes the same request contract, cooperatively interrupts cancellation/deadline work, maps errors through the same arms, and emits stream chunks through the same channel-event shape. Use `--script scenario.ndjson --watch` for repeatable logic iterations. The devhost reads `NATIVE_SDK_SESSION_RECORD`/`NATIVE_SDK_SESSION_REPLAY`, writes the native journal format, and starts no service worker during replay. Service-only recordings cross between it and the packaged runtime; packaged recordings containing other effect families must be replayed with `native automate replay`, and devhost rejects those records explicitly. `native dev` runs the compiled service executable beside the real app.\n\nCarrier selection is a build fact: `.service_carrier = \"in_process\" | \"child\"` in app.zon (or `-Dservice-carrier`). Unset/`\"auto\"` preserves the child carrier on desktop and resolves to the in-process pool on iOS/Android (mobile apps cannot spawn a sibling process; an explicit `\"child\"` there is refused with a teaching). The in-process archive is available for native Linux, cross-Linux x86_64/aarch64 (`aarch64-linux-android` included), native Windows x86_64, cross-Windows x86_64 GNU, and the Mach-O targets — macOS, `aarch64-ios`, `aarch64-ios-simulator` — built on macOS. `.service_pool_size` (or `-Dservice-pool-size`, 1–16) sets the in-process pool width; the default is min(4, cores).\n\nAuthority differs by carrier. The child process runs with the app's privileges and app-data cwd, receives an explicit environment allowlist (path, user/home/temp, locale/time zone, certificate, and proxy variables; platform equivalents on Windows) with `NATIVE_SDK_*` internals stripped, and its stdout belongs to framed transport (diagnostics go to stderr). In-process services share the app process outright: the app's full environment and working directory, no transport-owned stdout — and a hardware fault (stack overflow) or `process.exit()` in service code takes the app with it, so the child carrier remains the fully isolated option. Each pool worker owns a separate service-module instance, so mutable module globals are worker-local and requests on different keys may observe different copies; keep shared durable state outside module globals. Either way this authority is why service work never runs synchronously inside `update`.\n\nCurrent limits:\n\n- child executables are desktop-only and use the broad compiler matrix (same-platform builds, Linux/Windows GNU cross-targets from desktop hosts, and macOS targets from macOS), while in-process archives follow the localization matrix above (mobile targets are archive-only: iOS from a macOS host at the 15.0 floor, Android from any desktop host with an NDK at the API 26 floor); Windows MSVC builds natively on a matching Windows host, while cross-Windows uses GNU because Zig supplies that target's CRT and system libraries; any explicitly spelled Linux `-gnu` target — even one matching the build host — must also spell its glibc (`x86_64-linux-gnu.2.36` or later, or `-musl`) because Zig otherwise selects the runtime's too-old default floor;\n- synchronous static-tier operations only—async services wait for the next compiler/runtime phase;\n- no JavaScript engine or dynamic npm fallback;\n- storage remains engine-owned effects, not a service-layer database shortcut;\n- custom widgets, renderers, platform integration, and new engine capabilities remain Zig toolkit extensions.\n","skill-data/zig/SKILL.md":"---\nname: zig\ndescription: Zig 0.16 idioms for Native SDK code, indexed by compile error. Load when `zig build` fails on std APIs with errors like \"struct 'fs' has no member named 'cwd'\", \"struct 'array_list.Aligned(u8,null)' has no member named 'init'\", \"struct 'std' has no member named 'io'\", \"no member named 'GeneralPurposeAllocator'\", \"no member named 'getEnvMap'\", or \"invalid format string\" - the signature of code written for Zig 0.15 or earlier. Covers main(std.process.Init), std.Io file IO and writers, ArrayList, process spawning, environment, clocks and sleep, sockets, custom formatting, and build.zig module shapes, each as this SDK writes them.\n---\n\n# Zig 0.16 for Native SDK code\n\nThe Native SDK requires Zig 0.16.0 (`minimum_zig_version` in `build.zig.zon`; the CLI pins the same version and offers a checksum-verified download into `~/.native/toolchains/` when the `zig` on PATH does not match). Training data and older guides teach Zig 0.15 idioms, and 0.16 moved everything that touches the outside world — files, stdout, clocks, sleeping, process spawning, sockets — behind an explicit `std.Io` value, while containers became allocator-per-call. Each section below is headed by the exact compile error the old idiom produces, so search this file by error text.\n\nTwo rules resolve most failures:\n\n- Operations on the outside world take a `std.Io` first (or right after the receiver). Get one from `init.io` in `main(init: std.process.Init)`, from `std.testing.io` in tests, or from `std.Io.Threaded` in code with no `Init` to thread through.\n- Containers are unmanaged: initialize with `.empty` and pass the allocator to every mutating call.\n\nIn a UiApp, `update` never sees an `Io` — persistence, record and relational storage, secure credentials, subprocesses, HTTP, clocks, and timers go through the typed effects channel (`fx.persist`, `fx.storeSet`/`storeGet`/`storeDelete`/`storeScan`/`storeSetMany`, `fx.dbQuery`/`dbExec`, `fx.credentialsSet`/`credentialsGet`/`credentialsDelete`, `fx.readFile`/`appendFile`/`statFile`/`deleteFile`/streaming file verbs, `fx.spawn`, `fx.fetch`, `fx.wallMs`, `fx.startTimer`; see `native skills get native-ui`). Whole-file IO stays capped at 1 MiB; streamed reads deliver 256-KiB chunks, and streamed writes finalize atomically on close. External raw paths require the `filesystem` permission, while the app's six resolved directories are exempt after symlink-safe canonicalization. Raw `std.Io` belongs in `main`, tests, and standalone tools. Record-store apps declare `\"store\"`; relational apps declare `\"sqlite\"`; credentials require both the `\"credentials\"` capability and permission. Credential Msg arms carry `EffectCredentialsResult`; consume successful get bytes immediately and never retain them in Model. The engine owns database paths and app-scoped credential namespaces, while every result still returns as a Msg and crosses the replay journal (credential bytes are redacted). Use `TestHarness().createWithRelationalStore` for a hermetic in-memory relational database and `TestHarness().createWithCredentials` for a hermetic in-memory credential store. And because Zig analyzes lazily, a 0.15-ism can hide in code only one build path references: run BOTH `zig build` and `zig build test` before calling a change done.\n\n## error: struct 'heap' has no member named 'GeneralPurposeAllocator' — allocators come from `main(init: std.process.Init)`\n\nZig 0.15 and earlier:\n\n```zig\npub fn main() !void {\n var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n defer _ = gpa.deinit();\n const allocator = gpa.allocator();\n}\n```\n\nZig 0.16: `main` takes `std.process.Init`, which carries the process-wide allocators, the `Io`, the environment, and the args — nothing to construct or deinit:\n\n```zig\npub fn main(init: std.process.Init) !void {\n const gpa = init.gpa; // general purpose, leak-checked in Debug\n const arena = init.arena.allocator(); // process-lifetime arena, freed on exit\n const io = init.io; // the Io every std call below wants\n const args = try init.minimal.args.toSlice(arena);\n if (init.environ_map.get(\"HOME\")) |home| { ... }\n}\n```\n\nThe CLI's own entry point is the live reference: `tools/native-sdk/main.zig`. Generated **Zig-core** apps have this shape — `main(init: std.process.Init)` passes `init` through to `runner.runWithOptions(app, options, init)` and `init.io` to the markup hot-reload watcher (see the older Zig-core examples' `src/main.zig`). Default TypeScript apps have no authored Zig entry point. `std.heap.page_allocator` still exists for allocations that live for the whole process. Library code that cannot take an `Init` builds its own `Io`: `var threaded = std.Io.Threaded.init(allocator, .{});` then `threaded.io()` (`src/platform/macos/root.zig`).\n\n## error: struct 'fs' has no member named 'cwd' — file IO moved to `std.Io.Dir`\n\n`std.fs.cwd()`, `std.fs.File`, and `std.fs.selfExePath` are gone (`std.fs` retains only `path` helpers and deprecated aliases). The directory handle is `std.Io.Dir`, and every operation takes `io` right after the receiver:\n\n```zig\nconst cwd = std.Io.Dir.cwd();\nconst content = try cwd.readFileAlloc(io, \"app.zon\", allocator, .limited(1024 * 1024));\ndefer allocator.free(content);\ntry cwd.writeFile(io, .{ .sub_path = \"out.txt\", .data = bytes });\nvar file = try cwd.openFile(io, path, .{});\ndefer file.close(io);\ntry cwd.deleteTree(io, \"zig-out/tmp\");\n```\n\nNote the `readFileAlloc` argument order (`io`, path, allocator, limit) and the size limit as `std.Io.Limit` — `.limited(n)` or `.unlimited`. Live references: `tools/native-sdk/skills.zig` (readFileAlloc), `src/tooling/manifest.zig` (openFile), `src/tooling/cef.zig` tests (writeFile with `std.testing.io`). Path buffers size with `std.Io.Dir.max_path_bytes`. For the executable's own path, `std.fs.selfExePath(&buf)` became `std.process.executablePath(io, &buf)`, returning the length (`tools/native-sdk/skills.zig`).\n\n## error: struct 'std' has no member named 'io' — writers are `std.Io.Writer`, stdout is `std.Io.File.stdout()`\n\n`std.io.getStdOut().writer()` and `std.io.fixedBufferStream` are gone. Stdout takes `io` plus a caller-owned buffer, and the printable interface lives one field deep:\n\n```zig\nvar stdout_buffer: [4096]u8 = undefined;\nvar stdout_writer = std.Io.File.stdout().writer(io, &stdout_buffer);\nconst stdout = &stdout_writer.interface;\ndefer stdout.flush() catch {};\ntry stdout.print(\"{s}\\n\", .{message});\n```\n\nForgetting `flush()` means no output — the buffer is yours. `std.debug.print` is unchanged and needs no `io`; prefer it for diagnostics. The `fixedBufferStream` replacement is a fixed writer over a stack buffer, and the written bytes come back from `buffered()`:\n\n```zig\nvar buf: [256]u8 = undefined;\nvar writer = std.Io.Writer.fixed(&buf);\ntry writer.print(\"n={d}\", .{42});\nconst written = writer.buffered();\n```\n\nFor building a string of unknown size, use an allocating writer instead of an ArrayList writer: `var w = std.Io.Writer.Allocating.init(allocator); defer w.deinit();` then print through `w.writer` (`src/automation/server.zig`). One-shot formatting still has `std.fmt.bufPrint` and `std.fmt.allocPrint`, unchanged. Functions that accept a writer take `*std.Io.Writer`, not `anytype` (`tools/native-sdk/skills.zig`; fixed-writer reference: `src/tooling/doctor.zig`).\n\n## error: struct 'array_list.Aligned(u8,null)' has no member named 'init' — ArrayList is unmanaged\n\n`std.ArrayList(T).init(allocator)` is gone; the list no longer stores its allocator. Initialize with `.empty` and pass the allocator to every call that can allocate or free:\n\n```zig\nvar list: std.ArrayList(u8) = .empty;\ndefer list.deinit(allocator);\ntry list.append(allocator, 'a');\ntry list.appendSlice(allocator, \"bc\");\nconst owned = try list.toOwnedSlice(allocator);\n```\n\nThis is everywhere in the SDK — `src/tooling/templates.zig` builds every generated file this way, `tools/native-sdk/skills.zig` collects skills this way. Passing a managed-style call (`list.append('a')`) fails with \"member function expected 2 argument(s), found 1\". `std.StringHashMap`/`std.AutoHashMap` still have managed `.init(allocator)` forms; only explicitly `Unmanaged` maps take `.empty` (`tools/native-sdk/markup_lsp.zig`).\n\n## error: invalid format string 's' for type — enums print with `{t}`, format methods with `{f}`\n\n`{s}` is for strings only. Enums and tagged unions print their tag name with `{t}` (equivalent to `@tagName`, which also still works):\n\n```zig\nstd.debug.print(\"native {t}: `zig build` step failed (exit code {d})\\n\", .{ verb, code });\n```\n\n(`src/tooling/verbs.zig`.) Custom format methods changed shape twice over: the old four-parameter signature no longer compiles (`error: struct 'fmt' has no member named 'FormatOptions'`), and `{}` no longer calls a `format` method at all — it prints the default field dump silently. Declare the 0.16 signature and print with `{f}`:\n\n```zig\npub fn format(self: Point, writer: *std.Io.Writer) std.Io.Writer.Error!void {\n try writer.print(\"({d},{d})\", .{ self.x, self.y });\n}\n// call site\ntry writer.print(\"{f}\\n\", .{point});\n```\n\n## error: struct 'time' has no member named 'sleep' / 'milliTimestamp' — clocks live on Io\n\n`std.time` keeps only the unit constants (`ns_per_ms`, `ms_per_s`, ...) and epoch helpers. Sleeping and reading clocks take `io` and typed durations:\n\n```zig\ntry std.Io.sleep(io, std.Io.Duration.fromMilliseconds(50), .awake);\nconst now_ns: i128 = std.Io.Timestamp.now(io, .real).nanoseconds;\n```\n\n(`src/runtime/automation_liveness_tests.zig`, `src/automation/server.zig`.) In app code, do not reach for either: `native_sdk.nowMs()` / `native_sdk.monotonicMs()` are the facade, `fx.wallMs()` is the journaled read inside `update`, and `model.clock` is the testable seam — the native-ui skill's Time section owns that pattern.\n\n## error: struct 'process.Child' has no member named 'init' — spawning is `std.process.spawn(io, ...)`\n\nThe two-step `Child.init` + `child.spawn()` collapsed into one call, and lifecycle methods take `io`:\n\n```zig\nvar child = try std.process.spawn(io, .{\n .argv = &.{ \"npm\", \"run\", \"build\" },\n .stdin = .ignore,\n .stdout = .inherit,\n .stderr = .inherit,\n});\nconst term = try child.wait(io); // child.kill(io) to stop it\n```\n\n(`src/tooling/verbs.zig`, `src/tooling/dev.zig` — the latter also shows passing a custom environment via `.environ_map`.) Inside a UiApp, spawn through the effects channel (`fx.spawn`) instead — it is bounded, journaled, and delivers exit/output as Msgs.\n\n## error: struct 'process' has no member named 'getEnvMap' / 'argsAlloc' — environment and args come from Init\n\n`std.process.getEnvMap`, `argsAlloc`, and `argsWithAllocator` are gone. `main` already has both: `init.environ_map` (a `*std.process.Environ.Map`) and `init.minimal.args.toSlice(allocator)` (`tools/native-sdk/main.zig`). Building an environment from scratch — for a child process, or in tests — is `var env = std.process.Environ.Map.init(allocator); defer env.deinit(); try env.put(\"KEY\", \"value\");` (`src/tooling/dev.zig`).\n\n## error: struct 'mem' has no member named 'trimRight' / 'trimLeft' — renamed `trimEnd` / `trimStart`\n\nThe directional trims renamed to match the JS/string convention; arguments are unchanged:\n\n```zig\nconst line = std.mem.trimEnd(u8, raw, \"\\r\\n\"); // was trimRight\nconst body = std.mem.trimStart(u8, line, \" \\t\"); // was trimLeft\nconst both = std.mem.trim(u8, text, \" \"); // unchanged\n```\n\n## error: struct 'std' has no member named 'net' — sockets live on `std.Io.net`\n\n`std.net.Address` became `std.Io.net.IpAddress`, and connect/listen take `io`: `std.Io.net.IpAddress.resolve(io, host, port)`, then `IpAddress.connect(&address, io, .{ .mode = .stream, .protocol = .tcp })`; stream readers/writers follow the buffered-writer shape (`std.Io.net.Stream.writer(stream, io, &buffer)` then `.interface`). Live reference: `src/tooling/dev.zig` (`waitUntilReady`/`httpReady`). App-level HTTP belongs in `fx.fetch`, not hand-rolled sockets.\n\n## error: no field named 'root_source_file' in struct 'Build.ExecutableOptions' — build.zig artifacts take modules\n\nZero-config apps have no `build.zig` — the CLI owns the build graph, so this only appears in apps that ejected or scaffolded `--full`. Artifacts take a module, and the module owns root source, target, and optimize:\n\n```zig\nconst exe = b.addExecutable(.{\n .name = \"app\",\n .root_module = b.createModule(.{\n .root_source_file = b.path(\"src/main.zig\"),\n .target = target,\n .optimize = optimize,\n }),\n});\nconst tests = b.addTest(.{ .root_module = app_mod });\n```\n\nThe generated ejected `build.zig` is the reference shape (`native eject`, emitted by `src/tooling/templates.zig`); the SDK's own `build.zig` uses the same pattern throughout.\n\n## Reading files and streams incrementally\n\n`file.reader()` with no arguments is gone. A reader takes `io` and a buffer, and the stream interface lives on `.interface`:\n\n```zig\nvar read_buffer: [4096]u8 = undefined;\nvar reader = file.reader(io, &read_buffer);\nconst bytes = try reader.interface.allocRemaining(allocator, .limited(1024 * 1024));\nconst line = try reader.interface.takeDelimiterExclusive('\\n');\n```\n\n(`src/tooling/manifest.zig` for allocRemaining, `src/tooling/toolchain.zig` for line reading from stdin.) For whole-file reads, prefer `readFileAlloc` above.\n\n## Tests: the Io is `std.testing.io`\n\nTests never construct an `Io` — `std.testing.io` is the canonical one, next to `std.testing.allocator`:\n\n```zig\ntest \"reads the manifest\" {\n var tmp = std.testing.tmpDir(.{});\n defer tmp.cleanup();\n try tmp.dir.writeFile(std.testing.io, .{ .sub_path = \"app.zon\", .data = source });\n const content = try tmp.dir.readFileAlloc(std.testing.io, \"app.zon\", std.testing.allocator, .limited(4096));\n defer std.testing.allocator.free(content);\n}\n```\n\n(`src/tooling/cef.zig` and `src/tooling/manifest.zig` tests.) Model/Msg/update tests need no `Io` at all — the markup-view testing pattern in the native-ui skill is pure.\n\n## Unchanged — do not \"migrate\" these\n\n`std.fmt.bufPrint` / `allocPrint` / `parseInt` / `parseFloat`, `std.mem.*`, `std.debug.print`, `std.heap.page_allocator`, `std.time.ns_per_*` and `ms_per_*` constants, `@embedFile`, `std.testing.expect*`, and managed `std.StringHashMap` / `std.AutoHashMap` all work as before. If code using only these fails, the problem is elsewhere.\n","skill-data/ts-core/SKILL.md":"---\nname: ts-core\ndescription: Authoring guide for the primary Native SDK app-logic path: TypeScript app cores - Model, Msg, update, and the pure functions they call, written in the closed app-core subset, checked by the @native-sdk/core frontend, and compiled ahead-of-time to native code by the external core compiler. Use for new apps unless the user explicitly chose Zig, when writing or modifying a src/core.ts app core, fixing subset checker errors (NS1001-NS1069), or deciding how to express state, messages, text (bytes and the byte-text string methods), text input, continuous controls (sliders, scroll), effects (Cmd), subscriptions (Sub), the host-event wiring channels (frameMsg, keyMsg, pinchMsg, dropMsg, appearanceMsg, chromeMsg, envMsgs, app manifest assets), derived values, the view_unbound lint opt-out, local mutation of owned arrays, or how to split a core into modules under src/ (relative imports, namespace imports, @native-sdk/core/text, @native-sdk/core/events). Use ts-services alongside this guide for src/services work.\n---\n\n# Author app cores in the TypeScript subset\n\nTypeScript is the primary app-authoring language. An app core is a Native SDK app's deterministic logic: `Model` (the app state), `Msg` (a discriminated union of everything that can happen), `update(model, msg)` (the one pure transition function), and the pure helpers they call. You write it as a TypeScript module rooted at `src/core.ts` - splitting into more modules under `src/` when it grows (see \"Splitting a core into modules\") - and the build checks the whole import graph with the `@native-sdk/core` frontend and compiles it to native code with the external core compiler. No JS engine ships in the binary — the program either passes the subset checker and compiles to native, or you get a teaching error naming the rule, the fix, and the reason. The same file is executable TypeScript: it typechecks with stock tsc and runs unmodified under node, so you can poke behavior with plain node scripts before the native build.\n\nA whole TS app starts as three files of truth and zero Zig: `src/core.ts` (this guide; plus core-class modules it imports under `src/`), `src/app.native` (the markup view over the core's model), and `app.json` (windows, identity, permissions). Existing `app.zon` manifests remain supported. Optional ordinary-TypeScript service modules live under `src/services/` and are never imported by the core; load `native skills get ts-services` for that boundary. `native init` scaffolds the three-file base; the build detects `src/core.ts` in the tree (never a flag or config — a tree with both `src/core.ts` and `src/main.zig` is a teaching error) and generates the wiring outside the app. The loop:\n\n```sh\nnative dev --core # the fastest loop: run the core under node's virtual host —\n # dispatch Msgs as JSON lines ({\"kind\":\"add\"}, {\"$bytes\":\"…\"}\n # for bytes payloads, {\"advance\":1000} to run virtual timers),\n # watch the model + effect transcript. Logic only, no renderer.\nnative dev # build and run the real app (markup hot reload)\nnative check # subset-check core.ts + validate markup + app.json/app.zon\nnative build # ReleaseFast binary; native test runs the app's tests\n```\n\nThe complete reference app in this idiom is `examples/soundboard` in the SDK repo: the soundboard music library as three files and zero Zig — const catalog tables, REAL audio through the `Cmd.audioPlay` stream, scrub-to-seek on a markup slider, a motion-gated `Sub.timer` playback clock, the full text-edit engine on a search field, controlled scroll, registered cover assets, the width-adaptive grid through the frame channel, clipboard, and context menus, with an end-to-end suite driving the shipping markup.\n\n## The contract\n\n```ts\nexport interface Model { /* readonly data fields only */ }\n\nexport type Msg =\n | { readonly kind: \"add\" }\n | { readonly kind: \"toggle\"; readonly id: number };\n // ...one arm per thing that can happen; at least two arms\n\nexport function initialModel(): Model { /* pure */ }\n\nexport function update(model: Model, msg: Msg): Model {\n switch (msg.kind) {\n // one case per arm; the switch must be exhaustive (no default needed\n // once every arm is present — a missing arm is a build error)\n }\n}\n```\n\n- `update` is pure and synchronous: next model out, plus optionally command data describing effects. When a dispatch needs an effect, declare the return type `Model | [Model, Cmd]` and return `[nextModel, cmd]` — the runtime interprets the command after the model commits and dispatches any result back to you as a `Msg`. `initialModel` may return the same pair (`[Model, Cmd]`) to run a boot effect once at install, and an app that needs recurring timers exports `subscriptions(model): Sub`. See \"Effects are Cmd data\" below.\n- Exported helper functions (`export function doneCount(model: Model): number`) compile to public native functions — and every exported helper taking exactly ONE Model parameter also becomes a Model declaration markup binds by the helper's own name (`{doneCount}`), so derived values need no model field. One binding name per member: a helper that collides with a field (or another helper) is a taught NS1031.\n- Update-only state (fields, helpers, or Msg kinds nothing in markup binds or dispatches — host-fired timer arms, persistence bookkeeping) is declared once: `export const viewUnbound = [\"nextId\", \"tick\"] as const;`. It emits as the `view_unbound` opt-out `native check`'s unbound-state lint reads; a name outside the model surface is a taught NS1032. Entries are the TypeScript names exactly as declared (`\"nextId\"`) and Msg kinds as their `kind` tags — the same names markup binds, because there are no other names.\n- Names: your names are your names — fields, helpers, and locals emit into Zig with their TS spellings (`doneToday` stays `doneToday`), and markup binds them verbatim. String-literal unions emit as native enums.\n\n## Tests against the compiled app\n\nPut Node test files directly in `tests/*.test.ts` and run `native test`. Import `NativeApp` and `findWidget` from `@native-sdk/core/testing` **only in tests**, never in `src/core.ts`. Each `NativeApp.start()` launches a separate headless native process with the real scriptc-compiled core and markup. Drive `click`/`action`/`menu`, assert returned model and accessibility snapshots, inspect and answer fake requests with `respond`, and fire declared timers with `fireTimer`. Supply explicit declared launch values with `NativeApp.start({ environment: [{ name: \"APP_MODE\", value: \"manual\" }] })`; they are journaled and replay does not read ambient environment. Framework app directories still use `appDataDirectory`. Always `close()` in `finally` or use `await using`. `verifyReplay()` verifies checkpoints and the final model in a fresh runtime; afterward only snapshot/close are allowed. Model bytes are JSON number arrays; native identities are decimal strings. The host uses a fixed clock and fake effects, without production persistence/services/app-data startup. See https://native-sdk.dev/docs/testing for the complete API and limits.\n\n## The arena mental model\n\nEverything `update` builds lives in a per-dispatch bump arena that is freed wholesale after the returned model is committed, so spreads, `map`, and `filter` are cheap by construction. At commit, only nodes your update actually created are copied into the persistent model heap — everything you spread through unchanged is shared with the previous model for free.\n\nThat is why the immutable style is not a performance tax: `{ ...model, tasks: model.tasks.map(...) }` copies one small struct and one pointer array, never the world.\n\nBoth regions are the compiled core's own: the frame arena bounds one dispatch's transients, the model heap holds the committed model between dispatches, and the compiler's determinism fences keep every dispatch allocation-shaped and replayable.\n\n## What the subset means\n\nThe subset is TypeScript minus the ecosystem minus the purity violations — never minus basic syntax. Concretely: every basic statement, operator, and declaration form of the language compiles (every loop shape including `do...while`, labels with labeled `break`/`continue`, `switch` with `default`, the full assignment-operator family, `**` and the shifts, const record destructuring, namespace imports over your own modules). What does not compile falls into exactly two families, each with a named teaching rule: the ECOSYSTEM the binary cannot carry (npm packages, Node/DOM APIs, regex/JSON/Promise/generator machinery, `eval` — no JS engine ships), and the constructs that would break a core's guarantees (purity and determinism, fixed shapes, one text representation, functions as declarations not values, static types with no runtime tags). Classes and exceptions are NOT in either family: data classes and `throw`/`try`/`catch`/`finally` compile (see below) — only their guarantee-breaking tails (inheritance, unsafe finally, untagged thrown values) teach. A construct that fails with a generic error instead of a teaching rule is a checker bug — the grammar matrix test (`grammar_matrix.test.ts`) pins every grammar production to its verdict so no silent gap can appear.\n\nThe banned families at a glance (each diagnostic names the fix and the reason at the site):\n\n- **No JS engine ships**: `eval`, `new Function`, dynamic `import()`, `debugger` (NS1013); regexes (NS1040); BigInt/Symbol (NS1044); generators (NS1042); async/Promises (NS1002); npm imports (NS1035).\n- **Purity and determinism**: mutation of SHARED data — parameters, model/msg trees, module tables, escaped locals (NS1001/NS1022/NS1051; your own function-local scratch arrays mutate freely, see \"Local mutation\" below), module-level `let` (NS1010), ambient time/randomness/IO (NS1005), effects outside the Cmd/Sub return paths (NS1017/NS1025).\n- **Fixed shapes and layouts**: the class machinery beyond data classes — `extends`/`super`/`abstract` (NS1055), accessors/`#`-privates/class expressions/`this`-as-a-value (NS1056/NS1006), mutable statics (NS1010), generic classes (NS1053) — plus `delete`/getters/setters/computed keys (NS1012), `for`/`in` (NS1009), Map/Set (NS1011), runtime type/shape tests — `typeof`/`in`/`instanceof`/`Object.*` (NS1041). Data classes themselves compile — `static` methods, `static readonly` consts, and erased `private`/`protected` included (see \"Data classes\" below).\n- **One text representation**: string indexing (NS1004), `+` concatenation and tagged templates (NS1018), `string` model fields (NS1024), the byte-text stays-out spellings — `charCodeAt`/`normalize`/`replace` and friends on bytes teach the byte-honest form (NS1060; the supported method surface is under \"Text is bytes\").\n- **Functions are declarations — or const local helpers**: nested function declarations, non-const function values, `?.()` (NS1046), and const helpers that capture/escape/under-annotate (NS1054 — the legal shape is below under \"Local function values\"); fixed arity — no defaults, rest, `arguments`, call spreads (NS1019); generics live on module-level declarations and monomorphize per call site (NS1050/NS1053).\n- **The mapping stays exact**: `var` hoisting (NS1049), loose `==` (NS1048), comma/void/assignment-as-value outside a for-header (NS1043), array/parameter destructuring (NS1045), `export default`/`export =`/`export * from` (NS1047 — export lists and named value re-exports compile), namespace-alias-as-value and SDK namespace imports (NS1039).\n\n## What compiles (v1)\n\nModel and message shapes:\n\n- `interface` with `readonly` fields; nested interfaces; `T | null` for optional data.\n- Model field types: `number`, `boolean`, string-literal unions (`\"all\" | \"active\" | \"done\"` → native enum), numeric-literal unions, `Uint8Array` (bytes), a nested interface, `readonly Interface[]` (arrays of object types), primitive arrays (`readonly number[]`, `readonly boolean[]`, arrays of literal-union tags), a tag-discriminated union (`{ kind: \"list\" } | { kind: \"detail\"; note: Note }` — arms may carry records, bytes, and primitive arrays), and `T | null` over any of these. Model unions compile to native tagged unions; switching arms in `update` retires the old arm's payload automatically at commit.\n- `Msg`: a discriminated union on a `readonly kind` string tag, with primitive / bytes / interface payload fields. It must be a real union — give it at least two arms, or TypeScript collapses the alias to a plain object type and the checker rejects it.\n\nLogic:\n\n- `switch` on any union's `kind` tag — `msg.kind` (the Msg dispatch) and model-field unions (`switch (model.view.kind)`) alike — with member case labels, label stacking (`case \"a\": case \"b\": body`), `break`, and a trailing `default` covering the unnamed arms (without a `default` the switch must be exhaustive — NS1015; with every arm named the `default` is JS dead code and emits nothing) — and `switch` on a string-literal-union or numeric-literal-union *value* (`switch (model.filter)`) — an uncovered member skips the switch exactly like JS (a `default` anywhere but last is a taught stop in both forms) — and `switch` on a plain `number` or `string` value, lowered to an if/else chain with exact JS semantics: strict equality per case (NaN matches nothing, `-0` matches `0`, strings compare contents), cases tested in source order, `default` matching only after every case misses wherever it sits (an empty `default:` stacking onto the next body included); `if`/`else`; classic `for (let i = 0; ...)` including countdowns (`i--`, `i -= k`), multi-counter inits (`let lo = 0, hi = n`), and comma incrementors (`lo++, hi--` — the for-header is the one home for comma sequences); `do { ... } while (cond)` (the body runs before the first test; `continue` jumps to the test, exactly node); `for (const x of xs)` over arrays and `Uint8Array`, with `break`/`continue`, plus the indexed pair form `for (const [i, x] of xs.entries())` (exactly the `[index, element]` two-identifier binding — the index is the loop index, integer-classed; other tuple shapes stay taught); `while`; labeled statements on loops and blocks with labeled `break`/`continue` (`outer: for (...) { ... continue outer; }` — a labeled `continue` in a classic for still runs the incrementor, like JS); `let` locals with reassignment (and `let x: number;` declared-then-assigned); ternaries; `&&`/`||`/`!`; the empty statement `;`.\n- `const { total, done: doneCount } = stats;` — record-field destructuring into const locals (a compile-time alias per field, renames included). Array patterns, parameter patterns, defaults, rest, and nesting are taught (NS1045 — positions can be silently absent in JS; fields cannot).\n- `import * as util from \"./util.ts\"` — a namespace import over your own modules is pure dot-syntax: `util.helper(x)`, `util.CONST`, and `util.Cfg` in type positions all resolve to the target module's flat names. The alias is not a value (storing or passing `util` itself is taught), and the intrinsic `@native-sdk/core` module is always imported by name (NS1039 — the purity rules recognize `Cmd`/`Sub`/`asciiBytes`/`utf8Bytes` by their imported names).\n- Object spread `{ ...model, field: v }`, array spreads in any shape — append `[...xs, x]`, prepend `[x, ...xs]`, multi-spread `[...a, x, ...b]` (each compiles to one exact-size copy) — `.length`, indexing `xs[i]`.\n- Array methods, lowered to inlined loops and exact-size arena copies: `.map` / `.filter` / `.find` / `.findIndex` / `.some` / `.every` / `.reduce` / `.toSorted` / `.slice` / `.concat` / `.indexOf` / `.includes`. `.map` is type-changing — `tasks.map((t) => t.id)` produces a number array, `t => t.title` a bytes array, and a callback that can return `null` produces an optional-element array. Callbacks on map/filter/find/findIndex/some/every may take the `(element, index)` pair — the index is the loop index, integer-classed (`.reduce` stays `(acc, x)`: its index parameter is not in v1, and no callback takes the third JS parameter, the array itself — reference the array by name). Array-method calls may sit directly in `if`/`else if` and ternary conditions (`if (xs.some((x) => x > 3))`) — the scan lowers to a loop just before the branch; a `while` condition cannot (it re-evaluates per iteration — hoist into the loop body or restructure). Callbacks are arrows (expression or block body), inline `function` expressions, or a BARE REFERENCE to a module-level function or const helper (`xs.map(encodeTurn)`, `xs.toSorted(byAscending)` — the referenced body inlines exactly like the arrow spelled at the site); in a block body every code path must end in an explicit `return` (falling off the end would be JS `undefined`, which has no mapping — a taught stop). JS semantics hold exactly: `.slice` resolves negative and out-of-range indices the JS way, `.indexOf` never matches `NaN` while `.includes` does, `.some`/`.every` keep their vacuous defaults on empty arrays, and `.reduce` needs its initial value (the no-initial form throws on an empty array in JS, so it is a taught NS1007 — pass the starting accumulator). `.indexOf`/`.includes` work on scalar elements (numbers, tags, booleans); on record arrays JS compares references, which has no native mapping — match a field with `.find`/`.findIndex` instead.\n- **Local mutation — your own scratch is yours; shared data is immutable.** An array your function CREATES — an array literal (`const stack: number[] = []`, `const st = [1, 2, 3]`) or a fresh copy (`.slice()` / `.map()` / `.filter()` / `.concat()` / `.toSorted()`) — is locally owned, and the full mutating method set works on it with exact JS semantics: `push(...items)`, `pop()`, `shift()`, `unshift(...items)`, `splice(start, deleteCount?, ...items)` (negative/overshooting indices clamp the JS way; the value is the removed array, also yours), `reverse()`, `fill(v, start?, end?)`, in-place `sort(cmp)`, and indexed writes `xs[i] = v`. A parser stack, a work queue, a copy-then-sort — all legal, deterministic, and byte-identical to node. Ownership ends at the first ESCAPE: once the array is returned from a callback, stored into a record/array/model, aliased by a second binding (`const b = a`), or passed where the callee could keep or mutate it, mutating it afterwards is a taught NS1051 — finish mutating first, then let it escape (an early-exit `return` is fine: execution ends there, so mutations on the other path stay legal). Two loosenings keep real code flowing. BORROWING: passing an owned array into a `readonly T[]` parameter is NOT an escape when the callee only READS it (element/property access, iteration, spreads, further borrowing passes — no return of it, no store, no onward pass into a mutable position; recursion over borrowed slices included), so measure-mutate-measure loops work (`total(out); out.push(x); total(out)`). REASSIGNED-OWNING: a `let` binding whose EVERY assignment installs a fresh owning construction (a literal or a copy — `w = xs.filter(...)`, `acc = []`) stays owned through the reassignments; ONE mixed assignment (an alias, a parameter, a helper result) and the binding never owns (NS1001 names it). Never owned: parameters, model/msg data, module `const` tables, aliases, mixed reassigned bindings, and arrays produced by helper calls (copy with `.slice()` to own one). After the value escapes it is an ordinary immutable value; the commit walkers and sharing discipline are unaffected because ownership ended before the escape.\n- Local-mutation shape notes: `push`/`unshift` return the new length in JS, which has no mapping — mutate as a statement and read `.length` after; `sort`/`reverse`/`fill` return the same array — mutate as a statement, then use the array by name (`return copy.sort(cmp)` is a taught stop; the canonical form is `const copy = xs.slice(); copy.sort(cmp); return copy;`); `pop()`/`shift()` return `T | undefined` — the same one-empty the `.find` miss produces, so test `=== undefined` or fold with `??` (`stack.pop() ?? fallback`); spread arguments (`out.push(...xs)`) stay taught — one element per iteration; `xs[xs.length] = v` on an owned array IS a push (the one growth shape — compound forms like `xs[xs.length] += v` read the missing slot first and stay taught), and other out-of-bounds writes are JS sparse arrays with no mapping (they trap on the native bounds check in safe builds — keep writes inside `0..length-1`); changing the LENGTH of the array a `for...of` (or one of its own callbacks) is iterating is a taught stop (JS walks the live array; fixed-length writes during iteration are fine and identical to node); `copyWithin` stays out of v1 (splice/fill cover it).\n- `.toSorted(cmp)` sorts a copy in one expression; `.sort(cmp)` sorts in place on an array you own (on shared data it keeps the NS1022 teaching, which names the copy idiom). Both comparators follow the same rules: return a sign — `(a, b) => a - b` for ascending numbers, or explicit -1/0/1 branches; a boolean comparator is wrong in JS itself (false claims equality) and is rejected by the types plus a taught NS1023. The comparator-less arity sorts by string ToString order in JS (`[10, 9]` stays `[10, 9]`), which has no float-text mapping — pass a comparator. Both sorts are stable exactly like JS: comparator 0 (or NaN) keeps the original order of the pair. One honesty note: a comparator that is inconsistent over the actual data (e.g. `a - b` when elements can be `NaN`) is implementation-defined in JS itself, so node and native may then disagree — keep comparators consistent.\n- A `.find` miss is the core's one empty value: JS spells it `undefined`, so test the result with `=== undefined` (never `=== null` — the checker teaches the difference) or fold it away with `??`: `tasks.find((t) => t.id === id) ?? fallback`.\n- Optional chaining `?.` on property chains (`model.sel?.at ?? 0`), element hops (`m?.xs[0] ?? 0`, `xs?.[i] ?? d`), and method hops on supported receivers (`xs?.slice(0, 2)`, `xs?.includes(3) ?? false` — every mapped array/bytes method): each hop null-propagates exactly like JS, and the chain value is optional — end it in `??` or compare it against a real value. A `?.` chain compared against `null`/`undefined` is a taught error (NS1021), and `g?.()` on a function value stays taught.\n- Null-guard narrowing through `&&`/`||` chains, exactly the way TS narrows: `if (x !== null && x.items.length > 0)`, the flipped order (`null !== x`), the `||` dual (`x === null || x.items.length === 0`, including as an early-exit guard — the code after the exit stays narrowed), ternary conditions (`x !== null && x.at > 0 ? x.at : -1`), and `while (cur !== null && cur.n > 0)` loops (re-tested per iteration; assigning the guarded local drops the narrowing for what follows, like TS). Relational comparisons on guarded optionals (`cls !== null && cls < lim`) work too.\n- Nullish `??`, comparisons (including `===` on `string`-typed values — content equality, same as node; `==`/`!=` are taught NS1048 — coercion), `+ - * / % **` on numbers, unary `+`/`-`, and the bitwise family `& | ^ ~ << >> >>>` — all with JS number semantics (`/` is float division, `%` truncates, `**` is float pow with the exact JS corners — `1 ** NaN` is NaN, `(-1) ** Infinity` is NaN, right-associative `2 ** 3 ** 2` is 512; bitwise and shifts are ToInt32 with the shift count masked & 31, `>>>` yielding the unsigned 32-bit value; unary `+` is the identity on numbers). `**` and `/` results are float-classed; bitwise/shift operands are integer-required positions (a float operand is a taught NS1016).\n- Every compound assignment as a statement: `+= -= *= /= %= **= &= |= ^= <<= >>= >>>=`, each exactly `x = x op v`, plus the guarded forms `&&=`/`||=` (boolean targets; the right side evaluates only when assigned, like JS) and `??=` (optional targets; assigns only when null). A number `++`/`--`/assignment may sit in a VALUE position when the split statement is provably order-exact — the variable's only mention in the statement, in a position JS cannot skip (`arr[i++]`, `const n = ++count`, `const z = (y = 5)`; postfix yields the pre-step value, everything else the post-step value, exactly JS); every other value-position form is taught (NS1043 — ternary branches, short-circuit right operands, loop conditions, or a second mention of the variable).\n- The Math batch, every corner pinned to node: `Math.min` / `Math.max` (any arity — `Math.min()` is Infinity, `Math.max()` is -Infinity, NaN propagates, -0 orders below +0), `Math.round` (half toward +Infinity), `Math.floor` / `Math.ceil` / `Math.trunc` (NaN/Infinity propagate; the -0 results keep their sign, so `Math.ceil(-0.5)` is -0), `Math.abs` (clears the zero sign), `Math.sign` (NaN stays NaN, a zero keeps its sign), `Math.sqrt` (negative input is NaN, `sqrt(-0)` is -0). `Number.isInteger` / `Number.isFinite` / `Number.isNaN` classify like node, and the `NaN` / `Infinity` globals are ordinary number values. Math calls over compile-time constants fold to their exact JS value — `const HALF = Math.floor(5 / 2)` is the integer 2, `5 % 0` is NaN, `-5 % 5` is -0. A bare `-0` literal (and constant arithmetic folding to -0, like `0 * -1`) is a float value — only f64 carries the signed zero — so it cannot flow into an index or another integer-required slot. The integer rule: floor/ceil/trunc/abs/sign of an integer-classed value stays integer-classed, but of a float value stays float (floor of NaN is NaN), so `bytes[Math.floor(x / 2)]` over a float `x` is still a taught NS1016 — keep index flows integer end to end.\n- Template literals with integer holes (`` `${n} of ${total}` ``) feeding `utf8Bytes` or `asciiBytes` (below). Float-valued holes are not in v1 (JS float-to-string fidelity is a runtime v2 surface).\n- Module-level `const` numbers and strings fold to comptime constants, and const tables emit as rodata (no arena, shared for free at commit): arrays of numbers / booleans / strings / literal-union members (`const WEEKDAYS = [3, 5, 2]`, `const ORDER: readonly Filter[] = [\"done\", \"all\"]`), records annotated with an interface (`const LIMITS: Limits = { lo: 1, hi: 9 }`), and arrays of records (`const SEEDS: readonly Task[] = [...]`, names as `utf8Bytes` literals). Element access, `.length`, `for...of`, and the array methods all work over tables. Everything inside must fold at compile time — no spreads, no calls except `asciiBytes` or `utf8Bytes` on a literal — and a record table needs its interface annotation (an unannotated `{ ... }` is a taught stop naming the fix). Helper functions; recursion.\n- **Generics — module-level, monomorphized per call site.** A generic `function`, `interface`, or `type` declares type parameters and instantiates from tsc's RESOLVED type arguments (explicit or inferred): `export function pick(xs: readonly T[], i: number): T { return xs[i]; }` called with tasks emits `pick__Task`, with numbers `pick__f64` (a bare `number` type argument is always f64 — the JS-exact class), one readable Zig fn per distinct instantiation, deduped. Generics over records, unions, arrays, optionals, and bytes all work; generic interfaces/aliases instantiate structurally (`Box` emits `Box__Task`; `type Opt = T | null` resolves straight through); generics may recurse and call other generics (the inner call resolves at the outer's instantiation). `typeof CONST` type-query aliases resolve through tsc too (`const LIMIT = 9; type Limit = typeof LIMIT`). The boundaries teach: a call site whose type argument stays abstract (`pick([])` infers `never`; `any`/`unknown`, unnamed literal unions) is NS1053 — annotate the call or name the alias; generic function VALUES and generic entry points are NS1050.\n- **Data classes — fields, one constructor, plain methods, statics; no inheritance.** `class Task { title: Uint8Array; done: boolean = false; constructor(title: Uint8Array) { this.title = title; } toggle(): void { this.done = !this.done; } isDone(): boolean { return this.done; } }` emits as a plain struct plus module-level functions; `new Task(...)` constructs a record-shaped value (field initializers run in declaration order, then the constructor body). `static` members are per-class module declarations: a `static` method lowers to a receiver-less module fn under the class's mangled name (`Task.fromRow(...)` resolves to `Task__fromRow`), and a `static readonly` field with an initializer is a module const (`Task.LIMIT` — the module-const value rules apply: numbers/strings fold, tables need their annotation); a MUTABLE static is module state and teaches NS1010, and inside a static member reach other statics by the class name, never `this` (NS1056). `private`/`protected` keywords are accepted and ERASED — tsc enforces them at the type level, which is their whole meaning (`#`-fields stay taught: runtime privacy brands). `this` reaches instance fields and methods (`this.count`, `this.step()`) — anything that lets `this` escape as a value (returning it, storing it, passing it) is taught (NS1056), so fluent chaining is out. Mutation follows exactly the array ownership rule: an instance your function creates with `new` mutates freely — direct field writes (`t.count = 1`, `t.count += 2`) and methods that write `this` — until it ESCAPES (returned, passed, stored, aliased — then NS1051), and parameters/model data never mutate (NS1001); methods that only read are callable on anything. Fields require type annotations; instances flow between functions, sit in arrays, and compare/narrow like records. The class TAIL teaches by name: `extends`/`super`/`abstract` (NS1055 — compose, or model variants as a `kind`-union), getters/setters/`#`-privates/`accessor`/class expressions (NS1056), mutable statics (NS1010), generic classes (NS1053), parameter properties (NS1008), `instanceof` (NS1041 — a `kind` field is the tag that exists). Class instances stay LOCAL values in v1: storing one in the Model tree is taught (NS1056) — keep records (interfaces) in the Model and construct the class where behavior is needed.\n- **Exceptions — `throw`/`try`/`catch`/`finally` as pure control flow.** Inside a core, exceptions are deterministic: `throw` carries a subset VALUE and unwinds to the nearest enclosing `catch` — across helper calls, out of array-method callbacks (a `throw` inside `.map`'s callback exits the whole loop, like JS), through nested `try`s, with `finally` running on every path (fall-through, `return`, `break`/`continue`, and throw alike). The discipline is two rules. First (NS1057): thrown values are kind-tagged subset shapes — throw kind-discriminated records (`throw { kind: \"bad_digit\", at: i } as ParseError`, where `ParseError` is an interface with a string-literal `kind` field or a `kind`-discriminated union; a single-shape core may also throw a number), and SEVERAL distinct shapes may throw: the checker collects every shape the core throws into its implicit thrown union. The catch binding IS that union — narrow it in place with kind tests, no `as` ceremony: `catch (e) { if (e.kind === \"bad_digit\") return -e.at; if (e.kind === \"io\") return e.code; return -1; }` (or `switch (e.kind)` — tsc cannot prove exhaustiveness over the implicit union, so give the switch a `default` or a trailing return). Bare rethrow (`throw e;`) re-raises the bound value — a narrowed arm included — and `catch { ... }` needs no binding; the single-`as` form (`const err = e as ParseError;`) stays legal in single-shape cores (and for a DECLARED union whose arms equal the thrown set — declare `type AppError = ... | ...` and `as AppError` works). What teaches: untagged values in a heterogeneous set, two shapes sharing one `kind` with different payloads, asserting one member shape of a multi-shape core, the binding escaping untyped into a call/store/return, and `throw new Error(...)` (engine error objects carry stack traces with no native layout). Second (NS1058): `finally` never redirects control flow — no `return`/`throw`/`break`-out inside it (JS's own no-unsafe-finally rule; loops fully inside the finally may break within themselves). An UNCAUGHT throw that reaches an exported function's boundary is a defined deterministic panic — exactly where node's process would crash. A throw mid-mutation of an owned array keeps the mutations applied so far, exactly like JS — the catch sees the array as node would.\n- **Local function values — const helpers hoist.** `const scale = (x: number): number => x * 3;` (arrow or `function` expression) hoists to an ordinary module-level fn when it is capture-free (module constants and other const helpers are fine to reference; enclosing locals/params are not — pass them as parameters), fully annotated (every parameter and the return type), and used only by direct calls (`scale(v)`, recursion included) or as an array-method callback (`xs.map(scale)`, comparators included). Everything else teaches NS1054: captures, missing annotations, `let` bindings, returning/storing the value, passing it to your own functions, calling through a record field. Capturing a locally-owned array also ENDS its ownership at the capture (a later mutation is the NS1051 teach) — the stored closure would retain the reference.\n\nNot yet in v1 — genuine roadmap deferrals, each stopping with a loud, tailored NS9001 naming the rewrite (never missing basic syntax; the banned-with-a-rule families live in \"What the subset means\" above). The rule-level deferrals carry `class: \"deferred\"` in the diagnostics catalogue — NS1011 (Map/Set), NS1019 (fixed arity), NS1040 (regexes), NS1042 (generators), NS1044 (BigInt/Symbol) — and their diagnostics say the capability is deliberately deferred, not impossible; the list below is the method-level remainder: `.toSorted()`/`.sort()` without a comparator (JS ToString ordering; pass `(a, b) => a - b`), `.reduce` without an initial value (a taught NS1007 — JS throws on an empty array) or with an index parameter (use a classic loop), `.indexOf`/`.includes` on record arrays (match a field with `.find`/`.findIndex`), `.join` on number arrays (elements are float-valued; join byte values instead), float values (`/`, `**`, `Math.round`, `Math.sqrt`, float `Math.floor`-family results) where an integer is required such as an index (a taught NS1016 — those values can be fractional or NaN), Math methods beyond the batch above, `Number` methods beyond the three classifiers, float-valued template holes (JS float-to-string fidelity is a runtime v2 surface), arrays of unions (`readonly View[]`) or arrays of byte-strings (`readonly Uint8Array[]`) as model fields (wrap the element in a single-field interface), a collect spawn's stderr tail (v1 delivers the exit code and stdout; stderr is not surfaced — put diagnostics on stdout or check the code), per-line truncation flags (a stdout or response line over its configured bound arrives cut, without a flag), and non-timer subscriptions (`Sub.timer` is the one subscription; one-shot needs are `Cmd.delay`, and process/fetch/audio streams are Cmd-initiated, not subscribed).\n\n## Effects are Cmd data\n\n`update` never performs an effect — it can return one, as inert data, alongside the next model. Import the factories from the SDK and declare the pair-return type:\n\n```ts\nimport { Cmd } from \"@native-sdk/core\";\n\nexport function update(model: Model, msg: Msg): Model | [Model, Cmd] {\n switch (msg.kind) {\n case \"add\":\n return [{ ...model, count: model.count + 1 }, Cmd.persist()];\n case \"request_time\":\n return [model, Cmd.now(\"tick\")]; // dispatches { kind: \"tick\", at: }\n case \"tick\":\n return { ...model, lastTick: msg.at }; // bare model = [model, Cmd.none]\n case \"ship\":\n return [model, Cmd.batch([Cmd.persist(), Cmd.host(\"beep\", model.count)])];\n }\n}\n```\n\nThe command set (Cmd wire format v7):\n\n- `Cmd.none` — no effects; returning a bare `Model` is sugar for `[model, Cmd.none]`.\n- `Cmd.persist()` — snapshot the just-committed Model through the engine-owned store. Requires `\"persist\"` in `app.zon` capabilities plus `.persist = .{ .version, .restore = .{ .ok, .none, .err } }`; the host owns canonical encoding, debounce/coalescing, atomic app-data placement, backup recovery, and replay.\n- `Cmd.now(\"tick\")` — request a timestamp; the runtime dispatches the named Msg arm with the time (ms) as its payload. The target arm must carry exactly one number field (`{ kind: \"tick\", at: number }`), and tsc checks that for you.\n- `Cmd.host(name, ...args)` — a fire-and-forget host command by literal name; the host decides what the name means. Args are numbers, OR exactly one bytes payload: a `Uint8Array` (`Cmd.host(\"clipboard.write\", model.draft)`) or a flat inline record of number/boolean/`Uint8Array` fields (`Cmd.host(\"cfg.save\", { gain: model.gain, on: model.muted, label: asciiBytes(\"main\") })`) — the record lowers to one bytes payload from your types at build time, byte-identical under node and native. Anything else (a smuggled string, a nested record, a payload plus extra args) is a taught error (NS1020/NS1026).\n- `Cmd.request(name, payload, { key?, ok, err })` — a routed host command: the host performs `name` with the payload (same bytes/record rules) and dispatches exactly one result back to you as an ordinary Msg — the `ok` arm with the result bytes on success, or the `err` arm with the error bytes on failure. Both arms must carry exactly one `Uint8Array` field (`{ kind: \"loaded\", body: Uint8Array }`), checked by tsc and taught by NS1027. The routing is data — string-literal arm names, never callbacks — so the result decoder derives from your Msg types at build time. The optional `key` (a string literal) names the in-flight effect: issuing a request whose key is already in flight replaces it (the old result is dropped), which is the debounce/exactly-one-in-flight discipline.\n- Typed app services are the deliberate record-valued arm of this family: declare shared data shapes outside `src/services/`, import generated constructors from `@native-sdk/services`, and let those constructors encode requests and prove the typed success Msg arm. See `native skills get ts-services`. Raw `Cmd.request` remains bytes-oriented.\n- `Cmd.cancel(key)` — drop the in-flight keyed effect with that key, silently: a cancelled raw request, buffered named engine op (`readFile`/`writeFile`/`fetch`/`clipboardRead`), streamed file read, or armed delay dispatches NEITHER arm. Live spawn, streaming-fetch, streaming-service, and streamed write sinks are the exceptions: cancel ends them through `err: cancelled`; a half-written sink is observable and must never disappear silently.\n- `Cmd.batch([a, b])` — several commands from one dispatch, performed in order.\n\n### The named engine ops\n\nThese map directly onto the host's effect engine — files, HTTP, the clipboard, notifications, one-shot timers. Routed operations follow the `Cmd.request` rules (inline `{ key?, ok, err }`, string-literal arm names, arm shapes checked by tsc and taught by NS1027), with one difference from `request`: each op's `ok` arm has the op's OWN result shape. Keys follow the one keyed-effect rule everywhere: issuing a keyed op whose key is already in flight REPLACES the old one (the superseded op's result is dropped — no message), and `Cmd.cancel(key)` drops it silently. Every `err` arm carries exactly one `Uint8Array` field and receives a machine-readable reason; fire-and-forget writes and notifications have no routing arms. Paths, URLs, and bodies are bytes (`asciiBytes` for literals); dynamic values the engine refuses at runtime surface through the `err` arm, while compile-time-knowable bounds for routed operations stop the build (NS1030). Fire-and-forget operations fail closed under the host's validation instead.\n\n- `Cmd.store.set(key, bytes, { key?, ok, err })` / `get` / `delete` / `scan` / `setMany` — capability-gated, engine-owned per-record storage. Declare `\"store\"` in `app.zon`; keys are UTF-8 strings up to 512 bytes and values are bytes up to 1 MiB. `setMany` applies 1–64 entries atomically. `get`'s ok bytes are `[1][value...]` for a hit and `[0]` for a miss, keeping an empty value distinct from absence. `scan(prefix, { limit?, after? }, route)` returns a little-endian length-prefixed page of key/value pairs plus an opaque next-key cursor; pass those next-key bytes back as `after` (a known literal cursor may be a string). The limit defaults to 100 and is capped at 256. Writes run off-loop in issue order, a synchronous read waits for earlier writes in the same command walk, every result journals, and failures route one of `io_failed`, `over_bound`, `bad_key`, `rejected`, or `busy`. The SQLite backing and app-data path are never part of the app-facing API.\n- **Checked relational SQLite:** declare `\"sqlite\"` in `app.zon`. Add append-only, contiguous `src/schema/NNNN_name.sql` migrations (`STRICT` ordinary tables), commit the generated `src/schema/migrations.lock.json`, and add named statements in `src/queries.sql`: `-- name: notesInFolder`, `-- name: moveNote :exec`, or `-- name: notesInFolder :live`. `native check` applies the migrations and prepares every query with real SQLite, then generates flat `Cmd.q(params, route)` query constructors, typed `Cmd.q(params)` exec members composed only through `Cmd.qTx([...], route)`, `Sub.q(key, params, route)` for `:live`, row/param interfaces, and `decodePage`. TEXT/BLOB rows are `Uint8Array`; parameters inferred from TEXT columns wrap bytes automatically; raw or uninferred dynamic TEXT (for example an FTS `MATCH` term) uses `dbText(bytes)`. INTEGER is an exact `number` and generated decoders reject values outside ±(2^53−1). Live queries rerun after committed writes to their generated table dependency set, coalesced once per command frame. `native db new-migration `, `status`, and `reset --yes` own development migration operations. Do not edit or reuse a shipped migration number.\n- `Cmd.db.query(sql, params, { key?, page, done, err })` / `Cmd.db.exec(statements, { key?, ok, err })` — the permanent raw SQLite escape hatch. The engine owns `app.db`; parameters are `null | number | string | Uint8Array | dbText(bytes) | boolean`. A read delivers 256-row/256-KiB pages then `done`, with one result capped at 8,192 rows or 8 MiB; crossing either total bound rejects the whole result, so use `LIMIT` and keyset pagination for larger collections. An exec commits its 1–64 statements as ONE transaction. SQL remains pathless: `ATTACH`/`DETACH`/`VACUUM INTO`, TEMP schema objects, and engine lifecycle PRAGMAs are denied. Query keys replace/cancel silently; duplicate transaction keys reject loudly. Error bytes are `constraint`, `busy`, `io_failed`, `corrupt`, `misuse`, `rejected`, or `cancelled`. Every page/terminal journals and replay never opens SQLite. Prefer declared queries; NS1420 nudges raw query literals toward them.\n- `Cmd.readFile(path, { key?, ok, err })` — read a whole file. `ok` arm: one `Uint8Array` field with the content. `err` reasons: `not_found`, `io_failed`, `truncated` (the file exceeds the engine's 1 MiB read bound — a cut file never passes as whole), `rejected`. Paths are at most 1024 bytes.\n- `Cmd.writeFile(path, bytes, { key?, ok, err })` — write a whole file (parent directories created, an existing file replaced whole; at most 1 MiB). `ok` arm: NO payload fields (`{ kind: \"wrote\" }`) — a successful write has nothing to report. `err` reasons: `io_failed`, `rejected`.\n- `Cmd.appendFile(path, bytes, route)` appends one bounded payload; `Cmd.statFile(path, route)` returns `{ exists, size, mtimeMs }`; `Cmd.deleteFile(path, route)` deletes one file with a payload-less `ok` arm and routes a missing path as `not_found` (a final symlink is unlinked without deleting its target). `Cmd.readFileStream(path, { key?, chunk, done, err })` delivers 256-KiB chunks then the total; reissuing or cancelling its key silently replaces/drops the read. Atomic exports open with `Cmd.writeFileStream(key, path, route)`, send one acknowledged `writeFileChunk` (≤1 MiB) at a time, then `writeFileClose`; a duplicate sink rejects, overlapping chunk/close routes `out_of_order`, and sink cancellation is loud. Stream chunks spill to the session blob store for byte-identical replay. Raw paths under this app's resolved data/config/cache/state/logs/temp roots need no grant; every external path requires the `filesystem` permission. The runtime resolves existing parents and symlinks before checking (an in-root symlink pointing out is external); NS1074 catches certainly-external literals.\n- `Cmd.fetch({ url, method?, headers?, body?, timeoutMs? }, { key?, ok, err })` — a buffered HTTP(S) exchange. `ok` arm: exactly two fields, one `number` and one `Uint8Array` (`{ kind: \"fetched\", status: number, body: Uint8Array }`) — matched by type, so the names are yours. The status is the real HTTP status: a 404 is still `ok` (an HTTP-level error is a delivered response). `err` reasons: `connect_failed`, `tls_failed`, `protocol_failed`, `timed_out`, `rejected`, and `truncated` (the body exceeded the engine's 256 KiB buffered bound — never delivered silently cut). The spec is an inline object: `url` bytes (≤ 2 KiB), `method` one of `\"GET\" | \"POST\" | \"PUT\" | \"DELETE\" | \"PATCH\" | \"HEAD\"` (default GET), `headers` an inline flat record — names are compile-time ASCII, values are string literals OR runtime bytes (`{ authorization: bearerToken(model.apiKey), \"content-type\": \"application/json\" }` — how a launch-supplied key rides an `Authorization` header; ≤ 8 headers, ≤ 1 KiB total, NS1029/NS1030), `body` bytes (≤ 64 KiB), `timeoutMs` a positive integer literal (engine default when omitted).\n- `Cmd.clipboardWrite(bytes)` — put bytes on the system clipboard, fire-and-forget: there is no routing, and a refused or over-bound write is dropped by design.\n- `Cmd.clipboardRead({ key?, ok, err })` — read the clipboard. `ok` arm: one `Uint8Array` field with the text. `err` reasons: `failed` (no clipboard service, over-bound content, pasteboard error), `rejected`.\n- `Cmd.showNotification({ id?, title, subtitle?, body?, actionLabel?, actionCommand? })` — request a desktop notification, fire-and-forget: `title` is required bytes (1–128), `subtitle`, `id`, `actionLabel`, and `actionCommand` are optional bytes (up to 128), and `body` is optional bytes (up to 1024). A nonempty `id` replaces the app's earlier notification with that id where the OS supports replacement. `actionLabel` and `actionCommand` must be supplied together; activation dispatches `actionCommand` through the ordinary app-command path while the process is running. The host validates every field and command name before entering the platform service; invalid or unavailable requests fail closed, and Focus / Do Not Disturb and user settings remain authoritative after acceptance. Fake execution and session replay never display one, while the null test platform can activate a recorded notification deterministically.\n- `Cmd.openExternalUrl(url)` — open an HTTP(S) URL in the system browser, fire-and-forget. `url` is bytes; the runtime validates it and enforces `security.navigation.external_links` before entering the platform service. Invalid, denied, or unavailable requests fail closed; fake execution and replay never open one.\n- `Cmd.revealPath(path)` — reveal a byte path in Finder, Files, or Explorer, fire-and-forget. Runtime path validation stays in force; invalid or unavailable requests fail closed, and fake execution/replay never reveal one.\n- `Cmd.credentials.set(key, secret, { key?, ok, err })` / `Cmd.credentials.get(key, route)` / `Cmd.credentials.delete(key, route)` — app-scoped Keychain on macOS/iOS, Secret Service/libsecret on Linux, Credential Manager on Windows, and AndroidKeyStore-wrapped authenticated ciphertext on Android. The authored credential key is a NUL-free string (UTF-8, ≤256 bytes); the manifest app id (≤128 bytes) supplies the service namespace, and secrets are `Uint8Array` values through 2,560 bytes (the cross-platform floor set by WinCred). Set/delete deliver empty bytes on `ok`; get delivers secret bytes; the closed err reasons are `miss`, `denied`, `locked`, `io_failed`, `over_bound`, and `rejected`. Declare BOTH `\"credentials\"` in `app.zon` capabilities and permissions; NS1071 warns when the capability is absent, NS1072 errors when permission is absent, and NS1073 reserves `core.credentials.*` for the typed factories. Never retain a returned secret in Model: consume its Msg immediately to construct the next effect. Recording stores only a successful get's length, per-session salt, and a placeholder digest independent of the secret (never the secret or a blob); replay delivers deterministic same-length placeholder bytes, and devhost keeps an in-memory map while printing only ``.\n- `Cmd.formatLocalTime(timestampMs, \"date\" | \"time\" | \"datetime\", { key?, ok, err })` — format epoch milliseconds (the same unit `Cmd.now` produces) through the host's current locale and local time zone; `ok` carries localized UTF-8 bytes. This is deliberately an effect rather than a pure helper: locale/timezone are ambient state, so the observed bytes journal and replay without consulting the replay machine. Err reasons are `invalid_request`, `unsupported`, and `failed`.\n- `Cmd.delay(key, ms, \"fired\")` — a keyed ONE-SHOT timer: dispatches the named arm once, `ms` from now, with the fire time (ms) as its single number payload (the same arm shape `Cmd.now` and `Sub.timer` target). Re-issuing a live delay key re-arms it from now — that is the debounce discipline (`Cmd.delay(\"autosave\", 800, \"save_now\")` on every keystroke, one fire after the pause). `Cmd.cancel(key)` drops it silently. The interval is 1ms to one year; a literal outside that stops the build (NS1030).\n\nModel persistence is capability-gated. Without `\"persist\"`, NS1028 warns that `Cmd.persist()` has no linked host binding; declaring the capability without issuing the command produces the inverse warning. C","skill-data/native-ui/SKILL.md":"---\nname: native-ui\ndescription: Authoring guide for the Native markup (.native) view tier of native-rendered Native SDK apps. TypeScript cores are the default and use this skill together with ts-core; Zig cores are an explicit alternative and this guide labels their lower-level UiApp recipes. Use when building or modifying native UI (widgets, layout, bindings, messages), writing .native files, wiring views to Model/Msg/update, testing markup views, or verifying a native app through the automation harness.\n---\n\n# Author native UI with Native markup\n\nA native-rendered Native SDK app is a markup view plus an app core. The primary authoring path is:\n\n- `src/app.native` — the entire UI: elements, layout, bindings, message dispatch.\n- `src/core.ts` — `Model`, the discriminated `Msg` union, `update(model, msg)`, effects, subscriptions, and derived binding helpers.\n- `app.zon` — identity, windows, assets, permissions, and policy.\n\nThe TypeScript core is checked and compiled ahead of time to native code; no JS runtime ships in the binary. Load `native skills get ts-core` beside this skill for every default app implementation. A Zig core (`src/main.zig`) is first-class when explicitly selected with `native init --template zig-core`; the Zig-only wiring, builder, and runtime-extension recipes below are labeled so they are not mistaken for the default.\n\nThe markup compiles to the same widget tree a hand-written `canvas.Ui(Msg)` builder view would produce: identical structural widget ids, identical typed handler table. Markup can never mutate state — it binds values and dispatches messages; all logic lives in the app core, whichever core language the existing tree uses.\n\nEditors highlight `.native` markup well in HTML mode — the default scaffold writes no editor config, so add `.vscode/settings.json` with `\"files.associations\": {\"*.native\": \"html\"}` yourself, or scaffold with `native init --full`, which writes it.\n\nStart a new app with `native init` (zero-config: `app.zon` + `src/core.ts` + `src/app.native` + assets; the CLI generates the build graph). Use `examples/chatbot`, `examples/soundboard`, and `examples/system-monitor` as substantial TypeScript references. The `native check|dev|test|build` verbs drive any app directory shaped this way.\n\n## Menu-bar status items (TypeScript default)\n\nExport `statusItem(model: Model): StatusItemState` from `src/core.ts`. The generated launcher installs icon/tooltip/click-open commands plus the boot presentation/menu, re-derives it after every committed update, and patches presentation/menu independently. Import `StatusItemState` from `@native-sdk/core/events`. Commands route through the core's `commandMsg(name): Msg | null` export. There is no app-owned Zig wiring and `statusItem` is automatically marked shell-bound for the markup lint.\n\n```ts\nimport { asciiBytes, utf8Bytes } from \"@native-sdk/core\";\nimport { type StatusItemState } from \"@native-sdk/core/events\";\n\nexport function statusItem(model: Model): StatusItemState {\n return {\n iconPath: asciiBytes(\"assets/menu-bar.svg\"),\n tooltip: utf8Bytes(\"Player status\"),\n activationCommand: asciiBytes(\"app.refresh\"),\n alternateActivationCommand: asciiBytes(\"player.toggle\"),\n openCommand: asciiBytes(\"app.refresh\"),\n presentation: { title: model.playing ? utf8Bytes(\"MB PLAY\") : utf8Bytes(\"MB\"), width: 62, tone: \"normal\", iconOpacity: 1, monospaced: true, fontSize: 13, fontWeight: \"semibold\" },\n items: [\n { id: 1, label: utf8Bytes(\"Open\"), command: asciiBytes(\"app.open\"), separator: false, enabled: true, detail: asciiBytes(\"\"), role: \"command\", key: asciiBytes(\"\"), modifiers: { primary: false, command: false, control: false, option: false, shift: false } },\n { id: 0, label: asciiBytes(\"\"), command: asciiBytes(\"\"), separator: true, enabled: false, detail: asciiBytes(\"\"), role: \"command\", key: asciiBytes(\"\"), modifiers: { primary: false, command: false, control: false, option: false, shift: false } },\n { id: 2, label: model.playing ? utf8Bytes(\"Pause\") : utf8Bytes(\"Play\"), command: asciiBytes(\"player.toggle\"), separator: false, enabled: true, detail: utf8Bytes(\"configured ✓\"), role: \"agent\", key: asciiBytes(\"\"), modifiers: { primary: false, command: false, control: false, option: false, shift: false } },\n ],\n };\n}\n```\n\nPresentation fields style the persistent menu-bar item. Inside its dropdown, `metric` carries prominent primary/secondary text, `segmented` carries up to eight typed command options, and `chart` carries 1–32 bounded values with captions and accessibility. These are generic composable row payloads, not text conventions.\n\n## App wiring (Zig cores and extensions only)\n\nA default TypeScript app writes none of this: generated wiring connects `src/core.ts`, `src/app.native`, and `app.zon`. Use the following only when the existing app has a Zig core or the task explicitly requires owned runtime wiring.\n\n```zig\nconst HabitsApp = native_sdk.UiApp(Model, Msg);\n\npub fn main(init: std.process.Init) !void {\n // `create` heap-allocates the multi-MB app struct and constructs the\n // Model in place — neither ever rides the stack (avoid `App.init(alloc,\n // model, ...)`: its by-value Model is a stack-overflow trap once the\n // Model grows).\n const app_state = try HabitsApp.create(std.heap.page_allocator, .{\n .name = \"habits\",\n .scene = shell_scene, // one window, one gpu_surface view\n .canvas_label = \"habits-canvas\", // must match the ShellView label\n .update = update,\n .markup = .{\n .source = @embedFile(\"app.native\"),\n .watch_path = \"src/app.native\", // dev hot reload; omit in release\n .io = init.io,\n },\n });\n defer app_state.destroy();\n app_state.model = initialModel(); // boot state: assign through the pointer\n try runner.runWithOptions(app_state.app(), .{ ... }, init);\n}\n```\n\n(`create` requires every Model field to carry a default; the model starts as `.{}` and boot state is assigned through the returned pointer. Tests that instantiate the app per fixture should use `create`/`destroy` too — a runtime-built Model passed to `init` by value crashes the test stack once models get large.)\n\nThe runtime owns the loop: install on first GPU frame, presentation, resize, pointer/keyboard dispatch into `update` + rebuild. With `watch_path` set, editing the `.native` file while the app runs hot-reloads the view within ~2s, preserving model state and widget ids; parse failures keep the last good view and set `app_state.markup_diagnostic` (line/column/message).\n\n**Release: compile the markup at comptime.** `canvas.CompiledMarkupView(Model, Msg, source).build` parses the `.native` source entirely at compile time and produces the identical tree (same ids, handlers, dispatch) with no parser in the binary; markup or binding mistakes become compile errors with line/column. Hand it to `.view`, and gate the runtime engine per build mode:\n\n```zig\nconst dev = @import(\"builtin\").mode == .Debug;\nconst App = native_sdk.UiAppWithFeatures(Model, Msg, .{ .runtime_markup = dev });\nconst CompiledView = canvas.CompiledMarkupView(Model, Msg, @embedFile(\"app.native\"));\n// options:\n.view = CompiledView.build,\n.markup = if (dev) .{ .source = ..., .watch_path = \"src/app.native\", .io = init.io } else null,\n```\n\nWith both set (dev), the compiled view renders until the watched file first changes, then the interpreter hot-reloads it. See the native reference fixture in `tests/ts-core/habits_reference.zig` for this Zig wiring pattern.\n\n### Webview panes: canvas + live web content in one window\n\nFor TypeScript apps, export `webPanes(model: Model): readonly WebViewPane[]` from `core.ts`. Import the descriptor from `@native-sdk/core/events`; return `label`, nullable `anchor`, `url`, `x`, `y`, `width`, `height`, and `reloadToken`. The label identifies an existing manifest WebView; the anchor identifies a widget label such as ``. See `examples/canvas-preview` for pane, frame, and tray coordination in one compiled core. The native adapter copies bytes and validates finite geometry and safe integer tokens; the OS owns WebView hosting and navigation policy.\n\nFor all u64 reload states, return `readonly ExactWebViewPane[]` instead. Its `reloadToken` is decimal ASCII bytes; the host validates the full u64 range without rounding. `WebViewPane` retains its existing safe-number token.\n\n### TypeScript terminal panes\n\nBind `` to a `Uint8Array` helper or field naming the same key as `Cmd.ptySpawn`. Import `TerminalState` from `@native-sdk/core/events` for the message payload. The native host resolves the name to its PTY capability; engine identities never cross through a JavaScript number. Both view backends preserve the complete four-field state report. A bound slot remains reserved through exit until app teardown, keeping the ended screen stable across rebuilds. Restarting the same name reuses its slot; the existing four-slot budget applies. Keep `.terminal_sessions = true` and the lazy Ghostty pin in the app's owned build, as in `examples/workbench`. Native integer PTY bindings remain supported.\n\nFor Zig cores and extensions:\n\nDeclare the webview in the scene next to the gpu_surface (parent it to the canvas view), reserve its region with an empty panel carrying a semantics label, and let `Options.web_panes` snap the webview to that widget's layout frame while the model drives navigation:\n\n```zig\nconst shell_views = [_]native_sdk.ShellView{\n .{ .label = \"app-canvas\", .kind = .gpu_surface, .fill = true, .gpu_backend = .metal },\n .{ .label = \"preview\", .kind = .webview, .parent = \"app-canvas\", .url = \"https://example.com/\", .x = 240, .y = 76, .width = 704, .height = 548 },\n};\n// view: ui.panel(.{ .grow = 1, .semantics = .{ .label = \"preview-pane\" } }, .{})\nfn panes(model: *const Model, out: []App.WebViewPane) usize {\n out[0] = .{ .label = \"preview\", .anchor = \"preview-pane\", .url = model.url(), .reload_token = model.reload_token };\n return 1;\n}\n// options: .web_panes = panes,\n```\n\nURL changes navigate; bumping `reload_token` reloads the same URL (the CenterPane/Preview-tab shape). Pane URLs must pass `security.navigation.allowed_origins`. Panes reconcile against the runtime's live webview state on every rebuild and presented frame, so shell relayouts cannot detach them. `examples/canvas-preview` is the live reference; `zig build test-canvas-preview-smoke` verifies it.\n\n### Menu-bar extra (status item)\n\nThis is the Zig-core/custom-wiring form. Default TypeScript apps use the exported `statusItem(model)` helper above.\n\n`Options.status_item` installs a macOS `NSStatusItem` once, on the installing frame; its menu items dispatch commands through the same `on_command` mapping the toolbar and menus use (source `.tray`):\n\n```zig\n.status_item = .{ .title = \"ZN\", .tooltip = \"My App\", .items = &.{\n .{ .id = 1, .label = \"Refresh\", .command = \"app.refresh\" },\n .{ .separator = true },\n .{ .id = 2, .label = \"Quit\", .command = \"app.quit\" },\n} },\n```\n\nFor a LIVE menu-bar extra (an open-count badge in the title, a latest-items dropdown), add `Options.status_item_fn` — the `web_panes` pattern: consulted on install and after every rebuild, re-applied only when its output changed (title and menu patch independently; the static `status_item` keeps icon/tooltip). Format derived strings into the provided scratch; item `command`s dispatch through `on_command` exactly like static items:\n\n```zig\nfn statusItem(model: *const Model, scratch: *App.StatusItemScratch) App.StatusItemState {\n const title = std.fmt.bufPrint(&scratch.title_buffer, \"ZN {d}\", .{model.open_count}) catch \"ZN\";\n scratch.items[0] = .{ .id = 1, .label = \"Refresh\", .command = \"app.refresh\" };\n var count: usize = 1;\n for (model.latest(), 0..) |issue, i| { // per-row commands: map \"issue.select.N\" in on_command\n scratch.items[count] = .{ .id = @intCast(10 + i), .label = issue.title, .command = issue.select_command };\n count += 1;\n }\n return .{ .title = title, .items = scratch.items[0..count] };\n}\n// options: .status_item_fn = statusItem,\n```\n\nTitle updates retitle the live `NSStatusItem` button without re-creating it; platforms without a tray-title seam keep menu updates and log the title gap once.\n\n### Windowed lists in markup\n\nUse `` to resolve one retained range before rendering, then `` to request only its rendered rows. The window declares a stable literal `id`, an `as` range name, an `item-count`, and either `item-extent` or an exported Model-first `extent-estimate` helper. Optional `gap`, `overscan`, `viewport-fallback`, `index-base`, and `anchor=\"leading|trailing\"` describe the complete content geometry.\n\n```html\n\n \n \n {row.title}\n \n {range.first_visible_index}–{range.last_visible_index}\n \n\n```\n\nIn a TypeScript core, `rows(model: Model, range: VirtualListRange): readonly Row[]` takes the complete SDK range from `@native-sdk/core/events` and returns exactly `range.end_index - range.start_index` rows in rendered-index order. An extent estimator has shape `rowExtent(model: Model, index: number): number`; its retained identity survives rebuilds. Each row has one keyed root. Ordinary scroll styling, `on-scroll`, and reach-start/end messages belong on `virtual-list`.\n\nEach window has one root and exactly one consuming list; windows cannot nest. A range can pass through a template argument, and secondary window views have their own retained descriptors. The full range exposes visible and rendered bounds, content extent, row extent, and offset; use it for footer text without copying scroll state into the model. See `examples/feed` for variable-height estimates, stable row queries, and retained selection.\n\n### Native scrolling (macOS)\n\nZero app code: on macOS every non-virtualized `scroll` region — and every windowed virtual list (`ui.virtualList`), whose driver content size is the full virtual extent — is driven by an invisible `NSScrollView` — OS momentum and the system overlay scrollbar — while the engine renders the content. `widget.value` stays the offset of record, so the rebuild reconcile rule (\"user offset survives rebuilds until the source offset changes\"), automation snapshot offsets (`scroll=[offset=..]`), and `Options.sync` all work exactly as before; the engine-drawn scrollbar simply stops painting for natively driven regions. Programmatic scrolls still work: change the source offset (or scroll via keyboard/automation) and the runtime pushes it into the native scroller. GTK/Win32 and mobile embeds keep the engine's wheel physics unchanged. Nested-scroll saturation handoff (inner region exhausted, outer continues) is per-region native today: the inner region stops at its edge like a standalone scroller.\n\n**Overscroll is off by default, per region, on both paths.** Scroll regions pin at their content edges — the native scroller gets non-elastic edges, the engine's wheel/kinetic physics clamp, and kinetic motion stops cleanly at the boundary. Bouncing is a per-region opt-in: `overscroll=\"rubber_band\"` in markup (the `scroll` element only — the validator rejects it elsewhere with a teaching error) or `ElementOptions.overscroll = .rubber_band` in Zig views. The `ScrollPhysics.overscroll` design token (`ScrollPhysicsOverrides` in a theme) flips the app-wide default; per-region values override it, and `.none` pins a region regardless of the token. The rubber-band shape — excursion bound, resistance, spring-back rate — stays themable through the `rubberband_*` physics tokens.\n\n### Context menus: one declared menu, platform-decided presentation\n\nAuthors write ONE menu; the platform decides how it presents. The default is the real OS context menu at the pointer — `NSMenu` on macOS, `TrackPopupMenu` on Windows, `GtkPopoverMenu` on Linux — and the selection dispatches the item's typed `Msg`. On hosts without a native menu presenter (the mobile toolkit hosts and embed hosts today), the SAME declared items present automatically as an anchored canvas surface at the click point, with the standard anchored-surface behavior (Escape and outside-click dismiss, late z-pass, window clipping). Never two authored menus, never a canvas imitation where the OS menu exists.\n\nMarkup declares the menu as a `` element — a DIRECT child of the interactive element whose right-click it answers (a hit-target kind, or an element made interactive by `on-press`/`on-double-press`/`on-toggle`/`on-hold`/`on-drag`). It is metadata, not content: it renders nothing in the row's flow. Children are `menu-item`s (`on-press` required, `disabled` optional, the text content is the label) and bare ``s, with `if`/`else`/`for` around them to swap or repeat items — a menu whose items all evaporate at runtime simply declares no menu (the All Notes row pattern). Conditional MENUS are spelled as conditional ITEMS: the `` itself takes no attributes and cannot sit behind a structure tag. No submenus: the platform channel carries flat items (label, enabled, separator) only.\n\n```html\n\n {n.title}\n \n \n Restore\n Delete Permanently\n \n \n Copy\n Delete\n \n \n\n```\n\nThe compiled TypeScript view supports one direct menu with at most 32 labeled `menu-item` leaves and bare separators. Items require `on-press` and may bind `disabled`; structure tags inside menus currently remain on the native markup backend. The menu is copied into the native tree arena before the compiled result expires.\n\nThe Zig builder's mirror is `ElementOptions.context_menu` — per-widget items in the chrome-menu shape with typed messages:\n\n```zig\nui.listItem(.{\n .on_press = Msg{ .select = entry.index },\n .context_menu = &.{\n .{ .label = \"Open Section\", .msg = Msg{ .select = entry.index } },\n .{ .separator = true },\n .{ .label = \"Refresh Dashboard\", .msg = .refresh },\n },\n}, entry.title)\n```\n\nThe deepest declaring widget on the hit route wins; disabled items and separators are fine (`enabled = false`, `.separator = true`). Zero-code defaults need no declaration: editable text fields present the standard Cut / Copy / Paste / Select All menu wired to the existing clipboard actions, and a selected static text presents Copy (these defaults are presenter-only — without an OS menu they degrade to the keyboard clipboard paths). Touch long-press is design-noted for the mobile embeds: the iOS host's under-slop `Pending` touch state is the timer seam, pending a secondary-button leg in the embed ABI and `UIEditMenuInteraction` presentation.\n\nAutomation drives the native path honestly: snapshots list every widget's declared items in invocation order (`context_menu=[\"Rename\",\"Delete\"]`, separators keep their slots, disabled items say so), `widget-context-press ` performs the real secondary click (presenting the menu), and `widget-context-menu ` invokes an item — the selection dispatches as the same `context_menu_action` platform event a real pick produces; the journal records the complete widget invocation so replay reconstructs its pending request before selection, because the OS menu's tracking loop cannot be driven programmatically. Dead invocations fail by name (undeclared menu, index out of range, separator slot, disabled item). `examples/notes` row menus and `examples/gpu-dashboard` nav rows carry live menus; `zig build test-example-notes`, `test-example-gpu-dashboard`, and the runtime context-menu suite verify dispatch, the fallback surface, and the verb.\n\n## Elements\n\n| Markup | Widget | Notes |\n| --- | --- | --- |\n| `row`, `column` | flex containers | main axis horizontal / vertical |\n| `stack`, `panel`, `card` | overlay containers | children stack on top of each other — `gap` can never space them and is a validation error (put a `column`/`row` inside for flow) |\n| `scroll` | scroll_view | wrap multiple children in a `column` inside it |\n| `list`, `grid` | list, grid | vertical stack / cell grid |\n| `tabs`, `toggle-group`, `button-group`, `radio-group`, `breadcrumb`, `pagination` | row containers | children flow horizontally. Give every `radio-group` an accessible `label`; it is one logical `radiogroup`: descendant radios at any nesting depth share one Tab stop; arrows wrap while Home/End move to the edges, focus and selection move together, and selecting one clears the rest of the nearest group scope |\n| `table` > `table-row` > `table-cell` | table, data_row, data_cell | rows only inside a table, cells only inside a row (for/if wrappers are fine); cells are text leaves, dispatch with `on-press` |\n| `dropdown-menu` | dropdown_menu | vertical menu surface; children are `menu-item`s. `anchor=\"below\\|above\"` floats it against its PARENT's frame (see Pickers): late z-pass above the whole tree, window-clipped, auto-flipping at the window edges, zero flow space. Pair with `on-dismiss` |\n| `accordion` | accordion | header via `text` attr; children show while `selected`, dispatch `on-toggle` |\n| `alert`, `bubble` | surfaces | `alert` title via `text` attr; children stack inside. `bubble` hugs its message up to 80% of the thread (`ghost` exempt; explicit `width` wins) and takes one `` child — the reaction pill straddling its bottom edge, one text run, dock via `text-alignment` (default `end`); `text=` on bubble itself is a teaching error (that channel belongs to the pill). Grouped runs are spacing, not vocabulary: 8 gap within a sender's run, 32 between turns |\n| `dialog`, `drawer`, `sheet` | modal surfaces | root-relative and unaffected by ancestor scroll or clipping: dialogs center in the viewport, drawers span its width and dock to the bottom, and sheets span its height and dock to the right — title via `text` attr, wrap in `` to show conditionally |\n| `resizable` | resizable | engine-managed drag handle; `width` sets the initial width |\n| `split` | split | two-pane horizontal splitter: exactly two element children (nest splits for more panes), the engine synthesizes the draggable divider between them. `value` binds the model-owned first-pane fraction (0 lays out at 0.5), `on-resize` names an f32 Msg variant dispatched with every applied fraction (echo it back through `value` — see Splitters), `min-width` on the panes bounds the drag, `gap` sets the divider band thickness. The divider is focusable: Left/Right (Shift for bigger steps) adjust, Home/End jump to the clamp edges |\n| `tree` | tree | disclosure-tree container (vertical flow): descendant rows carrying `role=\"treeitem\"` — at ANY nesting depth — form one roving keyboard focus set with the ARIA tree keymap. Up/Down walk visible rows (selection follows focus through each row's `on-press`), Left collapses an expanded row or moves to the parent row, Right expands a collapsed row or moves to the first child row, Home/End jump to the edges, Enter/Space activate. Expandable rows bind `expanded` and `on-toggle`; the model owns selection and expansion (collapsed children are simply not rendered) |\n| `text`, `badge`, `tooltip` | text leaves | text content, `{}` interpolation allowed; `text` line policy via `wrap` (`\"true\"` word-wraps; `\"false\"`/unset paint one honest line, overflow eliding by default — `overflow=\"clip\"` opts out), and `text` alone takes the typography rungs `size=\"heading\"`/`size=\"display\"` (themable token steps above title — section headings, hero stats, timer numerals). `tooltip` with `anchor=\"above\\|below\"` floats against its parent (the stack wrapping trigger + tooltip, the dropdown pattern) and the RUNTIME owns its visibility — hover intent on the trigger: shows after `tooltip-delay` ms (default 600; `\"0\"` = instant) and immediately on keyboard focus; hides on leave, focus departure, Escape, or a press of the trigger (a press also closes the warm window), and a shared 400ms warm window after a pointer-hovered tooltip hides on leave (the only hide that warms) shows the next trigger's tooltip instantly; the model never hears hover. These are shadcn/ui's defaults (Base UI). Without `anchor` it stays a static leaf that paints whenever the view renders it |\n| `text` > `span` | inline styled runs | mixed-style text in ONE wrapped paragraph: span children style runs with `weight=\"regular\\|medium\\|bold\"`, `mono`, `italic`, `scale` (a positive multiplier on the paragraph's base size — inline headings, hero stats), `underline`, `foreground` (token name); `{bindings}` interpolate inside spans; whitespace between runs collapses to a single space (none = the runs abut); spans do not nest, take no events, and the paragraph announces as one text run — see \"Rich text\" |\n| `button`, `toggle-button`, `list-item`, `menu-item`, `toggle`, `switch`, `select`, `avatar` | text-bearing controls | label is the text content; `button`, `toggle-button`, `list-item`, and `menu-item` also take `icon=\"save\"` — a vector icon drawn inline (buttons/toggle-buttons before the label, icon-only when the content is empty: add a `label`; list/menu items as a leading slot), ONE hit target whose icon follows the element's enabled/disabled tint (no overlay stacking, no duplicated `on-press`); tab strips are `toggle-button` children, so tabs get icons this way; `select` shows `placeholder` while empty and dispatches `on-press`; `avatar` renders initials, or a runtime image via `image=\"{binding}\"` (see the Images section) |\n| `segmented-control` | exclusive-choice control | standalone text-bearing segment; bind `selected`, dispatch `on-press`, and optionally add a vector `icon`; compose several in a row, or use `tabs` for the strip-and-panel pattern |\n| `checkbox`, `radio`, `slider`, `progress` | value controls | `checked`, `value` (a 0..1 fraction on slider and progress; progress clamps out-of-range values at render, never an error); checkbox/radio visible labels are text content (`Done`), with `text=\"...\"` as the equivalent binding-friendly form and `label=` alone naming one for accessibility without drawing a label; a radio selection TRANSITION (pointer, Space/Enter, grouped navigation, or accessibility selection) dispatches `on-change` when bound, then `on-toggle`, then `on-press` for compatibility — reactivating the already-checked radio has no new `on-change` edge, though a legacy fallback still receives the activation; a slider's `value` follows the source when it MOVES (model-driven progress renders every rebuild) and keeps the user's drag while the source replays the same value — use `slider` for seek bars, `progress` for display-only; a markup slider's `on-change` dispatches a PLAIN Msg with no value payload — mirror the applied value into the model with `Options.sync` (the Zig builder's `on_value = Ui.valueMsg(.tag)` does deliver the applied f32) |\n| `text-field`, `input`, `search-field`, `combobox`, `textarea` | text entry | `placeholder`; edits via `on-input`, enter via `on-submit` on single-line kinds; in a default `textarea`, Enter (and Shift+Enter) inserts a newline and `on-submit` dispatches on primary+Enter (cmd on macOS, ctrl elsewhere). A chat composer opts into `submit-on-enter=\"true\"`: plain Enter submits, Shift+Enter remains a newline, and the primary chord still submits. `search-field` carries a built-in trailing clear affordance whenever it holds text (press the x, or Escape while focused — both clear through the text-edit path, so `on-input` hears it; no attribute, no external Clear button needed) |\n| `status-bar` | status bar | text leaf: content only, no children |\n| `separator`, `spacer` | separator, flexible space | `separator` is axis-aware: a horizontal rule in a `column`, a thin vertical divider in a `row`; give `spacer` a `grow` |\n| `skeleton`, `spinner` | loading leaves | size `skeleton` with `width`/`height` |\n| `icon` | vector icon leaf | `name` picks the icon: a bare literal is a curated built-in stroke icon (compile-checked; 49 names: search, plus, x, x-circle, check, check-circle, chevron-up/down/left/right, arrow-up/down/right, menu, panel-left, panel-right, settings, terminal, wrench, trash, edit, copy, external-link, play, pause, skip-back/forward, shuffle, repeat, music, volume, info, alert, download, save, folder, folder-open, file-text, sun, moon, eye, clock, git-pull-request, git-merge, git-branch, circle-dot, archive, refresh-cw, send); `app:` reaches an icon the app registered at boot with `canvas.icons.registerAppIcons` (declare the table as `pub const app_icons` on the app root so `native check` verifies the name against the model contract), and one `{binding}` defers the choice to model data - an unknown resolved name draws the missing-icon fallback (a slashed circle) with a Debug warning naming the value; tint with `foreground`, size with `width`/`height` |\n| `media-surface` | media surface leaf | composites a texture produced OUTSIDE the widget tree (video decoder, camera, an external renderer like mpv) into the layout like any widget — clipped, z-ordered, rounded. `surface=\"{binding}\"` (required) binds the model-owned u64 surface id a Zig-tier producer targets (`runtime.acquireMediaSurfaceProducer` pushes RGBA8 frames, latest-wins, paced by the presented-frame clock; 0 = unbound, draws nothing; usable ids are nonzero values below the reserved bit 63). No intrinsic size — give it `width`/`height` or `grow`; display-only (presses fall through); `label` it (pictorial content). Texture contents are presentation chrome: goldens, reference screenshots, and session replay show the deterministic id-derived placeholder, never producer frames |\n| `image` | runtime image leaf | draws a RUNTIME-REGISTERED image by its model-owned u64 ImageId — the id `Cmd.imageLoad` (TS) or `fx.loadImage`/`fx.registerImageBytes` (Zig) registered pixels under. `image=\"{binding}\"` (required) binds a model field/fn; ids are model data, never markup literals, and 0 draws nothing (store the id only when the load reports loaded — see the Images section). `source-x`/`source-y`/`source-width`/`source-height` select one atlas region in decoded-image pixel coordinates (declare all four). No intrinsic size — give it `width`/`height` or `grow`; display-only (presses fall through); `label` it (pictorial content) |\n| `code` | bare highlighted source/editor | `source=\"{binding}\"` (required) provides source text and `language=\"tsx\"` selects a literal lexer name; the component supplies no background, border, radius, shadow, or padding, so wrap it in a panel/card when chrome is wanted. It is read-only by default; `editable on-input=\"edit\"` opts into multiline editing while retaining highlighting. It wraps by default, `line-numbers` opts into logical line numbers, `added-lines=\"5\"` / `removed-lines=\"2-4\"` add Geist-style diff rows without changing copied source, and `wrap=\"false\"` preserves lines inside one horizontal scroll region. HTML-family highlighting distinguishes HTML/XML/SVG and JSX/TSX tags, attributes, strings, comments, and embedded expressions. Zig builder: `ui.code(CodeOptions, source)` |\n| `markdown` | rendered markdown subtree | leaf; `source` is one `{binding}` — see \"Markdown in markup\" |\n| `stepper` > `step` | composite stage track | `active=\"{index}\"` (required) derives each step's completed/active/pending state; steps are text leaves (no attributes) joined by connectors; stepper also takes `key`, `global-key`, `label` |\n| `timeline` > `timeline-item` | composite ledger list | items only inside a timeline (for/if fine); items are leaves — `title` (required), `description`, `meta`, `indicator`, `variant`, `connector=\"false\"` on the last item, `selected`; `on-press` makes the whole item pressable with a trailing chevron |\n| `chart` > `series` | composite data chart | series only inside a chart, and only series (the set is static — data varies through bindings); each series is a leaf — `values=\"{binding}\"` (required) names a model `[]const f32` iterable, `kind` is `line`/`area`/`bar` (literal), `color` a token name, `label` the semantics name; chart takes `y-min`, `y-max`, `grid-lines`, `baseline`, `x-labels`, `y-labels`, `hover-details`, `stroke-width`, box options, `label` — see \"Charts\" |\n| `context-menu` | consumed by its parent | right-click menu on its DIRECT parent (a hit-target kind or an element with `on-press`/`on-double-press`/`on-toggle`/`on-hold`/`on-drag`); metadata, never a flow child. Children: `menu-item`s (`on-press` required, `disabled` optional, no `icon`) and bare `separator`s, with `if`/`else`/`for` around them. Attribute-less; presents natively where the host has a menu presenter, as an anchored surface elsewhere — see \"Context menus\" |\n| `input-group` > `textarea` + `input-group-actions` | composite grouped input | the composer shape: ONE bordered field wrapping exactly one `textarea` (first — document order is focus order) plus an optional `input-group-actions` row of controls inside the same border. The group wears the focus ring for its focused descendant and the textarea's own chrome dissolves automatically, so the whole group reads as one field; the textarea keeps its full behavior (`text`, `placeholder`, `on-input`, `on-submit`, `autofocus`, and optional `submit-on-enter`). Group takes `label`, `width`, `height`, `min-width`, `grow`, `key`, `global-key`; the actions row takes `gap` and holds ordinary elements (`if`/`else`/`for` work — swap send for stop while streaming) — put a `` between leading and trailing controls (`Ui.inputGroup`/`Ui.inputGroupActions` are the Zig-view equivalents) |\n\nCapabilities still awaiting a separate admission or ruling are image-backed `icon_button` content, `data_grid` per-column cell templates, and `popover`/`menu_surface` anchoring. `segmented-control` is a first-class markup leaf, and vector icon buttons use `