@heybox/hb-sdk 0.9.1-alpha.8 → 0.9.1

package/types/index.d.ts

@@ -169,7 +169,7 @@ interface PathRoot {
      * 对应 operation：[FileHandle](/reference/symbols/root/interfaces/FileHandle) 的 `create()`、`remove()`、
      * `exists()`、`readText()`、`readBytes()`、`writeText()`、`writeBytes()`、`stat()` 分别使用
      * `file.create`、`file.remove`、`file.exists`、`file.readText`、`file.readBytes`、`file.writeText`、
-     * `file.writeBytes`、`file.stat`。未声明或未启用权限时分别返回 `PERMISSION_NOT_DECLARED` 或
+     * `file.writeBytes`、`file.stat`。当前运行快照缺少或未启用所需权限时分别返回 `PERMISSION_NOT_IN_SNAPSHOT` 或
      * `PERMISSION_DENIED`，Host 未开放具体 operation 时返回 `METHOD_FORBIDDEN`；这些错误在调用异步
      * 方法时发生，不由本方法抛出。
      *
@@ -244,8 +244,8 @@ interface PathRoot {
      * 后续 I/O 才要求在 `package.json#heybox.permissions` 中声明并启用 `filesystem`，并由 Host 开放
      * 对应 operation：[DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 的 `create()`、
      * `exists()`、`list()`、`remove()` 分别使用 `directory.create`、`directory.exists`、
-     * `directory.list`、`directory.remove`。未声明或未启用权限时分别返回
-     * `PERMISSION_NOT_DECLARED` 或 `PERMISSION_DENIED`，Host 未开放具体 operation 时返回
+     * `directory.list`、`directory.remove`。当前运行快照缺少或未启用所需权限时分别返回
+     * `PERMISSION_NOT_IN_SNAPSHOT` 或 `PERMISSION_DENIED`，Host 未开放具体 operation 时返回
      * `METHOD_FORBIDDEN`；这些错误在调用异步方法时发生，不由本方法抛出。
      *
      * `files.sandbox.directory('.')` 是沙箱根目录的逻辑代理，可用于 `exists()` 或 `list()`，但不能删除；
@@ -322,8 +322,8 @@ interface FileHandle {
      * ensure-exists 不会截断或改写已有内容。
      * @throws {@link HbMiniProgramSDKError} options 非对象，或 `recursive` / `exclusive` 不是 boolean 时
      * 返回 `INVALID_PARAMS`；代理不是 `readwrite` 时在发送 bridge 请求前返回 `FILE_ACCESS_DENIED`。
-     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 时返回
-     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放或未协商到 `file.create` 时返回
+     * @throws {@link HbMiniProgramSDKError} 当前运行快照缺少或未启用 `filesystem` 时返回
+     * `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`；Host 未开放或未协商到 `file.create` 时返回
      * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
      * @throws {@link HbMiniProgramSDKError} `recursive: false` 且父目录缺失时返回
      * `DIRECTORY_NOT_FOUND`；目标实际是目录或路径中的祖先实际是文件时返回 `FILE_TYPE_MISMATCH`；
@@ -344,8 +344,8 @@ interface FileHandle {
      * 该方法不需要可信用户手势，也不会创建新的 direct handle、消耗 1024 个外部授权句柄配额或暴露真实路径。
      *
      * 新 PC Host 支持该 operation；Android/iOS 需要 `1.3.396+` 并以 `system.describe` 实际宣告的
-     * operation 为准，OHOS 同样按 Host 协商结果启用。Android 的精确 SAF File 仅授予 `read`，因此
-     * 不能调用本方法；sandbox 或可写目录派生文件不受该精确 File 限制。Web、Browser Dev Host、旧 Host
+     * operation 为准，OHOS 同样按 Host 协商结果启用。外部精确 File 只有实际获授 `readwrite`
+     * 时才能调用本方法；较早 Android 客户端可能仅授予 `read`。Web、Browser Dev Host、旧 Host
      * 或 operation 集不完整时 fail closed，不提供 Blob 或内存 fallback。
      *
      * `create()` 只创建空目标。父目录已经存在时，{@link FileHandle.writeText} /
@@ -405,8 +405,8 @@ interface FileHandle {
      * @throws {@link HbMiniProgramSDKError} 目标或祖先不存在时返回 `FILE_NOT_FOUND` /
      * `DIRECTORY_NOT_FOUND`，目标实际是目录时可返回 `FILE_TYPE_MISMATCH`；授权失效或 Host 删除失败
      * 时返回 `FILE_ACCESS_REVOKED` / `FILE_IO_FAILED` 等稳定文件错误码。
-     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 时返回
-     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放 `file.remove` operation 时返回
+     * @throws {@link HbMiniProgramSDKError} 当前运行快照缺少或未启用 `filesystem` 时返回
+     * `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`；Host 未开放 `file.remove` operation 时返回
      * `METHOD_FORBIDDEN`，旧 Runtime 不认识该 method 时可返回 `METHOD_NOT_FOUND`。
      *
      * @remarks
@@ -453,8 +453,8 @@ interface FileHandle {
      * @returns Host 能取得目标且确认其类型为文件时返回 `true`。目标文件不存在、任一祖先目录
      * 不存在，或同一逻辑位置实际是目录时返回 `false`；这些正常的“不存在”结果不会抛出
      * `FILE_NOT_FOUND`、`DIRECTORY_NOT_FOUND` 或 `FILE_TYPE_MISMATCH`。
-     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 权限时分别以
-     * `PERMISSION_NOT_DECLARED`、`PERMISSION_DENIED` 拒绝；当前 Host 未开放 `file.exists` 时以
+     * @throws {@link HbMiniProgramSDKError} 当前运行快照缺少或未启用 `filesystem` 权限时分别以
+     * `PERMISSION_NOT_IN_SNAPSHOT`、`PERMISSION_DENIED` 拒绝；当前 Host 未开放 `file.exists` 时以
      * `METHOD_FORBIDDEN` 拒绝，旧 Runtime 也可能返回 `METHOD_NOT_FOUND`。
      * @throws {@link HbMiniProgramSDKError} picker / `saveFile()` 返回的精确外部授权被撤销、句柄
      * 不属于当前 Runtime session 或 registry 已释放时，以 `FILE_ACCESS_REVOKED` 拒绝，而不是返回
@@ -539,8 +539,8 @@ interface FileHandle {
      * @throws {@link HbMiniProgramSDKError} 目标或祖先不存在时返回 `FILE_NOT_FOUND` / `DIRECTORY_NOT_FOUND`，
      * 目标类型不匹配时返回 `FILE_TYPE_MISMATCH`。Android/iOS 当前对一次完整读取设 8 MiB 上限，
      * 超限时返回 `FILE_TOO_LARGE`。
-     * @throws {@link HbMiniProgramSDKError} 普通 sandbox / picker / `saveFile()` 句柄未声明或未启用
-     * `filesystem` 时返回 `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放或未协商到
+     * @throws {@link HbMiniProgramSDKError} 使用普通 sandbox / picker / `saveFile()` 句柄时，运行快照缺少或未启用
+     * `filesystem` 时返回 `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`；Host 未开放或未协商到
      * `file.readText` 时返回 `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
      * @throws {@link HbMiniProgramSDKError} 外部 direct handle 已失效、来自其他或已结束的 Runtime
      * session 时返回 `FILE_ACCESS_REVOKED`；SDK / Runtime 已终止、调用超时、Host 返回无效内容或底层
@@ -605,8 +605,8 @@ interface FileHandle {
      * @throws {@link HbMiniProgramSDKError} `content` 不是字符串时在 Host I/O 前以
      * `INVALID_PARAMS` 拒绝；当前代理的 `mode` 不是 `readwrite` 时在发送 bridge 请求前以
      * `FILE_ACCESS_DENIED` 拒绝。
-     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 权限时分别以
-     * `PERMISSION_NOT_DECLARED`、`PERMISSION_DENIED` 拒绝；Host 未开放 `file.writeText` 时以
+     * @throws {@link HbMiniProgramSDKError} 当前运行快照缺少或未启用 `filesystem` 权限时分别以
+     * `PERMISSION_NOT_IN_SNAPSHOT`、`PERMISSION_DENIED` 拒绝；Host 未开放 `file.writeText` 时以
      * `METHOD_FORBIDDEN` 拒绝，旧 Runtime 也可能返回 `METHOD_NOT_FOUND`。
      * @throws {@link HbMiniProgramSDKError} 缺失父目录时返回 `DIRECTORY_NOT_FOUND`，路径中的祖先
      * 或目标类型不匹配时返回 `FILE_TYPE_MISMATCH`。Android / iOS 对一次完整写入的 UTF-8 编码结果
@@ -632,7 +632,7 @@ interface FileHandle {
      * sandbox lazy FileHandle 固定继承 `readwrite`，并在每次调用时按当前 Mini-program identity 解析。
      * `pickFiles({ mode: 'readwrite' })`、`pickDirectory({ mode: 'readwrite' })` 的派生文件和
      * `saveFile()` 返回的精确外部 FileHandle 也可以写入，但授权范围不会因此扩张；direct handle 只在
-     * 当前 Runtime session 有效。只读 picker 结果、Android 的精确 SAF File 和 Companion attachment
+     * 当前 Runtime session 有效。只读 picker 结果和 Companion attachment
      * 会在本地 mode 检查时以 `FILE_ACCESS_DENIED` 拒绝。该方法不需要新的可信用户手势；只有最初
      * 获取外部授权的 picker / `saveFile()` 需要手势。
      *
@@ -698,8 +698,8 @@ interface FileHandle {
      * @throws {@link HbMiniProgramSDKError} 目标或祖先不存在时返回 `FILE_NOT_FOUND` / `DIRECTORY_NOT_FOUND`，
      * 目标类型不匹配时返回 `FILE_TYPE_MISMATCH`。Android / iOS 当前对一次完整读取设 `8 MiB`
      * （`8 * 1024 * 1024` bytes）上限，超限时返回 `FILE_TOO_LARGE`。
-     * @throws {@link HbMiniProgramSDKError} 普通 sandbox / picker / `saveFile()` 句柄未声明或未启用
-     * `filesystem` 时返回 `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放或未协商到
+     * @throws {@link HbMiniProgramSDKError} 使用普通 sandbox / picker / `saveFile()` 句柄时，运行快照缺少或未启用
+     * `filesystem` 时返回 `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`；Host 未开放或未协商到
      * `file.readBytes` 时返回 `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
      * @throws {@link HbMiniProgramSDKError} 外部 direct handle 被撤销、不属于当前或已结束的 Runtime
      * session 时返回 `FILE_ACCESS_REVOKED`；Host 拒绝底层授权时也可能返回 `FILE_ACCESS_DENIED`。
@@ -775,8 +775,8 @@ interface FileHandle {
      * @throws {@link HbMiniProgramSDKError} `content` 不是 `Uint8Array`，或其 backing buffer 是
      * `SharedArrayBuffer` 时，在发送 bridge 请求前返回 `INVALID_PARAMS`；当前代理不是 `readwrite`
      * 时在输入复制和 Host I/O 前返回 `FILE_ACCESS_DENIED`。
-     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 权限时返回
-     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放或未协商到 `file.writeBytes` 时返回
+     * @throws {@link HbMiniProgramSDKError} 当前运行快照缺少或未启用 `filesystem` 权限时返回
+     * `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`；Host 未开放或未协商到 `file.writeBytes` 时返回
      * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
      * @throws {@link HbMiniProgramSDKError} 缺失父目录时返回 `DIRECTORY_NOT_FOUND`，路径中的祖先或
      * 目标类型不匹配时返回 `FILE_TYPE_MISMATCH`。Android / iOS 对一次完整写入设 8 MiB 上限；当前
@@ -802,8 +802,8 @@ interface FileHandle {
      *
      * sandbox lazy FileHandle 固定继承 `readwrite`。`pickFiles({ mode: 'readwrite' })`、
      * `pickDirectory({ mode: 'readwrite' })` 的派生文件和 `saveFile()` 返回的精确外部 FileHandle 也可
-     * 写入，但 direct handle 只在当前 Runtime session 有效，且授权范围不会扩张。只读 picker 结果、
-     * Android 的精确 SAF File 和 Companion attachment 返回 `FILE_ACCESS_DENIED`。该方法不需要新的
+     * 写入，但 direct handle 只在当前 Runtime session 有效，且授权范围不会扩张。只读 picker 结果
+     * 和 Companion attachment 返回 `FILE_ACCESS_DENIED`。该方法不需要新的
      * 可信用户手势；只有最初取得外部授权的 picker / `saveFile()` 需要手势。
      *
      * 新 PC Host 支持该操作；Android / iOS `1.3.396+` 仅在 `system.describe` 同时宣告
@@ -853,8 +853,8 @@ interface FileHandle {
      * `DIRECTORY_NOT_FOUND`；目标实际是目录、direct handle 类型不匹配时返回 `FILE_TYPE_MISMATCH`。
      * @throws {@link HbMiniProgramSDKError} 外部 direct handle 已撤销、不属于当前 Runtime session 或
      * registry 已释放时返回 `FILE_ACCESS_REVOKED`；Host 拒绝读取元数据时返回 `FILE_ACCESS_DENIED`。
-     * @throws {@link HbMiniProgramSDKError} 普通 FileHandle 未声明或未启用 `filesystem` 时返回
-     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放或未协商到 `file.stat` 时返回
+     * @throws {@link HbMiniProgramSDKError} 使用普通 FileHandle 时，运行快照缺少或未启用 `filesystem` 时返回
+     * `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`；Host 未开放或未协商到 `file.stat` 时返回
      * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。Companion attachment 是受控例外：
      * 它使用已启用的 `companion` 授权读取自身元数据，不要求另行声明 `filesystem`。
      * @throws {@link HbMiniProgramSDKError} Host 返回非对象、错误的 `kind`，负数/小数/unsafe `size`，
@@ -957,8 +957,8 @@ interface DirectoryHandle extends PathRoot {
      * `result === directory`。不会创建新的授权 handle，也不会刷新或改变代理的 `name`、`mode`。
      * @throws {@link HbMiniProgramSDKError} options 非对象，或 `recursive` / `exclusive` 不是 boolean 时
      * 返回 `INVALID_PARAMS`；代理不是 `readwrite` 时在发送 bridge 请求前返回 `FILE_ACCESS_DENIED`。
-     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 时返回
-     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放或未协商到 `directory.create` 时返回
+     * @throws {@link HbMiniProgramSDKError} 当前运行快照缺少或未启用 `filesystem` 时返回
+     * `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`；Host 未开放或未协商到 `directory.create` 时返回
      * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
      * @throws {@link HbMiniProgramSDKError} `recursive: false` 且任一父目录缺失时返回
      * `DIRECTORY_NOT_FOUND`；目标实际是文件或路径中的祖先实际是文件时返回 `FILE_TYPE_MISMATCH`；
@@ -1042,8 +1042,8 @@ interface DirectoryHandle extends PathRoot {
      * @throws {@link HbMiniProgramSDKError} 目标或任一祖先不存在时返回 `DIRECTORY_NOT_FOUND`，目标
      * 实际是文件或路径中的祖先类型不匹配时返回 `FILE_TYPE_MISMATCH`。删除已经不存在的目录不会
      * 当作幂等成功；需要“确保不存在”语义时应先接受缺失错误或在操作后调用 `exists()` 对账。
-     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 权限时分别以
-     * `PERMISSION_NOT_DECLARED`、`PERMISSION_DENIED` 拒绝；Host 未开放 `directory.remove` 时以
+     * @throws {@link HbMiniProgramSDKError} 当前运行快照缺少或未启用 `filesystem` 权限时分别以
+     * `PERMISSION_NOT_IN_SNAPSHOT`、`PERMISSION_DENIED` 拒绝；Host 未开放 `directory.remove` 时以
      * `METHOD_FORBIDDEN` 拒绝，旧 Runtime 也可能返回 `METHOD_NOT_FOUND`。
      * @throws {@link HbMiniProgramSDKError} SDK 已销毁、Runtime 已卸载、请求超时、Host 拒绝删除或
      * 发生底层 I/O 失败时，以 `SDK_DESTROYED`、`RUNTIME_UNAVAILABLE`、`REQUEST_TIMEOUT`、
@@ -1126,8 +1126,8 @@ interface DirectoryHandle extends PathRoot {
      * `FILE_NOT_FOUND`、`DIRECTORY_NOT_FOUND`、`FILE_TYPE_MISMATCH` 报告同类状态时返回 `false`；Host
      * stat 响应不是对象或 `kind` 不是 `'directory'` 时也按类型不匹配返回 `false`。不返回目录元数据、
      * 句柄或缺失原因。
-     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 时返回
-     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放或未协商到 `directory.exists`
+     * @throws {@link HbMiniProgramSDKError} 当前运行快照缺少或未启用 `filesystem` 时返回
+     * `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`；Host 未开放或未协商到 `directory.exists`
      * （底层要求 `files.stat`）时返回 `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
      * @throws {@link HbMiniProgramSDKError} 外部 direct directory handle 被撤销、不属于当前或已结束的
      * Runtime session 时返回 `FILE_ACCESS_REVOKED`；Host 拒绝当前目录授权时返回 `FILE_ACCESS_DENIED`。
@@ -1206,8 +1206,8 @@ interface DirectoryHandle extends PathRoot {
      * @throws {@link HbMiniProgramSDKError} 当前目录或任一祖先不存在时返回 `DIRECTORY_NOT_FOUND`，目标
      * 实际是文件时返回 `FILE_TYPE_MISMATCH`；外部 direct Directory 授权失效、来自其他或已结束的
      * Runtime session 时返回 `FILE_ACCESS_REVOKED`。
-     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 时返回
-     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放或未协商到 `directory.list` 时返回
+     * @throws {@link HbMiniProgramSDKError} 当前运行快照缺少或未启用 `filesystem` 时返回
+     * `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`；Host 未开放或未协商到 `directory.list` 时返回
      * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
      * @throws {@link HbMiniProgramSDKError} Host 返回非数组、稀疏数组、非法 kind/name/mode/handle，或
      * 子项不能安全派生为当前目录的直接后代时返回 `FILE_IO_FAILED`；其他 Host 枚举或底层 I/O 失败
@@ -1319,8 +1319,8 @@ interface FilesModule {
      * @throws {@link HbMiniProgramSDKError} options、`mode`、`accept` 或 `multiple` 非法时返回
      * `INVALID_PARAMS`；缺少当前可信用户手势时返回 `USER_GESTURE_REQUIRED`；用户取消系统选择器
      * 时返回 `FILE_PICKER_CANCELLED`。
-     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 时返回
-     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放/未协商到 `files.external` 时返回
+     * @throws {@link HbMiniProgramSDKError} 当前运行快照缺少或未启用 `filesystem` 时返回
+     * `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`；Host 未开放/未协商到 `files.external` 时返回
      * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`；请求的 `readwrite` 未获 Host
      * 授予时返回 `FILE_ACCESS_DENIED`。
      * @throws {@link HbMiniProgramSDKError} 整批结果会让当前 session 的外部 direct handle 超过
@@ -1410,8 +1410,8 @@ interface FilesModule {
      * @throws {@link HbMiniProgramSDKError} options 或 `mode` 非法时返回 `INVALID_PARAMS`；缺少当前
      * 可信用户手势时返回 `USER_GESTURE_REQUIRED`；用户取消系统选择器时返回
      * `FILE_PICKER_CANCELLED`。
-     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 时返回
-     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放/未协商到 `files.external` 时返回
+     * @throws {@link HbMiniProgramSDKError} 当前运行快照缺少或未启用 `filesystem` 时返回
+     * `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`；Host 未开放/未协商到 `files.external` 时返回
      * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`；请求的 `readwrite` 未获 Host
      * 授予时返回 `FILE_ACCESS_DENIED`。
      * @throws {@link HbMiniProgramSDKError} 当前 session 的外部 direct handle 达到 1024 上限时返回
@@ -1496,8 +1496,8 @@ interface FilesModule {
      * @throws {@link HbMiniProgramSDKError} options 缺失/非对象、`suggestedName` 非字符串或不是规范
      * basename、或传入 V1 不支持的 `accept` 时返回 `INVALID_PARAMS`；缺少当前可信用户手势时
      * 返回 `USER_GESTURE_REQUIRED`；用户取消系统保存界面时返回 `FILE_PICKER_CANCELLED`。
-     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 时返回
-     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放/未协商到保存 operation 时返回
+     * @throws {@link HbMiniProgramSDKError} 当前运行快照缺少或未启用 `filesystem` 时返回
+     * `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`；Host 未开放/未协商到保存 operation 时返回
      * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。目标已存在且 Host 不能独占创建
      * 时返回 `FILE_ALREADY_EXISTS`，不会静默覆盖。
      * @throws {@link HbMiniProgramSDKError} 当前 session 的外部 direct handle 达到 1024 上限时返回
@@ -1878,8 +1878,8 @@ interface MiniProgramNetworkModule {
      * @throws {@link HbMiniProgramNetworkError} Host 已完成 HTTP 响应，但状态未通过
      * `validateStatus` 时抛出；错误的 `status`、`data`、安全 `headers`、`config` 与 `response`
      * 可用于业务分支。它不表示权限、bridge 或网络不可达。
-     * @throws {@link HbMiniProgramSDKError} 配置/数据/Header 非法时返回 `INVALID_PARAMS`；未声明、
-     * 未批准 `network` 或未获官方域名批准时返回 `PERMISSION_NOT_DECLARED` /
+     * @throws {@link HbMiniProgramSDKError} 配置/数据/Header 非法时返回 `INVALID_PARAMS`；当前运行快照
+     * 缺少 `network` 时返回 `PERMISSION_NOT_IN_SNAPSHOT`；权限未启用或未获官方域名批准时返回
      * `PERMISSION_DENIED`；Host 不支持请求形态时返回 `REQUEST_UNSUPPORTED`，Host/transport
      * 失败返回 `REQUEST_FAILED`，Host 能力关闭或旧 Runtime 不认识 method 时可返回
      * `METHOD_FORBIDDEN` / `METHOD_NOT_FOUND`，响应结构无效返回 `INVALID_NETWORK_RESPONSE`；
@@ -1956,8 +1956,8 @@ interface MiniProgramNetworkModule {
      * @returns Host 完成原子提交后的 `readwrite` {@link FileHandle}。File target 返回传入的同一
      * 代理；Directory target 返回目标目录中新建或替换的直接子 File 代理。
      * @throws {@link HbMiniProgramSDKError} 参数、URL、Header、目标或 Host 返回值不合法时返回
-     * `INVALID_PARAMS` / `INVALID_NETWORK_RESPONSE`；未声明或未启用 `network`、`filesystem`
-     * 时返回 `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 能力缺失时返回
+     * `INVALID_PARAMS` / `INVALID_NETWORK_RESPONSE`；当前运行快照缺少或未启用 `network`、`filesystem`
+     * 时返回 `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`；Host 能力缺失时返回
      * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
      * @throws {@link HbMiniProgramSDKError} 非成功或部分 HTTP 响应返回 `DOWNLOAD_HTTP_STATUS`；
      * 网络/响应 framing 失败、空闲超时、提交前取消或超出 `maxBytes` 分别返回
@@ -2079,10 +2079,12 @@ interface MiniProgramNetworkModule {
  * `data` 仅作为可选调试信息，不保证结构稳定。错误码是跨 Host 的分支契约；
  * `message` 只用于日志和开发者提示，不应作为机器判断条件。
  *
- * 常见处理类别包括：`INVALID_PARAMS`（修正调用参数）、`PERMISSION_NOT_DECLARED`
- * 或 `PERMISSION_DENIED`（检查 Manifest/平台批准）、`USER_GESTURE_REQUIRED`
+ * 常见处理类别包括：`INVALID_PARAMS`（修正调用参数）、`PERMISSION_NOT_IN_SNAPSHOT`
+ *（当前运行快照缺少权限，需发布含声明的新版本或重新打开调试）、
+ * `PERMISSION_DENIED`（检查权限启用状态与平台批准）、`USER_GESTURE_REQUIRED`
  *（改为用户点击后重试）、`AUTHORIZATION_CANCELLED`（结束当前流程），以及
  * `METHOD_FORBIDDEN`（当前 Host 不支持该能力）。具体能力还可能返回模块专属错误码。
+ * 旧 Runtime 仍可能返回 `PERMISSION_NOT_DECLARED`；SDK 会保留 Host 返回的错误码。
  * 不要把所有错误都当作可重试错误，也不要把 `data` 当成稳定的序列化协议。
  *
    * @example
@@ -2490,8 +2492,8 @@ interface MiniProgramAuthModule {
      * 实际授权 scope，不包含用户资料、`app_user_id`、access token、cookie 或应用密钥。
      * @throws {@link HbMiniProgramSDKError} `INVALID_PARAMS`：`scopes` 不是数组、包含未知值或
      * 重复值，或当前 Host 尚未启用请求的 `steam_account` scope。
-     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` 或 `PERMISSION_DENIED`：
-     * 当前版本未声明或不可使用 `userInfo` 权限。
+     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_IN_SNAPSHOT` 或 `PERMISSION_DENIED`：
+     * 当前运行快照缺少或未启用 `userInfo` 权限。
      * @throws {@link HbMiniProgramSDKError} `SERVER_API_REQUIRED`：当前处于无网络的 `local`
      * 模式，不能获取授权码；需要为当前版本启用有效网络权限。
      * @throws {@link HbMiniProgramSDKError} `USER_GESTURE_REQUIRED`：本次需要展示黑盒登录或
@@ -2760,8 +2762,8 @@ interface MiniProgramUserModule {
      *   支持 Steam 账号能力的 Host 还可能返回 `authorization.steam_account` 与
      *   `userInfo.steam_id`；授权与绑定状态应分别判断。
      *
-     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED` 表示
-     * `userInfo` Manifest 权限不可用；`INVALID_STATE` 表示缺少 canonical 小程序身份；
+     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED` 表示
+     * 当前运行快照缺少或未启用 `userInfo` 权限；`INVALID_STATE` 表示缺少 canonical 小程序身份；
      * `REQUEST_FAILED` / `REQUEST_UNSUPPORTED` / `INVALID_RESPONSE` 表示 Host 或资料读取失败；
      * `HEYBOX_APP_LOGIN_REQUIRED` 表示初次登录态检查后，Host 会话在隔离身份读取期间失效；
      * `AUTHORIZATION_CONTEXT_CHANGED` 表示请求期间发生账号切换或授权撤销；
@@ -2906,8 +2908,8 @@ interface MiniProgramUserModule {
      * `data` 为 `null`；两者均为 `true` 时返回游戏列表、`hasMore` 和 `nextOffset`。
      * @throws {@link HbMiniProgramSDKError} `INVALID_PARAMS` 表示存在未知字段，或参数类型、范围
      * 不合法。
-     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED` 表示
-     * `steamLibrary` 未声明或未启用；`METHOD_FORBIDDEN` 表示当前 Host 缺少该能力依赖。
+     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED` 表示
+     * 当前运行快照缺少或未启用 `steamLibrary`；`METHOD_FORBIDDEN` 表示当前 Host 缺少该能力依赖。
      * @throws {@link HbMiniProgramSDKError} `INVALID_STATE` 表示缺少 canonical 小程序身份；
      * `REQUEST_UNSUPPORTED` / `REQUEST_FAILED` / `INVALID_RESPONSE` 表示 Host 请求能力、Steam
      * 请求或响应失败；`HEYBOX_APP_LOGIN_REQUIRED` 表示请求期间 Host 登录态失效。
@@ -3133,13 +3135,21 @@ interface MiniProgramScreenshotRect {
  * 截图分享配置。
  *
  * @remarks
- * 该配置只暴露截图与保存相册相关基础字段，不暴露宿主内部上传、回调或样式扩展能力。
+ * 该配置只暴露截图、保存相册与水印主题字段，不暴露宿主内部上传、回调或其他样式扩展能力。
  * 所有字段均可省略；省略整个配置等同于传入空配置，并在调用时截取当前可见窗口。
  * JavaScript 调用在运行时传入 `null` 也会按空配置处理，但 TypeScript 调用方应直接省略参数。
  *
  * @see {@link MiniProgramShareModule.screenshot | share.screenshot}
  */
 interface MiniProgramScreenshotOptions {
+    /**
+     * 按截图背景选择水印主题：`light` 用于浅色背景，显示黑色胶囊与 40% 黑色说明文字；
+     * `dark` 用于深色背景，显示白色胶囊与 40% 白色说明文字。省略时默认为 `dark`，
+     * 保持现有白色水印效果；不会自动跟随 App 或系统主题。其他值会以 `INVALID_PARAMS` 拒绝。
+     *
+     * @remarks 仅影响水印配色，不改变小程序页面主题；底部仍需预留至少 57 个逻辑像素。
+     */
+    watermarkTheme?: 'light' | 'dark';
     /**
      * 指定截图区域；省略时截取调用时的整个可见窗口。
      *
@@ -3234,8 +3244,8 @@ interface MiniProgramShareModule {
      * `options.extra` 时生成不带扩展数据的链接。
      * @returns Host 完成剪贴板写入后 resolve 的完整分享链接；返回字符串与剪贴板内容一致。
      * @throws {@link HbMiniProgramSDKError} 参数、`extra` 编码或小程序身份不合法时返回
-     * `INVALID_PARAMS`；未声明或未启用 `share` 权限时分别返回
-     * `PERMISSION_NOT_DECLARED` 或 `PERMISSION_DENIED`；当前 Host 未开放剪贴板能力时可返回
+     * `INVALID_PARAMS`；当前运行快照缺少或未启用 `share` 权限时分别返回
+     * `PERMISSION_NOT_IN_SNAPSHOT` 或 `PERMISSION_DENIED`；当前 Host 未开放剪贴板能力时可返回
      * `METHOD_FORBIDDEN` 或 `REQUEST_UNSUPPORTED`。握手、bridge 超时和其他 Host 写入失败会保留
      * 对应错误码。
      *
@@ -3344,8 +3354,8 @@ interface MiniProgramShareModule {
      * trim 后为空，出现自定义 `url`，`imageUrl` 不是 HTTP(S)，`channel` 不在公开枚举内，
      * `extra` 超出编码限制，缺少 canonical 小程序身份/有效当前 URL，或开发态 `post` 无效、
      * 超过一个分区、与 `channel` 冲突。
-     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED` 表示
-     * `share` 权限未声明或未启用；`METHOD_FORBIDDEN` / `METHOD_NOT_FOUND` 表示当前 Host 未开放
+     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED` 表示
+     * 当前运行快照缺少或未启用 `share` 权限；`METHOD_FORBIDDEN` / `METHOD_NOT_FOUND` 表示当前 Host 未开放
      * 分享面板；`REQUEST_UNSUPPORTED` 表示 Host 不支持当前分享参数或渠道。
      * @throws {@link HbMiniProgramSDKError} `RUNTIME_DESTROYED` / `RUNTIME_UNAVAILABLE` /
      * `SDK_DESTROYED` 表示 Runtime、容器或 SDK 已进入终态。SDK 握手失败或 Host 面板调用超时
@@ -3430,8 +3440,8 @@ interface MiniProgramShareModule {
      * 除外），`rect` 不是对象或其坐标、尺寸经 `Number(...)` 转换后不是有效范围，`delay`
      * 转换后不是非负有限数，
      * `saveToAlbum` 不是布尔值，或开发 Runtime 中 `post` 含无效项时以 `INVALID_PARAMS`
-     * 拒绝。未声明或未启用 `share` 权限时分别以
-     * `PERMISSION_NOT_DECLARED`、`PERMISSION_DENIED` 拒绝；当前 Host 未开放截图能力时以
+     * 拒绝。当前运行快照缺少或未启用 `share` 权限时分别以
+     * `PERMISSION_NOT_IN_SNAPSHOT`、`PERMISSION_DENIED` 拒绝；当前 Host 未开放截图能力时以
      * `METHOD_FORBIDDEN` 拒绝，不支持请求形状时可能以 `REQUEST_UNSUPPORTED` 拒绝。握手失败、
      * SDK/Runtime 已销毁、bridge 超时或 Host 截图失败时抛出对应 SDK 错误。用户取消由
      * Host 决定返回不透明结果还是错误，不能依赖统一形态。
@@ -3443,6 +3453,26 @@ interface MiniProgramShareModule {
      * `pixelRatio` 换算，也不把越界矩形夹取到窗口内。JavaScript 的 coercible 非 number 值可能被
      * 当前 Runtime 接受，但这不是 TypeScript 公共合同，不应依赖。
      *
+     * SDK 每次调用都会输出 warning，提醒水印行为变化及布局、配色要求；日志失败不阻断截图。
+     * 新 Runtime 按 Version record 中已校验的 SDK 版本启用水印：低于正式版 `0.9.1`
+     * （包括 `0.9.1-alpha.*`）或兼容模式下版本缺失时，静默保持无水印截图；
+     * `0.9.1` 及以上默认添加水印。升级 SDK 前应同步调整截图布局。
+     *
+     * 启用水印时，Runtime 会在截图区域底部居中叠加「小黑盒 + 搜索图标 + 当前小程序名称」胶囊，
+     * 下方显示灰色「小黑盒工坊小程序」。开发者应在目标截图区域底部预留至少 57 个逻辑
+     * 像素的空白背景，不放置成绩、正文、按钮等重要内容，并保证背景与所选水印配色
+     * 有足够对比度；自定义 `rect` 也按该区域的底部预留。水印不增加图片尺寸，只在本次
+     * SDK 截图期间展示，完成、失败或终止后移除，不常驻业务页面。系统按键截图不属于
+     * 此能力；开发者无需自行绘制水印，也不能通过截图参数关闭水印。
+     *
+     * `watermarkTheme` 按截图背景选择：`light` 用于浅色背景，显示黑色水印；`dark` 用于
+     * 深色背景，显示白色水印。说明文字分别为 40% 黑色或白色。省略时默认为 `dark`，
+     * 不自动跟随 App 或系统主题。该参数由宿主 Runtime 实现，旧 Runtime 可能忽略此字段。
+     *
+     * 截图不受 SDK 普通请求的固定超时限制；排队、延迟和成图等待由 Host 管理，
+     * SDK/Runtime 终止时取消尚未投递的截图。Mobile Host 在延迟结束后才投递原生截图，
+     * 并从投递时起最多等待 15 秒成图回调。已投递原生的截图无法保证撤回。
+     *
      * `delay` 省略时由 Host 使用默认延迟；`saveToAlbum` 省略时由 Host 决定是否提供相册
      * 入口。`post` 会对分区 ID 和话题 trim、规范化及去重。截图分享允许多个分区；开发
      * Runtime 对任一无效项返回 `INVALID_PARAMS`，生产 Runtime 过滤无效项，并在没有有效项
@@ -4099,8 +4129,8 @@ interface MiniProgramCloudLeaderboardModule {
      * @throws {@link HbMiniProgramSDKError} `INVALID_PARAMS`：`options` 不是对象、含未知字段，
      * key 不合法，score 缺失/非有限数字/超出安全范围，或 extra 不是对象、不可 JSON 序列化、
      * 超过 2048 UTF-8 bytes。
-     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`：当前
-     * 版本未声明或未启用 `leaderboard`；`UNAUTHORIZED`：Host 未登录、服务端会话失效，或
+     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`：当前运行快照
+     * 缺少或未启用 `leaderboard`；`UNAUTHORIZED`：Host 未登录、服务端会话失效，或
      * 请求期间登录账号发生变化。
      * @throws {@link HbMiniProgramSDKError} `LEADERBOARD_DEFAULT_NOT_FOUND`：省略 key 但当前
      * 小程序未创建 `default` 榜单；`LEADERBOARD_SUBMIT_LOCKED`：同一用户记录正在被另一提交
@@ -4185,8 +4215,8 @@ interface MiniProgramCloudLeaderboardModule {
      * @returns 当前页 {@link LeaderboardEntry} 数组、可选下一页 cursor 和权威 `hasMore` 标记。
      * @throws {@link HbMiniProgramSDKError} `INVALID_PARAMS`：`options` 不是对象、含未知字段，
      * key 不符合 1 至 64 位 `[A-Za-z0-9_-]`，limit 不是 1 至 100 的整数，或 cursor 不是字符串。
-     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`：当前
-     * 版本未声明或未启用 `leaderboard` 权限。
+     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`：当前运行快照
+     * 缺少或未启用 `leaderboard` 权限。
      * @throws {@link HbMiniProgramSDKError} `LEADERBOARD_DEFAULT_NOT_FOUND`：省略 key 但当前
      * 小程序未创建 `default` 榜单。命名榜单不存在、cursor 失效或后端拒绝时保留服务端错误码。
      * @throws {@link HbMiniProgramSDKError} `INVALID_STATE`：canonical 小程序身份未就绪；
@@ -4269,8 +4299,8 @@ interface MiniProgramCloudLeaderboardModule {
      * 正常空结果。返回记录但 `ranked: false` 时记录仍存在，`rank` 固定为 `0`。
      * @throws {@link HbMiniProgramSDKError} `INVALID_PARAMS`：`options` 不是对象、含 `key` 以外
      * 的字段，或 key 不符合 1 至 64 位 `[A-Za-z0-9_-]` 规则。
-     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`：当前
-     * 版本未声明或未启用 `leaderboard`；`UNAUTHORIZED`：Host 未登录、服务端会话失效，或
+     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`：当前运行快照
+     * 缺少或未启用 `leaderboard`；`UNAUTHORIZED`：Host 未登录、服务端会话失效，或
      * 请求期间登录账号发生变化。
      * @throws {@link HbMiniProgramSDKError} `LEADERBOARD_DEFAULT_NOT_FOUND`：省略 key 但当前
      * 小程序未创建 `default` 榜单。命名榜单不存在或后端拒绝时保留服务端错误码。
@@ -4355,8 +4385,8 @@ interface MiniProgramCloudLeaderboardModule {
      * `deleted: false` 表示调用成功但已无记录，是幂等空结果。
      * @throws {@link HbMiniProgramSDKError} `INVALID_PARAMS`：`options` 不是对象、含 `key` 以外
      * 的字段，或 key 不符合 1 至 64 位 `[A-Za-z0-9_-]` 规则。
-     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`：当前
-     * 版本未声明或未启用 `leaderboard`；`UNAUTHORIZED`：Host 未登录、服务端会话失效，或
+     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`：当前运行快照
+     * 缺少或未启用 `leaderboard`；`UNAUTHORIZED`：Host 未登录、服务端会话失效，或
      * 请求期间登录账号发生变化。
      * @throws {@link HbMiniProgramSDKError} `LEADERBOARD_DEFAULT_NOT_FOUND`：省略 key 但当前
      * 小程序未创建 `default` 榜单。命名榜单不存在或后端拒绝时保留服务端错误码。
@@ -4428,8 +4458,8 @@ interface MiniProgramCloudLeaderboardModule {
      * 和列表展示上限 `rankLimit`。不返回榜单记录或当前用户数据。
      * @throws {@link HbMiniProgramSDKError} `INVALID_PARAMS`：`options` 不是对象、含 `key` 以外
      * 的字段，或 key 不符合 1 至 64 位 `[A-Za-z0-9_-]` 规则。
-     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`：当前
-     * 版本未声明或未启用 `leaderboard` 权限。
+     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`：当前运行快照
+     * 缺少或未启用 `leaderboard` 权限。
      * @throws {@link HbMiniProgramSDKError} `LEADERBOARD_DEFAULT_NOT_FOUND`：省略 key 但当前
      * 小程序未创建 `default` 榜单。命名榜单不存在或后端拒绝时保留服务端错误码。
      * @throws {@link HbMiniProgramSDKError} `INVALID_STATE`：canonical 小程序身份未就绪；
@@ -4646,8 +4676,8 @@ interface CompanionStdio {
      * @throws {@link HbMiniProgramSDKError} stdin 已由 {@link CompanionStdio.closeStdin | closeStdin()}
      * 关闭、Session 不再提供 `stdio` 或通信管道不可用时返回 `COMPANION_PIPE_CLOSED`；进程异常退出
      * 或因输出上限结束时还可能返回 `COMPANION_PROCESS_CRASHED` / `COMPANION_OUTPUT_LIMIT`。
-     * @throws {@link HbMiniProgramSDKError} 未声明或未获批 `companion` 权限时返回
-     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放 `companion.session.write` 时返回
+     * @throws {@link HbMiniProgramSDKError} 当前运行快照缺少或未启用 `companion` 权限时返回
+     * `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`；Host 未开放 `companion.session.write` 时返回
      * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。未知 Host 失败会脱敏并返回
      * `COMPANION_HOST_FAILED`；SDK/Runtime 终止或请求超时还可能返回 `SDK_DESTROYED`、
      * `RUNTIME_UNAVAILABLE`、`REQUEST_TIMEOUT`。
@@ -4748,8 +4778,8 @@ interface CompanionStdio {
      * @throws {@link HbMiniProgramSDKError} stdin 已关闭、Session 不再提供 `stdio` 或通信管道不可用时
      * 可返回 `COMPANION_PIPE_CLOSED`；进程异常退出或因输出上限结束时还可能返回
      * `COMPANION_PROCESS_CRASHED` / `COMPANION_OUTPUT_LIMIT`。
-     * @throws {@link HbMiniProgramSDKError} 未声明或未获批 `companion` 权限时返回
-     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放
+     * @throws {@link HbMiniProgramSDKError} 当前运行快照缺少或未启用 `companion` 权限时返回
+     * `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`；Host 未开放
      * `companion.session.closeStdin` 时返回 `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
      * 未识别的 Host 失败会脱敏为 `COMPANION_HOST_FAILED`；SDK / Runtime 终止、不可用或请求超时还
      * 可能返回 `SDK_DESTROYED`、`RUNTIME_UNAVAILABLE`、`REQUEST_TIMEOUT`。
@@ -5012,8 +5042,8 @@ interface CompanionAttachments {
      * `COMPANION_SESSION_EXITED`；controller 已转移给其他 Runtime generation 时返回
      * `COMPANION_SESSION_OWNERSHIP_LOST`。本地检查与 Host 打开之间存在竞态，Host 会用未公开的
      * controller generation 再次校验当前调用。
-     * @throws {@link HbMiniProgramSDKError} 未声明或未获批 `companion` 权限时返回
-     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放 `companion.openAttachment` 时返回
+     * @throws {@link HbMiniProgramSDKError} 当前运行快照缺少或未启用 `companion` 权限时返回
+     * `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`；Host 未开放 `companion.openAttachment` 时返回
      * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。Host 不支持 Companion 或附件描述符
      * 暂不可用时还可能返回 `COMPANION_UNSUPPORTED` / `COMPANION_DESCRIPTOR_UNAVAILABLE`。
      * @throws {@link HbMiniProgramSDKError} 当前 Runtime session 的 direct handles 已达到 1024 上限时
@@ -5137,8 +5167,8 @@ interface CompanionNotifications {
      * @throws {@link HbMiniProgramSDKError} 当前 Host、操作系统或 Session 无法展示通知时返回
      * `COMPANION_NOTIFICATION_UNAVAILABLE`；Companion 不受支持、进程已异常退出或因输出上限结束时
      * 还可能返回 `COMPANION_UNSUPPORTED`、`COMPANION_PROCESS_CRASHED`、`COMPANION_OUTPUT_LIMIT`。
-     * @throws {@link HbMiniProgramSDKError} 未声明或未获批 `companion` 权限时返回
-     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放 `companion.showNotification` 时返回
+     * @throws {@link HbMiniProgramSDKError} 当前运行快照缺少或未启用 `companion` 权限时返回
+     * `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`；Host 未开放 `companion.showNotification` 时返回
      * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。未知 Host 失败会脱敏为
      * `COMPANION_HOST_FAILED`；SDK / Runtime 终止、不可用或请求超时还可能返回 `SDK_DESTROYED`、
      * `RUNTIME_UNAVAILABLE`、`REQUEST_TIMEOUT`。
@@ -5234,8 +5264,8 @@ interface CompanionSession {
      * `COMPANION_TERMINATE_FAILED` 拒绝；进程已异常退出、因输出上限结束或 Session 状态已变化时还
      * 可能返回 `COMPANION_PROCESS_CRASHED`、`COMPANION_OUTPUT_LIMIT`、
      * `COMPANION_SESSION_EXITED` 等对应稳定 Companion 错误码。
-     * @throws {@link HbMiniProgramSDKError} 未声明或未获批 `companion` 权限时返回
-     * `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`；Host 未开放
+     * @throws {@link HbMiniProgramSDKError} 当前运行快照缺少或未启用 `companion` 权限时返回
+     * `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`；Host 未开放
      * `companion.session.terminate` 时返回 `METHOD_FORBIDDEN`，旧 Runtime 也可能返回
      * `METHOD_NOT_FOUND`。未知 Host 失败会脱敏为 `COMPANION_HOST_FAILED`；SDK / Runtime 已终止、
      * 不可用或请求超时时还可能返回 `SDK_DESTROYED`、`RUNTIME_UNAVAILABLE`、`REQUEST_TIMEOUT`。
@@ -5633,7 +5663,7 @@ interface MiniProgramCompanionModule {
      * 描述符暂不可用或当前 Host 不支持能力时，可能以 `COMPANION_NOT_DECLARED`、
      * `COMPANION_TARGET_UNSUPPORTED`、`COMPANION_PREVIEW_UNSUPPORTED`、
      * `COMPANION_DESCRIPTOR_UNAVAILABLE`、`COMPANION_UNSUPPORTED` 或 `METHOD_FORBIDDEN` 拒绝。
-     * 未声明或未获批 `companion` 权限时分别以 `PERMISSION_NOT_DECLARED`、
+     * 当前运行快照缺少或未启用 `companion` 权限时分别以 `PERMISSION_NOT_IN_SNAPSHOT`、
      * `PERMISSION_DENIED` 拒绝；Host 返回 alias 不匹配、未知 target/capability/source、非法大小
      * 或签名状态时以 `COMPANION_HOST_FAILED` 拒绝。握手失败、SDK/Runtime 已销毁、bridge
      * 超时及其他 Host 失败会保留对应 SDK 错误码。
@@ -5698,7 +5728,7 @@ interface MiniProgramCompanionModule {
      * 描述符暂不可用或 Host 不支持该能力时，可能以 `COMPANION_NOT_DECLARED`、
      * `COMPANION_TARGET_UNSUPPORTED`、`COMPANION_PREVIEW_UNSUPPORTED`、
      * `COMPANION_DESCRIPTOR_UNAVAILABLE`、`COMPANION_UNSUPPORTED` 或 `METHOD_FORBIDDEN` 拒绝。
-     * 未声明或未获批 `companion` 权限时分别以 `PERMISSION_NOT_DECLARED`、
+     * 当前运行快照缺少或未启用 `companion` 权限时分别以 `PERMISSION_NOT_IN_SNAPSHOT`、
      * `PERMISSION_DENIED` 拒绝；Host 返回未知 state、非法进度、非法 `preparedAt` 或失败摘要
      * 时以 `COMPANION_HOST_FAILED` 拒绝。握手失败、SDK/Runtime 已销毁、bridge 超时及其他
      * Host 失败会保留对应 SDK 错误码。
@@ -5785,7 +5815,7 @@ interface MiniProgramCompanionModule {
      * 暂不可用或当前 Host 未开放能力时，可能以 `COMPANION_NOT_DECLARED`、
      * `COMPANION_TARGET_UNSUPPORTED`、`COMPANION_PREVIEW_UNSUPPORTED`、
      * `COMPANION_DESCRIPTOR_UNAVAILABLE`、`COMPANION_UNSUPPORTED` 或 `METHOD_FORBIDDEN` 拒绝。
-     * 未声明或未获批 `companion` 权限时分别以 `PERMISSION_NOT_DECLARED`、
+     * 当前运行快照缺少或未启用 `companion` 权限时分别以 `PERMISSION_NOT_IN_SNAPSHOT`、
      * `PERMISSION_DENIED` 拒绝；Host 返回非法状态、进度或产物描述时以
      * `COMPANION_HOST_FAILED` 拒绝。握手失败、SDK/Runtime 已销毁及其他 bridge 或 Host 失败
      * 会保留对应 SDK 错误码。
@@ -5874,8 +5904,8 @@ interface MiniProgramCompanionModule {
      * @throws {@link HbMiniProgramSDKError} alias 不符合格式时在请求前以 `INVALID_PARAMS`
      * 拒绝；当前审核版本未声明该 alias、目标平台不匹配或 Host 不支持 Companion 时可能以
      * `COMPANION_NOT_DECLARED`、`COMPANION_TARGET_UNSUPPORTED`、`COMPANION_UNSUPPORTED` 或
-     * `METHOD_FORBIDDEN` 拒绝。未声明或未获批 `companion` 权限时分别以
-     * `PERMISSION_NOT_DECLARED`、`PERMISSION_DENIED` 拒绝；握手失败、SDK/Runtime 已销毁、
+     * `METHOD_FORBIDDEN` 拒绝。当前运行快照缺少或未启用 `companion` 权限时分别以
+     * `PERMISSION_NOT_IN_SNAPSHOT`、`PERMISSION_DENIED` 拒绝；握手失败、SDK/Runtime 已销毁、
      * bridge 超时及其他 Host 失败会保留对应 SDK 错误码。
      *
      * @remarks
@@ -5942,7 +5972,7 @@ interface MiniProgramCompanionModule {
      * 当前版本未声明 alias、当前平台没有匹配 target、预览 Host 不支持 Companion 或当前
      * Host 未开放能力时，可能以 `COMPANION_NOT_DECLARED`、`COMPANION_TARGET_UNSUPPORTED`、
      * `COMPANION_PREVIEW_UNSUPPORTED`、`COMPANION_UNSUPPORTED` 或 `METHOD_FORBIDDEN` 拒绝。
-     * 未声明或未获批 `companion` 权限时分别以 `PERMISSION_NOT_DECLARED`、
+     * 当前运行快照缺少或未启用 `companion` 权限时分别以 `PERMISSION_NOT_IN_SNAPSHOT`、
      * `PERMISSION_DENIED` 拒绝；Host 返回非法 Session 快照时以 `COMPANION_HOST_FAILED` 拒绝，
      * 同一 Session ID 的 alias、target 或 capability 集合发生不兼容变化时以
      * `COMPANION_SESSION_VERSION_MISMATCH` 拒绝。握手失败、SDK/Runtime 已销毁及其他 bridge
@@ -6034,8 +6064,8 @@ interface MiniProgramCompanionModule {
      * @throws {@link HbMiniProgramSDKError} alias 不符合格式时在请求前以 `INVALID_PARAMS`
      * 拒绝；当前审核版本未声明 alias、目标平台不匹配或 Host 不支持时可能以
      * `COMPANION_NOT_DECLARED`、`COMPANION_TARGET_UNSUPPORTED`、`COMPANION_UNSUPPORTED` 或
-     * `METHOD_FORBIDDEN` 拒绝。未声明或未获批 `companion` 权限时分别以
-     * `PERMISSION_NOT_DECLARED`、`PERMISSION_DENIED` 拒绝；Host 返回非法 Session 快照时以
+     * `METHOD_FORBIDDEN` 拒绝。当前运行快照缺少或未启用 `companion` 权限时分别以
+     * `PERMISSION_NOT_IN_SNAPSHOT`、`PERMISSION_DENIED` 拒绝；Host 返回非法 Session 快照时以
      * `COMPANION_HOST_FAILED` 拒绝，同一 Session ID 的 alias、target 或 capability 集合发生
      * 不兼容变化时以 `COMPANION_SESSION_VERSION_MISMATCH` 拒绝。握手失败、SDK/Runtime 已
      * 销毁、bridge 超时及其他 Host 失败会保留对应 SDK 错误码。
@@ -6185,8 +6215,8 @@ interface MiniProgramStorageModule {
      * @typeParam T - 调用方期望的反序列化数据类型；SDK 不会在运行时校验该类型。
      * @param options - 读取参数；`options.key` 必须符合 {@link GetStoragePayload.key} 的字符和长度约束。
      * @returns Host 读取完成后 resolve 的结果。合法 JSON 会被反序列化；key 不存在或历史空串返回 `{ data: undefined }`，合法 JSON `null` 返回 `{ data: null }`，历史非 JSON 原始值返回原字符串。
-     * @throws {@link HbMiniProgramSDKError} 参数非法时返回 `INVALID_PARAMS`；未声明或未启用
-     * `storage` 权限时分别返回 `PERMISSION_NOT_DECLARED` 或 `PERMISSION_DENIED`；canonical
+     * @throws {@link HbMiniProgramSDKError} 参数非法时返回 `INVALID_PARAMS`；当前运行快照缺少或未启用
+     * `storage` 权限时分别返回 `PERMISSION_NOT_IN_SNAPSHOT` 或 `PERMISSION_DENIED`；canonical
      * identity 尚未就绪时返回 `INVALID_STATE`；Host 不支持或禁用能力时可返回
      * `METHOD_NOT_FOUND` 或 `METHOD_FORBIDDEN`。其他 bridge 与 Host 读取错误会保留对应错误码。
      *
@@ -6238,9 +6268,9 @@ interface MiniProgramStorageModule {
      * @throws {@link HbMiniProgramSDKError} `INVALID_PARAMS`：`options`、key 或 JSON 数据非法，
      * 包括顶层 `undefined`、`BigInt`、循环引用或序列化过程抛错。
      * @throws {@link HbMiniProgramSDKError} `STORAGE_QUOTA_EXCEEDED`：完整 JSON 字符串的 UTF-8
-     * 字节数超过当前 Host 配额。
-     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`：当前
-     * 版本未声明或未启用 `storage`；`INVALID_STATE`：canonical 小程序身份尚未就绪。
+     * 字节数超过当前 Host 配额，或写入新 key 后当前小程序的不同 key 数量将超过 1000 个。
+     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`：当前运行快照
+     * 缺少或未启用 `storage`；`INVALID_STATE`：canonical 小程序身份尚未就绪。
      * @throws {@link HbMiniProgramSDKError} `METHOD_NOT_FOUND` / `METHOD_FORBIDDEN`：当前 Host
      * 不支持或禁用了该能力。其他握手、bridge、超时与 Host 写入失败会保留对应错误码。
      * @throws `DOMException` 数据含函数、Symbol、自定义 `toJSON` 方法等不可 structured-clone
@@ -6710,8 +6740,8 @@ interface MiniProgramDeviceModule {
      * @returns Host 确认系统剪贴板写入完成后 resolve `undefined`；不会返回或回读剪贴板内容。
      * @throws {@link HbMiniProgramSDKError} `INVALID_PARAMS`：`options` 不是对象、包含 `text`
      * 以外的字段，或 `text` 不是字符串、全为空白、超过 `10000` 个 UTF-16 code units。
-     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`：当前
-     * 版本未声明或未启用 `clipboard` 权限。
+     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`：当前运行快照
+     * 缺少或未启用 `clipboard` 权限。
      * @throws {@link HbMiniProgramSDKError} `METHOD_FORBIDDEN` / `METHOD_NOT_FOUND`：当前 Host
      * 未开放或尚不认识该能力；Host 不支持本次写入形状时可返回 `REQUEST_UNSUPPORTED`。
      * 其他握手、bridge 超时和 Host / 系统剪贴板失败会保留对应错误码。
@@ -6771,8 +6801,8 @@ interface MiniProgramDeviceModule {
      * @throws {@link HbMiniProgramSDKError} `INVALID_PARAMS`：输入既不是非空字符串，也不是带非空
      * 字符串 `protocol_type` 的 JSON 可序列化对象（含函数、`symbol`、`BigInt`、非有限数字或循环
      * 引用时会失败），此时不会产生任何投递。
-     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_DECLARED` / `PERMISSION_DENIED`：当前
-     * 版本未声明 `appProtocol`，或该权限未启用/未获平台批准；不会产生协议副作用。
+     * @throws {@link HbMiniProgramSDKError} `PERMISSION_NOT_IN_SNAPSHOT` / `PERMISSION_DENIED`：当前运行快照
+     * 缺少 `appProtocol`，或该权限未启用/未获平台批准；不会产生协议副作用。
      * @throws {@link HbMiniProgramSDKError} `METHOD_FORBIDDEN` / `METHOD_NOT_FOUND`：当前 Host 未
      * 开放或尚不认识通用协议执行能力；旧 PC Host 属于此分支。Host 明确拒绝的协议也可能映射为
      * 不支持错误。

package/types/miniapp-publish/index.d.ts

@@ -155,6 +155,8 @@ interface MiniappManifest {
     bindAppIds?: readonly string[];
     /** 发布类别；历史读取可缺省，发布校验必须提供。 */
     category?: MiniappCategory;
+    /** 简介，最多 200 个字符；未声明时简介页不展示。 */
+    desc?: string;
 }
 /**
  * 判断小程序版本是否符合公开 Manifest 版本规则。
@@ -211,6 +213,7 @@ declare function isValidMiniappManifestVersion(version: string): boolean;
  * 成功仅表示 Manifest 字段通过校验，不能替代文件检查与服务端发布预检。
  */
 declare function validateMiniappManifestForDeploy(manifest: MiniappManifest): {
+    desc?: string | undefined;
     category?: MiniappCategory | undefined;
     bindAppIds?: readonly string[] | undefined;
     window?: MiniappWindowDeclaration | undefined;