# Native SDK Documentation > Technical reference for the Native SDK toolkit: declarative .native markup, Zig app model, CLI workflows, automation, packaging, and platform hosts for building native desktop apps without a browser runtime. ## Context Links - [Agent index](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/llms.txt) - [Human interactive docs](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a) - [GitHub repository](https://github.com/vercel-labs/native) ## Repository Metadata - Repository: vercel-labs/native - Generated: 2026-07-09T08:24:49.332Z - Updated: 2026-07-09T08:25:27.078Z - Runtime: Grok CLI - Format: Documentation - Pages: 27 ## Page Index - 01. [Overview](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/01-overview.md) - What Native SDK exposes, who should use it, runtime assumptions, and the first docs routes from install to a running window. - 02. [Installation](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/02-installation.md) - Install @native-sdk/cli, platform package layout, prerequisites, and success signals for a working native binary on each host OS. - 03. [Quickstart](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/03-quickstart.md) - Create an app with native init, run native dev, edit .native markup and Zig Model/Msg/update, and verify the first live window. - 04. [Agent skills](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/04-agent-skills.md) - Shipped skill packs for core authoring, Native UI, and automation, including how agents discover and apply them via the CLI. - 05. [App model](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/05-app-model.md) - Model, Msg, and update loop wiring, hot reload boundaries, and how markup binds values without mutating state. - 06. [Native UI markup](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/06-native-ui-markup.md) - Elements, attributes, flex layout, bindings, expressions, and editor/LSP support for .native views compiled into the binary. - 07. [State and data flow](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/07-state-and-data-flow.md) - Derive-don't-store patterns, message dispatch, text editing paths, and effects as the only channel for side effects. - 08. [Theming](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/08-theming.md) - Design tokens for color, radius, and typography, live theme re-resolution, chrome passes, and token-only restyles across apps. - 09. [Components](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/09-components.md) - Built-in component catalog inventory, preview generation, eject workflows, and identity constraints for reusable widgets. - 10. [Windows and surfaces](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/10-windows-and-surfaces.md) - Multi-window apps, native surface composition, OS window chrome, GPU surfaces, and host presentation on macOS and desktop peers. - 11. [Menus, dialogs, and tray](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/11-menus-dialogs-and-tray.md) - App menus, context menus, system dialogs, tray status items, and how OS-owned UI coexists with engine-drawn widgets. - 12. [Commands and keyboard shortcuts](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/12-commands-and-keyboard-shortcuts.md) - Single command routing across toolbar, menu, tray, shortcut, and bridge entry points with keyboard binding constraints. - 13. [Capabilities](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/13-capabilities.md) - Guarded OS services for notifications, clipboard, credentials, dialogs, file drops, and effect-channel access boundaries. - 14. [Web engines](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/14-web-engines.md) - WebView composition on desktop hosts, CEF tooling and hosts, engine flags, and when native-rendered UI coexists with web content. - 15. [Bridge and builtin commands](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/15-bridge-and-builtin-commands.md) - Host-to-content bridge payloads, responses, async dispatch, builtin commands, and permission boundaries for WebView apps. - 16. [Frontend projects](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/16-frontend-projects.md) - Managed React, Next, Svelte, and Vue shells, frontend asset pipeline, and native dev server integration for web frontends. - 17. [Embedded app](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/17-embedded-app.md) - C embed ABI, host view controllers, mobile canvas libraries, and experimental iOS/Android host shims around the desktop-first runtime. - 18. [Automation](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/18-automation.md) - Embedded automation server: accessibility snapshots, widget driving, record/replay, deterministic screenshots, and agent command surface. - 19. [Testing](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/19-testing.md) - Full-loop UI tests via native test, headless truth drivers, effect tests, and frame-level verification without a display server dependency. - 20. [Testing in CI](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/20-testing-in-ci.md) - CI workflows, gate scripts, platform truth drivers, and eval harness wiring for reproducible headless and hosted checks. - 21. [Packaging](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/21-packaging.md) - From ReleaseFast binaries to distributable app bundles: assets, build graph outputs, and packaging layout expectations. - 22. [Code signing](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/22-code-signing.md) - Codesign tooling, framework and native binary copy steps, and signing constraints for macOS and related package pipelines. - 23. [Updates and package distribution](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/23-updates-and-package-distribution.md) - Update channels, npm multi-platform package layout, version sync checks, and binary distribution for @native-sdk packages. - 24. [CLI reference](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/24-cli-reference.md) - native init, dev, check, test, build, automate, doctor, and skills commands with flags, outputs, and failure modes. - 25. [Runtime and effects](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/25-runtime-and-effects.md) - Runtime API surface, effect kinds for spawn/fetch/file/audio/clipboard, cancellation, worker wakes, and deterministic frame limits. - 26. [Platform support and security](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/26-platform-support-and-security.md) - Host capability matrix for macOS, Linux, Windows, and experimental mobile, plus bridge permission and capability security boundaries. - 27. [Contributing](https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/27-contributing.md) - Local development setup, agent guidance, release and changelog merge process, and pre-1.0 contribution expectations. ## Source File Index - `.github/workflows/ci.yml` - `AGENTS.md` - `build.zig` - `build/app.zig` - `CHANGELOG.md` - `CONTRIBUTING.md` - `docs/src/app/dialogs/layout.tsx` - `docs/src/app/embed/layout.tsx` - `docs/src/app/frontend/layout.tsx` - `docs/src/app/keyboard-shortcuts/layout.tsx` - `docs/src/app/menus/layout.tsx` - `docs/src/app/native-surfaces/layout.tsx` - `docs/src/app/native-ui/layout.tsx` - `docs/src/app/packages/layout.tsx` - `docs/src/app/packaging/layout.tsx` - `docs/src/app/packaging/signing/layout.tsx` - `docs/src/app/quick-start/layout.tsx` - `docs/src/app/runtime/layout.tsx` - `docs/src/app/security/layout.tsx` - `docs/src/app/skills/layout.tsx` - `docs/src/app/state/layout.tsx` - `docs/src/app/testing/ci/layout.tsx` - `docs/src/app/testing/layout.tsx` - `docs/src/app/theming/layout.tsx` - `docs/src/app/tray/layout.tsx` - `docs/src/app/updates/layout.tsx` - `docs/src/app/web-engines/layout.tsx` - `docs/src/app/windows/layout.tsx` - `docs/src/components/component-preview.tsx` - `docs/src/components/eject-section.tsx` - `docs/src/components/home/install-toggle.tsx` - `docs/src/lib/component-vocab.json` - `docs/src/lib/components-pages.ts` - `docs/src/lib/docs-navigation.ts` - `editors/native-markup/extension.js` - `editors/native-markup/README.md` - `evals/README.md` - `examples/browser/frontend/app.js` - `examples/calculator/README.md` - `examples/capabilities/build.zig` - `examples/capabilities/README.md` - `examples/command-app/build.zig` - `examples/command-app/README.md` - `examples/deck/README.md` - `examples/deck/src/chrome.zig` - `examples/effects-probe/README.md` - `examples/hello/build.zig` - `examples/ios/README.md` - `examples/mobile-canvas/build.zig` - `examples/next/build.zig` - `examples/react/build.zig` - `examples/README.md` - `examples/soundboard/README.md` - `examples/webview/README.md` - `packages/native-sdk/npm/darwin-arm64/README.md` - `packages/native-sdk/README.md` - `packages/native-sdk/scripts/build-binaries.sh` - `packages/native-sdk/scripts/check-version-sync.js` - `packages/native-sdk/scripts/copy-framework.js` - `packages/native-sdk/scripts/copy-native.js` - `README.md` - `RELEASING.md` - `scripts/changelog-merge.sh` - `scripts/gate.sh` - `skill-data/automation/SKILL.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/SKILL.md` - `skill-data/native-ui/SKILL.md` - `skills/native-sdk/SKILL.md` - `src/embed/c_api.zig` - `src/embed/chrome.zig` - `src/embed/host.zig` - `src/platform/linux/cef_host.cpp` - `src/platform/linux/gtk_host.h` - `src/platform/macos/appkit_host.m` - `src/platform/windows/cef_host.cpp` - `src/primitives/canvas/themes/geist.zig` - `src/runtime/api.zig` - `src/runtime/async_bridge.zig` - `src/runtime/automation_commands.zig` - `src/runtime/automation_snapshot.zig` - `src/runtime/automation_widget_dispatch.zig` - `src/runtime/bridge_payload.zig` - `src/runtime/bridge_responses.zig` - `src/runtime/builtin_bridge.zig` - `src/runtime/canvas_widget_context_menu.zig` - `src/runtime/canvas_widget_runtime.zig` - `src/runtime/core.zig` - `src/runtime/effects_tests.zig` - `src/runtime/effects.zig` - `src/runtime/flow.zig` - `src/runtime/gpu_surface_events.zig` - `src/tooling/android.zig` - `src/tooling/assets.zig` - `src/tooling/buildgraph.zig` - `src/tooling/cef.zig` - `src/tooling/codesign.zig` - `src/tooling/dev.zig` - `src/tooling/doctor.zig` - `src/tooling/eject_components.zig` - `src/tooling/embedlib.zig` - `src/tooling/ios.zig` - `tests/README.md` - `third_party/cef/README.md` - `tools/linux-truth/drive.sh` - `tools/linux-truth/README.md` - `tools/native-sdk/automation.zig` - `tools/windows-truth/README.md` --- ## 01. Overview > What Native SDK exposes, who should use it, runtime assumptions, and the first docs routes from install to a running window. - Page Markdown: https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/01-overview.md - Generated: 2026-07-09T08:16:27.495Z ### Source Files - `README.md` - `packages/native-sdk/README.md` - `docs/src/lib/docs-navigation.ts` - `build.zig` - `examples/README.md` --- title: "Overview" description: "What Native SDK exposes, who should use it, runtime assumptions, and the first docs routes from install to a running window." --- Native SDK is a Zig-backed toolkit for desktop apps: declarative `.native` views, plain Zig `Model` / `Msg` / `update`, and a pixel engine that draws into real OS windows without a browser, WebView, or markup interpreter in release binaries. The primary author surface is the `native` CLI (`@native-sdk/cli`, currently versioned with the framework packages), which scaffolds apps, owns the zero-config build graph, validates markup, runs headless UI tests, packages hosts, and ships agent skill packs. ## What the SDK exposes | Surface | Role | | --- | --- | | **CLI** (`native`) | `init`, `dev`, `build`, `test`, `check`, `eject`, `doctor`, `validate`, `package`, `automate`, `skills`, `markup`, `version` | | **App model** | `native_sdk.UiApp(Model, Msg)` / `UiAppWithFeatures` wires Model, Msg, `update`, scene, and markup into the runtime | | **Markup** | `.native` files: elements, flex layout, `{bindings}`, expressions, message dispatch; compile-time `canvas.CompiledMarkupView` in release | | **Runtime** | Windows, GPU / software presentation, timers, commands, effects (spawn / fetch / file / audio / clipboard), automation server | | **Manifest** | `app.zon` — identity, windows, permissions, capabilities, bridge policy, security, web engine, packaging inputs | | **OS hosts** | Platform modules under `src/platform/` for macOS, Linux, Windows; experimental embed / mobile hosts via C ABI | | **Optional web path** | System WebView (and CEF Chromium on macOS) with bridge commands and managed frontend shells | | **Agent skills** | Shipped packs: `core`, `native-ui`, `automation` via `native skills list\|get` | The public Zig root (`src/root.zig`) re-exports the runtime (`Runtime`, `App`, `UiApp`, effects, clocks, test harness), platform types (windows, WebViews, GPU surfaces), automation, embed, bridge, frontend helpers, and security symbols. App authors typically depend on that module through the CLI-bundled framework rather than composing platform hosts by hand. ### Two app architectures ```text Default (native-rendered) Optional (WebView shell) ───────────────────────── ──────────────────────── .native + Model/Msg/update frontend/ + App + WebViewSource │ │ ▼ ▼ UiApp canvas tree Runtime WebView host │ │ └──────── OS window / chrome ──────────┘ menus · tray · dialogs (host-owned where supported) ``` - **Native-rendered (default):** `native init` scaffolds `src/app.native` + `src/main.zig` + `src/tests.zig` + `app.zon`. The engine owns every pixel; markup binds and dispatches only — it never mutates state. - **WebView shell:** `native init --frontend next|vite|react|svelte|vue` (or examples like `hello` / `webview`) loads web content in a platform WebView. Zig still owns lifecycle, windows, bridge policy, and packaging. One app can mix native canvas surfaces and WebViews. ## Who should use it | Audience | Fit | | --- | --- | | Desktop app authors who want declarative UI + typed state without shipping a browser runtime | Primary | | Teams shipping small native binaries with design tokens and a component catalog | Primary | | Humans and agents co-authoring UI (skills + automation + `native check` diagnostics) | Primary | | Products that need OS chrome (menus, tray, dialogs, credentials, notifications) behind explicit permissions | Primary | | Apps that already have a web frontend and need a native shell | Secondary (`--frontend`, bridge, WebView examples) | | Mobile hosts / embed consumers | Experimental (iOS/Android embed ABI; desktop remains mature) | Native SDK is **pre-1.0**: APIs still move. Prefer focused app work and issue discussion for large design changes. License: Apache-2.0. ## Runtime assumptions | Assumption | Detail | | --- | --- | | **Desktop-first hosts** | macOS is the deepest host (Metal presentation, OS scroll physics, native menus/tray/dialogs). Linux and Windows run full desktop apps (software renderer presentation, IME, CI truth drivers). | | **State loop** | Exactly one mutation site: `update(model, msg)`. Markup and views re-derive UI; side effects go through the effects channel, not ad-hoc mutation in views. | | **Build ownership** | Zero-config apps (`app.zon` + `src/`) let the CLI generate the build under `.native/build/`. `native eject` or `native init --full` writes owned `build.zig` / `build.zig.zon`. | | **Toolchain** | Apps compile with Zig. Compatible `zig` on `PATH` is used when present; otherwise `native dev\|build\|test` can fetch the pinned toolchain into `~/.native/toolchains/`. | | **SDK location** | `native init` records the framework path from the installed CLI (or `--framework`). The npm package ships SDK sources so init/dev work offline after install (no install scripts; platform binaries are optionalDependencies). | | **Debug vs release markup** | Debug + `watch_path` enables hot reload of `.native` files without losing model state. Release embeds compile-time compiled markup — no parser in the binary; markup mistakes become compile errors. | | **Headless truth** | Tests and automation can run without a display server via null / headless drivers; live automation uses a file-based protocol under `.zig-cache/native-sdk-automation/`. | | **Security defaults** | WebView content is untrusted: permissions, bridge command origins, and navigation allowlists in `app.zon` gate access. Unsupported platform services return explicit errors (for example Linux tray → `UnsupportedService`). | ### Host capability snapshot | Capability | macOS | Windows | Linux | Mobile (experimental) | | --- | --- | --- | --- | --- | | Real OS windows | Full | Full | Full | Full-screen toolkit host | | Native rendering | Metal + OS scroll | Software + GDI | Software + cairo | Software via embed hosts | | Menus / tray | Full | App menus + tray; context menus as canvas | App menus; tray unsupported | None | | WebView | System (+ CEF Chromium optional) | System (maturing) | System WebView | Embed / host shells | | Packaging | `.app` / DMG | Directory artifact | Install tree | Generated Xcode / APK hosts | | Code signing tooling | Ad-hoc + identity | — | — | Manual | Unsupported operations fail explicitly rather than pretending host parity. See [Platform support and security](/platform-security) for the full matrix and bridge permission boundaries. ## Package and install layout Install the CLI: ```bash npm install -g @native-sdk/cli native version ``` Expected version line shape: `native (commit , automation protocol v)`. | Package | Contents | | --- | --- | | `@native-sdk/cli` | `bin/native.js`, SDK sources (`src/`, `build/`, `build.zig*`, `app.zon`), `skills/`, `skill-data/` | | `@native-sdk/cli-` | Optional per-OS native binary (darwin-arm64/x64, linux-arm64/x64 gnu/musl, win32-arm64/x64) | First-build toolchain install may prompt; pass `--yes` for non-interactive scripts. Success signal after init/dev: a native window opens with the scaffolded counter (or frontend shell) and `native check` reports markup + manifest OK. ## From install to a running window `npm install -g @native-sdk/cli` then `native version`. Confirm the binary resolves and prints version + automation protocol. `native init my_app` creates a zero-config native-rendered app: `src/app.native`, `src/main.zig`, `src/tests.zig`, `app.zon`, `assets/icon.png`. Use `--frontend <…>` for a web shell or `--full` for owned build files and CI scaffold. `cd my_app && native dev`. First run compiles the app and SDK (slower); later runs are incremental. Debug build arms markup hot reload on `src/app.native`. `native check` validates every `src/**.native` and `app.zon` without a full build. `native test` runs full-loop UI tests headlessly. `native build` emits `zig-out/bin/` (ReleaseFast). ### Scaffold shape (native default) :::files my_app/ app.zon # identity, windows, permissions, security src/ app.native # UI: layout, bindings, on-press messages main.zig # Model, Msg, update, UiApp wiring, shell scene tests.zig # headless full-loop UI tests assets/ icon.png # single square source for packaging icons ::: ### Authoring loop ```zig // src/main.zig — state only changes here pub fn update(model: *Model, msg: Msg) void { switch (msg) { .increment => model.count += 1, .decrement => model.count -= 1, .reset => model.count = 0, } } ``` ```html {count} ``` While `native dev` runs, edit the markup: the window updates within about two seconds and keeps model state. Parse failures keep the last good view and surface `file:line:column` diagnostics (`native markup lsp` for editor integration). ### Repository examples Most apps under `examples/` are zero-config (`app.zon` + `src/`). From an example directory (or with repo-built `zig-out/bin/native`): | Path | Shows | | --- | --- | | `examples/habits` | Smallest native markup app | | `examples/calculator` | Keypad, keyboard path, chrome shortcuts, theming | | `examples/notes` | Effects channel persistence, dialogs, search | | `examples/feed` | 100k-row virtualized list | | `examples/soundboard` / `deck` | Same widgets, different tokens / multi-window | | `examples/hello` / `webview` | WebView shell and bridge policy | | `examples/capabilities` | Guarded OS services | | `examples/next`, `react`, `svelte`, `vue` | Managed frontend shells | ## Architecture layers ```mermaid flowchart TB subgraph authoring [Author surfaces] CLI["native CLI"] Markup[".native markup"] ZigApp["Model / Msg / update"] Manifest["app.zon"] Skills["skill-data packs"] end subgraph sdk [SDK modules] UiApp["runtime UiApp"] Canvas["primitives/canvas"] Runtime["runtime + effects"] Bridge["bridge + security"] Auto["automation server"] end subgraph host [Host] Plat["platform: macOS / Linux / Windows"] OSWin["OS windows · menus · tray · dialogs"] OptionalWeb["optional WebView / CEF"] Embed["embed C ABI · experimental mobile"] end CLI --> Markup CLI --> ZigApp CLI --> Manifest CLI --> Skills Markup --> UiApp ZigApp --> UiApp Manifest --> Runtime UiApp --> Canvas UiApp --> Runtime Runtime --> Plat Runtime --> Auto Bridge --> OptionalWeb Plat --> OSWin Plat --> OptionalWeb Runtime --> Embed ``` ## Agent and automation surface Every app can embed the automation server for accessibility snapshots, widget driving, assertions, deterministic CPU-reference screenshots, and record/replay (`native automate …`). Skill packs ship with the CLI: | Skill | Use when | | --- | --- | | `core` | Project anatomy, runtime, frontend, bridge, packaging | | `native-ui` | `.native` authoring, Model/Msg/update, UiApp | | `automation` | Driving a running app, smoke tests, screenshots | ```bash native skills list native skills get native-ui native skills get core --full ``` Skills are portable file/catalog content, not tied to a particular model provider. Agents should load skills before inventing APIs from general training data. ## Status and contribution boundary - **App authors:** install `@native-sdk/cli`, follow install → init → dev → check/test. - **Toolkit contributors:** Zig 0.16+, `zig build test`, `scripts/gate.sh fast` for affected suites; see [Contributing](/contributing). Do not treat pre-1.0 APIs as stable contracts without checking current sources. ## Next Install `@native-sdk/cli`, platform package layout, prerequisites, and success signals per host OS. `native init`, `native dev`, edit markup and Zig, verify the first live window. Model, Msg, update loop, hot reload boundaries, and markup binding rules. Full command list: init, dev, check, test, build, automate, doctor, skills. Discover and apply shipped skill packs for authoring and automation. Host capability matrix and capability / bridge security boundaries. --- ## 02. Installation > Install @native-sdk/cli, platform package layout, prerequisites, and success signals for a working native binary on each host OS. - Page Markdown: https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/02-installation.md - Generated: 2026-07-09T08:18:18.648Z ### Source Files - `README.md` - `packages/native-sdk/README.md` - `packages/native-sdk/scripts/build-binaries.sh` - `packages/native-sdk/npm/darwin-arm64/README.md` - `docs/src/components/home/install-toggle.tsx` --- title: "Installation" description: "Install @native-sdk/cli, platform package layout, prerequisites, and success signals for a working native binary on each host OS." --- `@native-sdk/cli` installs the `native` command as a Node dispatcher plus a per-platform prebuilt binary, and ships the SDK source your apps build against in the same package so `native init` and `native dev` work offline after install. ## Prerequisites | Requirement | Notes | | --- | --- | | **Host OS** | macOS 11+, Linux, or Windows (desktop is the mature surface; mobile targets are experimental) | | **Node.js + npm** | Required for the `native` wrapper (`bin/native.js`); the CLI binary itself is native | | **Optional deps enabled** | Platform binaries ship as `optionalDependencies` — do not install with `--no-optional` / `--omit=optional` | | **Zig 0.16.0+** | Not required before install; resolved on first `native dev\|build\|test` (see [Zig toolchain](#zig-toolchain)) | | **Network (first build)** | macOS/Linux may download the pinned Zig archive from ziglang.org if none is on `PATH` | Canvas-only apps need no system WebView SDK. System WebView / packaging checks are host-specific and surface under `native doctor`: | Host | Extra checks when you need WebView or packaging | | --- | --- | | **macOS** | WKWebView (in-box); `codesign`, `xcrun notarytool`, `hdiutil` for signing/DMG | | **Linux** | GTK4 + WebKitGTK 6.0 (`pkg-config --exists gtk4` / `webkitgtk-6.0`) for system WebView | | **Windows** | WebView2 Evergreen runtime for system WebView | ## Install the CLI ```bash npm install -g @native-sdk/cli ``` ```bash npx skills add vercel-labs/native ``` Installs the discovery skill so agents load version-matched guidance from the installed CLI via `native skills`. You still need `@native-sdk/cli` on the machine for `native` itself. Install runs **no package scripts**. The prebuilt `native` binary arrives as a platform optional dependency (`@native-sdk/cli-` with `preferUnplugged: true`). The main package carries SDK payload (`src/`, `build/`, `build.zig`, `build.zig.zon`, `app.zon`, `skills/`, `skill-data/`). Project-local install also works when you prefer not to global-install: ```bash npm install @native-sdk/cli npx native version ``` ## How the install resolves a binary ```text npm install -g @native-sdk/cli │ ├─► @native-sdk/cli │ bin/native.js # Node dispatcher (PATH entry: `native`) │ src/, build/, … # SDK apps build against │ optionalDependencies # all eight platform packages, exact version pin │ └─► package manager installs exactly one matching: @native-sdk/cli-darwin-arm64 @native-sdk/cli-darwin-x64 @native-sdk/cli-linux-arm64-gnu | -musl @native-sdk/cli-linux-x64-gnu | -musl @native-sdk/cli-win32-arm64 @native-sdk/cli-win32-x64 └── bin/native[.exe] ``` `bin/native.js` picks the platform package, `require.resolve`s `bin/native` (or `bin/native.exe` on Windows), ensures execute bits on Unix, then `spawn`s the binary with your args. | Step | Behavior | | --- | --- | | OS/arch map | `darwin` / `linux` / `win32` × `x64` / `arm64` | | Linux libc | `ldd` / musl loader paths → `gnu` or `musl` package | | Binary lookup | `require.resolve("@native-sdk/cli-/bin/native…")`, then legacy `bin/native-sdk-` for repo-local packs | | SDK path | Sets `NATIVE_SDK_PATH` to the package root when `src/root.zig` is present (user override always wins) | All packages share one version (currently **0.4.0**). `optionalDependencies` pins match that version so a given `@native-sdk/cli` always pairs with the binary built from the same release. ## Platform packages Install `@native-sdk/cli` only. Do not install platform packages directly. | Package | Target | | --- | --- | | `@native-sdk/cli-darwin-arm64` | macOS Apple silicon | | `@native-sdk/cli-darwin-x64` | macOS Intel | | `@native-sdk/cli-linux-arm64-gnu` | Linux arm64 (glibc) | | `@native-sdk/cli-linux-x64-gnu` | Linux x64 (glibc) | | `@native-sdk/cli-linux-arm64-musl` | Linux arm64 (musl) | | `@native-sdk/cli-linux-x64-musl` | Linux x64 (musl) | | `@native-sdk/cli-win32-x64` | Windows x64 | | `@native-sdk/cli-win32-arm64` | Windows ARM | Release engineering also stages flat GitHub assets (`native-sdk-[.exe]` + `CHECKSUMS.txt`) via `packages/native-sdk/scripts/build-binaries.sh` for non-npm distribution. See [Updates and package distribution](/updates-distribution). ## Zig toolchain `native dev`, `native build`, and `native test` resolve Zig before building. Pin: **`0.16.0`** (`src/tooling/toolchain.zig`). | Priority | Source | | --- | --- | | 1 | `NATIVE_SDK_ZIG` (trusted override) | | 2 | `zig` on `PATH` when version is compatible (same major.minor, patch ≥ pin; pre-release/dev builds never match) | | 3 | Managed install at `~/.native/toolchains/zig-0.16.0/zig` | | 4 | Interactive download from ziglang.org (~55 MB, SHA-256 verified) into (3) | ```bash # Non-interactive / CI: consent to managed download without a prompt native dev --yes native build --yes native test --yes ``` Managed download covers **macOS and Linux** (aarch64/x86_64) only. On hosts without a pinned archive (including **Windows**), install Zig 0.16.0+ yourself or set `NATIVE_SDK_ZIG` to a compatible binary. Non-TTY sessions without Zig and without `--yes` refuse the download and print the recovery command. Durable CLI state lives under `~/.native/` (toolchains). Per-app generated build graphs live under `/.native/build/` (gitignored, disposable). ## Environment overrides Absolute or relative path to an SDK/framework root that contains `src/root.zig`. Overrides the package-local SDK (npm wrapper sets this when the package carries source). Use a git checkout when developing against unreleased framework code. Path to a Zig executable. Skips PATH and managed-toolchain resolution. Root for managed toolchains (`$NATIVE_SDK_HOME/toolchains` instead of `~/.native/toolchains`). ## Verify the install ```bash native version ``` Stdout payload (scripts parse this): ```text native 0.4.0 (commit , automation protocol v) ``` `version` / `--version` print version, build commit, and automation protocol on **stdout** so binary/framework skew is a one-command check. ```bash native doctor ``` Default mode is informational (exit 0). Use `--strict` when you want non-zero exit on warnings: ```bash native doctor --strict native doctor --manifest app.zon --strict ``` ```bash native init install_smoke cd install_smoke native dev --yes ``` Success: a native window opens with the scaffolded counter; subsequent runs are incremental. First compile builds the app against the SDK payload and may install Zig. ### Success signals by host | Signal | macOS | Linux | Windows | | --- | --- | --- | --- | | `native version` prints `native (commit …)` | required | required | required | | Platform optional package present | `cli-darwin-*` | `cli-linux-*-gnu` or `*-musl` | `cli-win32-*` | | Zig for builds | PATH, managed `~/.native/toolchains`, or `NATIVE_SDK_ZIG` | same | PATH or `NATIVE_SDK_ZIG` (no managed download) | | Pure canvas window (`native dev`) | Metal/AppKit host | software/real window host | Win32 host | | System WebView doctor check | WKWebView available | WebKitGTK 6.0 + GTK4 | WebView2 registry client present | ## Troubleshooting | Failure | Cause | Fix | | --- | --- | --- | | `No native binary found for -` / `Expected package: @native-sdk/cli-…` | Optional deps omitted, or unsupported arch | Reinstall with optional deps: `npm install -g @native-sdk/cli` (not `--omit=optional`) | | `Unsupported platform: -` | Dispatcher only maps darwin/linux/win32 × x64/arm64 | Use a supported host | | `Cannot make binary executable` | Permission/bit on Unix binary | `chmod +x` on the path printed by the error | | Zig missing in non-TTY / CI | Managed download needs consent | Pass `--yes`, or install Zig 0.16.0 and ensure `zig version` is compatible | | Wrong Zig on PATH | Incompatible major.minor or dev build | Install matching Zig, set `NATIVE_SDK_ZIG`, or let managed install take over on macOS/Linux | | `cannot locate the Native SDK framework` | No `NATIVE_SDK_PATH` and binary cannot walk to `src/root.zig` | Reinstall `@native-sdk/cli` (must include SDK payload) or set `NATIVE_SDK_PATH` to a full checkout | | Linux WebView doctor fails | Missing GTK4 / WebKitGTK 6 | Install distro packages (`libgtk-4-dev`, `libwebkitgtk-6.0-dev` or equivalents); not required for canvas-only apps | | Windows WebView doctor fails | WebView2 runtime missing | Install Evergreen WebView2 Runtime | ## What install does *not* set up - **CEF / Chromium** — optional; use `native cef install` when an app selects the Chromium web engine (see [Web engines](/web-engines)). - **Owned `build.zig`** — zero-config apps need none; `native eject` is optional. - **Agent skill files in the workspace** — `native init` does not copy skills; use `npx skills add` or `native skills get`. - **Frontend node_modules** — only for `--frontend …` scaffolds; installed on first managed frontend run. ## Next Scaffold with `native init`, run `native dev`, and verify the first live window. Full verb list: init, dev, check, test, build, doctor, skills, and failure modes. Discovery install and `native skills list|get` for version-matched agent guidance. Multi-platform npm layout, version sync, and binary release assets. Host capability matrix across macOS, Linux, Windows, and experimental mobile. Toolkit checkout prerequisites (Zig, Node, pnpm) when working on the repository itself. --- ## 03. Quickstart > Create an app with native init, run native dev, edit .native markup and Zig Model/Msg/update, and verify the first live window. - Page Markdown: https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/03-quickstart.md - Generated: 2026-07-09T08:18:07.684Z ### Source Files - `README.md` - `docs/src/app/quick-start/layout.tsx` - `examples/hello/build.zig` - `examples/calculator/README.md` - `src/tooling/dev.zig` --- title: "Quickstart" description: "Create an app with native init, run native dev, edit .native markup and Zig Model/Msg/update, and verify the first live window." --- `native init` scaffolds a zero-config native-rendered app (`app.zon` + `src/` + `assets/`), and `native dev` builds a Debug binary, launches a real OS window, and arms markup hot reload for `src/app.native`. Logic stays in Zig as `Model`, `Msg`, and `update` on `native_sdk.UiApp`; the view is declarative markup that binds and dispatches but never mutates state. ## Prerequisites | Requirement | Notes | | --- | --- | | Host OS | macOS 11+ (primary), Linux, or Windows | | CLI | `@native-sdk/cli` on npm, binary name `native` | | Zig | Optional on PATH; CLI resolves or offers the pinned toolchain (`0.16.0`) under `~/.native/toolchains/` | | Display | A desktop session for `native dev` (headless machines use `native test` / `-Dplatform=null`) | Install and confirm the binary: ```bash npm install -g @native-sdk/cli native version ``` Expected shape: `native 0.4.0 (commit …, automation protocol v…)`. The CLI records the framework path at init (the SDK tree shipped with the npm package, or a checkout that contains `src/root.zig`). Override with `native init … --framework ` or set `NATIVE_SDK_PATH` when running verbs later. ## Create an app ```bash native init my_app cd my_app ``` Flags: | Flag | Values | Default | Effect | | --- | --- | --- | --- | | path | directory | `.` | Destination root for the scaffold | | `--frontend` | `native`, `next`, `vite`, `react`, `svelte`, `vue` | `native` | Native markup app vs WebView frontend shell | | `--framework` | filesystem path | resolved from the `native` binary | SDK root written into full scaffolds / used by the managed graph | | `--full` | boolean | off | Own `build.zig` / `build.zig.zon`, editor settings, CI (native frontend only; web frontends always scaffold full) | Success output: ```text created Native SDK app at my_app (native) Next steps: cd my_app native dev ``` ### Slim scaffold (default, `--frontend native`) No app-owned build files. Verbs synthesize the graph under `.native/build/` (gitignored) and install binaries to `zig-out/`. :::files my_app/ ├── app.zon # identity, shell window, permissions, security ├── assets/ │ └── icon.png # packaging icon source ├── src/ │ ├── app.native # entire UI (markup) │ ├── main.zig # Model, Msg, update, UiApp wiring │ └── tests.zig # full-loop headless UI tests ├── .gitignore # .native/, zig-out/, .zig-cache/ └── README.md ::: ### Full scaffold (`native init my_app --full`) Same app sources plus owned build and tooling: | Extra path | Purpose | | --- | --- | | `build.zig` | Calls `native_sdk.addApp` | | `build.zig.zon` | Path dependency on the framework | | `.vscode/settings.json` | Associates `*.native` with HTML mode | | `.github/workflows/ci.yml` | Null-platform test + Linux smoke pattern | Web frontends (`--frontend next|vite|react|svelte|vue`) always write the expanded shape plus a `frontend/` package and wire `native dev` to the frontend server (see [Frontend projects](/frontend)). ## Run the first window ```bash native dev ``` What runs: 1. Resolve Zig (`NATIVE_SDK_ZIG` → compatible PATH `zig` → managed `~/.native/toolchains/` → optional download with consent, or `--yes`). 2. If no `build.zig`, generate/refresh `.native/build/` against the framework root. 3. `zig build run -Doptimize=Debug` from the app root (or `--build-file` + `--prefix` for the managed graph). 4. Launch the app process group; Ctrl-C tears down the tree so automation-enabled orphans do not linger. Console signal: ```text native dev: building and running my-app (Debug) — hot reload arms in Debug builds ``` The first compile builds the app and the SDK; later runs are incremental. A window opens with the scaffolded counter (480×320, GPU surface canvas `main-canvas`). Click **+** / **−** / **Reset**. The center label and status bar update. That is live `Msg` dispatch through the engine, not a static mock. ### Name and binary `native init my_app` derives package identity in `app.zon` (for example `.name = "my-app"`). Release and install paths use that name: ```text zig-out/bin/my-app ``` ## Authoring surface ### Markup: `src/app.native` Scaffold view (bindings and message tags only — no mutation): ```html Counter {count} count: {count} ``` | Construct | Role | | --- | --- | | `{count}` | Read-only binding to `Model.count` | | `on-press="increment"` | Dispatches `Msg` tag `increment` | | layout attrs (`gap`, `padding`, `main`, `cross`, `grow`) | Flex layout on engine widgets | ### Logic: `src/main.zig` Core loop written by the scaffold: ```zig pub const Msg = union(enum) { increment, decrement, reset, }; pub const Model = struct { count: i64 = 0, }; pub fn update(model: *Model, msg: Msg) void { switch (msg) { .increment => model.count += 1, .decrement => model.count -= 1, .reset => model.count = 0, } } ``` Wiring (same file): - `pub const app_markup = @embedFile("app.native");` - `const CounterApp = native_sdk.UiApp(Model, Msg);` - `CounterApp.create(…, .{ .update = update, .markup = .{ .source = app_markup, .watch_path = "src/app.native", .io = init.io }, … })` - `runner.runWithOptions(app_state.app(), …)` `update` is the only place model state changes. Markup rebuilds from the model after each message. ```text pointer / keyboard / button │ ▼ Msg tag │ ▼ update(*Model, Msg) ◄── only mutation site │ ▼ rebuild view from Model │ ▼ GPU surface / OS window ``` ## Edit while it runs With `native dev` (Debug) and `.markup.watch_path = "src/app.native"`: 1. Change a label or add a button in `src/app.native`. 2. Save. Within about two seconds the window repaints. 3. Model state (for example `count`) is preserved across reload. 4. Parse failures keep the last good view on screen and surface line/column diagnostics (`app_state.markup_diagnostic`). Hot reload is a Debug-path feature. `native build` defaults to ReleaseFast and does not arm the watcher the same way. Pass an explicit `-Doptimize=…` to `native dev` only if you intentionally override the Debug default (reload will not arm in release-mode binaries). Zig logic changes (`Model` / `Msg` / `update`) require a rebuild — stop and re-run `native dev` (or keep the process cycle short). ## Validate without a full GUI session ### `native check` ```bash native check # optional: native check --strict ``` Collects every `src/**/*.native`, validates markup, validates `app.zon`, and uses `zig-out/model-contract.zon` when present (produced by a successful `native test` / model-contract step) for binding and message-tag checks against real `Model`/`Msg`. Success: ```text checked 1 markup file and app.zon ``` (or `… against the model contract` when the contract artifact is fresh). ### `native test` ```bash native test ``` Runs the scaffolded suite in `src/tests.zig`: builds the markup tree, finds **+** / **−** / **Reset** by text, dispatches `msgForPointer` like the runtime, asserts model values and stable widget ids — headless, no display server. Success ends with a build summary and: ```text native test: passed (test tally in the build summary above) ``` Null platform (CI / headless hosts): ```bash native test -Dplatform=null ``` ## Release binary ```bash native build ``` Default optimize: ReleaseFast. Install location: ```text native build: built zig-out/bin/my-app (ReleaseFast) ``` Package into a host app bundle with packaging tooling after the binary exists (see [Packaging](/packaging)). ## Own the build later | Path | When | | --- | --- | | `native init … --full` | Want `build.zig` from day one | | `native eject` | Zero-config app outgrew the managed graph; writes owned `build.zig` / `build.zig.zon` once, then verbs drive `zig build` without regenerating them | After eject, `native dev|build|test` keep working against your files. ## Verification checklist | Signal | How to confirm | | --- | --- | | CLI installed | `native version` prints version + commit | | Scaffold created | `created Native SDK app at …` and `src/app.native` exists | | Dev build | `native dev: building and running … (Debug)` | | Live window | OS window titled from `display_name` / shell config; counter UI visible | | Interaction | +/-/Reset change `{count}` and status bar | | Hot reload | Edit `app.native` → repaint without losing count | | Markup valid | `native check` → checked N markup files and `app.zon` | | Tests green | `native test` → passed | | Release artifact | `native build` → `zig-out/bin/` | ## Common failures | Symptom | Cause | Fix | | --- | --- | --- | | `no app.zon here` | Wrong cwd | `cd` to the app root or `native dev path/to/app` | | Framework not found | CLI cannot locate SDK | Reinstall `@native-sdk/cli`, run a checkout-built `zig-out/bin/native`, set `NATIVE_SDK_PATH`, or re-init with `--framework` | | Zig missing / wrong version | No compatible toolchain | Accept the managed download, pass `--yes`, or set `NATIVE_SDK_ZIG` | | Hot reload never fires | Release optimize, or no `watch_path` | Use default `native dev` Debug; keep scaffold markup options | | Test / check mismatch after UI edit | `tests.zig` still expects old button labels | Update tests or restore labels | | `native init --help` must not scaffold | Flag discipline | `--help` exits 0 without writing files | ## Optional next shapes | Goal | Command / example | | --- | --- | | Web frontend in a WebView | `native init my_web --frontend next` (or vite/react/svelte/vue) | | Smallest in-repo zero-config app | `examples/habits` (`app.zon` + `src/`, same verb shape) | | Precision markup + plain TEA update | `examples/calculator` (`native dev`, `native test -Dplatform=null`) | | Agent skill packs | `native skills list` → [Agent skills](/agent-skills) | `examples/hello` is a hand-wired WebView shell (`zig build run`), not the default `native init` counter path. ## Next Platform packages, prerequisites, and binary success signals per host OS. Model, Msg, update loop wiring, and hot reload boundaries. Elements, attributes, flex layout, bindings, and LSP diagnostics. Derive-don't-store, dispatch paths, and effects as the side-effect channel. Full-loop UI tests, headless truth drivers, and frame-level checks. init, dev, check, test, build, eject, doctor, and flag surface. --- ## 04. Agent skills > Shipped skill packs for core authoring, Native UI, and automation, including how agents discover and apply them via the CLI. - Page Markdown: https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/04-agent-skills.md - Generated: 2026-07-09T08:16:43.980Z ### Source Files - `skills/native-sdk/SKILL.md` - `skill-data/core/SKILL.md` - `skill-data/native-ui/SKILL.md` - `skill-data/automation/SKILL.md` - `docs/src/app/skills/layout.tsx` --- title: "Agent skills" description: "Shipped skill packs for core authoring, Native UI, and automation, including how agents discover and apply them via the CLI." --- The `@native-sdk/cli` package ships version-matched agent skill packs as `SKILL.md` documents under `skills/` and `skill-data/`. `native skills list` and `native skills get` discover those files next to the installed CLI (or via `NATIVE_SDK_SKILLS_ROOT`), print them to stdout, and optionally append each skill’s `references/` and `templates/` trees with `--full`. Skill content is not copied by `native init`; agents and evals load it explicitly so guidance always matches the toolkit binary on PATH. ## Layout on disk The CLI walks two package-root directories for any file named `SKILL.md`: | Directory | Role | | --- | --- | | `skills/` | Installer-facing discovery stub (`native-sdk`), marked `hidden: true` so it is omitted from `skills list` and `skills get --all` | | `skill-data/` | Full skill packs served to agents: `core`, `native-ui`, `automation` | ```text @native-sdk/cli package root ├── skills/ │ └── native-sdk/SKILL.md # discovery stub (hidden) └── skill-data/ ├── core/ │ ├── SKILL.md │ └── references/ │ ├── project-anatomy.md │ ├── app-model-runtime.md │ ├── frontend-assets.md │ ├── bridge-security-native-capabilities.md │ └── web-engines-packaging-debugging.md ├── native-ui/ │ └── SKILL.md └── automation/ └── SKILL.md ``` Both trees are included in the published npm package (`package.json` `files`: `skill-data`, `skills`). The binary resolves the package root by walking parents of the executable until either directory exists; override with `NATIVE_SDK_SKILLS_ROOT` when the binary and skill trees are not co-located. ### Frontmatter contract Each `SKILL.md` starts with YAML frontmatter. The CLI parses only these keys: | Field | Required | Behavior | | --- | --- | --- | | `name` | yes | Skill identifier for `skills get ` | | `description` | no | Printed as the second column of `skills list` | | `hidden` | no | `true` / `yes` → excluded from list and `--all` | | `allowed-tools` | no | Agent-installer metadata (e.g. discovery stub); ignored by the CLI printer | Missing `name` or invalid frontmatter skips the file during discovery. Skills sort alphabetically by name. ## Install and discovery Two layers keep install thin and content versioned: 1. **One-time agent install** — register the discovery skill with a skills installer: ```bash npx skills add vercel-labs/native ``` That installs the compact `native-sdk` entry point (the hidden stub). It orients the agent and directs it to load deep content from the installed CLI rather than embedding a full snapshot. 2. **Version-matched content** — after `@native-sdk/cli` is on PATH, agents (or humans) pull live packs: ```bash native skills list native skills get core native skills get core --full native skills get native-ui native skills get automation ``` Because deep guidance is always read from the CLI, the agent stays aligned with whatever toolkit version each project uses. Updating `@native-sdk/cli` updates skill text without re-running the skills installer. Skill packs are portable Markdown on disk. Any coding agent that can run shell commands and load a `SKILL.md` path works; nothing in the format assumes a particular model provider, hosted connector, or proprietary skill catalog beyond the optional one-time installer command above. ## CLI surface ### Commands ```bash native skills list native skills get [--full] native skills get --all [--full] native skills --help ``` | Command | Output | Notes | | --- | --- | --- | | `skills list` | `name\tdescription` per visible skill | Hidden skills omitted | | `skills get ` | Full `SKILL.md` body on stdout | Includes frontmatter | | `skills get --full` | `SKILL.md` plus every file under `references/` and `templates/` | Each supplementary file is separated with `---` and a `# references/…` or `# templates/…` heading | | `skills get --all [--full]` | All non-hidden skills concatenated | Skills separated by `\n---\n\n` | | unknown name | stderr `Unknown skill: …`, exit 1 | Does not list available names in the error | | no package root | stderr `native skills: could not find skills/ or skill-data/ near the native-sdk executable`, exit 1 | Fix install layout or set `NATIVE_SDK_SKILLS_ROOT` | ### Environment Absolute path to a directory that contains `skills/` and/or `skill-data/`. Checked first, before walking parents of the executable path. ### Deliver a skill into an agent workspace `skills get` is stdout-only, so delivery is a redirect into wherever the agent loads skills: ```bash mkdir -p .claude/skills/native-ui native skills get native-ui > .claude/skills/native-ui/SKILL.md ``` For implementation work that needs core references: ```bash mkdir -p .claude/skills/core native skills get core --full > .claude/skills/core/SKILL.md ``` `native init` does **not** copy skills into the app. Delivery is always explicit so the workspace skill is exactly what the installed CLI serves. The repository eval harness uses the same path: after `native init … --frontend native`, it runs `native skills get native-ui` and writes the stdout into `.claude/skills/native-ui/SKILL.md` before the agent-under-test runs. ## Shipped skill packs | Name | Path | Hidden | `--full` extras | Load when | | --- | --- | --- | --- | --- | | `native-sdk` | `skills/native-sdk/` | yes | none | Installer discovery only; not listed by default | | `core` | `skill-data/core/` | no | five `references/*.md` files | Orienting, scaffolding, `app.zon`, WebView shells, bridge, packaging, debug | | `native-ui` | `skill-data/native-ui/` | no | none today | Authoring `.native` views, `Model`/`Msg`/`update`, `UiApp`, markup testing | | `automation` | `skill-data/automation/` | no | none today | Live app inspection, `native automate *`, smoke tests, screenshots | ### `core` Shared foundation for both native-rendered and WebView-shell apps: - Mental model: `App`, `Runtime`, `WebViewSource`, `app.zon`, `src/main.zig` vs `src/runner.zig` - Task router into `--full` references - Frontend frameworks (`next`, `vite`, `react`, `svelte`, `vue`), bridge commands, security defaults - Package / doctor / validate command checklist `--full` appends, in walk order under `references/`: | Reference | Use for | | --- | --- | | `project-anatomy.md` | Generated files, build steps, project shape | | `app-model-runtime.md` | `App` / `Runtime` callbacks, embedding, tests | | `frontend-assets.md` | Dev server, HMR, bundled assets | | `bridge-security-native-capabilities.md` | Bridge handlers, permissions, windows, dialogs | | `web-engines-packaging-debugging.md` | System WebView vs CEF, package, doctor, logs | For native-rendered UI authoring, `core` explicitly routes agents to `native skills get native-ui`. For running-app inspection, it routes to `automation`. ### `native-ui` Authoring surface for native-rendered apps: declarative `.native` markup plus Zig `Model` / `Msg` / `update` on `native_sdk.UiApp`. Covers: - App wiring (`UiApp.create`, markup watch / compiled markup, web panes, status items) - Element and attribute catalog, flex layout, identity keys, token attributes - Expression grammar, binding resolution, derive-don’t-store model methods - Message dispatch, text-field mirror pattern, effects channel (`spawn` / `fetch` / file / clipboard / timer / audio) - Secondary windows, hidden titlebar chrome, images, templates/imports, markdown, charts - `native markup check`, unit testing via `msgFor*`, and live verification through automation Editors treat `.native` as HTML for highlighting; `native init --full` can write the VS Code association. ### `automation` File-based IPC automation every Native SDK app can embed (native-rendered and WebView shells). Covers: - Prerequisites: build/run with `-Dautomation=true`, pass `automation.Server` into `RuntimeOptions` - Commands: `wait`, `assert`, `list`, `snapshot`, `reload`, `screenshot`, widget drive verbs, `bridge`, `profile`, tray actions - Protocol dir `.zig-cache/native-sdk-automation/` (cwd-relative; CLI never creates it) - What is in scope (widgets, bridge, readiness, deterministic `gpu_surface` screenshots) and out of scope (WebView DOM / WebView pixels) - Smoke-test and CI patterns, protocol mismatch and stale-instance debugging ## Recommended agent workflow ```mermaid flowchart TD install["npx skills add vercel-labs/native\n+ npm install -g @native-sdk/cli"] list["native skills list"] core["native skills get core\n(+ --full for implement)"] branch{Task shape} ui["native skills get native-ui"] auto["native skills get automation"] build["native check / test / build / dev"] verify["native automate wait\nautomate assert / snapshot / screenshot"] install --> list --> core --> branch branch -->|markup Model Msg UiApp| ui --> build branch -->|WebView bridge package| build branch -->|live window / smoke| auto --> verify build --> verify ``` Install the CLI (`npm install -g @native-sdk/cli`) and, for agent hosts that use a skills installer, run `npx skills add vercel-labs/native`. Confirm with `native version` and `native skills list` (expect `automation`, `core`, `native-ui`). Run `native skills get core` before explaining or changing an app. For implementation, use `native skills get core --full` so project anatomy, runtime, frontend, bridge, and packaging references are in the same stream. Native UI authoring → `native skills get native-ui`. Live verification → `native skills get automation`. Write stdout into the agent’s skills directory when the host only auto-loads on-disk skills. Follow skill ownership: `app.zon` for manifest/policy, `src/main.zig` for app behavior / Model-Msg-update, `src/runner.zig` for runtime wiring, `src/*.native` for markup views, `frontend/` for web shells. Prefer `native check` / `native test` / headless unit paths first. For GUI confidence, build with `-Dautomation=true`, run the app, then `native automate wait` and `native automate assert` from the app cwd. ## Failure modes | Symptom | Likely cause | Fix | | --- | --- | --- | | `could not find skills/ or skill-data/` | Broken package layout or binary moved without skill trees | Reinstall `@native-sdk/cli`, or set `NATIVE_SDK_SKILLS_ROOT` to the package root that contains those dirs | | `Unknown skill: …` | Typo or requesting the hidden discovery name via list-only habits | Run `native skills list`; use `core`, `native-ui`, or `automation`. `native-sdk` exists but is hidden | | Empty `skills list` | No parseable `SKILL.md` under the resolved root | Confirm frontmatter `name:` fields and that root points at a real package | | Stale guidance vs runtime APIs | Workspace skill snapshot older than CLI | Re-run `native skills get ` (and `--full` if used) from the current binary | | Automation commands fail after skill-guided build | App not automation-enabled or wrong cwd | Build with `-Dautomation=true`, launch from the app directory, re-read the automation skill | | Agent invents layout / APIs | Skipped skills, relied on model memory | Skills themselves instruct agents to assume zero prior Native SDK knowledge and read the pack first | ## Constraints and design notes - **Version coupling** — skill Markdown ships inside `@native-sdk/cli` next to the Zig framework sources. Skills and binary move together on npm. - **No init embedding** — scaffolds stay skill-free; evals and agents inject skills deliberately. - **Hidden discovery skill** — `native-sdk` is for installer catalogs (`allowed-tools` allows `native:*` and `npx @native-sdk/cli:*`). Day-to-day agent work uses the three visible packs. - **`--full` is append-only** — supplementary files are concatenated after `SKILL.md`; only `core` currently ships `references/`. Empty `templates/` directories are skipped. - **Not a model-provider lock-in** — packs are plain files + CLI stdout. Hosts may load them as Claude-style skills, generic system context, or custom catalogs. ## Related pages Full `native` command surface, including `skills`, `automate`, `check`, and `dev`. Product docs for the markup and UiApp surface the `native-ui` skill teaches. Embedded automation server, snapshots, widget driving, and screenshots. Model, Msg, update loop wiring shared by skill guidance and runtime. Scaffold with `native init`, run `native dev`, and verify the first window. Headless UI tests and when to escalate from unit paths to automation. --- ## 05. App model > Model, Msg, and update loop wiring, hot reload boundaries, and how markup binds values without mutating state. - Page Markdown: https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/05-app-model.md - Generated: 2026-07-09T08:19:07.046Z ### Source Files - `skill-data/core/references/app-model-runtime.md` - `src/runtime/core.zig` - `src/runtime/flow.zig` - `src/runtime/api.zig` - `build/app.zig` --- title: "App model" description: "Model, Msg, and update loop wiring, hot reload boundaries, and how markup binds values without mutating state." --- `native_sdk.UiApp(Model, Msg)` (and `UiAppWithFeatures`) owns the declarative canvas loop: a heap-resident `Model`, a tagged-union `Msg`, exactly one of `update` / `update_fx`, and a view from either a Zig builder (`Options.view`) or runtime-parsed `.native` markup (`Options.markup`). It implements `native_sdk.App` via `app()`, drives install / rebuild / typed dispatch on `Runtime`, and keeps side effects on the effects channel — not in the view. ## Loop shape | Piece | Type / surface | Role | | --- | --- | --- | | **Model** | Plain Zig struct | All app state. Fields used with `create` need defaults. | | **Msg** | `union(enum)` | Every event that can change state (press, input, command, effect result, chrome, …). | | **update** | `fn (*Model, Msg) void` **or** `update_fx` | Sole state mutation path. Exactly one of the two is set. | | **View** | `view` and/or `markup` | Derives `canvas.Ui(Msg)` nodes from `*const Model`. Never mutates the model. | Runtime owns window creation, GPU presentation, resize, pointer/keyboard dispatch through the tree handler table, timers, accessibility, and markup watch polling. Input hits a widget → bound `Msg` → `applyMsg` → rebuild → repaint. ```mermaid flowchart LR subgraph inputs [Input and host] Ptr[Pointer / keyboard] Cmd[Menus / shortcuts / tray] Fx[Effect completions] Watch[Markup watch timer] end subgraph uiapp [UiApp] Disp["dispatch / drainEffects"] Upd["update / update_fx"] Model[(Model)] Build["buildViewNode"] Tree["Ui.Tree + handler table"] end subgraph runtime [Runtime] Layout[layout + reconcile] Present[GPU / pixels] end Ptr --> Disp Cmd --> Disp Fx --> Disp Watch --> Build Disp --> Upd --> Model Model --> Build --> Tree --> Layout --> Present ``` ## Wiring `Options` asserts at init: - At least one of `view` or `markup`. - Exactly one of `update` or `update_fx`. - If `windows_fn` is set, `window_view` is required. - If `UiAppFeatures.runtime_markup` is `false`, `markup` must be null. Construction paths: | API | Model lifecycle | | --- | --- | | `UiApp.init(allocator, model, options)` | Caller supplies the initial model value. | | `UiApp.create(allocator, options)` | Allocates the multi-MB app on the heap; model starts as `.{}` (every field needs a default); assign boot state through the pointer, then `destroy`. | | `initInPlace` | Builds everything except the model; assign `app.model` immediately after. | `app()` returns `native_sdk.App` with `scene_fn`, `event_fn`, `stop_fn`, and `replay_fn`. Stop tears down the effects channel while the platform is still alive; main’s deferred `deinit` only frees app memory afterward. ```zig const dev = @import("builtin").mode == .Debug; const App = native_sdk.UiAppWithFeatures(Model, Msg, .{ .runtime_markup = dev }); const Compiled = canvas.CompiledMarkupView(Model, Msg, @embedFile("app.native")); const app_state = try App.create(std.heap.page_allocator, .{ .name = "my_app", .scene = shell_scene, // one window, one gpu_surface .canvas_label = "main-canvas", // must match the surface view label .update = update, .view = Compiled.build, .markup = if (dev) .{ .source = @embedFile("app.native"), .watch_path = "src/app.native", .io = init.io, } else null, }); defer app_state.destroy(); // optional boot: app_state.model.count = 0; try runner.runWithOptions(app_state.app(), .{ ... }, init); ``` Live reference: `examples/ui-inbox` (markup + Zig model), `examples/notes` (`init_fx`, commands, tokens), `examples/split-collapse` (layout tweens / hybrid view). ### Common `Options` fields App name for traces and automation snapshots. Shell windows and views; canvas apps use a `gpu_surface` whose label equals `canvas_label`. Primary canvas view label for install, rebuild, and input routing. Pure update. Mutually exclusive with `update_fx`. Effects-capable update; spawn/cancel only from update arms, never from the view. Runs exactly once on the installing frame, after the effects channel is bound and before the first view build. Zig builder or `CompiledMarkupView(...).build`. Used alone in release, or until watched markup diverges when both `view` and `markup` are set. Runtime parser/interpreter: `source`, optional `sources` import closure, optional `watch_path` + `io` for Debug hot reload. Maps shell command events (menu, shortcut, tray, toolbar, bridge) into messages. Hidden-inset titlebar overlay geometry into the model (traffic-light insets, band height). Model-declared secondary windows; presence is visibility. Pair with `window_view`. Cap: `max_ui_windows`. ## Dispatch and rebuild `dispatch(runtime, window_id, msg)`: 1. Binds the effects channel. 2. Optional `sync` reads runtime-owned layout state into the model. 3. `applyMsg` runs `update` or `update_fx`. 4. If not yet installed, returns without rebuilding (appearance/chrome can land pre-frame). 5. Rebuilds the main canvas tree and secondary window slots. Effect completions drain on `.effects_wake` and each presented frame: each queued result becomes a `Msg`, then a single rebuild if any ran. Input mapping goes through the retained tree (`msgForPointerClick`, `msgForTextEdit`, `msgForKeyboard`, `msgForScroll`, `msgForDismiss`, `msgForResize`, `msgForChange`, `msgForContextMenu`, …). Optimistic runtime echoes (slider value, dismiss hide, text clear) apply immediately; the model owns the value after the mapped `Msg` and the next rebuild is source of truth. Rebuild uses a two-arena swap: the previous tree’s arena stays alive until the following rebuild so the handler table remains valid between events. Virtual lists may do a second build pass in the same rebuild when window coverage is under-guessed. ## Markup binds values; it never mutates state `.native` files are compiled (comptime or runtime) into the same `canvas.Ui(Msg)` tree a hand-written `view` would build: structural ids, flex layout, typed handlers. | Markup form | Meaning | | --- | --- | | `{count}`, `{t.title}`, `{draft}` | Read model (or loop-item) fields / methods into attributes or text. | | `on-press="increment"` | Names a unit `Msg` variant. | | `on-press="set_filter:{f}"` | Payload variant with bound expression. | | `on-input="draft_edit"` | Text edits map to a `Msg` carrying `TextInputEvent`; the model applies them. | | `on-toggle="toggle:{t.id}"` | Control change → message with id payload. | | `selected="{f == filter}"`, `checked="{t.done}"` | Controlled display from model; engine state survives until the model asserts a different value. | | `key="id"` on `` | Stable structural identity across reorder/filter. | Markup cannot assign to the model. Every mutation is a named `Msg` handled in `update`. Variants never bound from markup can declare `pub const view_unbound = .{"chrome_changed"}` so dead-state lint skips them. ```html {t.title} ``` ## Hot reload boundaries | Mode | Mechanism | What reloads | What is preserved | | --- | --- | --- | --- | | **Root markup watch** | `Options.markup.watch_path` + `io`; Debug + `runtime_markup` | Watched file and its import closure via timer poll | Model state; last good view on parse failure | | **Fragment watch** | `fragment_watch` with `CompiledX.fragment("path")` | Registered fragment closures (budget `max_watched_fragments` = 16) | Same degrade family; revert-to-baseline restores compiled path | | **Release / non-Debug** | Watch machinery compiles out | Nothing on disk | Comptime `CompiledMarkupView` only | When both `view` and `markup` are set, the compiled view runs until the watched file first diverges from the embedded baseline; then the interpreter takes over. Failed parses keep the last good document, set `app_state.markup_diagnostic` (line, column, message), and avoid teaching the same bad save every poll (hash-gated). Successful reload rebuilds without resetting the model. Zig logic (`Model`, `Msg`, `update`) is not hot-reloaded — only markup sources under watch. Mobile embed uses the compiled view; markup hot reload is desktop Debug. ## Dev vs release engines ```zig const dev_markup_reload = builtin.mode == .Debug; const App = native_sdk.UiAppWithFeatures(Model, Msg, .{ .runtime_markup = dev_markup_reload, }); ``` | Build | View path | Parser in binary | | --- | --- | --- | | Debug with `markup` + `watch_path` | Runtime interpreter after first disk divergence | Yes | | Release with `CompiledMarkupView.build` | Comptime-compiled builder | No (`runtime_markup = false`) | Both engines produce the same structural ids and handler table so tests, automation, and goldens hold across modes. Hybrid roots compose fragments as ordinary children: `CompiledHeaderView.build(ui, model)` inside a Zig `rootView` (see `examples/calculator`, `examples/notes`). ## Effects and purity `update` stays free of async I/O. With `update_fx` / `init_fx`, use `Effects` (`fx.spawn`, `fx.fetch`, `fx.readFile` / `writeFile`, `fx.startTimer`, `fx.cancel`, audio helpers). Completions re-enter as ordinary `Msg`s. Views never spawn effects. Boot work belongs in `init_fx` (once, pre-first paint), not a guarded `on_frame`. See [Runtime and effects](/runtime-effects) and [State and data flow](/state-data-flow). ## Rebuild identity and controlled state - **Structural identity**: widget ids survive rebuilds, reorders, and hot reloads. List items use `key` (or `global-key` across containers). Unkeyed same-kind siblings use positional identity — an `` that inserts earlier siblings can re-disambiguate trailing ones. - **Source wins**: engine-retained scroll/caret/focus survive until the model asserts a different controlled value; then the model applies. - **Windows**: `windows_fn` presence is visibility; user close dispatches `on_close`; keeping the window in the declared set re-creates it on the next rebuild. ## Lower-level `App` / `Runtime` `UiApp` is a layer over `App` + `Runtime` (`src/runtime/api.zig`, `flow.zig`, `core.zig`). WebView-first apps return `native_sdk.App` with `source` / `source_fn` / lifecycle hooks without a Model/Msg loop (e.g. `examples/hello`). Embed hosts pump frames through the mobile C ABI (`build/app.zig` `addMobileLib`, `native_sdk_app_*` symbols). Custom lifecycle, imperative windows, or bridge-heavy shells use the runtime surface directly. ## Constraints and failure modes | Constraint / signal | Behavior | | --- | --- | | `create` without Model field defaults | Comptime error naming the field. | | Both or neither of `update` / `update_fx` | Assert at `assertOptions`. | | Markup parse error under watch | Last good view kept; `markup_diagnostic` set. | | Fragment count > 16 | Extra fragments stay compiled-only (warning). | | Pre-install `dispatch` | Model updates; no rebuild until first GPU frame install. | | Platform stop | `stop_fn` deinit effects while services are live. | ## Next Derive-don’t-store, message dispatch paths, text editing, and effects as the only side-effect channel. Elements, attributes, flex layout, bindings, expressions, and LSP support for `.native` views. Effect kinds, cancellation, worker wakes, and frame limits behind `update_fx`. `native init` / `native dev` scaffold: first Model, Msg, update, and live window. Shell scenes, multi-window reconciliation, and GPU surface presentation. C embed ABI and host-driven frames for the same UiApp model on mobile. --- ## 06. Native UI markup > Elements, attributes, flex layout, bindings, expressions, and editor/LSP support for .native views compiled into the binary. - Page Markdown: https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/pages/06-native-ui-markup.md - Generated: 2026-07-09T08:16:54.234Z ### Source Files - `skill-data/native-ui/SKILL.md` - `editors/native-markup/README.md` - `editors/native-markup/extension.js` - `src/runtime/canvas_widget_runtime.zig` - `docs/src/app/native-ui/layout.tsx` --- title: "Native UI markup" description: "Elements, attributes, flex layout, bindings, expressions, and editor/LSP support for .native views compiled into the binary." --- `.native` files declare the entire canvas widget tree for a native-rendered app: elements, flex layout, value bindings, message dispatch, and structure tags. At build time the source is either interpreted at runtime (`canvas.MarkupView`) or compiled at comptime (`canvas.CompiledMarkupView` / `CompiledMarkupImports`) into the same `canvas.Ui(Msg)` nodes a hand-written Zig builder would emit—identical structural widget ids and the same typed handler table. Markup never mutates state; it only reads the `Model` and dispatches `Msg` values. Logic lives in Zig (`update` / `update_fx`). ```text src/.native ──parse──► MarkupDocument │ │ │ ┌──────────┴──────────┐ │ ▼ ▼ │ MarkupView (dev/hot reload) CompiledMarkupView (release) │ │ │ └──────────────┴─────────► Ui(Msg).Tree ──► canvas_widget_runtime reconcile ``` ## App wiring A native UI app is markup plus TEA-shaped Zig: | Piece | Role | | --- | --- | | `src/.native` | View: elements, layout, bindings, `on-*` dispatch | | `Model` | Plain struct; only source-of-truth fields | | `Msg` | Tagged union of events | | `update` / `update_fx` | Sole place state changes | Wire the view through `native_sdk.UiApp` / `UiAppWithFeatures`. Release builds prefer comptime compilation and gate the interpreter with `.runtime_markup`: ```zig const dev = @import("builtin").mode == .Debug; const App = native_sdk.UiAppWithFeatures(Model, Msg, .{ .runtime_markup = dev }); const CompiledView = canvas.CompiledMarkupView(Model, Msg, @embedFile("habits.native")); // Options: .view = CompiledView.build, .markup = if (dev) .{ .source = @embedFile("habits.native"), .watch_path = "src/habits.native", .io = init.io, } else null, ``` Embedded root markup bytes. Baseline for the first build and for watch comparison. Import closure for multi-file documents (same set as `CompiledMarkupImports`). Paths are relative to the root file's directory. Dev-only disk path to poll. When the root or any resolved import changes, the next rebuild swaps the view while preserving model state and widget ids. Omit in release. Required when `watch_path` is set so the runtime can read files on the watch timer. With both `.view` (compiled) and `.markup` (watched) in Debug, the compiled tree renders until the watched file first changes, then the interpreter hot-reloads. Parse failures keep the last good view and set `app_state.markup_diagnostic` (path, line, column, message). Hybrid Zig roots that embed compiled fragments register each with `Options.fragment_watch` via `CompiledView.fragment("src/header.native")`—only Debug carries path/baseline data. Reference app: `examples/habits` (`habits.native` + `CompiledHabitsView` + optional `watch_path`). ## Elements Markup tags lower to canvas widget kinds. Structure tags (`for`, `if`, `else`, `template`, `use`, `import`, `slot`) are not widgets. | Markup | Widget role | Notes | | --- | --- | --- | | `row`, `column` | Flex containers | Main axis horizontal / vertical | | `stack`, `panel`, `card` | Overlay containers | Children layer; `gap` is a validation error | | `scroll` | Scroll view | Put multi-child content in an inner `column`/`row` | | `list`, `grid` | List / grid | Vertical stack / cell grid; `columns` on `grid` only | | `tabs`, `toggle-group`, `button-group`, `radio-group`, `breadcrumb`, `pagination` | Horizontal row containers | Tab strips, chips, radios | | `table` → `table-row` → `table-cell` | Table | Strict nesting; cells are text leaves | | `dropdown-menu` | Menu surface | Children are `menu-item`s; `anchor` floats against parent | | `accordion` | Accordion | Header via `text`; children while `selected` | | `alert`, `bubble` | Surfaces | `alert` title via `text`; bubble message is content, not `text=` | | `dialog`, `drawer`, `sheet` | Modal surfaces | In-place; show with `` | | `resizable` | Resizable panel | Engine drag handle; `width` is initial | | `split` | Two-pane splitter | Exactly two element children; engine divider; `value` + `on-resize` | | `tree` | Disclosure tree | Rows with `role="treeitem"` join one roving focus set | | `text`, `badge`, `tooltip` | Text leaves | `{}` interpolation; `wrap` / `overflow` / `size` on `text` | | `text` → `span` | Inline runs | Weight, mono, italic, scale, underline, foreground | | `button`, `toggle-button`, `list-item`, `menu-item`, `toggle`, `switch`, `select`, `avatar` | Text-bearing controls | Label is content; optional `icon=` on several | | `checkbox`, `radio`, `slider`, `progress` | Value controls | Labels via `text=` / `label=`; content text is an error | | `text-field`, `input`, `search-field`, `combobox`, `textarea` | Text entry | `on-input` / `on-submit`; search-field has built-in clear | | `status-bar` | Status bar | Content only | | `separator`, `spacer` | Divider / flex space | Separator axis follows parent flex direction | | `skeleton`, `spinner` | Loading leaves | Size skeleton with `width`/`height` | | `icon` | Vector icon | Built-in name, `app:`, or one `{binding}` | | `markdown` | Markdown subtree | `source="{binding}"` only | | `stepper` → `step`, `timeline` → `timeline-item` | Pipeline composites | Stage track / ledger list | | `chart` → `series` | Data chart | `values="{binding}"` to `[]const f32` | | `context-menu` | Parent metadata | Direct child of pressable parent; not flow content | | `input-group` → `textarea` + `input-group-actions` | Grouped composer | One border; group owns focus ring | **Not expressible in markup** (Zig `canvas.Ui` only): free-form `image` widgets (pixels are runtime `ImageId`s), `data_grid`, `popover` / `menu_surface`, `segmented_control` (use `tabs`/`toggle-group`), windowed virtual lists (`ui.virtualWindow` / `ui.virtualList`), `on_double_press`, and dynamic chart series composition / `.band` series. Avatars do bind images: `image="{binding}"` to a model `u64` ImageId (`0` keeps initials). ## Flex layout and attributes ### Layout attributes | Attribute | Applies to | Behavior | | --- | --- | --- | | `gap` | Flow containers; `split` divider thickness | Invalid on stacking kinds (`stack`/`panel`/`card`/`alert`/`bubble`/`dialog`/`drawer`/`sheet`/`resizable`) | | `padding` | Most containers | Uniform inset | | `grow` | Flex children | Share free space on the main axis | | `width`, `height` | Sized elements | Definite size; content neither shrinks nor silently overflows | | `min-width` | Flex children; split panes | Floor without a definite max; bounds split drag | | `main` | Flex containers | `start` \| `center` \| `end` \| `space_between` | | `cross` | Flex containers | `stretch` \| `start` \| `center` \| `end` | | `wrap` | `text` only | `"true"` word-wraps; unset/`false` is single-line | | `overflow` | `text` only | `ellipsis` (default) or `clip` | | `text-alignment` | Text leaves, titles | `start` \| `center` \| `end` | | `columns` | `grid` only | Fixed column count | | `virtualized`, `virtual-item-extent` | `scroll`/`list`/`grid`/`table` | Layout-culls mounted nodes (not full windowed virtual lists) | | `anchor`, `anchor-alignment`, `anchor-offset` | `dropdown-menu` | Float against parent; late z-pass; window-clipped | | `overscroll` | `scroll` only | `none` (default pin) or `rubber_band` | | `window-drag` | Any element | macOS hidden-titlebar window move surface | Numbers are plain (`gap="12"`). Booleans are `true`/`false` or a binding. When children's minimum sizes exceed a container, debug builds log `zero_canvas_layout` with container, axis, and overflow pixels—flex overflow is never silent. ### Appearance and state Token attributes take **token names only** (no raw colors, no bindings): `background`, `foreground`, `accent`, `accent-foreground`, `border-color`, `focus-ring`, `radius` (`sm`/`md`/`lg`/`xl`). Names resolve against live design tokens on every rebuild (`finalizeWithTokens`). Other common attributes: `variant`, `size` (control scale `default`/`sm`/`lg`/`icon`; on `text` also typography `heading`/`display`), `disabled`, `checked`, `selected`, `value`, `placeholder`, `icon`, `autofocus`, `role`, `label`, `expanded`, `key`, `global-key`. ### Identity | Attribute | Scope | | --- | --- | | `key` | Sibling-scoped identity | | `global-key` | Parent-independent identity (items that move between containers) | Unkeyed same-kind siblings use positional identity; insert/remove earlier siblings can re-disambiguate trailing ones and hop engine-owned state (carets, scroll). Prefer keys on list rows. ## Structure tags ```html … Nothing yet … … ``` - ``: one or more children; `key` names an item field; every node an item emits shares that identity. - `` after ``: empty iterable state. - `` after ``: must immediately follow; nest for multi-branch (no `else-if` tag). - Templates: top-of-file `