cj-tauri 2.0.0 → 2.1.0

package/src/host.cj

@@ -1,607 +1,752 @@
-package cjTauri
-
-import std.collection.*
-import stdx.encoding.json.*
-import cjTauri.platform.*
-
-/**
- * WebView 宿主层（对标 Tauri 2 的 tao + wry 抽象）
- *
- * 平台差异由条件编译隔离在各自的宿主文件内，上层完全共用：
- *   - Linux 桌面：host_webkit.cj（WebKitGTK，经 native/bridge_linux.c 在原生 pthread 运行）
- *   - Windows   ：host_webview2.cj（WebView2 / Edge Chromium，经 native/bridge_win.c）
- *   - 鸿蒙       ：ArkWeb（架构预留，条件编译位）
- * IPC 桥（ipc_hub.cj）与能力安全模型（capability.cj）跨平台复用。
- */
-
-/**
- * 宿主能力位（与 native/bridge_core.h 的 `CJ_CAP_*` **逐位对齐**，两侧不许各写各的）
- *
- * 由平台在 C 侧 `cj_plat_init` 时填好，经 `WebViewHost.hostCapabilities()` 取回。
- * 「这台机器上的框架支持什么」是**静态事实**（编出来的桥有没有那块），不是运行期探测：
- * 应用据此决定要不要建菜单 / 托盘，拿不到就别骗自己。
- *
- * 与能力安全模型（capability.cj）的 `Capability` 不是一回事：那个管「页面能不能调某个命令」，
- * 这个管「宿主有没有这个本事」——所以名字里带 host 前缀，别混。
- */
-public const CJ_CAP_MENU: Int32 = 1
-
-public const CJ_CAP_TRAY: Int32 = 2
-
-public const CJ_CAP_DRAG_DROP: Int32 = 4
-
-/** 全局快捷键（与 native/bridge_core.h 的 CJ_CAP_HOTKEY 逐位对齐；Linux = 编进了 X11 支持） */
-public const CJ_CAP_HOTKEY: Int32 = 16
-
-/** 标题栏副标题（与 native/bridge_core.h 的 CJ_CAP_SUBTITLE 逐位对齐；Linux = 菜单栏同排的 label，
-    Windows 的系统菜单没有自绘区、不置位）。应用据它决定要不要自己画页面顶栏。 */
-public const CJ_CAP_SUBTITLE: Int32 = 32
-
-/**
- * 宿主能力位的**可读形态**（RFC-002 §5.3）：`CJ_CAP_*` 位域 → 具名布尔 + `toJson`。
- *
- * 为什么要有它：`hostCapabilities()` 给的是位域，应用与 `system:host` 的调用方要的是
- * 「menu 有没有」这种具名答案；位域 ↔ 名字的对应只留在这一个地方，
- * 免得每个消费点各写各的 `(caps & CJ_CAP_MENU) != 0`（写错一位就是一个静默的假答案）。
- *
- * `platform` 不在位域里，由调用方（`currentPlatform()`）单独给——位域来自 C 桥，平台标识来自
- * 仓颉侧的条件编译，两者本就是两个来源。
- */
-public class HostCapabilities {
-    public let platform: String
-    public let menu: Bool
-    public let tray: Bool
-    public let dragDrop: Bool
-    public let hotkey: Bool
-    public let subtitle: Bool
-
-    public init(platform: String, menu: Bool, tray: Bool, dragDrop: Bool, hotkey: Bool, subtitle: Bool) {
-        this.platform = platform
-        this.menu = menu
-        this.tray = tray
-        this.dragDrop = dragDrop
-        this.hotkey = hotkey
-        this.subtitle = subtitle
-    }
-
-    /** 位域 → 具名布尔（`platform` 由调用方给，见类注释） */
-    public static func fromBits(platform: String, caps: Int32): HostCapabilities {
-        return HostCapabilities(
-            platform,
-            (caps & CJ_CAP_MENU) != 0,
-            (caps & CJ_CAP_TRAY) != 0,
-            (caps & CJ_CAP_DRAG_DROP) != 0,
-            (caps & CJ_CAP_HOTKEY) != 0,
-            (caps & CJ_CAP_SUBTITLE) != 0
-        )
-    }
-
-    /** `system:host` 的返回形状：`{"platform":"linux","menu":true,"tray":true,"dragDrop":true,"hotkey":true,"subtitle":true}` */
-    public func toJson(): JsonValue {
-        var obj = JsonObject()
-        obj.put("platform", JsonString(this.platform))
-        obj.put("menu", JsonBool(this.menu))
-        obj.put("tray", JsonBool(this.tray))
-        obj.put("dragDrop", JsonBool(this.dragDrop))
-        obj.put("hotkey", JsonBool(this.hotkey))
-        obj.put("subtitle", JsonBool(this.subtitle))
-        return obj
-    }
-}
-
-public interface WebViewHost {
-    /**
-     * 本窗口的 label（单窗口阶段恒为 "main"）
-     *
-     * 与 `WindowRecord.label` 是同一个值：注册表是路由的权威来源，宿主自己也留一份——
-     * 给前端注入 label（`window.__CJ_TAURI_LABEL__`）以及将来的窗口内自省都用它。
-     */
-    func label(): String
-
-    /**
-     * 加载页面（唯一入口，RFC §4.3）：Inline / Url / DevServer / Asset 四态
-     *
-     * 原 start(html) / startUrl(url) 双入口在此收敛。Asset 怎么落地是 L0 的事（RFC §6.2）：
-     * 桌面经注入的 AssetResolver 读盘（未注入时按 cwd 相对路径读，与批次 1 行为等价），
-     * 鸿蒙由胶水印化的 rawfile 解析成 HTML 再落沙箱以 file:// 加载。
-     * URL 页面有真实来源，相对路径资源、动态 import、前端路由才成立（file:// 下禁止 fetch/XHR）。
-     */
-    func load(source: PageSource): Unit
-
-    /**
-     * 注入资产解析器（装配层在 load 之前调用；None = 各端默认读盘策略）
-     */
-    func setAssetResolver(resolver: Option<AssetResolver>): Unit
-
-    /**
-     * 注册一段「页面脚本执行前」注入的初始化脚本（多次调用按注册顺序注入）
-     *
-     * 必须在 load() 之前调用：宿主创建 WebView 时一次性交给 C 桥，桥以
-     * document-start 注入（WebKit user script / WebView2 AddScriptToExecuteOnDocumentCreated）。
-     * 因此它对 HTML 与 URL 两种页面来源**一视同仁**——插件的 jsShim 走的就是这条通道（RFC §5.4 的 v2 方案），
-     * 不再靠字符串拼 HTML。空串忽略；脚本是普通 JS 片段，不要自带 <script> 标签。
-     */
-    func addInitScript(js: String): Unit
-
-    /**
-     * 重新加载当前页面（整页 reload，对标浏览器刷新）
-     *
-     * 页面尚未加载时为空操作；开发者工具里的刷新按钮等价于此。
-     */
-    func reload(): Unit
-
-    /**
-     * 应用窗口配置（标题 / 尺寸）；必须在 load() 之前调用，宿主据此创建窗口
-     */
-    func setWindowConfig(config: WindowConfig): Unit
-
-    /**
-     * 是否允许打开开发者工具；必须在 load() 之前调用
-     */
-    func setDevTools(enabled: Bool): Unit
-
-    /**
-     * 运行时打开开发者工具（WebView2 DevTools / WebKit Inspector）
-     */
-    func openDevTools(): Unit
-
-    /**
-     * 设置本窗口的菜单栏（RFC-002 §5.2 的线路文本；空串 = 清空菜单栏）
-     *
-     * 调用时机两头都行：`start()` 之前调用会在建窗时一次建好（未就绪的文本由 C 桥记着）；
-     * 之后就投到宿主 UI 线程重建整棵菜单。
-     * 平台没有菜单能力（`hostCapabilities()` 不含 `CJ_CAP_MENU`）时不影响其它功能——
-     * 「能力位为 0 就别建菜单」是调用方的约定，宿主不替应用猜。
-     */
-    func setMenu(wire: String): Unit
-
-    /**
-     * 运行期改单个菜单项的状态（按 id 找；找不到只记一行日志，不报错）
-     *
-     * 只改状态、不改结构：结构变化走 `setMenu` 整棵重建。状态的真身在平台对象上
-     * （Windows 的 HMENU、GTK 的 GtkCheckMenuItem），模型本身是只读的——理由见 src/menu.cj。
-     */
-    func setMenuItemState(id: String, enabled: Bool, checked: Bool): Unit
-
-    /**
-     * 设置**窗口顶部副标题**：一行文本画在原生菜单栏**同一行的右侧**
-     *
-     * 用途是让应用省掉自己那条页面顶栏——标题 / 保存状态 / 字数挂在原生这一行上，
-     * 界面高度直接少一层。允许运行期高频更新（每次编辑都可能改），平台自己投递到
-     * UI 线程，调用方在哪个线程调都行。
-     * 这是**运行期能力**：建窗之前调用返回 -3（不像 `setMenu` 那样记 pending），
-     * 应用要么等页面加载后再调，要么按返回值如实处理。
-     * 平台没有该能力（能力位不含 `CJ_CAP_SUBTITLE`，Windows 即如此）时如实降级：
-     * 文本不显示、桥打一行 stderr，应用据能力位自己决定画不画页面顶栏。
-     */
-    func setTitlebarSubtitle(text: String): Unit
-
-    /**
-     * 设置拖放策略（RFC-002 §5）：enabled=false 平台不注册 drop target。
-     * 必须在 `load()` 之前调用（Linux 建 view 时决定挂不挂 drag dest）；
-     * 之后调用在未就绪时只记 pending、建窗生效，已就绪平台投 UI 线程重挂。
-     * 平台没有该能力（能力位不含 `CJ_CAP_DRAG_DROP`）时宿主只记日志，不报错。
-     */
-    func setDragDropPolicy(enabled: Bool, files: Bool): Unit
-
-    /**
-     * 注册**全局快捷键**（RFC-003 第 5 期）：wire 一行一条 `<accel>:<id>`（见 `HotkeyModel.toWire`）
-     *
-     * 全局 = 焦点不在本应用窗口时也生效（X11 grab / Win32 RegisterHotKey）。
-     * 允许在 `start()` 之前调（桥记 pending，宿主线程起来后注册）；运行期再调 = 整表替换。
-     * 触发事件以 `{"kind":"hotkey","id":"…"}` 走 shell 回调（按句柄路由）→ 前端 `hotkey:press`。
-     * 平台不支持时桥打一行 stderr 如实说明，调用不报错、事件不来。
-     */
-    func setGlobalHotkeys(wire: String): Unit
-
-    /**
-     * 设置**托盘**（RFC-002 §7.C）：wire 见 `TrayModel.toWire()`，空串 = 移除托盘
-     *
-     * 允许在 `start()` 之前调（桥记 pending，宿主线程装配时创建）；运行期再调 = 整体重建。
-     * 菜单项被点以 `{"kind":"tray","id":"…"}` 走 shell 回调（按句柄路由）→ 前端 `tray:click`。
-     * 平台不支持 / 依赖没编进来时桥打一行 stderr 如实说明，调用不报错、托盘不出现。
-     */
-    func setTray(wire: String): Unit
-
-    /**
-     * 显示 / 隐藏本窗口（对标 Tauri 2 的 `window.show()` / `window.hide()`）
-     *
-     * 隐藏 = 从任务栏与屏幕上消失（Windows 走 `ShowWindow(SW_HIDE)`，Linux 走 `gtk_widget_hide`），
-     * 事件循环照常跑、页面照常活着——所以「最小化到托盘」的还原路径（托盘菜单 / 全局快捷键）才成立。
-     * 两头都能调：`start()` 之前调只记下（建窗时按它定稿，隐藏态的窗口首次出现前就是隐藏的）；
-     * 之后调用投到宿主 UI 线程执行。显示时顺带把窗口提到前台（Linux 是 `gtk_window_present`，
-     * Windows 是 `SetForegroundWindow`）。
-     * 这是**宿主基元**，两平台都实现，不占能力位（没有平台只有一半）。
-     */
-    func setWindowVisible(visible: Bool): Unit
-
-    /**
-     * 最小化到托盘（RFC-003 第 5 期余项，`WindowConfig.minimizeToTray` 的落点）
-     *
-     * enabled=true 时，用户在标题栏点「最小化」不再缩到任务栏，而是**隐藏窗口**
-     * （= `setWindowVisible(false)` 的效果）；还原走应用自己的托盘菜单 / 全局快捷键。
-     * 必须在 `load()` 之前调用（窗口过程要在建窗时就知道这条策略）。
-     * 真到最小化那一刻，平台会复核托盘是否**真的**装上了（能力位不含 `CJ_CAP_TRAY`，
-     * 或应用压根没调 `setTray`）：没装就如实降级为普通最小化并打一行 stderr——
-     * 窗口藏起来却没有任何还原入口，是比「不支持」更糟的结果。
-     */
-    func setMinimizeToTray(enabled: Bool): Unit
-
-    /**
-     * 本宿主的静态能力位（`CJ_CAP_*` 的按位或）：能不能做菜单 / 托盘 / 文件拖入
-     *
-     * 宿主尚未创建（`dispose()` 之后 / `start()` 之前未分配句柄）返回 0。
-     * 注意与命令级的能力安全模型无关：这里说的是宿主本事，不是页面权限。
-     */
-    func hostCapabilities(): Int32
-
-    /**
-     * 装配本窗口的 shell 事件回调（菜单点击等；载荷是 C 桥的 JSON 信封）
-     *
-     * 与 `setMessageHandler` 同一套路，区别是事件源在宿主侧（应用菜单）而不是页面。
-     * **多窗口下必须按宿主身份路由**：C 侧回调首参是句柄，只有本窗口的句柄才转给本实例的
-     * 这个回调——这正是「回调带宿主身份」的落地方式（见 docs/RFC-菜单-托盘-拖放.md §5.5）。
-     */
-    func setShellHandler(handler: (String) -> Unit): Unit
-
-    /**
-     * 装配本窗口的销毁回调（窗口关闭 / 退出收尾时恰好触发一次）
-     *
-     * 多窗口下按宿主身份路由（C 侧回调首参是句柄），所以每扇窗口装自己的——回调不带参数，
-     * 因为「是哪扇窗」在装配时就已确定（应用可经 `app.hostOf(label)` 逐窗安装）。
-     * 与 `setShellHandler` 同为**可变槽位**：在 `load()` 之后再装同样生效（路由闭包读字段，不是快照）。
-     */
-    func setDestroyHandler(handler: () -> Unit): Unit
-
-    /**
-     * 原生文件选择对话框（阻塞到用户关闭）：返回选中的路径，取消 / 失败返回空串。
-     *
-     * filter 是「描述|模式|描述|模式」拼串（Windows 惯例；GTK 端按同一格式解析），
-     * 例如 "文本文件|*.txt|所有文件|*.*"；空串表示不限制。
-     * 必须在 load() 之后调用——对话框要拿已创建的应用窗口当父窗口。
-     */
-    func showFileDialog(save: Bool, title: String, filter: String): String
-
-    /**
-     * 带默认文件名的文件对话框：除预置名字外与 `showFileDialog` 完全同语义。
-     *
-     * 预置名字的用途是**自动化取证**——探针对原生框发 IDOK 时框里得已有名字才能关，
-     * 返回值因此可预期（预置什么回什么），多窗并发的「结果各归各窗」才验得动。
-     * 平台不支持预置（如 GTK 轮未接）时行为退化为 `showFileDialog`，如实降级。
-     */
-    func showFileDialogPreset(save: Bool, title: String, filter: String, defaultName: String): String
-
-    /**
-     * 原生目录选择对话框（阻塞到用户关闭）：返回选中的目录路径，取消 / 失败返回空串。
-     *
-     * 独立成方法而不是给 `showFileDialog` 加一个开关：选目录在两端都不是「换个动作」——
-     * GTK 是另一个 chooser action，Windows 更是另一套 API（`IFileOpenDialog` +
-     * `FOS_PICKFOLDERS`，`GetOpenFileName` 没有这个能力）。桥侧两者共用同名同签名的
-     * `cj_bridge_show_dialog`，以 kind=6 区分（与文件类 / 消息类并列，见 `dlg_req`）。
-     * 与 `showFileDialog` 同规矩：必须在 load() 之后调用（要拿应用窗口当父窗口）。
-     */
-    func showFolderDialog(title: String): String
-
-    /**
-     * 原生消息对话框（阻塞到用户关闭）：返回用户是否点了「确定」。
-     *
-     * kind 取 "info" / "warning" / "error" / "confirm"（其它值按 info 处理）。
-     * info / warning / error 只有一个「确定」，弹出即成立；只有 confirm 会返回 false。
-     */
-    func showMessageDialog(kind: String, title: String, message: String): Bool
-
-    /**
-     * 写文本进系统剪贴板（上限 8 MiB，C 侧 core 校验）
-     *
-     * 与对话框同类：宿主能力，要在 load() 之后调用（未就绪时返回 false）。
-     */
-    func clipboardWriteText(text: String): Bool
-
-    /**
-     * 读系统剪贴板文本：空 / 非文本 / 平台失败都返回 None，不区分（协议层没有可读的失败明细）
-     */
-    func clipboardReadText(): Option<String>
-
-    /**
-     * 发一条系统通知（发后即忘：提交即返回，显示成败不回传）。
-     * 本平台未实现时返回 false（`system:host` 的能力位会同口径如实上报）。
-     */
-    func notify(title: String, body: String): Bool
-
-    /**
-     * 原生 → JS：在 WebView 中执行脚本
-     */
-    func runJs(js: String): Unit
-
-    /**
-     * 停止本窗口的事件循环（低层原语）
-     *
-     * 应用级退出请用 `AppHost.quit()`——它会走所有窗口；单窗口下两者等价。
-     * 原语留在宿主上是因为「循环归谁所有」只有实现方知道（两平台的收尾方式不同：
-     * Linux 只收主循环、窗口留给收尾销毁，Windows 直接 DestroyWindow），上层不该自己拼。
-     */
-    func quit(): Unit
-
-    /**
-     * 装配前端消息回调（WebView 送来的 JSON 字符串 → IPC hub）
-     */
-    func setMessageHandler(handler: (String) -> Unit): Unit
-
-    /**
-     * 宿主事件循环是否已退出（窗口关闭等），app.run 据此阻塞与收尾
-     *
-     * 同为低层原语：应用级等待用 `AppHost.waitForExit()`，调用方不必自己写轮询。
-     */
-    func shouldQuit(): Bool
-
-    /**
-     * 释放宿主资源（宿主编由 C 侧分配与回收，跨 FFI 不换分配器）：幂等、无需检查调用时机
-     *
-     * TauriApp.run / runUrl 在 waitForExit() 之后调用它；实现方须把句柄置空——
-     * 释放后该实例不可再启动（原生窗口已随销毁路径在关窗时收尾）。
-     * 为什么「关窗」不等于「释放」：见 docs/架构演进-多平台与多窗口.md §6.1。
-     */
-    func dispose(): Unit
-}
-
-/**
- * 应用级宿主（对标 Tauri 2 的 `AppHandle`）
- *
- * 与 `WebViewHost` 的分工：`WebViewHost` 是**一个窗口**（创建、投脚本、对话框、本窗口的循环原语），
- * `AppHost` 是**整个应用**（退出、按 label 取窗口；将来还有托盘与应用菜单——批次 3 只定模型）。
- * 批次 2 由 `TauriApp` 实现：它持有窗口注册表，也只有它知道「哪些窗口还开着、应用该不该退」。
- *
- * 为什么 quit / waitForExit 收在这一层：它们跨窗口。宿主仍保留 `quit()` / `shouldQuit()` 作低层原语
- * （循环归宿主所有），但**应用的公开入口只有这里**——多窗口时代的「退出」必然是「先把各窗口收掉」。
- */
-public interface AppHost {
-    /**
-     * 退出应用：收掉所有窗口的事件循环，`run()` / `runUrl()` 随即返回
-     */
-    func quit(): Unit
-
-    /**
-     * 阻塞到应用退出（窗口关闭 / quit）后返回；`run()` / `runUrl()` 内部调它
-     */
-    func waitForExit(): Unit
-
-    /**
-     * 按 label 取窗口宿主（对标 Tauri 的 `app.get_webview_window(label)`）；未注册返回 None
-     */
-    func hostOf(label: String): Option<WebViewHost>
-}
-
-/**
- * C 桥原生线程 → 仓颉回调的中转。
- * 各平台宿主在 prepareHost() 时把「本句柄 → 本实例的回调」登记进路由表，C 侧的 @C 函数按句柄取用。
- */
-/**
- * 一条**宿主级回调路由**：C 侧句柄 → 本窗口的三个回调
- *
- * C 侧所有回调的入口都是模块级 @C 函数（每个宿主注册的是同一个函数指针），句柄是唯一能分辨
- * 「哪个窗口」的凭据——三类回调都按句柄查表，查到谁就派发给谁。
- *
- * 闭包都是可变的：读的是宿主实例的字段（不是快照），所以应用在 `load()` 之后再调
- * `setShellHandler` / `setDestroyHandler` 同样生效。
- */
-class HostRoute {
-    let handle: CPointer<Unit>
-    var onShell: (String) -> Unit
-    var onDestroy: () -> Unit
-    var onDialog: (String) -> Unit
-
-    init(handle: CPointer<Unit>, onShell: (String) -> Unit, onDestroy: () -> Unit,
-         onDialog: (String) -> Unit) {
-        this.handle = handle
-        this.onShell = onShell
-        this.onDestroy = onDestroy
-        this.onDialog = onDialog
-    }
-}
-
-class HostGlobals {
-    // 前端消息：**有意保留单槽**。报文自带发起窗口的 window label（架构文档 §7.3），
-    // TauriApp 给所有窗口装的是同一只派发器，路由不靠句柄（见 src/app.cj 的 wireHostCallbacks）。
-    static var onMessage: (String) -> Unit = { _ => }
-    // 其余三类回调没有「自带身份」的载荷（销毁无载荷、文件框结果只有路径、shell 事件只有信封），
-    // 只能让 C 侧把句柄带回来。表里每条只认领自己的句柄。
-    // 单槽时代的症状：后装配的窗口覆盖先装配的——「哪扇窗关了」认错、两窗同时开文件框时结果串台
-    // （见 docs/架构演进-多平台与多窗口.md §7.5）。
-    // 登记发生在 prepareHost（run() 之前、宿主线程还没起），派发时才读表 → 登记期没有并发。
-    static var hostRoutes: ArrayList<HostRoute> = ArrayList<HostRoute>()
-
-    /**
-     * 登记（或更新）一条宿主级路由
-     *
-     * 同一句柄重复登记＝换掉旧闭包（宿主被重新 prepare 时不叠加、事件也不会派发两次）；
-     * 句柄比较走 C 侧 `cj_bridge_host_eq`（仓颉的 `CPointer` 不支持 `==`）。
-     * 顺带解决「旧宿主销毁、新宿主复用同一地址」：新宿主登记时就覆盖了那条陈旧路由。
-     */
-    static func registerHostRoute(handle: CPointer<Unit>, onShell: (String) -> Unit,
-                                  onDestroy: () -> Unit, onDialog: (String) -> Unit): Unit {
-        for (r in HostGlobals.hostRoutes) {
-            if (hostHandleEquals(r.handle, handle)) {
-                r.onShell = onShell
-                r.onDestroy = onDestroy
-                r.onDialog = onDialog
-                return
-            }
-        }
-        HostGlobals.hostRoutes.add(HostRoute(handle, onShell, onDestroy, onDialog))
-    }
-
-    /**
-     * 按句柄取路由；查不到返回 None（句柄不属于本进程，或该宿主已注销）
-     */
-    static func hostRouteOf(handle: CPointer<Unit>): Option<HostRoute> {
-        for (r in HostGlobals.hostRoutes) {
-            if (hostHandleEquals(r.handle, handle)) {
-                return Some(r)
-            }
-        }
-        return None
-    }
-}
-
-/**
- * kind 字符串 → C 桥的对话框编号（与 native/bridge_linux.c、bridge_win.c 的取值一一对应）
- */
-func dialogKindCode(kind: String): Int32 {
-    match (kind) {
-        case "warning" => 3
-        case "error" => 4
-        case "confirm" => 5
-        case _ => 2
-    }
-}
-
-/**
- * 对话框结果回调（C 桥 → 仓颉）：文件类对话框选中的路径经它送回，首参是**发起这次对话框的宿主句柄**。
- *
- * 由 C 桥在自己的 UI 线程上调用，与 hostOnMessage 同一套路；按句柄写进对应宿主的结果位，
- * 再由桥唤醒阻塞的调用方去读。多窗口下两扇窗可以各自开着文件框，结果不许串台。
- * 非 @When：两平台的 C 侧都调它（签名一致，首参不透明）。
- */
-@C
-func dialogOnResult(host: CPointer<Unit>, path: CString): Unit {
-    try {
-        match (HostGlobals.hostRouteOf(host)) {
-            case Some(r) => r.onDialog(path.toString())
-            case None => eprintln("[cj-tauri] dialog callback: 未登记的宿主句柄（已丢弃）")
-        }
-    } catch (e: Exception) {
-        eprintln("[cj-tauri] dialog callback error: ${e}")
-    }
-}
-
-/**
- * 窗口销毁回调（C 桥 → 仓颉）：首参是**被销毁的宿主句柄**（每个宿主恰好触发一次）。
- *
- * 曾经写进全局单槽 → 多窗口下「哪扇窗关了」认错（后装配的窗口覆盖先装配的）；
- * 现在与 shell / 对话框一样按句柄认领。非 @When：两平台的 C 侧都调它。
- */
-@C
-func hostOnDestroy(host: CPointer<Unit>): Unit {
-    try {
-        match (HostGlobals.hostRouteOf(host)) {
-            case Some(r) => r.onDestroy()
-            case None => eprintln("[cj-tauri] destroy callback: 未登记的宿主句柄（已忽略）")
-        }
-    } catch (e: Exception) {
-        eprintln("[cj-tauri] destroy callback error: ${e}")
-    }
-}
-
-/**
- * shell 事件回调（C 桥 → 仓颉）：菜单点击等经它送回，首参是**发生事件的宿主句柄**。
- *
- * 由 C 桥在宿主 UI 线程上调用（与 hostOnMessage 同一套路）；句柄→实例的解引用走宿主级路由表，
- * 本函数只做「别抛穿 FFI 边界」这一件事。
- * 非 @When：两平台的 C 侧都调它（签名一致，首参不透明）。
- */
-@C
-func shellOnEvent(host: CPointer<Unit>, json: CString): Unit {
-    try {
-        // 认领自己那条：句柄对不上就静默跳过（C 侧只有一个入口，区分就在这里）
-        match (HostGlobals.hostRouteOf(host)) {
-            case Some(r) => r.onShell(json.toString())
-            case None => () // 未登记（旧宿主已注销 / 非本进程句柄）：静默，别在热路径上刷屏
-        }
-    } catch (e: Exception) {
-        eprintln("[cj-tauri] shell callback error: ${e}")
-    }
-}
-
-/**
- * 创建当前平台的 WebView 宿主（对标 Tauri 2 的 runtime 选择）
- *
- * label 按窗口给定（多窗口）：默认窗口传 DEFAULT_WINDOW_LABEL，附加窗口传各自登记的 label。
- * 必须是构造参数而不是事后 setter——label 决定页面侧 `window.__CJ_TAURI_LABEL__` 与事件过滤，
- * 启动之后再改就晚了（见 docs/架构演进-多平台与多窗口.md §7.3）。
- */
-// 判据为什么是 `env`（2026-10-19 校正）：鸿蒙目标下 `os` 仍取 `Linux`，`arch` 也只有
-// `aarch64`——桌面 aarch64 Linux 同样是 `aarch64`，拿它当判据会把「跑在 GTK 上」误判成
-// 「跑在 ArkWeb 上」，两边的宿主实现会互相打架（编译期就撞名）。官方条件编译映射表给出
-// `aarch64-linux-ohos` → `env == "ohos"`、桌面 Linux → `gnu`，这才是真正互斥的维度。
-// 于是桌面 Linux 侧写 `env != "ohos"`：**桌面 aarch64 Linux 因此重新拿回 WebKit 宿主**
-// （改判据之前它落到「只能注入宿主」的分支，是同一处误判的另一半）。
-@When[os == "Linux" && env != "ohos"]
-func createHost(label: String): WebViewHost {
-    return WebKitHost(label)
-}
-
-// 鸿蒙：内置 ArkWeb 宿主（应用侧只负责建 ArkUI 组件并把 controller 交给它，见 src/host_arkweb.cj）
-@When[env == "ohos"]
-func createHost(label: String): WebViewHost {
-    return ArkWebHost(label)
-}
-
-@When[os == "Windows"]
-func createHost(label: String): WebViewHost {
-    return WebView2Host(label)
-}
-
-/**
- * 两个宿主句柄是否指向同一宿主
- *
- * 桌面两平台走 C 桥 `cj_bridge_host_eq`——仓颉的 `CPointer` 既没有 `==` 也没有 `!=`
- * （实测报 `invalid binary operator '!=' on type 'CPointer<Unit>'`），也没有 `hashCode`，
- * 比较只能交给 C 侧。鸿蒙侧没有 C 桥（`native/platforms/harmonyos/` 尚未产出 `cj_bridge_*`），
- * `ArkWebHost` 的句柄在仓颉侧不参与路由（回调是仓颉闭包，不经 C 中转），因此恒为 false
- * 并留一行 stderr——**不假装相等**（假装相等会把两扇窗的路由串台）。
- */
-@When[os == "Windows"]
-func hostHandleEquals(a: CPointer<Unit>, b: CPointer<Unit>): Bool {
-    unsafe {
-        return cj_bridge_host_eq(a, b) != 0
-    }
-}
-
-@When[os == "Linux" && env != "ohos"]
-func hostHandleEquals(a: CPointer<Unit>, b: CPointer<Unit>): Bool {
-    unsafe {
-        return cj_bridge_host_eq(a, b) != 0
-    }
-}
-
-// 只在无 C 桥的平台用到，声明也放进同一门禁：桌面侧保留会变成 unused variable
-@When[env == "ohos"]
-private var HOST_ROUTE_WARNED: Bool = false
-
-@When[env == "ohos"]
-func hostHandleEquals(a: CPointer<Unit>, b: CPointer<Unit>): Bool {
-    let _ = a
-    let _ = b
-    if (!HOST_ROUTE_WARNED) {
-        HOST_ROUTE_WARNED = true
-        eprintln("[cj-tauri] host route by handle unavailable on this platform: injected host keeps its own callbacks")
-    }
-    return false
-}
-
-/**
- * 造一个「裸宿主句柄」：只分配 C 侧宿主对象（不 init / 不 start、不碰图形栈）
- *
- * 只给单元测试用（子包可见，不算对外 API）。为什么需要这层包皮：`cj_bridge_create` 是
- * `foreign func`——没有函数体、也就没有跨包符号，子包 `cjTauri.tests` 直接调会在**链接期**炸
- * （实测 `ld.lld: error: undefined symbol: cjTauri:cj_bridge_create`）；框架包内包一层就有实体符号了。
- *
- * 只编桌面两平台：鸿蒙没有 C 桥也就没有这个符号，而单测只在桌面跑（`cjpm test` 用桌面目标）。
- */
-@When[os == "Windows"]
-func createBareHostHandle(): CPointer<Unit> {
-    var h: CPointer<Unit> = CPointer<Unit>()
-    unsafe {
-        h = cj_bridge_create()
-    }
-    return h
-}
-
-@When[os == "Linux" && env != "ohos"]
-func createBareHostHandle(): CPointer<Unit> {
-    var h: CPointer<Unit> = CPointer<Unit>()
-    unsafe {
-        h = cj_bridge_create()
-    }
-    return h
-}
+package cjTauri
+
+import std.collection.*
+import stdx.encoding.json.*
+import cjTauri.platform.*
+
+/**
+ * WebView 宿主层（对标 Tauri 2 的 tao + wry 抽象）
+ *
+ * 平台差异由条件编译隔离在各自的宿主文件内，上层完全共用：
+ *   - Linux 桌面：host_webkit.cj（WebKitGTK，经 native/bridge_linux.c 在原生 pthread 运行）
+ *   - Windows   ：host_webview2.cj（WebView2 / Edge Chromium，经 native/bridge_win.c）
+ *   - 鸿蒙       ：ArkWeb（架构预留，条件编译位）
+ * IPC 桥（ipc_hub.cj）与能力安全模型（capability.cj）跨平台复用。
+ */
+
+/**
+ * 宿主能力位（与 native/bridge_core.h 的 `CJ_CAP_*` **逐位对齐**，两侧不许各写各的）
+ *
+ * 由平台在 C 侧 `cj_plat_init` 时填好，经 `WebViewHost.hostCapabilities()` 取回。
+ * 「这台机器上的框架支持什么」是**静态事实**（编出来的桥有没有那块），不是运行期探测：
+ * 应用据此决定要不要建菜单 / 托盘，拿不到就别骗自己。
+ *
+ * 与能力安全模型（capability.cj）的 `Capability` 不是一回事：那个管「页面能不能调某个命令」，
+ * 这个管「宿主有没有这个本事」——所以名字里带 host 前缀，别混。
+ */
+public const CJ_CAP_MENU: Int32 = 1
+
+public const CJ_CAP_TRAY: Int32 = 2
+
+public const CJ_CAP_DRAG_DROP: Int32 = 4
+
+/** 平台通知（与 native/bridge_core.h 的 CJ_CAP_NOTIFICATION 逐位对齐；Linux = freedesktop
+    Notifications，Windows 侧同样置位）。这一位曾漏在仓颉侧：C 侧置了、`system:host` 却看不到，
+    两侧「逐位对齐」的契约当场破了——`scripts/check-static.sh` 现在按名字比对两边的常量表，
+    加位时漏了哪一侧都会在门禁上红。 */
+public const CJ_CAP_NOTIFICATION: Int32 = 8
+
+/** 全局快捷键（与 native/bridge_core.h 的 CJ_CAP_HOTKEY 逐位对齐；Linux = 编进了 X11 支持） */
+public const CJ_CAP_HOTKEY: Int32 = 16
+
+/** 标题栏副标题（与 native/bridge_core.h 的 CJ_CAP_SUBTITLE 逐位对齐；Linux = 菜单栏同排的 label，
+    Windows 的系统菜单没有自绘区、不置位）。应用据它决定要不要自己画页面顶栏。 */
+public const CJ_CAP_SUBTITLE: Int32 = 32
+
+/**
+ * 宿主能力位的**可读形态**（RFC-002 §5.3）：`CJ_CAP_*` 位域 → 具名布尔 + `toJson`。
+ *
+ * 为什么要有它：`hostCapabilities()` 给的是位域，应用与 `system:host` 的调用方要的是
+ * 「menu 有没有」这种具名答案；位域 ↔ 名字的对应只留在这一个地方，
+ * 免得每个消费点各写各的 `(caps & CJ_CAP_MENU) != 0`（写错一位就是一个静默的假答案）。
+ *
+ * `platform` 不在位域里，由调用方（`currentPlatform()`）单独给——位域来自 C 桥，平台标识来自
+ * 仓颉侧的条件编译，两者本就是两个来源。
+ */
+public class HostCapabilities {
+    public let platform: String
+    public let menu: Bool
+    public let tray: Bool
+    public let dragDrop: Bool
+    public let notification: Bool
+    public let hotkey: Bool
+    public let subtitle: Bool
+
+    /** 字段顺序按 `native/bridge_core.h` 的位序（menu / tray / dragDrop / notification / hotkey / subtitle），
+        不是为了好看：位置参数一旦与位序错开，读的人就得来回对表，漏位也就更难发现。 */
+    public init(platform: String, menu: Bool, tray: Bool, dragDrop: Bool, notification: Bool, hotkey: Bool, subtitle: Bool) {
+        this.platform = platform
+        this.menu = menu
+        this.tray = tray
+        this.dragDrop = dragDrop
+        this.notification = notification
+        this.hotkey = hotkey
+        this.subtitle = subtitle
+    }
+
+    /** 位域 → 具名布尔（`platform` 由调用方给，见类注释） */
+    public static func fromBits(platform: String, caps: Int32): HostCapabilities {
+        return HostCapabilities(
+            platform,
+            (caps & CJ_CAP_MENU) != 0,
+            (caps & CJ_CAP_TRAY) != 0,
+            (caps & CJ_CAP_DRAG_DROP) != 0,
+            (caps & CJ_CAP_NOTIFICATION) != 0,
+            (caps & CJ_CAP_HOTKEY) != 0,
+            (caps & CJ_CAP_SUBTITLE) != 0
+        )
+    }
+
+    /** `system:host` 的返回形状：
+        `{"platform":"linux","menu":true,"tray":true,"dragDrop":true,"notification":true,"hotkey":true,"subtitle":true}` */
+    public func toJson(): JsonValue {
+        var obj = JsonObject()
+        obj.put("platform", JsonString(this.platform))
+        obj.put("menu", JsonBool(this.menu))
+        obj.put("tray", JsonBool(this.tray))
+        obj.put("dragDrop", JsonBool(this.dragDrop))
+        obj.put("notification", JsonBool(this.notification))
+        obj.put("hotkey", JsonBool(this.hotkey))
+        obj.put("subtitle", JsonBool(this.subtitle))
+        return obj
+    }
+}
+
+public interface WebViewHost {
+    /**
+     * 本窗口的 label（单窗口阶段恒为 "main"）
+     *
+     * 与 `WindowRecord.label` 是同一个值：注册表是路由的权威来源，宿主自己也留一份——
+     * 给前端注入 label（`window.__CJ_TAURI_LABEL__`）以及将来的窗口内自省都用它。
+     */
+    func label(): String
+
+    /**
+     * 加载页面（唯一入口，RFC §4.3）：Inline / Url / DevServer / Asset 四态
+     *
+     * 原 start(html) / startUrl(url) 双入口在此收敛。Asset 怎么落地是 L0 的事（RFC §6.2）：
+     * 桌面经注入的 AssetResolver 读盘（未注入时按 cwd 相对路径读，与批次 1 行为等价），
+     * 鸿蒙由胶水印化的 rawfile 解析成 HTML 再落沙箱以 file:// 加载。
+     * URL 页面有真实来源，相对路径资源、动态 import、前端路由才成立（file:// 下禁止 fetch/XHR）。
+     */
+    func load(source: PageSource): Unit
+
+    /**
+     * 注入资产解析器（装配层在 load 之前调用；None = 各端默认读盘策略）
+     */
+    func setAssetResolver(resolver: Option<AssetResolver>): Unit
+
+    /**
+     * 注册一段「页面脚本执行前」注入的初始化脚本（多次调用按注册顺序注入）
+     *
+     * 必须在 load() 之前调用：宿主创建 WebView 时一次性交给 C 桥，桥以
+     * document-start 注入（WebKit user script / WebView2 AddScriptToExecuteOnDocumentCreated）。
+     * 因此它对 HTML 与 URL 两种页面来源**一视同仁**——插件的 jsShim 走的就是这条通道（RFC §5.4 的 v2 方案），
+     * 不再靠字符串拼 HTML。空串忽略；脚本是普通 JS 片段，不要自带 <script> 标签。
+     */
+    func addInitScript(js: String): Unit
+
+    /**
+     * 重新加载当前页面（整页 reload，对标浏览器刷新）
+     *
+     * 页面尚未加载时为空操作；开发者工具里的刷新按钮等价于此。
+     */
+    func reload(): Unit
+
+    /**
+     * 应用窗口配置（标题 / 尺寸）；必须在 load() 之前调用，宿主据此创建窗口
+     */
+    func setWindowConfig(config: WindowConfig): Unit
+
+    /**
+     * 是否允许打开开发者工具；必须在 load() 之前调用
+     */
+    func setDevTools(enabled: Bool): Unit
+
+    /**
+     * 运行时打开开发者工具（WebView2 DevTools / WebKit Inspector）
+     */
+    func openDevTools(): Unit
+
+    /**
+     * 设置本窗口的菜单栏（RFC-002 §5.2 的线路文本；空串 = 清空菜单栏）
+     *
+     * 调用时机两头都行：`start()` 之前调用会在建窗时一次建好（未就绪的文本由 C 桥记着）；
+     * 之后就投到宿主 UI 线程重建整棵菜单。
+     * 平台没有菜单能力（`hostCapabilities()` 不含 `CJ_CAP_MENU`）时不影响其它功能——
+     * 「能力位为 0 就别建菜单」是调用方的约定，宿主不替应用猜。
+     */
+    func setMenu(wire: String): Unit
+
+    /**
+     * 运行期改单个菜单项的状态（按 id 找；找不到只记一行日志，不报错）
+     *
+     * 只改状态、不改结构：结构变化走 `setMenu` 整棵重建。状态的真身在平台对象上
+     * （Windows 的 HMENU、GTK 的 GtkCheckMenuItem），模型本身是只读的——理由见 src/menu.cj。
+     */
+    func setMenuItemState(id: String, enabled: Bool, checked: Bool): Unit
+
+    /**
+     * 设置**窗口顶部副标题**：一行文本画在原生菜单栏**同一行的右侧**
+     *
+     * 用途是让应用省掉自己那条页面顶栏——标题 / 保存状态 / 字数挂在原生这一行上，
+     * 界面高度直接少一层。允许运行期高频更新（每次编辑都可能改），平台自己投递到
+     * UI 线程，调用方在哪个线程调都行。
+     * 这是**运行期能力**：建窗之前调用返回 -3（不像 `setMenu` 那样记 pending），
+     * 应用要么等页面加载后再调，要么按返回值如实处理。
+     * 平台没有该能力（能力位不含 `CJ_CAP_SUBTITLE`，Windows 即如此）时如实降级：
+     * 文本不显示、桥打一行 stderr，应用据能力位自己决定画不画页面顶栏。
+     */
+    func setTitlebarSubtitle(text: String): Unit
+
+    /**
+     * 设置拖放策略（RFC-002 §5）：enabled=false 平台不注册 drop target。
+     * 必须在 `load()` 之前调用（Linux 建 view 时决定挂不挂 drag dest）；
+     * 之后调用在未就绪时只记 pending、建窗生效，已就绪平台投 UI 线程重挂。
+     * 平台没有该能力（能力位不含 `CJ_CAP_DRAG_DROP`）时宿主只记日志，不报错。
+     */
+    func setDragDropPolicy(enabled: Bool, files: Bool): Unit
+
+    /**
+     * 注册**全局快捷键**（RFC-003 第 5 期）：wire 一行一条 `<accel>:<id>`（见 `HotkeyModel.toWire`）
+     *
+     * 全局 = 焦点不在本应用窗口时也生效（X11 grab / Win32 RegisterHotKey）。
+     * 允许在 `start()` 之前调（桥记 pending，宿主线程起来后注册）；运行期再调 = 整表替换。
+     * 触发事件以 `{"kind":"hotkey","id":"…"}` 走 shell 回调（按句柄路由）→ 前端 `hotkey:press`。
+     * 平台不支持时桥打一行 stderr 如实说明，调用不报错、事件不来。
+     */
+    func setGlobalHotkeys(wire: String): Unit
+
+    /**
+     * 设置**托盘**（RFC-002 §7.C）：wire 见 `TrayModel.toWire()`，空串 = 移除托盘
+     *
+     * 允许在 `start()` 之前调（桥记 pending，宿主线程装配时创建）；运行期再调 = 整体重建。
+     * 菜单项被点以 `{"kind":"tray","id":"…"}` 走 shell 回调（按句柄路由）→ 前端 `tray:click`。
+     * 平台不支持 / 依赖没编进来时桥打一行 stderr 如实说明，调用不报错、托盘不出现。
+     */
+    func setTray(wire: String): Unit
+
+    /**
+     * 显示 / 隐藏本窗口（对标 Tauri 2 的 `window.show()` / `window.hide()`）
+     *
+     * 隐藏 = 从任务栏与屏幕上消失（Windows 走 `ShowWindow(SW_HIDE)`，Linux 走 `gtk_widget_hide`），
+     * 事件循环照常跑、页面照常活着——所以「最小化到托盘」的还原路径（托盘菜单 / 全局快捷键）才成立。
+     * 两头都能调：`start()` 之前调只记下（建窗时按它定稿，隐藏态的窗口首次出现前就是隐藏的）；
+     * 之后调用投到宿主 UI 线程执行。显示时顺带把窗口提到前台（Linux 是 `gtk_window_present`，
+     * Windows 是 `SetForegroundWindow`）。
+     * 这是**宿主基元**，两平台都实现，不占能力位（没有平台只有一半）。
+     */
+    func setWindowVisible(visible: Bool): Unit
+
+    /**
+     * 最小化到托盘（RFC-003 第 5 期余项，`WindowConfig.minimizeToTray` 的落点）
+     *
+     * enabled=true 时，用户在标题栏点「最小化」不再缩到任务栏，而是**隐藏窗口**
+     * （= `setWindowVisible(false)` 的效果）；还原走应用自己的托盘菜单 / 全局快捷键。
+     * 必须在 `load()` 之前调用（窗口过程要在建窗时就知道这条策略）。
+     * 真到最小化那一刻，平台会复核托盘是否**真的**装上了（能力位不含 `CJ_CAP_TRAY`，
+     * 或应用压根没调 `setTray`）：没装就如实降级为普通最小化并打一行 stderr——
+     * 窗口藏起来却没有任何还原入口，是比「不支持」更糟的结果。
+     */
+    func setMinimizeToTray(enabled: Bool): Unit
+
+    /**
+     * 把本窗口挂到另一扇窗下（**附庸窗 / owned window**）：不重复占任务栏、跟随属主显隐
+     *
+     * 为什么需要它：像 ai-chat 的「网页版」这类**入口聚合窗**，本质是主窗延伸出来的一块，
+     * 独立在任务栏再占一格、还能飘到主窗背后去，用户就会把它当成第二个应用。
+     *
+     * 时机：**在 `load()` 之前**调（与 `setWindowConfig` 同段）——C 桥把属主记进宿主状态，
+     * 平台建窗装配期按它定稿，于是任务栏从头到尾只占一格；`load()` 之后再调也能用
+     * （投 UI 线程执行），代价是任务栏按钮会先出现再消失。Windows 落 `GWLP_HWNDPARENT`
+     * 并补 `WS_EX_TOOLWINDOW`，Linux 落 `gtk_window_set_transient_for` + `skip_taskbar_hint`；
+     * 鸿蒙没有系统任务栏语义，走默认实现即可（应用内窗口）。属主未登记 / 本窗尚未创建时
+     * **只打一行 stderr 并跳过**——这是外观修饰，不该让开窗失败。
+     *
+     * 默认实现是空：只有「有系统窗口系统」的平台才需要覆盖它。
+     */
+    func setOwnerWindow(ownerLabel: String): Unit {
+        // 默认实现是空（鸿蒙等无系统任务栏语义的平台）：显式弃用参数，保住零警告
+        let _ = ownerLabel
+    }
+
+    /**
+     * 在本窗口内创建一个内嵌视图（同窗真标签页，PLT-006），返回视图句柄（> 0 有效，0 = 不支持）
+     *
+     * 为什么需要它：像「网页版」这类入口聚合，把每个站点开成一个**独立窗口**会让任务栏越点越乱、
+     * 还会飘到主窗背后去。内嵌视图是同一扇窗里的真标签页——每个 tab 一个 WebView，
+     * 切换只是换谁露出来，不重载、也不丢滚动位置（vs「单视图 navigate」要等 1–3 秒重新加载）。
+     *
+     * 时机：**页面加载之后**（宿主窗口与主 WebView 都已经在）。命令 worker 线程里调也安全——
+     * 平台会把建视图的动作投回自己的 UI 线程（Windows 同步建 controller 会死锁，这是官方 known issue）。
+     * 返回值**当场**给出，真正的 WebView 稍后才建，所以「句柄有效」不等于「已经能看见内容」。
+     *
+     * **不注入桥**：内嵌视图装的是第三方站点，它的脚本不该拿到 `window.__CJ_TAURI__`，
+     * 更不该能调宿主命令（能力清单管不到外部页面，一旦注入就等于把整份能力开放给任意网站）。
+     * 要与站点通信只能走 URL 参数 / 服务端。
+     *
+     * 坐标是页面 client 坐标（与 `getBoundingClientRect()` 同量纲）：视图是**宿主原生控件**，
+     * 盖在页面之上、不参与页面排版与裁剪，所以应用要按自己的布局持续上报矩形。
+     * 默认实现返回 0：没有窗口内嵌能力的平台（鸿蒙走应用内窗口）如实降级，不假装成功。
+     */
+    func createEmbeddedView(url: String, x: Int32, y: Int32, width: Int32, height: Int32): Int64 {
+        let _ = url
+        let _ = x
+        let _ = y
+        let _ = width
+        let _ = height
+        return 0
+    }
+
+    /**
+     * 显示 / 隐藏内嵌视图——切换 tab 就是这一步（隐藏的视图照常停在原页面，不重载）
+     */
+    func setEmbeddedViewVisible(view: Int64, visible: Bool): Unit {
+        let _ = view
+        let _ = visible
+    }
+
+    /**
+     * 重排内嵌视图：父窗 resize、DPI 变化、页面自己的布局变化之后都要重报
+     *
+     * 原生视图**不会**跟随父窗缩放（与页面元素不同），少了这一路同步就会出现露白边 / 盖住侧栏。
+     */
+    func setEmbeddedViewBounds(view: Int64, x: Int32, y: Int32, width: Int32, height: Int32): Unit {
+        let _ = view
+        let _ = x
+        let _ = y
+        let _ = width
+        let _ = height
+    }
+
+    /**
+     * 让内嵌视图导航到新地址（同一 tab 内跳转用；开新 tab 请再调 createEmbeddedView）
+     */
+    func navigateEmbeddedView(view: Int64, url: String): Unit {
+        let _ = view
+        let _ = url
+    }
+
+    /**
+     * 销毁内嵌视图（关掉那个 tab）：平台会连带收掉它背后的渲染进程
+     *
+     * 窗口销毁时名下的视图由平台自己收，应用不必逐个 destroy——但**上限淘汰（LRU）必须显式调**，
+     * 否则关掉的 tab 只是看不见，内存还占着（一个站点少则几十 MB）。
+     */
+    func destroyEmbeddedView(view: Int64): Unit {
+        let _ = view
+    }
+
+    /**
+     * 本宿主的静态能力位（`CJ_CAP_*` 的按位或）：能不能做菜单 / 托盘 / 文件拖入
+     *
+     * 宿主尚未创建（`dispose()` 之后 / `start()` 之前未分配句柄）返回 0。
+     * 注意与命令级的能力安全模型无关：这里说的是宿主本事，不是页面权限。
+     */
+    func hostCapabilities(): Int32
+
+    /**
+     * 装配本窗口的 shell 事件回调（菜单点击等；载荷是 C 桥的 JSON 信封）
+     *
+     * 与 `setMessageHandler` 同一套路，区别是事件源在宿主侧（应用菜单）而不是页面。
+     * **多窗口下必须按宿主身份路由**：C 侧回调首参是句柄，只有本窗口的句柄才转给本实例的
+     * 这个回调——这正是「回调带宿主身份」的落地方式（见 docs/RFC-菜单-托盘-拖放.md §5.5）。
+     */
+    func setShellHandler(handler: (String) -> Unit): Unit
+
+    /**
+     * 装配本窗口的销毁回调（窗口关闭 / 退出收尾时恰好触发一次）
+     *
+     * 多窗口下按宿主身份路由（C 侧回调首参是句柄），所以每扇窗口装自己的——回调不带参数，
+     * 因为「是哪扇窗」在装配时就已确定（应用可经 `app.hostOf(label)` 逐窗安装）。
+     * 与 `setShellHandler` 同为**可变槽位**：在 `load()` 之后再装同样生效（路由闭包读字段，不是快照）。
+     */
+    func setDestroyHandler(handler: () -> Unit): Unit
+
+    /**
+     * 原生文件选择对话框（阻塞到用户关闭）：返回选中的路径，取消 / 失败返回空串。
+     *
+     * filter 是「描述|模式|描述|模式」拼串（Windows 惯例；GTK 端按同一格式解析），
+     * 例如 "文本文件|*.txt|所有文件|*.*"；空串表示不限制。
+     * 必须在 load() 之后调用——对话框要拿已创建的应用窗口当父窗口。
+     */
+    func showFileDialog(save: Bool, title: String, filter: String): String
+
+    /**
+     * 带默认文件名的文件对话框：除预置名字外与 `showFileDialog` 完全同语义。
+     *
+     * 预置名字的用途是**自动化取证**——探针对原生框发 IDOK 时框里得已有名字才能关，
+     * 返回值因此可预期（预置什么回什么），多窗并发的「结果各归各窗」才验得动。
+     * 平台不支持预置（如 GTK 轮未接）时行为退化为 `showFileDialog`，如实降级。
+     */
+    func showFileDialogPreset(save: Bool, title: String, filter: String, defaultName: String): String
+
+    /**
+     * 原生目录选择对话框（阻塞到用户关闭）：返回选中的目录路径，取消 / 失败返回空串。
+     *
+     * 独立成方法而不是给 `showFileDialog` 加一个开关：选目录在两端都不是「换个动作」——
+     * GTK 是另一个 chooser action，Windows 更是另一套 API（`IFileOpenDialog` +
+     * `FOS_PICKFOLDERS`，`GetOpenFileName` 没有这个能力）。桥侧两者共用同名同签名的
+     * `cj_bridge_show_dialog`，以 kind=6 区分（与文件类 / 消息类并列，见 `dlg_req`）。
+     * 与 `showFileDialog` 同规矩：必须在 load() 之后调用（要拿应用窗口当父窗口）。
+     */
+    func showFolderDialog(title: String): String
+
+    /**
+     * 原生消息对话框（阻塞到用户关闭）：返回用户是否点了「确定」。
+     *
+     * kind 取 "info" / "warning" / "error" / "confirm"（其它值按 info 处理）。
+     * info / warning / error 只有一个「确定」，弹出即成立；只有 confirm 会返回 false。
+     */
+    func showMessageDialog(kind: String, title: String, message: String): Bool
+
+    /**
+     * 写文本进系统剪贴板（上限 8 MiB，C 侧 core 校验）
+     *
+     * 与对话框同类：宿主能力，要在 load() 之后调用（未就绪时返回 false）。
+     */
+    func clipboardWriteText(text: String): Bool
+
+    /**
+     * 读系统剪贴板文本：空 / 非文本 / 平台失败都返回 None，不区分（协议层没有可读的失败明细）
+     */
+    func clipboardReadText(): Option<String>
+
+    /**
+     * 发一条系统通知（发后即忘：提交即返回，显示成败不回传）。
+     * 本平台未实现时返回 false（`system:host` 的能力位会同口径如实上报）。
+     */
+    func notify(title: String, body: String): Bool
+
+    /**
+     * 原生 → JS：在 WebView 中执行脚本
+     */
+    func runJs(js: String): Unit
+
+    /**
+     * 停止本窗口的事件循环（低层原语）
+     *
+     * 应用级退出请用 `AppHost.quit()`——它会走所有窗口；单窗口下两者等价。
+     * 原语留在宿主上是因为「循环归谁所有」只有实现方知道（两平台的收尾方式不同：
+     * Linux 只收主循环、窗口留给收尾销毁，Windows 直接 DestroyWindow），上层不该自己拼。
+     */
+    func quit(): Unit
+
+    /**
+     * 装配前端消息回调（WebView 送来的 JSON 字符串 → IPC hub）
+     */
+    func setMessageHandler(handler: (String) -> Unit): Unit
+
+    /**
+     * 宿主事件循环是否已退出（窗口关闭等），app.run 据此阻塞与收尾
+     *
+     * 同为低层原语：应用级等待用 `AppHost.waitForExit()`，调用方不必自己写轮询。
+     */
+    func shouldQuit(): Bool
+
+    /**
+     * 释放宿主资源（宿主编由 C 侧分配与回收，跨 FFI 不换分配器）：幂等、无需检查调用时机
+     *
+     * TauriApp.run / runUrl 在 waitForExit() 之后调用它；实现方须把句柄置空——
+     * 释放后该实例不可再启动（原生窗口已随销毁路径在关窗时收尾）。
+     * 为什么「关窗」不等于「释放」：见 docs/架构演进-多平台与多窗口.md §6.1。
+     */
+    func dispose(): Unit
+}
+
+/**
+ * 应用级宿主（对标 Tauri 2 的 `AppHandle`）
+ *
+ * 与 `WebViewHost` 的分工：`WebViewHost` 是**一个窗口**（创建、投脚本、对话框、本窗口的循环原语），
+ * `AppHost` 是**整个应用**（退出、按 label 取窗口；将来还有托盘与应用菜单——批次 3 只定模型）。
+ * 批次 2 由 `TauriApp` 实现：它持有窗口注册表，也只有它知道「哪些窗口还开着、应用该不该退」。
+ *
+ * 为什么 quit / waitForExit 收在这一层：它们跨窗口。宿主仍保留 `quit()` / `shouldQuit()` 作低层原语
+ * （循环归宿主所有），但**应用的公开入口只有这里**——多窗口时代的「退出」必然是「先把各窗口收掉」。
+ */
+public interface AppHost {
+    /**
+     * 退出应用：收掉所有窗口的事件循环，`run()` / `runUrl()` 随即返回
+     */
+    func quit(): Unit
+
+    /**
+     * 阻塞到应用退出（窗口关闭 / quit）后返回；`run()` / `runUrl()` 内部调它
+     */
+    func waitForExit(): Unit
+
+    /**
+     * 按 label 取窗口宿主（对标 Tauri 的 `app.get_webview_window(label)`）；未注册返回 None
+     */
+    func hostOf(label: String): Option<WebViewHost>
+}
+
+/**
+ * C 桥原生线程 → 仓颉回调的中转。
+ * 各平台宿主在 prepareHost() 时把「本句柄 → 本实例的回调」登记进路由表，C 侧的 @C 函数按句柄取用。
+ */
+/**
+ * 一条**宿主级回调路由**：C 侧句柄 → 本窗口的三个回调
+ *
+ * C 侧所有回调的入口都是模块级 @C 函数（每个宿主注册的是同一个函数指针），句柄是唯一能分辨
+ * 「哪个窗口」的凭据——三类回调都按句柄查表，查到谁就派发给谁。
+ *
+ * 闭包都是可变的：读的是宿主实例的字段（不是快照），所以应用在 `load()` 之后再调
+ * `setShellHandler` / `setDestroyHandler` 同样生效。
+ */
+class HostRoute {
+    let handle: CPointer<Unit>
+    var onShell: (String) -> Unit
+    var onDestroy: () -> Unit
+    var onDialog: (String) -> Unit
+
+    init(handle: CPointer<Unit>, onShell: (String) -> Unit, onDestroy: () -> Unit,
+         onDialog: (String) -> Unit) {
+        this.handle = handle
+        this.onShell = onShell
+        this.onDestroy = onDestroy
+        this.onDialog = onDialog
+    }
+}
+
+/**
+ * 一条「窗口 label → 系统句柄」登记：附庸窗按 label 找属主窗的句柄
+ *
+ * 与 `HostRoute` 分开是因为用途不同：路由表按**句柄**查回调（C 侧把句柄带回来），
+ * 这里按**label** 查句柄（应用侧只知道主窗的 label）。
+ */
+class HostHandleEntry {
+    let label: String
+    let handle: CPointer<Unit>
+
+    init(label: String, handle: CPointer<Unit>) {
+        this.label = label
+        this.handle = handle
+    }
+}
+
+class HostGlobals {
+    // 前端消息：**有意保留单槽**。报文自带发起窗口的 window label（架构文档 §7.3），
+    // TauriApp 给所有窗口装的是同一只派发器，路由不靠句柄（见 src/app.cj 的 wireHostCallbacks）。
+    static var onMessage: (String) -> Unit = { _ => }
+    // 其余三类回调没有「自带身份」的载荷（销毁无载荷、文件框结果只有路径、shell 事件只有信封），
+    // 只能让 C 侧把句柄带回来。表里每条只认领自己的句柄。
+    // 单槽时代的症状：后装配的窗口覆盖先装配的——「哪扇窗关了」认错、两窗同时开文件框时结果串台
+    // （见 docs/架构演进-多平台与多窗口.md §7.5）。
+    // 登记发生在 prepareHost（run() 之前、宿主线程还没起），派发时才读表 → 登记期没有并发。
+    static var hostRoutes: ArrayList<HostRoute> = ArrayList<HostRoute>()
+    // label → 系统句柄：附庸窗（`setOwnerWindow`）要按 label 找属主窗的句柄。
+    // 与上面同理——登记发生在 prepareHost（宿主线程还没起），读取发生在 load() 之后，
+    // 登记期没有并发；句柄随窗口重建而更新（同 label 覆盖）。
+    static var hostHandles: ArrayList<HostHandleEntry> = ArrayList<HostHandleEntry>()
+
+    /**
+     * 登记（或更新）一条宿主级路由
+     *
+     * 同一句柄重复登记＝换掉旧闭包（宿主被重新 prepare 时不叠加、事件也不会派发两次）；
+     * 句柄比较走 C 侧 `cj_bridge_host_eq`（仓颉的 `CPointer` 不支持 `==`）。
+     * 顺带解决「旧宿主销毁、新宿主复用同一地址」：新宿主登记时就覆盖了那条陈旧路由。
+     */
+    static func registerHostRoute(handle: CPointer<Unit>, onShell: (String) -> Unit,
+                                  onDestroy: () -> Unit, onDialog: (String) -> Unit): Unit {
+        for (r in HostGlobals.hostRoutes) {
+            if (hostHandleEquals(r.handle, handle)) {
+                r.onShell = onShell
+                r.onDestroy = onDestroy
+                r.onDialog = onDialog
+                return
+            }
+        }
+        HostGlobals.hostRoutes.add(HostRoute(handle, onShell, onDestroy, onDialog))
+    }
+
+    /**
+     * 按句柄取路由；查不到返回 None（句柄不属于本进程，或该宿主已注销）
+     */
+    static func hostRouteOf(handle: CPointer<Unit>): Option<HostRoute> {
+        for (r in HostGlobals.hostRoutes) {
+            if (hostHandleEquals(r.handle, handle)) {
+                return Some(r)
+            }
+        }
+        return None
+    }
+
+    /**
+     * 登记（或更新）某窗口的系统句柄；同一 label 重复登记＝覆盖（窗口重建后句柄会变）
+     */
+    static func registerHostHandle(label: String, handle: CPointer<Unit>): Unit {
+        for (i in 0..HostGlobals.hostHandles.size) {
+            if (HostGlobals.hostHandles[i].label == label) {
+                HostGlobals.hostHandles[i] = HostHandleEntry(label, handle)
+                return
+            }
+        }
+        HostGlobals.hostHandles.add(HostHandleEntry(label, handle))
+    }
+
+    /**
+     * 按 label 取句柄；查不到返回 None（该窗口尚未 prepare，或 label 写错）
+     */
+    static func handleOfLabel(label: String): Option<CPointer<Unit>> {
+        for (h in HostGlobals.hostHandles) {
+            if (h.label == label) {
+                return Some(h.handle)
+            }
+        }
+        return None
+    }
+}
+
+/**
+ * kind 字符串 → C 桥的对话框编号（与 native/bridge_linux.c、bridge_win.c 的取值一一对应）
+ */
+func dialogKindCode(kind: String): Int32 {
+    match (kind) {
+        case "warning" => 3
+        case "error" => 4
+        case "confirm" => 5
+        case _ => 2
+    }
+}
+
+/**
+ * 对话框结果回调（C 桥 → 仓颉）：文件类对话框选中的路径经它送回，首参是**发起这次对话框的宿主句柄**。
+ *
+ * 由 C 桥在自己的 UI 线程上调用，与 hostOnMessage 同一套路；按句柄写进对应宿主的结果位，
+ * 再由桥唤醒阻塞的调用方去读。多窗口下两扇窗可以各自开着文件框，结果不许串台。
+ * 非 @When：两平台的 C 侧都调它（签名一致，首参不透明）。
+ */
+@C
+func dialogOnResult(host: CPointer<Unit>, path: CString): Unit {
+    try {
+        match (HostGlobals.hostRouteOf(host)) {
+            case Some(r) => r.onDialog(path.toString())
+            case None => eprintln("[cj-tauri] dialog callback: 未登记的宿主句柄（已丢弃）")
+        }
+    } catch (e: Exception) {
+        eprintln("[cj-tauri] dialog callback error: ${e}")
+    }
+}
+
+/**
+ * 窗口销毁回调（C 桥 → 仓颉）：首参是**被销毁的宿主句柄**（每个宿主恰好触发一次）。
+ *
+ * 曾经写进全局单槽 → 多窗口下「哪扇窗关了」认错（后装配的窗口覆盖先装配的）；
+ * 现在与 shell / 对话框一样按句柄认领。非 @When：两平台的 C 侧都调它。
+ */
+@C
+func hostOnDestroy(host: CPointer<Unit>): Unit {
+    try {
+        match (HostGlobals.hostRouteOf(host)) {
+            case Some(r) => r.onDestroy()
+            case None => eprintln("[cj-tauri] destroy callback: 未登记的宿主句柄（已忽略）")
+        }
+    } catch (e: Exception) {
+        eprintln("[cj-tauri] destroy callback error: ${e}")
+    }
+}
+
+/**
+ * shell 事件回调（C 桥 → 仓颉）：菜单点击等经它送回，首参是**发生事件的宿主句柄**。
+ *
+ * 由 C 桥在宿主 UI 线程上调用（与 hostOnMessage 同一套路）；句柄→实例的解引用走宿主级路由表，
+ * 本函数只做「别抛穿 FFI 边界」这一件事。
+ * 非 @When：两平台的 C 侧都调它（签名一致，首参不透明）。
+ */
+@C
+func shellOnEvent(host: CPointer<Unit>, json: CString): Unit {
+    try {
+        // 认领自己那条：句柄对不上就静默跳过（C 侧只有一个入口，区分就在这里）
+        match (HostGlobals.hostRouteOf(host)) {
+            case Some(r) => r.onShell(json.toString())
+            case None => () // 未登记（旧宿主已注销 / 非本进程句柄）：静默，别在热路径上刷屏
+        }
+    } catch (e: Exception) {
+        eprintln("[cj-tauri] shell callback error: ${e}")
+    }
+}
+
+/**
+ * 创建当前平台的 WebView 宿主（对标 Tauri 2 的 runtime 选择）
+ *
+ * label 按窗口给定（多窗口）：默认窗口传 DEFAULT_WINDOW_LABEL，附加窗口传各自登记的 label。
+ * 必须是构造参数而不是事后 setter——label 决定页面侧 `window.__CJ_TAURI_LABEL__` 与事件过滤，
+ * 启动之后再改就晚了（见 docs/架构演进-多平台与多窗口.md §7.3）。
+ */
+// 判据为什么是 `env`（2026-10-19 校正）：鸿蒙目标下 `os` 仍取 `Linux`，`arch` 也只有
+// `aarch64`——桌面 aarch64 Linux 同样是 `aarch64`，拿它当判据会把「跑在 GTK 上」误判成
+// 「跑在 ArkWeb 上」，两边的宿主实现会互相打架（编译期就撞名）。官方条件编译映射表给出
+// `aarch64-linux-ohos` → `env == "ohos"`、桌面 Linux → `gnu`，这才是真正互斥的维度。
+// 于是桌面 Linux 侧写 `env != "ohos"`：**桌面 aarch64 Linux 因此重新拿回 WebKit 宿主**
+// （改判据之前它落到「只能注入宿主」的分支，是同一处误判的另一半）。
+@When[os == "Linux" && env != "ohos"]
+func createHost(label: String): WebViewHost {
+    return WebKitHost(label)
+}
+
+// 鸿蒙：内置 ArkWeb 宿主（应用侧只负责建 ArkUI 组件并把 controller 交给它，见 src/host_arkweb.cj）
+@When[env == "ohos"]
+func createHost(label: String): WebViewHost {
+    return ArkWebHost(label)
+}
+
+@When[os == "Windows"]
+func createHost(label: String): WebViewHost {
+    return WebView2Host(label)
+}
+
+/**
+ * 两个宿主句柄是否指向同一宿主
+ *
+ * 桌面两平台走 C 桥 `cj_bridge_host_eq`——仓颉的 `CPointer` 既没有 `==` 也没有 `!=`
+ * （实测报 `invalid binary operator '!=' on type 'CPointer<Unit>'`），也没有 `hashCode`，
+ * 比较只能交给 C 侧。鸿蒙侧没有 C 桥（`native/platforms/harmonyos/` 尚未产出 `cj_bridge_*`），
+ * `ArkWebHost` 的句柄在仓颉侧不参与路由（回调是仓颉闭包，不经 C 中转），因此恒为 false
+ * 并留一行 stderr——**不假装相等**（假装相等会把两扇窗的路由串台）。
+ */
+@When[os == "Windows"]
+func hostHandleEquals(a: CPointer<Unit>, b: CPointer<Unit>): Bool {
+    unsafe {
+        return cj_bridge_host_eq(a, b) != 0
+    }
+}
+
+@When[os == "Linux" && env != "ohos"]
+func hostHandleEquals(a: CPointer<Unit>, b: CPointer<Unit>): Bool {
+    unsafe {
+        return cj_bridge_host_eq(a, b) != 0
+    }
+}
+
+// 只在无 C 桥的平台用到，声明也放进同一门禁：桌面侧保留会变成 unused variable
+@When[env == "ohos"]
+private var HOST_ROUTE_WARNED: Bool = false
+
+@When[env == "ohos"]
+func hostHandleEquals(a: CPointer<Unit>, b: CPointer<Unit>): Bool {
+    let _ = a
+    let _ = b
+    if (!HOST_ROUTE_WARNED) {
+        HOST_ROUTE_WARNED = true
+        eprintln("[cj-tauri] host route by handle unavailable on this platform: injected host keeps its own callbacks")
+    }
+    return false
+}
+
+/**
+ * 造一个「裸宿主句柄」：只分配 C 侧宿主对象（不 init / 不 start、不碰图形栈）
+ *
+ * 只给单元测试用（子包可见，不算对外 API）。为什么需要这层包皮：`cj_bridge_create` 是
+ * `foreign func`——没有函数体、也就没有跨包符号，子包 `cjTauri.tests` 直接调会在**链接期**炸
+ * （实测 `ld.lld: error: undefined symbol: cjTauri:cj_bridge_create`）；框架包内包一层就有实体符号了。
+ *
+ * 只编桌面两平台：鸿蒙没有 C 桥也就没有这个符号，而单测只在桌面跑（`cjpm test` 用桌面目标）。
+ */
+@When[os == "Windows"]
+func createBareHostHandle(): CPointer<Unit> {
+    var h: CPointer<Unit> = CPointer<Unit>()
+    unsafe {
+        h = cj_bridge_create()
+    }
+    return h
+}
+
+@When[os == "Linux" && env != "ohos"]
+func createBareHostHandle(): CPointer<Unit> {
+    var h: CPointer<Unit> = CPointer<Unit>()
+    unsafe {
+        h = cj_bridge_create()
+    }
+    return h
+}