Native SDK

A standard Native SDK project is composed of three primary files of truth:

• src/app.native: The declarative markup defining the view.
• src/core.ts (or src/main.zig): The logic containing the Model, Msg, and update function.
• Manifest: Defines the application configuration.

There is no separate build configuration required for standard projects.

The Native SDK includes a built-in component catalog featuring house-style defaults such as neutral surfaces, Geist typography, and token-driven styling (color, radius, shadow, and motion).

Each component in the catalog provides:

• Native Markup: The view language representation (tags, attributes, and bindings).
• Logic Samples: Implementation examples in both TypeScript and Zig.
• Programmatic Construction: Examples using the canvas.Ui builder for Zig views created without markup.

To view the full set of component variations, navigate to the specific component's page from the index grid.

The Native SDK uses a dual-architecture approach: native-rendered apps (using .native markup and Zig logic) and WebView-shell apps (rendering web frontends in a WebView).

Key components include:

• App: Describes product state, name, WebView source, lifecycle, and bridge dispatch.
• Runtime: Manages the event loop, windows, bridge dispatch, security, and platform services.
• WebViewSource: Defines what the WebView loads (HTML, URL, or local assets).
• app.zon: The app manifest containing identity, icons, windows, permissions, and security policies.
• src/runner.zig: Generated runtime wiring (security, platform setup, tracing).
• src/main.zig: App behavior, state, and lifecycle callbacks.
• frontend/: Standard web code that communicates with Zig via window.zero.invoke().

A Native SDK application core is the logic tier consisting of four main components:

1. Model: A readonly interface representing the application state.
2. Msg: A discriminated union representing all possible events/actions.
3. update(model, msg): A single, pure, synchronous transition function that returns the next state.
4. Pure Helpers: Functions that take the Model as an argument to derive data.

By default, this is authored in src/core.ts. The @native-sdk/core transpiler compiles this TypeScript into native code at build time. No JS engine is included in the final binary; instead, the code is checked against a subset of TypeScript to ensure it can be safely compiled to native.

A Native SDK application is composed of four primary parts:

1. src/app.native: The UI definition containing elements, layout, bindings, and message dispatch.
2. Model: A plain data structure that holds the application state.
3. Msg: A tagged union representing all possible events or actions that can occur.
4. update(model, msg): The single function responsible for all state transitions.

The runtime handles installation, presentation, resizing, event dispatch, timers, and hot reloading.

A Native SDK application follows a unidirectional data flow loop consisting of four parts:

1. Model: A plain data structure representing the entire application state.
2. Msg: A tagged union (or TypeScript union type) representing all possible events or actions.
3. update(model, msg): A pure function that is the sole place where state changes occur. It takes the current model and a message, then returns a new model.
4. View: A Native markup file (.native) or a Zig view function that derives the UI from the current model.

Input events (pointer, keyboard, etc.) are dispatched to widgets, which then trigger the bound Msg to be processed by the update function. The runtime then rebuilds the view and repaints the changes.

The Native SDK provides a unified runtime model for building native desktop applications, with experimental mobile support. While the runtime is shared, native affordances are platform-specific.

Important Behavior: If you attempt an operation that is not supported on the current host platform, the SDK will return explicit runtime errors rather than failing silently or attempting to emulate the behavior. Always check platform support before executing platform-specific native affordances.

The tools/linux-truth/run-all.sh script supports several specific commands to manage the lifecycle of the Linux truth loop:

• image: Builds the container image.
• up: Starts the long-lived container.
• sync: Rsyncs /src into the container's /work volume (useful after making local edits; note that it never writes back to the host).
• recon: Builds and launches every showcase app, dumping snapshots, widget inventories, and both screenshot channels.
• drive: Replays per-app interaction scenarios (clicks, text input, wheel, and resizing including min-size clamps).
• suites: Runs the engine, example test suites, and the webview link check on real Linux.
• all: Runs the entire sequence.

Windows packaging (early development) copies the binary and assets into a distributable directory and generates a multi-size app-icon.ico. If file associations or URL schemes are configured, it includes install/register-file-types.ps1 to register types in the user registry.

native package --target windows --manifest app.zon --binary zig-out/bin/MyApp.exe