# Overview

> What Native SDK exposes, who should use it, runtime assumptions, and the first docs routes from install to a running window.

- Repository: vercel-labs/native
- GitHub: https://github.com/vercel-labs/native
- Human docs: https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a
- Complete Markdown: https://grok-wiki.com/public/docs/vercel-labs-native-8ccc3580636a/llms-full.txt

## 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 <version> (commit <hash>, automation protocol v<n>)`.

| Package | Contents |
| --- | --- |
| `@native-sdk/cli` | `bin/native.js`, SDK sources (`src/`, `build/`, `build.zig*`, `app.zon`), `skills/`, `skill-data/` |
| `@native-sdk/cli-<platform>` | 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

<Steps>
  <Step title="Install the CLI">
    `npm install -g @native-sdk/cli` then `native version`. Confirm the binary resolves and prints version + automation protocol.
  </Step>
  <Step title="Scaffold">
    `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.
  </Step>
  <Step title="Run">
    `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`.
  </Step>
  <Step title="Verify">
    `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/<app-name>` (ReleaseFast).
  </Step>
</Steps>

### 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
<!-- src/app.native — binds and dispatches; never mutates -->
<button variant="secondary" on-press="decrement">-</button>
<text>{count}</text>
<button variant="primary" on-press="increment">+</button>
```

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

<CardGroup>
  <Card title="Installation" href="/installation">
    Install `@native-sdk/cli`, platform package layout, prerequisites, and success signals per host OS.
  </Card>
  <Card title="Quickstart" href="/quickstart">
    `native init`, `native dev`, edit markup and Zig, verify the first live window.
  </Card>
  <Card title="App model" href="/app-model">
    Model, Msg, update loop, hot reload boundaries, and markup binding rules.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    Full command list: init, dev, check, test, build, automate, doctor, skills.
  </Card>
  <Card title="Agent skills" href="/agent-skills">
    Discover and apply shipped skill packs for authoring and automation.
  </Card>
  <Card title="Platform support and security" href="/platform-security">
    Host capability matrix and capability / bridge security boundaries.
  </Card>
</CardGroup>