Windows

The Native SDK supports multiple windows. A native-rendered app declares its windows as a scene — ShellWindow entries carrying titles, sizes, restore behavior, and view trees, the shape UiApp takes through its scene option and app.zon takes through the shell block:

const shell_windows = [_]native_sdk.ShellWindow{.{
    .label = "main",
    .title = "My App",
    .width = 480,
    .height = 320,
    .restore_state = false,
    .views = &shell_views,
}};
const shell_scene: native_sdk.ShellConfig = .{ .windows = &shell_windows };

The first scene window adopts the startup window; additional scene windows are created through the window service. Secondary windows can also be created imperatively from Zig — or, in apps that embed web content, from trusted JavaScript.

Creating windows from Zig

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

Creating windows from JavaScript

js_window_api exposes the window.zero.windows.* helper in JavaScript. Window commands still require an allowed origin and the window permission when runtime permissions are configured:

const app_permissions = [_][]const u8{native_sdk.security.permission_window};

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

Then JavaScript can call the helper from an allowed origin:

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

Window types

Type	Description
`WindowId`	Opaque identifier (`u64`)
`WindowCreateOptions`	Options for `runtime.createWindow()`: label, title, frame
`WindowInfo`	Returned after creation: id, label, title, frame
`WindowState`	Persisted state: id, label, title, frame, open, focused, maximized, fullscreen, scale
`WindowRestorePolicy`	How restored frames are placed, such as clamping to the visible screen or centering on the primary display

Platform limits

Constant	Value
`max_windows`	16
`max_window_label_bytes`	64
`max_window_title_bytes`	128

Window state persistence

The window_state.Store persists geometry to windows.zon in the app's state directory. Startup restore uses the window label from the manifest and applies the saved frame; titles continue to come from app.zon or runtime window creation options.

Field	Description
`id`	Window ID
`label`	Window label (used for merge matching)
`frame`	Position and size (x, y, width, height)
`maximized`	Whether the window was maximized
`fullscreen`	Whether the window was fullscreen
`scale`	Display scale factor

When saveWindow is called, the store merges by matching on label or id, so secondary windows are preserved alongside the main window. Records with missing, malformed, or empty labels are ignored on load and omitted the next time the file is rewritten.

Declaring windows in app.zon

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