### Run Example with Chromium/CEF

Source: https://github.com/vercel-labs/zero-native/blob/main/examples/webview/README.md

Build and run the WebView example using the Chromium/CEF web engine, with automatic installation enabled.

```bash
zig build run -Dweb-engine=chromium -Dcef-auto-install=true
```

--------------------------------

### Run the Hello Example

Source: https://github.com/vercel-labs/zero-native/blob/main/examples/hello/README.md

Execute this command in the terminal to build and run the 'Hello Example' application.

```bash
zig build run
```

--------------------------------

### Run Hello Example with Custom Path

Source: https://github.com/vercel-labs/zero-native/blob/main/examples/hello/README.md

When using the example standalone, specify the path to the zero-native library using this command.

```bash
zig build run -Dzero-native-path=/path/to/zero-native
```

--------------------------------

### Build and Run WebView Example (System Engine)

Source: https://github.com/vercel-labs/zero-native/blob/main/CONTRIBUTING.md

Build the WebView example, linking against the system's web engine, and then run it.

```bash
zig build test-webview-system-link
```

```bash
zig build run-webview
```

--------------------------------

### Install and Run CEF

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/web-engines/page.mdx

Commands to install the CEF runtime and then build and run the application. Ensure the CEF runtime is correctly installed before running.

```bash
zero-native cef install
zig build run
```

--------------------------------

### Initialize a new zero-native project

Source: https://github.com/vercel-labs/zero-native/blob/main/packages/zero-native/README.md

Scaffold a new zero-native project with a specified frontend framework. After initialization, navigate into the project directory and run `zig build run` to install frontend dependencies and start the application.

```bash
zero-native init my_app --frontend vite
cd my_app
zig build run
```

--------------------------------

### Install CEF and Run WebView with Chromium Engine

Source: https://github.com/vercel-labs/zero-native/blob/main/CONTRIBUTING.md

Install the Chromium Embedded Framework (CEF) and then run the WebView example using the Chromium engine.

```bash
zero-native cef install
```

```bash
zig build run-webview -Dweb-engine=chromium
```

--------------------------------

### Run Example with Automation Enabled

Source: https://github.com/vercel-labs/zero-native/blob/main/examples/webview/README.md

Build and run the WebView example with automation features enabled, typically used for testing purposes.

```bash
zig build run -Dautomation=true
```

--------------------------------

### CLI Setup for CEF

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/web-engines/page.mdx

Commands to install the CEF runtime and check the project's health. `zero-native cef install` downloads and verifies the CEF runtime, while `zero-native doctor` checks manifest integrity.

```bash
zero-native cef install
zero-native doctor --manifest app.zon
```

--------------------------------

### Install zero-native CLI

Source: https://github.com/vercel-labs/zero-native/blob/main/README.md

Install the zero-native command-line interface globally using npm.

```bash
npm install -g zero-native
```

--------------------------------

### Run WebView with System Engine

Source: https://github.com/vercel-labs/zero-native/blob/main/CONTRIBUTING.md

Build and run the WebView example, explicitly setting the web engine to the system's default.

```bash
zig build run-webview -Dweb-engine=system
```

--------------------------------

### Install Panic Capture Handler

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/debugging/page.mdx

Installs the panic capture handler during application startup. This function requires the IO and log paths to be provided.

```zig
zero_native.debug.installPanicCapture(io, log_setup.paths);
```

--------------------------------

### Enable Automation in Build

Source: https://github.com/vercel-labs/zero-native/blob/main/CONTRIBUTING.md

Build the WebView example with automation enabled.

```bash
zig build run-webview -Dautomation=true
```

--------------------------------

### Run Dev Server with Binary

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/cli/dev/page.mdx

Starts the dev server, waits for the frontend to be ready, and launches the native shell. Specify the path to your built native binary.

```bash
zero-native dev --binary zig-out/bin/MyApp
```

--------------------------------

### Enabling Built-in Commands (Zig Example)

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/bridge/builtin-commands/page.mdx

Configuration example in Zig to enable and specify permissions and origins for built-in bridge commands.

```APIDOC
```zig
const app_permissions = [_][]const u8{zero_native.security.permission_window};

.security = .{
    .permissions = &app_permissions,
    .navigation = .{ .allowed_origins = &.{ "zero://app" } },
},
.builtin_bridge = .{
    .enabled = true,
    .commands = &.{ 
        .{ .name = "zero-native.window.list", .permissions = .{ "window" }, .origins = .{ "zero://app" } },
        .{ .name = "zero-native.window.create", .permissions = .{ "window" }, .origins = .{ "zero://app" } },
        .{ .name = "zero-native.dialog.openFile", .origins = .{ "zero://app" } },
        .{ .name = "zero-native.dialog.showMessage", .origins = .{ "zero://app" } },
    },
},
```
```

--------------------------------

### Open Xcode Project

Source: https://github.com/vercel-labs/zero-native/blob/main/examples/ios/README.md

Open the iOS example project in Xcode to build and run the application on a simulator or device.

```bash
open examples/ios/ZeroNativeIOSExample.xcodeproj
```

--------------------------------

### Check Documentation Site

Source: https://github.com/vercel-labs/zero-native/blob/main/CONTRIBUTING.md

Install dependencies and check the documentation site using pnpm.

```bash
pnpm --dir docs install --frozen-lockfile
```

```bash
pnpm --dir docs check
```

--------------------------------

### Start Next.js Dev Server

Source: https://github.com/vercel-labs/zero-native/blob/main/examples/next/README.md

Starts the Next.js development server and launches the native shell with the specified frontend URL. This is useful for rapid development.

```bash
zig build dev
```

--------------------------------

### Install CEF from Official Archives with Build Tools

Source: https://github.com/vercel-labs/zero-native/blob/main/third_party/cef/README.md

Installs CEF from official archives and allows building the wrapper locally. Requires build tools to be present.

```sh
zero-native cef install --source official --allow-build-tools --dir /path/to/cef
```

--------------------------------

### Full app.zon Manifest Example

Source: https://context7.com/vercel-labs/zero-native/llms.txt

This is a comprehensive example of the app.zon manifest file, showcasing various configuration options including metadata, permissions, security settings, web engine, window layout, frontend configuration, and auto-update settings.

```zig
// app.zon — full example
.{ 
    .id = "com.example.myapp",
    .name = "myapp",
    .display_name = "My App",
    .version = "1.0.0",
    .icons = .{ "assets/icon.icns", "assets/icon.ico" },
    .platforms = .{ "macos", "linux" },
    .permissions = .{ "window", "filesystem" },
    .capabilities = .{ "webview", "js_bridge" },

    // Bridge command allowlist (default-deny)
    .bridge = .{
        .commands = .{
            .{ .name = "native.ping", .origins = .{ "zero://app" } },
            .{ .name = "zero-native.window.create", .permissions = .{ "window" }, .origins = .{ "zero://app" } },
            .{ .name = "zero-native.dialog.openFile", .origins = .{ "zero://app" } },
        },
    },

    // Security: navigation allowlist + external links
    .security = .{
        .navigation = .{
            .allowed_origins = .{ "zero://app", "http://127.0.0.1:5173" },
            .external_links = .{ .action = "open_system_browser", .allowed_urls = .{ "https://docs.example.com/*" } },
        },
    },

    // Web engine: "system" or "chromium"
    .web_engine = "system",
    .cef = .{ .dir = "third_party/cef/macos", .auto_install = false },

    // Windows declared at startup
    .windows = .{
        .{ .label = "main", .title = "My App", .width = 960, .height = 640, .restore_state = true },
    },

    // Frontend build/dev config
    .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,
        },
    },

    // Optional: auto-update config
    .updates = .{
        .feed_url = "https://example.com/releases/feed.json",
        .public_key = "base64-ed25519-public-key",
        .check_on_start = true,
    },
}

```

--------------------------------

### Start the Development Server

Source: https://context7.com/vercel-labs/zero-native/llms.txt

The `zero-native dev` command launches the app with a managed frontend dev server. You can override the default server URL and command, or increase the startup timeout.

```bash
zero-native dev --binary zig-out/bin/MyApp
```

```bash
zero-native dev --binary zig-out/bin/MyApp \
  --url http://127.0.0.1:3000/ \
  --command "npm run dev"
```

```bash
zero-native dev --binary zig-out/bin/MyApp --timeout-ms 60000
```

--------------------------------

### Full Automation Test Flow Example

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/automation/page.mdx

Demonstrates a complete automation test flow including building, waiting for readiness, verifying the snapshot, and testing the native bridge.

```bash
zig build test-webview-smoke -Dplatform=macos
```

--------------------------------

### Install CEF Runtime to Custom Directory

Source: https://github.com/vercel-labs/zero-native/blob/main/third_party/cef/README.md

Installs the CEF runtime to a specified directory. This is useful for managing CEF installations outside the default paths.

```sh
zero-native cef install --dir /path/to/cef
zig build run-webview -Dcef-dir=/path/to/cef
```

--------------------------------

### Install Android App

Source: https://github.com/vercel-labs/zero-native/blob/main/examples/android/README.md

Install the debug version of the Android application onto a connected emulator or device using Gradle.

```bash
./gradlew :app:installDebug
```

--------------------------------

### zero-native dev

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/cli/page.mdx

Starts the application with a managed frontend development server. The `--binary` flag is required to specify the path to the binary.

```APIDOC
## zero-native dev --binary <path>

### Description
Start the app with a managed frontend dev server.

### Parameters
#### Query Parameters
- **--binary** (string) - Required - The path to the binary.
```

--------------------------------

### Install CEF Version

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/packaging/page.mdx

Install a specific version of CEF using the zero-native CLI before building and packaging your application.

```bash
zero-native cef install --version <pinned-version>
```

--------------------------------

### Handling tray actions

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/tray/page.mdx

Example of how to handle user interactions with tray menu items.

```APIDOC
## Handling tray actions

When a user clicks a tray menu item, the runtime dispatches a `CommandEvent` with the name `"tray.action"`. Use your `event_fn` to handle it:

```zig
fn event(context: *anyopaque, runtime: *Runtime, ev: Event) anyerror!void {
    switch (ev) {
        .command => |cmd| {
            if (std.mem.eql(u8, cmd.name, "tray.action")) {
                // Handle tray menu click
                // The clicked menu item's ID can be found in cmd.data
            }
        },
        else => {},
    }
}
```
```

--------------------------------

### Create and Manage Windows in JavaScript

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/bridge/builtin-commands/page.mdx

Use the `window.zero.windows.create` API to create a new window with specified dimensions and labels. This example demonstrates creating a 'tools' window.

```javascript
const win = await window.zero.windows.create({
  label: "tools",
  title: "Tools",
  width: 420,
  height: 320,
});
```

--------------------------------

### Install Default macOS CEF Runtime

Source: https://github.com/vercel-labs/zero-native/blob/main/third_party/cef/README.md

Installs the default zero-native prepared CEF runtime from GitHub Releases for macOS. This includes the necessary wrapper library, eliminating the need for CMake.

```sh
zero-native cef install
```

--------------------------------

### app.zon Manifest Example

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/app-zon/page.mdx

This is a complete example of an app.zon manifest file. It includes declarations for app metadata, permissions, bridge commands, security policies, web engine settings, and window configurations.

```zig
.{
    .id = "dev.zero_native",
    .name = "zero-native",
    .display_name = "zero-native",
    .version = "0.1.0",
    .icons = .{ "assets/icon.icns", "assets/icon.ico" },
    .platforms = .{ "macos" },
    .permissions = .{ "window" },
    .capabilities = .{ "webview", "js_bridge" },
    .bridge = .{
        .commands = .{
            .{ .name = "native.ping", .origins = .{ "zero://app" } },
            .{ .name = "zero-native.window.create", .permissions = .{ "window" }, .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 = "zero-native", .width = 720, .height = 480, .restore_state = true },
    },
}

```

--------------------------------

### Manage Chromium Embedded Framework (CEF)

Source: https://context7.com/vercel-labs/zero-native/llms.txt

The `zero-native cef` command handles the download, installation, and validation of the CEF runtime. You can install specific versions, to custom directories, or force re-downloads.

```bash
zero-native cef install
```

```bash
zero-native cef install --version 133.4.0+g6a9cf0f
```

```bash
zero-native cef install --dir /path/to/cef
```

```bash
zero-native cef install --force
```

```bash
zero-native cef doctor
```

```bash
zero-native cef path
```

```bash
zero-native doctor --manifest app.zon
```

--------------------------------

### Build Native Library for iOS

Source: https://github.com/vercel-labs/zero-native/blob/main/examples/ios/README.md

Build the static library using Zig and copy it to the expected location in the iOS example project.

```bash
zig build lib -Dtarget=aarch64-ios
mkdir -p examples/ios/Libraries
cp zig-out/lib/libzero-native.a examples/ios/Libraries/libzero-native.a
```

--------------------------------

### zero-native cef install

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/cli/page.mdx

Downloads, prepares, and verifies the macOS CEF runtime.

```APIDOC
## zero-native cef install

### Description
Download, prepare, and verify the macOS CEF runtime.

### Flags
- **--dir** (string) - Optional - CEF install directory. Defaults to the host platform directory under `third_party/cef`.
- **--version** (string) - Optional - CEF binary version to download. The default is zero-native's pinned tested version.
- **--source** (string) - Optional - `prepared` or `official`. Defaults to `prepared`, which downloads zero-native's no-CMake runtime from GitHub Releases.
- **--download-url** (string) - Optional - Override the prepared runtime release base URL, or the official CEF host when using `--source official`.
- **--allow-build-tools** (boolean) - Optional - Allow the advanced official CEF path to invoke local build tools for `libcef_dll_wrapper`.
- **--force** (boolean) - Optional - Redownload and replace the target directory.
```

--------------------------------

### Run Development Server with `zero-native dev`

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/frontend/page.mdx

Use the `zero-native dev` command to manage the frontend development server lifecycle. It starts the server, waits for it to be ready, and launches the native shell with the appropriate environment variable.

```bash
zero-native dev --binary zig-out/bin/MyApp
```

```bash
zero-native dev --binary zig-out/bin/MyApp --url http://127.0.0.1:3000/ --command "npm run dev"
```

--------------------------------

### Build and Run with Chromium Engine

Source: https://context7.com/vercel-labs/zero-native/llms.txt

Commands to install CEF, then build and run the application with the Chromium web engine. Demonstrates overriding the web engine and CEF directory via build flags.

```bash
zero-native cef install
zig build run
```

```bash
# One-off engine override without touching app.zon
zig build run -Dweb-engine=system
zig build run -Dweb-engine=chromium -Dcef-dir=third_party/cef/macos
```

```bash
# Bundle CEF into the app output
zig build cef-bundle -Dcef-dir=third_party/cef/macos
```

```bash
# Smoke-test Chromium rendering + bridge round-trip
zig build test-webview-cef-smoke -Dplatform=macos -Dweb-engine=chromium
```

```bash
# Verify packaged Chromium app contains CEF framework + resources
zig build test-package-cef-layout -Dplatform=macos

```

--------------------------------

### zero-native App Configuration (app.zon)

Source: https://github.com/vercel-labs/zero-native/blob/main/README.md

Example configuration file for a zero-native application. Specifies app metadata, web engine, permissions, capabilities, security policies for navigation, and window properties.

```zig
{
    .id = "com.example.my-app",
    .name = "my-app",
    .display_name = "My App",
    .version = "0.1.0",
    .web_engine = "system",
    .permissions = .{ "window" },
    .capabilities = .{ "webview", "js_bridge" },
    .security = .{
        .navigation = .{
            .allowed_origins = .{ "zero://app", "http://127.0.0.1:5173" },
        },
    },
    .windows = .{
        .{ .label = "main", .title = "My App", .width = 960, .height = 640 },
    },
}

```

--------------------------------

### Configure Dev Server URL and Command

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/cli/dev/page.mdx

Override the default frontend development server URL and the command used to start it. This is useful when `app.zon` does not specify these or you need to use different settings.

```bash
zero-native dev --binary zig-out/bin/MyApp --url http://127.0.0.1:3000/ --command "npm run dev"
```

--------------------------------

### macOS Beta Workflow with Chromium

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/quick-start/page.mdx

This sequence of commands outlines the process for setting up and running a zero-native app on macOS using the Chromium engine for beta testing. It includes installing CEF, building the app, packaging, and running diagnostics.

```bash
zero-native init my_app --frontend next
cd my_app
zig build run
zero-native cef install
zig build run
zero-native package --target macos --signing identity --identity "Developer ID Application: Your Name"
zero-native doctor --manifest app.zon --strict
```

--------------------------------

### Configure Runtime Trace Sink

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/debugging/page.mdx

Wires a trace sink into the runtime using RuntimeOptions.trace_sink. This example shows how to use a FanoutTraceSink.

```zig
var runtime = zero_native.Runtime.init(.{
    .platform = my_platform,
    .trace_sink = fanout.sink(),
});
```

--------------------------------

### Initialize and Run Embedded App

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/embed/page.mdx

Initializes an EmbeddedApp with application and platform contexts, then starts its runtime. This is used for embedding zero-native within an existing application or custom render loop.

```zig
var embedded = zero_native.embed.EmbeddedApp.init(my_app.app(), my_platform);

try embedded.start();

// In your render loop:
try embedded.frame();

// On resize:
try embedded.resize(new_surface);

// On shutdown:
try embedded.stop();
```

--------------------------------

### Sign and Package Chromium Apps

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/packaging/signing/page.mdx

For Chromium-based apps, first install the CEF version, then build the project, sign the package, and finally create a DMG. This ensures the CEF framework and all helper executables are covered by the distribution identity.

```bash
zero-native cef install --version <pinned-version>
```

```bash
zig build
```

```bash
zero-native package --target macos --signing identity --identity "Developer ID Application: Your Name"
```

```bash
hdiutil create -volname "Your App" -srcfolder zig-out/package/your-app.app -ov -format UDZO zig-out/package/your-app.dmg
```

--------------------------------

### Enable Automatic CEF Installation for Local Development

Source: https://github.com/vercel-labs/zero-native/blob/main/third_party/cef/README.md

Configures the build to automatically install CEF during the build process. This simplifies local development by handling CEF installation implicitly.

```sh
zig build run-webview -Dcef-auto-install=true
```

--------------------------------

### Initialize a zero-native Project

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/quick-start/page.mdx

Use this command to create a new zero-native project with a specified frontend framework. Navigate into the project directory afterward.

```bash
zero-native init my_app --frontend next
cd my_app
```

--------------------------------

### Register and Initialize Modules with ModuleRegistry

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/extensions/page.mdx

Demonstrates how to instantiate a module, define its capabilities, and register it with the `ModuleRegistry`. It then initializes the `zero_native.Runtime` with the custom registry.

```zig
var my_module = MyModule{};
const caps = [_]zero_native.extensions.Capability{.{ .kind = .native_module }};
const modules = [_]zero_native.extensions.Module{.{ 
    .info = .{ .id = 1, .name = "my-module", .capabilities = &caps },
    .context = &my_module,
    .hooks = .{ .start_fn = MyModule.start, .command_fn = MyModule.command },
}};
const registry = zero_native.extensions.ModuleRegistry{ .modules = &modules };

var runtime = zero_native.Runtime.init(.{
    .platform = my_platform,
    .extensions = registry,
});

```

--------------------------------

### JavaScript Usage Example

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/bridge/builtin-commands/page.mdx

Examples of how to invoke built-in bridge commands using JavaScript in the browser environment.

```APIDOC
```javascript
const win = await window.zero.windows.create({
  label: "tools",
  title: "Tools",
  width: 420,
  height: 320,
});

const files = await window.zero.invoke("zero-native.dialog.openFile", {
  title: "Select a file",
  allowMultiple: true,
});

const result = await window.zero.invoke("zero-native.dialog.showMessage", {
  style: "warning",
  title: "Confirm",
  message: "Are you sure?",
  primaryButton: "Yes",
  secondaryButton: "No",
});
```
```

--------------------------------

### Initialize Automation Server with Custom Directory

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/automation/page.mdx

Pass a custom path to `automation.Server.init()` to specify a different directory for automation files.

```zig
const server = zero_native.automation.Server.init(io, "/tmp/my-app-automation", "My App");
```

--------------------------------

### Create and Run a zero-native App

Source: https://github.com/vercel-labs/zero-native/blob/main/README.md

Initialize a new zero-native application with a Next.js frontend, navigate into the project directory, and run the application using Zig build.

```bash
zero-native init my_app --frontend next
cd my_app
zig build run
```

--------------------------------

### Check CEF Setup with Zero-Native Doctor

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/debugging/doctor/page.mdx

This command specifically checks the CEF (Chromium Embedded Framework) setup, validating the app.zon manifest file in the process.

```bash
zero-native doctor --manifest app.zon
```

--------------------------------

### Initialize Automation Server

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/automation/page.mdx

In your runner, pass an `automation.Server` instance to `RuntimeOptions`. The default directory is `.zig-cache/zero-native-automation`.

```zig
const server = zero_native.automation.Server.init(io, ".zig-cache/zero-native-automation", "My App");
var runtime = zero_native.Runtime.init(.{
    .platform = my_platform,
    .automation = server,
});
```

--------------------------------

### Minimal CSP for Inline Zig Examples

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/security/page.mdx

For inline Zig examples that embed scripts or styles, add minimal inline allowances to the Content Security Policy. This includes 'unsafe-inline' for script-src and style-src.

```html
<meta http-equiv="Content-Security-Policy"
  content="default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'">
```

--------------------------------

### Bundle Frontend Assets

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/packaging/page.mdx

If your app includes a frontend, use this command to bundle its output. These assets are served via `zero://app/` in production.

```bash
zig build bundle-assets
```

--------------------------------

### Define a Zig Module with Lifecycle Hooks

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/extensions/page.mdx

Defines a Zig struct representing a module with `start` and `command` lifecycle hooks. The `start` hook initializes module data, and the `command` hook handles specific commands like 'reset'.

```zig
const MyModule = struct {
    data: u32 = 0,

    fn start(context: *anyopaque, runtime: zero_native.extensions.RuntimeContext) anyerror!void {
        _ = runtime;
        const self: *@This() = @ptrCast(@alignCast(context));
        self.data = 42;
    }

    fn command(context: *anyopaque, runtime: zero_native.extensions.RuntimeContext, cmd: zero_native.extensions.Command) anyerror!void {
        _ = runtime;
        const self: *@This() = @ptrCast(@alignCast(context));
        if (std.mem.eql(u8, cmd.name, "reset")) self.data = 0;
    }
};

```

--------------------------------

### Package App with CLI Options

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/packaging/page.mdx

Use the zero-native CLI for more granular control over the packaging process, specifying target platform, manifest, and binary.

```bash
zero-native package --target macos --manifest app.zon --binary zig-out/bin/MyApp
```

--------------------------------

### zero-native init

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/cli/page.mdx

Scaffolds a new zero-native project. You can specify a path to initialize the project in, or omit it to use the current directory. The `--frontend` flag is required to select your preferred frontend framework.

```APIDOC
## zero-native init [path] --frontend <next|vite|react|svelte|vue>

### Description
Scaffold a new zero-native project with the specified frontend. Omit `path` to scaffold into the current directory.

### Parameters
#### Path Parameters
- **path** (string) - Optional - The directory to scaffold the project into. Defaults to the current directory if omitted.

#### Query Parameters
- **--frontend** (string) - Required - The frontend framework to use (e.g., `next`, `vite`, `react`, `svelte`, `vue`).
```

--------------------------------

### App Struct and WebViewSource Initialization

Source: https://context7.com/vercel-labs/zero-native/llms.txt

Defines the MyApp struct and its app method, which returns a zero_native.App descriptor. This includes setting up the WebViewSource (either inline HTML or dynamic), and defining lifecycle callbacks like onStart, onEvent, and onStop.

```zig
const std = @import("std");
const zero_native = @import("zero-native");

const MyApp = struct {
    ping_count: u32 = 0,
    env_map: std.process.EnvMap,

    // Return the App descriptor
    fn app(self: *@This()) zero_native.App {
        return .{
            .context = self,
            .name = "my-app",
            // Option 1: inline HTML
            .source = zero_native.WebViewSource.html(
                \<!doctype html><html><body>
                \  <h1>Hello from zero-native</h1>
                \</body></html>
            ),
            // Option 2: dynamic source (dev server or bundled assets)
            // .source_fn = source,
            .start_fn = onStart,
            .event_fn = onEvent,
            .stop_fn = onStop,
        };
    }

    // Dynamic source: dev server in dev, bundled assets in production
    fn source(context: *anyopaque) anyerror!zero_native.WebViewSource {
        const self: *@This() = @ptrCast(@alignCast(context));
        return zero_native.frontend.sourceFromEnv(self.env_map, .{
            .dist = "frontend/dist",
            .entry = "index.html",
        });
    }

    fn onStart(context: *anyopaque, runtime: *zero_native.Runtime) anyerror!void {
        _ = context;
        _ = runtime;
        std.debug.print("App started\n", .{});
    }

    fn onEvent(context: *anyopaque, runtime: *zero_native.Runtime, ev: zero_native.Event) anyerror!void {
        _ = context;
        _ = runtime;
        switch (ev) {
            .lifecycle => |lc| std.debug.print("lifecycle: {s}\n", .{@tagName(lc)}),
            .command => |cmd| std.debug.print("command: {s}\n", .{cmd.name}),
        }
    }

    fn onStop(context: *anyopaque, runtime: *zero_native.Runtime) anyerror!void {
        _ = context;
        _ = runtime;
        std.debug.print("App stopping\n", .{});
    }
};

// WebViewSource constructors:
// .html("...") — inline HTML at zero://inline
// .url("http://127.0.0.1:5173/") — remote or local URL
// .assets(.{ .root_path = "dist", .entry = "index.html", .origin = "zero://app", .spa_fallback = true })

```

--------------------------------

### Verify CEF Layout

Source: https://github.com/vercel-labs/zero-native/blob/main/third_party/cef/README.md

Verifies the CEF runtime layout at a specified directory before building the application. This helps ensure the CEF installation is correctly structured.

```sh
zero-native doctor --manifest app.zon --cef-dir /path/to/cef
```

--------------------------------

### Configure WebView Assets Source

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/app-model/page.mdx

Use the `WebViewSource.assets` constructor to serve local files. Specify the root directory, entry point, origin, and SPA fallback behavior.

```zig
.source = zero_native.WebViewSource.assets(.{
    .root_path = "dist",
    .entry = "index.html",      // default
    .origin = "zero://app",     // default
    .spa_fallback = true,       // default
}),
```

--------------------------------

### Package Application for Windows

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/packaging/page.mdx

Use the zero-native CLI shortcut command to package your application specifically for Windows. Optional arguments allow specifying output and binary paths.

```bash
zero-native package-windows [--output path] [--binary path]
```

--------------------------------

### Initialize NullPlatform and Runtime

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/testing/page.mdx

Initializes NullPlatform, a headless platform stub, and a Runtime using it. NullPlatform records loaded sources and dispatched events without creating real windows, making it suitable for tests and EmbeddedApp.

```zig
var null_platform = zero_native.NullPlatform.init(.{});
var runtime = zero_native.Runtime.init(.{
    .platform = null_platform.platform(),
});
```

--------------------------------

### Set Dev Server Timeout

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/cli/dev/page.mdx

Adjust the maximum time in milliseconds to wait for the frontend development server to become ready. This can be useful for slower starting applications.

```bash
zero-native dev --binary zig-out/bin/MyApp --timeout-ms 60000
```

--------------------------------

### Initialize and Run Zero Native Runtime

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/app-model/page.mdx

Initialize the Zero Native runtime with platform, trace sink, bridge configurations, security policies, and window state persistence. Then, run the application using the initialized runtime.

```zig
var runtime = zero_native.Runtime.init(.{
    .platform = my_platform,
    .trace_sink = fanout.sink(),
    .bridge = my_app.bridge(),
    .builtin_bridge = .{ .enabled = true, .commands = &builtin_policies },
    .security = .{
        .permissions = &app_permissions,
        .navigation = .{ .allowed_origins = &.{ "zero://app" } },
    },
    .js_window_api = true,
    .window_state_store = state_store,
    .automation = if (build_options.automation) automation_server else null,
});
try runtime.run(my_app.app());
```

--------------------------------

### Create and Manage Windows in Zig

Source: https://context7.com/vercel-labs/zero-native/llms.txt

Use `runtime.createWindow`, `runtime.focusWindow`, `runtime.listWindows`, and `runtime.closeWindow` for window management. Requires `js_window_api = true` and `window` permission.

```zig
// Zig: enable js_window_api with window permission
const app_permissions = [_][]const u8{ zero_native.security.permission_window };
// In RuntimeOptions:
// .security =Аналогично .{ .permissions = &app_permissions, ... },
// .js_window_api = true,

// Create a secondary window from Zig directly
const info = try runtime.createWindow(.{
    .label = "tools",
    .title = "Tools",
    .default_frame = zero_native.geometry.RectF.init(80, 80, 420, 320),
});
try runtime.focusWindow(info.id);
const windows = runtime.listWindows(); // []WindowInfo
try runtime.closeWindow(info.id);

```

--------------------------------

### Implement Analytics Module with ModuleRegistry

Source: https://context7.com/vercel-labs/zero-native/llms.txt

Defines an AnalyticsModule with start, command, and stop hooks. It registers this module with the ModuleRegistry and validates it. The registry is then used to initialize the zero-native Runtime.

```zig
const zero_native = @import("zero-native");
const std = @import("std");

const AnalyticsModule = struct {
    event_count: u32 = 0,

    fn start(context: *anyopaque, runtime: zero_native.extensions.RuntimeContext) anyerror!void {
        _ = runtime;
        const self: *@This() = @ptrCast(@alignCast(context));
        self.event_count = 0;
        std.debug.print("Analytics module started\n", .{});
    }

    fn command(context: *anyopaque, runtime: zero_native.extensions.RuntimeContext, cmd: zero_native.extensions.Command) anyerror!void {
        _ = runtime;
        const self: *@This() = @ptrCast(@alignCast(context));
        if (std.mem.eql(u8, cmd.name, "analytics.reset")) self.event_count = 0;
    }

    fn stop(context: *anyopaque, runtime: zero_native.extensions.RuntimeContext) anyerror!void {
        _ = context;
        _ = runtime;
        std.debug.print("Analytics module stopped\n", .{});
    }
};

var analytics = AnalyticsModule{};
const caps = [_]zero_native.extensions.Capability{.{ .kind = .native_module }};
const modules = [_]zero_native.extensions.Module{.{ 
    .info = .{ .id = 1, .name = "analytics", .capabilities = &caps },
    .context = &analytics,
    .hooks = .{ 
        .start_fn   = AnalyticsModule.start,
        .command_fn = AnalyticsModule.command,
        .stop_fn    = AnalyticsModule.stop,
    },
}};
const registry = zero_native.extensions.ModuleRegistry{ .modules = &modules };
try registry.validate(); // checks for duplicate module IDs

// Check capabilities
const has_fs = registry.hasCapability(.filesystem); // false

// Pass to runtime
var runtime = zero_native.Runtime.init(.{
    .platform = my_platform,
    .extensions = registry,
});

```

--------------------------------

### Set Minimum CMake Version and Project Name

Source: https://github.com/vercel-labs/zero-native/blob/main/examples/android/app/src/main/cpp/CMakeLists.txt

Specifies the minimum required CMake version and declares the project name. This is a standard starting point for any CMake project.

```cmake
cmake_minimum_required(VERSION 3.22.1)

project(zero_native_android_example C)
```

--------------------------------

### Package Application for Linux

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/packaging/page.mdx

Use the zero-native CLI shortcut command to package your application specifically for Linux. Optional arguments allow specifying output and binary paths.

```bash
zero-native package-linux [--output path] [--binary path]
```

--------------------------------

### Dynamic Source Function with `sourceFromEnv`

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/frontend/page.mdx

Use this function with `App` to dynamically switch between a development server (using `ZERO_NATIVE_FRONTEND_URL`) and bundled assets for production. It checks the environment variable specified in `dev_url_env`.

```zig
fn source(context: *anyopaque) anyerror!zero_native.WebViewSource {
    const self: *App = @ptrCast(@alignCast(context));
    return zero_native.frontend.sourceFromEnv(self.env_map, .{
        .dist = "dist",
        .entry = "index.html",
    });
}
```

--------------------------------

### Run Framework Tests

Source: https://github.com/vercel-labs/zero-native/blob/main/CONTRIBUTING.md

Execute the framework's test suite using the Zig build system.

```bash
zig build test
```

--------------------------------

### Create and Focus Secondary Window in Zig

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/windows/page.mdx

Use `runtime.createWindow` to create a new window with specified options and `runtime.focusWindow` to bring it to the foreground. Ensure the `label` and `title` are descriptive.

```zig
const info = try runtime.createWindow(.{
    .label = "tools",
    .title = "Tools",
    .default_frame = zero_native.geometry.RectF.init(80, 80, 420, 320),
});
try runtime.focusWindow(info.id);
```

--------------------------------

### Enable Builtin Bridge Commands in Zig

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/bridge/builtin-commands/page.mdx

Configure the `builtin_bridge` policy in `RuntimeOptions` to enable specific window and dialog commands. This example shows how to enable `zero-native.window.list`, `zero-native.window.create`, `zero-native.dialog.openFile`, and `zero-native.dialog.showMessage` for the `zero://app` origin.

```zig
const app_permissions = [_][]const u8{zero_native.security.permission_window};

.security = .{
    .permissions = &app_permissions,
    .navigation = .{ .allowed_origins = &.{ "zero://app" } },
},
.builtin_bridge = .{
    .enabled = true,
    .commands = &.{ 
        .{ .name = "zero-native.window.list", .permissions = .{ "window" }, .origins = .{ "zero://app" } },
        .{ .name = "zero-native.window.create", .permissions = .{ "window" }, .origins = .{ "zero://app" } },
        .{ .name = "zero-native.dialog.openFile", .origins = .{ "zero://app" } },
        .{ .name = "zero-native.dialog.showMessage", .origins = .{ "zero://app" } },
    },
},
```

--------------------------------

### Test Embedded App with NullPlatform

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/embed/page.mdx

Initializes an EmbeddedApp for testing purposes using a NullPlatform. This setup allows for testing the embedded application's behavior, such as loading HTML content, without a full platform implementation.

```zig
var null_platform = zero_native.NullPlatform.init(.{});
var state: u8 = 0;
var embedded = zero_native.embed.EmbeddedApp.init(.{
    .context = &state,
    .name = "embedded",
    .source = zero_native.WebViewSource.html("<p>Embedded</p>"),
}, null_platform.platform());

try embedded.start();
// null_platform.loaded_source now contains the loaded HTML
```

--------------------------------

### CLI: Dump Snapshot

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/automation/page.mdx

Dump the current runtime snapshot, including app name, source kind, window metadata, and ready status.

```bash
zero-native automate snapshot
```

--------------------------------

### Allowlist Main-Frame Navigation Origins

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/security/page.mdx

Configure allowed origins for main-frame navigation. Packaged assets use 'zero://app', inline examples use 'zero://inline', and dev servers should list their exact local origin.

```zig
.security = .{
    .navigation = .{
        .allowed_origins = .{
            "zero://app",
            "zero://inline",
            "http://127.0.0.1:5173",
        },
    },
},
```

--------------------------------

### Configure JavaScript Window API and Permissions

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/windows/page.mdx

To enable JavaScript window creation, configure application permissions to include `zero_native.security.permission_window` and set `js_window_api` to true. Define allowed origins for security.

```zig
const app_permissions = [_][]const u8{zero_native.security.permission_window};
.security = .{
    .permissions = &app_permissions,
    .navigation = .{ .allowed_origins = &.{ "zero://app" } },
},
.js_window_api = true,
```

--------------------------------

### Build CEF from Source for Maintainers

Source: https://github.com/vercel-labs/zero-native/blob/main/third_party/cef/README.md

A script for core maintainers to build CEF from source. It uses CEF's automation tools, depot_tools, CMake, and the platform compiler to produce a CEF runtime archive. App developers should use `zero-native cef install` instead.

```sh
tools/cef/build-from-source.sh --platform macosarm64 --cef-branch <branch> --output zig-out/cef
```

--------------------------------

### Zig: Dynamic Frontend Source Loading

Source: https://context7.com/vercel-labs/zero-native/llms.txt

Dynamically determines the WebView source, switching between a development server and bundled production assets based on the ZERO_NATIVE_FRONTEND_URL environment variable. Falls back to local assets if the variable is not set.

```zig
// Zig: dynamic source — dev server or production assets
fn source(context: *anyopaque) anyerror!zero_native.WebViewSource {
    const self: *MyApp = @ptrCast(@alignCast(context));
    // Checks ZERO_NATIVE_FRONTEND_URL; falls back to .assets({ .root_path = "dist" })
    return zero_native.frontend.sourceFromEnv(self.env_map, .{
        .dist        = "frontend/dist",
        .entry       = "index.html",
        .origin      = "zero://app",
        .spa_fallback = true,
    });
}

// For packaged builds that always use local assets:
fn sourceProd(context: *anyopaque) anyerror!zero_native.WebViewSource {
    _ = context;
    return zero_native.frontend.productionSource(.{
        .dist  = "frontend/dist",
        .entry = "index.html",
    });
}
```

--------------------------------

### TrayOptions

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/tray/page.mdx

Configuration options for creating a system tray icon.

```APIDOC
## TrayOptions

Configuration options for creating a system tray icon.

- **icon_path** (`[]const u8`): Path to the icon file. Defaults to `""`.
- **tooltip** (`[]const u8`): Tooltip text displayed when hovering over the icon. Defaults to `""`.
- **items** (`[]const TrayMenuItem`): An array of menu items to display in the tray menu. Defaults to an empty array.
```

--------------------------------

### RuntimeOptions

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/app-model/page.mdx

Configuration options for initializing the Zero Native runtime.

```APIDOC
## RuntimeOptions

### Fields

- **platform** (`Platform`) - Required - Platform abstraction (macOS, Linux, or NullPlatform).
- **trace_sink** (`?trace.Sink`) - Optional - Destination for structured trace records. Defaults to `null`.
- **log_path** (`?[]const u8`) - Optional - Path for persistent log file. Defaults to `null`.
- **extensions** (`?ModuleRegistry`) - Optional - Extension modules with lifecycle hooks. Defaults to `null`.
- **bridge** (`?BridgeDispatcher`) - Optional - App-defined bridge commands and handlers. Defaults to `null`.
- **builtin_bridge** (`BridgePolicy`) - Required - Policy for built-in commands (dialogs, windows). Defaults to `{}`.
- **security** (`SecurityPolicy`) - Required - Navigation allowlist, external links, permissions. Defaults to `{}`.
- **automation** (`?automation.Server`) - Optional - File-based automation server for testing. Defaults to `null`.
- **window_state_store** (`?window_state.Store`) - Optional - Persistent window geometry and state. Defaults to `null`.
- **js_window_api** (`bool`) - Required - Expose `window.zero.windows.*`; origin and `window` permission checks still apply. Defaults to `false`.
```

--------------------------------

### Package Application for iOS

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/packaging/page.mdx

Use the zero-native CLI shortcut command to package your application specifically for iOS. Optional arguments allow specifying output and binary paths.

```bash
zero-native package-ios [--output path] [--binary path]
```

--------------------------------

### Package Application for Android

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/packaging/page.mdx

Use the zero-native CLI shortcut command to package your application specifically for Android. Optional arguments allow specifying output and binary paths.

```bash
zero-native package-android [--output path] [--binary path]
```

--------------------------------

### Build and Copy Native Library

Source: https://github.com/vercel-labs/zero-native/blob/main/examples/android/README.md

Build the Android static library using zig and copy it to the expected location in the Android project. Ensure the target architecture is correctly specified.

```bash
zig build lib -Dtarget=aarch64-linux-android
mkdir -p examples/android/app/src/main/cpp/lib
cp zig-out/lib/libzero-native.a examples/android/app/src/main/cpp/lib/libzero-native.a
```

--------------------------------

### Bash: Frontend Development and Build Commands

Source: https://context7.com/vercel-labs/zero-native/llms.txt

Commands for managing frontend development with React/Vite and Next.js, including building assets and serving the application. Also includes a command to bundle frontend assets for packaging.

```bash
# React/Vite example — run with hot-reloading dev server
cd examples/react
zig build run           # first run installs npm deps automatically
zig build dev           # managed dev server mode

# Next.js example — build and serve bundled assets
cd examples/next
npm --prefix frontend run build   # outputs to frontend/out
zig build run                     # serves zero://app from frontend/out

# Bundle frontend assets into the build output for packaging
zig build bundle-assets
```

--------------------------------

### Define Permissions and Capabilities

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/security/page.mdx

Declare the broad features your app uses with `capabilities` and the runtime grants required for native commands with `permissions`.

```zig
.permissions = .{"window", "filesystem"},
.capabilities = .{"webview", "js_bridge"},

```

--------------------------------

### CLI: Wait for App Ready

Source: https://github.com/vercel-labs/zero-native/blob/main/docs/src/app/automation/page.mdx

Use the `wait` command to poll `snapshot.txt` until the app is ready (`ready=true`).

```bash
zero-native automate wait
```