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

package/types/protocol.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 上限时返回
@@ -1993,13 +1993,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';
     /**
      * 指定截图区域；省略时截取调用时的整个可见窗口。
      *

package/types/vite/index.d.ts

@@ -149,6 +149,7 @@ declare const HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN_ENV = "HB_SDK_MINI_PROGR
  *   图片源路径相对项目目录；icon 为 200×200，封面 1–5 张，每张不超过 10 MiB / 4000 万像素。
  *   build 会复制图片到输出目录 `_hb/basic-info/`，并将 Manifest 路径改为生成路径，不改写源图片；
  * - `heybox.category`：`tool`、`game` 或 `other`；构建时允许缺省，发布预检要求提供；
+ * - `heybox.desc`：可选简介，最多 200 个字符，写入 manifest 后在小程序简介页展示；
  * - `heybox.platforms`：项目实际承诺适配的非空、无重复平台 allowlist；输出按平台词表规范排序。
  *   声明仍停留在旧模板移动端默认（`android`、`ios`、`ohos`）时，`serve` 与 `build` 都只输出
  *   一条非阻断提示，不影响构建结果；