@heybox/hb-sdk 0.9.1-alpha.4 → 0.9.1-alpha.5

package/types/protocol.d.ts

@@ -1,9 +1,2083 @@
-export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, DIRECTORY_CREATE_METHOD, DIRECTORY_EXISTS_METHOD, DIRECTORY_LIST_METHOD, DIRECTORY_REMOVE_METHOD, DEVICE_EXECUTE_PROTOCOL_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, FILES_PICK_DIRECTORY_METHOD, FILES_PICK_FILES_METHOD, FILES_SAVE_FILE_METHOD, FILE_CREATE_METHOD, FILE_EXISTS_METHOD, FILE_READ_BYTES_METHOD, FILE_READ_TEXT_METHOD, FILE_REMOVE_METHOD, FILE_STAT_METHOD, FILE_WRITE_BYTES_METHOD, FILE_WRITE_TEXT_METHOD, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_OPERATION_PROGRESS_METHOD, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_METHOD, NETWORK_DOWNLOAD_METHOD, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, SHARE_COPY_LINK_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_INFO_AUTHORIZATION_SCOPES, USER_GET_INFO_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_REVOKE_AUTHORIZATION_METHOD, VIEWPORT_SET_DISPLAY_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, isManagedMiniProgramRuntimePermissionKey, isMiniProgramByteArray, isMiniProgramBridgeMessage, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramPathRootRef, isMiniProgramRelativePath, parseMiniProgramRuntimePermissions, } from '@heybox/hb-sdk-protocol';
-export type { AuthorizedUserInfo, ClosePayload, CloseResult, CopyLinkPayload, CopyLinkResult, DirectoryCreatePayload, DirectoryCreateResult, DirectoryExistsPayload, DirectoryExistsResult, DirectoryListPayload, DirectoryListResult, DirectoryRemovePayload, DirectoryRemoveResult, DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, GetSteamGameListPayload, GetSteamGameListResult, GetStoragePayload, GetStorageResult, GetUserInfoPayload, GetUserInfoResult, MiniProgramOrientationMode, SetDisplayPayload, SetDisplayResult, MiniProgramDisplayState, GetWindowInfoPayload, GetWindowInfoResult, DownloadProgressPayload, HideLoadingPayload, HideLoadingResult, FileCreatePayload, FileCreateResult, FileExistsPayload, FileExistsResult, FileReadBytesPayload, FileReadBytesResult, FileReadTextPayload, FileReadTextResult, FileRemovePayload, FileRemoveResult, FileStatPayload, FileStatResult, FileWriteBytesPayload, FileWriteBytesResult, FileWriteTextPayload, FileWriteTextResult, LeaderboardEntry, LeaderboardOrder, LoginPayload, LoginResult, LoginScope, MiniProgramAuthMethod, MiniProgramBridgeError, MiniProgramBridgeCancelMessage, MiniProgramBridgeMessage, MiniProgramBridgeMessageType, MiniProgramBridgeProgressMessage, MiniProgramBridgeMethod, MiniProgramCapabilityDefinition, MiniProgramCapabilityModule, MiniProgramCapabilityPayload, MiniProgramCapabilityPayloadMap, MiniProgramCapabilityResult, MiniProgramCapabilityResultMap, MiniProgramCapabilityRisk, MiniProgramCloudMethod, MiniProgramDeviceMethod, MiniProgramDirectoryDescriptor, MiniProgramDirectoryMethod, MiniProgramDirectoryRef, MiniProgramDirectDirectoryRef, MiniProgramDirectFileRef, MiniProgramEventName, MiniProgramEventPayloadMap, MiniProgramFileDescriptor, MiniProgramFileMode, MiniProgramFileMethod, MiniProgramFileRef, MiniProgramFilesMethod, MiniProgramFileStat, MiniProgramFileSystemEntityDescriptor, MiniProgramFileSystemEntityRef, MiniProgramPathRootRef, MiniProgramSandboxRootRef, MiniProgramNavigationBarForegroundStyle, MiniProgramNavigationMethod, MiniProgramNetworkHeaders, MiniProgramNetworkMethod, MiniProgramNetworkParams, MiniProgramNetworkRequestMethod, MiniProgramOperatingSystemName, MiniProgramRuntimePermissionEntry, MiniProgramRuntimeEnvironmentInfo, MiniProgramRuntimeMode, MiniProgramRuntimePermissionsSnapshot, MiniProgramRuntimePermissionStatus, MiniProgramSafeArea, MiniProgramScreenshotRect, MiniProgramShareChannel, MiniProgramShareMethod, MiniProgramSharePostOptions, MiniProgramStorageMethod, MiniProgramToastStatus, MiniProgramUiMethod, MiniProgramUserInfoResult, MiniProgramUserMethod, MiniProgramVibrateIntensity, MiniProgramViewportMethod, MiniProgramWindowInfoResult, NetworkRequestPayload, NetworkResponsePayload, NetworkDownloadPayload, NetworkDownloadResult, OpenAppPagePayload, OpenAppPageResult, OpenGameDetailAppPagePayload, OpenMiniProgramAppPagePayload, OpenPostDetailAppPagePayload, OpenUserDetailAppPagePayload, PickDirectoryPayload, PickDirectoryResult, PickFilesPayload, PickFilesResult, ParsedMiniProgramRuntimePermissions, ReloadPayload, ReloadResult, RevokeAuthorizationPayload, RevokeAuthorizationResult, RuntimeLocationProbePayload, ScreenshotPayload, ScreenshotResult, SaveFilePayload, SaveFileResult, SDKCSPBlockedResourceType, SDKCSPViolationPayload, SDKHandshakePayload, SDKHandshakeResult, SDKLocationReportPayload, SDKLocationReportTrigger, SetClipboardPayload, SetClipboardResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, SetStoragePayload, ShowLoadingPayload, ShowLoadingResult, ShowShareMenuPayload, ShowShareMenuResult, ShowToastPayload, ShowToastResult, SteamGameListData, SteamGameListItem, SteamGameListSort, SteamGamePrice, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, UserInfoAuthorization, UserInfoAuthorizationScope, UserInfoAuthorizationStatus, VibratePayload, VibrateResult, } from '@heybox/hb-sdk-protocol';
-export type { LoginOptions } from './modules/auth';
-export type { GetSteamGameListOptions } from './modules/user';
-export type { MiniProgramEventHandler } from './protocol/types';
-export type { DownloadBaseOptions, DownloadOptions, DownloadProgress, MiniProgramNetworkRequestConfig, MiniProgramNetworkResponse, MiniProgramNetworkValidateStatus, } from './modules/network';
-export type { CreateOptions, DirectoryHandle, FileHandle, FileMode, FileStat, FileSystem, FileSystemEntity, FilesModule, ListOptions, PathRoot, PickDirectoryOptions, PickFilesOptions, RemoveOptions, SaveFileOptions, } from './modules/files';
-export type { MiniProgramScreenshotOptions, MiniProgramShowShareMenuOptions } from './modules/share';
-export type { MiniProgramSetNavigationBarStyleOptions } from './modules/viewport';
+import { MiniProgramEventName, MiniProgramEventPayloadMap, LoginScope as LoginScope$1 } from '@heybox/hb-sdk-protocol';
+export { AUTH_LOGIN_METHOD, AuthorizedUserInfo, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, ClosePayload, CloseResult, CopyLinkPayload, CopyLinkResult, DEVICE_EXECUTE_PROTOCOL_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, DIRECTORY_CREATE_METHOD, DIRECTORY_EXISTS_METHOD, DIRECTORY_LIST_METHOD, DIRECTORY_REMOVE_METHOD, DeleteCurrentUserLeaderboardEntryPayload, DeleteCurrentUserLeaderboardEntryResult, DirectoryCreatePayload, DirectoryCreateResult, DirectoryExistsPayload, DirectoryExistsResult, DirectoryListPayload, DirectoryListResult, DirectoryRemovePayload, DirectoryRemoveResult, DownloadProgressPayload, FILES_PICK_DIRECTORY_METHOD, FILES_PICK_FILES_METHOD, FILES_SAVE_FILE_METHOD, FILE_CREATE_METHOD, FILE_EXISTS_METHOD, FILE_READ_BYTES_METHOD, FILE_READ_TEXT_METHOD, FILE_REMOVE_METHOD, FILE_STAT_METHOD, FILE_WRITE_BYTES_METHOD, FILE_WRITE_TEXT_METHOD, FileCreatePayload, FileCreateResult, FileExistsPayload, FileExistsResult, FileReadBytesPayload, FileReadBytesResult, FileReadTextPayload, FileReadTextResult, FileRemovePayload, FileRemoveResult, FileStatPayload, FileStatResult, FileWriteBytesPayload, FileWriteBytesResult, FileWriteTextPayload, FileWriteTextResult, GetCurrentUserLeaderboardEntryPayload, GetCurrentUserLeaderboardEntryResult, GetLeaderboardInfoPayload, GetLeaderboardInfoResult, GetLeaderboardListPayload, GetLeaderboardListResult, GetSteamGameListPayload, GetSteamGameListResult, GetStoragePayload, GetStorageResult, GetUserInfoPayload, GetUserInfoResult, GetWindowInfoPayload, GetWindowInfoResult, HideLoadingPayload, HideLoadingResult, LeaderboardEntry, LeaderboardOrder, LoginPayload, LoginResult, LoginScope, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_OPERATION_PROGRESS_METHOD, MINI_PROGRAM_PROTOCOL_CAPABILITIES, MiniProgramAuthMethod, MiniProgramBridgeCancelMessage, MiniProgramBridgeError, MiniProgramBridgeMessage, MiniProgramBridgeMessageType, MiniProgramBridgeMethod, MiniProgramBridgeProgressMessage, MiniProgramCapabilityDefinition, MiniProgramCapabilityModule, MiniProgramCapabilityPayload, MiniProgramCapabilityPayloadMap, MiniProgramCapabilityResult, MiniProgramCapabilityResultMap, MiniProgramCapabilityRisk, MiniProgramCloudMethod, MiniProgramDeviceMethod, MiniProgramDirectDirectoryRef, MiniProgramDirectFileRef, MiniProgramDirectoryDescriptor, MiniProgramDirectoryMethod, MiniProgramDirectoryRef, MiniProgramDisplayState, MiniProgramEventName, MiniProgramEventPayloadMap, MiniProgramFileDescriptor, MiniProgramFileMethod, MiniProgramFileMode, MiniProgramFileRef, MiniProgramFileStat, MiniProgramFileSystemEntityDescriptor, MiniProgramFileSystemEntityRef, MiniProgramFilesMethod, MiniProgramNavigationBarForegroundStyle, MiniProgramNavigationMethod, MiniProgramNetworkHeaders, MiniProgramNetworkMethod, MiniProgramNetworkParams, MiniProgramNetworkRequestMethod, MiniProgramOperatingSystemName, MiniProgramOrientationMode, MiniProgramPathRootRef, MiniProgramRuntimeEnvironmentInfo, MiniProgramRuntimeMode, MiniProgramRuntimePermissionEntry, MiniProgramRuntimePermissionStatus, MiniProgramRuntimePermissionsSnapshot, MiniProgramSafeArea, MiniProgramSandboxRootRef, MiniProgramScreenshotRect, MiniProgramShareChannel, MiniProgramShareMethod, MiniProgramSharePostOptions, MiniProgramStorageMethod, MiniProgramToastStatus, MiniProgramUiMethod, MiniProgramUserInfoResult, MiniProgramUserMethod, MiniProgramVibrateIntensity, MiniProgramViewportMethod, MiniProgramWindowInfoResult, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_DOWNLOAD_METHOD, NETWORK_REQUEST_METHOD, NetworkDownloadPayload, NetworkDownloadResult, NetworkRequestPayload, NetworkResponsePayload, OpenAppPagePayload, OpenAppPageResult, OpenGameDetailAppPagePayload, OpenMiniProgramAppPagePayload, OpenPostDetailAppPagePayload, OpenUserDetailAppPagePayload, ParsedMiniProgramRuntimePermissions, PickDirectoryPayload, PickDirectoryResult, PickFilesPayload, PickFilesResult, RUNTIME_LOCATION_PROBE_METHOD, ReloadPayload, ReloadResult, RevokeAuthorizationPayload, RevokeAuthorizationResult, RuntimeLocationProbePayload, SDKCSPBlockedResourceType, SDKCSPViolationPayload, SDKHandshakePayload, SDKHandshakeResult, SDKLocationReportPayload, SDKLocationReportTrigger, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_METHOD, SHARE_COPY_LINK_METHOD, SHARE_SCREENSHOT_METHOD, SHARE_SHOW_SHARE_MENU_METHOD, STORAGE_GET_STORAGE_METHOD, STORAGE_SET_STORAGE_METHOD, SaveFilePayload, SaveFileResult, ScreenshotPayload, ScreenshotResult, SetClipboardPayload, SetClipboardResult, SetDisplayPayload, SetDisplayResult, SetNavigationBarStylePayload, SetNavigationBarStyleResult, SetStoragePayload, ShowLoadingPayload, ShowLoadingResult, ShowShareMenuPayload, ShowShareMenuResult, ShowToastPayload, ShowToastResult, SteamGameListData, SteamGameListItem, SteamGameListSort, SteamGamePrice, SubmitLeaderboardEntryPayload, SubmitLeaderboardEntryResult, UI_HIDE_LOADING_METHOD, UI_SHOW_LOADING_METHOD, UI_SHOW_TOAST_METHOD, USER_GET_INFO_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_INFO_AUTHORIZATION_SCOPES, USER_REVOKE_AUTHORIZATION_METHOD, UserInfoAuthorization, UserInfoAuthorizationScope, UserInfoAuthorizationStatus, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_DISPLAY_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, VibratePayload, VibrateResult, isManagedMiniProgramRuntimePermissionKey, isMiniProgramBridgeMessage, isMiniProgramByteArray, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramPathRootRef, isMiniProgramRelativePath, parseMiniProgramRuntimePermissions } from '@heybox/hb-sdk-protocol';
+
+/**
+ * 小程序生命周期或业务事件监听函数。
+ *
+ * @typeParam T - 受
+ * [MiniProgramEventName](/reference/symbols/root/types/MiniProgramEventName) 约束的事件名；它决定
+ * `payload` 的精确类型。
+ * @param payload - 由
+ * [MiniProgramEventPayloadMap](/reference/symbols/root/interfaces/MiniProgramEventPayloadMap) 按 `T`
+ * 索引得到的事件载荷。
+ *
+ * @remarks
+ * handler 在 event bus 派发时同步调用，返回值会被忽略且 Promise 不会被等待。普通事件 handler
+ * 之间没有异常隔离：同步抛错会从当前派发传播，并可能阻止同一事件的后续 handler；异步 handler
+ * 的 rejected Promise 也不会被 SDK 捕获。监听器应在自身边界处理同步和异步错误。
+ *
+ * 生命周期事件不会重放，只派发给事件到达时已经注册的监听器。需要查询当前握手状态时，使用
+ * [getHandshakeState()](/reference/sdk/lifecycle/getHandshakeState) 或
+ * [onHandshakeStateChange()](/reference/sdk/lifecycle/onHandshakeStateChange)。
+ */
+type MiniProgramEventHandler<T extends MiniProgramEventName = MiniProgramEventName> = (payload: MiniProgramEventPayloadMap[T]) => void;
+
+/**
+ * File/Directory 访问模式。
+ *
+ * `read` 允许读取、查询状态和枚举目录；`readwrite` 在此基础上允许创建和写入。
+ * 删除操作仍只对 sandbox 对象开放，外部授权即使为 `readwrite` 也不能删除。
+ */
+type FileMode = 'read' | 'readwrite';
+/**
+ * 用户选择文件时的筛选和授权选项。
+ *
+ * @remarks
+ * 省略 options 或传 `{}` 等同于 `{ mode: 'read', multiple: false }`，且不设置扩展名筛选。
+ * Host 返回的整批文件会先校验数量、结构、名称、mode 和 session 配额，再一次性注册；任一项
+ * 失败都不会保留部分授权。
+ */
+interface PickFilesOptions {
+    /**
+     * 请求的访问模式，默认 `read`。Host 即使授予更高权限也会被 Runtime 收窄为 `read`；请求
+     * `readwrite` 但平台/选择器只能授予只读时返回 `FILE_ACCESS_DENIED`，不会静默降级。外部
+     * File 即使为 `readwrite` 也不能调用 `remove()`。
+     */
+    mode?: FileMode;
+    /**
+     * 传给系统选择器的文件扩展名筛选，例如 `['.json', '.txt', '.tar.gz']`。
+     *
+     * @remarks
+     * 必须是数组；每项匹配 `/^\.[a-z0-9][a-z0-9._-]*$/i`，即以 `.` 和 ASCII 字母/数字开头，
+     * 后续只允许 ASCII 字母、数字、点、下划线或连字符。空串、缺少前导点、路径、通配符、空格
+     * 或 MIME type 会以 `INVALID_PARAMS` 拒绝。重复项在进入 Host 前按首次出现顺序去重。
+     * 该字段只影响系统选择器筛选，不读取或转换文件内容；不需要筛选时应省略。
+     */
+    accept?: string[];
+    /**
+     * 是否允许选择多个文件，默认 `false`。`false` 时成功结果恰好一个；只有显式为 `true` 时
+     * 才接受多个结果，实际数量由系统选择器决定，但成功结果仍至少一个。
+     */
+    multiple?: boolean;
+}
+/**
+ * 用户选择目录时的授权选项。
+ *
+ * @remarks
+ * V1 只接受 `mode`，不支持文件扩展名筛选、多选或建议名称。省略 options、传 `{}` 或省略
+ * `mode` 都请求 `read`。Host 即使返回更高权限也会被 Runtime 收窄到请求模式；请求
+ * `readwrite` 但平台/选择器只授予只读时返回 `FILE_ACCESS_DENIED`，不会静默降级。
+ */
+interface PickDirectoryOptions {
+    /**
+     * 请求的访问模式，默认 `read`。`read` 允许枚举、读取和查询派生目标；`readwrite` 还允许
+     * 创建/写入派生文件与目录，并可把所选目录作为 `network.download()` target。外部授权即使
+     * 为 `readwrite` 也不能调用 `remove()`。
+     */
+    mode?: FileMode;
+}
+/**
+ * 用户选择精确保存目标时的选项。
+ *
+ * @remarks
+ * V1 只接受 `suggestedName`，不支持 `accept`、扩展名筛选、访问模式或 overwrite；返回授权固定
+ * 为 `readwrite`。该名称是提供给 Host 系统保存界面的建议值，跨平台最终文件名以返回
+ * {@link FileHandle.name} 为准。
+ */
+interface SaveFileOptions {
+    /**
+     * 提供给系统选择器的建议文件名。
+     *
+     * @remarks
+     * 必须是非空的单个规范 basename：不能以 `/` 开头或结尾，不能包含 `/`、`\\`、NUL、
+     * U+0000-U+001F / U+007F 控制字符或空 path segment，也不能等于 `.` 或 `..`。例如
+     * `report.json` 合法，`reports/report.json`、`../report.json` 与 `report\\latest.json` 非法并返回
+     * `INVALID_PARAMS`。SDK 不会自动添加或修改扩展名。
+     */
+    suggestedName: string;
+}
+/**
+ * {@link FileHandle.create} / {@link DirectoryHandle.create} 的创建选项。
+ *
+ * @remarks
+ * 两个字段都只接受 boolean，省略 options、传 `{}` 或省略单个字段时均使用 `false`。这些选项只影响
+ * 当前代理所指向的目标：不会把外部 File 授权扩张到父目录或兄弟项，也不会绕过当前代理的 `mode`、
+ * Runtime session、Mini-program identity、`filesystem` 权限或 Host capability 检查。
+ */
+interface CreateOptions {
+    /**
+     * 是否同时创建目标路径中缺失的父目录，默认 `false`。
+     *
+     * `false` 时任一父目录缺失会失败；`true` 时 Host 在当前 sandbox 或已授权目录范围内创建缺失父目录。
+     * 它不改变目标已存在时的处理方式，也不能跨出当前逻辑 root。
+     */
+    recursive?: boolean;
+    /**
+     * 目标已存在时是否失败，默认 `false`。
+     *
+     * `false` 是不破坏内容的 ensure-exists：同类型目标已存在时成功，不清空已有文件。`true` 要求本次
+     * 新建目标，文件或目录已存在时分别返回 `FILE_ALREADY_EXISTS` / `DIRECTORY_ALREADY_EXISTS`。
+     * 该字段只约束最终目标，不要求 `recursive` 创建的父目录也必须全新。
+     */
+    exclusive?: boolean;
+}
+/** 删除目录时的选项。 */
+interface RemoveOptions {
+    /** 是否递归删除目录内容，默认 `false`。 */
+    recursive?: boolean;
+}
+/** 枚举目录直接子项时的选项。 */
+interface ListOptions {
+    /**
+     * 本次最多返回的直接子项数量，默认 `1000`。
+     *
+     * 必须是 `1` 到 `1000`（含）之间的 safe integer。`0`、负数、小数、`NaN`、无穷大或 unsafe
+     * integer 返回 `INVALID_PARAMS`；大于 `1000` 返回 `DIRECTORY_LIST_LIMIT_EXCEEDED`。该字段只是
+     * 单次结果上限，不是 offset、cursor 或递归深度，也没有配套的总数或截断标记。
+     */
+    limit?: number;
+}
+/**
+ * 可同步派生 lazy File/Directory proxy 的逻辑根。
+ *
+ * @remarks
+ * 派生只创建当前 SDK session 内的冻结代理，不执行 I/O，也不暴露宿主真实路径。
+ * 路径在调用时同步校验，后续读写才通过 Host 访问目标。
+ */
+interface PathRoot {
+    /**
+     * 按规范相对路径派生文件代理。
+     *
+     * @param relativePath - 相对于当前逻辑根、使用 `/` 分隔的规范路径。必须是非空字符串，不能以
+     * `/` 开头或结尾，不能包含空 segment、反斜杠、NUL 或其他控制字符；任一 segment 恰为 `.` 或
+     * `..` 都会拒绝，包括整个参数 `'.'`。`.env`、`report..json` 等不等于点段的普通名称可以使用。
+     * @returns 当前 SDK session 内延迟访问目标文件的冻结
+     * [FileHandle](/reference/symbols/root/interfaces/FileHandle)。其 `kind` 固定为 `'file'`，`name` 是
+     * `relativePath` 的末段 basename，`mode` 继承当前逻辑根；因此 `files.sandbox.file()` 返回
+     * `readwrite`，从用户选择目录继续派生时则继承所选目录的 `read` 或 `readwrite`，不能通过子路径
+     * 提升权限。
+     * @throws [HbMiniProgramSDKError](/reference/symbols/root/classes/HbMiniProgramSDKError)
+     * `relativePath` 不是字符串、为空、以 `/` 开头或结尾，包含连续 `/`、任一 `.` / `..` 点段、
+     * 反斜杠或控制字符时，同步抛出 `INVALID_PARAMS`。
+     *
+     * @remarks
+     * 该方法同步校验路径并创建 lazy proxy，不检查文件是否存在或创建文件，不读取内容或元数据，不发送
+     * bridge 请求，也不会打开系统选择器。调用本身因此不需要用户手势，不会触发 Host operation，
+     * 不会占用 `pickFiles()` / `saveFile()` 的 direct handle 配额，也不会暴露宿主真实路径。
+     *
+     * 后续 I/O 才要求在 `package.json#heybox.permissions` 中声明并启用 `filesystem`，并由 Host 开放
+     * 对应 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` 或
+     * `PERMISSION_DENIED`，Host 未开放具体 operation 时返回 `METHOD_FORBIDDEN`；这些错误在调用异步
+     * 方法时发生，不由本方法抛出。
+     *
+     * 代理只表达目标位置。`exists()` 可区分文件缺失或目标实际为目录；`create()` 可显式确保文件存在，
+     * `writeText()` / `writeBytes()` 也可隐式创建目标文件，但不会自动创建缺失的父目录。只读父目录派生
+     * 的文件可以读取与查询，调用 `create()`、写入或删除会返回 `FILE_ACCESS_DENIED`；外部目录派生的
+     * 文件即使是 `readwrite` 也不能删除。
+     *
+     * 若目标是目录或需要先创建父目录，使用
+     * [files.sandbox.directory()](/reference/sdk/files/sandbox/directory)。若要让用户选择现有的精确外部
+     * 文件，使用 [files.pickFiles()](/reference/sdk/files/pickFiles)；若要让用户指定新的精确可写目标，
+     * 使用 [files.saveFile()](/reference/sdk/files/saveFile)。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * // 构造代理时没有 I/O，且不会隐式创建 reports 目录。
+     * const report = hbSDK.files.sandbox.file('reports/latest.json')
+     * console.log(report.kind, report.name, report.mode)
+     * // file, latest.json, readwrite
+     *
+     * await hbSDK.files.sandbox.directory('reports').create({ recursive: true })
+     * await report.writeText(JSON.stringify({ generatedAt: Date.now() }))
+     *
+     * if (await report.exists()) {
+     *   console.log(await report.readText())
+     *   console.log((await report.stat()).size)
+     * }
+     * ```
+     *
+     * @see [files.sandbox.directory()](/reference/sdk/files/sandbox/directory) 派生或创建沙箱目录。
+     * @see [files.pickFiles()](/reference/sdk/files/pickFiles) 通过可信用户操作取得现有外部文件授权。
+     * @see [files.saveFile()](/reference/sdk/files/saveFile) 通过可信用户操作取得精确可写目标。
+     * @see [FileHandle](/reference/symbols/root/interfaces/FileHandle) 查看创建、读写、状态与删除方法。
+     * @see [文件能力与沙箱](/guide/files-and-sandbox) 路径、权限、Host operation 与配额说明。
+     *
+     * @since 0.8.0-alpha.2
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android numeric-dot \>= 1.3.396
+     * @hbClient ios numeric-dot \>= 1.3.396
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
+    file(relativePath: string): FileHandle;
+    /**
+     * 按规范相对路径派生目录代理。
+     *
+     * @param relativePath - 相对于当前逻辑根、使用 `/` 分隔的规范路径。必须是非空字符串，不能以
+     * `/` 开头或结尾，不能包含空 segment、反斜杠、NUL 或其他控制字符。`.` 是仅有的特例：只有
+     * 整个参数等于 `'.'` 时才表示当前逻辑根；`./cache`、`cache/.`、`cache/../secret` 等含点段路径
+     * 不会被折叠或解析，而会直接拒绝。
+     * @returns 当前 SDK session 内延迟访问目标目录的冻结
+     * [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle)。其 `kind` 固定为
+     * `'directory'`，`name` 是末段 basename（传 `'.'` 时为 `'.'`），`mode` 继承当前逻辑根；因此
+     * `files.sandbox.directory()` 返回 `readwrite`，从用户选择目录继续派生时则继承所选目录的
+     * `read` 或 `readwrite`，不能通过子路径提升权限。
+     * @throws [HbMiniProgramSDKError](/reference/symbols/root/classes/HbMiniProgramSDKError)
+     * `relativePath` 不是字符串、为空、以 `/` 开头或结尾，包含连续 `/`、任何 `.` / `..` 点段、
+     * 反斜杠或控制字符时，同步抛出 `INVALID_PARAMS`；完整参数 `'.'` 除外。
+     *
+     * @remarks
+     * 该方法同步校验路径并创建 lazy proxy，不检查目录是否存在或创建目录，不执行文件 I/O，不发送
+     * bridge 请求，也不会打开系统选择器。调用本身因此不需要用户手势，不会触发 Host operation，
+     * 不会占用 picker / `saveFile()` 的 direct handle 配额，也不会暴露宿主真实路径。
+     *
+     * 后续 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 时返回
+     * `METHOD_FORBIDDEN`；这些错误在调用异步方法时发生，不由本方法抛出。
+     *
+     * `files.sandbox.directory('.')` 是沙箱根目录的逻辑代理，可用于 `exists()` 或 `list()`，但不能删除；
+     * 对它调用 `remove()` 会返回 `FILE_ACCESS_DENIED`。普通子目录代理只表达目标位置：需要确保目录
+     * 存在时调用 `create()`，需要观察直接子项时调用 `list()`。若目标是文件，使用
+     * [files.sandbox.file()](/reference/sdk/files/sandbox/file)；若要访问用户选择的外部目录，使用
+     * [files.pickDirectory()](/reference/sdk/files/pickDirectory)。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * // 构造代理时没有 I/O；父目录也不会被隐式创建。
+     * const reports = hbSDK.files.sandbox.directory('reports/2026')
+     * console.log(reports.kind, reports.name, reports.mode)
+     * // directory, 2026, readwrite
+     *
+     * await reports.create({ recursive: true })
+     *
+     * // `.` 只作为完整参数表示沙箱根；它不是可嵌入路径的点段。
+     * const root = hbSDK.files.sandbox.directory('.')
+     * const entries = await root.list({ limit: 100 })
+     * console.log(entries.map(entry => entry.name))
+     * ```
+     *
+     * @see [files.sandbox.file()](/reference/sdk/files/sandbox/file) 派生沙箱文件代理。
+     * @see [files.pickDirectory()](/reference/sdk/files/pickDirectory) 通过可信用户操作取得外部目录授权。
+     * @see [DirectoryHandle](/reference/symbols/root/interfaces/DirectoryHandle) 查看 `create()`、`exists()`、`list()` 与 `remove()`。
+     * @see [文件能力与沙箱](/guide/files-and-sandbox) 路径、权限、Host operation 与配额说明。
+     *
+     * @since 0.8.0-alpha.2
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android numeric-dot \>= 1.3.396
+     * @hbClient ios numeric-dot \>= 1.3.396
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
+    directory(relativePath: string): DirectoryHandle;
+}
+/**
+ * Mini-program 私有 sandbox 的逻辑根。
+ *
+ * @remarks
+ * sandbox 按 Mini-program identity 隔离并由 Host 持久保存；它是逻辑根，不是本机路径。
+ * sandbox 派生对象固定为 `readwrite`，但每次 I/O 仍需已声明 `filesystem` 权限且 Host 支持对应 operation。
+ */
+interface FileSystem extends PathRoot {
+}
+/**
+ * 当前 SDK session 中的文件代理。
+ *
+ * @remarks
+ * 代理是冻结的能力对象，不是原生 `File` 或文件路径。picker / `saveFile()` 返回的精确授权仅在当前
+ * Runtime session 有效；sandbox 或已授权目录派生的逻辑代理不会在创建时执行 I/O。
+ */
+interface FileHandle {
+    /** 可用于区分文件与目录的固定标记。 */
+    readonly kind: 'file';
+    /** 文件 basename，不包含父目录或真实路径。 */
+    readonly name: string;
+    /** 当前代理被授予的访问模式。 */
+    readonly mode: FileMode;
+    /**
+     * 确保文件存在并返回同一个代理。
+     *
+     * @param options - 可选的父目录创建与目标独占创建设置。省略时等同于
+     * `{ recursive: false, exclusive: false }`；完整语义见 {@link CreateOptions}。
+     * @returns 当前同一个 `FileHandle` proxy；成功后 `result === file`。方法不会读取文件，且默认的
+     * 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` 时返回
+     * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
+     * @throws {@link HbMiniProgramSDKError} `recursive: false` 且父目录缺失时返回
+     * `DIRECTORY_NOT_FOUND`；目标实际是目录或路径中的祖先实际是文件时返回 `FILE_TYPE_MISMATCH`；
+     * `exclusive: true` 且文件已存在时返回 `FILE_ALREADY_EXISTS`。
+     * @throws {@link HbMiniProgramSDKError} 外部 direct handle 已失效或不属于当前 Runtime session 时返回
+     * `FILE_ACCESS_REVOKED`；Host 创建失败、响应异常或底层平台 I/O 失败时返回相应稳定文件错误码，
+     * 无法识别的 Host 错误统一为 `FILE_IO_FAILED`。
+     *
+     * @remarks
+     * 目标缺失时创建空文件。`recursive: true` 会在当前逻辑 root 内同时创建缺失父目录；它不会允许
+     * `..`、绝对路径或跨越用户授权边界。目标已是文件时，默认调用作为幂等的 ensure-exists 成功，
+     * 保留原内容；需要检测冲突时传 `exclusive: true`。若目标实际为目录，不会把目录替换为文件。
+     *
+     * 调用要求当前代理的 `mode === 'readwrite'`。sandbox 文件固定继承 `readwrite`；从用户选择的目录
+     * 派生时继承该目录的 `mode`，因此只读目录的后代不能创建。用户选择或 `saveFile()` 返回的精确
+     * 外部 File 也只能在获授 `readwrite` 时调用；操作仍局限于该精确文件，不能取得父目录或兄弟文件。
+     * Runtime 会重新校验 direct handle 的 session/provenance，Host 还会绑定当前 Mini-program identity。
+     * 该方法不需要可信用户手势，也不会创建新的 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 集不完整时 fail closed，不提供 Blob 或内存 fallback。
+     *
+     * `create()` 只创建空目标。父目录已经存在时，{@link FileHandle.writeText} /
+     * {@link FileHandle.writeBytes} 也可隐式创建文件并写入内容；它们不会自动创建父目录。若需要先确保
+     * 目录存在，使用 {@link DirectoryHandle.create}；只需探测目标时使用 {@link FileHandle.exists}。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const report = hbSDK.files.sandbox.file('reports/2026/summary.json')
+     * const sameReport = await report.create({ recursive: true })
+     * console.assert(sameReport === report)
+     *
+     * await report.writeText('{"ready":true}')
+     * await report.create() // 已存在时成功，原内容不变
+     * console.log(await report.readText())
+     *
+     * try {
+     *   await report.create({ exclusive: true })
+     * } catch (error) {
+     *   if (!(error instanceof HbMiniProgramSDKError) || error.code !== 'FILE_ALREADY_EXISTS') throw error
+     * }
+     * ```
+     *
+     * @see {@link CreateOptions}
+     * @see {@link FileHandle.exists}
+     * @see {@link FileHandle.writeText}
+     * @see {@link FileHandle.writeBytes}
+     * @see {@link DirectoryHandle.create}
+     * @see {@link FilesModule.pickDirectory | files.pickDirectory}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/files-and-sandbox | 文件能力与沙箱}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling | 错误处理}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     *
+     * @since 0.8.0-alpha.2
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android numeric-dot \>= 1.3.396
+     * @hbClient ios numeric-dot \>= 1.3.396
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
+    create(options?: CreateOptions): Promise<FileHandle>;
+    /**
+     * 删除当前代理指向的 sandbox 文件。
+     *
+     * @returns Host 完成删除后以 `undefined` resolve；当前 `FileHandle` 代理本身仍可复用，后续可用
+     * {@link FileHandle.exists | exists()} 确认目标已不存在，或用 {@link FileHandle.create | create()}
+     * 在同一位置重新创建文件。
+     * @throws {@link HbMiniProgramSDKError} 代理为只读，或来源是 `pickFiles()`、`saveFile()`、外部
+     * Directory 派生项/枚举项时返回 `FILE_ACCESS_DENIED`；外部授权即使为 `readwrite` 也不能删除。
+     * @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 时返回
+     * `METHOD_FORBIDDEN`，旧 Runtime 不认识该 method 时可返回 `METHOD_NOT_FOUND`。
+     *
+     * @remarks
+     * 该方法只删除一个文件，不接受参数，也不删除目录。可删除对象必须同时来自当前
+     * Mini-program 的 sandbox 且为 `readwrite`；`files.sandbox.file()` 和 sandbox 目录的 `list()`
+     * 结果满足来源约束。若目标是目录，使用 {@link DirectoryHandle.remove}；删除非空目录还需显式
+     * 传入 `{ recursive: true }`。
+     *
+     * `remove()` 不会先调用 `exists()`，也不是幂等的“确保不存在”操作：lazy sandbox 代理可以在
+     * 文件尚不存在时构造，此时调用删除会按 Host 结果抛出缺失错误。即使先由 `exists()` 返回
+     * `true`，目标仍可能在两次异步调用之间变化，因此仍应处理 `FILE_NOT_FOUND` /
+     * `DIRECTORY_NOT_FOUND`。调用不要求可信用户手势，也不占用外部 direct-handle 配额。
+     *
+     * 新 PC Host 支持该操作；Android/iOS `1.3.396+` 和 OHOS 仍以启动时
+     * `system.describe` 宣告的 `files.remove` operation 为准。Web、Browser Dev Host、旧 Host 或
+     * operation 缺失时 fail closed，不提供浏览器文件系统或内存 fallback。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const draft = hbSDK.files.sandbox.file('draft.txt')
+     * await draft.writeText('temporary')
+     *
+     * if (await draft.exists()) {
+     *   await draft.remove()
+     * }
+     * console.log(await draft.exists()) // false
+     *
+     * // 代理仍表示同一个 sandbox 位置，可以重新创建。
+     * await draft.create()
+     * ```
+     *
+     * @see {@link FileHandle.create}
+     * @see {@link FileHandle.exists}
+     * @see {@link DirectoryHandle.remove}
+     * @see [files.sandbox.file()](/reference/sdk/files/sandbox/file) 创建 sandbox 文件代理。
+     * @see [文件能力与沙箱](/guide/files-and-sandbox) 查看来源、平台与错误码边界。
+     */
+    remove(): Promise<void>;
+    /**
+     * 检查当前代理是否仍解析到一个文件。
+     *
+     * @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` 时以
+     * `METHOD_FORBIDDEN` 拒绝，旧 Runtime 也可能返回 `METHOD_NOT_FOUND`。
+     * @throws {@link HbMiniProgramSDKError} picker / `saveFile()` 返回的精确外部授权被撤销、句柄
+     * 不属于当前 Runtime session 或 registry 已释放时，以 `FILE_ACCESS_REVOKED` 拒绝，而不是返回
+     * `false`；SDK 已销毁或 Runtime 已卸载时分别以 `SDK_DESTROYED`、`RUNTIME_UNAVAILABLE` 拒绝。
+     * @throws {@link HbMiniProgramSDKError} Host 拒绝访问、`stat` 探测失败、返回非布尔 bridge 结果
+     * 或发生其他文件 I/O 失败时，以 `FILE_ACCESS_DENIED`、`FILE_IO_FAILED` 或对应 SDK / bridge
+     * 错误拒绝。调用方不应把所有异常都解释为“不存在”。
+     *
+     * @remarks
+     * 这是只读查询，不创建文件、不读取内容、不修改访问模式，也不要求可信用户手势。
+     * `mode: 'read'` 与 `mode: 'readwrite'` 的 {@link FileHandle} 均可调用；但成功返回 `true` 不会
+     * 授予写权限，后续 `create()`、写入或删除仍受当前 mode、来源和 Host operation 限制。
+     *
+     * Runtime 使用 Host 的文件状态原语完成检查，但该布尔结果不是 {@link FileHandle.stat | stat()}
+     * 的缓存或替代品，也不包含大小与时间戳。它只描述本次探测时的状态：目标可能在 resolve 后
+     * 被删除、替换或撤销授权，因此后续 `readText()`、`stat()` 或写入仍可能失败；不要用
+     * `exists()` 作为权限检查或消除并发竞态。
+     *
+     * 对 sandbox lazy proxy，返回 `false` 后可在 `readwrite` 模式下调用
+     * {@link FileHandle.create | create()} 显式确保文件存在；缺失父目录时由 `create({ recursive: true })`
+     * 决定是否一并创建。对 picker / `saveFile()` 的精确外部 FileHandle，授权失效属于错误，不等价于
+     * 文件不存在。若要检查目录，应使用 {@link DirectoryHandle.exists | DirectoryHandle.exists()}，
+     * 目录位于当前文件代理对应位置时本方法返回 `false`。
+     *
+     * 新 PC Host 支持该操作；Android / iOS `1.3.396+` 仅在 `system.describe` 宣告
+     * `files.stat` 时逐项启用，OHOS 同样以 Host 实际协商结果为准。Web、Browser Dev Host、旧 Host
+     * 或缺少该 operation 的环境会 fail closed，不提供浏览器 File / Blob 或内存 fallback；页面应
+     * 处理 `METHOD_FORBIDDEN`，不要仅按操作系统推断可用性。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const report = hbSDK.files.sandbox.file('reports/latest.json')
+     *
+     * try {
+     *   if (!(await report.exists())) {
+     *     await report.create({ recursive: true })
+     *     await report.writeText('{}')
+     *   }
+     *
+     *   // exists() 之后状态仍可能变化，实际读取错误仍需处理。
+     *   console.log(await report.readText())
+     * } catch (error) {
+     *   if (error instanceof HbMiniProgramSDKError && error.code === 'METHOD_FORBIDDEN') {
+     *     showFilesUnsupported()
+     *   } else {
+     *     throw error
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link FileHandle.create | FileHandle.create()} 确保 sandbox 文件存在。
+     * @see {@link FileHandle.stat | FileHandle.stat()} 读取文件大小与 Host 可提供的时间戳。
+     * @see {@link DirectoryHandle.exists | DirectoryHandle.exists()} 检查目录类型的目标。
+     * @see [files.sandbox.file()](/reference/sdk/files/sandbox/file) 创建 sandbox lazy FileHandle。
+     * @see [files.pickFiles()](/reference/sdk/files/pickFiles) 取得当前 session 的精确外部文件授权。
+     * @see [文件能力与沙箱](/guide/files-and-sandbox) 查看权限、平台与 Host operation 说明。
+     *
+     * @since 0.8.0-alpha.2
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android numeric-dot \>= 1.3.396
+     * @hbClient ios numeric-dot \>= 1.3.396
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
+    exists(): Promise<boolean>;
+    /**
+     * 将完整文件按文本读取。
+     *
+     * @returns Runtime 将 Host 返回的完整字节序列按严格 UTF-8 解码后的字符串。空文件返回 `''`；
+     * 换行、NUL 与其他合法 Unicode 内容保持不变。UTF-8 decoder 会剥离第一个开头 BOM；若解码结果
+     * 仍以 `U+FEFF` 开头，Runtime 再移除一个，因此一到两个连续前导 UTF-8 BOM 都不会出现在结果中。
+     * @throws {@link HbMiniProgramSDKError} 文件不是合法 UTF-8 时返回 `FILE_ENCODING_INVALID`，不会用
+     * replacement character 静默替换坏字节。需要无损读取任意二进制或保留 BOM 时使用
+     * {@link FileHandle.readBytes | readBytes()}。
+     * @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 未开放或未协商到
+     * `file.readText` 时返回 `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
+     * @throws {@link HbMiniProgramSDKError} 外部 direct handle 已失效、来自其他或已结束的 Runtime
+     * session 时返回 `FILE_ACCESS_REVOKED`；SDK / Runtime 已终止、调用超时、Host 返回无效内容或底层
+     * I/O 失败时返回 `SDK_DESTROYED`、`RUNTIME_DESTROYED`、`REQUEST_TIMEOUT` 或 `FILE_IO_FAILED` 等
+     * 对应 SDK 错误。
+     *
+     * @remarks
+     * 该方法读取并缓冲整个文件，没有 offset、range、stream、encoding 或 `AbortSignal` 参数。移动端
+     * Host 可以在内部按 chunk 读取，但公开 Promise 只在全部字节读取、复制和 UTF-8 解码完成后 resolve；
+     * 读取失败不会返回部分文本。8 MiB 是 Android/iOS 当前 Host 的原始文件字节上限，不是 JavaScript
+     * 字符串长度限制；新 PC Host 的限制由实际 Host I/O 合同决定。
+     *
+     * `mode: 'read'` 与 `mode: 'readwrite'` 句柄都可以读取，调用不需要可信用户手势，也不会弹出 picker、
+     * 创建文件、修改内容或延长外部授权寿命。picker / `saveFile()` 返回的 direct handle 只在当前
+     * Runtime session 有效；sandbox lazy ref 会在每次调用时按当前 Mini-program identity 解析。
+     * Companion `attachments.open()` 返回的只读 FileHandle 是受控例外：其 `readText()` 由 `companion`
+     * provenance 授权，不额外要求 `filesystem`，但仍受当前 Companion / Runtime session 生命周期约束。
+     *
+     * {@link FileHandle.writeText | writeText()} 执行相反方向的完整 UTF-8 编码与覆盖写入；它不会添加 BOM，
+     * 且要求 `mode === 'readwrite'`。若内容可能不是文本，或业务需要区分 BOM 和文件正文，应使用
+     * {@link FileHandle.readBytes | readBytes()} 获取原始字节并自行解析。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const settings = hbSDK.files.sandbox.file('settings.json')
+     *
+     * try {
+     *   const text = await settings.readText()
+     *   const value = JSON.parse(text)
+     *   console.log(value)
+     * } catch (error) {
+     *   if (error instanceof HbMiniProgramSDKError && error.code === 'FILE_ENCODING_INVALID') {
+     *     // readBytes() 保留原始字节和 BOM，可交给业务自己的格式解析器。
+     *     const bytes = await settings.readBytes()
+     *     console.warn('settings.json 不是 UTF-8', bytes)
+     *   } else if (error instanceof HbMiniProgramSDKError && error.code === 'FILE_NOT_FOUND') {
+     *     await settings.writeText('{}')
+     *   } else {
+     *     throw error
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link FileHandle.readBytes | FileHandle.readBytes()} 无损读取原始字节并保留 BOM。
+     * @see {@link FileHandle.writeText | FileHandle.writeText()} 以 UTF-8 覆盖写入完整字符串。
+     * @see {@link FileHandle.stat | FileHandle.stat()} 在读取前查看文件字节数。
+     * @see [files.pickFiles()](/reference/sdk/files/pickFiles) 取得当前 session 的外部文件授权。
+     * @see [文件能力与沙箱](/guide/files-and-sandbox) 查看权限、平台限制与错误码。
+     */
+    readText(): Promise<string>;
+    /**
+     * 将字符串按 UTF-8 编码后完整写入文件。
+     *
+     * @param content - 要写入的 JavaScript 字符串。必须确实是 `string`；SDK 不会对对象调用
+     * `String()`，也不接受 `Uint8Array`、`Blob`、stream 或 encoding 选项。空字符串合法，会把目标
+     * 替换为空文件。需要精确控制原始字节时使用 {@link FileHandle.writeBytes | writeBytes()}。
+     * @returns Runtime 完成 UTF-8 编码且 Host 的完整写入请求成功后以 `undefined` resolve。移动端会
+     * 等待最后一个带 EOF 的 chunk 获得 Host 响应；该时点不返回写入字节数、文件元数据或新的
+     * `FileHandle`，也不承诺操作系统已执行物理 `fsync`。
+     * @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` 时以
+     * `METHOD_FORBIDDEN` 拒绝，旧 Runtime 也可能返回 `METHOD_NOT_FOUND`。
+     * @throws {@link HbMiniProgramSDKError} 缺失父目录时返回 `DIRECTORY_NOT_FOUND`，路径中的祖先
+     * 或目标类型不匹配时返回 `FILE_TYPE_MISMATCH`。Android / iOS 对一次完整写入的 UTF-8 编码结果
+     * 设 `8 MiB` 上限，超过 `8 * 1024 * 1024` bytes 时返回 `FILE_TOO_LARGE`；该限制按字节而不是
+     * JavaScript 字符数计算。
+     * @throws {@link HbMiniProgramSDKError} 外部 direct handle 被撤销、不属于当前 Runtime session
+     * 或 registry 已释放时返回 `FILE_ACCESS_REVOKED`；SDK 已销毁、Runtime 已卸载、请求超时、Host
+     * 响应异常或底层 I/O 失败时，分别以 `SDK_DESTROYED`、`RUNTIME_UNAVAILABLE`、
+     * `REQUEST_TIMEOUT`、`FILE_IO_FAILED` 或对应稳定文件错误码拒绝。
+     *
+     * @remarks
+     * Runtime 使用标准 `TextEncoder` 把完整字符串编码为不带 BOM 的 UTF-8，再调用 Host 的完整文件
+     * 写原语。该方法不是 append、range write 或 stream：已有文件内容会被本次编码结果整体替换，
+     * 写入 `''` 会把文件截断为零字节。若 Host 在写入中途失败，Promise 会拒绝；公开合同不承诺失败
+     * 时回滚旧内容或提供跨进程原子替换，需要事务语义时应由业务使用临时文件和自己的提交协议。
+     *
+     * 目标文件本身不存在时可以隐式创建，因此通常不需要先调用
+     * {@link FileHandle.create | create()}；但父目录必须已经存在，`writeText()` 不会递归创建目录。
+     * 需要创建父目录时先调用 {@link DirectoryHandle.create | DirectoryHandle.create()}，或对文件调用
+     * `create({ recursive: true })`。不要用 `exists()` 后再写来消除竞态：目标可能在两次异步调用之间
+     * 变化，实际写入错误仍应处理。
+     *
+     * 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
+     * 会在本地 mode 检查时以 `FILE_ACCESS_DENIED` 拒绝。该方法不需要新的可信用户手势；只有最初
+     * 获取外部授权的 picker / `saveFile()` 需要手势。
+     *
+     * 新 PC Host 支持该操作；Android / iOS `1.3.396+` 仅在 `system.describe` 同时宣告
+     * `files.openWrite`、`files.write`、`files.release` 时逐项启用，OHOS 同样以 Host 实际协商结果为准。
+     * Web、Browser Dev Host、旧 Host 或 operation 集不完整时 fail closed，不提供浏览器 File / Blob
+     * 或内存 fallback。新 PC Host 的大小限制由实际 Host 合同决定，不应套用移动端 8 MiB 上限。
+     *
+     * {@link FileHandle.readText | readText()} 可按严格 UTF-8 读取完整内容，但会移除前导 BOM；写入后
+     * 仍可能因为外部修改、授权撤销或 Session 结束而读取失败。需要检查最终字节数或时间戳时，在
+     * 写入成功后另行调用 {@link FileHandle.stat | stat()}。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const reports = hbSDK.files.sandbox.directory('reports')
+     * await reports.create({ recursive: true })
+     *
+     * const report = reports.file('latest.txt')
+     * await report.writeText('第一版\n') // 文件不存在时隐式创建。
+     *
+     * try {
+     *   await report.writeText('第二版\n') // 完整替换，不会追加到第一版后面。
+     *   console.log(await report.readText()) // 第二版
+     * } catch (error) {
+     *   if (error instanceof HbMiniProgramSDKError && error.code === 'FILE_TOO_LARGE') {
+     *     console.warn('文本的 UTF-8 编码结果超过当前平台上限')
+     *   } else {
+     *     throw error
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link FileHandle.readText | FileHandle.readText()} 按严格 UTF-8 读取完整文件。
+     * @see {@link FileHandle.writeBytes | FileHandle.writeBytes()} 写入调用方提供的原始字节。
+     * @see {@link FileHandle.create | FileHandle.create()} 显式确保文件和可选父目录存在。
+     * @see {@link FileHandle.stat | FileHandle.stat()} 在写入后读取文件大小与时间戳。
+     * @see {@link DirectoryHandle.create | DirectoryHandle.create()} 先创建缺失父目录。
+     * @see [files.pickFiles()](/reference/sdk/files/pickFiles) 取得可选的精确外部文件写授权。
+     * @see [files.saveFile()](/reference/sdk/files/saveFile) 让用户指定新的精确可写目标。
+     * @see [文件能力与沙箱](/guide/files-and-sandbox) 查看路径、权限、平台与配额边界。
+     *
+     * @since 0.8.0-alpha.2
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android numeric-dot \>= 1.3.396
+     * @hbClient ios numeric-dot \>= 1.3.396
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
+    writeText(content: string): Promise<void>;
+    /**
+     * 将完整文件读取为新的字节数组。
+     *
+     * @returns 包含完整文件原始字节的新 `Uint8Array`。空文件返回长度为 `0` 的数组。Runtime 会先
+     * 复制 Host 字节，SDK 验证 bridge 结果后再创建当前可见区间的副本，因此返回值不与 Host / bridge
+     * 响应共享可变存储；修改数组只改变调用方的本地副本，不会写回文件。
+     * @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 未开放或未协商到
+     * `file.readBytes` 时返回 `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
+     * @throws {@link HbMiniProgramSDKError} 外部 direct handle 被撤销、不属于当前或已结束的 Runtime
+     * session 时返回 `FILE_ACCESS_REVOKED`；Host 拒绝底层授权时也可能返回 `FILE_ACCESS_DENIED`。
+     * 握手失败、SDK / Runtime 已终止或不可用、调用超时、Host 返回非字节结果或底层 I/O 失败时，返回
+     * `HANDSHAKE_FAILED`、`SDK_DESTROYED`、`RUNTIME_DESTROYED`、`RUNTIME_UNAVAILABLE`、
+     * `REQUEST_TIMEOUT`、`FILE_IO_FAILED` 或对应稳定文件错误码。
+     *
+     * @remarks
+     * 该方法读取并缓冲整个文件，不提供 offset、range、stream、encoding、进度回调或 `AbortSignal`
+     * 参数。移动端 Host 可以在内部按 chunk 拉取，但公开 Promise 只在全部字节读取并复制完成后 resolve；
+     * 失败不会返回部分数组。8 MiB 是 Android / iOS 当前 Host 的原始文件字节上限，恰好等于上限允许；
+     * 新 PC Host 的限制由实际 Host I/O 合同决定。
+     *
+     * `readBytes()` 不解释内容格式：UTF-8 BOM、无效 UTF-8、NUL、压缩数据和图片头都会原样保留，也不会
+     * 因文本编码返回 `FILE_ENCODING_INVALID`。需要严格 UTF-8 字符串并移除前导 BOM 时使用
+     * {@link FileHandle.readText | readText()}；需要把修改后的字节完整覆盖回文件时使用
+     * {@link FileHandle.writeBytes | writeBytes()}。
+     *
+     * `mode: 'read'` 与 `mode: 'readwrite'` 句柄都可以读取，调用不需要可信用户手势，也不会弹出 picker、
+     * 创建文件、修改内容或延长外部授权寿命。picker / `saveFile()` 返回的 direct handle 只在当前
+     * Runtime session 有效；sandbox lazy ref 会在每次调用时按当前 Mini-program identity 解析。
+     * Companion `attachments.open()` 返回的只读 FileHandle 是受控例外：其 `readBytes()` 由 `companion`
+     * provenance 授权，不额外要求 `filesystem`，但仍受当前 Companion / Runtime session 生命周期约束。
+     *
+     * 新 PC Host 支持该操作；Android / iOS `1.3.396+` 仅在 `system.describe` 同时宣告
+     * `files.openRead`、`files.read`、`files.release` 时逐项启用，OHOS 同样以 Host 实际协商结果为准。
+     * Web、Browser Dev Host 的普通 sandbox / picker 路径、旧 Host 或 operation 集不完整时 fail closed，
+     * 不提供浏览器 File / Blob、内存 fallback 或自动分段的公开 API；前述 Companion attachment 仍按
+     * 自身受控 provenance 判断。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const avatar = hbSDK.files.sandbox.file('avatar.png')
+     *
+     * try {
+     *   const bytes = await avatar.readBytes()
+     *   const isPng =
+     *     bytes.length >= 4 &&
+     *     bytes[0] === 0x89 &&
+     *     bytes[1] === 0x50 &&
+     *     bytes[2] === 0x4e &&
+     *     bytes[3] === 0x47
+     *
+     *   console.log({ isPng, size: bytes.byteLength })
+     *   bytes[0] = 0 // 只修改本地副本，不会写回 avatar.png
+     * } catch (error) {
+     *   if (error instanceof HbMiniProgramSDKError && error.code === 'FILE_TOO_LARGE') {
+     *     console.warn('请改用业务分片格式，或避免把大文件一次读入内存')
+     *   } else {
+     *     throw error
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link FileHandle.readText | FileHandle.readText()} 严格按 UTF-8 解码并处理前导 BOM。
+     * @see {@link FileHandle.writeBytes | FileHandle.writeBytes()} 完整覆盖写入原始字节。
+     * @see {@link FileHandle.stat | FileHandle.stat()} 在完整读取前查看文件字节数。
+     * @see [files.pickFiles()](/reference/sdk/files/pickFiles) 取得当前 session 的外部文件授权。
+     * @see [文件能力与沙箱](/guide/files-and-sandbox) 查看权限、平台限制与错误码。
+     */
+    readBytes(): Promise<Uint8Array>;
+    /**
+     * 将原始字节完整写入文件。
+     *
+     * @param content - 要写入的 `Uint8Array`。SDK 在调用时只复制该 view 的当前可见字节区间；不会把
+     * `byteOffset` 之前或 `byteLength` 之后的 backing `ArrayBuffer` 内容一并写入。调用返回 Promise 后
+     * 再修改原数组不会改变本次写入。空数组合法，会把目标替换为零字节文件。
+     * @returns SDK 与 Runtime 完成输入复制且 Host 的完整写入请求成功后以 `undefined` resolve。移动端
+     * 会等待最后一个带 EOF 的 chunk 获得 Host 响应；该时点不返回写入字节数、文件元数据或新的
+     * `FileHandle`，也不承诺操作系统已执行物理 `fsync`。
+     * @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` 时返回
+     * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
+     * @throws {@link HbMiniProgramSDKError} 缺失父目录时返回 `DIRECTORY_NOT_FOUND`，路径中的祖先或
+     * 目标类型不匹配时返回 `FILE_TYPE_MISMATCH`。Android / iOS 对一次完整写入设 8 MiB 上限；当前
+     * view 的 `byteLength` 超过 `8 * 1024 * 1024` 时返回 `FILE_TOO_LARGE`。
+     * @throws {@link HbMiniProgramSDKError} 外部 direct handle 被撤销、不属于当前 Runtime session 或
+     * registry 已释放时返回 `FILE_ACCESS_REVOKED`；SDK 已销毁、Runtime 已卸载、请求超时、Host 响应
+     * 异常或底层 I/O 失败时，返回 `SDK_DESTROYED`、`RUNTIME_UNAVAILABLE`、`REQUEST_TIMEOUT`、
+     * `FILE_IO_FAILED` 或对应稳定文件错误码。
+     *
+     * @remarks
+     * SDK 会在调用同步阶段执行第一次防御性复制，Runtime 收到 payload 后再复制一次，再把独立的
+     * `Uint8Array` 交给 Host。因此本次写入只观察调用时 view 中的字节，不与调用方继续共享可变
+     * `ArrayBuffer`。`SharedArrayBuffer` backing 会被明确拒绝，不能借此建立跨 bridge 共享内存。
+     *
+     * 这是完整文件写入，不是 append、range write 或 stream：已有内容会被本次字节序列整体替换，
+     * 写入空数组会截断为零字节。若 Host 在写入中途失败，Promise 会拒绝；公开合同不承诺失败时
+     * 回滚旧内容或提供跨进程原子替换，需要事务语义时应由业务使用临时文件和自己的提交协议。
+     *
+     * 目标文件不存在时可以隐式创建，但父目录必须已经存在，`writeBytes()` 不会递归创建目录。
+     * 需要创建父目录时先调用 {@link DirectoryHandle.create | DirectoryHandle.create()}，或对文件调用
+     * `create({ recursive: true })`。不必先用 `exists()` 检查文件；该检查也不能消除两次异步调用之间
+     * 的状态竞态，实际写入错误仍应处理。
+     *
+     * 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`。该方法不需要新的
+     * 可信用户手势；只有最初取得外部授权的 picker / `saveFile()` 需要手势。
+     *
+     * 新 PC Host 支持该操作；Android / iOS `1.3.396+` 仅在 `system.describe` 同时宣告
+     * `files.openWrite`、`files.write`、`files.release` 时逐项启用，OHOS 同样以 Host 实际协商结果
+     * 为准。Web、Browser Dev Host、旧 Host 或 operation 集不完整时 fail closed，不提供浏览器
+     * File / Blob 或内存 fallback。新 PC Host 的大小限制由实际 Host 合同决定，不应套用移动端
+     * 8 MiB 上限。
+     *
+     * {@link FileHandle.readBytes | readBytes()} 返回完整文件的独立字节副本；
+     * {@link FileHandle.writeText | writeText()} 则先把字符串编码成不带 BOM 的 UTF-8，再执行相同的
+     * 完整替换语义。需要检查写入后的最终大小或时间戳时，成功后另行调用
+     * {@link FileHandle.stat | stat()}。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const file = hbSDK.files.sandbox.file('header.bin')
+     * const backing = new Uint8Array([0xff, 0x89, 0x50, 0x4e, 0x47, 0xff])
+     * const visible = backing.subarray(1, 5)
+     *
+     * const writing = file.writeBytes(visible)
+     * visible.fill(0) // 不影响 writeBytes() 已取得的快照。
+     * await writing
+     *
+     * console.log([...await file.readBytes()]) // [137, 80, 78, 71]
+     * await file.writeBytes(new Uint8Array()) // 完整替换为空文件。
+     * ```
+     *
+     * @see {@link FileHandle.readBytes | FileHandle.readBytes()} 读取独立的原始字节副本。
+     * @see {@link FileHandle.writeText | FileHandle.writeText()} 以 UTF-8 写入完整字符串。
+     * @see {@link FileHandle.create | FileHandle.create()} 显式确保文件和可选父目录存在。
+     * @see {@link FileHandle.stat | FileHandle.stat()} 在写入后读取文件大小与时间戳。
+     * @see {@link DirectoryHandle.create | DirectoryHandle.create()} 先创建缺失父目录。
+     * @see [files.pickFiles()](/reference/sdk/files/pickFiles) 取得可选的精确外部文件写授权。
+     * @see [files.saveFile()](/reference/sdk/files/saveFile) 让用户指定新的精确可写目标。
+     * @see [文件能力与沙箱](/guide/files-and-sandbox) 查看路径、权限、平台与错误码边界。
+     */
+    writeBytes(content: Uint8Array): Promise<void>;
+    /**
+     * 读取当前文件的元数据快照。
+     *
+     * @returns 新建的 {@link FileStat} 对象：`kind` 固定为 `'file'`，`size` 是 `0` 到
+     * `Number.MAX_SAFE_INTEGER` 的整数；Host 提供时还包含相互独立、非负有限数值的
+     * `modifiedAt` / `createdAt`。返回对象不是 `FileHandle`，也不会包含真实路径、内容或 Host 的额外字段。
+     * @throws {@link HbMiniProgramSDKError} 目标文件或任一祖先不存在时返回 `FILE_NOT_FOUND` /
+     * `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` 时返回
+     * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。Companion attachment 是受控例外：
+     * 它使用已启用的 `companion` 授权读取自身元数据，不要求另行声明 `filesystem`。
+     * @throws {@link HbMiniProgramSDKError} Host 返回非对象、错误的 `kind`，负数/小数/unsafe `size`，
+     * 或负数、非有限数值的时间戳时返回 `FILE_IO_FAILED`；未知 Host 错误和无法识别的响应同样规范为
+     * `FILE_IO_FAILED`。SDK 已销毁、Runtime 已卸载或请求超时时还可能返回 `SDK_DESTROYED`、
+     * `RUNTIME_UNAVAILABLE`、`REQUEST_TIMEOUT`。
+     *
+     * @remarks
+     * 这是只读操作，`mode: 'read'` 与 `mode: 'readwrite'` 均可调用，不要求可信用户手势，也不会读取
+     * 文件内容、创建文件、更新时间戳或占用新的 direct-handle 配额。Runtime 会重新校验 ref 的类型、
+     * 当前 session/provenance 与 Mini-program identity；通过结构校验不等于可以跨 session 复用句柄。
+     *
+     * 每次调用都会发送新的 `file.stat` 请求，并返回与 Host 响应分离的新对象；SDK 不缓存、冻结或持续
+     * 更新该对象。修改返回对象不会影响文件或后续结果，文件也可能在 Promise resolve 后立即被外部进程
+     * 修改、替换或删除。因此它只描述本次 Host 查询的快照，不能与之前的 `exists()` 或之后的
+     * `readText()` / `readBytes()` 组成原子检查。
+     *
+     * `size` 的公开约定单位是 byte，`modifiedAt` / `createdAt` 的公开约定单位是 Unix epoch
+     * milliseconds；但 Runtime 只能验证数值结构，不能证明 Host 使用了正确单位、时间来自文件系统或
+     * `size` 与稍后读取的内容仍一致。时间戳可分别缺失，也不要求为整数/safe integer、落在 JavaScript
+     * `Date` 可表示范围内、`createdAt <= modifiedAt` 或不晚于当前时间；用于排序和日期展示前应按业务范围
+     * 继续校验。
+     *
+     * 与 {@link FileHandle.exists | exists()} 不同，`stat()` 不会把缺失祖先、缺失目标或 kind mismatch
+     * 归一为 `false`，而会以对应错误拒绝。与 {@link FileHandle.readText | readText()} /
+     * {@link FileHandle.readBytes | readBytes()} 不同，它只读取元数据，不传输文件 body；Android/iOS 的
+     * 8 MiB 单次完整内容读写上限不限制可报告的 `size`，但 `size` 仍不能超过
+     * `Number.MAX_SAFE_INTEGER`。
+     *
+     * 新 PC Host 支持该 operation；Android/iOS `1.3.396+` 仅在 `system.describe` 宣告
+     * `files.stat` 时逐项启用，OHOS 同样以 Host 实际协商结果为准。Web、Browser Dev Host、旧 Host
+     * 或缺少该 operation 的环境会 fail closed，不提供浏览器 File / Blob 或内存 fallback。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const report = hbSDK.files.sandbox.file('reports/latest.json')
+     *
+     * // exists() 只用于快速分支；文件仍可能在下一次异步调用前变化。
+     * if (await report.exists()) {
+     *   try {
+     *     const stat = await report.stat()
+     *     console.log(`${stat.size} bytes`)
+     *
+     *     if (stat.modifiedAt !== undefined) {
+     *       const modifiedAt = new Date(stat.modifiedAt)
+     *       if (!Number.isNaN(modifiedAt.getTime())) console.log(modifiedAt.toISOString())
+     *     }
+     *   } catch (error) {
+     *     if (!(error instanceof HbMiniProgramSDKError) || error.code !== 'FILE_NOT_FOUND') throw error
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link FileStat}
+     * @see {@link FileHandle.exists}
+     * @see {@link FileHandle.readText}
+     * @see {@link FileHandle.readBytes}
+     * @see [files.sandbox.file()](/reference/sdk/files/sandbox/file) 创建 sandbox lazy FileHandle。
+     * @see [files.pickFiles()](/reference/sdk/files/pickFiles) 取得当前 session 的精确外部文件授权。
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/files-and-sandbox | 文件能力与沙箱}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling | 错误处理}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     *
+     * @since 0.8.0-alpha.2
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android numeric-dot \>= 1.3.396
+     * @hbClient ios numeric-dot \>= 1.3.396
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
+    stat(): Promise<FileStat>;
+}
+/**
+ * 当前 SDK session 中的目录代理。
+ *
+ * @remarks
+ * 目录既能执行目录操作，也是派生子 File/Directory 逻辑代理的根。派生代理继承目录的 `mode`，
+ * 不能通过子路径提升授权范围。
+ */
+interface DirectoryHandle extends PathRoot {
+    /** 可用于区分文件与目录的固定标记。 */
+    readonly kind: 'directory';
+    /** 目录 basename，不包含父目录或真实路径。 */
+    readonly name: string;
+    /** 当前代理及其派生项被授予的访问模式。 */
+    readonly mode: FileMode;
+    /**
+     * 确保目录存在并返回同一个代理。
+     *
+     * @param options - 可选的父目录创建与目标独占创建设置。省略时等同于
+     * `{ recursive: false, exclusive: false }`；完整语义见 {@link CreateOptions}。
+     * @returns Host 确认目录存在后返回当前同一个 `DirectoryHandle` proxy；成功后
+     * `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` 时返回
+     * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
+     * @throws {@link HbMiniProgramSDKError} `recursive: false` 且任一父目录缺失时返回
+     * `DIRECTORY_NOT_FOUND`；目标实际是文件或路径中的祖先实际是文件时返回 `FILE_TYPE_MISMATCH`；
+     * `exclusive: true` 且目录已存在时返回 `DIRECTORY_ALREADY_EXISTS`。
+     * @throws {@link HbMiniProgramSDKError} 外部 direct handle 已失效、伪造或不属于当前 Runtime session
+     * 时返回 `FILE_ACCESS_REVOKED`；Host 创建失败或底层平台 I/O 失败时返回相应稳定文件错误码，
+     * 无法识别的 Host 错误统一为 `FILE_IO_FAILED`。SDK / Runtime 终止或请求超时还可能返回
+     * `SDK_DESTROYED`、`RUNTIME_DESTROYED`、`RUNTIME_UNAVAILABLE` 或 `REQUEST_TIMEOUT`。
+     *
+     * @remarks
+     * 目标缺失时创建空目录。`recursive: true` 会在当前逻辑 root 内同时创建缺失父目录；它不会允许
+     * `..`、绝对路径或越过 sandbox / 用户选择目录的授权边界。目标已是目录时，默认调用作为幂等的
+     * ensure-exists 成功，不删除、清空或重新创建其中内容；需要检测最终目标冲突时传
+     * `exclusive: true`。`exclusive` 只约束最终目录，`recursive` 创建的父目录可以已经存在。
+     * 若同一位置实际是文件，则不会把文件替换为目录。
+     *
+     * 调用要求当前代理的 `mode === 'readwrite'`。sandbox 目录固定继承 `readwrite`；从
+     * `files.pickDirectory({ mode: 'readwrite' })` 返回的外部目录派生后代时也可在该授权范围内创建，
+     * 但默认 `read` 的选择结果及其后代会在本地 mode 检查时拒绝。创建不会扩大授权到所选目录之外，
+     * 也不会让外部目录获得 `remove()` 权限；外部 direct handle 及其后代仍只在当前 Runtime session
+     * 有效。Runtime 会重新校验 direct handle 的 provenance，Host 还会绑定当前 Mini-program identity。
+     *
+     * 该方法要求 `package.json#heybox.permissions` 已声明并启用 `filesystem`，但不要求新的可信用户
+     * 手势；只有最初调用 `pickDirectory()` 取得外部授权时需要用户操作。它不占用新的外部 direct-handle
+     * 配额，也不暴露 Host 真实路径。
+     *
+     * 新 PC Host 支持该 operation；Android / iOS 需要 `1.3.396+` 并以 `system.describe` 实际宣告的
+     * operation 集为准，OHOS 同样按 Host 协商结果启用。Web、Browser Dev Host、旧 Host 或 operation
+     * 集不完整时 fail closed，不提供浏览器文件系统、OPFS 或内存 fallback。
+     *
+     * 创建目录后，可用当前代理的 {@link PathRoot.file | file()} / {@link PathRoot.directory | directory()}
+     * 同步派生后代代理，并用 {@link DirectoryHandle.list | list()} 枚举直接子项；派生与枚举结果继承
+     * 当前目录的 mode。若最终目标应是文件，使用 {@link FileHandle.create}；它复用同一组
+     * `recursive` / `exclusive` 选项，但独占冲突返回 `FILE_ALREADY_EXISTS`。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const reports = hbSDK.files.sandbox.directory('exports/2026')
+     * const sameReports = await reports.create({ recursive: true })
+     * console.assert(sameReports === reports)
+     *
+     * const summary = reports.file('summary.json')
+     * await summary.create()
+     * await summary.writeText('{"ready":true}')
+     * console.log((await reports.list()).map(entry => entry.name))
+     *
+     * try {
+     *   await reports.create({ exclusive: true })
+     * } catch (error) {
+     *   if (!(error instanceof HbMiniProgramSDKError) || error.code !== 'DIRECTORY_ALREADY_EXISTS') throw error
+     * }
+     * ```
+     *
+     * @see {@link CreateOptions}
+     * @see {@link FileHandle.create}
+     * @see {@link DirectoryHandle.exists}
+     * @see {@link DirectoryHandle.list}
+     * @see {@link FilesModule.pickDirectory | files.pickDirectory}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/files-and-sandbox | 文件能力与沙箱}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling | 错误处理}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     */
+    create(options?: CreateOptions): Promise<DirectoryHandle>;
+    /**
+     * 删除当前代理指向的 sandbox 目录。
+     *
+     * @param options - 可选删除配置。省略 options、传 `{}` 或省略 `recursive` 都等同于
+     * `{ recursive: false }`；此时只允许删除空目录。`recursive` 必须是 boolean，非对象 options、
+     * 数组或其他类型会以 `INVALID_PARAMS` 拒绝。
+     * @returns Host 报告目标目录删除完成后以 `undefined` resolve。不返回删除的子项数量、原目录
+     * 内容或新的 handle；当前 `DirectoryHandle` 仍是同一逻辑位置的代理，可继续调用
+     * {@link DirectoryHandle.exists | exists()} 或 {@link DirectoryHandle.create | create()}。
+     * @throws {@link HbMiniProgramSDKError} 当前代理不是 `readwrite`，来源是 `pickDirectory()` 返回的
+     * 外部目录，或从外部目录派生/枚举得到时，在发送 bridge 请求前以 `FILE_ACCESS_DENIED` 拒绝。
+     * 外部目录授权即使为 `readwrite` 也不能删除其自身或任何后代。
+     * @throws {@link HbMiniProgramSDKError} 删除 `files.sandbox.directory('.')` 表示的 sandbox 根目录时
+     * 以 `FILE_ACCESS_DENIED` 拒绝；`recursive: true` 也不能绕过该边界。目标目录非空且
+     * `recursive` 为默认的 `false` 时返回 `DIRECTORY_NOT_EMPTY`。
+     * @throws {@link HbMiniProgramSDKError} 目标或任一祖先不存在时返回 `DIRECTORY_NOT_FOUND`，目标
+     * 实际是文件或路径中的祖先类型不匹配时返回 `FILE_TYPE_MISMATCH`。删除已经不存在的目录不会
+     * 当作幂等成功；需要“确保不存在”语义时应先接受缺失错误或在操作后调用 `exists()` 对账。
+     * @throws {@link HbMiniProgramSDKError} 未声明或未启用 `filesystem` 权限时分别以
+     * `PERMISSION_NOT_DECLARED`、`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`、
+     * `FILE_ACCESS_DENIED`、`FILE_IO_FAILED` 或 Host 保留的对应稳定文件错误码拒绝。
+     *
+     * @remarks
+     * 该方法只对当前 Mini-program identity 的 sandbox 子目录开放，并要求代理的
+     * `mode === 'readwrite'`。它不需要可信用户手势、不打开系统选择器、不暴露真实路径，也不会因为
+     * 传入 `recursive: true` 而跨出当前逻辑目录。picker 只负责授予外部访问，不能授予删除外部目录
+     * 树的能力；这一来源限制独立于 mode 和 Host 原生权限。
+     *
+     * `recursive: false` 是保护性默认值：空目录会删除，存在任意直接或间接子项时应返回
+     * `DIRECTORY_NOT_EMPTY`，且不应由 Runtime 自动重试为递归删除。`recursive: true` 明确授权 Host
+     * 删除该目录及其整个后代，包括文件、空目录和非空目录。Promise 只反映 Host 对本次请求的最终
+     * 结果；公开合同不承诺多对象删除具备事务原子性或失败后自动恢复已删除子项。
+     *
+     * 删除成功后，当前代理对象不会失效或自动改变 `name` / `mode`。随后
+     * {@link DirectoryHandle.exists | exists()} 应在目标仍不存在时返回 `false`，也可以调用
+     * {@link DirectoryHandle.create | create()} 在同一 sandbox 位置重新创建。两次调用之间仍存在
+     * 并发变化窗口，因此删除前的 `exists()` 或 `list()` 不能保证后续删除成功。
+     *
+     * 若只需删除单个 sandbox 文件，使用 {@link FileHandle.remove | FileHandle.remove()}；它没有
+     * `recursive` 选项。若希望保留目录并清理部分内容，应先通过 `list()` 取得直接子项，再按业务规则
+     * 删除 sandbox 项；不要对外部授权项调用 remove。
+     *
+     * 新 PC Host 支持该操作；Android / iOS `1.3.396+` 仅在 `system.describe` 宣告
+     * `files.remove` 时逐项启用，OHOS 同样以 Host 实际协商结果为准。Web、Browser Dev Host、旧 Host
+     * 或缺少该 operation 的环境会 fail closed，不提供浏览器文件系统或内存 fallback；页面应处理
+     * `METHOD_FORBIDDEN`，不要仅按操作系统推断可用性。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const cache = hbSDK.files.sandbox.directory('cache')
+     * await cache.create({ recursive: true })
+     * await cache.file('index.json').writeText('{}')
+     *
+     * try {
+     *   await cache.remove() // 默认 recursive: false，非空目录会拒绝。
+     * } catch (error) {
+     *   if (!(error instanceof HbMiniProgramSDKError) || error.code !== 'DIRECTORY_NOT_EMPTY') {
+     *     throw error
+     *   }
+     * }
+     *
+     * await cache.remove({ recursive: true })
+     * console.log(await cache.exists()) // false
+     *
+     * // 代理仍表示同一个 sandbox 位置。
+     * await cache.create()
+     * ```
+     *
+     * @see {@link DirectoryHandle.create | DirectoryHandle.create()} 显式确保目录和可选父目录存在。
+     * @see {@link DirectoryHandle.exists | DirectoryHandle.exists()} 删除后确认当前目录是否仍存在。
+     * @see {@link DirectoryHandle.list | DirectoryHandle.list()} 删除前枚举直接子项。
+     * @see {@link FileHandle.remove | FileHandle.remove()} 删除单个 sandbox 文件。
+     * @see [files.sandbox.directory()](/reference/sdk/files/sandbox/directory) 创建 sandbox 目录代理。
+     * @see [files.pickDirectory()](/reference/sdk/files/pickDirectory) 取得不可删除的外部目录授权。
+     * @see [文件能力与沙箱](/guide/files-and-sandbox) 查看来源、权限、平台和错误码边界。
+     *
+     * @since 0.8.0-alpha.2
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android numeric-dot \>= 1.3.396
+     * @hbClient ios numeric-dot \>= 1.3.396
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
+    remove(options?: RemoveOptions): Promise<void>;
+    /**
+     * 检查目录是否存在。
+     *
+     * @returns Runtime 对当前目录引用执行一次 Host `stat` 后得到的 boolean 快照。目标目录存在且 Host
+     * 确认为目录时返回 `true`；目标或任一祖先不存在，目标实际是文件，或 Host 以
+     * `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`
+     * （底层要求 `files.stat`）时返回 `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
+     * @throws {@link HbMiniProgramSDKError} 外部 direct directory handle 被撤销、不属于当前或已结束的
+     * Runtime session 时返回 `FILE_ACCESS_REVOKED`；Host 拒绝当前目录授权时返回 `FILE_ACCESS_DENIED`。
+     * 这些授权错误不会被转换为 `false`。
+     * @throws {@link HbMiniProgramSDKError} Host 返回未归类的错误、公开 bridge 返回非 boolean 结果或底层
+     * I/O 失败时返回 `FILE_IO_FAILED` 或对应稳定文件错误码。握手失败、SDK / Runtime 已终止或不可用、
+     * 调用超时时还可能返回 `HANDSHAKE_FAILED`、`SDK_DESTROYED`、`RUNTIME_DESTROYED`、
+     * `RUNTIME_UNAVAILABLE`、`REQUEST_TIMEOUT`。
+     *
+     * @remarks
+     * `exists()` 是只读探测，`mode: 'read'` 与 `mode: 'readwrite'` 均可调用；它不要求可信用户手势，
+     * 不会创建目录、枚举子项、读取文件内容、延长外部授权寿命或占用新的 direct-handle 配额。sandbox
+     * lazy ref 会在每次调用时按当前 Mini-program identity 解析；picker 返回的外部目录授权只在当前
+     * Runtime session 有效。
+     *
+     * 每次调用都会发送新的 `directory.exists` 请求并重新查询 Host，不读取或更新 SDK 本地缓存。
+     * 返回值只描述该次查询完成时的状态：目录可能在 Promise resolve 后立即被其他代码创建、删除或
+     * 替换，因此先 `exists()` 再 `create()` / `list()` 存在 TOCTOU 竞态。必须继续处理后续操作自身的
+     * `DIRECTORY_NOT_FOUND`、`FILE_TYPE_MISMATCH`、授权和 I/O 错误；需要确保目录存在时，直接调用
+     * {@link DirectoryHandle.create | create()} 的幂等默认模式通常更合适。
+     *
+     * Runtime 内部通过 Host directory `stat` 判断 kind，但公开 `DirectoryHandle` 没有 `stat()` 方法，
+     * `exists()` 也不会暴露 size、时间戳或其他目录元数据。{@link FileHandle.stat | FileHandle.stat()}
+     * 只适用于文件；不要把它当作目录元数据入口。需要直接子项时调用
+     * {@link DirectoryHandle.list | list()}，它会重新访问 Host，不复用本次存在性结果。
+     *
+     * 新 PC Host 支持该操作；Android / iOS `1.3.396+` 仅在 `system.describe` 宣告 `files.stat` 时启用，
+     * OHOS 同样以 Host 实际协商结果为准。Web、Browser Dev Host、旧 Host 或缺少该 operation 的环境
+     * fail closed，返回 `METHOD_FORBIDDEN` / `METHOD_NOT_FOUND`，不会用浏览器 File / Blob 或内存目录
+     * 伪造 `false`。该操作只读取元数据，不受移动端 8 MiB 完整文件内容读写上限影响。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const cache = hbSDK.files.sandbox.directory('cache/images')
+     *
+     * try {
+     *   if (!(await cache.exists())) {
+     *     // 默认 create 是幂等的；recursive 同时确保父目录存在。
+     *     await cache.create({ recursive: true })
+     *   }
+     *
+     *   // exists() 与 list() 不是原子操作，list() 的错误仍需处理。
+     *   const entries = await cache.list({ limit: 100 })
+     *   console.log(entries.map(entry => entry.name))
+     * } catch (error) {
+     *   if (error instanceof HbMiniProgramSDKError && error.code === 'DIRECTORY_NOT_FOUND') {
+     *     console.warn('目录在检查后被删除，请刷新状态后重试')
+     *   } else {
+     *     throw error
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link DirectoryHandle.create | DirectoryHandle.create()} 幂等确保目录及可选父目录存在。
+     * @see {@link DirectoryHandle.list | DirectoryHandle.list()} 重新访问 Host 并枚举直接子项。
+     * @see {@link FileHandle.exists | FileHandle.exists()} 对文件目标执行相同的存在性归一化。
+     * @see {@link FileHandle.stat | FileHandle.stat()} 文件专属的公开元数据快照。
+     * @see [files.sandbox.directory()](/reference/sdk/files/sandbox/directory) 创建 sandbox lazy DirectoryHandle。
+     * @see [files.pickDirectory()](/reference/sdk/files/pickDirectory) 取得当前 session 的外部目录授权。
+     * @see [文件能力与沙箱](/guide/files-and-sandbox) 查看权限、平台和错误边界。
+     */
+    exists(): Promise<boolean>;
+    /**
+     * 枚举当前目录的直接子项。
+     *
+     * @param options - 可选的单次结果数量上限。省略 options、传 `{}` 或省略 `limit` 时使用
+     * `1000`；完整范围见 {@link ListOptions}。
+     * @returns 当前目录直接子项的冻结 {@link FileHandle} / {@link DirectoryHandle} 代理数组；空目录
+     * 返回 `[]`。数组与每个代理都是本次调用的新结果，条目 `mode` 与当前目录严格一致，`name` 只含
+     * basename，不包含父路径或 Host 真实路径。不会递归返回后代。
+     * @throws {@link HbMiniProgramSDKError} options 不是对象，或 `limit` 不是正的 safe integer 时返回
+     * `INVALID_PARAMS`；`limit > 1000`，或 Host 返回项目数超过有效 `limit` 时返回
+     * `DIRECTORY_LIST_LIMIT_EXCEEDED`。
+     * @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` 时返回
+     * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。
+     * @throws {@link HbMiniProgramSDKError} Host 返回非数组、稀疏数组、非法 kind/name/mode/handle，或
+     * 子项不能安全派生为当前目录的直接后代时返回 `FILE_IO_FAILED`；其他 Host 枚举或底层 I/O 失败
+     * 返回对应稳定文件错误码，无法识别的 Host 错误统一为 `FILE_IO_FAILED`。
+     *
+     * @remarks
+     * `list()` 只枚举一层，不排序、不去重，也不补齐分页。结果顺序以及达到 `limit` 时选择哪些条目
+     * 由 Host 文件系统决定；调用方不能依赖字母序、创建时间序或跨调用稳定顺序。需要稳定展示时应按
+     * `name` 等业务规则自行排序。公开结果没有 `total`、`hasMore` 或 continuation cursor，因此
+     * `limit` 不应被当作可完整遍历超大目录的分页协议。
+     *
+     * Runtime 逐槽读取 Host 数组，拒绝稀疏或越界结果，并把每个 Host 文件/目录转换成当前目录的直接
+     * 子逻辑引用；SDK 再验证所有 descriptor 都继承父目录 `mode`。从 `read` 目录列出的代理仍只读，
+     * 从 `readwrite` 目录列出的代理可在原授权范围内写入，但枚举不会提升权限或扩大到父目录之外。
+     *
+     * 返回项不会作为新的 external direct handles 注册，因此不消耗 picker / `saveFile()` 共享的 1024
+     * direct-handle 配额。它们仍依赖原目录的来源和生命周期：sandbox 子项按当前 Mini-program identity
+     * 解析；外部目录的子项只在原 direct Directory 所属的当前 Runtime session 内有效，session 结束或
+     * 授权撤销后后续操作会失败。列表只是本次枚举快照，返回后文件系统可以继续变化。
+     *
+     * `mode: 'read'` 与 `mode: 'readwrite'` 目录都能调用。该方法不要求可信用户手势，不创建、读取或
+     * 修改文件内容；外部目录只有最初调用 `pickDirectory()` 时需要手势。新 PC Host 支持该操作；
+     * Android / iOS `1.3.396+` 仅在 `system.describe` 宣告 `files.list` 时逐项启用，OHOS 同样以 Host
+     * 实际协商结果为准。Web、Browser Dev Host、旧 Host 或 operation 缺失时 fail closed，不提供
+     * 浏览器文件系统、File / Blob 或内存 fallback。
+     *
+     * 若只需判断目录本身是否存在，使用 {@link DirectoryHandle.exists | exists()}。已知子项名称时，
+     * 可直接通过当前目录的 {@link PathRoot.file | file()} 或 {@link PathRoot.directory | directory()}
+     * 构造 lazy proxy，无需先枚举；这两个方法同样不会执行 I/O 或占用 direct-handle 配额。
+     *
+     * @example
+     * ```ts
+     * import hbSDK from '@heybox/hb-sdk'
+     *
+     * const reports = hbSDK.files.sandbox.directory('reports')
+     * await reports.create({ recursive: true })
+     * await reports.file('summary.json').writeText('{}')
+     * await reports.directory('archive').create()
+     *
+     * const entries = await reports.list({ limit: 100 })
+     * const sorted = [...entries].sort((left, right) => left.name.localeCompare(right.name))
+     * for (const entry of sorted) {
+     *   if (entry.kind === 'file') console.log('file', entry.name, await entry.stat())
+     *   else console.log('directory', entry.name, await entry.exists())
+     * }
+     * ```
+     *
+     * @see {@link ListOptions}
+     * @see {@link FileSystemEntity}
+     * @see {@link PathRoot.file | DirectoryHandle.file()} 构造已知名称的直接或嵌套文件代理。
+     * @see {@link PathRoot.directory | DirectoryHandle.directory()} 构造已知名称的直接或嵌套目录代理。
+     * @see {@link DirectoryHandle.exists | DirectoryHandle.exists()} 检查当前目录是否存在。
+     * @see {@link FilesModule.pickDirectory | files.pickDirectory} 取得当前 session 的外部目录授权。
+     * @see [文件能力与沙箱](/guide/files-and-sandbox) 查看权限、路径、平台与配额边界。
+     */
+    list(options?: ListOptions): Promise<FileSystemEntity[]>;
+}
+/** 目录枚举返回的文件或目录代理。 */
+type FileSystemEntity = FileHandle | DirectoryHandle;
+/**
+ * {@link FileHandle.stat} 返回的文件元数据快照。
+ *
+ * @remarks
+ * Runtime 与 SDK 会把 Host 结果规范为这四个公开字段；Host 的额外字段不会进入结果。每次 `stat()`
+ * 返回新对象，它不是缓存或 live view，也不冻结；调用方修改字段不会改变文件或后续快照。
+ *
+ * 单位是公开合同而不是可从 number 结构证明的事实：`size` 按 byte 解释，时间字段按 Unix epoch
+ * milliseconds 解释。SDK 无法验证 Host 实际单位、时间来源、字段之间的顺序关系或快照 resolve 后是否仍
+ * 与磁盘一致。
+ */
+interface FileStat {
+    /** 固定为 `'file'`，用于和 Host 的目录状态区分。 */
+    kind: 'file';
+    /**
+     * 本次快照中的文件大小，公开约定单位为 byte。必须是 `0` 到 `Number.MAX_SAFE_INTEGER` 的整数；
+     * `0` 表示空文件。负数、小数、`NaN`、Infinity、unsafe integer 或数字字符串会使 `stat()` 以
+     * `FILE_IO_FAILED` 拒绝。
+     */
+    size: number;
+    /**
+     * Host 可提供的最后修改时间，公开约定为 Unix epoch milliseconds。可独立省略；存在时只保证为
+     * 非负有限 number，允许小数和超过 `Number.MAX_SAFE_INTEGER` 的值，不保证可构造有效 `Date`。
+     */
+    modifiedAt?: number;
+    /**
+     * Host 可提供的创建时间，公开约定为 Unix epoch milliseconds。可独立省略；范围规则与
+     * {@link FileStat.modifiedAt} 相同，也不保证早于或等于 `modifiedAt`。
+     */
+    createdAt?: number;
+}
+/**
+ * Mini-program 对外文件能力。
+ *
+ * @remarks
+ * `sandbox` 提供隔离持久存储；picker 与 `saveFile()` 通过可信用户操作授予当前 Runtime session
+ * 最小化的外部访问范围。所有能力要求声明 `filesystem`，具体 operation 还需由 Host 宣告支持。
+ */
+interface FilesModule {
+    /** 当前 Mini-program 的私有 sandbox 逻辑根。 */
+    readonly sandbox: FileSystem;
+    /**
+     * 让用户选择一个或多个文件并返回当前 session 的授权代理。
+     *
+     * @param options - 可选访问模式、扩展名筛选与多选设置；完整默认值和校验见
+     * {@link PickFilesOptions}。
+     * @returns 非空的冻结 {@link FileHandle} 数组。默认单选时恰好一项；每项 `kind` 固定为
+     * `'file'`，`name` 是安全 basename，`mode` 与请求模式一致，且不包含真实路径。用户取消会
+     * 抛错，不返回空数组或 `undefined`。
+     * @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` 时返回
+     * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`；请求的 `readwrite` 未获 Host
+     * 授予时返回 `FILE_ACCESS_DENIED`。
+     * @throws {@link HbMiniProgramSDKError} 整批结果会让当前 session 的外部 direct handle 超过
+     * 1024 时返回 `FILE_QUOTA_EXCEEDED`，且不保留部分结果；授权在完成前失效、Host 返回空数组、
+     * 单选返回多项、结果结构/name/mode 非法或其他 picker/I/O 失败时返回
+     * `FILE_ACCESS_REVOKED` / `FILE_IO_FAILED` 等稳定文件错误码。
+     *
+     * @remarks
+     * 必须直接从按钮点击等可信用户操作调用。不要先 `await` 握手或其他异步任务；应提前通过
+     * `getHandshakeState()` / `onHandshakeStateChange()` 控制按钮只在 ready 时可用，再在点击回调
+     * 中立即调用 picker。取消是正常用户结果，应按 `FILE_PICKER_CANCELLED` 结束当前流程。
+     *
+     * 默认 `mode: 'read'`、`multiple: false` 且无 `accept`。返回的是用户选择范围内的精确外部
+     * File direct handles，不是浏览器原生 `File`，不能扩张到父目录或兄弟文件；每项授权只在
+     * 当前 Runtime session 有效，session 结束或授权撤销后不能恢复或持久化复用。单个 session
+     * 的 picker / `saveFile()` direct handle 共享 1024 上限，每个返回文件占用一个。
+     *
+     * `read` File 可调用 `readText()`、`readBytes()`、`exists()` 与 `stat()`；写入、创建及作为
+     * 下载替换目标需要 `readwrite`。外部精确 File 无论 mode 都不能删除。Android 已适配客户端
+     * 支持精确 SAF 文件的 `readwrite` 选择，需系统返回写入授权；较早客户端仍会拒绝该模式。
+     * `writeText()` / `writeBytes()` 先暂存完整内容再写入，最终 Provider 写入不是原子替换，
+     * 失败时原文件可能为空或只写入部分内容。该授权不支持 `network.download()` 的原子替换。
+     * 未指定模式时仍为只读；用户或 Provider 未授予写入权限时返回 `FILE_ACCESS_DENIED`。
+     *
+     * 新 PC Host 支持文件选择；Android/iOS 需要 `1.3.396+`，移动端继续以 `system.describe`
+     * 实际声明的 operation 为准；OHOS 同样按 Host 宣告能力启用。Web、Browser Dev Host、旧 Host
+     * 或 operation 集不完整时 fail closed，不提供浏览器 File/Blob 或内存 fallback。页面代码不应
+     * 按操作系统猜测可用性，应处理 `METHOD_FORBIDDEN`。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const chooseFilesButton = document.querySelector<HTMLButtonElement>('#choose-files')!
+     *
+     * chooseFilesButton.addEventListener('click', async () => {
+     *   try {
+     *     const files = await hbSDK.files.pickFiles({
+     *       mode: 'read',
+     *       accept: ['.json', '.txt'],
+     *       multiple: true,
+     *     })
+     *
+     *     for (const file of files) {
+     *       console.log(file.kind, file.name, file.mode, await file.readText())
+     *     }
+     *   } catch (error) {
+     *     if (error instanceof HbMiniProgramSDKError && error.code === 'FILE_PICKER_CANCELLED') return
+     *     throw error
+     *   }
+     * })
+     * ```
+     *
+     * @see {@link PickFilesOptions}
+     * @see {@link FileHandle}
+     * @see {@link FileHandle.readText}
+     * @see {@link FileHandle.readBytes}
+     * @see {@link FileHandle.stat}
+     * @see {@link FilesModule.pickDirectory | files.pickDirectory}
+     * @see {@link FilesModule.saveFile | files.saveFile}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/files-and-sandbox | 文件能力与沙箱}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling | 错误处理}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     *
+     * @since 0.8.0-alpha.2
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android numeric-dot \>= 1.3.396
+     * @hbClient ios numeric-dot \>= 1.3.396
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
+    pickFiles(options?: PickFilesOptions): Promise<FileHandle[]>;
+    /**
+     * 让用户选择目录并返回当前 session 的授权代理。
+     *
+     * @param options - 可选目录授权模式；省略时等同于 `{ mode: 'read' }`，完整规则见
+     * {@link PickDirectoryOptions}。
+     * @returns 用户选中的冻结 {@link DirectoryHandle} direct proxy。`kind` 固定为
+     * `'directory'`，`name` 是安全 basename，`mode` 与请求模式一致；不包含真实路径。取消会抛错，
+     * 不返回 `undefined`。
+     * @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` 时返回
+     * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`；请求的 `readwrite` 未获 Host
+     * 授予时返回 `FILE_ACCESS_DENIED`。
+     * @throws {@link HbMiniProgramSDKError} 当前 session 的外部 direct handle 达到 1024 上限时返回
+     * `FILE_QUOTA_EXCEEDED`；授权在完成前失效、Host 结果非法/mode 不匹配或其他 picker/I/O 失败时
+     * 返回 `FILE_ACCESS_REVOKED` 或 `FILE_IO_FAILED` 等稳定文件错误码。
+     *
+     * @remarks
+     * 必须直接从按钮点击等可信用户操作调用。不要先 `await` 握手或其他异步任务；应提前通过
+     * `getHandshakeState()` / `onHandshakeStateChange()` 控制按钮只在 ready 时可用，再在点击回调
+     * 中立即调用 picker。取消是正常用户结果，应按 `FILE_PICKER_CANCELLED` 结束当前流程。
+     *
+     * 默认授权模式为 `read`。返回的是用户选择范围的精确外部目录授权，只在当前 Runtime
+     * session 有效；session 结束或授权撤销后不能恢复或持久化复用。其 `file()` / `directory()`
+     * 派生项及 `list()` 结果继承 mode、不能提升权限，也不会继续占用 direct handle 配额。
+     * `readwrite` 允许在授权目录内创建/写入以及作为 `network.download()` target，但外部目录及
+     * 其后代仍不能删除。
+     *
+     * 单个 Runtime session 最多保留 1024 个 picker / `saveFile()` direct handles；每次成功的
+     * `pickDirectory()` 占用一个。它与 sandbox 的逻辑代理不同：
+     * {@link FileSystem.directory | files.sandbox.directory} 不打开选择器、无需用户手势、持久按
+     * Mini-program 隔离，也不占用该 direct-handle 配额。
+     *
+     * 鸿蒙手机和平板的单目录选择需要系统 API 26.0.0 或以上；较早系统需具备
+     * `SystemCapability.FileManagement.UserFileService.FolderSelection` 能力。
+     * 同时要求当前客户端已适配并开放目录选择，不支持时抛出 `METHOD_FORBIDDEN`。
+     * 不具备上述能力的 API 24 鸿蒙手机无法选择外部目录，声明 `filesystem` 或升级编译 SDK
+     * 不会解除限制。单文件读写或导出可分别使用 `pickFiles()`、`saveFile()`，不授予父目录权限。
+     *
+     * 新 PC Host 支持目录选择；Android/iOS 需要 `1.3.396+`，移动端继续以 `system.describe`
+     * 实际声明的 operation 为准；OHOS 同样按 Host 宣告能力启用。Web、Browser Dev Host、旧 Host
+     * 或 operation 集不完整时 fail closed，不提供 Blob/内存 fallback。页面代码不应按操作系统
+     * 猜测可用性，应处理 `METHOD_FORBIDDEN`。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const chooseDirectoryButton = document.querySelector<HTMLButtonElement>('#choose-directory')!
+     *
+     * chooseDirectoryButton.addEventListener('click', async () => {
+     *   try {
+     *     const directory = await hbSDK.files.pickDirectory({ mode: 'readwrite' })
+     *     console.log(directory.kind, directory.name, directory.mode)
+     *     await directory.file('report.txt').writeText('done')
+     *   } catch (error) {
+     *     if (error instanceof HbMiniProgramSDKError && error.code === 'FILE_PICKER_CANCELLED') return
+     *     throw error
+     *   }
+     * })
+     * ```
+     *
+     * @see {@link PickDirectoryOptions}
+     * @see {@link DirectoryHandle}
+     * @see {@link FileSystem.directory | files.sandbox.directory}
+     * @see {@link FilesModule.saveFile | files.saveFile}
+     * @see {@link MiniProgramNetworkModule.download | network.download}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/files-and-sandbox | 文件能力与沙箱}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling | 错误处理}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     *
+     * @since 0.8.0-alpha.2
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android numeric-dot \>= 1.3.396
+     * @hbClient ios numeric-dot \>= 1.3.396
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
+    pickDirectory(options?: PickDirectoryOptions): Promise<DirectoryHandle>;
+    /**
+     * 让用户选择一个精确的文件保存目标。
+     *
+     * @param options - 必填的保存目标建议 basename；完整校验见 {@link SaveFileOptions}。
+     * @returns 用户确认后的冻结 {@link FileHandle} direct proxy。`kind` 固定为 `'file'`，`name`
+     * 是 Host 最终文件 basename，`mode` 固定为 `'readwrite'`；不包含真实路径，也不授予父目录或
+     * 兄弟文件访问权。
+     * @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 时返回
+     * `METHOD_FORBIDDEN`，旧 Runtime 可返回 `METHOD_NOT_FOUND`。目标已存在且 Host 不能独占创建
+     * 时返回 `FILE_ALREADY_EXISTS`，不会静默覆盖。
+     * @throws {@link HbMiniProgramSDKError} 当前 session 的外部 direct handle 达到 1024 上限时返回
+     * `FILE_QUOTA_EXCEEDED`；授权在完成前失效、Host 返回非精确 File、非 `readwrite` mode、非法
+     * descriptor 或其他 picker/I/O 失败时返回 `FILE_ACCESS_REVOKED` / `FILE_IO_FAILED` 等稳定
+     * 文件错误码。
+     *
+     * @remarks
+     * 必须直接从按钮点击等可信用户操作调用。不要先 `await` 握手或其他异步任务；应提前通过
+     * `getHandshakeState()` / `onHandshakeStateChange()` 控制按钮只在 ready 时可用，再在点击回调
+     * 中立即调用。取消是正常用户结果，应按 `FILE_PICKER_CANCELLED` 结束当前流程。
+     *
+     * 返回的是当前 Runtime session 内一个精确外部 File 授权，不会额外保留或暴露父 Directory
+     * handle。它占用 picker / `saveFile()` 共享的 1024 direct-handle 配额中的一个；session 结束
+     * 或授权撤销后不能恢复或持久化复用。代理固定 `readwrite`，可调用 `writeText()` /
+     * `writeBytes()`，或作为 {@link MiniProgramNetworkModule.download | network.download} 的 File
+     * target；外部授权仍不能调用 `remove()`。
+     *
+     * V1 没有 overwrite 选项。当前新 PC Host 先让用户选择保存目录，再以 `suggestedName` 独占
+     * 创建空文件；同名目标返回 `FILE_ALREADY_EXISTS`。其他 Host 可以展示平台原生保存界面，
+     * 但成功结果仍只授权最终精确 File，且不能通过该 API 请求静默覆盖。
+     *
+     * Android 已适配客户端支持 `files.saveFile`，系统保存器返回精确 SAF 文件授权，不授予
+     * 父目录权限。`writeText()` / `writeBytes()` 先暂存完整内容，再写入该目标；最终 Provider
+     * 写入不是原子替换，失败时目标可能为空或部分写入，原内容不保证保留。该授权不支持
+     * `network.download()` 的原子替换，导出请调用文件代理的写入方法。
+     *
+     * 新 PC、Android 与 iOS Host 支持该能力。OHOS 按 Host 实际宣告的
+     * operation 启用。Web、Browser Dev Host、旧 Host 或 operation 集不完整时 fail closed，不
+     * 提供 Blob/内存 fallback。页面代码不应仅按操作系统判断，应处理 `METHOD_FORBIDDEN`。
+     *
+     * @example
+     * ```ts
+     * import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'
+     *
+     * const saveButton = document.querySelector<HTMLButtonElement>('#save-report')!
+     *
+     * saveButton.addEventListener('click', async () => {
+     *   try {
+     *     const file = await hbSDK.files.saveFile({ suggestedName: 'report.json' })
+     *     await file.writeText(JSON.stringify({ ok: true }))
+     *     console.log(file.kind, file.name, file.mode)
+     *   } catch (error) {
+     *     if (error instanceof HbMiniProgramSDKError && error.code === 'FILE_PICKER_CANCELLED') return
+     *     throw error
+     *   }
+     * })
+     * ```
+     *
+     * @see {@link SaveFileOptions}
+     * @see {@link FileHandle}
+     * @see {@link FileHandle.writeText}
+     * @see {@link FileHandle.writeBytes}
+     * @see {@link FilesModule.pickFiles | files.pickFiles}
+     * @see {@link FilesModule.pickDirectory | files.pickDirectory}
+     * @see {@link MiniProgramNetworkModule.download | network.download}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/files-and-sandbox | 文件能力与沙箱}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/error-handling | 错误处理}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/guide/permissions | 权限声明}
+     *
+     * @since 0.8.0-alpha.2
+     * @hbPlatform android
+     * @hbPlatform ios
+     * @hbPlatform ohos
+     * @hbPlatform windows
+     * @hbPlatform macos
+     * @hbClient android numeric-dot \>= 1.3.396
+     * @hbClient ios numeric-dot \>= 1.3.396
+     * @hbClient ohos none
+     * @hbClient windows none
+     * @hbClient macos none
+     */
+    saveFile(options: SaveFileOptions): Promise<FileHandle>;
+}
+
+/**
+ * `network.request` 请求头。
+ *
+ * @remarks
+ * 键必须是无首尾空白的合法 HTTP header name，值必须是无换行/控制字符的字符串。
+ * `Host`、`Content-Length`、hop-by-hop/framing Header 以及平台保留的认证 Header 会以
+ * `INVALID_PARAMS` 拒绝。响应侧不会向小程序暴露 `Set-Cookie`、认证凭据或平台保留 Header。
+ */
+type MiniProgramNetworkHeaders = Record<string, string>;
+/**
+ * `network.request` 查询参数，由 Host 编码到请求 URL。
+ *
+ * @remarks
+ * 必须是普通对象。为获得跨 Host 一致的查询字符串，优先使用 string/number/boolean 等标量值；
+ * `null`、`undefined`、数组和嵌套对象的具体 URL 编码不属于公共稳定契约。
+ */
+type MiniProgramNetworkParams = Record<string, unknown>;
+/** `network.request` 支持的 HTTP 方法；省略时使用 `GET`。 */
+type MiniProgramNetworkRequestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/**
+ * SDK 侧可配置的状态校验函数。
+ *
+ * @param status - 标准化后的 HTTP 状态码。
+ * @returns 返回 `true` 时表示本次响应应视为成功。
+ *
+ * @remarks
+ * 该函数只在 SDK 收到并标准化响应后执行，不会跨 bridge 传输到 Host。默认仅接受 `200`
+ * 至 `299`；可返回 `true` 接受 3xx/4xx 等完成态响应。函数自身抛出的异常会原样向调用方传播，
+ * 不会包装成 SDK 或 Network 错误。
+ */
+type MiniProgramNetworkValidateStatus = (status: number) => boolean;
+/**
+ * 对外开放的网络请求配置。
+ *
+ * @remarks
+ * 该配置面向业务层，保持 axios-like 的窄接口，不暴露宿主协议的原始字段。请求进入 bridge
+ * 时会复制 plain object/array 数据并移除 `validateStatus`；响应中的 `config` 由 SDK 另行构造。
+ */
+interface MiniProgramNetworkRequestConfig {
+    /**
+     * 绝对请求地址。必须是无 username/password 的 HTTP(S) URL；生产环境只允许 HTTPS，本地
+     * 开发仅允许 Host 明确放行的数字 loopback/LAN HTTP origin。官方域名要求
+     * `package.json#heybox.permissions.network.useOfficialDomain` 的声明值与平台批准值都为
+     * `true`；Runtime auth、OpenAPI 内部路径和官方账号敏感路径始终禁止访问。
+     */
+    url: string;
+    /** HTTP 方法，默认 `GET`；仅支持 {@link MiniProgramNetworkRequestMethod} 中列出的值。 */
+    method?: MiniProgramNetworkRequestMethod;
+    /** 查询参数；必须是普通对象，SDK 会递归复制 plain object/array 后交给 Host 编码。 */
+    params?: MiniProgramNetworkParams;
+    /**
+     * 请求体。
+     *
+     * @remarks
+     * 支持可序列化的 JSON-compatible 值与原始字符串，总大小不得超过 2 MiB。plain object/array
+     * 会递归复制，因此复用同一子对象可以，但循环引用会以 `INVALID_PARAMS` 拒绝。`GET`/`HEAD`
+     * 不应携带 body。
+     *
+     * 第三方 URL 的非字符串 JSON-compatible 值默认按 JSON 发送；官方域名为兼容既有 Host，
+     * plain object/array 在未显式设置 Content-Type 时默认按 form 编码。要强制 JSON，请设置
+     * `Content-Type: application/json`；表单请传
+     * `new URLSearchParams(values).toString()` 并设置
+     * `application/x-www-form-urlencoded`。
+     *
+     * 不支持 `FormData`、`Blob`、File/Directory 代理、`ArrayBuffer`、TypedArray、`DataView`、
+     * `SharedArrayBuffer` 或它们的嵌套值。`multipart/form-data` 与手写 multipart body 均不可用；
+     * 文件传输应使用专用能力。
+     */
+    data?: unknown;
+    /**
+     * 请求头；规则见 {@link MiniProgramNetworkHeaders}。调用方显式提供的普通 `Cookie` /
+     * `Authorization` 可作为应用 Header 交给 Host，但 SDK 不提供平台 Cookie/token，且不得在
+     * 小程序中持有或发送平台凭据、服务端应用密钥等敏感信息。
+     */
+    headers?: MiniProgramNetworkHeaders;
+    /**
+     * Host 请求超时，单位毫秒；必须是 `0` 至 `30000` 的有限数字。省略或 `0` 时的具体默认
+     * 行为由 Host 决定；业务需要明确超时时应传正数。该字段不改变 SDK 等待 bridge 响应的
+     * 独立超时；默认 SDK 实例的等待上限为 10 秒，详见 {@link MiniProgramNetworkModule.request}。
+     */
+    timeout?: number;
+    /** SDK 侧状态校验；默认只接受 2xx，函数本身不会跨 bridge，详见 {@link MiniProgramNetworkValidateStatus}。 */
+    validateStatus?: MiniProgramNetworkValidateStatus;
+}
+/**
+ * 流式下载的 request-scoped 进度。
+ *
+ * @remarks
+ * Runtime 会过滤倒退、负数、超出可信 `Content-Length` 或 `maxBytes` 的进度，并在原子提交后、
+ * `download()` resolve 前发送一次最终进度。最终值可能与上一次相同，空文件也会发送
+ * `loaded: 0`；不要依赖回调次数或严格递增。
+ */
+interface DownloadProgress {
+    /** 已接收并写入临时目标的非负字节数；原子提交完成前不表示原目标已改变。 */
+    loaded: number;
+    /** 可从可信响应 framing 确定总长度时的非负字节数；未知、分块或压缩响应时省略。 */
+    total?: number;
+    /** `total` 是否存在且可用于计算百分比；为 `false` 时应展示不定进度。 */
+    lengthComputable: boolean;
+}
+/**
+ * 流式下载两种 target 分支共享的地址、限制、取消与进度选项。
+ *
+ * @remarks
+ * 下载固定使用 GET、拒绝重定向，不接受 `method`、`data`、`body`、Range/If-Range/A-IM
+ * 等部分响应字段。响应字节由 Host 直接写入临时目标，不经过 iframe bridge。
+ */
+interface DownloadBaseOptions {
+    /**
+     * 下载地址。必须是无 username/password 的 HTTP(S) URL；生产环境只允许 HTTPS，本地开发
+     * 仅允许 Host 明确放行的 loopback/LAN HTTP origin。当前公开 Host 的流式下载 adapter 不支持
+     * 小黑盒官方域名，即使 `network.useOfficialDomain` 已声明并获批也不应依赖；Runtime/账号
+     * 敏感路径始终禁止访问。
+     */
+    url: string;
+    /** 查询参数；必须是对象，SDK 会复制后交给 Host 编码到下载 URL。 */
+    params?: MiniProgramNetworkParams;
+    /**
+     * 请求头；必须是合法的字符串字典。Host/framing/hop-by-hop、平台保留认证头以及
+     * `Range`、`If-Range`、`A-IM` 会以 `INVALID_PARAMS` 拒绝。普通 `Authorization` / `Cookie`
+     * 不会被 Runtime 一律拒绝，但移动端下载不会自动附带 Host credential；鉴权资源优先使用
+     * 短期签名 URL。
+     */
+    headers?: MiniProgramNetworkHeaders;
+    /**
+     * 网络与响应 body 的空闲超时，单位毫秒；必须是有限正数，不是整个下载的总时长。
+     * 省略时 SDK 与 Runtime 不设置统一默认值，由 Host 采用自身策略；需要确定超时预算时显式传入。
+     */
+    timeout?: number;
+    /**
+     * 单次下载可提交的最大字节数；必须是正的 safe integer。可信 `Content-Length` 已超限时
+     * 会在写入前返回 `FILE_TOO_LARGE`，流式传输过程中超限也不会提交部分文件。
+     * 省略时 SDK 与 Runtime 不附加该字节上限，但仍受 Host 文件与传输限制；不能视为无限容量。
+     */
+    maxBytes?: number;
+    /**
+     * 用于取消当前下载。调用前已 aborted 会立即返回 `DOWNLOAD_CANCELLED`；提交前取消获胜时
+     * 原目标保持不变，Host 已完成原子提交时则成功结果优先。
+     */
+    signal?: AbortSignal;
+    /**
+     * 接收当前下载的标准化 {@link DownloadProgress}。回调本身不会序列化到 bridge；回调抛错
+     * 不会中断下载。`lengthComputable` 为 `false` 时不要按 `total` 计算百分比。
+     */
+    onProgress?: (progress: DownloadProgress) => void;
+}
+/**
+ * 下载目标选项。
+ *
+ * @remarks
+ * File target 必须是当前 SDK session 中已存在的 `readwrite` {@link FileHandle}。下载成功后
+ * 原子替换该文件并返回传入的同一个代理，不接受 `suggestedName` 或 `overwrite`。
+ *
+ * Directory target 必须是当前 SDK session 中已存在的 `readwrite` {@link DirectoryHandle}。
+ * 下载会在其中创建一个直接子文件并返回新的冻结 `readwrite` File 代理；默认独占创建，
+ * 同名目标返回 `FILE_ALREADY_EXISTS`，仅 `overwrite: true` 允许原子创建或替换。
+ */
+type DownloadOptions = DownloadBaseOptions & ({
+    /** 当前 SDK session 创建的 `readwrite` File 代理；目标文件必须已存在。成功后返回同一代理。 */
+    to: FileHandle;
+    /** File target 不接受该字段；即使显式传入字符串也返回 `INVALID_PARAMS`。 */
+    suggestedName?: never;
+    /** File target 固定原子替换，不接受该字段；即使显式传入 boolean 也返回 `INVALID_PARAMS`。 */
+    overwrite?: never;
+} | {
+    /** 当前 SDK session 创建的、已存在的 `readwrite` Directory 代理；成功后返回其直接子 File 代理。 */
+    to: DirectoryHandle;
+    /**
+     * 建议的安全子文件 basename。服务端安全 `Content-Disposition filename*` / `filename`
+     * 优先于该值；之后依次回退 URL basename 与 `download.bin`。不能包含路径分隔符、点段、
+     * 控制字符、Windows 保留名或尾随点/空格，最长 255 个 Unicode 字符。
+     */
+    suggestedName?: string;
+    /** 是否允许原子创建或替换目录内的同名文件，默认 `false`；`false` 时采用独占创建。 */
+    overwrite?: boolean;
+});
+/**
+ * bridge / runtime 返回的标准化 HTTP 响应。
+ *
+ * @typeParam T - 调用方声明的响应数据类型；只影响 TypeScript，不执行运行时 schema 校验。
+ */
+interface NetworkResponsePayload<T = unknown> {
+    /** Host 标准化后的响应数据；泛型 `T` 只提供 TypeScript 类型，不执行运行时 schema 校验。 */
+    data: T;
+    /** 已完成 HTTP 响应的状态码。 */
+    status: number;
+    /** 可用时的 HTTP 状态文本。 */
+    statusText?: string;
+    /**
+     * Host 返回的安全字符串响应头；无有效响应头时为空对象。`Set-Cookie`、认证凭据以及
+     * `x-heybox-*` / `x-xhh-*` 平台保留 Header 会在跨 bridge 前移除。
+     */
+    headers: MiniProgramNetworkHeaders;
+}
+/**
+ * SDK 对外暴露的网络响应。
+ *
+ * @typeParam T - 调用方期望的响应数据类型；SDK 不会在运行时校验 Host 返回值是否符合该类型。
+ *
+ * @remarks
+ * `config` 不包含 Host 内部 route、body encoding、Cookie 状态或协议字段。bridge 请求在调用时
+ * 使用独立克隆；响应完成时，SDK 再从原始公开 config 构造响应快照，递归复制其中的 plain
+ * object/array，并保留同一个 `validateStatus` 函数引用。因此请求进行期间对原 config 的修改
+ * 不会改变已发送 payload，但可能反映在完成时生成的 `response.config` 中。
+ */
+interface MiniProgramNetworkResponse<T = unknown> extends NetworkResponsePayload<T> {
+    /** 响应标准化时构造的 SDK 公共配置快照；对象和数组已复制，`validateStatus` 保留原函数引用。 */
+    config: MiniProgramNetworkRequestConfig;
+}
+
+/**
+ * 登录时可请求的用户信息 scope。
+ *
+ * @remarks
+ * - `identity`：允许开发者服务端取得当前用户在当前小程序内稳定、隔离的
+ *   `app_user_id`。它不是黑盒用户 ID，也不能跨小程序关联用户。
+ * - `profile`：允许开发者服务端读取当前用户的昵称和头像。用户可以只同意
+ *   `identity`，因此请求 `profile` 不代表最终一定获得该 scope。
+ * - `steam_account`：申请当前用户主绑定 Steam 账号资料。授权成功不代表已绑定 Steam；
+ *   {@link AuthorizedUserInfo.steam_id} 存在才表示取得了主绑定 SteamID64，不包含游戏库。
+ *   旧版或未启用 Steam 账号能力的 Host 会以 `INVALID_PARAMS` 拒绝该 scope。
+ *
+ * `identity` 是登录流程的必选 scope：调用方可以不传它，平台仍会把它加入实际授权
+ * 结果。scope 只描述授权码和后续 OpenAPI token 可访问的资料，不是 token、客户端权限
+ * 或 `package.json#heybox.permissions` 中的开发者权限声明。
+ *
+ * @see {@link LoginOptions.scopes}
+ * @see {@link LoginResult.scopes}
+ * @see [用户身份与登录](https://docs.xiaoheihe.cn/hb_sdk/guide/auth)
+ */
+type LoginScope = LoginScope$1;
+/**
+ * `auth.login` 的可选配置。
+ *
+ * @remarks
+ * 整个参数、省略的 `scopes` 和 `scopes: undefined` 都表示只申请平台隐式包含的
+ * `identity`。配置中不接收小程序 ID、用户 ID、手势标记、应用密钥或 token；这些值由
+ * Host 的可信上下文提供，不能由页面覆盖。
+ *
+ * @see {@link LoginScope}
+ * @see [权限声明](https://docs.xiaoheihe.cn/hb_sdk/guide/permissions)
+ */
+interface LoginOptions {
+    /**
+     * 要申请的可选资料 scope。
+     *
+     * @remarks
+     * 通常只在需要昵称和头像时传 `['profile']`；`identity` 无需显式填写。空数组不会产生
+     * 匿名授权，成功结果仍包含 `identity`。数组中的值必须属于 {@link LoginScope} 且不能
+     * 重复；JavaScript 调用传入未知值、重复值、`null` 或非数组值时，Promise 以
+     * `HbMiniProgramSDKError.code === 'INVALID_PARAMS'` 拒绝。
+     * `steam_account` 虽属于公开类型，仍要求 Host 支持并启用 Steam 账号能力。
+     *
+     * @defaultValue `undefined`，即只申请隐式的 `identity`。
+     * @see {@link LoginResult.scopes}
+     */
+    scopes?: LoginScope[];
+}
+
+/**
+ * Steam 游戏库的服务端排序维度。
+ *
+ * @remarks
+ * - `weeks`：按最近两周游玩时长排序，也是默认值。
+ * - `all`：按累计游玩时长排序。
+ * - `achieved`：按已解锁成就数排序。
+ */
+type SteamGameListSort = 'weeks' | 'all' | 'achieved';
+/**
+ * Steam 游戏库查询与 offset 分页参数。
+ *
+ * @remarks
+ * Runtime 会拒绝未知字段和类型不匹配的值，不会把数字字符串或 `0` / `1` 自动转换为
+ * `number` / `boolean`。所有默认值和规范化均在 Host 发出 Steam 请求前完成。
+ */
+interface GetSteamGameListOptions {
+    /**
+     * 要查询的 Steam ID；省略时使用当前小黑盒用户的默认绑定账号。
+     * 首尾空白会被移除，trim 后为空会以 `INVALID_PARAMS` 拒绝。
+     */
+    steamId?: string;
+    /** 单页数量，默认 `20`；必须是大于等于 `1` 的整数，大于 `100` 时按 `100` 查询。 */
+    limit?: number;
+    /** 分页偏移量，默认 `0`；必须是大于等于 `0` 的整数，不接受数字字符串。 */
+    offset?: number;
+    /** 排序维度，默认 `weeks`；只接受大小写完全一致的 `weeks`、`all` 或 `achieved`。 */
+    sort?: SteamGameListSort;
+    /**
+     * 游戏名称搜索词。Runtime 会先 trim，再保留前 `100` 个 UTF-16 code unit；trim 后为空时
+     * 不向服务端发送 `q`，等价于不按关键词过滤。
+     */
+    q?: string;
+    /** 是否包含当前用户隐藏的游戏，默认 `false`；只接受 boolean，不接受 `0` / `1`。 */
+    includeHidden?: boolean;
+}
+
+/**
+ * 小程序可选分享渠道。
+ *
+ * @remarks
+ * `wechatSession` / `wechatTimeline` / `qqFriend` / `qzone` / `weibo` 分别表示微信好友、
+ * 微信朋友圈、QQ 好友、QQ 空间和微博。值区分大小写；Host 可以只支持其中一部分。
+ * `share.showShareMenu()` 省略 `channel` 时由客户端展示默认分享面板；指定 `channel` 时不能
+ * 同时配置有效的社区 `post` 预置。
+ */
+type MiniProgramShareChannel = 'wechatSession' | 'wechatTimeline' | 'qqFriend' | 'qzone' | 'weibo';
+/**
+ * 分享扩展数据支持的 JSON-compatible 类型。
+ *
+ * @remarks
+ * 只允许 `null`、有限数字、字符串、布尔值、数组和普通对象；`undefined`、`NaN`、
+ * `Infinity`、`bigint`、`symbol`、函数、循环引用、`Date`、`Map` 和其他 class 实例均不受支持。
+ * 普通对象的 key 不能是 MessagePack 解码器保留的 `__proto__`。
+ * 合法的 `null`、`false`、`0` 与空字符串在 {@link MiniProgramShareModule.getExtra | share.getExtra}
+ * 中会原样返回，不能用真假值判断是否存在分享数据。
+ *
+ * 编码后的 MessagePack 最多 8 层嵌套，单个数组或对象最多 64 项，总容量不超过 128 字节；
+ * 超限时分享 API 返回 `INVALID_PARAMS`，接收端 `getExtra()` 则对非法启动参数返回 `undefined`。
+ * 不要把 token、cookie、个人信息或其他敏感数据放入分享 URL。
+ */
+type MiniProgramShareExtraValue = null | boolean | number | string | readonly MiniProgramShareExtraValue[] | {
+    readonly [key: string]: MiniProgramShareExtraValue;
+};
+/**
+ * 客户端“转发到社区”发帖页的可编辑预置。
+ *
+ * @remarks
+ * 预置只填充客户端发帖页，用户仍可修改或取消，不会由 SDK 直接发布。`showShareMenu` 最多
+ * 保留一个分区，`screenshot` 可保留多个分区；两者都会按首次出现顺序去重。
+ *
+ * 开发 Runtime 对任一无效项返回 `INVALID_PARAMS`，生产 Runtime 则过滤无效项；过滤后没有
+ * 任何有效分区或话题时省略整个 `post`，但继续原分享流程。
+ *
+ * @see [社区分享预置](/recipes/community-share)
+ */
+interface MiniProgramSharePostOptions {
+    /**
+     * 默认发布分区 ID。number 必须是正安全整数并转换为字符串；string 会 trim 且必须非空。
+     * 规范化后按首次出现顺序去重，普通分享最多保留第一项，截图分享可保留多项。
+     */
+    topicIds?: (string | number)[];
+    /**
+     * 预置话题正文。每项必须是 string，trim 后非空且不能以 `#` 开头或结尾；规范化后按首次
+     * 出现顺序去重。传正文即可，不要自行包裹 `#`。
+     */
+    topics?: string[];
+}
+/**
+ * 展示基础分享面板的配置。
+ *
+ * @remarks
+ * 分享落地页固定为当前小程序的通用分享页。该配置只暴露基础分享字段，不暴露宿主内部
+ * 上报、回调、自定义按钮、直接发布等协议参数。`url` 即使值为 `undefined` 也不允许出现；
+ * 其他未知字段不会传给 Host。
+ */
+interface MiniProgramShowShareMenuOptions {
+    /** 分享标题；必须是 trim 后非空的字符串，前后空白不会被 SDK 改写。 */
+    title: string;
+    /** 分享描述；必须是 trim 后非空的字符串，前后空白不会被 SDK 改写。 */
+    desc: string;
+    /**
+     * 写入固定落地页 URL、供接收方 {@link MiniProgramShareModule.getExtra | share.getExtra}
+     * 读取的业务状态；遵守 {@link MiniProgramShareExtraValue} 的类型、深度、项数和 128 字节限制。
+     * 省略时不携带 `extra`，也不会继承当前启动链接中的值。
+     */
+    extra?: MiniProgramShareExtraValue;
+    /**
+     * 分享缩略图的绝对 URL；必须是非空字符串、可由 `URL` 解析，且协议严格为 `http:` 或
+     * `https:`。SDK 只校验 URL，不负责下载、裁剪或确认 Host 最终采用该图片。
+     */
+    imageUrl?: string;
+    /**
+     * 指定站外分享渠道；省略时由客户端展示默认面板。不能与有效 `post` 同时使用，且具体
+     * 渠道是否可用由 Host 决定。
+     */
+    channel?: MiniProgramShareChannel;
+    /**
+     * 转发到社区时使用的分区与话题预置；`null` 或省略表示不预置。
+     *
+     * @remarks
+     * 普通分享最多保留一个规范化后的 `topicIds`，但可保留多个去重后的 `topics`。开发态对
+     * 无效项、空预置、多个分区或与 `channel` 的冲突返回 `INVALID_PARAMS`；生产态会过滤无效项、
+     * 截断到首个分区，并在冲突时保留 `channel`、省略 `post`，不会阻断基础分享面板。
+     * 用户进入发帖页后仍可修改或取消，SDK 不会直接发布帖子。
+     */
+    post?: MiniProgramSharePostOptions | null;
+}
+/**
+ * 截图区域。
+ *
+ * @remarks
+ * 坐标与尺寸均使用当前小程序可见窗口的逻辑像素，原点是窗口左上角，与
+ * {@link MiniProgramViewportModule.getWindowInfo | viewport.getWindowInfo} 返回的
+ * `windowWidth`、`windowHeight` 使用同一坐标系。TypeScript 调用方应传有限 number；当前
+ * Runtime 会先用 `Number(...)` 转换 JavaScript 值再校验范围，因此字符串、boolean、`null`
+ * 等可能被兼容转换，业务不应依赖该宽松行为。Runtime 不会取整，也不会把矩形夹取到窗口边界；调用方应确保
+ * `left + width <= windowWidth`、`top + height <= windowHeight`。
+ *
+ * 省略整个 `rect` 时，Runtime 会在调用时读取当前窗口并构造
+ * `{ left: 0, top: 0, width: windowWidth, height: windowHeight }`。窗口可能在用户拖动、
+ * 旋转设备或 Host 恢复后变化，不要长期缓存旧矩形。
+ *
+ * @see {@link MiniProgramScreenshotOptions.rect}
+ * @see {@link MiniProgramViewportModule.getWindowInfo | viewport.getWindowInfo}
+ */
+interface MiniProgramScreenshotRect {
+    /** 截图区域左边缘距窗口左边缘的逻辑像素数；转换后必须有限且大于等于 `0`。 */
+    left: number;
+    /** 截图区域上边缘距窗口上边缘的逻辑像素数；必须是有限且大于等于 `0` 的数。 */
+    top: number;
+    /** 截图区域宽度，单位逻辑像素；必须是有限且大于 `0` 的数。 */
+    width: number;
+    /** 截图区域高度，单位逻辑像素；必须是有限且大于 `0` 的数。 */
+    height: number;
+}
+/**
+ * 截图分享配置。
+ *
+ * @remarks
+ * 该配置只暴露截图与保存相册相关基础字段，不暴露宿主内部上传、回调或样式扩展能力。
+ * 所有字段均可省略；省略整个配置等同于传入空配置，并在调用时截取当前可见窗口。
+ * JavaScript 调用在运行时传入 `null` 也会按空配置处理，但 TypeScript 调用方应直接省略参数。
+ *
+ * @see {@link MiniProgramShareModule.screenshot | share.screenshot}
+ */
+interface MiniProgramScreenshotOptions {
+    /**
+     * 指定截图区域；省略时截取调用时的整个可见窗口。
+     *
+     * @remarks
+     * 字段单位、有效范围和窗口边界要求见 {@link MiniProgramScreenshotRect}。Runtime 不会
+     * 自动按设备像素比换算，也不会裁正越界矩形。
+     */
+    rect?: MiniProgramScreenshotRect;
+    /**
+     * Host 开始截图前的延迟，单位毫秒；TypeScript 调用应传 number，Runtime 用 `Number(...)`
+     * 转换后要求有限且大于等于 `0`。
+     *
+     * @remarks
+     * Runtime 不要求整数，也不设置上限。省略时不会下发 `delay`，由当前 Host 使用默认值；
+     * Host 仍可按平台能力拒绝过大的值。
+     */
+    delay?: number;
+    /**
+     * 是否在客户端截图分享流程中提供保存到系统相册的能力。
+     *
+     * @remarks
+     * `true` 明确请求提供，`false` 明确关闭。省略时不会下发该开关，由当前 Host 决定
+     * 默认行为；该字段本身不表示图片已经保存成功。
+     */
+    saveToAlbum?: boolean;
+    /**
+     * 转发到社区时使用的分区与话题预置；`null` 或省略表示不预置。
+     *
+     * @remarks
+     * 截图分享支持多个分区。`topicIds` 中的正安全整数会转成字符串，字符串会 trim，
+     * 再按首次出现顺序去重；`topics` 会 trim、拒绝首尾 `#`，再按首次出现顺序去重。
+     * 预置必须至少保留一个有效的 `topicIds` 或 `topics` 项。
+     *
+     * 开发 Runtime 遇到任一无效项会以 `INVALID_PARAMS` 拒绝，生产 Runtime 则过滤无效项，
+     * 将剩余有效项交给客户端；没有有效项时省略整个 `post`，但继续截图。预置只填充
+     * 客户端发帖页，用户仍可修改或取消，不会直接发布内容。
+     * 当前小程序来源由 Runtime 使用 Host 确认的 canonical identity 自动关联，调用方不能
+     * 也无需传入小程序 ID 或其他来源字段。
+     *
+     * @see {@link MiniProgramSharePostOptions}
+     * @see {@link https://docs.xiaoheihe.cn/hb_sdk/recipes/community-share | 社区分享预置}
+     */
+    post?: MiniProgramSharePostOptions | null;
+}
+
+/**
+ * 导航栏关闭按钮与状态栏图标/文字的前景样式。
+ *
+ * @remarks
+ * `light` 请求 Host 使用白色或浅色前景，适合深色背景；`dark` 请求 Host 使用黑色
+ * 或深色前景，适合浅色背景。该类型没有 `auto`、`system` 或恢复默认值；需要跟随
+ * 页面主题时，应在主题变化后重新调用
+ * {@link MiniProgramViewportModule.setNavigationBarStyle}。
+ *
+ * 取值表达的是对比度语义，不是固定色号。具体颜色、透明度以及状态栏和关闭按钮的
+ * 渲染方式由当前 Host 与操作系统决定。
+ *
+ * @see {@link MiniProgramSetNavigationBarStyleOptions.foregroundStyle}
+ */
+type MiniProgramNavigationBarForegroundStyle = 'light' | 'dark';
+/**
+ * 设置导航栏样式的配置。
+ *
+ * @remarks
+ * `options` 必须是对象，且 `foregroundStyle` 是必填字段。Runtime 只接受精确的
+ * `light` 或 `dark` 字符串；缺少字段、传入 `null`、数组或其他值都会以
+ * `INVALID_PARAMS` 拒绝。
+ *
+ * 当前仅开放关闭按钮与状态栏图标/文字的前景明暗样式，不设置导航栏背景色。
+ *
+ * @see {@link MiniProgramNavigationBarForegroundStyle}
+ */
+interface MiniProgramSetNavigationBarStyleOptions {
+    /**
+     * 导航栏关闭按钮与状态栏图标/文字的前景样式。
+     *
+     * @remarks
+     * 该字段必填且仅接受 `light` 或 `dark`。`light` 适合深色背景，`dark` 适合浅色
+     * 背景；它不读取网页背景，也不会自动跟随 `prefers-color-scheme`。
+     */
+    foregroundStyle: MiniProgramNavigationBarForegroundStyle;
+}
+
+export type { CreateOptions, DirectoryHandle, DownloadBaseOptions, DownloadOptions, DownloadProgress, FileHandle, FileMode, FileStat, FileSystem, FileSystemEntity, FilesModule, GetSteamGameListOptions, ListOptions, LoginOptions, MiniProgramEventHandler, MiniProgramNetworkRequestConfig, MiniProgramNetworkResponse, MiniProgramNetworkValidateStatus, MiniProgramScreenshotOptions, MiniProgramSetNavigationBarStyleOptions, MiniProgramShowShareMenuOptions, PathRoot, PickDirectoryOptions, PickFilesOptions, RemoveOptions, SaveFileOptions };