cj-tauri 2.0.0 → 2.1.0

package/src/platform/platform_discover.cj

@@ -1,176 +1,176 @@
-package cjTauri.platform
-
-import std.env.*
-import std.collection.ArrayList
-
-/**
- * 平台发现（RFC-002 §4.2 / §5.3）——全框架唯一的「端在哪儿」知识入口
- *
- * 按约定（RFC §5.3），os 名匹配的 @When 只允许出现在本文件与 targets 目录下的生成胶水；
- * CI 用 `grep -r '@When\[os' src/ | grep -v src/platform/` 守这条线。
- * @When 分支一律成对出现（本仓库惯例，参照 host_webview2.cj），保证任何目标下每个
- * 符号恰好有一个定义；跨平台文件里只用短名。
- *
- * 批次 0 边界：本文件只提供**可编译的默认实现**（桌面 Linux / Windows 实测，
- * 鸿蒙走 mobile(filesDir)），特性位清单是占位值，接端时按实测修正。
- */
-public class Platform {
-    /**
-     * 桌面端默认发现：paths 走平台规范目录（RFC §5.2），dev 看 CJ_TAURI_DEV_URL
-     *
-     * arch 默认 x86_64；ARM64 Linux 桌面请显式传 arch（它的 os 与 x86_64 Linux 相同，
-     * 这是仓库已知的「同 os 多宿主」来源，见 RFC §5.1）。
-     * appId 由 launch() 从清单传入（清单解析在批次 1 落地，见 RFC §3/§13.1 风险 1）。
-     */
-    public static func discover(appId: String, arch: String): AppContext {
-        return desktop(appId, arch)
-    }
-
-    public static func desktop(appId: String, arch: String): AppContext {
-        let data = "${dataRoot()}/${appId}"
-        let target = TargetInfo(desktopOs(), arch, desktopHostKind(), "desktop")
-        let fs = ArrayList<PlatformFeature>()
-        fs.add(PlatformFeature.MultiWindow)
-        fs.add(PlatformFeature.FilePicker)
-        fs.add(PlatformFeature.ClipboardImage)
-        fs.add(PlatformFeature.Tray)
-        return AppContext(
-            AppPaths(data, "${cacheRoot()}/${appId}", "${cacheRoot()}/${appId}/tmp"),
-            target, devMode(), fs)
-    }
-
-    /**
-     * 移动端发现：沙箱目录由系统能力入口传入（鸿蒙 Ability 的 filesDir / Android 的 filesDir）
-     *
-     * 沙箱端没有 dev server，dev 恒为 false；hostKind 是占位（鸿蒙 ArkWeb，
-     * Android 接入时由其 Provider 决定），特性位清单接端实测后修正。
-     */
-    public static func mobile(filesDir: String, arch: String): AppContext {
-        let target = TargetInfo("Linux", arch, "arkweb", "mobile")
-        let fs = ArrayList<PlatformFeature>()
-        fs.add(PlatformFeature.MultiWindow)
-        fs.add(PlatformFeature.ClipboardImage)
-        fs.add(PlatformFeature.SoftKeyboardInset)
-        return AppContext(
-            AppPaths(filesDir, "${filesDir}/cache", "${filesDir}/cache/tmp"),
-            target, false, fs)
-    }
-
-    // ---- 平台名与目录根：@When 成对门禁，只落在这几个函数（RFC §5.3）----
-
-    /** dev server 探测：子包不引用父包，直接读环境变量（与 TauriApp.devUrl() 同语义） */
-    private static func devMode(): Bool {
-        if (let Some(v) <- getVariable("CJ_TAURI_DEV_URL")) {
-            if (v.size > 0) {
-                return true
-            }
-        }
-        return false
-    }
-
-    /**
-     * 当前目标的 TargetInfo（批次 1：装配层 resolveHost 用它选宿主）
-     *
-     * ohos 报 HarmonyOS/arkweb/mobile（运行时 os 虽取 Linux，语义归鸿蒙）；
-     * arch 从 CJ_TAURI_ARCH 环境变量取——编译期拿不到可靠的 arch，
-     * 由 hvigor / CLI 构建时注入（未注入为 unknown，宿主选择请勿依赖 arch，
-     * 用 hostKind/display 区分——它们正是为「同 os 多宿主」设计的）。
-     */
-    public static func guessTarget(): TargetInfo {
-        let arch = getVariable("CJ_TAURI_ARCH") ?? "unknown"
-        return TargetInfo(currentOs(), arch, currentHostKind(), currentDisplay())
-    }
-
-    @When[env == "ohos"]
-    private static func currentOs(): String {
-        return "HarmonyOS"
-    }
-
-    @When[env != "ohos"]
-    private static func currentOs(): String {
-        return desktopOs()
-    }
-
-    @When[env == "ohos"]
-    private static func currentHostKind(): String {
-        return "arkweb"
-    }
-
-    @When[env != "ohos"]
-    private static func currentHostKind(): String {
-        return desktopHostKind()
-    }
-
-    @When[env == "ohos"]
-    private static func currentDisplay(): String {
-        return "mobile"
-    }
-
-    @When[env != "ohos"]
-    private static func currentDisplay(): String {
-        return "desktop"
-    }
-
-    @When[os == "Windows"]
-    private static func desktopOs(): String {
-        return "Windows"
-    }
-
-    @When[os != "Windows"]
-    private static func desktopOs(): String {
-        return "Linux"
-    }
-
-    @When[os == "Windows"]
-    private static func desktopHostKind(): String {
-        return "webview2"
-    }
-
-    @When[os != "Windows"]
-    private static func desktopHostKind(): String {
-        return "webkitgtk"
-    }
-
-    @When[os == "Windows"]
-    private static func dataRoot(): String {
-        return getVariable("APPDATA") ?? "."
-    }
-
-    @When[os == "Windows"]
-    private static func cacheRoot(): String {
-        return getVariable("LOCALAPPDATA") ?? "."
-    }
-
-    @When[os == "Linux" && env != "ohos"]
-    private static func dataRoot(): String {
-        return getVariable("XDG_DATA_HOME") ?? "${getVariable("HOME") ?? "."}/.local/share"
-    }
-
-    @When[os == "Linux" && env != "ohos"]
-    private static func cacheRoot(): String {
-        return getVariable("XDG_CACHE_HOME") ?? "${getVariable("HOME") ?? "."}/.cache"
-    }
-
-    // ohos 目标上 desktop() 不会被调用，但符号必须存在才能编译；
-    // 返回占位值，真机路径由 mobile(filesDir) 提供。
-    @When[env == "ohos"]
-    private static func dataRoot(): String {
-        return "."
-    }
-
-    @When[env == "ohos"]
-    private static func cacheRoot(): String {
-        return "."
-    }
-
-    // 其余目标（macOS 等）暂按 HOME 兜底：接入对应端时在这里补实现并真机验证。
-    @When[os != "Windows" && os != "Linux"]
-    private static func dataRoot(): String {
-        return "${getVariable("HOME") ?? "."}/.local/share"
-    }
-
-    @When[os != "Windows" && os != "Linux"]
-    private static func cacheRoot(): String {
-        return "${getVariable("HOME") ?? "."}/.cache"
-    }
-}
+package cjTauri.platform
+
+import std.env.*
+import std.collection.ArrayList
+
+/**
+ * 平台发现（RFC-002 §4.2 / §5.3）——全框架唯一的「端在哪儿」知识入口
+ *
+ * 按约定（RFC §5.3），os 名匹配的 @When 只允许出现在本文件与 targets 目录下的生成胶水；
+ * CI 用 `grep -r '@When\[os' src/ | grep -v src/platform/` 守这条线。
+ * @When 分支一律成对出现（本仓库惯例，参照 host_webview2.cj），保证任何目标下每个
+ * 符号恰好有一个定义；跨平台文件里只用短名。
+ *
+ * 批次 0 边界：本文件只提供**可编译的默认实现**（桌面 Linux / Windows 实测，
+ * 鸿蒙走 mobile(filesDir)），特性位清单是占位值，接端时按实测修正。
+ */
+public class Platform {
+    /**
+     * 桌面端默认发现：paths 走平台规范目录（RFC §5.2），dev 看 CJ_TAURI_DEV_URL
+     *
+     * arch 默认 x86_64；ARM64 Linux 桌面请显式传 arch（它的 os 与 x86_64 Linux 相同，
+     * 这是仓库已知的「同 os 多宿主」来源，见 RFC §5.1）。
+     * appId 由 launch() 从清单传入（清单解析在批次 1 落地，见 RFC §3/§13.1 风险 1）。
+     */
+    public static func discover(appId: String, arch: String): AppContext {
+        return desktop(appId, arch)
+    }
+
+    public static func desktop(appId: String, arch: String): AppContext {
+        let data = "${dataRoot()}/${appId}"
+        let target = TargetInfo(desktopOs(), arch, desktopHostKind(), "desktop")
+        let fs = ArrayList<PlatformFeature>()
+        fs.add(PlatformFeature.MultiWindow)
+        fs.add(PlatformFeature.FilePicker)
+        fs.add(PlatformFeature.ClipboardImage)
+        fs.add(PlatformFeature.Tray)
+        return AppContext(
+            AppPaths(data, "${cacheRoot()}/${appId}", "${cacheRoot()}/${appId}/tmp"),
+            target, devMode(), fs)
+    }
+
+    /**
+     * 移动端发现：沙箱目录由系统能力入口传入（鸿蒙 Ability 的 filesDir / Android 的 filesDir）
+     *
+     * 沙箱端没有 dev server，dev 恒为 false；hostKind 是占位（鸿蒙 ArkWeb，
+     * Android 接入时由其 Provider 决定），特性位清单接端实测后修正。
+     */
+    public static func mobile(filesDir: String, arch: String): AppContext {
+        let target = TargetInfo("Linux", arch, "arkweb", "mobile")
+        let fs = ArrayList<PlatformFeature>()
+        fs.add(PlatformFeature.MultiWindow)
+        fs.add(PlatformFeature.ClipboardImage)
+        fs.add(PlatformFeature.SoftKeyboardInset)
+        return AppContext(
+            AppPaths(filesDir, "${filesDir}/cache", "${filesDir}/cache/tmp"),
+            target, false, fs)
+    }
+
+    // ---- 平台名与目录根：@When 成对门禁，只落在这几个函数（RFC §5.3）----
+
+    /** dev server 探测：子包不引用父包，直接读环境变量（与 TauriApp.devUrl() 同语义） */
+    private static func devMode(): Bool {
+        if (let Some(v) <- getVariable("CJ_TAURI_DEV_URL")) {
+            if (v.size > 0) {
+                return true
+            }
+        }
+        return false
+    }
+
+    /**
+     * 当前目标的 TargetInfo（批次 1：装配层 resolveHost 用它选宿主）
+     *
+     * ohos 报 HarmonyOS/arkweb/mobile（运行时 os 虽取 Linux，语义归鸿蒙）；
+     * arch 从 CJ_TAURI_ARCH 环境变量取——编译期拿不到可靠的 arch，
+     * 由 hvigor / CLI 构建时注入（未注入为 unknown，宿主选择请勿依赖 arch，
+     * 用 hostKind/display 区分——它们正是为「同 os 多宿主」设计的）。
+     */
+    public static func guessTarget(): TargetInfo {
+        let arch = getVariable("CJ_TAURI_ARCH") ?? "unknown"
+        return TargetInfo(currentOs(), arch, currentHostKind(), currentDisplay())
+    }
+
+    @When[env == "ohos"]
+    private static func currentOs(): String {
+        return "HarmonyOS"
+    }
+
+    @When[env != "ohos"]
+    private static func currentOs(): String {
+        return desktopOs()
+    }
+
+    @When[env == "ohos"]
+    private static func currentHostKind(): String {
+        return "arkweb"
+    }
+
+    @When[env != "ohos"]
+    private static func currentHostKind(): String {
+        return desktopHostKind()
+    }
+
+    @When[env == "ohos"]
+    private static func currentDisplay(): String {
+        return "mobile"
+    }
+
+    @When[env != "ohos"]
+    private static func currentDisplay(): String {
+        return "desktop"
+    }
+
+    @When[os == "Windows"]
+    private static func desktopOs(): String {
+        return "Windows"
+    }
+
+    @When[os != "Windows"]
+    private static func desktopOs(): String {
+        return "Linux"
+    }
+
+    @When[os == "Windows"]
+    private static func desktopHostKind(): String {
+        return "webview2"
+    }
+
+    @When[os != "Windows"]
+    private static func desktopHostKind(): String {
+        return "webkitgtk"
+    }
+
+    @When[os == "Windows"]
+    private static func dataRoot(): String {
+        return getVariable("APPDATA") ?? "."
+    }
+
+    @When[os == "Windows"]
+    private static func cacheRoot(): String {
+        return getVariable("LOCALAPPDATA") ?? "."
+    }
+
+    @When[os == "Linux" && env != "ohos"]
+    private static func dataRoot(): String {
+        return getVariable("XDG_DATA_HOME") ?? "${getVariable("HOME") ?? "."}/.local/share"
+    }
+
+    @When[os == "Linux" && env != "ohos"]
+    private static func cacheRoot(): String {
+        return getVariable("XDG_CACHE_HOME") ?? "${getVariable("HOME") ?? "."}/.cache"
+    }
+
+    // ohos 目标上 desktop() 不会被调用，但符号必须存在才能编译；
+    // 返回占位值，真机路径由 mobile(filesDir) 提供。
+    @When[env == "ohos"]
+    private static func dataRoot(): String {
+        return "."
+    }
+
+    @When[env == "ohos"]
+    private static func cacheRoot(): String {
+        return "."
+    }
+
+    // 其余目标（macOS 等）暂按 HOME 兜底：接入对应端时在这里补实现并真机验证。
+    @When[os != "Windows" && os != "Linux"]
+    private static func dataRoot(): String {
+        return "${getVariable("HOME") ?? "."}/.local/share"
+    }
+
+    @When[os != "Windows" && os != "Linux"]
+    private static func cacheRoot(): String {
+        return "${getVariable("HOME") ?? "."}/.cache"
+    }
+}

package/src/platform/platform_env.cj

@@ -1,29 +1,29 @@
-package cjTauri.platform
-
-import std.collection.ArrayList
-
-/**
- * L0 适配层契约（RFC-002 §5.1）——每端各实现一份，框架只依赖这些接口
- *
- * 这些接口**不是给业务用的**：业务拿到的只有 AppContext。
- * 批次 1 接入装配层时，Platform.discover() 会按端挑选实现。
- */
-
-/** 资产读取：按逻辑名取内容（读盘 / 内嵌常量 / rawfile 由实现决定） */
-public interface AssetResolver {
-    func readText(name: String): Option<String>
-    func exists(name: String): Bool
-}
-
-/** 目录与特性发现：沙箱端必须实现，桌面端由 Platform 给默认 */
-public interface PlatformEnv {
-    func paths(appId: String): AppPaths
-    func assets(root: String): AssetResolver
-    /** RFC 写 Set<PlatformFeature>；批次 0 用 ArrayList 近似，接口定型时统一替换 */
-    func features(): ArrayList<PlatformFeature>
-}
-
-/** 页面材化：把 Asset 逻辑名变成宿主可加载的形态（L0 内部细节） */
-public interface PageMaterializer {
-    func resolve(asset: String, page: String): PageSource
-}
+package cjTauri.platform
+
+import std.collection.ArrayList
+
+/**
+ * L0 适配层契约（RFC-002 §5.1）——每端各实现一份，框架只依赖这些接口
+ *
+ * 这些接口**不是给业务用的**：业务拿到的只有 AppContext。
+ * 批次 1 接入装配层时，Platform.discover() 会按端挑选实现。
+ */
+
+/** 资产读取：按逻辑名取内容（读盘 / 内嵌常量 / rawfile 由实现决定） */
+public interface AssetResolver {
+    func readText(name: String): Option<String>
+    func exists(name: String): Bool
+}
+
+/** 目录与特性发现：沙箱端必须实现，桌面端由 Platform 给默认 */
+public interface PlatformEnv {
+    func paths(appId: String): AppPaths
+    func assets(root: String): AssetResolver
+    /** RFC 写 Set<PlatformFeature>；批次 0 用 ArrayList 近似，接口定型时统一替换 */
+    func features(): ArrayList<PlatformFeature>
+}
+
+/** 页面材化：把 Asset 逻辑名变成宿主可加载的形态（L0 内部细节） */
+public interface PageMaterializer {
+    func resolve(asset: String, page: String): PageSource
+}

package/src/platform/platform_feature.cj

@@ -1,31 +1,31 @@
-package cjTauri.platform
-
-/**
- * 平台特性位（RFC-002 §4.5）——业务判断"这个端有没有某设施"的唯一手段
- *
- * 命名约定（评审定稿）：**看到 PlatformFeature 只谈可用性，看到 Capability 只谈权限**。
- * - 平台特性 = 本枚举：这个端的系统设施有没有（托盘、文件选择器……）；
- * - 安全能力 = CapabilitySet（capability.cj）：哪条命令允许被前端调用。
- * 两者中文都容易被叫成"能力"，类型名必须分开，否则会退化回 os 分支。
- *
- * 治理规则（RFC §13.2 问题 4）：新增一个特性位，必须同时写清三端语义与缺省降级行为，
- * 否则业务会把它当成按 OS 名分支的马甲。
- */
-public enum PlatformFeature {
-    | Tray               // 托盘
-    | MultiWindow        // 多窗口（桌面）/ 多任务（移动端）
-    | FilePicker         // 系统文件选择器
-    | ClipboardImage     // 剪贴板图片读写
-    | SoftKeyboardInset  // 软键盘遮挡可感知（移动端）
-
-    /** 枚举无内建 ==（1.2.0 实测），比较走模式匹配 */
-    public static func same(a: PlatformFeature, b: PlatformFeature): Bool {
-        match (a) {
-            case Tray => match (b) { case Tray => true case _ => false }
-            case MultiWindow => match (b) { case MultiWindow => true case _ => false }
-            case FilePicker => match (b) { case FilePicker => true case _ => false }
-            case ClipboardImage => match (b) { case ClipboardImage => true case _ => false }
-            case SoftKeyboardInset => match (b) { case SoftKeyboardInset => true case _ => false }
-        }
-    }
-}
+package cjTauri.platform
+
+/**
+ * 平台特性位（RFC-002 §4.5）——业务判断"这个端有没有某设施"的唯一手段
+ *
+ * 命名约定（评审定稿）：**看到 PlatformFeature 只谈可用性，看到 Capability 只谈权限**。
+ * - 平台特性 = 本枚举：这个端的系统设施有没有（托盘、文件选择器……）；
+ * - 安全能力 = CapabilitySet（capability.cj）：哪条命令允许被前端调用。
+ * 两者中文都容易被叫成"能力"，类型名必须分开，否则会退化回 os 分支。
+ *
+ * 治理规则（RFC §13.2 问题 4）：新增一个特性位，必须同时写清三端语义与缺省降级行为，
+ * 否则业务会把它当成按 OS 名分支的马甲。
+ */
+public enum PlatformFeature {
+    | Tray               // 托盘
+    | MultiWindow        // 多窗口（桌面）/ 多任务（移动端）
+    | FilePicker         // 系统文件选择器
+    | ClipboardImage     // 剪贴板图片读写
+    | SoftKeyboardInset  // 软键盘遮挡可感知（移动端）
+
+    /** 枚举无内建 ==（1.2.0 实测），比较走模式匹配 */
+    public static func same(a: PlatformFeature, b: PlatformFeature): Bool {
+        match (a) {
+            case Tray => match (b) { case Tray => true case _ => false }
+            case MultiWindow => match (b) { case MultiWindow => true case _ => false }
+            case FilePicker => match (b) { case FilePicker => true case _ => false }
+            case ClipboardImage => match (b) { case ClipboardImage => true case _ => false }
+            case SoftKeyboardInset => match (b) { case SoftKeyboardInset => true case _ => false }
+        }
+    }
+}

package/src/platform/platform_page_source.cj

@@ -1,87 +1,87 @@
-package cjTauri.platform
-
-import std.fs.*
-
-/**
- * 页面来源（RFC-002 §4.3）——取代 run(html) / runUrl(url) 双入口的唯一表达
- *
- * 业务与清单只写 Asset("ui/index.html") 这一种；devMode 下由框架改写为
- * DevServer；Asset 在各端怎么落地（读盘 / rawfile 材化 / assets base URL）
- * 是 L0 适配层（PageMaterializer）的事，业务与骨架都不接触沙箱路径。
- */
-public enum PageSource {
-    /** 代码里直接给的 HTML 字符串（探针、错误页用） */
-    | Inline(String)
-    /** 资产逻辑名，如 "ui/index.html"（sync 生成期校验存在，见 RFC §6.1） */
-    | Asset(String)
-    /** http(s):// 或 file:// 直载 */
-    | Url(String)
-    /** 开发期前端 dev server（HMR），由 CJ_TAURI_DEV_URL 注入 */
-    | DevServer(String)
-}
-
-/** 解析结果：宿主最终执行的动作（纯数据，可测） */
-public enum PageLoad {
-    | StartHtml(String)  // host.start(html)
-    | StartUrl(String)   // host.startUrl(url)
-}
-
-/**
- * PageSource → PageLoad 的唯一决策点（批次 1，RFC §4.3）
- *
- * - Inline / Url / DevServer：直接映射
- * - Asset：优先走注入的 AssetResolver；未注入时按 cwd 相对路径读盘——与现有模板
- *   textOrFile 的桌面行为等价，鸿蒙 rawfile / 内嵌常量的实现在批次 2 随清单接入
- * - 找不到资产：抛可照做的错误，不静默白屏（与宿主装配「不静默回落」同约定）
- */
-
-/** 资产解析异常：message 即面向用户的措辞。子包不引用根包的 CommandException
- *  （那会构成父↔子互引），独立定义；传播路径与原先一致（run() 路径上无人
- *  按具体类型捕获，message 原样抛到顶层） */
-public class AssetResolutionException <: Exception {
-    public init(msg: String) {
-        super(msg)
-    }
-}
-
-public func resolvePage(source: PageSource, resolver: Option<AssetResolver>): PageLoad {
-    match (source) {
-        case Inline(html) => return PageLoad.StartHtml(html)
-        case Url(url) => return PageLoad.StartUrl(url)
-        case DevServer(url) => return PageLoad.StartUrl(url)
-        case Asset(name) =>
-            match (resolver) {
-                case Some(r) =>
-                    match (r.readText(name)) {
-                        case Some(html) => return PageLoad.StartHtml(html)
-                        case None =>
-                            throw AssetResolutionException("资产未找到：${name}（请检查注入的 AssetResolver 与清单 [assets] 配置）")
-                    }
-                case None =>
-                    var text = ""
-                    try {
-                        text = String.fromUtf8(File.readFrom(name))
-                    } catch (e: Exception) {
-                        throw AssetResolutionException("资产未找到：${name}（未注入 AssetResolver，按相对路径读盘失败：${e}；鸿蒙 rawfile / 内嵌场景请注入对应解析器）")
-                    }
-                    return PageLoad.StartHtml(text)
-            }
-    }
-}
-
-/**
- * devMode 改写（RFC §4.3）：CJ_TAURI_DEV_URL 存在时，Asset 页面自动改走 dev server
- *
- * 只改 Asset：显式 Inline（探针）/ Url / DevServer 是业务明说的意图，不改写。
- * 纯函数，可测。
- */
-public func rewriteForDev(source: PageSource, devUrl: Option<String>): PageSource {
-    match (devUrl) {
-        case Some(url) =>
-            match (source) {
-                case Asset(_) => return PageSource.DevServer(url)
-                case _ => return source
-            }
-        case None => return source
-    }
-}
+package cjTauri.platform
+
+import std.fs.*
+
+/**
+ * 页面来源（RFC-002 §4.3）——取代 run(html) / runUrl(url) 双入口的唯一表达
+ *
+ * 业务与清单只写 Asset("ui/index.html") 这一种；devMode 下由框架改写为
+ * DevServer；Asset 在各端怎么落地（读盘 / rawfile 材化 / assets base URL）
+ * 是 L0 适配层（PageMaterializer）的事，业务与骨架都不接触沙箱路径。
+ */
+public enum PageSource {
+    /** 代码里直接给的 HTML 字符串（探针、错误页用） */
+    | Inline(String)
+    /** 资产逻辑名，如 "ui/index.html"（sync 生成期校验存在，见 RFC §6.1） */
+    | Asset(String)
+    /** http(s):// 或 file:// 直载 */
+    | Url(String)
+    /** 开发期前端 dev server（HMR），由 CJ_TAURI_DEV_URL 注入 */
+    | DevServer(String)
+}
+
+/** 解析结果：宿主最终执行的动作（纯数据，可测） */
+public enum PageLoad {
+    | StartHtml(String)  // host.start(html)
+    | StartUrl(String)   // host.startUrl(url)
+}
+
+/**
+ * PageSource → PageLoad 的唯一决策点（批次 1，RFC §4.3）
+ *
+ * - Inline / Url / DevServer：直接映射
+ * - Asset：优先走注入的 AssetResolver；未注入时按 cwd 相对路径读盘——与现有模板
+ *   textOrFile 的桌面行为等价，鸿蒙 rawfile / 内嵌常量的实现在批次 2 随清单接入
+ * - 找不到资产：抛可照做的错误，不静默白屏（与宿主装配「不静默回落」同约定）
+ */
+
+/** 资产解析异常：message 即面向用户的措辞。子包不引用根包的 CommandException
+ *  （那会构成父↔子互引），独立定义；传播路径与原先一致（run() 路径上无人
+ *  按具体类型捕获，message 原样抛到顶层） */
+public class AssetResolutionException <: Exception {
+    public init(msg: String) {
+        super(msg)
+    }
+}
+
+public func resolvePage(source: PageSource, resolver: Option<AssetResolver>): PageLoad {
+    match (source) {
+        case Inline(html) => return PageLoad.StartHtml(html)
+        case Url(url) => return PageLoad.StartUrl(url)
+        case DevServer(url) => return PageLoad.StartUrl(url)
+        case Asset(name) =>
+            match (resolver) {
+                case Some(r) =>
+                    match (r.readText(name)) {
+                        case Some(html) => return PageLoad.StartHtml(html)
+                        case None =>
+                            throw AssetResolutionException("资产未找到：${name}（请检查注入的 AssetResolver 与清单 [assets] 配置）")
+                    }
+                case None =>
+                    var text = ""
+                    try {
+                        text = String.fromUtf8(File.readFrom(name))
+                    } catch (e: Exception) {
+                        throw AssetResolutionException("资产未找到：${name}（未注入 AssetResolver，按相对路径读盘失败：${e}；鸿蒙 rawfile / 内嵌场景请注入对应解析器）")
+                    }
+                    return PageLoad.StartHtml(text)
+            }
+    }
+}
+
+/**
+ * devMode 改写（RFC §4.3）：CJ_TAURI_DEV_URL 存在时，Asset 页面自动改走 dev server
+ *
+ * 只改 Asset：显式 Inline（探针）/ Url / DevServer 是业务明说的意图，不改写。
+ * 纯函数，可测。
+ */
+public func rewriteForDev(source: PageSource, devUrl: Option<String>): PageSource {
+    match (devUrl) {
+        case Some(url) =>
+            match (source) {
+                case Asset(_) => return PageSource.DevServer(url)
+                case _ => return source
+            }
+        case None => return source
+    }
+}