应用模型 (App Model)

一个 zero-native 应用包含名称（Name）、WebView 源码（Source）以及可选的生命周期回调（Lifecycle Callbacks）。运行时（Runtime）拥有事件循环、窗口与原生服务；平台（Platform）拥有 Web 引擎。

App 结构体

字段	类型	描述
`context`	`*anyopaque`	指向应用状态的指针（必填）
`name`	`[]const u8`	应用名称，用于追踪 (Traces) 和自动化快照 (Automation snapshots)（必填）
`source`	`WebViewSource`	WebView 的初始内容（必填）
`source_fn`	`?fn(*anyopaque) !WebViewSource`	动态源解析器（设置后将覆盖 `source`）
`start_fn`	`?fn(anyopaque, Runtime) !void`	运行时启动且第一个窗口加载完成后调用
`event_fn`	`?fn(anyopaque, Runtime, Event) !void`	在每次发生运行时事件（生命周期 + 命令）时调用
`stop_fn`	`?fn(anyopaque, Runtime) !void`	运行时关闭前调用

所有回调字段都是可选的。最简的应用仅需要配置 context、name 和 source。

WebViewSource

用于指定 WebView 加载内容的三个构造函数：

.html(content) — 内联 HTML 字符串，作为 zero://inline 提供服务
.url(address) — 加载远程或本地的 URL
.assets(options) — 通过自定义源服务本地文件目录树

其中，assets 构造函数接收一个 WebViewAssetSource 参数：

zig

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

字段	默认值	描述
`root_path`	必填	包含前端静态资源的目录路径
`entry`	`"index.html"`	根路径下的 HTML 入口文件
`origin`	`"zero://app"`	用于静态资源 URL 的源（Origin）
`spa_fallback`	`true`	对未知路由返回入口文件（单页应用 SPA 模式）

生命周期事件

运行时会通过你的 event_fn 分发 LifecycleEvent 值：

start — 应用已启动，初始源已加载
frame — 请求了新的一帧（用于动画或状态更新）
stop — 应用正在关闭

启动器模式 (Runner Pattern)

生成的 src/runner.zig 用于将运行时与平台服务进行连接：

选择目标平台（macOS、Linux，在无头 Headless 测试时为 null）
通过 FanoutTraceSink 设置追踪接收器（标准输出 + 文件）
安装异常捕获，在崩溃时将异常写入 last-panic.txt
从 windows.zon 初始化窗口状态持久化
使用配置选项创建 Runtime 并调用 runtime.run(app)

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

RuntimeOptions (运行时配置项)

字段	类型	默认值	描述
`platform`	`Platform`	必填	平台抽象（macOS、Linux 或 `NullPlatform`）
`trace_sink`	`?trace.Sink`	`null`	结构化追踪记录的目标输出
`log_path`	`?[]const u8`	`null`	持久化日志文件的路径
`extensions`	`?ModuleRegistry`	`null`	带有生命周期钩子的扩展模块
`bridge`	`?BridgeDispatcher`	`null`	应用自定义的桥接命令与处理函数
`builtin_bridge`	`BridgePolicy`	`.`	内置命令（对话框、窗口）的策略
`security`	`SecurityPolicy`	`.`	导航白名单、外部链接和权限控制
`automation`	`?automation.Server`	`null`	用于测试的基于文件的自动化服务
`window_state_store`	`?window_state.Store`	`null`	持久化窗口几何布局与状态
`js_window_api`	`bool`	`false`	暴露 `window.zero.windows` 和 `window.zero.webviews`；依然适用源（Origin）与窗口权限检查

Runtime 方法

方法	描述
`init(options) Runtime`	创建一个运行时
`run(app) !void`	进入平台事件循环
`createWindow(options) !WindowInfo`	打开一个新窗口
`listWindows() []WindowInfo`	列出所有打开的窗口
`focusWindow(id) !void`	将指定窗口带到最前端
`closeWindow(id) !void`	关闭指定窗口
`invalidate()`	请求重绘
`invalidateFor(reason, dirty_region)`	带原因及可选脏区域（dirty region）请求重绘
`frameDiagnostics() FrameDiagnostics`	返回上一帧的诊断统计信息
`dispatchEvent(event)`	注入一个合成事件
`dispatchPlatformEvent(app, event)`	转发平台事件
`automationSnapshot()`	将状态写入自动化目录

应用模型 (App Model) ​

App 结构体 ​

WebViewSource ​

生命周期事件 ​

启动器模式 (Runner Pattern) ​

RuntimeOptions (运行时配置项) ​