cj-tauri 2.0.0 → 2.1.0

package/src/ipc_hub.cj

@@ -1,337 +1,337 @@
-package cjTauri
-
-import std.collection.*
-import stdx.encoding.json.*
-
-/**
- * 命令处理器接口（对标 Tauri command）
- * 实现方注册到 IpcHub，前端 invoke 时经 capability 校验后调用。
- */
-public interface CommandHandler {
-    /**
-     * 处理命令并返回结果 JSON 值。
-     * @param cmd   命令名
-     * @param args  前端传入的参数对象
-     * @param ipc   IPC 上下文（可发事件、取窗口信息）
-     * @return 成功返回值；如需失败可在实现中抛 CommandException
-     */
-    func handle(cmd: String, args: JsonObject, ipc: IpcContext): JsonValue
-}
-
-/**
- * 命令执行异常：message 将作为 error 返回给前端
- */
-public class CommandException <: Exception {
-    public init(msg: String) {
-        super(msg)
-    }
-}
-
-/**
- * IPC 上下文：命令执行时可访问
- */
-public class IpcContext {
-    public let window: String
-    private let hub: IpcHub
-
-    public init(window: String, hub: IpcHub) {
-        this.window = window
-        this.hub = hub
-    }
-
-    /**
-     * 向当前窗口推送事件
-     */
-    public func emit(event: String, payload: JsonValue): Unit {
-        this.hub.emitToWindow(event, payload, this.window)
-    }
-
-    /**
-     * 向当前窗口推送「只保最新」的事件：同一帧内同名事件只投最后一次 payload，中间值丢弃
-     *
-     * 高频进度类事件用；需要每条都到达的继续用 `emit`。选型理由见 docs/IPC-通信机制.md §6 第 5 项。
-     */
-    public func emitLatest(event: String, payload: JsonValue): Unit {
-        this.hub.emitLatest(event, payload, this.window)
-    }
-
-    /**
-     * 打开开发者工具（宿主实现），供内置 system:devtools 与应用自定义命令使用
-     */
-    public func openDevTools(): Unit {
-        this.hub.openDevTools()
-    }
-
-    /**
-     * 本窗口的宿主能力位（`CJ_CAP_*` 按位或），供内置 system:host 使用
-     *
-     * 取的是**发起命令那个窗口**的位域：能力位是宿主级事实，多窗口下可能不同（如 Linux 托盘
-     * 取决于桥怎么编的）。窗口没登记 / 宿主还没建句柄时返回 0——后者不代表「平台没这本事」，
-     * 所以页面自检应在窗口起来之后做（与 examples/menu 探针的口径一致）。
-     */
-    public func hostCapabilities(): Int32 {
-        return this.hub.hostCapabilities(this.window)
-    }
-
-    /**
-     * 解析并校验一个路径参数（RFC-003 第 4 期）。
-     *
-     * 带路径参数的插件**一律**用它取代自己拼路径：清单里为插件写了 scope 就按
-     * allow/deny 判定，越界抛业务错误；没写就维持旧行为（全量放行，启动时有提示）。
-     * 返回值是规范化后的路径（绝对、已解析软链接），直接交给 std.fs 用即可。
-     */
-    public func resolveScopedPath(plugin: String, rawPath: String): String {
-        return this.hub.resolveScopedPath(plugin, rawPath)
-    }
-
-    /**
-     * 取某插件的 scope 规则**本体**（不给判定）：给「匹配语义不是文件路径」的插件用——
-     * 如 http 插件把 allow/deny 模式当**主机名**匹配（不能先走 normalizeScopePath 的
-     * 文件路径折叠）。判定本身仍走共享层 `scopeAllows`，插件不自己写第二份 glob。
-     */
-    public func scopeRuleFor(plugin: String): Option<ScopeRule> {
-        return this.hub.scopeRuleFor(plugin)
-    }
-}
-
-/**
- * IPC 中心：命令注册、能力校验、消息分发、事件推送
- */
-public class IpcHub {
-    private var commands: HashMap<String, CommandHandler> = HashMap<String, CommandHandler>()
-    private var capabilities: CapabilityRegistry = CapabilityRegistry()
-    // 事件 / 回执投递通道：由宿主层注入（把 JSON 字符串投递给前端 JS）。
-    // 第二个参数是**目标窗口 label**：批次 2 起由 TauriApp 按窗口注册表派发，
-    // 空串 = 广播（投给所有已注册窗口），非空 = 只投该窗口。
-    public var jsSink: (String, String) -> Unit = { _, _ => }
-    // 开发者工具通道：由 TauriApp 注入宿主实现
-    public var devToolsSink: () -> Unit = { => }
-    // 宿主能力位通道：由 TauriApp 注入（window label → CJ_CAP_* 位域），供 system:host 用。
-    // 为什么走注入而不是让 IpcHub 自己拿窗口注册表：注册表归 TauriApp（AppHost 契约），
-    // hub 只认「label → 位域」这一个函数——依赖方向保持 app → ipc_hub 单向。
-    public var hostCapabilitiesSink: (String) -> Int32 = { _ => 0 }
-    // 后端事件监听器（对标 Tauri 的 Rust 侧 Listener）：事件名 → 处理函数。
-    // 只在前端 emit 时被调用；后端自己 emit 给前端的事件**不**回流到这里（否则「后端广播 → 监听器再广播」会自激）。
-    private var eventListeners: HashMap<String, ArrayList<(JsonValue) -> Unit>> =
-        HashMap<String, ArrayList<(JsonValue) -> Unit>>()
-
-    public init() {}
-
-    public func setCapabilities(reg: CapabilityRegistry): Unit {
-        this.capabilities = reg
-    }
-
-    /**
-     * 打开开发者工具（宿主注入的实现；未注入时空操作）
-     */
-    public func openDevTools(): Unit {
-        this.devToolsSink()
-    }
-
-    /**
-     * 宿主能力位（宿主注入的实现；未注入 / 窗口未知时返回 0）
-     */
-    public func hostCapabilities(window: String): Int32 {
-        return this.hostCapabilitiesSink(window)
-    }
-
-    public func register(cmd: String, handler: CommandHandler): Unit {
-        this.commands.add(cmd, handler)
-    }
-
-    public func hasCommand(cmd: String): Bool {
-        return this.commands.contains(cmd)
-    }
-
-    /**
-     * 路径 scope 校验（RFC-003 第 4 期）：IpcContext.resolveScopedPath 的实现体。
-     *
-     * 校验只在**真的有插件来问**时发生——没有为它声明 scope 的插件完全不受影响（旧清单行为不变）。
-     * 拒绝时 stderr 留一行凭证（前缀统一好 grep），前端拿到的是可读的业务错误而不是宿主崩溃。
-     */
-    public func resolveScopedPath(plugin: String, rawPath: String): String {
-        let resolved = normalizeScopePath(rawPath)
-        match (this.capabilities.scopeForPlugin(plugin)) {
-            case Some(rule) =>
-                if (!scopeAllows(rule, resolved)) {
-                    eprintln("[cj-tauri] scope denied (${plugin}): ${rawPath} -> ${resolved}")
-                    throw CommandException("${plugin}: path is outside the authorized scope")
-                }
-            case None => ()
-        }
-        return resolved
-    }
-
-    /**
-     * 取某插件的 scope 规则**本体**（不给判定）：给「匹配语义不是文件路径」的插件用——
-     * 如 http 插件把 allow/deny 模式当**主机名**匹配（不能先走 normalizeScopePath 的
-     * 文件路径折叠，那会把 `api.example.com` 当成相对路径去拼接）。判定本身仍走共享层
-     * `scopeAllows`，插件不自己写第二份 glob。
-     */
-    public func scopeRuleFor(plugin: String): Option<ScopeRule> {
-        return this.capabilities.scopeForPlugin(plugin)
-    }
-
-    /**
-     * 注册后端事件监听器（对标 Tauri Rust 侧的 `app.listen(...)`）
-     *
-     * 调用时机：装配期（插件在自己的 setup() 里注册）。同一事件可注册多个监听器，按注册顺序调用；
-     * 暂时不提供注销（emit 分发是遍历快照式的短回调，注册期外再改表属于未定义用法）。
-     */
-    public func listenEvent(event: String, handler: (JsonValue) -> Unit): Unit {
-        if (!this.eventListeners.contains(event)) {
-            this.eventListeners.add(event, ArrayList<(JsonValue) -> Unit>())
-        }
-        this.eventListeners.get(event).getOrThrow().add(handler)
-    }
-
-    /**
-     * 处理来自前端的原始消息（JSON 字符串）：invoke 与 emit 两条路径
-     *
-     * 全链路：解析 → capability 校验（调用线程上同步完成）→ 执行（worker 线程）→ 结果/错误回投
-     */
-    public func handleRawMessage(raw: String): Unit {
-        if (let Some(req) <- InvokeRequest.parse(raw)) {
-            this.handleInvoke(req)
-            return
-        }
-        if (let Some(ev) <- EmitRequest.parse(raw)) {
-            this.handleEmit(ev)
-            return
-        }
-        // 两条解析都不认：只要报文里读得出 id 就回一条 reject——前端那条 promise 否则会永久 pending，
-        // 比一条明确的报错难排查得多（前端 invoke 没有超时参数）。
-        eprintln("[cj-tauri] invalid IPC message: ${raw}")
-        if (let Some(id) <- IpcMessage.peekId(raw)) {
-            // 报文非法时读不出窗口，只能广播一份：id 只会挂在某一个页面的 pending 上，
-            // 别的窗口的 _dispatch 找不到它、忽略即可——这样发起方那条 promise 才不会永久 pending。
-            this.reject(id, "invalid IPC message", "")
-        }
-    }
-
-    /**
-     * 校验与执行分两段，这是当前的线程模型（改之前想清楚，见 RFC-001 §8 第 8 条）：
-     *   1/2. 「未授权」「未注册」在**调用线程上同步**拒绝——前端拿到的报错要即时、顺序确定，
-     *        也免得为一条注定失败的请求白开一个线程；
-     *   3.   真正执行挪到 worker 线程（spawn）。此前 handler 直接在宿主 UI 线程上跑完，
-     *        慢命令（`shell:exec` 跑一个进程、等原生对话框）会把窗口钉住——不重绘、不响应事件。
-     * 结果经 jsSink 回投即可：两平台桥的 runJs 都是「加锁入队 + 投递到宿主 UI 线程」
-     * （bridge_linux.c 的 g_idle_add → flush_pending_js，bridge_win.c 的 PostMessageW(WM_CJT_FLUSH) → flush_js），
-     * 从任意线程调用都安全。也正因如此，worker 里**不要**绕过桥直接调 GTK / WebKit：
-     * 仓颉轻量线程的堆上协程栈会被 JSC 的栈边界校验 abort（AGENTS.md §4）。
-     * 同一命令被并发调用**不保证执行顺序**（前端按 promise id 匹配，不会串包）。
-     */
-    private func handleInvoke(req: InvokeRequest): Unit {
-        // 1. 能力校验（默认最小权限）
-        if (!this.capabilities.canInvoke(req.cmd)) {
-            this.reject(req.id, "command not allowed: ${req.cmd}", req.window)
-            return
-        }
-        // 2. 命令是否存在
-        if (!this.commands.contains(req.cmd)) {
-            this.reject(req.id, "command not registered: ${req.cmd}", req.window)
-            return
-        }
-        // 3. 交给 worker 线程执行：调用线程立刻返回，UI 不被命令阻塞
-        let _ = spawn { => this.runCommand(req) }
-    }
-
-    /** worker 线程上的实际执行：跑完（或抛错）就把 resolve / reject 回投给前端 */
-    private func runCommand(req: InvokeRequest): Unit {
-        try {
-            let handler = this.commands.get(req.cmd).getOrThrow()
-            let ctx = IpcContext(req.window, this)
-            let result = handler.handle(req.cmd, req.args, ctx)
-            this.jsSink(IpcMessage.resolve(req.id, result), req.window)
-        } catch (e: CommandException) {
-            // 应用级拒绝（作者主动抛的业务失败）也要留痕：前端可能压根没接 catch，
-            // 只回 reject 的话「这条命令失败了」在页面之外毫无线索——事件监听器路早有同款日志。
-            // 与下面的非预期失败分开措辞，便于 `grep command rejected` / `grep command failed` 分流。
-            eprintln("[cj-tauri] command rejected (${req.cmd}): ${e.message}")
-            this.reject(req.id, e.message, req.window)
-        } catch (e: Exception) {
-            eprintln("[cj-tauri] command failed (${req.cmd}): ${e}")
-            this.reject(req.id, "command failed: ${e}", req.window)
-        }
-    }
-
-    /**
-     * 回一条 reject；window 是回投目标（空串 = 广播，只用在读不出窗口的非法报文路径）
-     */
-    private func reject(id: Int64, error: String, window: String): Unit {
-        this.jsSink(IpcMessage.reject(id, error), window)
-    }
-
-    /**
-     * 前端 emit 事件：校验（同步，调用线程）→ 投给后端监听器（worker 线程）→ resolve。
-     *
-     * 为什么校验同步、投递异步：与命令同一套理由——未授权要在调用线程上立刻拒（报错即时、顺序确定），
-     * 而回调可能慢，不能钉住宿主 UI 线程。
-     * 「没有监听器」不是错误：事件是广播语义，没人听很正常（Tauri 同样不报），照常 resolve。
-     * 与 Tauri 的差异（不广播回页面）见 EmitRequest 的文档注释。
-     */
-    private func handleEmit(req: EmitRequest): Unit {
-        if (!this.capabilities.canEmit(req.event)) {
-            eprintln("[cj-tauri] event not allowed: ${req.event}")
-            this.reject(req.id, "event not allowed: ${req.event}", req.window)
-            return
-        }
-        let _ = spawn { => this.dispatchEvent(req) }
-    }
-
-    /** worker 线程上把事件投给监听器，然后 resolve 发送方 */
-    private func dispatchEvent(req: EmitRequest): Unit {
-        match (this.eventListeners.get(req.event)) {
-            case Some(handlers) =>
-                for (h in handlers) {
-                    // 单个监听器抛错只记 stderr：事件是广播，一个听众崩了不该牵连别的听众和发送方
-                    try {
-                        h(req.payload)
-                    } catch (e: Exception) {
-                        eprintln("[cj-tauri] event listener failed (${req.event}): ${e}")
-                    }
-                }
-            case None => ()
-        }
-        this.jsSink(IpcMessage.resolve(req.id, JsonObject()), req.window)
-    }
-
-    /**
-     * 广播事件到所有窗口（对标 Tauri 的 `emit`）：报文不带 window 字段，各窗口的桥自行放行。
-     * 批次 2 起投递侧按 label 派发，空串即「已注册的每个窗口各投一份」。
-     */
-    public func emitAll(event: String, payload: JsonValue): Unit {
-        this.emitToWindow(event, payload, "")
-    }
-
-    /**
-     * 推送「只保最新」的事件到指定窗口（经 capability 校验，与 `emitToWindow` 同一套白名单）
-     *
-     * 与 `emitToWindow` 只差页面侧的合并语义（报文多 `coalesce: true`）：同一帧内同名事件只投
-     * 最后一次 payload。**默认不合并**——静默丢数据比慢更难排查，要不要这条路必须调用方显式选
-     * （Tauri v2 核心同样不做合并，对照见 docs/IPC-通信机制.md §6 第 5 项）。
-     *
-     * @param window 接收窗口的 label；空串 = 广播（语义同 `emitToWindow`）
-     */
-    public func emitLatest(event: String, payload: JsonValue, window: String): Unit {
-        if (!this.capabilities.canEmit(event)) {
-            eprintln("[cj-tauri] event not allowed: ${event}")
-            return
-        }
-        this.jsSink(IpcMessage.eventLatest(event, payload, window), window)
-    }
-
-    /**
-     * 推送事件到指定窗口（经 capability 校验）
-     *
-     * @param window 接收窗口的 label；空串 = 广播。此前这个参数被丢掉（报文里也无 window 字段），
-     *               定向推送实际退化成广播——协议补上字段后，多窗口的过滤由各页面的桥完成。
-     */
-    public func emitToWindow(event: String, payload: JsonValue, window: String): Unit {
-        if (!this.capabilities.canEmit(event)) {
-            eprintln("[cj-tauri] event not allowed: ${event}")
-            return
-        }
-        this.jsSink(IpcMessage.event(event, payload, window), window)
-    }
-}
+package cjTauri
+
+import std.collection.*
+import stdx.encoding.json.*
+
+/**
+ * 命令处理器接口（对标 Tauri command）
+ * 实现方注册到 IpcHub，前端 invoke 时经 capability 校验后调用。
+ */
+public interface CommandHandler {
+    /**
+     * 处理命令并返回结果 JSON 值。
+     * @param cmd   命令名
+     * @param args  前端传入的参数对象
+     * @param ipc   IPC 上下文（可发事件、取窗口信息）
+     * @return 成功返回值；如需失败可在实现中抛 CommandException
+     */
+    func handle(cmd: String, args: JsonObject, ipc: IpcContext): JsonValue
+}
+
+/**
+ * 命令执行异常：message 将作为 error 返回给前端
+ */
+public class CommandException <: Exception {
+    public init(msg: String) {
+        super(msg)
+    }
+}
+
+/**
+ * IPC 上下文：命令执行时可访问
+ */
+public class IpcContext {
+    public let window: String
+    private let hub: IpcHub
+
+    public init(window: String, hub: IpcHub) {
+        this.window = window
+        this.hub = hub
+    }
+
+    /**
+     * 向当前窗口推送事件
+     */
+    public func emit(event: String, payload: JsonValue): Unit {
+        this.hub.emitToWindow(event, payload, this.window)
+    }
+
+    /**
+     * 向当前窗口推送「只保最新」的事件：同一帧内同名事件只投最后一次 payload，中间值丢弃
+     *
+     * 高频进度类事件用；需要每条都到达的继续用 `emit`。选型理由见 docs/IPC-通信机制.md §6 第 5 项。
+     */
+    public func emitLatest(event: String, payload: JsonValue): Unit {
+        this.hub.emitLatest(event, payload, this.window)
+    }
+
+    /**
+     * 打开开发者工具（宿主实现），供内置 system:devtools 与应用自定义命令使用
+     */
+    public func openDevTools(): Unit {
+        this.hub.openDevTools()
+    }
+
+    /**
+     * 本窗口的宿主能力位（`CJ_CAP_*` 按位或），供内置 system:host 使用
+     *
+     * 取的是**发起命令那个窗口**的位域：能力位是宿主级事实，多窗口下可能不同（如 Linux 托盘
+     * 取决于桥怎么编的）。窗口没登记 / 宿主还没建句柄时返回 0——后者不代表「平台没这本事」，
+     * 所以页面自检应在窗口起来之后做（与 examples/menu 探针的口径一致）。
+     */
+    public func hostCapabilities(): Int32 {
+        return this.hub.hostCapabilities(this.window)
+    }
+
+    /**
+     * 解析并校验一个路径参数（RFC-003 第 4 期）。
+     *
+     * 带路径参数的插件**一律**用它取代自己拼路径：清单里为插件写了 scope 就按
+     * allow/deny 判定，越界抛业务错误；没写就维持旧行为（全量放行，启动时有提示）。
+     * 返回值是规范化后的路径（绝对、已解析软链接），直接交给 std.fs 用即可。
+     */
+    public func resolveScopedPath(plugin: String, rawPath: String): String {
+        return this.hub.resolveScopedPath(plugin, rawPath)
+    }
+
+    /**
+     * 取某插件的 scope 规则**本体**（不给判定）：给「匹配语义不是文件路径」的插件用——
+     * 如 http 插件把 allow/deny 模式当**主机名**匹配（不能先走 normalizeScopePath 的
+     * 文件路径折叠）。判定本身仍走共享层 `scopeAllows`，插件不自己写第二份 glob。
+     */
+    public func scopeRuleFor(plugin: String): Option<ScopeRule> {
+        return this.hub.scopeRuleFor(plugin)
+    }
+}
+
+/**
+ * IPC 中心：命令注册、能力校验、消息分发、事件推送
+ */
+public class IpcHub {
+    private var commands: HashMap<String, CommandHandler> = HashMap<String, CommandHandler>()
+    private var capabilities: CapabilityRegistry = CapabilityRegistry()
+    // 事件 / 回执投递通道：由宿主层注入（把 JSON 字符串投递给前端 JS）。
+    // 第二个参数是**目标窗口 label**：批次 2 起由 TauriApp 按窗口注册表派发，
+    // 空串 = 广播（投给所有已注册窗口），非空 = 只投该窗口。
+    public var jsSink: (String, String) -> Unit = { _, _ => }
+    // 开发者工具通道：由 TauriApp 注入宿主实现
+    public var devToolsSink: () -> Unit = { => }
+    // 宿主能力位通道：由 TauriApp 注入（window label → CJ_CAP_* 位域），供 system:host 用。
+    // 为什么走注入而不是让 IpcHub 自己拿窗口注册表：注册表归 TauriApp（AppHost 契约），
+    // hub 只认「label → 位域」这一个函数——依赖方向保持 app → ipc_hub 单向。
+    public var hostCapabilitiesSink: (String) -> Int32 = { _ => 0 }
+    // 后端事件监听器（对标 Tauri 的 Rust 侧 Listener）：事件名 → 处理函数。
+    // 只在前端 emit 时被调用；后端自己 emit 给前端的事件**不**回流到这里（否则「后端广播 → 监听器再广播」会自激）。
+    private var eventListeners: HashMap<String, ArrayList<(JsonValue) -> Unit>> =
+        HashMap<String, ArrayList<(JsonValue) -> Unit>>()
+
+    public init() {}
+
+    public func setCapabilities(reg: CapabilityRegistry): Unit {
+        this.capabilities = reg
+    }
+
+    /**
+     * 打开开发者工具（宿主注入的实现；未注入时空操作）
+     */
+    public func openDevTools(): Unit {
+        this.devToolsSink()
+    }
+
+    /**
+     * 宿主能力位（宿主注入的实现；未注入 / 窗口未知时返回 0）
+     */
+    public func hostCapabilities(window: String): Int32 {
+        return this.hostCapabilitiesSink(window)
+    }
+
+    public func register(cmd: String, handler: CommandHandler): Unit {
+        this.commands.add(cmd, handler)
+    }
+
+    public func hasCommand(cmd: String): Bool {
+        return this.commands.contains(cmd)
+    }
+
+    /**
+     * 路径 scope 校验（RFC-003 第 4 期）：IpcContext.resolveScopedPath 的实现体。
+     *
+     * 校验只在**真的有插件来问**时发生——没有为它声明 scope 的插件完全不受影响（旧清单行为不变）。
+     * 拒绝时 stderr 留一行凭证（前缀统一好 grep），前端拿到的是可读的业务错误而不是宿主崩溃。
+     */
+    public func resolveScopedPath(plugin: String, rawPath: String): String {
+        let resolved = normalizeScopePath(rawPath)
+        match (this.capabilities.scopeForPlugin(plugin)) {
+            case Some(rule) =>
+                if (!scopeAllows(rule, resolved)) {
+                    eprintln("[cj-tauri] scope denied (${plugin}): ${rawPath} -> ${resolved}")
+                    throw CommandException("${plugin}: path is outside the authorized scope")
+                }
+            case None => ()
+        }
+        return resolved
+    }
+
+    /**
+     * 取某插件的 scope 规则**本体**（不给判定）：给「匹配语义不是文件路径」的插件用——
+     * 如 http 插件把 allow/deny 模式当**主机名**匹配（不能先走 normalizeScopePath 的
+     * 文件路径折叠，那会把 `api.example.com` 当成相对路径去拼接）。判定本身仍走共享层
+     * `scopeAllows`，插件不自己写第二份 glob。
+     */
+    public func scopeRuleFor(plugin: String): Option<ScopeRule> {
+        return this.capabilities.scopeForPlugin(plugin)
+    }
+
+    /**
+     * 注册后端事件监听器（对标 Tauri Rust 侧的 `app.listen(...)`）
+     *
+     * 调用时机：装配期（插件在自己的 setup() 里注册）。同一事件可注册多个监听器，按注册顺序调用；
+     * 暂时不提供注销（emit 分发是遍历快照式的短回调，注册期外再改表属于未定义用法）。
+     */
+    public func listenEvent(event: String, handler: (JsonValue) -> Unit): Unit {
+        if (!this.eventListeners.contains(event)) {
+            this.eventListeners.add(event, ArrayList<(JsonValue) -> Unit>())
+        }
+        this.eventListeners.get(event).getOrThrow().add(handler)
+    }
+
+    /**
+     * 处理来自前端的原始消息（JSON 字符串）：invoke 与 emit 两条路径
+     *
+     * 全链路：解析 → capability 校验（调用线程上同步完成）→ 执行（worker 线程）→ 结果/错误回投
+     */
+    public func handleRawMessage(raw: String): Unit {
+        if (let Some(req) <- InvokeRequest.parse(raw)) {
+            this.handleInvoke(req)
+            return
+        }
+        if (let Some(ev) <- EmitRequest.parse(raw)) {
+            this.handleEmit(ev)
+            return
+        }
+        // 两条解析都不认：只要报文里读得出 id 就回一条 reject——前端那条 promise 否则会永久 pending，
+        // 比一条明确的报错难排查得多（前端 invoke 没有超时参数）。
+        eprintln("[cj-tauri] invalid IPC message: ${raw}")
+        if (let Some(id) <- IpcMessage.peekId(raw)) {
+            // 报文非法时读不出窗口，只能广播一份：id 只会挂在某一个页面的 pending 上，
+            // 别的窗口的 _dispatch 找不到它、忽略即可——这样发起方那条 promise 才不会永久 pending。
+            this.reject(id, "invalid IPC message", "")
+        }
+    }
+
+    /**
+     * 校验与执行分两段，这是当前的线程模型（改之前想清楚，见 RFC-001 §8 第 8 条）：
+     *   1/2. 「未授权」「未注册」在**调用线程上同步**拒绝——前端拿到的报错要即时、顺序确定，
+     *        也免得为一条注定失败的请求白开一个线程；
+     *   3.   真正执行挪到 worker 线程（spawn）。此前 handler 直接在宿主 UI 线程上跑完，
+     *        慢命令（`shell:exec` 跑一个进程、等原生对话框）会把窗口钉住——不重绘、不响应事件。
+     * 结果经 jsSink 回投即可：两平台桥的 runJs 都是「加锁入队 + 投递到宿主 UI 线程」
+     * （bridge_linux.c 的 g_idle_add → flush_pending_js，bridge_win.c 的 PostMessageW(WM_CJT_FLUSH) → flush_js），
+     * 从任意线程调用都安全。也正因如此，worker 里**不要**绕过桥直接调 GTK / WebKit：
+     * 仓颉轻量线程的堆上协程栈会被 JSC 的栈边界校验 abort（AGENTS.md §4）。
+     * 同一命令被并发调用**不保证执行顺序**（前端按 promise id 匹配，不会串包）。
+     */
+    private func handleInvoke(req: InvokeRequest): Unit {
+        // 1. 能力校验（默认最小权限）
+        if (!this.capabilities.canInvoke(req.cmd)) {
+            this.reject(req.id, "command not allowed: ${req.cmd}", req.window)
+            return
+        }
+        // 2. 命令是否存在
+        if (!this.commands.contains(req.cmd)) {
+            this.reject(req.id, "command not registered: ${req.cmd}", req.window)
+            return
+        }
+        // 3. 交给 worker 线程执行：调用线程立刻返回，UI 不被命令阻塞
+        let _ = spawn { => this.runCommand(req) }
+    }
+
+    /** worker 线程上的实际执行：跑完（或抛错）就把 resolve / reject 回投给前端 */
+    private func runCommand(req: InvokeRequest): Unit {
+        try {
+            let handler = this.commands.get(req.cmd).getOrThrow()
+            let ctx = IpcContext(req.window, this)
+            let result = handler.handle(req.cmd, req.args, ctx)
+            this.jsSink(IpcMessage.resolve(req.id, result), req.window)
+        } catch (e: CommandException) {
+            // 应用级拒绝（作者主动抛的业务失败）也要留痕：前端可能压根没接 catch，
+            // 只回 reject 的话「这条命令失败了」在页面之外毫无线索——事件监听器路早有同款日志。
+            // 与下面的非预期失败分开措辞，便于 `grep command rejected` / `grep command failed` 分流。
+            eprintln("[cj-tauri] command rejected (${req.cmd}): ${e.message}")
+            this.reject(req.id, e.message, req.window)
+        } catch (e: Exception) {
+            eprintln("[cj-tauri] command failed (${req.cmd}): ${e}")
+            this.reject(req.id, "command failed: ${e}", req.window)
+        }
+    }
+
+    /**
+     * 回一条 reject；window 是回投目标（空串 = 广播，只用在读不出窗口的非法报文路径）
+     */
+    private func reject(id: Int64, error: String, window: String): Unit {
+        this.jsSink(IpcMessage.reject(id, error), window)
+    }
+
+    /**
+     * 前端 emit 事件：校验（同步，调用线程）→ 投给后端监听器（worker 线程）→ resolve。
+     *
+     * 为什么校验同步、投递异步：与命令同一套理由——未授权要在调用线程上立刻拒（报错即时、顺序确定），
+     * 而回调可能慢，不能钉住宿主 UI 线程。
+     * 「没有监听器」不是错误：事件是广播语义，没人听很正常（Tauri 同样不报），照常 resolve。
+     * 与 Tauri 的差异（不广播回页面）见 EmitRequest 的文档注释。
+     */
+    private func handleEmit(req: EmitRequest): Unit {
+        if (!this.capabilities.canEmit(req.event)) {
+            eprintln("[cj-tauri] event not allowed: ${req.event}")
+            this.reject(req.id, "event not allowed: ${req.event}", req.window)
+            return
+        }
+        let _ = spawn { => this.dispatchEvent(req) }
+    }
+
+    /** worker 线程上把事件投给监听器，然后 resolve 发送方 */
+    private func dispatchEvent(req: EmitRequest): Unit {
+        match (this.eventListeners.get(req.event)) {
+            case Some(handlers) =>
+                for (h in handlers) {
+                    // 单个监听器抛错只记 stderr：事件是广播，一个听众崩了不该牵连别的听众和发送方
+                    try {
+                        h(req.payload)
+                    } catch (e: Exception) {
+                        eprintln("[cj-tauri] event listener failed (${req.event}): ${e}")
+                    }
+                }
+            case None => ()
+        }
+        this.jsSink(IpcMessage.resolve(req.id, JsonObject()), req.window)
+    }
+
+    /**
+     * 广播事件到所有窗口（对标 Tauri 的 `emit`）：报文不带 window 字段，各窗口的桥自行放行。
+     * 批次 2 起投递侧按 label 派发，空串即「已注册的每个窗口各投一份」。
+     */
+    public func emitAll(event: String, payload: JsonValue): Unit {
+        this.emitToWindow(event, payload, "")
+    }
+
+    /**
+     * 推送「只保最新」的事件到指定窗口（经 capability 校验，与 `emitToWindow` 同一套白名单）
+     *
+     * 与 `emitToWindow` 只差页面侧的合并语义（报文多 `coalesce: true`）：同一帧内同名事件只投
+     * 最后一次 payload。**默认不合并**——静默丢数据比慢更难排查，要不要这条路必须调用方显式选
+     * （Tauri v2 核心同样不做合并，对照见 docs/IPC-通信机制.md §6 第 5 项）。
+     *
+     * @param window 接收窗口的 label；空串 = 广播（语义同 `emitToWindow`）
+     */
+    public func emitLatest(event: String, payload: JsonValue, window: String): Unit {
+        if (!this.capabilities.canEmit(event)) {
+            eprintln("[cj-tauri] event not allowed: ${event}")
+            return
+        }
+        this.jsSink(IpcMessage.eventLatest(event, payload, window), window)
+    }
+
+    /**
+     * 推送事件到指定窗口（经 capability 校验）
+     *
+     * @param window 接收窗口的 label；空串 = 广播。此前这个参数被丢掉（报文里也无 window 字段），
+     *               定向推送实际退化成广播——协议补上字段后，多窗口的过滤由各页面的桥完成。
+     */
+    public func emitToWindow(event: String, payload: JsonValue, window: String): Unit {
+        if (!this.capabilities.canEmit(event)) {
+            eprintln("[cj-tauri] event not allowed: ${event}")
+            return
+        }
+        this.jsSink(IpcMessage.event(event, payload, window), window)
+    }
+}