Native Controls

Native controls are platform-owned views declared with App.scene_fn, attached with runtime.createShellViews(...), created imperatively through runtime.createView(...), or created from trusted WebView code through the guarded window.zero.views.* bridge helpers. They are intended for trusted chrome, utility panels, and OS-native affordances around rich WebView content.

const shell_views = [_]zero_native.ShellView{
    .{ .label = "toolbar", .kind = .toolbar, .edge = .top, .height = 52 },
    .{ .label = "refresh-icon", .kind = .icon_button, .parent = "toolbar", .accessibility_label = "Refresh", .text = "R", .command = "app.refresh" },
    .{ .label = "refresh", .kind = .button, .parent = "toolbar", .text = "Refresh", .command = "app.refresh" },
    .{ .label = "search", .kind = .search_field, .parent = "toolbar", .text = "Search" },
    .{ .label = "live", .kind = .checkbox, .parent = "toolbar", .text = "Live" },
    .{ .label = "view-mode", .kind = .segmented_control, .parent = "toolbar", .text = "List|Grid" },
    .{ .label = "syncing", .kind = .progress_indicator, .parent = "toolbar", .role = "Syncing" },
    .{ .label = "body", .kind = .split, .fill = true, .axis = .row },
    .{ .label = "sidebar", .kind = .sidebar, .parent = "body", .width = 240 },
    .{ .label = "filters", .kind = .stack, .parent = "sidebar", .x = 16, .y = 16, .width = 180, .height = 120, .axis = .column },
    .{ .label = "filter-title", .kind = .label, .parent = "filters", .text = "Filters" },
    .{ .label = "filter-live", .kind = .checkbox, .parent = "filters", .text = "Live" },
    .{ .label = "main", .kind = .webview, .parent = "body", .url = "zero://inline", .fill = true },
};

const shell_windows = [_]zero_native.ShellWindow{.{
    .label = "main",
    .title = "Acme",
    .width = 1100,
    .height = 760,
    .views = &shell_views,
}};

fn scene(context: *anyopaque) anyerror!zero_native.ShellConfig {
    _ = context;
    return .{ .windows = &shell_windows };
}

Supported Kinds

Kind	Notes
`toolbar`	Native container for top app chrome
`titlebar_accessory`	Native titlebar-adjacent container where the platform allows it
`sidebar`	Native side panel container
`statusbar`	Native bottom/status container
`split`	Native container for fixed and fill panes; set `axis` to `.row` or `.column`
`stack`	Native container for grouped child controls; set `axis` to `.row` or `.column`
`button`	Dispatches `command` through `Event.command`
`icon_button`	Compact command button for toolbar-style actions
`checkbox`	Native checkbox control
`toggle`	Native binary toggle button
`segmented_control`	Native segmented choice control; use pipe-delimited `text`, such as `List\|Grid`
`text_field`	Native editable text field
`search_field`	Native search input
`label`	Native static text
`spacer`	Empty native layout spacer
`progress_indicator`	Native indeterminate progress indicator
`webview`	Compatibility view backed by the WebView backend

The macOS, Linux, and Windows system-WebView backends support these native kinds today. Chromium hosts return explicit unsupported errors until their native hosts implement the same surface.

Layout

For declarative shell views, use edge for docked chrome, fill = true for content, parent for controls inside containers, axis for row or column child flow, and min/max size fields when a surface needs resize constraints. stack containers apply native spacing between controls; split containers divide panes along their axis without spacing, so a fixed sidebar and fill WebView can resize together. The runtime keeps shell views bound to the window and reapplies their frames on resize.

Use accessibility_label for the announced control name when it should differ from visible text. Use role for semantic/fallback accessibility text. Use text for visible labels, button titles, and text/search placeholders.

ViewInfo.focused reports the last successfully focused view in a window. Use runtime.focusNextView(...), runtime.focusPreviousView(...), or window.zero.views.focusNext() / focusPrevious() to move through visible, enabled native controls and WebView-backed views in stable view order. Automation snapshots include the same focus state for native controls and WebView-backed views.