zero-native

https://zero-native.dev
Admin
zero-native is a framework for building native desktop applications with web UI using Zig and system...
Tokens:18,807
Snippets:255
Trust Score:2.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Panic Capture Handler

Source: https://zero-native.dev/debugging

Installs the panic capture handler during application startup. Requires an IO object and the paths to log setup.

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

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

### Install and Run CEF

Source: https://zero-native.dev/web-engines

Use the zero-native CLI to install the CEF runtime and then build and run the application.

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

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

### CLI Setup for CEF

Source: https://zero-native.dev/web-engines

Install the CEF runtime using the CLI and then run a doctor check on the application manifest.

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

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

### EmbeddedApp Initialization Example

Source: https://zero-native.dev/embed

Example demonstrating how to initialize and use the EmbeddedApp for testing purposes.

```APIDOC
## Testing with EmbeddedApp

```
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
```
```

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

### Testing EmbeddedApp with NullPlatform

Source: https://zero-native.dev/embed

This example demonstrates testing the EmbeddedApp with a NullPlatform, useful for isolated testing scenarios. It initializes the app with a simple HTML source and starts it, allowing verification of the loaded content via null_platform.loaded_source.

```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
```

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

### Hello World App in Zero-Native

Source: https://zero-native.dev/quick-start

A minimal Zero-Native application example that displays a simple 'Hello from zero-native' message using inline HTML.

```zig
const HelloApp = struct {
    fn app(self: *@This()) zero_native.App {
        return .{ 
            .context = self,
            .name = "hello",
            .source = zero_native.WebViewSource.html(
                \<!doctype html>
                \<html>
                \<body style="font-family: system-ui; padding: 2rem;">
                \  <h1>Hello from zero-native</h1>
                \</body>
                \</html>
            ),
        };
    }
};

```

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

### Initialize and Run a zero-native App

Source: https://zero-native.dev/

Use this command sequence to initialize a new zero-native project with a Next.js frontend, install its dependencies, and run the application for the first time.

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

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

### Handling tray actions

Source: https://zero-native.dev/tray

Example of how to handle user interactions with the system 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
            }
        },
        else => {},
    }
}
```
```

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

### Install zero-native CLI

Source: https://zero-native.dev/packages

Install the zero-native CLI globally using npm. This command installs the zero-native package, which includes prebuilt binaries for macOS, Linux, and Windows.

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

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

### Run Zero-Native Application

Source: https://zero-native.dev/quick-start

Builds and runs the Zero-Native application. The first run automatically installs frontend dependencies.

```bash
zig build run
```

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

### Run Zero-Native Dev Server

Source: https://zero-native.dev/cli/dev

Execute the dev server with your native binary. You can override the frontend URL and the command used to start the dev server, or set a custom readiness 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
```

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

### Initialize Runtime with Options

Source: https://zero-native.dev/app-model

Initialize the Zero Native runtime with various options, including platform, trace sink, security policies, and window state persistence. The runtime is then started with the application.

```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());
```

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

### Typical CEF Workflow

Source: https://zero-native.dev/packaging

This sequence outlines the typical workflow for developing with the Chromium engine, including installing CEF, building the app, and packaging.

```bash
zero-native cef install --version <pinned-version>
zig build
zero-native package --target macos
```

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

### app.zon Manifest Example

Source: https://zero-native.dev/app-zon

This is a complete example of an app.zon manifest file. It declares essential app metadata, permissions, bridge policies, security rules, and window layout.

```json
.{
    .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 },
    },
}

```

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

### Define a Zero-Native Module with Lifecycle Hooks

Source: https://zero-native.dev/extensions

Defines a module structure with data and implements 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 Application for Linux

Source: https://zero-native.dev/packaging

Shortcut command to package your application for Linux, including desktop entry and icon installation. Optional arguments for output directory and binary path are available.

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

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

### Automatic CEF Installation during Build

Source: https://zero-native.dev/web-engines

Enable automatic installation of the CEF runtime during the build process by setting '.auto_install' to true in the app.zon manifest.

```zig
.cef = .{ .dir = "third_party/cef/<platform>", .auto_install = true }
```

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

### Manage Frontend Dev Server Lifecycle

Source: https://zero-native.dev/frontend

Use the `zero-native dev` command to manage the frontend server. It starts the process, waits for connections, launches the native shell, and terminates the frontend when the shell exits.

```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"
```

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

### Check CEF setup with zero-native doctor

Source: https://zero-native.dev/debugging/doctor

This command checks the CEF setup and validates the app.zon manifest file.

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

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

### Configure Runtime Trace Sink

Source: https://zero-native.dev/debugging

Wires a trace sink into the zero-native runtime using RuntimeOptions.trace_sink. This example uses a fanout sink.

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

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

### macOS Beta Path for Zero-Native

Source: https://zero-native.dev/quick-start

Steps for validating an app on macOS using the beta path, including CEF installation and packaging. Ensure app.zon is configured for Chromium.

```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 Frontend Settings in app.zon

Source: https://zero-native.dev/frontend

Configure frontend build paths, entry points, and development server settings within your app.zon file. This setup is crucial for managing how your frontend assets are handled.

```json
.frontend = .{
    .dist = "dist",
    .entry = "index.html",
    .spa_fallback = true,
    .dev = .{
        .url = "http://127.0.0.1:5173/",
        .command = .{"npm", "run", "dev", "--", "--host", "127.0.0.1"},
        .ready_path = "/",
        .timeout_ms = 30000,
    },
}
```

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

### JavaScript Usage of Builtin Commands

Source: https://zero-native.dev/bridge/builtin-commands

Examples of how to use built-in Zero-Native commands from JavaScript, including creating a window, opening a file dialog, and showing a message dialog. Ensure the `builtin_bridge` policy is correctly configured in your runtime options.

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

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

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

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

### Define File Filters for Dialogs

Source: https://zero-native.dev/dialogs

Example of how to define file filters for use with dialogs. This structure specifies display names and associated file extensions.

```zig
const filters = [_]zero_native.FileFilter{
    .{ .name = "Images", .extensions = &.{ "png", "jpg", "gif" } },
    .{ .name = "All Files", .extensions = &.{ "*" } },
};
```

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

### Sign and Package CEF Apps for macOS

Source: https://zero-native.dev/packaging/signing

This sequence installs a specific CEF version, builds the project, signs the macOS package, and creates a DMG. This is for Chromium-based applications where CEF needs to be bundled and signed correctly.

```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
```

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

### Verify CEF Package Layout on macOS

Source: https://zero-native.dev/packaging

Use this command to verify that the packaged macOS application correctly includes the CEF framework and resource files. It requires a local CEF layout or automatic installation.

```bash
zig build test-package-cef-layout -Dplatform=macos
```

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

### Create a Zero-Native Project

Source: https://zero-native.dev/quick-start

Initializes a new Zero-Native project with a specified frontend framework. Navigate into the project directory after creation.

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

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

### Initialize NullPlatform and Runtime

Source: https://zero-native.dev/testing

Initializes NullPlatform for headless testing and sets up a Runtime with it. NullPlatform records loaded sources and dispatched events without creating real windows.

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

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

### Initialize Automation Server with Custom Directory

Source: https://zero-native.dev/automation

Initialize the automation server with a custom directory path instead of the default.

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

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

### Build and Package Application

Source: https://zero-native.dev/packaging

Use these commands to build and package your application. The first command performs a standard build and package, while the second offers more control via the CLI.

```bash
zig build package
```

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

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

### Create and Focus Window from Zig

Source: https://zero-native.dev/windows

Use `runtime.createWindow` to create a new window with specified options and `runtime.focusWindow` to bring it to the foreground. Requires the `runtime` and `zero_native` modules.

```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);
```

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

### Configure WebView Assets

Source: https://zero-native.dev/app-model

Use the `assets` constructor for WebViewSource to serve local files. Specify the root path, 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
}),
```

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

### CLI: Dump Snapshot

Source: https://zero-native.dev/automation

Retrieve and display the current runtime state, including app name, window metadata, and readiness status.

```bash
# Dump the current snapshot
zero-native automate snapshot
```

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

### Bundle Frontend Assets

Source: https://zero-native.dev/packaging

Use this command to bundle your frontend assets. This copies the configured `dist` directory into the build output, making assets accessible via `zero://app/`.

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

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

### Configure System WebView

Source: https://zero-native.dev/web-engines

Set the web engine to 'system' to use the OS's default WebView. This option has no bundled browser dependency.

```zig
.web_engine = "system",
```

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

### Register and Initialize a Zero-Native Module

Source: https://zero-native.dev/extensions

Registers a defined module with the ModuleRegistry and initializes the Zero-Native runtime with the registry. Ensure capabilities are correctly defined for the module.

```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,
});

```

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

### Configure External Link Handling

Source: https://zero-native.dev/security

Opt into opening external links in the system browser by specifying an action and a list of allowed URL prefixes.

```zig
.security = .{
    .navigation = .{
        .external_links = .{
            .action = "open_system_browser",
            .allowed_urls = .{ "https://example.com/docs/*" },
        },
    },
},

```

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

### Initialize and Control Embedded App Runtime

Source: https://zero-native.dev/embed

Use this snippet to initialize an EmbeddedApp and control its lifecycle within your application's event loop. Ensure proper error handling for start, frame, resize, and stop operations.

```javascript
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();
```

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

### Create, List, Focus, and Close Windows from JavaScript

Source: https://zero-native.dev/windows

Utilize the `window.zero.windows` API in JavaScript to create new windows, list all open windows, focus a specific window by its ID, and close a window. Ensure the JavaScript is executed from an allowed origin.

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

const all = await window.zero.windows.list();
await window.zero.windows.focus(win.id);
await window.zero.windows.close(win.id);
```

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

### Zero-Native Configuration in app.zon

Source: https://zero-native.dev/cli/dev

Configure frontend development server settings within the `app.zon` manifest file. This includes the distribution directory, entry point, SPA fallback behavior, and specific development server configurations like URL, command, ready path, and timeout.

```zig
.frontend = .{\n    .dist = "dist",\n    .entry = "index.html",\n    .spa_fallback = true,\n    .dev = .{\n        .url = "http://127.0.0.1:5173/",\n        .command = .{ "npm", "run", "dev", "--", "--host", "127.0.0.1" },\n        .ready_path = "/",\n        .timeout_ms = 30000,\n    },\n}
```

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

### Package Application for iOS

Source: https://zero-native.dev/packaging

Shortcut command for experimental packaging of your application for iOS. Optional arguments for output directory and binary path are available.

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

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

### Package Application for Android

Source: https://zero-native.dev/packaging

Shortcut command for experimental packaging of your application for Android. Optional arguments for output directory and binary path are available.

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

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

### Define Permissions and Capabilities

Source: https://zero-native.dev/security

Declare broad app features with capabilities and runtime grants with permissions. Use the smallest set required for your app.

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

```

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

### Package Application for Windows

Source: https://zero-native.dev/packaging

Shortcut command to package your application specifically for Windows. Optional arguments for output directory and binary path are available.

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

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

### Initialize Automation Server in Runner

Source: https://zero-native.dev/automation

Pass an initialized `zero_native.automation.Server` to `RuntimeOptions` in your runner code. 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,
});
```

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

### CLI: Reload WebView

Source: https://zero-native.dev/automation

Instruct the runtime to reload the WebView source code.

```bash
# Reload the WebView
zero-native automate reload
```

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

### Declare Main Window in app.zon

Source: https://zero-native.dev/windows

Define the main window configuration within the `app.zon` file, specifying its label, title, dimensions, and whether to restore its state on startup. This is crucial for application initialization.

```json
.windows = .{
    .{ .label = "main", .title = "zero-native", .width = 720, .height = 480, .restore_state = true },
},
```

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

### RuntimeOptions Fields

Source: https://zero-native.dev/app-model

Configuration options for initializing the Runtime.

```APIDOC
## RuntimeOptions

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

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

### Initialize FileTraceSink

Source: https://zero-native.dev/debugging

Initializes a FileTraceSink to append trace records to a file on disk. Requires an IO object, log directory, log file name, and format.

```zig
var file_sink = zero_native.debug.FileTraceSink.init(io, log_dir, log_file, .json_lines);
```

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

### Configure app.zon for Packaging

Source: https://zero-native.dev/packaging

The `app.zon` manifest file drives packaging metadata. Ensure fields like `id`, `name`, `version`, `icons`, and `platforms` are correctly set for your application.

```zig
.{
    .id = "com.example.myapp",
    .name = "myapp",
    .display_name = "My App",
    .version = "1.0.0",
    .icons = .{ "assets/icon.icns", "assets/icon.ico" },
    .platforms = .{ "macos", "linux" },
    .web_engine = "system",
    .cef = .{ .dir = "third_party/cef/macos", .auto_install = false },
}
```

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

### CLI: Wait for App Ready

Source: https://zero-native.dev/automation

Use the `zero-native automate wait` command to block execution until the application's snapshot indicates `ready=true`.

```bash
# Wait for the app to be ready (polls snapshot.txt for ready=true)
zero-native automate wait
```

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

### TrayOptions

Source: https://zero-native.dev/tray

Configuration options for creating or updating a system tray icon.

```APIDOC
## TrayOptions

Field| Type| Default  
---|---|---  
`icon_path`| `[]const u8`| `""`  
`tooltip`| `[]const u8`| `""`  
`items`| `[]const TrayMenuItem`| `&.`
```

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

### PlatformServices methods

Source: https://zero-native.dev/tray

Methods available for managing the system tray icon and its menu.

```APIDOC
## PlatformServices methods

* `createTray(options)` -- create or replace the tray icon
* `updateTrayMenu(items)` -- update menu items without recreating the tray
* `removeTray()` -- remove the tray icon
```

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

### Configure Permissions for JavaScript Window API

Source: https://zero-native.dev/windows

Before using JavaScript to create windows, configure application permissions to include `zero_native.security.permission_window` and specify allowed origins. This snippet shows the security configuration object.

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

.security = .{
    .permissions = &app_permissions,
    .navigation = .{ .allowed_origins = &.{ "zero://app" } },
},
.js_window_api = true,
```

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

### CLI: Capture Screenshot

Source: https://zero-native.dev/automation

Capture a screenshot of the running application. The output is currently a 2x2 placeholder in PPM format.

```bash
# Capture a screenshot
zero-native automate screenshot
```

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

### Build with Debug Overlay

Source: https://zero-native.dev/debugging

Builds and runs the webview application with the debug overlay enabled using the -Ddebug-overlay=true flag. This provides a visual debugging interface.

```bash
zig build run-webview -Ddebug-overlay=true
```

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

### WebViewSource Constructors

Source: https://zero-native.dev/app-model

Methods for specifying the initial content of a WebView.

```APIDOC
## WebViewSource

Three constructors for specifying what the WebView loads:

*   **`.html(content)`**
    Inline HTML string, served as `zero://inline`.

*   **`.url(address)`**
    Load a remote or local URL.

*   **`.assets(options)`**
    Serve a local file tree through a custom origin.

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

    Field| Default| Description
    ---|---|---
    `root_path`| required| Path to the directory containing frontend assets
    `entry`| `"index.html"`| HTML entry point within the root path
    `origin`| `"zero://app"`| Origin used for asset URLs
    `spa_fallback`| `true`| Serve entry for unknown routes (SPA mode)
```

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

### Package for Windows

Source: https://zero-native.dev/packaging

Command to package the application for the Windows target. Note that Windows packaging is in early development.

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

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

### Dynamic Frontend Source Function

Source: https://zero-native.dev/frontend

Use this function on your App to dynamically switch between a development server and bundled production assets based on environment variables.

```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",
    });
}
```

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

### Package for Linux

Source: https://zero-native.dev/packaging

Command to package the application specifically for the Linux target. Ensure the manifest and binary path are correct.

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

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

### Configure Chromium (CEF) Engine

Source: https://zero-native.dev/web-engines

Set the web engine to 'chromium' and specify the CEF directory. Ensure 'auto_install' is set to false if managing CEF manually.

```zig
.web_engine = "chromium",
```

```zig
.cef = .{ .dir = "third_party/cef/<platform>", .auto_install = false },
```

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

### Frontend Dev Server Configuration

Source: https://zero-native.dev/app-zon

Configures the managed dev server for `zero-native dev` and `zig build dev`. Specify the distribution directory, entry point, SPA fallback behavior, and dev server details.

```json
.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,
    },
},

```

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

### CLI: List Automation Apps

Source: https://zero-native.dev/automation

List all running applications that have been enabled for automation.

```bash
# List running automation-enabled apps
zero-native automate list
```

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

### Build Test WebView Smoke

Source: https://zero-native.dev/automation

Build the `test-webview-smoke` step, typically used for end-to-end testing of the WebView integration.

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

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

### Configure Frontend Assets in app.zon

Source: https://zero-native.dev/packaging

Configure frontend asset bundling within the `app.zon` manifest. Specify the distribution directory, entry point, and SPA fallback behavior.

```zig
.frontend = .{ .dist = "dist", .entry = "index.html", .spa_fallback = true }
```

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

### Enable Automation Build Flag

Source: https://zero-native.dev/automation

Build your Zig project with the automation flag enabled to activate the automation server.

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

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

### Create Distributable Disk Image

Source: https://zero-native.dev/packaging/signing

Use this command to build a distributable disk image (.dmg) for your macOS application. This is typically done after the application has been packaged and signed.

```bash
zig build dmg
```

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

### Create FanoutTraceSink

Source: https://zero-native.dev/debugging

Creates a FanoutTraceSink to broadcast trace records to multiple child sinks, such as stdout and a file sink. Requires an array of sinks.

```zig
var sinks = [_]trace.Sink{ stdout_sink.sink(), file_sink.sink() };
var fanout = zero_native.debug.FanoutTraceSink{ .sinks = &sinks };
```

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

### Enable Builtin Commands with Runtime Options

Source: https://zero-native.dev/bridge/builtin-commands

Configure the `builtin_bridge` policy in `RuntimeOptions` to enable specific built-in commands and define allowed origins and permissions. This is necessary for dialog commands which are default-deny.

```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" } },
    },
},
```

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

### Local Release Testing with Zig Build Notarize

Source: https://zero-native.dev/packaging/signing

This command is a helper for local release testing of the notarization process. It does not invoke `xcrun notarytool` directly. After running, manually submit the signed package for notarization.

```bash
zig build notarize
```

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

### Production Frontend Source

Source: https://zero-native.dev/frontend

Return a production source configuration that always uses local assets. This is suitable for packaged builds where a development server is not needed.

```zig
return zero_native.frontend.productionSource(.{ .dist = "dist", .entry = "index.html" });
```

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

### Submit Signed Package for Notarization

Source: https://zero-native.dev/packaging/signing

Manually submit your signed application package for notarization using `xcrun notarytool`. This command requires your Apple ID, Team ID, and a keychain-stored password. The `--wait` flag ensures the command blocks until notarization is complete.

```bash
xcrun notarytool submit zig-out/package/your-app.zip --apple-id "you@example.com" --team-id "TEAMID" --password "@keychain:AC_PASSWORD" --wait
```

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

### Handle System Tray Actions

Source: https://zero-native.dev/tray

Use your `event_fn` to handle `"tray.action"` commands dispatched when a user clicks a system tray menu item. This snippet shows how to check the event type and command name.

```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
            }
        },
        else => {},
    }
}
```

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

### Run WebView Smoke Tests

Source: https://zero-native.dev/testing

Executes WebView smoke tests on macOS, including options for CEF integration. These tests require a GUI-capable macOS session.

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

```bash
zig build test-webview-cef-smoke -Dplatform=macos -Dweb-engine=chromium
```

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

### Run Headless Tests

Source: https://zero-native.dev/testing

Executes the default test suite which does not require a window server. Bridge and IPC coverage are handled by these headless desktop tests.

```bash
zig build test
```

```bash
zig build test-desktop
```

```bash
zig build test-platform-info
```

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

### Validate Application Manifest and Environment

Source: https://zero-native.dev/packaging

Use `zero-native doctor` to check your host environment, WebView, manifest, and log paths. Add `--strict` to fail on warnings. `zero-native validate` checks the manifest.

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

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

### Open File Dialog from JavaScript

Source: https://zero-native.dev/dialogs

Invokes the open file dialog from JavaScript. Requires the 'zero-native.dialog.openFile' function to be available via the zero bridge. Options like 'allowMultiple' and 'allowDirectories' can be configured.

```javascript
const files = await window.zero.invoke("zero-native.dialog.openFile", {
  title: "Select a file",
  defaultPath: "/home",
  allowMultiple: true,
  allowDirectories: false,
});
```

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

### Configure Update Settings in app.zon

Source: https://zero-native.dev/updates

Define the update feed URL, public key for signature verification, and startup check behavior. Ensure the `feed_url` points to a valid JSON feed and `public_key` is a base64-encoded ed25519 public key.

```zon
.updates = .{
    .feed_url = "https://example.com/releases/zero-native-feed.json",
    .public_key = "base64-ed25519-public-key",
    .check_on_start = true,
},

```

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

### Validate app.zon Manifest

Source: https://zero-native.dev/app-zon

Commands to validate the app.zon manifest file using the zero-native CLI.

```bash
zero-native validate app.zon

```

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

```

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

### Configure Built-in Bridge Policy

Source: https://zero-native.dev/security

Explicitly configure built-in bridge policies for window and dialog commands, specifying required permissions and allowed origins.

```zig
.builtin_bridge = .{
    .enabled = true,
    .commands = &+{
        .{ .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 File Dialog

Source: https://zero-native.dev/dialogs

Opens a native file dialog to allow users to select one or more files or directories. Returns a result object containing the count and paths of selected items.

```APIDOC
## Open File Dialog

### Description
Opens a native file dialog for selecting files or directories.

### Parameters
#### Request Body
- **title** (string) - Optional - The title of the dialog window.
- **default_path** (string) - Optional - The initial directory to open.
- **filters** (array of FileFilter) - Optional - Filters for file types.
- **allow_directories** (boolean) - Optional - Whether to allow selecting directories.
- **allow_multiple** (boolean) - Optional - Whether to allow selecting multiple items.

### Response
#### Success Response (200)
- **count** (integer) - The number of selected items.
- **paths** (array of string) - An array of paths to the selected items.

### Request Example
```json
{
  "title": "Select files",
  "defaultPath": "/home/user",
  "allowMultiple": true,
  "filters": [
    { "name": "Images", "extensions": ["png", "jpg"] },
    { "name": "All Files", "extensions": ["*"] }
  ]
}
```

### Response Example
```json
{
  "count": 2,
  "paths": ["/home/user/image1.png", "/home/user/image2.jpg"]
}
```
```

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

### Generate Platform-Specific Icons

Source: https://zero-native.dev/packaging

Command to generate platform-specific icon files (`.icns` for macOS, `.ico` for Windows) from a source PNG image.

```bash
zig build generate-icon
```

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

### Initialize TestHarness

Source: https://zero-native.dev/testing

Initializes the TestHarness with default settings for headless testing. Use this to test bridge handlers, lifecycle events, and command dispatch.

```zig
var harness: zero_native.TestHarness = undefined;
harness.init(.{});
```

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

### Bundle CEF Runtime

Source: https://zero-native.dev/packaging

Command to bundle the Chromium Embedded Framework (CEF) runtime. This is necessary when using the Chromium web engine. Ensure the CEF distribution matches the target platform and architecture.

```bash
zig build cef-bundle -Dcef-dir=/path/to/cef
```

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

### App Struct Fields

Source: https://zero-native.dev/app-model

Defines the structure of a Zero-Native application.

```APIDOC
## The App struct

Field| Type| Description
---|---|---
`context`| `*anyopaque`| Pointer to your app state (required)
`name`| `[]const u8`| App name used in traces and automation snapshots (required)
`source`| `WebViewSource`| Initial WebView content (required)
`source_fn`| `?fn(*anyopaque) !WebViewSource`| Dynamic source resolver (overrides `source` when set)
`start_fn`| `?fn(*anyopaque, *Runtime) !void`| Called after the runtime starts and the first window is loaded
`event_fn`| `?fn(*anyopaque, *Runtime, Event) !void`| Called on every runtime event (lifecycle + commands)
`stop_fn`| `?fn(*anyopaque, *Runtime) !void`| Called before the runtime shuts down

All callback fields are optional. A minimal app only needs `context`, `name`, and `source`.
```

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

### Register Native Bridge Commands

Source: https://zero-native.dev/security

Register native bridge commands with their names, required permissions, and allowed origins. Prefer exact origins over wildcards.

```zig
.bridge = .{
    .commands = .{
        ,{
            .name = "native.ping",
            .origins = .{ "zero://app" },
        },
        ,{
            .name = "zero-native.window.create",
            .permissions = .{ "window" },
            .origins = .{ "zero://app" },
        },
    },
},

```

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

### Runtime Methods

Source: https://zero-native.dev/app-model

The Runtime object provides methods to manage application windows and lifecycle.

```APIDOC
## Runtime Methods

### `init(options) Runtime`

Create a runtime instance with specified options.

### `run(app) !void`

Enter the platform event loop and start the application.

### `createWindow(options) !WindowInfo`

Open a new application window.

### `listWindows() []WindowInfo`

Retrieve a list of all currently open windows.

### `focusWindow(id) !void`

Bring a specific window to the foreground.

### `closeWindow(id) !void`

Close a specific application window.

### `invalidate()`

Request a redraw of the application.

### `invalidateFor(reason, dirty_region)`

Request a redraw for a specific reason and an optional dirty region.

### `frameDiagnostics() FrameDiagnostics`

Return statistics from the last rendered frame.

### `dispatchEvent(event)`

Inject a synthetic event into the application.

### `dispatchPlatformEvent(app, event)`

Forward a platform-specific event to the application.

### `automationSnapshot()`

Write the current application state to the automation directory.
```

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

### Run CEF Smoke Tests

Source: https://zero-native.dev/web-engines

Execute smoke tests for the webview and CEF layout on macOS. The CEF smoke test requires a local CEF layout or auto-installation enabled.

```bash
zig build test-webview-cef-smoke -Dplatform=macos -Dweb-engine=chromium
```

```bash
zig build test-package-cef-layout -Dplatform=macos
```

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

### Configure Web Engine in app.zon

Source: https://zero-native.dev/web-engines

Specify the web engine to use in your application's configuration. Options include 'system' for the default or 'chromium' for a Chromium-based engine. CEF can also be configured with its directory and auto-installation.

```zon
.web_engine = "system",
// or, on supported platforms:
.web_engine = "chromium",
.cef = .{
  .dir = "third_party/cef/<platform>",
  .auto_install = true,
},
```

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

### Wire the Bridge Dispatcher in Zig

Source: https://zero-native.dev/bridge

Configure the bridge dispatcher by defining handlers and optionally setting up policies. This involves creating a registry of command names mapped to handler functions and their contexts.

```zig
fn bridge(self: *App) zero_native.BridgeDispatcher {
    self.handlers = .{.{ .name = "native.ping", .context = self, .invoke_fn = ping }};
    return .{ 
        .policy = .{ .enabled = true, .commands = &policies },
        .registry = .{ .handlers = &self.handlers },
    };
}
```

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

### Run zero-native doctor

Source: https://zero-native.dev/debugging/doctor

Use this command to check your development environment for issues. It always exits with a status code of 0.

```bash
zero-native doctor
```
Tokens:
Raw