cj-tauri 2.0.0 → 2.1.0

package/src/clipboard_bridge.cj

@@ -1,5 +1,14 @@
 package cjTauri
 
+/**
+ * 鸿蒙侧 pasteboard 的唯一依赖：`LibC.mallocCString` / `malloc` / `free`
+ *
+ * 加 `@When` 门禁是必须的——桌面两平台走 C 桥（下面那段 `cj_bridge_clipboard_*`），
+ * 用不到 LibC；不门禁就会在桌面构建里变成一条 `unused import` 警告（AGENTS §3 零警告）。
+ */
+@When[env == "ohos"]
+import std.posix.*
+
 
 /**
  * 剪贴板 / 通知桥（plugin_clipboard、plugin_notification 的 FFI 面）：
@@ -53,3 +62,172 @@ foreign func cj_bridge_clipboard_free(s: CString): Unit
 @When[env != "ohos"]
 @C
 foreign func cj_bridge_notification_notify(h: CPointer<Unit>, title: CString, body: CString): Int32
+
+/* ==========================================================================
+ * 鸿蒙侧剪贴板：直接 FFI 到原生 pasteboard（`libpasteboard.so`）
+ *
+ * ## 为什么不是 `ohos.pasteboard`
+ *
+ * 仓颉套件里**没有**这个包。查过两套 SDK 的包清单（`api/lib/linux_ohos_aarch64_cjnative/`）：
+ * 6.1（apiVersion 24，`build-hap.sh` 默认选它的那套）的 340 个 ohos 包里没有 pasteboard，
+ * `kit/` 下也没有再导出；只有旧的 5.0（apiVersion 15，Beta2）带 `ohos.pasteboard.cjo`。
+ * 于是在设备上能用的只有原生 C API（`native/sysroot/usr/include/database/pasteboard/`，
+ * 同一 sysroot 里就有 `libpasteboard.so`，`entry/cjpm.toml` 的 `-L` 已指着它）。
+ *
+ * ## 为什么这不算「破坏宿主能力位如实约定」
+ *
+ * 平台差异只落在 `@When[env == "ohos"]` 这一处（AGENTS §2 允许的第二个落点就是条件编译），
+ * 桌面两平台仍走 C 桥同名导出，上层（`WebViewHost.clipboardWriteText/ReadText`）一行都不用分叉。
+ *
+ * ## 权限前提（判据在设备上，不在代码里）
+ *
+ * 写（SetData）不需要权限；**读（GetData）要 `ohos.permission.READ_PASTEBOARD`**
+ * （`udmf_datashare_config.json` 里是 user_grant + system_basic）。普通签名的应用拿不到该权限时，
+ * GetData 不抛异常、只回空数据 / 非 0 状态——所以读路径**只能靠真机实测**判定通没通，
+ * 代码里不许假设它「应该能读」。`arkwebClipboardReadText` 因此对「空 / 被拒 / 非文本」一律回 None。
+ * ========================================================================== */
+
+/** 取本进程的粘贴板句柄（失败回空指针） */
+@When[env == "ohos"]
+@C
+foreign func OH_Pasteboard_Create(): CPointer<Unit>
+
+@When[env == "ohos"]
+@C
+foreign func OH_Pasteboard_Destroy(pasteboard: CPointer<Unit>): Unit
+
+/** 0 = 成功；非 0 = 平台拒绝（状态码见 `oh_pasteboard_err_code.h`） */
+@When[env == "ohos"]
+@C
+foreign func OH_Pasteboard_SetData(pasteboard: CPointer<Unit>, data: CPointer<Unit>): Int32
+
+/** 读：`status` 是出参（`Pasteboard_Status` 的 0 是 E_OK）；返回的 UdmfData 由调用方 Destroy */
+@When[env == "ohos"]
+@C
+foreign func OH_Pasteboard_GetData(pasteboard: CPointer<Unit>, status: CPointer<Int32>): CPointer<Unit>
+
+@When[env == "ohos"]
+@C
+foreign func OH_UdmfData_Create(): CPointer<Unit>
+
+@When[env == "ohos"]
+@C
+foreign func OH_UdmfData_Destroy(pThis: CPointer<Unit>): Unit
+
+@When[env == "ohos"]
+@C
+foreign func OH_UdmfData_AddRecord(pThis: CPointer<Unit>, record: CPointer<Unit>): Int32
+
+/** 取「主纯文本」（不必自己遍历 records）；没有纯文本时回非 0 */
+@When[env == "ohos"]
+@C
+foreign func OH_UdmfData_GetPrimaryPlainText(data: CPointer<Unit>, plainText: CPointer<Unit>): Int32
+
+@When[env == "ohos"]
+@C
+foreign func OH_UdmfRecord_Create(): CPointer<Unit>
+
+@When[env == "ohos"]
+@C
+foreign func OH_UdmfRecord_Destroy(pThis: CPointer<Unit>): Unit
+
+@When[env == "ohos"]
+@C
+foreign func OH_UdmfRecord_AddPlainText(pThis: CPointer<Unit>, plainText: CPointer<Unit>): Int32
+
+@When[env == "ohos"]
+@C
+foreign func OH_UdsPlainText_Create(): CPointer<Unit>
+
+@When[env == "ohos"]
+@C
+foreign func OH_UdsPlainText_Destroy(pThis: CPointer<Unit>): Unit
+
+@When[env == "ohos"]
+@C
+foreign func OH_UdsPlainText_SetContent(pThis: CPointer<Unit>, content: CString): Int32
+
+/** 回的是库内自有缓冲（**不要** free），并发的另一次读会让它失效——取到就立刻拷成 String */
+@When[env == "ohos"]
+@C
+foreign func OH_UdsPlainText_GetContent(pThis: CPointer<Unit>): CString
+
+/**
+ * 写文本进系统剪贴板（鸿蒙侧）。true = 平台接受了这次写入。
+ *
+ * 收尾是**显式**的：本机仓颉没有 `defer`（实测 `error: undeclared identifier 'defer'`），
+ * 每个出口都要自己 Destroy，漏一个就是一处泄漏。
+ */
+@When[env == "ohos"]
+public func arkwebClipboardWriteText(text: String): Bool {
+    let pb = unsafe { OH_Pasteboard_Create() }
+    if (unsafe { pb.isNull() }) {
+        return false
+    }
+    let data = unsafe { OH_UdmfData_Create() }
+    let record = unsafe { OH_UdmfRecord_Create() }
+    let plain = unsafe { OH_UdsPlainText_Create() }
+    if (unsafe { data.isNull() } || unsafe { record.isNull() } || unsafe { plain.isNull() }) {
+        unsafe { OH_UdsPlainText_Destroy(plain) }
+        unsafe { OH_UdmfRecord_Destroy(record) }
+        unsafe { OH_UdmfData_Destroy(data) }
+        unsafe { OH_Pasteboard_Destroy(pb) }
+        return false
+    }
+    let content = unsafe { LibC.mallocCString(text) }
+    var ok = false
+    if (unsafe { OH_UdsPlainText_SetContent(plain, content) } == 0) {
+        if (unsafe { OH_UdmfRecord_AddPlainText(record, plain) } == 0) {
+            if (unsafe { OH_UdmfData_AddRecord(data, record) } == 0) {
+                ok = unsafe { OH_Pasteboard_SetData(pb, data) } == 0
+            }
+        }
+    }
+    unsafe { LibC.free(content) }
+    unsafe { OH_UdsPlainText_Destroy(plain) }
+    unsafe { OH_UdmfRecord_Destroy(record) }
+    unsafe { OH_UdmfData_Destroy(data) }
+    unsafe { OH_Pasteboard_Destroy(pb) }
+    return ok
+}
+
+/**
+ * 读系统剪贴板文本（鸿蒙侧）：None = 空 / 非文本 / 平台拒绝（含缺 READ_PASTEBOARD 权限）。
+ *
+ * 三种 None 在页面侧看起来一样，**这是有意的**：WebViewHost 的契约就是 Option，
+ * 平台没给出文本与平台拒绝了读取，对调用方是同一个「没拿到」。要区分得看 hilog 里的
+ * `[cj-bridge] pasteboard read status=` 行（由应用侧 `probeLog` 打，框架侧 eprintln 在设备上不可见）。
+ */
+@When[env == "ohos"]
+public func arkwebClipboardReadText(): Option<String> {
+    let pb = unsafe { OH_Pasteboard_Create() }
+    if (unsafe { pb.isNull() }) {
+        return None
+    }
+    let statusBox = unsafe { LibC.malloc<Int32>(count: 1) }
+    if (unsafe { statusBox.isNull() }) {
+        unsafe { OH_Pasteboard_Destroy(pb) }
+        return None
+    }
+    let statusPtr = unsafe { CPointer<Int32>(statusBox) }
+    unsafe { statusPtr.write(0) }
+    let data = unsafe { OH_Pasteboard_GetData(pb, statusPtr) }
+    var out: Option<String> = None
+    if (!unsafe { data.isNull() }) {
+        let plain = unsafe { OH_UdsPlainText_Create() }
+        if (!unsafe { plain.isNull() }) {
+            if (unsafe { OH_UdmfData_GetPrimaryPlainText(data, plain) } == 0) {
+                let cstr = unsafe { OH_UdsPlainText_GetContent(plain) }
+                if (!unsafe { cstr.isNull() }) {
+                    let value = unsafe { cstr.toString() }
+                    out = Some(value)
+                }
+            }
+            unsafe { OH_UdsPlainText_Destroy(plain) }
+        }
+        unsafe { OH_UdmfData_Destroy(data) }
+    }
+    unsafe { LibC.free(statusBox) }
+    unsafe { OH_Pasteboard_Destroy(pb) }
+    return out
+}

package/src/dialog_spec.cj

@@ -0,0 +1,79 @@
+package cjTauri
+
+/**
+ * 消息框的「形状」：由 kind 归一而来，呈现层只认这三态
+ *
+ * ## 为什么单独抽一层
+ *
+ * `kind` 是页面可控的字符串（`dialog:message` 的入参），而「单键还是双键」直接决定呈现层的
+ * 按钮布局与回填语义。桌面两平台的原生对话框与鸿蒙的应用侧 overlay 必须给出**同一个**判定，
+ * 否则同一个 kind 在两处表现不同。原先这段判定写在 `host_arkweb.cj` 里，而那个文件带
+ * `@When[env == "ohos"]` 门禁——桌面上根本无法编译，也就没有单测覆盖。
+ *
+ * 这里只放「语义」，不放任何呈现：按钮文案、配色、布局一律由应用侧决定（框架不猜文案）。
+ */
+public enum DialogShape {
+    /**
+     * 单键（确定）：弹出即成立，回填恒为 true
+     *
+     * `info` / `warning` / `error` 都归这里——它们的区别只体现在呈现的图标与配色，
+     * 语义上没有第二个选择。
+     */
+    | Message
+
+    /** 双键（确定 / 取消）：取消回填 false */
+    | Confirm
+
+    /**
+     * 带文本输入：输入内容随回填一起交回
+     *
+     * 当前没有命令产生这个形状（桌面原生对话框没有 prompt 等价物，框架不造平台分叉的 API），
+     * 先把它留在协议里：宿主与呈现层按形状分派，将来开放时不必再改一次接口形状。
+     */
+    | Prompt
+}
+
+/** 认得的 kind；其余一律按 info 处理（页面写错一个字母不该让对话框不弹） */
+let DIALOG_KINDS: Array<String> = ["info", "warning", "error", "confirm", "prompt"]
+
+/**
+ * kind 归一：去首尾空白、转小写，认不出的回落 `info`
+ *
+ * 回落而不是报错是有意的：`kind` 只影响呈现，写错了还让命令失败等于把「外观问题」升级成
+ * 「功能不可用」。归一的收益是**下游只可能见到这五个词之一**，不用各自再判一次。
+ */
+public func normalizeDialogKind(kind: String): String {
+    let trimmed = kind.trimAscii()
+    if (trimmed.size == 0) {
+        return "info"
+    }
+    let lowered = trimmed.toAsciiLower()
+    for (candidate in DIALOG_KINDS) {
+        if (candidate == lowered) {
+            return candidate
+        }
+    }
+    return "info"
+}
+
+/**
+ * kind → 形状（内部先归一，所以入参可以是任意字符串）
+ *
+ * 呈现层据此决定按钮个数与是否需要输入框；宿主据此决定回填值是布尔还是「布尔 + 文本」。
+ */
+public func dialogShapeOf(kind: String): DialogShape {
+    match (normalizeDialogKind(kind)) {
+        case "confirm" => return DialogShape.Confirm
+        case "prompt" => return DialogShape.Prompt
+        case _ => return DialogShape.Message
+    }
+}
+
+/** 形状是否要「确定 / 取消」两键（`Prompt` 也要两键：输入完要么交回、要么放弃） */
+public func dialogShapeIsTwoKey(shape: DialogShape): Bool {
+    match (shape) {
+        case DialogShape.Confirm => return true
+        case DialogShape.Prompt => return true
+        case DialogShape.Message => return false
+    }
+}

package/src/dragdrop.cj

@@ -1,26 +1,26 @@
-package cjTauri
-
-/**
- * 拖放策略（RFC-002 §5 的 v1 落地）：框架只负责「把拖进来的文件路径交出去」，
- * 动作由页面决定（监听 `dragdrop:files` 事件，事件需在能力清单 events 里声明）。
- *
- * 策略必须在 `start()` / `startUrl()` 之前通过 `TauriApp.setDragDrop(...)` 定稿——
- * Linux 侧要在建 view 时决定挂不挂 drag dest；不设置 = 不注册（默认关，现有应用零改动）。
- */
-public class DragDropPolicy {
-    /** 关掉则平台层不注册 drop target（默认关） */
-    public let enabled: Bool
-
-    /** 接受文件路径（v1 唯一载荷；text 载荷留给后续版本，先不设开关） */
-    public let files: Bool
-
-    public init(enabled: Bool, files: Bool) {
-        this.enabled = enabled
-        this.files = files
-    }
-
-    /** 便捷构造：开文件拖入（v1 最常用形态） */
-    public static func filesEnabled(): DragDropPolicy {
-        return DragDropPolicy(true, true)
-    }
-}
+package cjTauri
+
+/**
+ * 拖放策略（RFC-002 §5 的 v1 落地）：框架只负责「把拖进来的文件路径交出去」，
+ * 动作由页面决定（监听 `dragdrop:files` 事件，事件需在能力清单 events 里声明）。
+ *
+ * 策略必须在 `start()` / `startUrl()` 之前通过 `TauriApp.setDragDrop(...)` 定稿——
+ * Linux 侧要在建 view 时决定挂不挂 drag dest；不设置 = 不注册（默认关，现有应用零改动）。
+ */
+public class DragDropPolicy {
+    /** 关掉则平台层不注册 drop target（默认关） */
+    public let enabled: Bool
+
+    /** 接受文件路径（v1 唯一载荷；text 载荷留给后续版本，先不设开关） */
+    public let files: Bool
+
+    public init(enabled: Bool, files: Bool) {
+        this.enabled = enabled
+        this.files = files
+    }
+
+    /** 便捷构造：开文件拖入（v1 最常用形态） */
+    public static func filesEnabled(): DragDropPolicy {
+        return DragDropPolicy(true, true)
+    }
+}

package/src/embedded_assets.cj

@@ -1,98 +1,98 @@
-package cjTauri
-
-/**
- * 内嵌资源释放（单文件包专用）。
- *
- * 背景：应用产物可以打成**单个 exe**（`scripts/pack-win-single.sh`），页面 / 能力清单 / vendor JS
- * 都编成字符串，但**随包的外部程序**（例如 cjnote 的 cjh 后端）没法静态链接进 exe，只能作为 PE
- * 资源（RT_RCDATA）跟着走；运行期由本函数取出写盘，应用再按得到的路径去起它。
- *
- * `dir` 由调用方给（框架不认识应用名），典型是 `%LOCALAPPDATA%\<应用名>\runtime`；
- * **调用方负责先把目录建好**（桥只建最后一级）。
- *
- * 返回值：> 0 = 就绪的文件数（本次释放的 + 本来就在的）；0 = 这个产物里没有内嵌资源
- * （普通构建就是这样，**不是错误**）；-1 = 参数为空或写盘失败（原因在 stderr）。
- * 幂等：目标已在且大小与资源一致时桥会跳过，所以每次启动都可以调。
- */
-public func extractEmbeddedAssets(dir: String): Int64 {
-    if (dir.isEmpty()) {
-        eprintln("[cj-tauri] extractEmbeddedAssets: 目录为空")
-        return -1
-    }
-    let n = extractAssetsBridge(dir)
-    if (n < 0) {
-        eprintln("[cj-tauri] 释放内嵌资源失败：${dir}")
-    }
-    return n
-}
-
-/**
- * 鸿蒙侧没有 C 桥产物（`native/platforms/harmonyos/` 目前只有契约），照桌面那份写声明会让模块
- * 加载期就 SIGSEGV（与 `log_bridge.cj` / `process_hidden.cj` 同一条坑，AGENTS §4）——按 `env` 分叉，
- * 如实降级。判据用 `env` 而不是 `arch`：桌面 aarch64 Linux 也有 C 桥。
- */
-@When[env != "ohos"]
-@C
-foreign func cj_bridge_extract_assets(dir: CString): Int32
-
-@When[env != "ohos"]
-func extractAssetsBridge(dir: String): Int64 {
-    var n: Int32 = 0
-    unsafe {
-        n = cj_bridge_extract_assets(LibC.mallocCString(dir))
-    }
-    return Int64(n)
-}
-
-@When[env == "ohos"]
-func extractAssetsBridge(dir: String): Int64 {
-    let _ = dir
-    eprintln("[cj-tauri] 本平台没有 C 桥，无内嵌资源可释放")
-    return 0
-}
-
-/**
- * 按**绝对路径**预加载一个随包释放出来的动态库（单文件包专用）。
- *
- * 为什么需要它（2026-10-21 实测，另一台机器）：仓颉运行时的随机数默认实现走 OpenSSL，而它按
- * **裸名**找 `libcrypto-3-x64.dll` / `libssl-3-x64.dll`——SDK 与 stdx 都不带这两个，开发机上只是
- * 恰好命中 PATH 里 Git 自带的那份。于是同一条 `ws://` 连接线，本机全通、别人双击就挂：
- * `ws: connect failed: Can not load openssl library or function RAND_bytes.`
- * （RFC6455 升级要算 `Sec-WebSocket-Key` 的随机 nonce，**明文 ws 也逃不掉**）。
- *
- * 只要进程内先按绝对路径加载一次，之后同类裸名加载就命中已加载模块：不必改 PATH，
- * 也不必把 DLL 摆到 exe 旁边（单文件承诺不破）。
- *
- * `path` 必须是释放后的真实路径；返回 true = 已在进程内（含本来就在的）。
- * 平台没有 C 桥时如实返回 false（`src/log_bridge.cj` 同款门禁）。
- */
-public func preloadEmbeddedLibrary(path: String): Bool {
-    if (path.isEmpty()) {
-        eprintln("[cj-tauri] preloadEmbeddedLibrary: 路径为空")
-        return false
-    }
-    let ok = preloadLibraryBridge(path)
-    if (!ok) {
-        eprintln("[cj-tauri] 预加载动态库失败：${path}")
-    }
-    return ok
-}
-
-@When[env != "ohos"]
-@C
-foreign func cj_bridge_preload_library(path: CString): Int32
-
-@When[env != "ohos"]
-func preloadLibraryBridge(path: String): Bool {
-    var ok: Int32 = 0
-    unsafe {
-        ok = cj_bridge_preload_library(LibC.mallocCString(path))
-    }
-    return ok == 1
-}
-
-@When[env == "ohos"]
-func preloadLibraryBridge(path: String): Bool {
-    let _ = path
-    return false
-}
+package cjTauri
+
+/**
+ * 内嵌资源释放（单文件包专用）。
+ *
+ * 背景：应用产物可以打成**单个 exe**（`scripts/pack-win-single.sh`），页面 / 能力清单 / vendor JS
+ * 都编成字符串，但**随包的外部程序**（例如 cjnote 的 cjh 后端）没法静态链接进 exe，只能作为 PE
+ * 资源（RT_RCDATA）跟着走；运行期由本函数取出写盘，应用再按得到的路径去起它。
+ *
+ * `dir` 由调用方给（框架不认识应用名），典型是 `%LOCALAPPDATA%\<应用名>\runtime`；
+ * **调用方负责先把目录建好**（桥只建最后一级）。
+ *
+ * 返回值：> 0 = 就绪的文件数（本次释放的 + 本来就在的）；0 = 这个产物里没有内嵌资源
+ * （普通构建就是这样，**不是错误**）；-1 = 参数为空或写盘失败（原因在 stderr）。
+ * 幂等：目标已在且大小与资源一致时桥会跳过，所以每次启动都可以调。
+ */
+public func extractEmbeddedAssets(dir: String): Int64 {
+    if (dir.isEmpty()) {
+        eprintln("[cj-tauri] extractEmbeddedAssets: 目录为空")
+        return -1
+    }
+    let n = extractAssetsBridge(dir)
+    if (n < 0) {
+        eprintln("[cj-tauri] 释放内嵌资源失败：${dir}")
+    }
+    return n
+}
+
+/**
+ * 鸿蒙侧没有 C 桥产物（`native/platforms/harmonyos/` 目前只有契约），照桌面那份写声明会让模块
+ * 加载期就 SIGSEGV（与 `log_bridge.cj` / `process_hidden.cj` 同一条坑，AGENTS §4）——按 `env` 分叉，
+ * 如实降级。判据用 `env` 而不是 `arch`：桌面 aarch64 Linux 也有 C 桥。
+ */
+@When[env != "ohos"]
+@C
+foreign func cj_bridge_extract_assets(dir: CString): Int32
+
+@When[env != "ohos"]
+func extractAssetsBridge(dir: String): Int64 {
+    var n: Int32 = 0
+    unsafe {
+        n = cj_bridge_extract_assets(LibC.mallocCString(dir))
+    }
+    return Int64(n)
+}
+
+@When[env == "ohos"]
+func extractAssetsBridge(dir: String): Int64 {
+    let _ = dir
+    eprintln("[cj-tauri] 本平台没有 C 桥，无内嵌资源可释放")
+    return 0
+}
+
+/**
+ * 按**绝对路径**预加载一个随包释放出来的动态库（单文件包专用）。
+ *
+ * 为什么需要它（2026-10-21 实测，另一台机器）：仓颉运行时的随机数默认实现走 OpenSSL，而它按
+ * **裸名**找 `libcrypto-3-x64.dll` / `libssl-3-x64.dll`——SDK 与 stdx 都不带这两个，开发机上只是
+ * 恰好命中 PATH 里 Git 自带的那份。于是同一条 `ws://` 连接线，本机全通、别人双击就挂：
+ * `ws: connect failed: Can not load openssl library or function RAND_bytes.`
+ * （RFC6455 升级要算 `Sec-WebSocket-Key` 的随机 nonce，**明文 ws 也逃不掉**）。
+ *
+ * 只要进程内先按绝对路径加载一次，之后同类裸名加载就命中已加载模块：不必改 PATH，
+ * 也不必把 DLL 摆到 exe 旁边（单文件承诺不破）。
+ *
+ * `path` 必须是释放后的真实路径；返回 true = 已在进程内（含本来就在的）。
+ * 平台没有 C 桥时如实返回 false（`src/log_bridge.cj` 同款门禁）。
+ */
+public func preloadEmbeddedLibrary(path: String): Bool {
+    if (path.isEmpty()) {
+        eprintln("[cj-tauri] preloadEmbeddedLibrary: 路径为空")
+        return false
+    }
+    let ok = preloadLibraryBridge(path)
+    if (!ok) {
+        eprintln("[cj-tauri] 预加载动态库失败：${path}")
+    }
+    return ok
+}
+
+@When[env != "ohos"]
+@C
+foreign func cj_bridge_preload_library(path: CString): Int32
+
+@When[env != "ohos"]
+func preloadLibraryBridge(path: String): Bool {
+    var ok: Int32 = 0
+    unsafe {
+        ok = cj_bridge_preload_library(LibC.mallocCString(path))
+    }
+    return ok == 1
+}
+
+@When[env == "ohos"]
+func preloadLibraryBridge(path: String): Bool {
+    let _ = path
+    return false
+}