cj-tauri 2.0.0 → 2.1.1

package/src/host_webkit.cj

@@ -1,570 +1,663 @@
-package cjTauri
-
-// Linux 侧才用得上（类整体门禁在 Linux）：加同款门禁，免得 Windows 构建把这条当「未使用 import」清掉
-// （host_webview2.cj 是镜像写法。清掉它 Linux 侧当场编炸：`error: undeclared identifier 'std'`，
-// 2026-10-13 实测；48fe433、1747075 已踩过两次——AGENTS §4 同条）
-@When[os == "Linux" && env != "ohos"]
-import std.collection.*
-
-// 页面来源契约（load(source) 收敛，RFC §4.3）：同款门禁，免得别的目标把这条当未使用清掉
-@When[os == "Linux" && env != "ohos"]
-import cjTauri.platform.*
-
-/**
- * C 桥 FFI 声明（native/libcjtbridge.so）
- * 所有 GTK/WebKit 调用在 C 桥的原生 pthread 内执行（见 native/bridge_linux.c 头注释）。
- *
- * 句柄制（批次 1）：宿主状态在 C 侧按句柄隔离，导出一律首参收句柄（`cj_host*`）。
- * 句柄内存由 C 侧分配/回收（create 分配、destroy 释放）——跨 FFI 绝不「这边分配那边释放」
- * （Windows 上 CRT 与仓颉运行时不是同一个分配器）；生命周期约定见
- * docs/架构演进-多平台与多窗口.md §6.1。
- */
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_create(): CPointer<Unit>
-
-/**
- * 释放宿主编：对空指针安全、幂等；调用后该句柄不可再用
- */
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_destroy(h: CPointer<Unit>): Unit
-
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_init(h: CPointer<Unit>, m: CFunc<(CString) -> Unit>, d: CFunc<(CPointer<Unit>) -> Unit>): Unit
-
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_start(h: CPointer<Unit>, html: CString): Unit
-
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_load_url(h: CPointer<Unit>, url: CString): Unit
-
-/**
- * 注册一段预执行脚本（插件 jsShim 等）：须在 cj_bridge_start 之前调用，桥在 document-start 注入
- */
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_add_init_script(h: CPointer<Unit>, js: CString): Unit
-
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_reload(h: CPointer<Unit>): Unit
-
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_set_window(h: CPointer<Unit>, title: CString, width: Int32, height: Int32): Unit
-
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_set_devtools(h: CPointer<Unit>, enabled: Int32): Unit
-
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_set_icon(h: CPointer<Unit>, path: CString): Unit
-
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_open_devtools(h: CPointer<Unit>): Unit
-
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_set_dialog_callback(h: CPointer<Unit>, cb: CFunc<(CPointer<Unit>, CString) -> Unit>): Unit
-
-/**
- * 原生对话框（阻塞式）：kind 0=打开文件 1=保存文件 2=info 3=warning 4=error 5=confirm。
- * 返回 1 = 用户确认；文件类选中路径经 cj_bridge_set_dialog_callback 注册的回调送回。
- */
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_show_dialog(h: CPointer<Unit>, kind: Int32, title: CString, message: CString,
-                                   filter: CString): Int32
-
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_run_js(h: CPointer<Unit>, js: CString): Unit
-
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_quit(h: CPointer<Unit>): Unit
-
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_is_ready(h: CPointer<Unit>): Int32
-
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_should_quit(h: CPointer<Unit>): Int32
-
-/**
- * 菜单栏（RFC-002 §5.4 的线路文本）：空串 = 清空。未就绪时桥只记下，建窗时一次建好。
- */
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_set_menu(h: CPointer<Unit>, wire: CString): Unit
-
-/**
- * 运行期改单个菜单项的状态（按 id 找；找不到只记日志）
- */
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_set_menu_item_state(h: CPointer<Unit>, id: CString, enabled: Int32,
-                                           checked: Int32): Unit
-
-/**
- * 窗口顶部副标题（与菜单栏同一行的右侧）。返回 0 = 已提交、-3 = 宿主未就绪、-4 = 平台没有这块
- */
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_set_titlebar_subtitle(h: CPointer<Unit>, text: CString): Int32
-
-/** 拖放策略（RFC-002 §5）：enabled=0 平台不注册 drop target（默认关） */
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_set_drag_drop(h: CPointer<Unit>, enabled: Int32, files: Int32): Unit
-
-/**
- * 全局快捷键（RFC-003 第 5 期）：wire 一行一条 `<accel>:<id>`。
- * Linux 走 X11 grab（可选编译：桥没编 X11 支持时打一行 stderr 忽略）。
- */
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_set_global_hotkeys(h: CPointer<Unit>, wire: CString): Unit
-
-/**
- * 托盘（RFC-002 §7.C）：wire 见 TrayModel.toWire()，空串 = 移除。
- * Linux 走 libayatana-appindicator3（可选编译：桥没编托盘支持时打一行 stderr 忽略）。
- */
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_set_tray(h: CPointer<Unit>, wire: CString): Unit
-
-/**
- * 窗口可见性（`show()` / `hide()` 的 C 侧落点）：start 之前调只记 pending，就绪后投 GTK 线程执行
- */
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_set_window_visible(h: CPointer<Unit>, visible: Int32): Unit
-
-/**
- * 最小化到托盘策略位（须在 start 之前调）：GTK 侧据此把 window-state-event 里的 iconify 改写成 hide
- */
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_set_minimize_to_tray(h: CPointer<Unit>, enabled: Int32): Unit
-
-/**
- * shell 事件回调（菜单点击等）：首参是宿主句柄，多窗口靠它分辨事件属于哪个窗口
- */
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_set_shell_callback(h: CPointer<Unit>,
-                                          cb: CFunc<(CPointer<Unit>, CString) -> Unit>): Unit
-
-/**
- * 宿主能力位（CJ_CAP_* 的按位或）：未 init 返回 0
- */
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_host_capabilities(h: CPointer<Unit>): Int32
-
-/**
- * 句柄同一性判定（返回 1 = 同一个宿主）：仓颉侧 CPointer 不能比较，判定交回 C 侧
- */
-@When[os == "Linux" && env != "ohos"]
-@C
-foreign func cj_bridge_host_eq(a: CPointer<Unit>, b: CPointer<Unit>): Int32
-
-/**
- * Linux WebKit 宿主实现：通过 C 桥驱动
- */
-@When[os == "Linux" && env != "ohos"]
-public class WebKitHost <: WebViewHost {
-    // 消息回调：GTK 线程（原生 pthread）→ 仓颉
-    public var onMessage: (String) -> Unit = { _ => }
-    // 销毁回调（应用经 setDestroyHandler 装配；由 C 桥按句柄认领，多窗口不串）
-    public var onDestroy: () -> Unit = { => }
-    // 本窗口文件对话框的结果：C 桥按句柄经路由回调写入（两窗各写各的，不许串台）
-    private var dialogResult: String = ""
-    // 本窗口的 shell 事件（菜单点击等）回调：TauriApp 装配时经 setShellHandler 覆盖它做分发，
-    // 未覆盖时只留一行 stderr——菜单点了没人管，至少能在日志里看见。
-    public var shellHandler: (String) -> Unit = { json =>
-        eprintln("[cj-tauri] shell event (no handler): ${json}")
-    }
-    // 窗口配置（标题 / 尺寸），start() 前由 TauriApp 注入
-    private var config: WindowConfig = WindowConfig()
-    // 预执行脚本（插件 jsShim 等）：start 前收集，prepareHost 一次性交给桥，桥在 document-start 注入
-    private var initScripts = ArrayList<String>()
-    // 宿主编（C 侧分配）：空指针 = 尚未创建；dispose() 后置空
-    private var handle: CPointer<Unit> = CPointer<Unit>()
-    // 本窗口的 label（字段名不叫 label：接口有同名方法）。单窗口阶段是常量，
-    // 与 TauriApp 注册的 WindowRecord.label 一致；多窗口时由构造参数给定。
-    private let windowLabel: String
-    // 资产解析器：装配层在 load 前注入（None = 按 cwd 相对路径读盘，与批次 1 行为等价）
-    private var assetResolver: Option<AssetResolver> = None
-
-    public init() {
-        this.windowLabel = DEFAULT_WINDOW_LABEL
-    }
-
-    /**
-     * 带 label 构造（多窗口）：label 必须与 TauriApp 注册表里登记的那个一致，
-     * 页面侧的 `window.__CJ_TAURI_LABEL__` 也取同一个值（由 TauriApp 注入）。
-     */
-    public init(label: String) {
-        this.windowLabel = label
-    }
-
-    public func label(): String {
-        return this.windowLabel
-    }
-
-    public func setMessageHandler(handler: (String) -> Unit): Unit {
-        this.onMessage = handler
-    }
-
-    public func setWindowConfig(config: WindowConfig): Unit {
-        this.config = config
-    }
-
-    public func setDevTools(enabled: Bool): Unit {
-        this.config.devTools = enabled
-    }
-
-    public func addInitScript(js: String): Unit {
-        // 空串忽略（插件没写 shim 时不必占位，桥侧也会再挡一次）
-        if (js.size > 0) {
-            this.initScripts.add(js)
-        }
-    }
-
-    public func openDevTools(): Unit {
-        unsafe {
-            cj_bridge_open_devtools(this.handle)
-        }
-    }
-
-    public func setMenu(wire: String): Unit {
-        // 句柄先建出来：setMenu 允许在 start() 之前调——文本由桥记着，建窗时一次建好
-        this.ensureHandle()
-        unsafe {
-            cj_bridge_set_menu(this.handle, LibC.mallocCString(wire))
-        }
-    }
-
-    public func setMenuItemState(id: String, enabled: Bool, checked: Bool): Unit {
-        if (this.handle.isNull()) {
-            // 还没建宿主就谈不上「改状态」：静默返回，不拿空句柄去 FFI
-            return
-        }
-        var e: Int32 = 0
-        var c: Int32 = 0
-        if (enabled) {
-            e = 1
-        }
-        if (checked) {
-            c = 1
-        }
-        unsafe {
-            cj_bridge_set_menu_item_state(this.handle, LibC.mallocCString(id), e, c)
-        }
-    }
-
-    public func setTitlebarSubtitle(text: String): Unit {
-        if (this.handle.isNull()) {
-            // 运行期能力：建窗前没有落点（见接口注释），不拿空句柄去 FFI
-            return
-        }
-        unsafe {
-            let rc = cj_bridge_set_titlebar_subtitle(this.handle, LibC.mallocCString(text))
-            if (rc != 0) {
-                // 能力位说支持、这次却没写进去：留一行凭证（宿主未就绪 / 文本超 1024 字节）
-                eprintln("[cj-tauri] titlebar subtitle rejected: rc=${rc}")
-            }
-        }
-    }
-
-    public func setDragDropPolicy(enabled: Bool, files: Bool): Unit {
-        // 与 setMenu 同形：允许在 start() 之前调——策略由桥记 pending，建 view 时挂 drag dest
-        this.ensureHandle()
-        var en: Int32 = 0
-        var fi: Int32 = 0
-        if (enabled) {
-            en = 1
-        }
-        if (files) {
-            fi = 1
-        }
-        unsafe {
-            cj_bridge_set_drag_drop(this.handle, en, fi)
-        }
-    }
-
-    public func setGlobalHotkeys(wire: String): Unit {
-        // 与 setMenu 同形：允许在 start() 之前调——线路由桥记 pending，宿主线程起来后 grab
-        this.ensureHandle()
-        unsafe {
-            cj_bridge_set_global_hotkeys(this.handle, LibC.mallocCString(wire))
-        }
-    }
-
-    public func setTray(wire: String): Unit {
-        // 与 setMenu 同形：允许在 start() 之前调——线路由桥记 pending，宿主线程装配时创建
-        this.ensureHandle()
-        unsafe {
-            cj_bridge_set_tray(this.handle, LibC.mallocCString(wire))
-        }
-    }
-
-    public func setWindowVisible(visible: Bool): Unit {
-        // 与 setTray 同形：允许在 start() 之前调（桥记 pending，建窗时定稿）；就绪后投 GTK 线程执行
-        this.ensureHandle()
-        var v: Int32 = 0
-        if (visible) {
-            v = 1
-        }
-        unsafe {
-            cj_bridge_set_window_visible(this.handle, v)
-        }
-    }
-
-    public func setMinimizeToTray(enabled: Bool): Unit {
-        // 策略位：GTK 侧要在建窗时连 window-state-event 信号，所以只在 start() 之前调才有意义
-        this.ensureHandle()
-        var e: Int32 = 0
-        if (enabled) {
-            e = 1
-        }
-        unsafe {
-            cj_bridge_set_minimize_to_tray(this.handle, e)
-        }
-    }
-
-    public func hostCapabilities(): Int32 {
-        if (this.handle.isNull()) {
-            return 0
-        }
-        var caps: Int32 = 0
-        unsafe {
-            caps = cj_bridge_host_capabilities(this.handle)
-        }
-        return caps
-    }
-
-    public func setShellHandler(handler: (String) -> Unit): Unit {
-        this.shellHandler = handler
-    }
-
-    public func setDestroyHandler(handler: () -> Unit): Unit {
-        this.onDestroy = handler
-    }
-
-    public func showFileDialog(save: Bool, title: String, filter: String): String {
-        return this.showFileDialogPreset(save, title, filter, "")
-    }
-
-    public func showFileDialogPreset(save: Bool, title: String, filter: String,
-                                     defaultName: String): String {
-        // GTK 轮未接预置文件名（自动化取证只在 Windows 侧做）：如实降级为普通文件框
-        let _ = defaultName
-        var kind: Int32 = 0
-        if (save) {
-            kind = 1
-        }
-        var ok: Int32 = 0
-        unsafe {
-            ok = cj_bridge_show_dialog(this.handle, kind, LibC.mallocCString(title),
-                                       LibC.mallocCString(""), LibC.mallocCString(filter))
-        }
-        if (ok == 0) {
-            // 取消 / 宿主未就绪：上游按「空路径」处理，不再读结果位
-            return ""
-        }
-        return this.dialogResult
-    }
-
-    public func showFolderDialog(title: String): String {
-        var ok: Int32 = 0
-        unsafe {
-            // 选目录：kind=6（与文件类 / 消息类并列，见 bridge_core.h 的 dlg_req）；
-            // message / filter 不参与，方向框也没有「默认文件名」的概念
-            ok = cj_bridge_show_dialog(this.handle, 6, LibC.mallocCString(title),
-                                       LibC.mallocCString(""), LibC.mallocCString(""))
-        }
-        if (ok == 0) {
-            // 取消 / 宿主未就绪：上游按「空路径」处理
-            return ""
-        }
-        return this.dialogResult
-    }
-
-    public func showMessageDialog(kind: String, title: String, message: String): Bool {
-        var ok: Int32 = 0
-        unsafe {
-            ok = cj_bridge_show_dialog(this.handle, dialogKindCode(kind), LibC.mallocCString(title),
-                                       LibC.mallocCString(message), LibC.mallocCString(""))
-        }
-        return ok != 0
-    }
-
-    public func clipboardWriteText(text: String): Bool {
-        var rc: Int32 = -1
-        unsafe {
-            rc = cj_bridge_clipboard_write_text(this.handle, LibC.mallocCString(text))
-        }
-        if (rc != 0) {
-            eprintln("[cj-tauri] clipboard write failed: code=${rc}")
-        }
-        return rc == 0
-    }
-
-    public func clipboardReadText(): Option<String> {
-        let cs = unsafe { cj_bridge_clipboard_read_text(this.handle) }
-        if (cs.isNull()) {
-            return None<String> // 空 / 非文本 / 平台失败，协议层不区分
-        }
-        let text = cs.toString()
-        unsafe {
-            cj_bridge_clipboard_free(cs) // 归还缓冲：malloc 家族分配，必须走桥的 free
-        }
-        return Some(text)
-    }
-
-    public func notify(title: String, body: String): Bool {
-        var rc: Int32 = -1
-        unsafe {
-            rc = cj_bridge_notification_notify(this.handle, LibC.mallocCString(title),
-                                               LibC.mallocCString(body))
-        }
-        if (rc != 0) {
-            // -4 = 本平台未实现：这是静态事实，stderr 一行说清，不算异常
-            eprintln("[cj-tauri] notification failed: code=${rc}")
-        }
-        return rc == 0
-    }
-
-    /**
-     * 创建宿主编（幂等）：首次启动时分配，dispose() 后置空
-     */
-    private func ensureHandle(): Unit {
-        if (this.handle.isNull()) {
-            unsafe {
-                this.handle = cj_bridge_create()
-            }
-        }
-    }
-
-    /**
-     * 启动前的共同装配：宿主编、回调槽位、窗口配置、图标
-     */
-    private func prepareHost(): Unit {
-        this.ensureHandle()
-        HostGlobals.onMessage = this.onMessage
-        // 宿主级路由：「本句柄 → 本实例的三个回调」登记一条（表式，不覆盖别的窗口）
-        HostGlobals.registerHostRoute(this.handle, { json => this.shellHandler(json) },
-                                      { => this.onDestroy() },
-                                      { path => this.dialogResult = path })
-        var devTools: Int32 = 0
-        if (this.config.devTools) {
-            devTools = 1
-        }
-        unsafe {
-            cj_bridge_init(this.handle, hostOnMessage, hostOnDestroy)
-            // shell 事件回调（菜单点击等）：与消息回调同一套路，多一个首参用来分辨窗口
-            cj_bridge_set_shell_callback(this.handle, shellOnEvent)
-            // 原生对话框的结果回调：与消息回调同一套路，多一个首参（结果只落发起这次对话框的窗口）
-            cj_bridge_set_dialog_callback(this.handle, dialogOnResult)
-            cj_bridge_set_window(this.handle, LibC.mallocCString(this.config.title),
-                                 Int32(this.config.width), Int32(this.config.height))
-            cj_bridge_set_devtools(this.handle, devTools)
-            // 窗口图标：空串表示系统默认图标
-            cj_bridge_set_icon(this.handle, LibC.mallocCString(this.config.iconPath))
-            // 预执行脚本（插件 jsShim 等）：与 BRIDGE_JS 同一条 document-start 通道，按注册顺序排在桥之后
-            for (js in this.initScripts) {
-                cj_bridge_add_init_script(this.handle, LibC.mallocCString(js))
-            }
-        }
-    }
-
-    /**
-     * 加载页面（唯一入口，RFC §4.3）：Inline/Url/DevServer 直接映射；
-     * Asset 经注入的 resolver 读盘，未注入时按 cwd 相对路径读（批次 1 的桌面行为）
-     */
-    public func load(source: PageSource): Unit {
-        match (resolvePage(source, this.assetResolver)) {
-            case StartHtml(html) => this.start(html)
-            case StartUrl(url) => this.startUrl(url)
-        }
-    }
-
-    /** 注入资产解析器（装配层在 load 前调用） */
-    public func setAssetResolver(resolver: Option<AssetResolver>): Unit {
-        this.assetResolver = resolver
-    }
-
-    public func start(html: String): Unit {
-        this.prepareHost()
-        unsafe {
-            cj_bridge_start(this.handle, LibC.mallocCString(html))
-        }
-    }
-
-    public func startUrl(url: String): Unit {
-        this.prepareHost()
-        unsafe {
-            cj_bridge_load_url(this.handle, LibC.mallocCString(url))
-            // 空串表示「页面由 cj_bridge_load_url 指定」（同一次启动里 URL 优先）
-            cj_bridge_start(this.handle, LibC.mallocCString(""))
-        }
-    }
-
-    public func reload(): Unit {
-        unsafe {
-            cj_bridge_reload(this.handle)
-        }
-    }
-
-    public func runJs(js: String): Unit {
-        unsafe {
-            cj_bridge_run_js(this.handle, LibC.mallocCString(js))
-        }
-    }
-
-    public func quit(): Unit {
-        unsafe {
-            cj_bridge_quit(this.handle)
-        }
-    }
-
-    public func shouldQuit(): Bool {
-        unsafe {
-            cj_bridge_should_quit(this.handle) != 0
-        }
-    }
-
-    /**
-     * 释放宿主编（幂等，未创建过则是空操作）：事件循环退出后调用一次，之后句柄置空、本实例不可再启动
-     */
-    public func dispose(): Unit {
-        if (this.handle.isNull()) {
-            return
-        }
-        unsafe {
-            cj_bridge_destroy(this.handle)
-        }
-        this.handle = CPointer<Unit>()
-    }
-}
-
-// C 回调中转：C 桥线程 → 仓颉闭包（经全局槽位）
-@When[os == "Linux" && env != "ohos"]
-@C
-func hostOnMessage(json: CString): Unit {
-    try {
-        HostGlobals.onMessage(json.toString())
-    } catch (e: Exception) {
-        eprintln("[cj-tauri] host callback error: ${e}")
-    }
-}
+package cjTauri
+
+// Linux 侧才用得上（类整体门禁在 Linux）：加同款门禁，免得 Windows 构建把这条当「未使用 import」清掉
+// （host_webview2.cj 是镜像写法。清掉它 Linux 侧当场编炸：`error: undeclared identifier 'std'`，
+// 2026-10-13 实测；48fe433、1747075 已踩过两次——AGENTS §4 同条）
+@When[os == "Linux" && env != "ohos"]
+import std.collection.*
+
+// 页面来源契约（load(source) 收敛，RFC §4.3）：同款门禁，免得别的目标把这条当未使用清掉
+@When[os == "Linux" && env != "ohos"]
+import cjTauri.platform.*
+
+/**
+ * C 桥 FFI 声明（native/libcjtbridge.so）
+ * 所有 GTK/WebKit 调用在 C 桥的原生 pthread 内执行（见 native/bridge_linux.c 头注释）。
+ *
+ * 句柄制（批次 1）：宿主状态在 C 侧按句柄隔离，导出一律首参收句柄（`cj_host*`）。
+ * 句柄内存由 C 侧分配/回收（create 分配、destroy 释放）——跨 FFI 绝不「这边分配那边释放」
+ * （Windows 上 CRT 与仓颉运行时不是同一个分配器）；生命周期约定见
+ * docs/架构演进-多平台与多窗口.md §6.1。
+ */
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_create(): CPointer<Unit>
+
+/**
+ * 释放宿主编：对空指针安全、幂等；调用后该句柄不可再用
+ */
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_destroy(h: CPointer<Unit>): Unit
+
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_init(h: CPointer<Unit>, m: CFunc<(CString) -> Unit>, d: CFunc<(CPointer<Unit>) -> Unit>): Unit
+
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_start(h: CPointer<Unit>, html: CString): Unit
+
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_load_url(h: CPointer<Unit>, url: CString): Unit
+
+/**
+ * 注册一段预执行脚本（插件 jsShim 等）：须在 cj_bridge_start 之前调用，桥在 document-start 注入
+ */
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_add_init_script(h: CPointer<Unit>, js: CString): Unit
+
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_reload(h: CPointer<Unit>): Unit
+
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_set_window(h: CPointer<Unit>, title: CString, width: Int32, height: Int32): Unit
+
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_set_devtools(h: CPointer<Unit>, enabled: Int32): Unit
+
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_set_icon(h: CPointer<Unit>, path: CString): Unit
+
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_open_devtools(h: CPointer<Unit>): Unit
+
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_set_dialog_callback(h: CPointer<Unit>, cb: CFunc<(CPointer<Unit>, CString) -> Unit>): Unit
+
+/**
+ * 原生对话框（阻塞式）：kind 0=打开文件 1=保存文件 2=info 3=warning 4=error 5=confirm。
+ * 返回 1 = 用户确认；文件类选中路径经 cj_bridge_set_dialog_callback 注册的回调送回。
+ */
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_show_dialog(h: CPointer<Unit>, kind: Int32, title: CString, message: CString,
+                                   filter: CString): Int32
+
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_run_js(h: CPointer<Unit>, js: CString): Unit
+
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_quit(h: CPointer<Unit>): Unit
+
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_is_ready(h: CPointer<Unit>): Int32
+
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_should_quit(h: CPointer<Unit>): Int32
+
+/**
+ * 菜单栏（RFC-002 §5.4 的线路文本）：空串 = 清空。未就绪时桥只记下，建窗时一次建好。
+ */
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_set_menu(h: CPointer<Unit>, wire: CString): Unit
+
+/**
+ * 运行期改单个菜单项的状态（按 id 找；找不到只记日志）
+ */
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_set_menu_item_state(h: CPointer<Unit>, id: CString, enabled: Int32,
+                                           checked: Int32): Unit
+
+/**
+ * 窗口顶部副标题（与菜单栏同一行的右侧）。返回 0 = 已提交、-3 = 宿主未就绪、-4 = 平台没有这块
+ */
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_set_titlebar_subtitle(h: CPointer<Unit>, text: CString): Int32
+
+/** 拖放策略（RFC-002 §5）：enabled=0 平台不注册 drop target（默认关） */
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_set_drag_drop(h: CPointer<Unit>, enabled: Int32, files: Int32): Unit
+
+/**
+ * 同窗内嵌视图（PLT-006）：create 返回视图句柄（> 0 有效，0 = 平台未就绪 / 不支持）。
+ * 五条都只是「投递」——桥把动作 g_idle_add 到 GTK 线程执行，句柄当场返回，
+ * 所以 create 成功不代表内容已经出来（视图是随后建的）。
+ */
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_view_create(h: CPointer<Unit>, url: CString,
+                                   x: Int32, y: Int32, width: Int32, height: Int32): Int64
+
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_view_set_visible(h: CPointer<Unit>, view: Int64, visible: Int32): Unit
+
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_view_set_bounds(h: CPointer<Unit>, view: Int64,
+                                       x: Int32, y: Int32, width: Int32, height: Int32): Unit
+
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_view_navigate(h: CPointer<Unit>, view: Int64, url: CString): Unit
+
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_view_destroy(h: CPointer<Unit>, view: Int64): Unit
+
+/**
+ * 全局快捷键（RFC-003 第 5 期）：wire 一行一条 `<accel>:<id>`。
+ * Linux 走 X11 grab（可选编译：桥没编 X11 支持时打一行 stderr 忽略）。
+ */
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_set_global_hotkeys(h: CPointer<Unit>, wire: CString): Unit
+
+/**
+ * 托盘（RFC-002 §7.C）：wire 见 TrayModel.toWire()，空串 = 移除。
+ * Linux 走 libayatana-appindicator3（可选编译：桥没编托盘支持时打一行 stderr 忽略）。
+ */
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_set_tray(h: CPointer<Unit>, wire: CString): Unit
+
+/**
+ * 窗口可见性（`show()` / `hide()` 的 C 侧落点）：start 之前调只记 pending，就绪后投 GTK 线程执行
+ */
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_set_window_visible(h: CPointer<Unit>, visible: Int32): Unit
+
+/**
+ * 把 h 挂到 owner 下（transient-for + skip_taskbar_hint）：不重复占任务栏、跟随属主显隐
+ *
+ * 与 Windows 侧同名同签名，上层调用点不分平台（§2 的跨平台约束）。
+ */
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_set_owner_window(h: CPointer<Unit>, owner: CPointer<Unit>): Unit
+
+/**
+ * 最小化到托盘策略位（须在 start 之前调）：GTK 侧据此把 window-state-event 里的 iconify 改写成 hide
+ */
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_set_minimize_to_tray(h: CPointer<Unit>, enabled: Int32): Unit
+
+/**
+ * shell 事件回调（菜单点击等）：首参是宿主句柄，多窗口靠它分辨事件属于哪个窗口
+ */
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_set_shell_callback(h: CPointer<Unit>,
+                                          cb: CFunc<(CPointer<Unit>, CString) -> Unit>): Unit
+
+/**
+ * 宿主能力位（CJ_CAP_* 的按位或）：未 init 返回 0
+ */
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_host_capabilities(h: CPointer<Unit>): Int32
+
+/**
+ * 句柄同一性判定（返回 1 = 同一个宿主）：仓颉侧 CPointer 不能比较，判定交回 C 侧
+ */
+@When[os == "Linux" && env != "ohos"]
+@C
+foreign func cj_bridge_host_eq(a: CPointer<Unit>, b: CPointer<Unit>): Int32
+
+/**
+ * Linux WebKit 宿主实现：通过 C 桥驱动
+ */
+@When[os == "Linux" && env != "ohos"]
+public class WebKitHost <: WebViewHost {
+    // 消息回调：GTK 线程（原生 pthread）→ 仓颉
+    public var onMessage: (String) -> Unit = { _ => }
+    // 销毁回调（应用经 setDestroyHandler 装配；由 C 桥按句柄认领，多窗口不串）
+    public var onDestroy: () -> Unit = { => }
+    // 本窗口文件对话框的结果：C 桥按句柄经路由回调写入（两窗各写各的，不许串台）
+    private var dialogResult: String = ""
+    // 本窗口的 shell 事件（菜单点击等）回调：TauriApp 装配时经 setShellHandler 覆盖它做分发，
+    // 未覆盖时只留一行 stderr——菜单点了没人管，至少能在日志里看见。
+    public var shellHandler: (String) -> Unit = { json =>
+        eprintln("[cj-tauri] shell event (no handler): ${json}")
+    }
+    // 窗口配置（标题 / 尺寸），start() 前由 TauriApp 注入
+    private var config: WindowConfig = WindowConfig()
+    // 预执行脚本（插件 jsShim 等）：start 前收集，prepareHost 一次性交给桥，桥在 document-start 注入
+    private var initScripts = ArrayList<String>()
+    // 宿主编（C 侧分配）：空指针 = 尚未创建；dispose() 后置空
+    private var handle: CPointer<Unit> = CPointer<Unit>()
+    // 本窗口的 label（字段名不叫 label：接口有同名方法）。单窗口阶段是常量，
+    // 与 TauriApp 注册的 WindowRecord.label 一致；多窗口时由构造参数给定。
+    private let windowLabel: String
+    // 资产解析器：装配层在 load 前注入（None = 按 cwd 相对路径读盘，与批次 1 行为等价）
+    private var assetResolver: Option<AssetResolver> = None
+
+    public init() {
+        this.windowLabel = DEFAULT_WINDOW_LABEL
+    }
+
+    /**
+     * 带 label 构造（多窗口）：label 必须与 TauriApp 注册表里登记的那个一致，
+     * 页面侧的 `window.__CJ_TAURI_LABEL__` 也取同一个值（由 TauriApp 注入）。
+     */
+    public init(label: String) {
+        this.windowLabel = label
+    }
+
+    public func label(): String {
+        return this.windowLabel
+    }
+
+    public func setMessageHandler(handler: (String) -> Unit): Unit {
+        this.onMessage = handler
+    }
+
+    public func setWindowConfig(config: WindowConfig): Unit {
+        this.config = config
+    }
+
+    public func setDevTools(enabled: Bool): Unit {
+        this.config.devTools = enabled
+    }
+
+    public func addInitScript(js: String): Unit {
+        // 空串忽略（插件没写 shim 时不必占位，桥侧也会再挡一次）
+        if (js.size > 0) {
+            this.initScripts.add(js)
+        }
+    }
+
+    public func openDevTools(): Unit {
+        unsafe {
+            cj_bridge_open_devtools(this.handle)
+        }
+    }
+
+    // ===== 同窗内嵌视图（PLT-006）：桥侧把动作投回 GTK 线程，这里只是转发 =====
+
+    public func createEmbeddedView(url: String, x: Int32, y: Int32, width: Int32, height: Int32): Int64 {
+        // 窗口没就绪时桥会如实回 0 并打一行 stderr（不是崩溃路径）
+        this.ensureHandle()
+        unsafe {
+            return cj_bridge_view_create(this.handle, LibC.mallocCString(url), x, y, width, height)
+        }
+    }
+
+    public func setEmbeddedViewVisible(view: Int64, visible: Bool): Unit {
+        var flag: Int32 = 0
+        if (visible) {
+            flag = 1
+        }
+        unsafe {
+            cj_bridge_view_set_visible(this.handle, view, flag)
+        }
+    }
+
+    public func setEmbeddedViewBounds(view: Int64, x: Int32, y: Int32, width: Int32, height: Int32): Unit {
+        unsafe {
+            cj_bridge_view_set_bounds(this.handle, view, x, y, width, height)
+        }
+    }
+
+    public func navigateEmbeddedView(view: Int64, url: String): Unit {
+        unsafe {
+            cj_bridge_view_navigate(this.handle, view, LibC.mallocCString(url))
+        }
+    }
+
+    public func destroyEmbeddedView(view: Int64): Unit {
+        unsafe {
+            cj_bridge_view_destroy(this.handle, view)
+        }
+    }
+
+    public func setMenu(wire: String): Unit {
+        // 句柄先建出来：setMenu 允许在 start() 之前调——文本由桥记着，建窗时一次建好
+        this.ensureHandle()
+        unsafe {
+            cj_bridge_set_menu(this.handle, LibC.mallocCString(wire))
+        }
+    }
+
+    public func setMenuItemState(id: String, enabled: Bool, checked: Bool): Unit {
+        if (this.handle.isNull()) {
+            // 还没建宿主就谈不上「改状态」：静默返回，不拿空句柄去 FFI
+            return
+        }
+        var e: Int32 = 0
+        var c: Int32 = 0
+        if (enabled) {
+            e = 1
+        }
+        if (checked) {
+            c = 1
+        }
+        unsafe {
+            cj_bridge_set_menu_item_state(this.handle, LibC.mallocCString(id), e, c)
+        }
+    }
+
+    public func setTitlebarSubtitle(text: String): Unit {
+        if (this.handle.isNull()) {
+            // 运行期能力：建窗前没有落点（见接口注释），不拿空句柄去 FFI
+            return
+        }
+        unsafe {
+            let rc = cj_bridge_set_titlebar_subtitle(this.handle, LibC.mallocCString(text))
+            if (rc != 0) {
+                // 能力位说支持、这次却没写进去：留一行凭证（宿主未就绪 / 文本超 1024 字节）
+                eprintln("[cj-tauri] titlebar subtitle rejected: rc=${rc}")
+            }
+        }
+    }
+
+    public func setDragDropPolicy(enabled: Bool, files: Bool): Unit {
+        // 与 setMenu 同形：允许在 start() 之前调——策略由桥记 pending，建 view 时挂 drag dest
+        this.ensureHandle()
+        var en: Int32 = 0
+        var fi: Int32 = 0
+        if (enabled) {
+            en = 1
+        }
+        if (files) {
+            fi = 1
+        }
+        unsafe {
+            cj_bridge_set_drag_drop(this.handle, en, fi)
+        }
+    }
+
+    public func setGlobalHotkeys(wire: String): Unit {
+        // 与 setMenu 同形：允许在 start() 之前调——线路由桥记 pending，宿主线程起来后 grab
+        this.ensureHandle()
+        unsafe {
+            cj_bridge_set_global_hotkeys(this.handle, LibC.mallocCString(wire))
+        }
+    }
+
+    public func setTray(wire: String): Unit {
+        // 与 setMenu 同形：允许在 start() 之前调——线路由桥记 pending，宿主线程装配时创建
+        this.ensureHandle()
+        unsafe {
+            cj_bridge_set_tray(this.handle, LibC.mallocCString(wire))
+        }
+    }
+
+    public func setOwnerWindow(ownerLabel: String): Unit {
+        if (ownerLabel.size == 0) {
+            return
+        }
+        // 与 setWindowVisible 同形：允许在 start() 之前调（桥记 pending，建窗时定稿）
+        this.ensureHandle()
+        match (HostGlobals.handleOfLabel(ownerLabel)) {
+            case Some(ownerHandle) =>
+                unsafe {
+                    cj_bridge_set_owner_window(this.handle, ownerHandle)
+                }
+            case None =>
+                // 外观修饰失败不该拦着开窗，但要在日志里留凭证
+                eprintln("[cj-tauri] setOwnerWindow(${ownerLabel}): 该窗口尚未登记，跳过")
+        }
+    }
+
+    public func setWindowVisible(visible: Bool): Unit {
+        // 与 setTray 同形：允许在 start() 之前调（桥记 pending，建窗时定稿）；就绪后投 GTK 线程执行
+        this.ensureHandle()
+        var v: Int32 = 0
+        if (visible) {
+            v = 1
+        }
+        unsafe {
+            cj_bridge_set_window_visible(this.handle, v)
+        }
+    }
+
+    public func setMinimizeToTray(enabled: Bool): Unit {
+        // 策略位：GTK 侧要在建窗时连 window-state-event 信号，所以只在 start() 之前调才有意义
+        this.ensureHandle()
+        var e: Int32 = 0
+        if (enabled) {
+            e = 1
+        }
+        unsafe {
+            cj_bridge_set_minimize_to_tray(this.handle, e)
+        }
+    }
+
+    public func hostCapabilities(): Int32 {
+        if (this.handle.isNull()) {
+            return 0
+        }
+        var caps: Int32 = 0
+        unsafe {
+            caps = cj_bridge_host_capabilities(this.handle)
+        }
+        return caps
+    }
+
+    public func setShellHandler(handler: (String) -> Unit): Unit {
+        this.shellHandler = handler
+    }
+
+    public func setDestroyHandler(handler: () -> Unit): Unit {
+        this.onDestroy = handler
+    }
+
+    public func showFileDialog(save: Bool, title: String, filter: String): String {
+        return this.showFileDialogPreset(save, title, filter, "")
+    }
+
+    public func showFileDialogPreset(save: Bool, title: String, filter: String,
+                                     defaultName: String): String {
+        // GTK 轮未接预置文件名（自动化取证只在 Windows 侧做）：如实降级为普通文件框
+        let _ = defaultName
+        var kind: Int32 = 0
+        if (save) {
+            kind = 1
+        }
+        var ok: Int32 = 0
+        unsafe {
+            ok = cj_bridge_show_dialog(this.handle, kind, LibC.mallocCString(title),
+                                       LibC.mallocCString(""), LibC.mallocCString(filter))
+        }
+        if (ok == 0) {
+            // 取消 / 宿主未就绪：上游按「空路径」处理，不再读结果位
+            return ""
+        }
+        return this.dialogResult
+    }
+
+    public func showFolderDialog(title: String): String {
+        var ok: Int32 = 0
+        unsafe {
+            // 选目录：kind=6（与文件类 / 消息类并列，见 bridge_core.h 的 dlg_req）；
+            // message / filter 不参与，方向框也没有「默认文件名」的概念
+            ok = cj_bridge_show_dialog(this.handle, 6, LibC.mallocCString(title),
+                                       LibC.mallocCString(""), LibC.mallocCString(""))
+        }
+        if (ok == 0) {
+            // 取消 / 宿主未就绪：上游按「空路径」处理
+            return ""
+        }
+        return this.dialogResult
+    }
+
+    public func showMessageDialog(kind: String, title: String, message: String): Bool {
+        var ok: Int32 = 0
+        unsafe {
+            ok = cj_bridge_show_dialog(this.handle, dialogKindCode(kind), LibC.mallocCString(title),
+                                       LibC.mallocCString(message), LibC.mallocCString(""))
+        }
+        return ok != 0
+    }
+
+    public func clipboardWriteText(text: String): Bool {
+        var rc: Int32 = -1
+        unsafe {
+            rc = cj_bridge_clipboard_write_text(this.handle, LibC.mallocCString(text))
+        }
+        if (rc != 0) {
+            eprintln("[cj-tauri] clipboard write failed: code=${rc}")
+        }
+        return rc == 0
+    }
+
+    public func clipboardReadText(): Option<String> {
+        let cs = unsafe { cj_bridge_clipboard_read_text(this.handle) }
+        if (cs.isNull()) {
+            return None<String> // 空 / 非文本 / 平台失败，协议层不区分
+        }
+        let text = cs.toString()
+        unsafe {
+            cj_bridge_clipboard_free(cs) // 归还缓冲：malloc 家族分配，必须走桥的 free
+        }
+        return Some(text)
+    }
+
+    public func notify(title: String, body: String): Bool {
+        var rc: Int32 = -1
+        unsafe {
+            rc = cj_bridge_notification_notify(this.handle, LibC.mallocCString(title),
+                                               LibC.mallocCString(body))
+        }
+        if (rc != 0) {
+            // -4 = 本平台未实现：这是静态事实，stderr 一行说清，不算异常
+            eprintln("[cj-tauri] notification failed: code=${rc}")
+        }
+        return rc == 0
+    }
+
+    /**
+     * 创建宿主编（幂等）：首次启动时分配，dispose() 后置空
+     */
+    private func ensureHandle(): Unit {
+        if (this.handle.isNull()) {
+            unsafe {
+                this.handle = cj_bridge_create()
+            }
+        }
+    }
+
+    /**
+     * 启动前的共同装配：宿主编、回调槽位、窗口配置、图标
+     */
+    private func prepareHost(): Unit {
+        this.ensureHandle()
+        HostGlobals.onMessage = this.onMessage
+        // 宿主级路由：「本句柄 → 本实例的三个回调」登记一条（表式，不覆盖别的窗口）
+        HostGlobals.registerHostRoute(this.handle, { json => this.shellHandler(json) },
+                                      { => this.onDestroy() },
+                                      { path => this.dialogResult = path })
+        // label → 句柄：附庸窗（setOwnerWindow）按 label 找属主窗，登记点与路由表同步
+        HostGlobals.registerHostHandle(this.windowLabel, this.handle)
+        var devTools: Int32 = 0
+        if (this.config.devTools) {
+            devTools = 1
+        }
+        unsafe {
+            cj_bridge_init(this.handle, hostOnMessage, hostOnDestroy)
+            // shell 事件回调（菜单点击等）：与消息回调同一套路，多一个首参用来分辨窗口
+            cj_bridge_set_shell_callback(this.handle, shellOnEvent)
+            // 原生对话框的结果回调：与消息回调同一套路，多一个首参（结果只落发起这次对话框的窗口）
+            cj_bridge_set_dialog_callback(this.handle, dialogOnResult)
+            cj_bridge_set_window(this.handle, LibC.mallocCString(this.config.title),
+                                 Int32(this.config.width), Int32(this.config.height))
+            cj_bridge_set_devtools(this.handle, devTools)
+            // 窗口图标：空串表示系统默认图标
+            cj_bridge_set_icon(this.handle, LibC.mallocCString(this.config.iconPath))
+            // 预执行脚本（插件 jsShim 等）：与 BRIDGE_JS 同一条 document-start 通道，按注册顺序排在桥之后
+            for (js in this.initScripts) {
+                cj_bridge_add_init_script(this.handle, LibC.mallocCString(js))
+            }
+        }
+    }
+
+    /**
+     * 加载页面（唯一入口，RFC §4.3）：Inline/Url/DevServer 直接映射；
+     * Asset 经注入的 resolver 读盘，未注入时按 cwd 相对路径读（批次 1 的桌面行为）
+     */
+    public func load(source: PageSource): Unit {
+        match (resolvePage(source, this.assetResolver)) {
+            case StartHtml(html) => this.start(html)
+            case StartUrl(url) => this.startUrl(url)
+        }
+    }
+
+    /** 注入资产解析器（装配层在 load 前调用） */
+    public func setAssetResolver(resolver: Option<AssetResolver>): Unit {
+        this.assetResolver = resolver
+    }
+
+    public func start(html: String): Unit {
+        this.prepareHost()
+        unsafe {
+            cj_bridge_start(this.handle, LibC.mallocCString(html))
+        }
+    }
+
+    public func startUrl(url: String): Unit {
+        this.prepareHost()
+        unsafe {
+            cj_bridge_load_url(this.handle, LibC.mallocCString(url))
+            // 空串表示「页面由 cj_bridge_load_url 指定」（同一次启动里 URL 优先）
+            cj_bridge_start(this.handle, LibC.mallocCString(""))
+        }
+    }
+
+    public func reload(): Unit {
+        unsafe {
+            cj_bridge_reload(this.handle)
+        }
+    }
+
+    public func runJs(js: String): Unit {
+        unsafe {
+            cj_bridge_run_js(this.handle, LibC.mallocCString(js))
+        }
+    }
+
+    public func quit(): Unit {
+        unsafe {
+            cj_bridge_quit(this.handle)
+        }
+    }
+
+    public func shouldQuit(): Bool {
+        unsafe {
+            cj_bridge_should_quit(this.handle) != 0
+        }
+    }
+
+    /**
+     * 释放宿主编（幂等，未创建过则是空操作）：事件循环退出后调用一次，之后句柄置空、本实例不可再启动
+     */
+    public func dispose(): Unit {
+        if (this.handle.isNull()) {
+            return
+        }
+        unsafe {
+            cj_bridge_destroy(this.handle)
+        }
+        this.handle = CPointer<Unit>()
+    }
+}
+
+// C 回调中转：C 桥线程 → 仓颉闭包（经全局槽位）
+@When[os == "Linux" && env != "ohos"]
+@C
+func hostOnMessage(json: CString): Unit {
+    try {
+        HostGlobals.onMessage(json.toString())
+    } catch (e: Exception) {
+        eprintln("[cj-tauri] host callback error: ${e}")
+    }
+}