多窗口应用Multi-window apps

为编辑器、预览器或工具面板创建彼此隔离的原生窗口，由一个事件循环按 window_id 分发。Create isolated native windows for editors, previews or tool panels, all driven by one event loop that dispatches by window_id.

何时使用When to use it

单窗口应用继续使用 App，它的 API 不受影响。只有当窗口必须拥有独立的生命周期、输入路由、GPU surface 或辅助功能树时，才升级为 MultiWindowApp（也导出为 zenit_app.Application）。Single-window apps keep using App; its API is unchanged. Move to MultiWindowApp (also exported as zenit_app.Application) only when windows need their own lifecycle, input routing, GPU surface or accessibility tree.

创建窗口Creating windows

const std = @import("std");
const ui = @import("ui");
const zenit_app = @import("zenit_app");

fn mountEditor(cx: *ui.Cx, scope: *ui.Scope) anyerror!*ui.Node {
    _ = scope;
    return ui.box(cx, .{ .width = .fill(), .height = .fill() }, .{});
}

fn mountPreview(cx: *ui.Cx, scope: *ui.Scope) anyerror!*ui.Node {
    _ = scope;
    return ui.box(cx, .{ .width = .fill(), .height = .fill() }, .{});
}

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();

    var application = zenit_app.MultiWindowApp.init(gpa.allocator(), .{});
    defer application.deinit();

    // createWindowWith = create + mount in one transaction: if mount fails,
    // every native / GPU resource of that window is torn down again.
    const editor = try application.createWindowWith(.{
        .window = .{ .width = 900, .height = 700, .title = "Editor" },
    }, mountEditor);

    _ = try application.createWindowWith(.{
        .window = .{ .width = 480, .height = 700, .title = "Preview" },
    }, mountPreview);

    _ = application.activateWindow(editor.windowId());
    try application.run(); // returns after the last window closes or quit()
}

每次 createWindow* 返回一个 *App，配置项与单窗口 App 相同（window、console、frame_pacing 等）。createWindow 只创建不挂载，需要自己调用 app.mount(mountFn)；createWindowWith 把创建与挂载合成一个事务。仓库的 zig build multi-window 示例同时演示两种写法。Each createWindow* call returns an *App and takes the same config as a single-window App (window, console, frame_pacing, …). createWindow creates without mounting, so you call app.mount(mountFn) yourself; createWindowWith does both as one transaction. The repo’s zig build multi-window example exercises both.

隔离保证Isolation guarantees

生命周期Lifecycle

const preview_id = preview.windowId(); // preview: *App from createWindowWith

// Safe from inside an input / menu / render callback: the close is queued
// and committed at the loop's iteration boundary.
_ = application.closeWindow(preview_id);

// Look windows up by id instead of holding *App across a close.
if (application.window(preview_id)) |app| {
    _ = app; // still alive
}

共享状态策略Sharing state

跨窗口的业务模型由应用持有，每个窗口只保存自己的视图状态。每个 Cx 有独立的响应式图，因此不要让一个窗口的 Effect 读取另一个窗口 Scope 里的 Signal，也不要跨 Cx 共享 Node 指针或 Scope 资源。The cross-window model is owned by the app; each window keeps only its own view state. Every Cx has its own reactive graph, so don’t let one window’s Effect read a Signal from another window’s Scope, and never share Node pointers or Scope resources across Cx.

• ✓

  模型在窗口之外。用普通结构体或应用级 Store 保存事实，生命周期长于任何一扇窗口。The model lives outside the windows. Keep facts in a plain struct or an app-level store that outlives any single window.

• ✓

  每个窗口镜像自己需要的部分。窗口在自己的 Scope 里创建 Signal，模型变化时由应用显式写入各窗口的镜像。Each window mirrors what it needs. A window creates Signals in its own Scope; when the model changes, the app writes each window’s mirror explicitly.

• ✓

  关闭时解除登记。窗口关闭后，模型不能再持有指向该窗口 Signal 的指针。Unregister on close. After a window closes, the model must not keep pointers to that window’s Signals.