# Native SDK documentation > Build native desktop applications with TypeScript and Native markup. Native SDK provides a native renderer, components, app state, and development tools. ## When to use Native SDK - Category: Application framework Common use cases: - Build native desktop apps with TypeScript and Native markup - Look up Native markup components and platform support - Test and automate native apps ## Documentation --- title: App Model url: "https://native-sdk.dev/docs/app-model" docs_index: /llms.txt lastUpdated: 2026-10-16 --- > For an index of all documentation, see [/llms.txt](/llms.txt). A Native SDK app is one loop with four parts: - **Model** — a plain data structure holding all app state. - **Msg** — a tagged union of everything that can happen. - **update(model, msg)** — the only place state changes. - **View** — a Native markup file (`.native`, or a Zig view function) that derives the UI from the model. The runtime manages windows, rendering, input dispatch, timers, accessibility, and hot reload. A widget dispatches its bound message to `update`; the runtime then derives the view from the committed model and renders the changes. Both TypeScript and Zig cores use this loop. The default project has `src/core.ts`, compiled to native code at build time. A `zig-core` project has `src/main.zig`. The wiring sections below show the runtime setup that the build generates for TypeScript apps and that a Zig app can configure directly. See [TypeScript Cores](/docs/typescript) for the TypeScript contract. ## The loop in full A minimal counter declares state, messages, and a pure `update`: ```ts title="src/core.ts" export interface Model { readonly count: number; } export type Msg = | { readonly kind: "increment" } | { readonly kind: "decrement" } | { readonly kind: "reset" }; export function initialModel(): Model { return { count: 0 }; } export function update(model: Model, msg: Msg): Model { switch (msg.kind) { case "increment": return { ...model, count: model.count + 1 }; case "decrement": return { ...model, count: model.count - 1 }; case "reset": return { ...model, count: 0 }; } } ``` ```zig title="src/main.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, } } ``` The view in `src/app.native` binds the model and names the messages: ```html {count} ``` Markup can never mutate state. `{count}` is a read; `on-press="increment"` names a `Msg` variant (in a TypeScript core, the arm's `kind`). Every state change flows through `update`, which makes the app's behavior testable as a plain function — the Zig template's generated `src/tests.zig` drives it with no GUI at all, and a TypeScript core runs under node the same way (`native dev --core`). ## Wiring `native_sdk.UiApp(Model, Msg)` ties the loop to the runtime. A zero-config app never writes this — the build graph generates it (for a TypeScript core, over the compiled core's model) — but it is ordinary code you can own any time. From the Zig template's `main`: ```zig const CounterApp = native_sdk.UiApp(Model, Msg); pub fn main(init: std.process.Init) !void { // `create` heap-allocates the multi-MB app struct and constructs the // Model in place — neither ever rides the stack. const app_state = try CounterApp.create(std.heap.page_allocator, .{ .name = "my_app", .scene = shell_scene, // one window, one gpu_surface view .canvas_label = "main-canvas", // must match the scene's view label .update_fx = update, // update(model, msg, fx) - or .update for a pure app .markup = .{ .source = app_markup, .watch_path = "src/app.native", .io = init.io }, }); defer app_state.destroy(); app_state.model = initialModel(); // boot state: assign through the pointer try runner.runWithOptions(app_state.app(), .{ ... }, init); } ``` `create` requires every `Model` field to carry a default; the model starts as `.{}` and boot state is assigned through the returned pointer. The `scene` declares the native window and its GPU surface view — see [Windows](/docs/windows) and [Native Surfaces](/docs/native-surfaces) for multi-view scenes. ## Rebuilds and widget identity After `update`, the runtime derives the view from the committed model. Reconciliation follows these rules: - **Widget identity is structural.** A widget keeps its id across rebuilds, reorders, and hot reloads, so engine-owned state — scroll offsets, text carets, focus — survives. List items carry `key` (or `global-key` for items that move between containers) to keep identity through reorders. Unkeyed same-kind siblings take positional identity (sibling index), so an `` that inserts or removes an earlier same-kind sibling re-disambiguates the trailing ones — engine-owned state like carets and scroll can hop; keyed items and keyed ancestors hold identity. - **The source wins.** Engine-retained state (a scroll offset, a toggle) survives rebuilds until the model asserts a different value; then the model's value applies. This is why controlled patterns echo runtime-applied values back through the model — see [State & Data Flow](/docs/state). - **Update errors are recorded.** A returned `update` error is caught and recorded in a bounded error ring (visible in [automation](/docs/automation) snapshots as `dispatch_errors=`), and the app keeps running. ## Hot reload in development With `watch_path` set, the runtime watches the `.native` file while the app runs. Edits preserve model state and widget identity. Parse failures keep the last good view on screen and record a diagnostic (`app_state.markup_diagnostic` carries line, column, and message). ## Compile the markup for release In release builds the markup compiles at comptime — no parser in the binary, and markup or binding mistakes become compile errors with line and column: ```zig const dev = @import("builtin").mode == .Debug; const App = native_sdk.UiAppWithFeatures(Model, Msg, .{ .runtime_markup = dev }); const CompiledView = canvas.CompiledMarkupView(Model, Msg, @embedFile("app.native")); // options: .view = CompiledView.build, .markup = if (dev) .{ .source = app_markup, .watch_path = "src/app.native", .io = init.io } else null, ``` Both engines produce the identical widget tree — same structural ids, same typed handler table — so tests, automation scripts, and goldens hold across dev and release. ## Hybrid views: a Zig root composing markup fragments Compiled markup views compose the other way too: a hand-written Zig builder root can build markup fragments as ordinary children. This is the pattern for any UI that mixes custom Zig panes with declarative markup — the root places what the closed grammar cannot express (a scaled `ui.paragraph` display block, a `.band`-series `ui.chart`, per-row native context menus), and the markup keeps everything it can: ```zig const CompiledHeaderView = canvas.CompiledMarkupView(Model, Msg, @embedFile("header.native")); pub fn rootView(ui: *Ui, model: *const Model) Ui.Node { return ui.column(.{ .gap = 12, .grow = 1 }, .{ CompiledHeaderView.build(ui, model), // the markup fragment, as a child ui.paragraph(.{}, &.{ .{ .text = model.readout(ui.arena), .monospace = true, .scale = 1.6 }, }), }); } // options: .view = rootView, ``` `examples/calculator` is the smallest live reference (`CompiledKeypadView.build(ui, model)` inside a hand-written root); `deck` uses the same shape. Widget ids, handlers, and dispatch are identical to a pure-markup tree, so tests and automation address the fragment's widgets the usual way. A Zig-root app keeps dev-time hot reload for its embedded fragments too: build with `UiAppWithFeatures(Model, Msg, .{ .runtime_markup = dev_markup_reload })` and pass `.markup = .{ .source = ..., .watch_path = "src/header.native", .io = init.io }` gated on `builtin.mode == .Debug` (`null` otherwise) — the wiring in `examples/notes`. Debug builds then reload edits to the watched file in place; release builds compile the runtime engine out entirely. ## Side effects `update` stays pure by routing anything that leaves the model — subprocesses, HTTP, file persistence, timers, clipboard, desktop notifications — through the effects channel, and routed results come back as ordinary messages. In a TypeScript core, effects are `Cmd` data returned from `update` and recurring timers are declared `Sub` data — see [TypeScript Cores: Effects](/docs/typescript#effects-are-cmd-data). In a Zig core, declare `.update_fx` instead of `.update` and spawn from message arms; boot-time work goes in `.init_fx`, which runs exactly once before the first paint. See [Native UI: Effects](/docs/native-ui#effects). ## Dropping down `UiApp` is a layer over the lower-level `App`/`Runtime` pair, which any app can use directly — for custom lifecycle callbacks, imperative window and view management, or embedding [web content](/docs/frontend). The [App & Runtime](/docs/runtime) reference documents that layer, and [Embedded App](/docs/embed) covers driving the runtime from an existing host (including iOS and Android). --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md) --- title: Config url: "https://native-sdk.dev/docs/app-zon" docs_index: /llms.txt lastUpdated: 2026-10-16 --- > For an index of all documentation, see [/llms.txt](/llms.txt). The `app.json` manifest declares app metadata, permissions, security rules, window layout, and packaging inputs. It is read by the CLI and tooling at build, package, and validation time. New projects use JSON so TypeScript developers get familiar syntax, completion, and inline validation through [`$schema`](https://schema.native-sdk.dev/app/v1.json). Existing `app.zon` manifests remain fully supported and expose the same fields—there is no reduced JSON feature set. The versioned URL stays compatible for the lifetime of the v1 manifest contract; `/app.json` is the current-version alias. ## Example: native-rendered app The manifest `native init` generates — identity, one shell window with a GPU surface view, and the minimal permission set: ```json title="app.json" { "$schema": "https://schema.native-sdk.dev/app/v1.json", "id": "dev.native_sdk.my-app", "name": "my-app", "display_name": "My App", "description": "A counter that lives in one native window.", "version": "0.1.0", "icons": ["assets/icon.png"], "platforms": ["macos"], "permissions": ["view", "command"], "capabilities": ["native_views", "gpu_surfaces"], "shell": { "windows": [{ "label": "main", "title": "My App", "width": 480, "height": 320, "views": [{ "label": "main-canvas", "kind": "gpu_surface", "fill": true, "role": "Counter canvas", "accessibility_label": "Counter", "gpu_backend": "metal", "gpu_pixel_format": "bgra8_unorm", "gpu_present_mode": "timer", "gpu_alpha_mode": "opaque", "gpu_color_space": "srgb", "gpu_vsync": true }] }] }, "security": { "navigation": { "allowed_origins": ["zero://app", "zero://inline"], "external_links": { "action": "deny" } } }, "web_engine": "system", "cef": { "dir": "third_party/cef/macos", "auto_install": false } } ``` ## Example: app with web content, menus, and shortcuts A fuller manifest for an app that also [embeds web content](/docs/frontend) and declares commands, shortcuts, menus, and packaging metadata: ```zig title="app.zon" .{ .id = "dev.native_sdk", .name = "native-sdk", .display_name = "native-sdk", .version = "0.1.0", .icons = .{"assets/icon.png"}, .platforms = .{ "macos" }, .permissions = .{ "command", "view", "dialog", "window", "clipboard", "credentials" }, .capabilities = .{ "webview", "js_bridge", "native_views", "gpu_surfaces", "menus", "shortcuts", "dialog", "clipboard", "credentials" }, .bridge = .{ .commands = .{ .{ .name = "native.ping", .origins = .{ "zero://app" } }, .{ .name = "native-sdk.window.create", .permissions = .{ "window" }, .origins = .{ "zero://app" } }, .{ .name = "native-sdk.command.invoke", .permissions = .{ "command" }, .origins = .{ "zero://app" } }, .{ .name = "native-sdk.view.list", .permissions = .{ "view" }, .origins = .{ "zero://app" } }, .{ .name = "native-sdk.dialog.showMessage", .permissions = .{ "dialog" }, .origins = .{ "zero://app" } }, .{ .name = "native-sdk.clipboard.readText", .permissions = .{ "clipboard" }, .origins = .{ "zero://app" } }, .{ .name = "native-sdk.credentials.get", .permissions = .{ "credentials" }, .origins = .{ "zero://app" } }, }, }, .security = .{ .navigation = .{ .allowed_origins = .{ "zero://app", "http://127.0.0.1:5173" }, .external_links = .{ .action = "deny" }, }, }, .web_engine = "system", .cef = .{ .dir = "third_party/cef/macos", .auto_install = false }, .windows = .{ .{ .label = "main", .title = "native-sdk", .width = 720, .height = 480, .restore_state = true }, }, .commands = .{ .{ .id = "command.palette", .title = "Command Palette" }, .{ .id = "app.reload", .title = "Reload" }, }, .shortcuts = .{ .{ .id = "command.palette", .key = "p", .modifiers = .{ "primary", "shift" } }, }, .menus = .{ .{ .title = "View", .items = .{ .{ .label = "Command Palette", .command = "command.palette", .key = "p", .modifiers = .{ "primary", "shift" } }, .{ .separator = true }, .{ .label = "Reload", .command = "app.reload", .key = "r", .modifiers = .{ "primary" } }, }, }, }, .file_associations = .{ .{ .name = "Markdown Document", .extensions = .{ "md", ".markdown" }, .mime_types = .{ "text/markdown" }, .icon = "assets/markdown.icns", }, }, .url_schemes = .{ .{ .scheme = "native-sdk" }, }, } ``` ## Fields
Field Description
`id` Reverse-DNS bundle identifier (e.g. `com.example.myapp` )
`name` Short machine name
`display_name` Human-readable app name — the application menu, Dock, app switcher, and About panel all use it, in dev runs and packaged bundles alike
`description` Optional one-line description shown in the About panel (max 256 bytes, single line)
`version` Canonical `X.Y.Z` version with no leading zeroes — also the version the About panel shows
`icons` The app icon: one square `.png` (1:1, ideally 1024x1024) or `.svg` source that packaging turns into every platform's icon artifacts — the macOS `.icns` gets the platform's rounded-rect icon shape applied automatically. A prebuilt `.icns` / `.ico` entry ships untouched for its platform instead
`platforms` Target platforms: `macos` , `linux` , `windows` , `ios` , `android` , `web`
`dmg` Optional macOS DMG presentation: volume name, PNG/JPEG/TIFF background (with automatic adjacent `@2x` discovery), usable Finder canvas and icon sizes, simple app/Applications positions, or an explicit positioned `items` list of the app, Applications alias, project files/directories, and absolute links. The zero-config defaults produce a complete drag-to-Applications layout.
`permissions` Runtime permissions (see Security ). Audio capture uses `microphone` and `system_audio` ; macOS packaging emits the matching microphone, audio-capture, and screen-capture usage descriptions only when declared
`capabilities` Feature declarations (see Security ). `"store"` links the engine-owned record store; `"sqlite"` links relational SQL effects. They share one capability-shed SQLite object but use separate databases; see Record Store and Relational SQLite
`dock_visible` Initial macOS Dock and app-switcher presence. Defaults to `true` . Set `false` for an Accessory/menu-bar app; the policy is applied before startup windows are created, so no Dock tile flashes. Accessory apps must declare the `"tray"` capability. Runtime `Cmd.setDockPresence` can still promote or demote the app later.
`persist` Engine-owned Model snapshot config: monotonic `version` , optional `debounce_ms` , and the `restore` Msg routes ( `ok` / `none` / `err` ). Requires `"persist"` in capabilities — see Model Persistence
`images` Optional registered-image budget: `.images = .{ .max_image_pixel_bytes = 8_388_608 }` . The default is 1 MiB and accepted values are 1–8 MiB. Encoded photos decode aspect-preservingly to fit; storage is lazy per used slot, but 16 fully used 8 MiB slots are a declared 128 MiB high-water. See Dynamic Images .
`bridge` Bridge command policies (see Bridge )
`security` Navigation and external link policies (see Security )
`web_engine` `system` or `chromium` ; Chromium is currently supported for macOS builds (see Web Engines )
`webview_layer` `auto` (default), `include` , or `exclude` — whether the build ships the embedded web layer (see below)
`theme` Built-in theme pack: `house` (default) or `geist` ; an unknown name is a build/check error (see Theming )
`theme_accent` Optional `#rrggbb` accent layered over the pack — recolors the accent, its knockout ink, the focus ring, and the slider active range together; skipped under high contrast; a malformed value is a build/check error
`cef` CEF runtime config for Chromium apps: `dir` and `auto_install`
`assets` Launch-registered assets for TypeScript-core apps: `images` entries ( `.{ .id = 1, .path = "assets/art/cover.jpg" }` ) are read once at launch and registered on the installing frame; the `id` is the `ImageId` markup avatar bindings reference
`windows` Window definitions (see Windows )
`shell` Native-first window and view tree declarations
`commands` Shared command metadata for menus, shortcuts, native controls, tray items, and bridge calls
`shortcuts` Keyboard shortcuts delivered as `shortcut` events (see Keyboard Shortcuts )
`menus` Native menu declarations delivered through the command event path (see Menus )
`file_associations` File type registration metadata for packaging
`url_schemes` Custom URL scheme registration metadata for packaging
`frontend` Frontend build/dev config (see Frontend Projects )
## `webview_layer` Under the default `auto`, the build infers whether to ship the embedded web layer from what the app declares: `"webview"` in `.capabilities`, a `.frontend` block, a `.shell` webview view, or a web engine resolved to Chromium (from `.web_engine` or the `-Dweb-engine`/`--web-engine` flags) each count as web intent, and an app with none of them builds native-only. `include` forces the layer into a build that declares nothing yet; `exclude` promises a native-only app. The `-Dweb-layer` build option overrides the manifest setting for one build. A native-only build carries the platform consequences with it: on Windows the executable never references `WebView2Loader.dll` and no loader ships in the package; on Linux the host compiles and links without WebKitGTK entirely, so building needs no WebKitGTK development package and users need no `libwebkitgtk` installed at runtime. `exclude` alongside any web declaration is a contradiction, refused with a diagnostic error at validate, build, and package time instead of shipping an app whose declared webviews cannot work: ```zig .capabilities = .{"webview"}, .webview_layer = "exclude", // rejected: remove the web declarations or drop the exclude ``` ## `shell` The optional `shell` block declares native-first windows with explicit view trees. Existing `windows` entries remain the simple compatibility path; `shell.windows` is the richer contract for native chrome, native controls, WebViews, and GPU surfaces. Tooling parses and validates the schema. Runtime code can return the same shape from `App.scene_fn`, materialize a parsed shell window with `runtime.createShellWindow(...)`, or attach a shell view list to an existing window with `runtime.createShellViews(...)`; platform hosts implement view kinds progressively, so unsupported native kinds fail at runtime with an explicit unsupported error until that backend grows support. When an app uses both `windows` and `shell.windows`, labels must stay unique across both lists. Use `windows` for the simple compatibility path or `shell.windows` for native-first structure; do not define two window entries with the same label. For a scene-first app — a `UiApp` passing its Zig scene (`shell_scene`) to the runner — the scene is authoritative at runtime: it re-applies size, title, and views when it loads. the manifest’s first `shell.windows` entry exists because the host creates the startup window before the scene loads, and create-time-only properties must come from the manifest: `titlebar` chrome, `min_width`/`min_height` floors, overlay presentation (`transparent`, `always_on_top`, `click_through`, and `activate_on_show`), and the show mode (canvas-first windows are created hidden and shown after the first frame presents). The numbers appearing in both places is by design — edit the scene for anything that can change after create (size, title, views), and the manifest for create-time presentation and floors. ```zig .shell = .{ .windows = .{ .{ .label = "main", .title = "Acme", .width = 1100, .height = 760, .views = .{ .{ .label = "toolbar", .kind = "toolbar", .edge = "top", .height = 44, .role = "toolbar" }, .{ .label = "body", .kind = "split", .fill = true, .axis = "row" }, .{ .label = "sidebar", .kind = "sidebar", .parent = "body", .width = 280, .min_width = 220, .max_width = 360 }, .{ .label = "sidebar-stack", .kind = "stack", .parent = "sidebar", .x = 16, .y = 16, .width = 220, .height = 120, .axis = "column" }, .{ .label = "sidebar-live", .kind = "checkbox", .parent = "sidebar-stack", .accessibility_label = "Toggle live updates", .text = "Live updates" }, .{ .label = "content", .kind = "webview", .parent = "body", .url = "zero://app/index.html", .fill = true }, .{ .label = "canvas", .kind = "gpu_surface", .parent = "body", .width = 480, .gpu_backend = "metal", .gpu_pixel_format = "bgra8_unorm", .gpu_present_mode = "timer", .gpu_alpha_mode = "opaque", .gpu_color_space = "srgb", .gpu_vsync = true }, .{ .label = "status", .kind = "statusbar", .edge = "bottom", .height = 24, .text = "Ready" }, }, }, }, }, ``` Each window takes a `label` plus optional `title`, `width`, `height`, `x`, `y`, `resizable`, `restore_state`, `restore_policy` (`clamp_to_visible_screen` or `center_on_primary`), `initially_hidden` (default false; create the native window ordered out until an explicit show/focus), `allows_fullscreen` (default true; false disables native fullscreen on macOS without disabling ordinary resizing), `min_width`/`min_height` (a content min-size floor the window itself enforces — macOS `contentMinSize`; the first shell window's declaration threads through the startup create like `titlebar`, negative values are a manifest error, 0 means no floor), and `titlebar` (`standard`, `hidden_inset`, `hidden_inset_tall` — the tall variant centers macOS's traffic lights in the 52pt unified band for toolbar-height headers — or `chromeless`, the fully-skinned opt-in that removes all OS chrome including the system buttons; only for apps that draw their own working window controls, see `examples/deck`). `restore_state` defaults to true and controls only whether the state store is consulted: a store hit restores the saved frame, an authored `x` or `y` is explicit placement, and a fresh window with neither is default placement. On macOS the default `clamp_to_visible_screen` policy keeps restored and explicit frames on their matching or nearest display, centers the main fresh window, and cascades fresh secondary windows; `center_on_primary` centers restored and fresh default frames on the primary display. `titlebar = "hidden_inset"` hides the titlebar and extends content under it (macOS keeps the traffic lights) — the first shell window's declaration threads through the STARTUP window create, so the main window's chrome is right from the first frame; the app's own header then takes over dragging and inset padding through the `window-drag` attribute and the `on_chrome` hook (see Native UI). Platforms without the concept keep standard chrome. The same fields are accepted on top-level `windows` entries. `dock_visible` is top-level app policy, not a window field: setting it false removes the Dock/app-switcher presence but does not hide a window; pair it with `initially_hidden = true` when the app should launch behind its status item. Overlay presentation is also fixed at create time: `transparent` makes the top-level window alpha-capable, `always_on_top` selects its floating/topmost level, `click_through` passes pointer input to windows underneath, `activate_on_show = false` reveals it without activating the app or taking focus, and `allows_fullscreen = false` removes macOS fullscreen participation while keeping the window resizable. Canvas windows already use present-before-show, so these flags are applied while the window is hidden and its first alpha-correct frame becomes the first visible frame. `initially_hidden = true` is stronger: it suppresses that reveal until `Cmd.showWindow` or explicit focus. Pair `transparent = true` with a non-opaque `gpu_alpha_mode`; `UiApp.WindowDescriptor` makes that canvas-alpha choice and uses an alpha-zero clear automatically. See the overlay window recipe. These fields are accepted on top-level `windows` and `shell.windows`. Runtime `WindowCreateOptions` exposes the same controls but spells the hidden mode `.show = .hidden`; `UiApp.WindowDescriptor` exposes the overlay controls but not the initially-hidden mode. Windows also take `close_policy` (`quit`, the default — the close affordance really closes, behavior unchanged for every existing app — or `hide`, the menu-bar-app shape: close hides the window and the app keeps running behind its status item). Like `titlebar`, close handling is host window state fixed at create, and the first shell window's declaration threads through the startup create. `hide` is supported on macOS and Windows — on Windows it additionally requires the `"tray"` capability (the tray icon is the only re-show affordance there; a declaration without it is refused at build time with a diagnostic). Linux has no status item to bring a hidden window back, so the declaration is refused at build time with a diagnostic. See Windows and the tray lifecycle recipe. The same `close_policy` field is accepted on top-level `windows` entries. Supported `kind` values are `webview`, `toolbar`, `titlebar_accessory`, `sidebar`, `statusbar`, `split`, `stack`, `button`, `icon_button`, `list_item`, `checkbox`, `toggle`, `segmented_control`, `text_field`, `search_field`, `label`, `spacer`, `gpu_surface`, and `progress_indicator`. Each view has a required `label` and `kind`. WebView views require `url`. Optional layout fields are `parent`, `edge`, `axis`, `x`, `y`, `width`, `height`, `min_width`, `min_height`, `max_width`, `max_height`, `fill`, and `layer`. Optional behavior and accessibility metadata are `visible`, `enabled`, `role`, `accessibility_label`, `text`, and `command`. `gpu_surface` views may also set `gpu_backend`, `gpu_pixel_format`, `gpu_present_mode`, `gpu_alpha_mode`, `gpu_color_space`, and `gpu_vsync`; those fields are rejected on non-GPU view kinds. The macOS system-WebView host presents with Metal, while the Windows host presents representable binary canvas packets with Direct2D/DirectWrite; frame events expose the concrete `metal` or `direct2d` backend. `gpu_backend` accepts `metal` or `software` as portable requests; omit it to select the default. Linux falls back to software presentation, and Windows uses software for unrepresentable commands, transparent layered windows, or when Direct2D is unavailable. The `axis` field accepts `row` or `column` on parent containers such as `toolbar`, `sidebar`, `split`, and `stack`; it defaults to `row`. `createShellWindow` and `createShellViews` dock `edge` views against the remaining window content, let one or more top-level `fill` views use the final remaining rectangle, clamp resolved frames with any min/max size fields, and lay out parented controls such as toolbar buttons with small native defaults when explicit `x`, `y`, `width`, or `height` values are omitted. Parent containers flow omitted child positions horizontally with `axis = "row"` and vertically with `axis = "column"`. `split` containers use the same axis without inner spacing, so fixed-size children can sit beside a `fill` child. The runtime keeps the shell view slice as a layout binding and reapplies it when the window is resized, so pass data that lives for the lifetime of the window. ## `commands` The optional `commands` list declares shared command metadata. The runtime still dispatches by command id, but this section gives menus, shortcuts, native controls, tray items, and bridge callers one manifest-level source of truth for user-facing labels and default state: ```zig .commands = .{ .{ .id = "app.refresh", .title = "Refresh" }, .{ .id = "app.sidebar.toggle", .title = "Sidebar", .checked = true }, .{ .id = "app.sync", .title = "Sync", .enabled = false }, }, ``` `id` is required and must be unique. `title` defaults to an empty string. `enabled` defaults to `true`; `checked` defaults to `false`. An app can define up to 256 commands. Command ids can be up to 128 bytes and titles can be up to 128 bytes. Generated zero-config TypeScript and Zig-core runners load manifest commands into `RuntimeOptions.commands`; ejected runners use the same fallback. Native code can read the active catalog with `runtime.listCommands(...)`, and trusted WebView code can read it with `window.zero.commands.list()` when the built-in command bridge allows it. Use the catalog to keep menus, shortcuts, toolbar controls, tray items, and bridge callers aligned with the same command ids. ## `shortcuts` The optional `shortcuts` list defines app-level keyboard shortcuts. Generated zero-config TypeScript and Zig-core runners load these automatically, as do ejected runners: ```zig .shortcuts = .{ .{ .id = "command.palette", .key = "p", .modifiers = .{ "primary", "shift" } }, .{ .id = "reload", .key = "r", .modifiers = .{ "primary" } }, }, ``` `id` is the event identifier. `key` accepts letters, digits, the unshifted punctuation keys `=`, `-`, `,`, `.`, `/`, `;`, `'`, `[`, `]`, `\`, and `` ` ``, or a named key. `modifiers` accepts `primary`, `command`, `control`, `option`, `alt`, and `shift`. Single-character keys and text-entry keys (`enter`, `tab`, `space`, and `backspace`) require at least one modifier. An app can define up to 64 shortcuts. Shortcut ids can be up to 64 bytes and keys can be up to 32 bytes. Chromium builds are currently macOS-only; use the Linux system WebView backend when an app needs native shortcut events on Linux. ## `menus` The optional `menus` list defines native app menus. Generated zero-config TypeScript and Zig-core runners load these automatically, as do ejected runners: ```zig .menus = .{ .{ .title = "View", .items = .{ .{ .label = "Refresh", .command = "app.refresh", .key = "r", .modifiers = .{ "primary" } }, .{ .separator = true }, .{ .label = "Sidebar", .command = "app.sidebar.toggle", .checked = true }, }, }, }, ``` Each menu has a `title` and optional `items`. Command-backed items require `label` and `command`. Optional fields are `key`, `modifiers`, `separator`, `enabled`, and `checked`. `modifiers` accepts the same values as shortcuts. An app can define up to 16 menus and 128 total menu items. Menu titles can be up to 64 bytes, item labels up to 128 bytes, command ids up to 128 bytes, and keys up to 32 bytes. ## File associations and URL schemes The optional `file_associations` and `url_schemes` lists declare packaging metadata for document types and custom protocols: ```zig .file_associations = .{ .{ .name = "Markdown Document", .role = "editor", .extensions = .{ "md", ".markdown" }, .mime_types = .{ "text/markdown" }, .icon = "assets/markdown.icns", }, }, .url_schemes = .{ .{ .scheme = "acme-notes" }, }, ``` File associations require a `name` and at least one `extensions` or `mime_types` entry. Extensions may include a leading dot, but packaging tools treat the extension as the same value either way. `icon` is optional and must be a relative path. URL schemes require a lowercase custom `scheme`. Reserved schemes such as `http`, `https`, and `file` are rejected. `role` defaults to `viewer` and accepts `viewer`, `editor`, `shell`, or `none`. Package generation emits this metadata into macOS `Info.plist` document/protocol declarations, Linux desktop and shared MIME metadata, and a Windows per-user registration script. ## `frontend.dev` The optional `frontend.dev` block configures the managed dev server for `native dev` and `zig build dev`: ```zig .frontend = .{ .dist = "frontend/dist", .entry = "index.html", .spa_fallback = true, .dev = .{ .url = "http://127.0.0.1:5173/", .command = .{ "npm", "--prefix", "frontend", "run", "dev" }, .ready_path = "/", .timeout_ms = 30000, }, }, ```
Field Description
`url` Dev server URL to load in the WebView during development
`command` Command to start the dev server (spawned as a child process)
`ready_path` HTTP path to poll until the dev server is ready (default `/` )
`timeout_ms` Milliseconds to wait for the dev server before failing (default `30000` )
## Validation ```bash native validate app.json native doctor --manifest app.json --strict ``` --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md) --- title: Automation url: "https://native-sdk.dev/docs/automation" docs_index: /llms.txt lastUpdated: 2026-10-19 --- > For an index of all documentation, see [/llms.txt](/llms.txt). The automation server exposes runtime state and accepts commands via a file-based protocol. A running app publishes an accessibility snapshot — every widget with its id, role, name, bounds, and state — and accepts scripted clicks, keys, drags, and assertions against it. Use it for integration testing, CI smoke tests, inspecting running apps, and letting AI agents verify their own UI work. ## Enabling automation Build with the automation flag (`native` verbs forward `-D` flags to the underlying `zig build`): ```bash native build -Dautomation=true ``` In your runner, pass an `automation.Server` to `RuntimeOptions`: ```zig const server = native_sdk.automation.Server.init(io, ".zig-cache/native-sdk-automation", "My App"); var runtime = native_sdk.Runtime.init(.{ .platform = my_platform, .automation = server, }); ``` The default directory is `.zig-cache/native-sdk-automation`. ## File protocol When the runtime publishes a snapshot, it writes these files to the automation directory:
File Description
`snapshot.txt` Runtime state: source kind, window metadata, native/WebView metadata including role, accessibility label, text, and focus state, the configured command and app-menu catalogs, `ready=true/false` , and `markup_watch=armed|off` in the header — whether the markup hot-reload watch is 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)
`accessibility.txt` Accessibility tree summary with native view roles and accessible names. An explicit `label=` REPLACES the visible text as the accessible name — snapshot greps and screen readers see the label, not the text, so don't label an element whose visible text your assertions grep for.
`windows.txt` Window list: window @w\{id} "\{title}" focused=\{bool} per line
`screenshot-.png` Deterministic PNG of a `gpu_surface` view, rendered through the CPU reference renderer on `screenshot [scale]`
`command-.txt` Command queue: one entry per command, written by the CLI, consumed oldest-first by the runtime (which deletes the entry as its consumption ack)
`bridge-response.txt` JSON response from the last bridge command
`provenance.txt` Response to the last `provenance` command: where a live widget was authored (file, byte span, line:column, template chain, iteration keys)
## Commands The runtime watches the command queue and processes these actions:
Action Description
`reload` Reload the WebView source
`wait` Block until the snapshot shows `ready=true`
`resize []` Dispatch a main-window resize event and relayout native/WebView surfaces
`provenance ( | at )` Report where a live widget was authored into `provenance.txt` : markup file, byte span, line:column, template use-site chain, and iteration keys. Point queries hit-test view-local coordinates.
`bridge ` Send a bridge command with origin `zero://inline`
`menu-command ` Dispatch a menu command event for the main window
`native-command []` Dispatch a native view command event for the main window
`widget-action []` Invoke a retained canvas widget action
`widget-click ` Dispatch pointer down/up at a retained canvas widget
`widget-hold ` Press-and-hold: pointer down, the reserved hold timer fired, then the suppressed release — the widget's `on_hold` Msg through the real gesture path
`widget-context-press ` Secondary click (right/ctrl-click): presents the widget's context menu, or dispatches `on_hold` immediately when the route has none
`widget-context-menu ` Invoke a declared context-menu item by 0-based index (as the snapshot's `context_menu=[...]` lists them) — the selection dispatches as the same `context_menu_action` platform event a real pick produces; presentation is skipped because the OS menu's tracking loop cannot be driven. Refuses undeclared menus, out-of-range indices, separators, and disabled items by name
`widget-drag [ ]` Dispatch pointer down/drag/up across a retained canvas widget
`widget-wheel []` Dispatch wheel input at a retained canvas widget (the optional `delta-x` scrolls the horizontal axis)
`widget-key []` Dispatch key input to the focused retained canvas widget
`widget-pinch [ ]` Dispatch a trackpad pinch gesture at a gpu-surface view: the real `pinch_begin` / `pinch_change` / `pinch_end` events, with one change carrying `scale - 1` . `scale` is the final multiplicative zoom for the gesture (1.5 zooms in 50%, 0.5 zooms out to half) — the cumulative product of `1 + delta` lands exactly on it. The anchor point defaults to the view center
`shortcut ` Dispatch a shortcut command event for the main window
`tray-action ` or `tray-action ` Select a status-item dropdown row. The one-id form targets primary status item `#1` ; multiple-item snapshots print `tray #id` headers
`focus ` Focus a native or WebView-backed view in the main window
`focus-next` / `focus-previous` Move focus through visible, enabled views in runtime order
`profile ` Toggle per-stage frame timing. While on, the snapshot 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` )
Commands queue as `command-.txt` entries: each `native automate ` claims the next sequence number exclusively (rapid back-to-back invocations can never overwrite each other), the app consumes one entry per presented frame in strict arrival order, and deleting the entry is the consumption ack. The queue is bounded to a handful of entries — a writer finding it full retries until the app drains a slot and fails loudly (non-zero exit) if it never does. `native automate ` prints `delivered -> ` only after the app consumed its entry, so a unresponsive app causes a delivery failure. Widget verbs and `screenshot` address a `gpu_surface` view by its label across ALL open windows — snapshots enumerate every window's views and widgets, so a model-declared secondary window's canvas (a settings window) is drivable and capturable exactly like the main one, with no window argument. ## CLI usage The `native automate` subcommand interacts with the automation directory: ```bash # Wait for the app to be ready (polls snapshot.txt for ready=true) native automate wait # Assert on the snapshot: each argument is a regex that must match # (polls up to --timeout-ms, default 30000; --absent inverts) native automate assert 'gpu_nonblank=true' 'role=button name="Reset"' native automate assert --absent 'error event=' # List running automation-enabled apps native automate list # Dump the current snapshot native automate snapshot # Render a gpu_surface view to screenshot-main-canvas.png native automate screenshot main-canvas # Reload the WebView native automate reload # Resize the main window surface native automate resize 900 640 # Dispatch command-source events native automate menu-command app.refresh native automate native-command app.refresh refresh-button native automate shortcut app.refresh # Drive retained canvas widgets native automate widget-action canvas 2 press native automate widget-click canvas 3 native automate widget-hold canvas 3 # press-and-hold (on_hold) native automate widget-context-press canvas 3 # right-click (presents the menu) native automate widget-context-menu canvas 3 1 # pick declared menu item 1 # Drive focus between native controls and WebViews native automate focus refresh-button native automate focus-next native automate focus-previous # Toggle per-stage frame timing; the snapshot then carries a # frame_profile line (rolling p50/p90/max us per pipeline stage) native automate profile on native automate snapshot | grep -o 'frame_profile.*' native automate profile off # Send a bridge command and get the response native automate bridge '{"id":"1","command":"native.ping","payload":{"source":"automation"}}' ``` ## Testing with automation The WebView and native-shell smoke build steps demonstrate full automation test flows: 1. Build and start the app with `-Dautomation=true` 2. Run `native automate wait` to block until the app is ready 3. Run `native automate snapshot` to verify window, source, and native/WebView metadata 4. Run `native automate resize ...`, `native automate bridge '...'`, focus traversal, or command-source actions such as `native automate native-command ...` 5. Verify bridge responses, relayout bounds, focus state, and updated snapshots ```bash zig build test-webview-smoke -Dplatform=macos ``` ## Write-back Because views are data, automation can go the other way too: select a widget in the running app, jump to the markup that authored it, and write an edit back into the source file — the app's own hot-reload watch picks the change up and repaints. The read half is `provenance`. Every markup-built widget's structural id maps back to its authored source, captured at view build time: the file, the node's byte span and line:column, the template instantiation chain (a widget inside a template reports both its definition site and every `` that put it there), and the iteration keys that say which `` row it is. Widgets built with the Zig builder report `authored=zig` — write-back edits markup files only. TypeScript apps report provenance from their compiled views in `native dev`, and an edit reloads in place through the same dev loop. ```bash # Where does this widget come from? (id from the snapshot, or hit-test a point) native automate provenance kanban-canvas 6624116744891006388 native automate provenance kanban-canvas at 760 30 ``` The write half is `edit`: typed, minimal-diff operations on the file the widget came from. An operation changes only bytes inside the target node's span — whitespace, comments, attribute order, and every other node survive byte for byte, proven by reparsing and diffing the parse trees before anything is written. ```bash native automate edit kanban-canvas 6624116744891006388 set-text "Add task" native automate edit kanban-canvas 6624116744891006388 set-attr variant secondary native automate edit kanban-canvas 6624116744891006388 remove-attr variant ``` Edits refuse rather than guess: a widget authored in Zig, a file that changed on disk since the app loaded it (the provenance response carries the loaded bytes' hash, so concurrent edits are never clobbered), or an edit that would fail markup validation all stop with a diagnostic and leave the file untouched. A successful edit needs no reload command — the markup watch (`MarkupOptions.watch_path`, a dev/Debug feature) reloads within its poll interval, so `native automate assert` on the snapshot is the way to await the repaint. `zig build test-writeback-smoke` (macOS) drives the whole loop against the kanban example: query provenance, flip the button label through the verb, assert the repaint, verify the byte-exact diff, and flip it back. ## Session recording and blob growth `NATIVE_SDK_SESSION_RECORD=/path/session.journal` records platform events and effect results; `NATIVE_SDK_SESSION_REPLAY` replays that journal without touching the original network, process, database, or file. Large effect payloads—including every streamed file-read chunk—live content-addressed under the sibling `blobs/` directory, and the journal stores each hash and length. Keep the journal and `blobs/` together when copying a recording. The blob store deduplicates identical chunks but is intentionally unbounded today: there is no automatic size quota or garbage collector. Long recordings and repeated large imports can therefore grow the directory substantially. Treat a recording as one disposable artifact, monitor its directory size in long automation runs, and delete the journal plus its sibling `blobs/` directory when it is no longer needed. ## Custom directory Pass a custom path to `automation.Server.init()`: ```zig const server = native_sdk.automation.Server.init(io, "/tmp/my-app-automation", "My App"); ``` The CLI reads from the default `.zig-cache/native-sdk-automation` unless you specify a directory via the automation subcommand. --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md) --- title: Building Components url: "https://native-sdk.dev/docs/building-components" docs_index: /llms.txt lastUpdated: 2026-10-16 --- > For an index of all documentation, see [/llms.txt](/llms.txt). Use [theming](/docs/theming) to customize the built-in components. App components are Native markup templates: they compose built-ins, accept values through template args, accept content through slots, and live in `.native` component files. Component logic stays in the TypeScript core's ordinary `update` and derived helpers. The mechanics (template grammar, import rules, slots) are specified in [Native UI](/docs/native-ui#templates); this page builds one real component end to end. The ownership model in one line: **use and theme the built-ins by default; eject a library composite when you need to own its shape; build new composites from primitives when the library has no shape for it.** The last two are this page. ## A component in markup A dashboard needs the same labeled stat tile three times. That repetition is a `