cj-tauri 0.8.0 → 1.1.0

package/src/api_system.cj

@@ -14,7 +14,7 @@ public class SystemCommands <: CommandHandler {
             case "system:version" => this.version()
             case "system:ping" => this.ping(args)
             case "system:echo" => this.echo(args)
-            case "system:devtools" => this.devTools(ipc)
+            case "system:devtools" => this.devTools(ipc)
             case "system:host" => this.hostCapabilities(ipc)
             case _ => throw CommandException("unknown system command: ${cmd}")
         }
@@ -24,6 +24,7 @@ public class SystemCommands <: CommandHandler {
         var obj = JsonObject()
         obj.put("name", JsonString("cj-tauri"))
         obj.put("version", JsonString(CJ_TAURI_VERSION))
+        obj.put("protocol", JsonString(CJ_IPC_PROTOCOL))
         obj.put("cangjie", JsonString("1.0.5"))
         obj.put("platform", JsonString(currentPlatform()))
         return obj
@@ -52,8 +53,15 @@ public class SystemCommands <: CommandHandler {
      * 「这个应用准不准」，两者都要过才叫真能用——放行了但平台没有，事件永远不会出现。
      * 取**调用方那个窗口**的位域（多窗口下可能不同，如 Linux 托盘取决于桥怎么编的）。
      * 与 `system:*` 的其它命令一样，需在清单里声明 `system:host` 才可调用（三处联动）。
+     *
+     * 另带 `logFile`（RFC-003 第 5 期）：日志落盘是**进程级**的，不是某一台宿主的能力，
+     * 所以它没有对应的布尔位——空串＝没开（stderr 照旧），非空＝诊断都落在那个文件里，
+     * 远程报障先问这一个字段，比让用户去翻平台目录快。
      */
     private func hostCapabilities(ipc: IpcContext): JsonValue {
-        return HostCapabilities.fromBits(currentPlatform(), ipc.hostCapabilities()).toJson()
+        let obj = HostCapabilities.fromBits(currentPlatform(), ipc.hostCapabilities())
+            .toJson().asObject()
+        obj.put("logFile", JsonString(currentLogFilePath()))
+        return obj
     }
 }

package/src/app.cj

@@ -183,6 +183,126 @@ public class TauriApp <: AppHost {
         return this.setMenuItemStateTo(DEFAULT_WINDOW_LABEL, id, enabled, checked)
     }
 
+    /**
+     * 设置默认窗口的拖放策略（RFC-002 §5；必须在 `start()` / `startUrl()` 之前调）
+     *
+     * 打开后页面经 `dragdrop:files` 事件收到拖入的文件路径数组（`paths: [...]`），
+     * 该事件需在能力清单 `events` 里声明；不设 = 不注册 drop target（默认关）。
+     * 平台没有该能力（如 Windows 桩阶段）时宿主只记日志，不报错——能力位经 `system:host` 如实上报。
+     */
+    public func setDragDrop(policy: DragDropPolicy): TauriApp {
+        return this.setDragDropTo(DEFAULT_WINDOW_LABEL, policy)
+    }
+
+    /** 指定窗口版本（多窗口）：语义同 `setDragDrop`，作用于 `label` 那个窗口 */
+    public func setDragDropTo(label: String, policy: DragDropPolicy): TauriApp {
+        match (this.hostOf(label)) {
+            case Some(host) =>
+                host.setDragDropPolicy(policy.enabled, policy.files)
+            case None =>
+                eprintln("[cj-tauri] setDragDrop: 未注册的窗口 label \"${label}\"（策略未设置）")
+        }
+        return this
+    }
+
+    /**
+     * 注册**默认窗口**的全局快捷键（RFC-003 第 5 期）
+     *
+     * 全局 = 焦点不在本应用时也生效（Linux = X11 grab，能力位 `hotkey` 如实上报）。
+     * 触发时页面收 `hotkey:press` 事件（载荷 `{"id":…}`，需在能力清单 `events` 声明）；
+     * 应用侧钩子挂 `onShellEvent`（信封 `kind == "hotkey"`）。运行期再调 = 整表替换。
+     */
+    public func setGlobalHotkeys(keys: HotkeyModel): TauriApp {
+        return this.setGlobalHotkeysTo(DEFAULT_WINDOW_LABEL, keys)
+    }
+
+    /** 指定窗口版本（多窗口）：语义同 `setGlobalHotkeys`，作用于 `label` 那个窗口 */
+    public func setGlobalHotkeysTo(label: String, keys: HotkeyModel): TauriApp {
+        match (this.hostOf(label)) {
+            case Some(host) =>
+                host.setGlobalHotkeys(keys.toWire())
+            case None =>
+                eprintln("[cj-tauri] setGlobalHotkeys: 未注册的窗口 label \"${label}\"（快捷键未设置）")
+        }
+        return this
+    }
+
+    /**
+     * 设置**托盘**（RFC-002 §7.C；托盘是应用级资源，走默认窗口的宿主）
+     *
+     * 图标 + 提示 + 右键菜单一次给定；重复调用 = 整体重建，`TrayModel("")` = 移除。
+     * 菜单项被点时页面收 `tray:click` 事件（载荷 `{"id":…}`，需在能力清单 `events` 声明）；
+     * 应用侧钩子挂 `onShellEvent`（信封 `kind == "tray"`）。平台不支持时桥如实打日志、托盘不出现。
+     */
+    public func setTray(tray: TrayModel): TauriApp {
+        match (this.hostOf(DEFAULT_WINDOW_LABEL)) {
+            case Some(host) =>
+                host.setTray(tray.toWire())
+            case None =>
+                eprintln("[cj-tauri] setTray: 默认窗口未注册（托盘未设置）")
+        }
+        return this
+    }
+
+    /**
+     * 开启日志落盘（RFC-003 第 5 期）
+     *
+     * 单文件产物是 Windows 的 GUI 子系统、双击时没有控制台，stderr 无处可去——开了它，C 桥与
+     * 仓颉侧**两侧**的诊断都落到这一个文件（`system:host` 的 `logFile` 回读生效路径）。
+     * **越早调越好**（宿主的装配期日志比 `run()` 还早）：最晚在 `run()` / `runUrl()` 之前。
+     * 超预算按份轮转（`log.1` … `log.keep`）；不调用 = 不落盘，行为与之前完全一致。
+     * `CJ_TAURI_LOG_MAX_KB` / `CJ_TAURI_LOG_KEEP` 可覆盖这里的预算——报障时让用户改环境变量，
+     * 不必动代码。被拒（路径打不开 / 已激活）时桥打一行 stderr 并**保持不落盘**，这里不假装成功。
+     */
+    public func setLogFile(path: String): TauriApp {
+        return this.setLogFile(path, CJ_LOG_DEFAULT_MAX_KB, CJ_LOG_DEFAULT_KEEP)
+    }
+
+    /** 显式给预算的版本（仓颉没有默认参数值，所以拆成两个重载） */
+    public func setLogFile(path: String, maxKB: Int64, keep: Int64): TauriApp {
+        let kb = logBudgetFromEnv("CJ_TAURI_LOG_MAX_KB", maxKB)
+        let kp = logBudgetFromEnv("CJ_TAURI_LOG_KEEP", keep)
+        let _ = enableLogFile(path, kb, kp) // 成败都由桥出声：成功落文件、被拒落 stderr
+        return this
+    }
+
+    /**
+     * 落到平台惯例目录的日志文件（`appName` 作文件名）
+     *
+     * Linux `$XDG_STATE_HOME/cj-tauri/<app>.log`（缺省 `~/.local/state/…`）、
+     * Windows `%LOCALAPPDATA%\cj-tauri\logs\<app>.log`；`CJ_TAURI_LOG` 给了路径时优先用它——
+     * 报障的人只需带一个环境变量启动，不必知道平台目录在哪（也不受应用是否设过名字影响）。
+     */
+    public func setLogToDefaultFile(appName: String): TauriApp {
+        return this.setLogToDefaultFile(appName, CJ_LOG_DEFAULT_MAX_KB, CJ_LOG_DEFAULT_KEEP)
+    }
+
+    /** 显式给预算的版本（同上，重载而非默认参数） */
+    public func setLogToDefaultFile(appName: String, maxKB: Int64, keep: Int64): TauriApp {
+        return this.setLogFile(logPathOrDefault(logEnvOr("CJ_TAURI_LOG", ""), appName), maxKB, keep)
+    }
+
+    /**
+     * 显示 / 隐藏**默认窗口**（对标 Tauri 2 的 `window.show()` / `window.hide()`）
+     *
+     * 典型用途是「最小化到托盘」的还原路径：托盘菜单项或全局快捷键触发时 `setWindowVisible(true)`。
+     * `run()` / `runUrl()` 之前调用同样有效（宿主记下，建窗时定稿）。
+     */
+    public func setWindowVisible(visible: Bool): TauriApp {
+        return this.setWindowVisibleTo(DEFAULT_WINDOW_LABEL, visible)
+    }
+
+    /** 指定窗口版本（多窗口）：语义同 `setWindowVisible`，作用于 `label` 那个窗口 */
+    public func setWindowVisibleTo(label: String, visible: Bool): TauriApp {
+        match (this.hostOf(label)) {
+            case Some(host) =>
+                host.setWindowVisible(visible)
+            case None =>
+                eprintln("[cj-tauri] setWindowVisible: 未注册的窗口 label \"${label}\"（窗口未改可见性）")
+        }
+        return this
+    }
+
     /** 指定窗口版本（多窗口）：语义同 `setMenuItemState`，作用于 `label` 那个窗口 */
     public func setMenuItemStateTo(label: String, id: String, enabled: Bool, checked: Bool): TauriApp {
         this.applyMenuState(label, id, enabled, checked)
@@ -324,6 +444,34 @@ public class TauriApp <: AppHost {
         return this
     }
 
+    /**
+     * 运行期给某插件的 scope 追加一条白名单模式（**不落盘**，重启即失效）：插件名如 `"http"`，
+     * 模式写法同 `src/scope.cj`（主机名 / 路径，支持 `*` `**` `?` 与变量）。
+     *
+     * 调用时机是硬约束：**只应在应用已取得用户明确确认之后调**——框架替你做不了确认，它不理解
+     * 你的 UI 语义。典型落法是先在原生确认框里问到「是」
+     * （`host.showMessageDialog("confirm", …, "允许 <主机> 出网？")` 返回 true）再调本方法；
+     * 页面自己点不了原生对话框，所以「确认」这一步天然挡得住被注入的页面自行加白。
+     * 另外，清单 `scopes.<插件>.deny` 命中即拒，这里加白掀不掉 deny（判定顺序仍是先 deny 后 allow）。
+     *
+     * 需要重启仍生效就在启动时把存过的模式重新叠一遍（持久化与存放位置由应用自己决定）。
+     *
+     * 返回 false = 这条模式**没被采纳**（空串、或含 `*` / `?` 与制表/换行这类脏字符）：加白的语义是
+     * 「往白名单里加一条具体值」，带通配透传进来等于全放行，所以注册中心当场拒。调用方应把 false
+     * 当成「没放行」如实回给用户，别写成成功。
+     */
+    public func allowScopePattern(plugin: String, pattern: String): Bool {
+        return this.capabilities.addRuntimeScopeAllow(plugin, pattern)
+    }
+
+    /**
+     * 某插件的 scope 此刻是否放行某个值（口径与判定完全一致：清单 + 运行期叠加，先 deny 后 allow）。
+     * 没写 scope 的插件恒为 true（旧行为：全量放行）。
+     */
+    public func isScopeAllowed(plugin: String, value: String): Bool {
+        return this.capabilities.scopeAllowsValue(plugin, value)
+    }
+
     /**
      * 直接添加 capability
      */
@@ -481,11 +629,21 @@ public class TauriApp <: AppHost {
         }
         this.started = true
 
+        // 环境变量兜底（RFC-003 第 5 期）：应用没显式开日志时，`CJ_TAURI_LOG` 仍能把它开起来——
+        // 已经分发出去的 exe 改不了代码，报障时靠这一个变量拿凭证。放在装配的最早处，
+        // 让宿主与插件的启动期日志都赶得上；不设这个变量 = 一行不动，行为与之前完全一致。
+        if (currentLogFilePath().size == 0) {
+            let envPath = logEnvOr("CJ_TAURI_LOG", "")
+            if (envPath.size > 0) {
+                let _ = this.setLogFile(envPath)
+            }
+        }
+
         // 注入内置系统命令
         this.hub.register("system:version", SystemCommands())
         this.hub.register("system:ping", SystemCommands())
         this.hub.register("system:echo", SystemCommands())
-        this.hub.register("system:devtools", SystemCommands())
+        this.hub.register("system:devtools", SystemCommands())
         this.hub.register("system:host", SystemCommands())
 
         // 未显式挂载 capability 时，自动扫描 capabilities/ 目录（对标 Tauri）
@@ -513,6 +671,8 @@ public class TauriApp <: AppHost {
         }
         // 集注册完才可能判定「清单引用的集有没有插件提供」，故放在插件装配之后
         warnUnknownPermissionSets(this.capabilities)
+        // 路径 scope 的缺省行为提示（RFC-003 第 4 期）：没为吃 scope 的插件写规则 = 全量放行，如实告知
+        warnUnscopedPlugins(this.plugins, this.capabilities)
 
         // 装配：宿主消息 → IPC hub；hub 输出 → 宿主 JS
         this.wireHostCallbacks(this.host)
@@ -526,6 +686,9 @@ public class TauriApp <: AppHost {
         this.hub.hostCapabilitiesSink = { label => this.windowCapabilities(label) }
 
         this.host.setWindowConfig(this.config)
+        // 最小化到托盘同属「建窗时定稿」的窗口行为（窗口过程要提前知道这条策略），
+        // 所以与窗口配置一起在 start() 之前交给宿主——能力位不含托盘时平台会拒绝并出声
+        this.host.setMinimizeToTray(this.config.minimizeToTray)
     }
 
     /**
@@ -632,90 +795,90 @@ public class TauriApp <: AppHost {
      * 多窗口下每个宿主都挂**同一只**派发器：报文自带发起窗口的 label（架构文档 §7.3），
      * 路由不需要按句柄分表——所以这里传的是同一个闭包，不是每窗口一份。
      */
-    /**
-     * 应用层的 shell 事件钩子（对标 Tauri 的 `on_menu_event`）
-     *
-     * 回调参数是 `(信封 JSON, 发生事件的窗口 label)`。给原始 JSON 而不是解析后的对象：钩子多半
-     * 是应用自己写的诊断 / 日志（探针就靠它断言），原样透传最不容易丢信息。label 是必需的——
-     * 钩子是应用级的，一份回调要能分辨事件来自哪个窗口。
-     *
-     * 与前端事件**两条路都走**：先按注册顺序跑钩子（应用侧决策，例如改菜单项状态），再投前端
-     * 事件（页面自己 `listen("menu:click", …)`）。钩子里抛异常只留一行 stderr，不挡后面的钩子
-     * 与前端事件。
-     */
-    public func onShellEvent(handler: (String, String) -> Unit): TauriApp {
-        this.shellHooks.add(handler)
-        return this
-    }
-
-    /**
-     * 装配本窗口的 shell 事件分发（应用层是唯一安装者）
-     *
-     * 必须在宿主 `start()` / `startUrl()` **之前**装：窗口一建出来菜单点击就可能来，装晚了会漏。
-     * 宿主层的 `setShellHandler` 是**可变槽位**（后装覆盖先装），所以应用要处理 shell 事件请用
-     * `onShellEvent()`（应用级钩子，可叠加多条），不要和框架抢宿主槽位——抢赢的那个会让框架的
-     * 前端事件分发失效。
-     */
-    private func wireShellEvents(host: WebViewHost, label: String): Unit {
-        host.setShellHandler({ json => this.dispatchShellEvent(label, json) })
-    }
-
-    /**
-     * shell 事件 → 应用层钩子 + 前端事件（按窗口投递）
-     *
-     * 路由靠**闭包捕获的 label**：C 侧已按宿主句柄把事件分给了本窗口的回调（见 host.cj 的
-     * `ShellRoute`），这里再按 label 投前端事件，多窗口下不会串。事件放不放行由 capability 清单
-     * 决定——没在清单里声明 `menu:click` 就是静默丢弃（最小权限不破）。
-     *
-     * 本函数跑在**宿主 UI 线程**上（C 桥的 shell 回调就在那儿），所以中途不碰 GTK / WebKit 之外
-     * 的东西：投递走 `emitToWindow` → `jsSink`，与其它事件同一条路。
-     */
-    private func dispatchShellEvent(label: String, json: String): Unit {
-        for (hook in this.shellHooks) {
-            try {
-                hook(json, label)
-            } catch (e: Exception) {
-                eprintln("[cj-tauri] shell hook 抛出异常（已忽略）：${e}")
-            }
-        }
-        match (parseShellEnvelope(json)) {
-            case None => eprintln("[cj-tauri] shell event 信封解析失败（已丢弃）：${json}")
-            case Some(obj) =>
-                var kind = ""
-                if (let Some(k) <- shellString(obj, "kind")) {
-                    kind = k
-                }
-                match (shellEventNameFor(kind)) {
-                    case None => eprintln("[cj-tauri] shell event: 未知 kind \"${kind}\"（未投递）：${json}")
-                    case Some(event) =>
-                        if (kind == "menu") {
-                            this.syncMenuStateFromShellObj(label, obj)
-                        }
-                        try {
-                            this.hub.emitToWindow(event, obj, label)
-                        } catch (e: Exception) {
-                            eprintln("[cj-tauri] shell event 投递失败（已忽略）：${e}")
-                        }
-                }
-        }
-    }
-
-    /**
-     * 菜单事件里的平台真值 → 应用层模型：id / enabled / checked 三者齐了才写
-     *
-     * 缺字段不拿默认值顶（见 shellBool 的注释）——这条路径写错的表现是「勾选莫名回退」，
-     * 比少同步一次难查得多。
-     */
-    private func syncMenuStateFromShellObj(label: String, obj: JsonObject): Unit {
-        if (let Some(id) <- shellString(obj, "id")) {
-            if (let Some(enabled) <- shellBool(obj, "enabled")) {
-                if (let Some(checked) <- shellBool(obj, "checked")) {
-                    this.syncMenuStateFromShell(label, id, enabled, checked)
-                }
-            }
-        }
-    }
-
+    /**
+     * 应用层的 shell 事件钩子（对标 Tauri 的 `on_menu_event`）
+     *
+     * 回调参数是 `(信封 JSON, 发生事件的窗口 label)`。给原始 JSON 而不是解析后的对象：钩子多半
+     * 是应用自己写的诊断 / 日志（探针就靠它断言），原样透传最不容易丢信息。label 是必需的——
+     * 钩子是应用级的，一份回调要能分辨事件来自哪个窗口。
+     *
+     * 与前端事件**两条路都走**：先按注册顺序跑钩子（应用侧决策，例如改菜单项状态），再投前端
+     * 事件（页面自己 `listen("menu:click", …)`）。钩子里抛异常只留一行 stderr，不挡后面的钩子
+     * 与前端事件。
+     */
+    public func onShellEvent(handler: (String, String) -> Unit): TauriApp {
+        this.shellHooks.add(handler)
+        return this
+    }
+
+    /**
+     * 装配本窗口的 shell 事件分发（应用层是唯一安装者）
+     *
+     * 必须在宿主 `start()` / `startUrl()` **之前**装：窗口一建出来菜单点击就可能来，装晚了会漏。
+     * 宿主层的 `setShellHandler` 是**可变槽位**（后装覆盖先装），所以应用要处理 shell 事件请用
+     * `onShellEvent()`（应用级钩子，可叠加多条），不要和框架抢宿主槽位——抢赢的那个会让框架的
+     * 前端事件分发失效。
+     */
+    private func wireShellEvents(host: WebViewHost, label: String): Unit {
+        host.setShellHandler({ json => this.dispatchShellEvent(label, json) })
+    }
+
+    /**
+     * shell 事件 → 应用层钩子 + 前端事件（按窗口投递）
+     *
+     * 路由靠**闭包捕获的 label**：C 侧已按宿主句柄把事件分给了本窗口的回调（见 host.cj 的
+     * `ShellRoute`），这里再按 label 投前端事件，多窗口下不会串。事件放不放行由 capability 清单
+     * 决定——没在清单里声明 `menu:click` 就是静默丢弃（最小权限不破）。
+     *
+     * 本函数跑在**宿主 UI 线程**上（C 桥的 shell 回调就在那儿），所以中途不碰 GTK / WebKit 之外
+     * 的东西：投递走 `emitToWindow` → `jsSink`，与其它事件同一条路。
+     */
+    private func dispatchShellEvent(label: String, json: String): Unit {
+        for (hook in this.shellHooks) {
+            try {
+                hook(json, label)
+            } catch (e: Exception) {
+                eprintln("[cj-tauri] shell hook 抛出异常（已忽略）：${e}")
+            }
+        }
+        match (parseShellEnvelope(json)) {
+            case None => eprintln("[cj-tauri] shell event 信封解析失败（已丢弃）：${json}")
+            case Some(obj) =>
+                var kind = ""
+                if (let Some(k) <- shellString(obj, "kind")) {
+                    kind = k
+                }
+                match (shellEventNameFor(kind)) {
+                    case None => eprintln("[cj-tauri] shell event: 未知 kind \"${kind}\"（未投递）：${json}")
+                    case Some(event) =>
+                        if (kind == "menu") {
+                            this.syncMenuStateFromShellObj(label, obj)
+                        }
+                        try {
+                            this.hub.emitToWindow(event, obj, label)
+                        } catch (e: Exception) {
+                            eprintln("[cj-tauri] shell event 投递失败（已忽略）：${e}")
+                        }
+                }
+        }
+    }
+
+    /**
+     * 菜单事件里的平台真值 → 应用层模型：id / enabled / checked 三者齐了才写
+     *
+     * 缺字段不拿默认值顶（见 shellBool 的注释）——这条路径写错的表现是「勾选莫名回退」，
+     * 比少同步一次难查得多。
+     */
+    private func syncMenuStateFromShellObj(label: String, obj: JsonObject): Unit {
+        if (let Some(id) <- shellString(obj, "id")) {
+            if (let Some(enabled) <- shellBool(obj, "enabled")) {
+                if (let Some(checked) <- shellBool(obj, "checked")) {
+                    this.syncMenuStateFromShell(label, id, enabled, checked)
+                }
+            }
+        }
+    }
+
     private func wireHostCallbacks(host: WebViewHost): Unit {
         host.setMessageHandler({ raw =>
             this.hub.handleRawMessage(raw)

package/src/arkweb_proxy.cj

@@ -0,0 +1,56 @@
+package cjTauri
+
+/**
+ * HarmonyOS ArkWeb 的**桥接函数**（ArkUI-free 的那一半）
+ *
+ * ## 为什么组件本体不在这里
+ *
+ * 2026-10-19 真机定位到一个必须先说清的硬约束：**框架包（独立编译单元，`output-type = "static"`）
+ * 一旦 import `kit.ArkUI.*` / `kit.ArkWeb.*` / `ohos.arkui.component.web.Web`，应用就会在启动瞬间
+ * 死在包初始化**——`InitCJLibrary → cangjie_entry::package_global_init → cjTauri::package_global_init`
+ * 里那条 `bl _CGP9kit.ArkUIiiHv@plt` 跳进未映射地址，`hilog` 里只有一行
+ * `SIGSEGV(SEGV_MAPERR)@0x0004exxx`，窗口起不来、我方日志一行都没有。
+ *
+ * 判据来自一组对照实验（都在这台真机上跑的）：
+ * 1. 入口包自己写 `@Component` + `Web`（不引用框架）→ 正常启动，还拉起了 `:gpu` / `:render`；
+ * 2. 入口包只引用框架的一个字符串常量（`DEFAULT_WINDOW_LABEL`）→ 照样崩在包初始化；
+ * 3. 把 `arkweb_view.cj`（框架里唯一碰 ArkUI 的文件）移出编译 → 立刻正常启动
+ *    （`onCreated` / `onWindowStageCreate` 都有、`SIGSEGV` 计数为 0）。
+ *
+ * 也就是说：**同一张 PLT 表，在入口包里调用 `_CGP9kit.ArkUIiiHv` 是好的，在框架包里就解析不了。**
+ * 所以 ArkUI 声明式组件只能由**应用模块**持有（这也正是 ArkUI 的模型：组件树属于应用的 UIAbility），
+ * 框架这边只保留与 UI 无关的接线——报文、脚本队列、label 注入。
+ *
+ * 应用侧要写的东西见 `docs/鸿蒙ArkWeb接入踩坑.md`：一个 `@Component`，`build()` 里放 `Web(...)` 并
+ * 把下面两个函数塞进 `javaScriptProxy` 的 `funcList`。
+ */
+
+/**
+ * 页面 → 原生：`javaScriptProxy` 的 `post`（同步调用，返回值无意义）
+ *
+ * ArkWeb 的 proxy 只能挂在组件上，且回调签名固定为 `(String) -> String`；窗口身份靠
+ * **闭包捕获 label** 传进来（应用侧写 `{ raw => arkWebProxyPost(this.windowLabel, raw) }`），不靠全局单槽——
+ * 多窗口下静态单槽会让后建的窗口认领先前窗口的报文（AGENTS §4 的「静态单槽」坑）。
+ */
+@When[env == "ohos"]
+public func arkWebProxyPost(label: String, raw: String): String {
+    match (ArkWebRuntime.hostFor(label)) {
+        case Some(h) => h.acceptPageMessage(raw)
+        case None => ()
+    }
+    return ""
+}
+
+/**
+ * 原生 → 页面：`javaScriptProxy` 的 `poll`（同步调用，返回待执行脚本的 JSON 数组）
+ *
+ * 页面侧 `setInterval` 每 10ms 拉一次（见 `ARKWEB_BRIDGE_JS` 的 pump）——
+ * 这样框架线程不需要定时器、也不需要碰 ArkUI。
+ */
+@When[env == "ohos"]
+public func arkWebProxyPoll(label: String): String {
+    match (ArkWebRuntime.hostFor(label)) {
+        case Some(h) => return h.pollScriptsJson()
+        case None => return "[]"
+    }
+}

package/src/arkweb_script.cj

@@ -0,0 +1,154 @@
+package cjTauri
+
+/**
+ * 鸿蒙 ArkWeb 侧的页面桥脚本与注入片段
+ *
+ * ## 为什么要另存一份（而不是复用 `native/core/bridge_js.h`）
+ *
+ * 那一份是 **C 宏**（`CJ_BRIDGE_JS(POST_STMT, RELOAD_STMT)`），只有编 C 桥的平台能用；
+ * 鸿蒙没有 C 桥（宿主在仓颉侧直接驱动 ArkWeb），拿不到宏展开结果。所以这里按同一份语义
+ * 落成仓颉常量——**改动要两边同步**，判断「哪边漏了」的判据是：页面上 `invoke` / `emit` /
+ * `listen` / `reload` / `_dispatch` 五个入口的行为是否与桌面一致（桥只负责路由与回执匹配，
+ * 不含业务）。
+ *
+ * ## 与桌面版的唯一差异
+ *
+ * `post`：桌面走 `window.chrome.webview.postMessage` / `window.webkit.messageHandlers`，
+ * 鸿蒙走 `javaScriptProxy` 注入的同步方法（`window.__CJ_TAURI_HOST__.post(json)`）。
+ * 同步调用不携带返回值语义——它是「投递即返回」，回执仍由 `_dispatch` 从仓颉侧推回来。
+ *
+ * ## 转义口径
+ *
+ * 用 raw string（`#"..."#`）：三引号字符串会先处理反斜杠转义（AGENTS §4 踩过，内联 JS 会被
+ * 拆断而 stderr 一行提示都没有），raw string 原样保留。因此本文件里的 JS **不要**出现 `"#`
+ * 这个序列（那是 raw string 的收尾）。
+ */
+@When[env == "ohos"]
+public let ARKWEB_PROXY_NAME: String = "__CJ_TAURI_HOST__"
+
+@When[env == "ohos"]
+let ARKWEB_BRIDGE_JS: String = #"window.__CJ_TAURI__ = (function () {
+  var seq = 0;
+  var pending = {};
+  var listeners = {};
+  var coalesceSlots = Object.create(null);
+  var coalesceTimer = null;
+  var coalesceRaf = 0;
+  function flushCoalesced() {
+    if (coalesceTimer !== null) { clearTimeout(coalesceTimer); coalesceTimer = null; }
+    coalesceRaf = 0;
+    var due = coalesceSlots;
+    coalesceSlots = Object.create(null);
+    for (var name in due) {
+      var arr = listeners[name] || [];
+      for (var i = 0; i < arr.length; i++) arr[i](due[name]);
+    }
+  }
+  function scheduleCoalesced() {
+    if (coalesceTimer !== null || coalesceRaf) return;
+    coalesceTimer = setTimeout(flushCoalesced, 50);
+  }
+  var cachedLabel = null;
+  function labelOf() {
+    if (cachedLabel === null) {
+      var v = (typeof window !== 'undefined') ? window.__CJ_TAURI_LABEL__ : null;
+      cachedLabel = (typeof v === 'string' && v.length > 0) ? v : 'main';
+    }
+    return cachedLabel;
+  }
+  function post(obj) {
+    try {
+      var host = window.__CJ_TAURI_HOST__;
+      if (host && typeof host.post === 'function') host.post(JSON.stringify(obj));
+    } catch (e) { }
+  }
+  /*
+   * 原生 -> 页面的推送：页面**只负责叫一声**，脚本由原生在 post 回调里用
+   * `controller.runJavaScript` 推回来。
+   *
+   * 为什么不是「页面 poll 取返回值」：2026-10-19 真机实测，`javaScriptProxy` 的
+   * funcList 返回值**传不回 JS**（换上无条件返回固定串的桩，页面拿到的仍是 null），
+   * 而 post 方向一切正常。所以同步取数模型不成立，只能反过来推。
+   * 心跳周期的代价只是一次同步调用；队列空时原生什么都不做。
+   */
+  var pumping = false;
+  function pump() {
+    if (pumping) return;
+    pumping = true;
+    try {
+      var host = window.__CJ_TAURI_HOST__;
+      if (host && typeof host.post === 'function') {
+        host.post('{"type":"pull","window":' + JSON.stringify(labelOf()) + '}');
+      }
+    } catch (e2) { } finally { pumping = false; }
+  }
+  try { setInterval(pump, 50); } catch (e3) { }
+  return {
+    invoke: function (cmd, args) {
+      var id = ++seq;
+      var p = new Promise(function (resolve, reject) { pending[id] = { resolve: resolve, reject: reject }; });
+      post({ type: 'invoke', id: id, cmd: cmd, args: args || {}, window: labelOf() });
+      return p;
+    },
+    listen: function (event, cb) {
+      if (!listeners[event]) listeners[event] = [];
+      listeners[event].push(cb);
+      return function () {
+        var arr = listeners[event] || [];
+        var i = arr.indexOf(cb);
+        if (i >= 0) arr.splice(i, 1);
+      };
+    },
+    emit: function (event, payload) {
+      var id = ++seq;
+      var p = new Promise(function (resolve, reject) { pending[id] = { resolve: resolve, reject: reject }; });
+      post({ type: 'emit', id: id, event: event, payload: payload === undefined ? {} : payload, window: labelOf() });
+      return p;
+    },
+    reload: function () {
+      post({ type: 'reload', window: labelOf() });
+    },
+    _dispatch: function (msg) {
+      if (!msg) return;
+      if (msg.type === 'resolve') {
+        var p = pending[msg.id];
+        if (!p) return;
+        delete pending[msg.id];
+        if (msg.ok) p.resolve(msg.data); else p.reject(new Error(msg.error || 'invoke failed'));
+      } else if (msg.type === 'event') {
+        if (msg.window && msg.window !== labelOf()) return;
+        if (msg.coalesce) {
+          coalesceSlots[msg.event] = msg.payload;
+          scheduleCoalesced();
+          return;
+        }
+        var arr = listeners[msg.event] || [];
+        for (var i = 0; i < arr.length; i++) arr[i](msg.payload);
+      }
+    }
+  };
+})();"#
+
+/**
+ * 窗口 label 注入片段（等价于桌面 C 侧的 document-start 注入）
+ *
+ * 单引号包住 JSON 字符串：label 由应用给定，实际取值来自 `WindowConfig.label` / 默认 label，
+ * 里层用 JSON 转义保证引号与反斜杠安全（不做手工拼接转义）。
+ */
+@When[env == "ohos"]
+public func arkWebLabelScript(label: String): String {
+    return "window.__CJ_TAURI_LABEL__ = ${jsStringLiteral(label)};"
+}
+
+/**
+ * 把一段「已经是 JSON」的报文推给页面（不经 JSON 二次解析）
+ *
+ * 桌面两平台由 C 桥拼 `_dispatch(报文)` 并 ExecuteScript；这里产出同形状的脚本字符串，
+ * 由 UI 线程的组件交给 `controller.runJavaScript`。报文本身来自 `IpcHub` 的序列化结果，
+ * 所以这里**只包一层括号**、不做转义（做了会变成字符串字面量，页面收到的是文本而非对象）。
+ */
+@When[env == "ohos"]
+func arkWebDispatchScript(payloadJson: String): String {
+    return "window.__CJ_TAURI__ && window.__CJ_TAURI__._dispatch(${payloadJson});"
+}
+