cj-tauri 2.0.0 → 2.1.0

package/cli/templates/ohos-skeleton/entry/cjpm.toml

@@ -1,43 +1,51 @@
-[package]
-  cjc-version = "1.1.3"
-  compile-option = "--dy-std --cfg=\"${COMPILE_CONDITION_ENTRY}\""
-  description = "{{PROJECT_NAME}} - cj-tauri 鸿蒙入 module"
-  name = "ohos_app_cangjie_entry"
-  output-type = "dynamic"
-  src-dir = "./src/main/cangjie"
-  target-dir = ""
-  version = "1.0.0"
-
-[dependencies]
-  # 源码依赖：hvigor 的 CompileCangjie 会把框架各包按本模块（dynamic）需要的形态编进来。
-  # 路径由 `cj-tauri create --template ohos` 写成**本机绝对路径**；换机器 / 挪仓库后重跑一次
-  # create，或手改这一行（与桌面模板同一条规矩）。
-  cjTauri = { path = "{{FRAMEWORK_ROOT_TOML}}" }
-
-[profile]
-  [profile.build]
-    incremental = true
-    lto = ""
-  [profile.customized-option]
-    debug = "-g -Woff all -Won apilevel-check"
-    release = "--fast-math -O2 -s -Woff all -Won apilevel-check"
-  [profile.test]
-
-[target.aarch64-linux-ohos]
-  compile-option = "-B \"${DEVECO_CANGJIE_HOME}/build-tools/third_party/llvm/bin\" -B \"${DEVECO_OH_NATIVE_HOME}/sysroot/usr/lib/aarch64-linux-ohos\" -L \"${DEVECO_OH_NATIVE_HOME}/sysroot/usr/lib/aarch64-linux-ohos\" -L \"${DEVECO_OH_NATIVE_HOME}/llvm/lib/clang/15.0.4/lib/aarch64-linux-ohos\" -L \"${DEVECO_OH_NATIVE_HOME}/llvm/lib/aarch64-linux-ohos\" --sysroot \"${DEVECO_OH_NATIVE_HOME}/sysroot\""
-[target.aarch64-linux-ohos.bin-dependencies]
-  # 鸿蒙版 stdx：这里写**相对路径**，指向工程根上的 `stdx` 联接（build-hap.sh 用
-  # CANGJIE_STDX_OHOS 建，不入库）。两条实测依据：
-  # ① hvigor 只替换它自己的模板变量（${AARCH64_LIBS} 这组），写别的 ${...} 会变成空串，
-  #    而空串会让**整条 path-option 一起失效**，报错却是
-  #    「imports package 'stdx.encoding.json' ... not added as a dependency」，看着像漏配；
-  # ② 本机绝对路径能编过，但换机器就得改文件，而 DevEco 里点 Build 不经过脚本——
-  #    相对路径两处都通用。
-  path-option = ["${AARCH64_LIBS}", "${AARCH64_MACRO_LIBS}", "${AARCH64_KIT_LIBS}", "../stdx"]
-  package-option = {}
-
-[target.x86_64-linux-ohos]
-  compile-option = "-B \"${DEVECO_CANGJIE_HOME}/build-tools/third_party/llvm/bin\" -B \"${DEVECO_OH_NATIVE_HOME}/sysroot/usr/lib/x86_64-linux-ohos\" -L \"${DEVECO_OH_NATIVE_HOME}/sysroot/usr/lib/x86_64-linux-ohos\" -L \"${DEVECO_OH_NATIVE_HOME}/llvm/lib/clang/15.0.4/lib/x86_64-linux-ohos\" -L \"${DEVECO_OH_NATIVE_HOME}/llvm/lib/x86_64-linux-ohos\" --sysroot \"${DEVECO_OH_NATIVE_HOME}/sysroot\""
-[target.x86_64-linux-ohos.bin-dependencies]
-  path-option = ["${X86_64_OHOS_LIBS}", "${X86_64_OHOS_MACRO_LIBS}", "${X86_64_OHOS_KIT_LIBS}", "../stdx"]
-  package-option = {}
+[package]
+  cjc-version = "1.1.3"
+  compile-option = "--dy-std --cfg=\"${COMPILE_CONDITION_ENTRY}\""
+  description = "{{PROJECT_NAME}} - cj-tauri 鸿蒙入 module"
+  name = "ohos_app_cangjie_entry"
+  output-type = "dynamic"
+  src-dir = "./src/main/cangjie"
+  target-dir = ""
+  version = "1.0.0"
+
+[dependencies]
+  # 源码依赖：hvigor 的 CompileCangjie 会把框架各包按本模块（dynamic）需要的形态编进来。
+  # 路径由 `cj-tauri create --template ohos` 写成**本机绝对路径**；换机器 / 挪仓库后重跑一次
+  # create，或手改这一行（与桌面模板同一条规矩）。
+  cjTauri = { path = "{{FRAMEWORK_ROOT_TOML}}" }
+
+[profile]
+  [profile.build]
+    incremental = true
+    lto = ""
+  [profile.customized-option]
+    debug = "-g -Woff all -Won apilevel-check"
+    release = "--fast-math -O2 -s -Woff all -Won apilevel-check"
+  [profile.test]
+
+[target.aarch64-linux-ohos]
+  compile-option = "-B \"${DEVECO_CANGJIE_HOME}/build-tools/third_party/llvm/bin\" -B \"${DEVECO_OH_NATIVE_HOME}/sysroot/usr/lib/aarch64-linux-ohos\" -L \"${DEVECO_OH_NATIVE_HOME}/sysroot/usr/lib/aarch64-linux-ohos\" -L \"${DEVECO_OH_NATIVE_HOME}/llvm/lib/clang/15.0.4/lib/aarch64-linux-ohos\" -L \"${DEVECO_OH_NATIVE_HOME}/llvm/lib/aarch64-linux-ohos\" --sysroot \"${DEVECO_OH_NATIVE_HOME}/sysroot\""
+  # -lpasteboard -ludmf：框架的剪贴板宿主能力（`src/clipboard_bridge.cj` 鸿蒙段）用原生
+  # `OH_Pasteboard_*` / `OH_Udmf*` / `OH_UdsPlainText_*` C API。两组符号分属两个库
+  # （`OH_Pasteboard_*` 在 libpasteboard、其余在 libudmf），所以两个都要给。
+  # 最终链接发生在**本模块**（output-type = dynamic），所以开关必须在这儿落地——
+  # 只写在框架自己的 cjpm.toml 里不生效，缺了模块里就留一堆 `U OH_Pasteboard_*`，
+  # 表现是应用启动即 SIGSEGV（模块加载期解析不到符号）。
+  # 库在同 sysroot 的 `usr/lib/aarch64-linux-ohos`，上面 compile-option 的 `-L` 已指着它。
+  link-option = "-lpasteboard -ludmf"
+[target.aarch64-linux-ohos.bin-dependencies]
+  # 鸿蒙版 stdx：这里写**相对路径**，指向工程根上的 `stdx` 联接（build-hap.sh 用
+  # CANGJIE_STDX_OHOS 建，不入库）。两条实测依据：
+  # ① hvigor 只替换它自己的模板变量（${AARCH64_LIBS} 这组），写别的 ${...} 会变成空串，
+  #    而空串会让**整条 path-option 一起失效**，报错却是
+  #    「imports package 'stdx.encoding.json' ... not added as a dependency」，看着像漏配；
+  # ② 本机绝对路径能编过，但换机器就得改文件，而 DevEco 里点 Build 不经过脚本——
+  #    相对路径两处都通用。
+  path-option = ["${AARCH64_LIBS}", "${AARCH64_MACRO_LIBS}", "${AARCH64_KIT_LIBS}", "../stdx"]
+  package-option = {}
+
+[target.x86_64-linux-ohos]
+  compile-option = "-B \"${DEVECO_CANGJIE_HOME}/build-tools/third_party/llvm/bin\" -B \"${DEVECO_OH_NATIVE_HOME}/sysroot/usr/lib/x86_64-linux-ohos\" -L \"${DEVECO_OH_NATIVE_HOME}/sysroot/usr/lib/x86_64-linux-ohos\" -L \"${DEVECO_OH_NATIVE_HOME}/llvm/lib/clang/15.0.4/lib/x86_64-linux-ohos\" -L \"${DEVECO_OH_NATIVE_HOME}/llvm/lib/x86_64-linux-ohos\" --sysroot \"${DEVECO_OH_NATIVE_HOME}/sysroot\""
+[target.x86_64-linux-ohos.bin-dependencies]
+  path-option = ["${X86_64_OHOS_LIBS}", "${X86_64_OHOS_MACRO_LIBS}", "${X86_64_OHOS_KIT_LIBS}", "../stdx"]
+  package-option = {}

package/cli/templates/ohos-skeleton/entry/hvigorfile.ts

@@ -1,6 +1,6 @@
-import { hapTasks } from '@ohos/hvigor-ohos-plugin';
-
-export default {
-  system: hapTasks, /* Built-in plugin of Hvigor. It cannot be modified. */
-  plugins: []       /* Custom plugin to extend the functionality of Hvigor. */
-}
+import { hapTasks } from '@ohos/hvigor-ohos-plugin';
+
+export default {
+  system: hapTasks, /* Built-in plugin of Hvigor. It cannot be modified. */
+  plugins: []       /* Custom plugin to extend the functionality of Hvigor. */
+}

package/cli/templates/ohos-skeleton/entry/oh-package.json5

@@ -1,9 +1,9 @@
-{
-  "name": "entry",
-  "version": "1.0.0",
-  "description": "{{PROJECT_NAME}} - entry 模块",
-  "main": "",
-  "author": "",
-  "license": "",
-  "dependencies": {}
-}
+{
+  "name": "entry",
+  "version": "1.0.0",
+  "description": "{{PROJECT_NAME}} - entry 模块",
+  "main": "",
+  "author": "",
+  "license": "",
+  "dependencies": {}
+}

package/cli/templates/ohos-skeleton/entry/src/main/cangjie/ability_stage.cj

@@ -1,17 +1,17 @@
-package ohos_app_cangjie_entry
-
-import kit.AbilityKit.AbilityStage
-import kit.PerformanceAnalysisKit.Hilog
-
-/*
- * AbilityStage：模块级入口（module.json5 的 srcEntry 指向它）
- *
- * 只打一行 hilog。鸿蒙侧排查的第一句话是「AbilityStage 有没有被创建」——
- * 应用启动即崩（比如框架包初始化链坏了）时，hilog 里连这一行都没有，
- * 而 CANGJIE-RUNTIME 的行照常在，很容易被误读成「生命周期卡死」。
- */
-class MyAbilityStage <: AbilityStage {
-    public override func onCreate(): Unit {
-        Hilog.info(1, "CjTauri", "MyAbilityStage onCreated.")
-    }
-}
+package ohos_app_cangjie_entry
+
+import kit.AbilityKit.AbilityStage
+import kit.PerformanceAnalysisKit.Hilog
+
+/*
+ * AbilityStage：模块级入口（module.json5 的 srcEntry 指向它）
+ *
+ * 只打一行 hilog。鸿蒙侧排查的第一句话是「AbilityStage 有没有被创建」——
+ * 应用启动即崩（比如框架包初始化链坏了）时，hilog 里连这一行都没有，
+ * 而 CANGJIE-RUNTIME 的行照常在，很容易被误读成「生命周期卡死」。
+ */
+class MyAbilityStage <: AbilityStage {
+    public override func onCreate(): Unit {
+        Hilog.info(1, "CjTauri", "MyAbilityStage onCreated.")
+    }
+}

package/cli/templates/ohos-skeleton/entry/src/main/cangjie/app_host.cj

@@ -1,94 +1,94 @@
-package ohos_app_cangjie_entry
-
-import cjTauri.*
-import stdx.encoding.json.*
-import kit.PerformanceAnalysisKit.Hilog
-
-/*
- * {{PROJECT_NAME}} 的框架装配（鸿蒙侧）
- *
- * 桌面的 `main()` 在鸿蒙上不成立——鸿蒙应用没有「自己起进程跑一个 main」这回事，
- * 窗口属于 ArkUI、页面由 ArkWeb 组件承载。所以装配被拆成三段：
- *   ① `MainAbility.onCreate`：定沙箱目录（`run(html)` 要把页面落到沙箱再 file:// 加载）
- *   ② `MainAbility.onCreate` 里 `spawn { startTauriApp(...) }`：**必须非 UI 线程**，
- *      `run()` 会阻塞到 quit()，而 UI 线程要留给 ArkUI 建树
- *   ③ `onWindowStageCreate`：等宿主登记 → `loadContent` → 组件里建 `Web`
- *
- * 页面与能力清单的来路：都来自 hap 的 `resources/rawfile/`，由 Ability 读成字符串传进来
- * （设备上没有 `ui/` 与 `capabilities/` 目录，这两份是构建期打进 hap 的）。
- */
-
-/** greet 命令（对标 tauri command）：前端 `tauri.invoke("greet", { name: "..." })` */
-public class GreetCommand <: CommandHandler {
-    public init() {}
-
-    public func handle(cmd: String, args: JsonObject, ipc: IpcContext): JsonValue {
-        var name = "world"
-        if (let Some(n) <- args.get("name")) {
-            match (n.kind()) {
-                case JsonKind.JsString => name = n.asString().getValue()
-                case _ => ()
-            }
-        }
-        return JsonString("Hello, ${name}! 来自仓颉后端（鸿蒙 ArkWeb 宿主）")
-    }
-}
-
-/**
- * 定时器命令：起一个后台线程，每秒向后端推一个 tick 事件（验证 仓颉 → JS 通道）
- *
- * 鸿蒙侧的 `emit` 同样只入队，真正的投递在 `onProxyPost` 里由页面心跳带出去——
- * 所以页面必须一直在跑（`setInterval` 的心跳由框架的桥脚本负责，业务代码不用管）。
- */
-public class TimerCommand <: CommandHandler {
-    private var counter: Int64 = 0
-    private var started: Bool = false
-
-    public init() {}
-
-    public func handle(cmd: String, args: JsonObject, ipc: IpcContext): JsonValue {
-        if (!this.started) {
-            this.started = true
-            spawn {
-                while (true) {
-                    sleep(Duration.second)
-                    this.counter += 1
-                    var payload = JsonObject()
-                    payload.put("n", JsonInt(this.counter))
-                    ipc.emit("tick", payload)
-                }
-            }
-        }
-        return JsonString("timer started")
-    }
-}
-
-/**
- * 装配并运行框架应用（**必须在非 UI 线程调用**：`run()` 阻塞到 `quit()`）
- *
- * @param windowTitle 窗口标题（ArkUI 侧不起作用，留着与桌面版对齐）
- * @param pageHtml 页面原文（rawfile/index.html）
- * @param capsJson 能力清单原文（rawfile/capabilities.json）；空串表示不挂清单
- */
-public func startTauriApp(windowTitle: String, pageHtml: String, capsJson: String): Unit {
-    Hilog.info(1, "CjTauri", "startTauriApp begin page=${pageHtml.size}B caps=${capsJson.size}B")
-
-    let app = TauriApp()
-        .window(WindowConfig(windowTitle, 1280, 820))
-        .register("greet", GreetCommand())
-        .register("timer", TimerCommand())
-
-    // 显式挂载能力清单即不自动扫描目录——hap 里本来也没有 capabilities/ 这个目录。
-    if (capsJson.size > 0) {
-        app.addCapabilityJson(JsonValue.fromStr(capsJson))
-        Hilog.info(1, "CjTauri", "capability embedded bytes=${capsJson.size}")
-    } else {
-        // 空清单 = 一条命令都不放行（含 system:*），页面会看到「command not allowed」。
-        // 这比静默放行安全，也比假装成功好排查。
-        Hilog.info(1, "CjTauri", "capability missing: rawfile/capabilities.json 没打进 hap，所有命令都会被拒")
-    }
-
-    // 阻塞到 quit()：Ability 的生命周期仍归系统管，`run()` 返回不代表进程退出。
-    app.run(pageHtml)
-    Hilog.info(1, "CjTauri", "after run")
-}
+package ohos_app_cangjie_entry
+
+import cjTauri.*
+import stdx.encoding.json.*
+import kit.PerformanceAnalysisKit.Hilog
+
+/*
+ * {{PROJECT_NAME}} 的框架装配（鸿蒙侧）
+ *
+ * 桌面的 `main()` 在鸿蒙上不成立——鸿蒙应用没有「自己起进程跑一个 main」这回事，
+ * 窗口属于 ArkUI、页面由 ArkWeb 组件承载。所以装配被拆成三段：
+ *   ① `MainAbility.onCreate`：定沙箱目录（`run(html)` 要把页面落到沙箱再 file:// 加载）
+ *   ② `MainAbility.onCreate` 里 `spawn { startTauriApp(...) }`：**必须非 UI 线程**，
+ *      `run()` 会阻塞到 quit()，而 UI 线程要留给 ArkUI 建树
+ *   ③ `onWindowStageCreate`：等宿主登记 → `loadContent` → 组件里建 `Web`
+ *
+ * 页面与能力清单的来路：都来自 hap 的 `resources/rawfile/`，由 Ability 读成字符串传进来
+ * （设备上没有 `ui/` 与 `capabilities/` 目录，这两份是构建期打进 hap 的）。
+ */
+
+/** greet 命令（对标 tauri command）：前端 `tauri.invoke("greet", { name: "..." })` */
+public class GreetCommand <: CommandHandler {
+    public init() {}
+
+    public func handle(cmd: String, args: JsonObject, ipc: IpcContext): JsonValue {
+        var name = "world"
+        if (let Some(n) <- args.get("name")) {
+            match (n.kind()) {
+                case JsonKind.JsString => name = n.asString().getValue()
+                case _ => ()
+            }
+        }
+        return JsonString("Hello, ${name}! 来自仓颉后端（鸿蒙 ArkWeb 宿主）")
+    }
+}
+
+/**
+ * 定时器命令：起一个后台线程，每秒向后端推一个 tick 事件（验证 仓颉 → JS 通道）
+ *
+ * 鸿蒙侧的 `emit` 同样只入队，真正的投递在 `onProxyPost` 里由页面心跳带出去——
+ * 所以页面必须一直在跑（`setInterval` 的心跳由框架的桥脚本负责，业务代码不用管）。
+ */
+public class TimerCommand <: CommandHandler {
+    private var counter: Int64 = 0
+    private var started: Bool = false
+
+    public init() {}
+
+    public func handle(cmd: String, args: JsonObject, ipc: IpcContext): JsonValue {
+        if (!this.started) {
+            this.started = true
+            spawn {
+                while (true) {
+                    sleep(Duration.second)
+                    this.counter += 1
+                    var payload = JsonObject()
+                    payload.put("n", JsonInt(this.counter))
+                    ipc.emit("tick", payload)
+                }
+            }
+        }
+        return JsonString("timer started")
+    }
+}
+
+/**
+ * 装配并运行框架应用（**必须在非 UI 线程调用**：`run()` 阻塞到 `quit()`）
+ *
+ * @param windowTitle 窗口标题（ArkUI 侧不起作用，留着与桌面版对齐）
+ * @param pageHtml 页面原文（rawfile/index.html）
+ * @param capsJson 能力清单原文（rawfile/capabilities.json）；空串表示不挂清单
+ */
+public func startTauriApp(windowTitle: String, pageHtml: String, capsJson: String): Unit {
+    Hilog.info(1, "CjTauri", "startTauriApp begin page=${pageHtml.size}B caps=${capsJson.size}B")
+
+    let app = TauriApp()
+        .window(WindowConfig(windowTitle, 1280, 820))
+        .register("greet", GreetCommand())
+        .register("timer", TimerCommand())
+
+    // 显式挂载能力清单即不自动扫描目录——hap 里本来也没有 capabilities/ 这个目录。
+    if (capsJson.size > 0) {
+        app.addCapabilityJson(JsonValue.fromStr(capsJson))
+        Hilog.info(1, "CjTauri", "capability embedded bytes=${capsJson.size}")
+    } else {
+        // 空清单 = 一条命令都不放行（含 system:*），页面会看到「command not allowed」。
+        // 这比静默放行安全，也比假装成功好排查。
+        Hilog.info(1, "CjTauri", "capability missing: rawfile/capabilities.json 没打进 hap，所有命令都会被拒")
+    }
+
+    // 阻塞到 quit()：Ability 的生命周期仍归系统管，`run()` 返回不代表进程退出。
+    app.run(pageHtml)
+    Hilog.info(1, "CjTauri", "after run")
+}

package/cli/templates/ohos-skeleton/entry/src/main/cangjie/dialog_host.cj

@@ -0,0 +1,217 @@
+package ohos_app_cangjie_entry
+
+import kit.ArkUI.*
+import ohos.arkui.state_macro_manage.*
+import std.collection.HashMap
+import cjTauri.*
+
+/*
+ * 「每个窗口已回填的请求 id」——组件与父组件共享的一格状态（同包、UI 线程内）。
+ *
+ * 为什么需要它：父组件要判断「当前这条还在展示、不能再取下一条」，而展示中这件事
+ * 只有组件自己知道（`answered` 是它的私有 @State）。把答案放在这里，两边读同一份，
+ * 就不用把闭包当构造参数传给 @Component（那条路宏支持有限，且多窗口下容易串台）。
+ *
+ * 没登记过的窗口回 -1：与 `dialogRequestId` 的初值相等，所以**首次**允许取请求。
+ */
+let dialogAnswered: HashMap<String, Int64> = HashMap<String, Int64>()
+
+/** 取某窗口「已回填的请求 id」，没记录过返回 -1（= 还没有任何一条被答过） */
+func dialogAnsweredIdOf(label: String): Int64 {
+    match (dialogAnswered.get(label)) {
+        case Some(v) => return v
+        case None => return -1
+    }
+}
+
+/** 记下某窗口已回填的 id（回填发生在 UI 线程，与读取同线程，不需要锁） */
+func markDialogAnswered(label: String, id: Int64): Unit {
+    dialogAnswered[label] = id
+}
+
+/*
+ * 对话框 overlay 的外观常量（0xAARRGGBB，Int64 就是 ResourceColor）。
+ *
+ * **遮罩必须带 alpha**：早先这里是 `Color.Black`（= 0xFF000000，完全不透明），
+ * 弹出时整页被一块黑板盖住——用户真机实测的原话是「背景全黑了」。
+ * 现在 0x66 ≈ 40% 不透明，页面内容透得出来，才像对话框盖在页面上。
+ *
+ * 这几个常量就是业务侧的定制位：改配色改这里，改布局改下面 `CjDialogHost.build()`。
+ * 想彻底换成自己的样式（比如页内 HTML 弹窗）就不要调 `dialog:message`——
+ * overlay 只是「零配置可用」的默认实现，不是唯一通路。
+ */
+let DIALOG_SCRIM: Int64 = 0x66000000
+
+let DIALOG_CARD_BG: Int64 = 0xFFFFFFFF
+
+let DIALOG_TITLE_TEXT: Int64 = 0xFF1A1A1A
+
+let DIALOG_BODY_TEXT: Int64 = 0xFF44474F
+
+/* 取消键的浅灰底：中性动作不抢主色，桌面惯例里主色只给「确定」 */
+let DIALOG_BTN_NEUTRAL: Int64 = 0xFFF1F3F5
+
+/* 确定键底色按 kind 区分：info 蓝 / warning 橙 / error 红；单键与双键共用这一支 */
+let DIALOG_ACCENT_INFO: Int64 = 0xFF0A59F7
+
+let DIALOG_ACCENT_WARNING: Int64 = 0xFFED6F21
+
+let DIALOG_ACCENT_ERROR: Int64 = 0xFFE84026
+
+/*
+ * kind → 强调色（`normalizeDialogKind` 是框架共享层的归一，认不出的 kind 已回落成 info）
+ *
+ * 只影响「确定键底色」这一个可视点：警告与错误在桌面惯例里都用颜色区分，
+ * 而单键/双键的**语义**判定在框架侧（`dialogShapeOf`），这里不重复判一次。
+ */
+func dialogAccentColor(kind: String): Int64 {
+    match (normalizeDialogKind(kind)) {
+        case "warning" => return DIALOG_ACCENT_WARNING
+        case "error" => return DIALOG_ACCENT_ERROR
+        case _ => return DIALOG_ACCENT_INFO
+    }
+}
+
+/*
+ * 宿主对话框的默认呈现（声明式 overlay）。
+ *
+ * ## 为什么必须是声明式
+ *
+ * 页面经 `dialog:message` 要求弹框时，命令是从 `javaScriptProxy` 的 `post` 回调同步栈上回来的；
+ * 在那条栈上调 `showAlertDialog` / `getPromptAction().showDialog`（含 `workerthread: true`）
+ * 会被 ArkUI **静默丢弃**——不抛异常、窗口不画、回调不来（取证见 docs/鸿蒙ArkWeb接入踩坑.md §10.11）。
+ * 所以唯一的落法是：回调里只置状态，`build()` 里按状态把 overlay 画成组件树的最后一个孩子。
+ *
+ * ## 为什么做成组件
+ *
+ * 内联在 `CjTauriWebView` 里时，业务想换个样子只能改模板——而 `targets/` 是 `cj-tauri sync`
+ * 的派生物，改了下次 sync 就没了。抽成组件后业务只需在根 `Stack` 里放一个实例：
+ *
+ * ```
+ * if (this.dialogActive) {
+ *     CjDialogHost(windowLabel: this.windowLabel, requestId: this.dialogRequestId,
+ *                  title: this.dialogTitle, message: this.dialogMessage,
+ *                  twoKey: this.dialogIsConfirm, kind: this.dialogKind)
+ * }
+ * ```
+ *
+ * 调用点必须保持**纯调用**：挂链式修饰（`.width(...)` 之类）会让 `@Component` 宏展开时
+ * 补不上 `__gen_parent`，报的是「expected N arguments」（见 AGENTS §4）。
+ *
+ * ## 点完为什么自己会消失
+ *
+ * 按钮回填走模块级 `answerArkWebDialog`（框架队列），而父组件的 `dialogActive` 不会因为
+ * 一次点击而变——所以收起由组件自己记：`answered` 记住已回填的请求 id，`requestId`
+ * 与它不等时才画。下一轮请求进来父组件赋一个新的 `requestId`，卡片自然重新出现。
+ * 这条不依赖父组件回调，也就不需要把闭包当构造参数传进来。
+ *
+ * ## 收起后必须 visibility(None)，不能只把子内容裁掉
+ *
+ * 组件要挂在外层 `Stack` 里就得始终返回一个根节点，所以外层 `Column` 收起来之后**仍然在**——
+ * 它是 100%×100% 的透明容器，在 ArkUI 里照样参与命中测试、照样吃掉落在页面上的点击。
+ * 真机第二轮反馈的原话是「点完对话框后，点其他没反应了」：卡片确实没了，整页却点不动，
+ * 凶手就是这层看不见的壳。
+ *
+ * `Visibility.Hidden` 不够——它只是不画，**布局占位与命中区都还在**；只有
+ * `Visibility.None` 才既不占位也不响应事件。所以这里两分：该画时 Visible，收起时 None。
+ * （同类风险：任何「常驻但条件内空的 overlay 容器」都要这么写，别只依赖背景透明。）
+ */
+@Component
+class CjDialogHost {
+    /* label 决定回填给哪个窗口的宿主（多窗口下不能串台） */
+    @Prop
+    var windowLabel: String
+
+    /* 请求 id：父组件每来一条新请求就换一个值，组件据此判断该不该重新显示 */
+    @Prop
+    var requestId: Int64
+
+    @Prop
+    var title: String
+
+    @Prop
+    var message: String
+
+    /* true = 双键（取消 + 确定），false = 单键（只有确定）；判定在框架侧，这里只消费 */
+    @Prop
+    var twoKey: Bool
+
+    /* info / warning / error，只用于确定键配色 */
+    @Prop
+    var kind: String
+
+    /* 已回填过的请求 id（-1 = 还没有）。@State 不允许与 private 同用，宏会拒绝。 */
+    @State
+    var answered: Int64 = -1
+
+    func build() {
+        /* 外层这一层 **不设背景**：遮罩只在「确实该画」的那一支里，否则收起的瞬间
+           整页会被一层灰蒙住不散（内联版第一版就有这个毛病）。 */
+        Column {
+            if (this.requestId != this.answered) {
+                Column {
+                    Column(space: 14) {
+                        Text(this.title)
+                            .fontSize(19)
+                            .fontWeight(FontWeight.Bold)
+                            .fontColor(DIALOG_TITLE_TEXT)
+                            .width(100.percent)
+                        Text(this.message)
+                            .fontSize(15)
+                            .fontColor(DIALOG_BODY_TEXT)
+                            .width(100.percent)
+                        Row(space: 12) {
+                            if (this.twoKey) {
+                                Button("取消")
+                                    .fontSize(15)
+                                    .fontColor(DIALOG_BODY_TEXT)
+                                    .backgroundColor(DIALOG_BTN_NEUTRAL)
+                                    .onClick({ _ => this.answer(false) })
+                            }
+                            Button("确定")
+                                .fontSize(15)
+                                .fontColor(Color.White)
+                                .backgroundColor(dialogAccentColor(this.kind))
+                                .onClick({ _ => this.answer(true) })
+                        }
+                        .width(100.percent)
+                        .justifyContent(FlexAlign.End)
+                    }
+                    .width(86.percent)
+                    .constraintSize(maxWidth: 420)
+                    .padding(20)
+                    .backgroundColor(DIALOG_CARD_BG)
+                    .borderRadius(16)
+                }
+                .width(100.percent)
+                .height(100.percent)
+                .justifyContent(FlexAlign.Center)
+                .backgroundColor(DIALOG_SCRIM)
+            }
+        }
+        .width(100.percent)
+        .height(100.percent)
+        /* 收起后整块退出命中测试（详见类头注释）：只裁子内容会留下 100% 的透明层，
+           真机上表现为「点完对话框后整页点不动」。 */
+        .visibility(if (this.requestId != this.answered) {
+            Visibility.Visible
+        } else {
+            Visibility.None
+        })
+    }
+
+    /**
+     * 回填用户的选择并收起自己。
+     *
+     * 先记 `answered` 再回填：回填会进框架的队列锁，连点时第二下不该再压在同一个 id 上
+     * （那次回填会被宿主的 `awaitingDialogs` 校验拒掉，日志里看得见）。
+     */
+    private func answer(confirmed: Bool): Unit {
+        let id = this.requestId
+        this.answered = id
+        /* 同时登记到共享状态：父组件靠它判断「上一条已答完、可以取下一条」，
+           否则 overlay 收起后父组件永远以为还在展示，第二次点菜单就不弹了。 */
+        markDialogAnswered(this.windowLabel, id)
+        answerArkWebDialog(this.windowLabel, id, confirmed)
+    }
+}