@heybox/hb-sdk 0.7.5-alpha.0 → 0.8.0-alpha.10

package/dist/index.esm.js

@@ -292,9 +292,9 @@ class HbMiniProgramSDKError extends Error {
 /**
  * 创建 SDK 标准错误。
  *
- * @param code 稳定错误码。
- * @param message 面向开发者的错误说明。
- * @param data 可选调试数据。
+ * @param code - 稳定错误码。
+ * @param message - 面向开发者的错误说明。
+ * @param data - 可选调试数据。
  * @returns 标准化 `HbMiniProgramSDKError` 实例。
  *
  * @remarks
@@ -314,7 +314,7 @@ function createSDKError(code, message, data) {
  * 仅在请求已经成功走完 bridge / runtime / 宿主调用链、但最终 HTTP 状态不满足
  * `validateStatus` 时抛出。它不表示握手失败或 bridge 级错误。
  *
- * @typeParam T 标准化响应数据的类型。
+ * @typeParam T - 标准化响应数据的类型。
  */
 class HbMiniProgramNetworkError extends Error {
     /** HTTP 状态码。 */
@@ -328,7 +328,7 @@ class HbMiniProgramNetworkError extends Error {
     /** 完整标准化响应。 */
     response;
     /**
-     * @param response 已完成请求的标准化网络响应。
+     * @param response - 已完成请求的标准化网络响应。
      */
     constructor(response) {
         const method = (response.config.method || 'GET').toUpperCase();
@@ -572,6 +572,22 @@ const VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD = 'viewport.setNavigationBarStyle
 const STORAGE_GET_STORAGE_METHOD = 'storage.getStorage';
 const STORAGE_SET_STORAGE_METHOD = 'storage.setStorage';
 const NETWORK_REQUEST_METHOD = 'network.request';
+const NETWORK_DOWNLOAD_METHOD = 'network.download';
+const FILES_PICK_FILES_METHOD = 'files.pickFiles';
+const FILES_PICK_DIRECTORY_METHOD = 'files.pickDirectory';
+const FILES_SAVE_FILE_METHOD = 'files.saveFile';
+const FILE_CREATE_METHOD = 'file.create';
+const FILE_REMOVE_METHOD = 'file.remove';
+const FILE_EXISTS_METHOD = 'file.exists';
+const FILE_READ_TEXT_METHOD = 'file.readText';
+const FILE_WRITE_TEXT_METHOD = 'file.writeText';
+const FILE_READ_BYTES_METHOD = 'file.readBytes';
+const FILE_WRITE_BYTES_METHOD = 'file.writeBytes';
+const FILE_STAT_METHOD = 'file.stat';
+const DIRECTORY_CREATE_METHOD = 'directory.create';
+const DIRECTORY_REMOVE_METHOD = 'directory.remove';
+const DIRECTORY_EXISTS_METHOD = 'directory.exists';
+const DIRECTORY_LIST_METHOD = 'directory.list';
 const UI_SHOW_TOAST_METHOD = 'ui.showToast';
 const UI_SHOW_LOADING_METHOD = 'ui.showLoading';
 const UI_HIDE_LOADING_METHOD = 'ui.hideLoading';
@@ -593,20 +609,131 @@ const SDK_HANDSHAKE_METHOD = 'sdk.handshake';
 const RUNTIME_LOCATION_PROBE_METHOD = 'runtime.location.probe';
 const SDK_LOCATION_REPORT_METHOD = 'sdk.location.report';
 const SDK_CSP_VIOLATION_METHOD = 'sdk.csp.violation';
+const MINI_PROGRAM_OPERATION_PROGRESS_METHOD = 'operation.progress';
 
 function isMiniProgramBridgeMessage(value) {
-    if (!value || typeof value !== 'object')
+    if (!isRecord$1(value))
         return false;
-    const message = value;
-    return (message.namespace === MINI_PROGRAM_MESSAGE_NAMESPACE &&
-        (message.version === 1 || message.version === 2) &&
-        typeof message.nonce === 'string' &&
-        typeof message.type === 'string');
+    if (value.namespace !== MINI_PROGRAM_MESSAGE_NAMESPACE || (value.version !== 1 && value.version !== 2) || !isNonEmptyString(value.nonce)) {
+        return false;
+    }
+    if (value.type === 'handshake') {
+        return isNonEmptyString(value.id) && value.method === SDK_HANDSHAKE_METHOD && value.error === undefined && isSDKHandshakePayload(value.payload);
+    }
+    if (value.type === 'request') {
+        return isNonEmptyString(value.id) && isNonEmptyString(value.method) && value.error === undefined;
+    }
+    if (value.type === 'response') {
+        return (isNonEmptyString(value.id) &&
+            (value.method === undefined || isNonEmptyString(value.method)) &&
+            (value.error === undefined || isBridgeError(value.error)));
+    }
+    if (value.type === 'event') {
+        if (!isNonEmptyString(value.method) || value.error !== undefined)
+            return false;
+        if (value.method === MINI_PROGRAM_OPERATION_PROGRESS_METHOD) {
+            return value.version === 2 && isNonEmptyString(value.id) && isMiniProgramDownloadProgressPayload(value.payload);
+        }
+        return value.id === undefined || isNonEmptyString(value.id);
+    }
+    if (value.type === 'cancel') {
+        return (value.version === 2 && isNonEmptyString(value.id) && value.method === undefined && value.payload === undefined && value.error === undefined);
+    }
+    return false;
+}
+function isMiniProgramRelativePath(value) {
+    if (typeof value !== 'string' || !value || value.startsWith('/') || value.endsWith('/')) {
+        return false;
+    }
+    if (/[\\\u0000-\u001f\u007f]/.test(value))
+        return false;
+    return value.split('/').every((segment) => Boolean(segment) && segment !== '.' && segment !== '..');
+}
+function isMiniProgramPathRootRef(value) {
+    if (!isRecord$1(value))
+        return false;
+    if (value.kind === 'sandbox')
+        return hasOnlyKeys(value, ['kind']);
+    return value.kind === 'directory' && isNonEmptyString(value.handleId) && hasOnlyKeys(value, ['kind', 'handleId']);
+}
+function isMiniProgramFileRef(value) {
+    if (!isRecord$1(value) || value.kind !== 'file')
+        return false;
+    if (isNonEmptyString(value.handleId)) {
+        return hasOnlyKeys(value, ['kind', 'handleId']);
+    }
+    return (isMiniProgramPathRootRef(value.root) && isMiniProgramRelativePath(value.relativePath) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
+}
+function isMiniProgramDirectoryRef(value) {
+    if (!isRecord$1(value) || value.kind !== 'directory')
+        return false;
+    if (isNonEmptyString(value.handleId)) {
+        return hasOnlyKeys(value, ['kind', 'handleId']);
+    }
+    return (isMiniProgramPathRootRef(value.root) && isMiniProgramRelativePath(value.relativePath) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
+}
+function isMiniProgramByteArray(value) {
+    return value instanceof Uint8Array && value.buffer instanceof ArrayBuffer;
+}
+function isMiniProgramFileStat(value) {
+    return (isRecord$1(value) &&
+        value.kind === 'file' &&
+        isNonNegativeSafeInteger(value.size) &&
+        (value.modifiedAt === undefined || isNonNegativeFiniteNumber(value.modifiedAt)) &&
+        (value.createdAt === undefined || isNonNegativeFiniteNumber(value.createdAt)) &&
+        hasOnlyKeys(value, ['kind', 'size', 'modifiedAt', 'createdAt']));
+}
+function isMiniProgramDownloadProgressPayload(value) {
+    if (!isRecord$1(value) ||
+        !isNonNegativeSafeInteger(value.loaded) ||
+        typeof value.lengthComputable !== 'boolean' ||
+        !hasOnlyKeys(value, ['loaded', 'total', 'lengthComputable'])) {
+        return false;
+    }
+    if (!value.lengthComputable)
+        return value.total === undefined;
+    return isNonNegativeSafeInteger(value.total) && value.loaded <= value.total;
+}
+function isSDKHandshakePayload(value) {
+    return isRecord$1(value) && isNonEmptyString(value.href) && typeof value.userAgent === 'string' && isNonEmptyString(value.sdkVersion);
+}
+function isBridgeError(value) {
+    return isRecord$1(value) && isNonEmptyString(value.code) && typeof value.message === 'string';
+}
+function isNonNegativeSafeInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function isNonNegativeFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function hasOnlyKeys(value, allowedKeys) {
+    const allowed = new Set(allowedKeys);
+    return Object.keys(value).every((key) => allowed.has(key));
+}
+function isRecord$1(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
 /** 当前用户信息与登录能力支持的完整 scope 目录。 */
 const USER_INFO_AUTHORIZATION_SCOPES = ['identity', 'profile'];
 
+const MINI_PROGRAM_PERMISSION_KEYS = [
+    'userInfo',
+    'steamLibrary',
+    'share',
+    'storage',
+    'filesystem',
+    'clipboard',
+    'leaderboard',
+    'network',
+];
+new Set(MINI_PROGRAM_PERMISSION_KEYS);
+
+new Set(MINI_PROGRAM_PERMISSION_KEYS);
+
 /** 获取浏览器全局 window。 */
 function getGlobalWindow() {
     return typeof window === 'undefined' ? undefined : window;
@@ -668,7 +795,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.7.5-alpha.0';
+    : '0.8.0-alpha.10';
 
 const DEFAULT_TIMEOUT = 10000;
 const HANDSHAKE_RETRY_INTERVAL = 250;
@@ -703,8 +830,7 @@ class MiniProgramBridgeClient {
     constructor(options = {}) {
         this.timeout = options.timeout || DEFAULT_TIMEOUT;
         this.selfWindow = options.selfWindow || getGlobalWindow();
-        this.targetWindow =
-            options.targetWindow === undefined ? getParentWindow(this.selfWindow) : options.targetWindow;
+        this.targetWindow = options.targetWindow === undefined ? getParentWindow(this.selfWindow) : options.targetWindow;
         this.targetOrigin = options.targetOrigin || readParentOrigin(this.selfWindow) || '*';
         this.nonce = options.nonce || readBridgeNonce(this.selfWindow);
         this.handleMessage = this.onMessage.bind(this);
@@ -737,20 +863,42 @@ class MiniProgramBridgeClient {
     }
     /** 调用父容器开放能力。 */
     async request(method, ...args) {
+        return this.performRequest(method, args[0], true);
+    }
+    /** 发起不使用固定总时长 timer 的长操作。 */
+    async requestOperation(method, payload, options = {}) {
+        return this.performRequest(method, payload, false, options);
+    }
+    async performRequest(method, payload, useTimeout, options = {}) {
         if (this.destroyed) {
             throw createSDKError('SDK_DESTROYED', '小程序 SDK 已销毁');
         }
         if (this.runtimeUnavailable) {
             throw this.getRuntimeUnavailableError();
         }
-        await this.waitForHandshake();
+        if (!useTimeout && options.signal?.aborted) {
+            throw options.createAbortError?.() ?? createSDKError('REQUEST_CANCELLED', `${method} 已取消`);
+        }
+        if (!useTimeout && options.signal && !this.handshakeSettled) {
+            await waitForHandshakeOrAbort(this.waitForHandshake(), options.signal, () => options.createAbortError?.() ?? createSDKError('REQUEST_CANCELLED', `${method} 已取消`), () => {
+                const state = this.handshakeState.getState();
+                if (state.status === 'failed')
+                    return state.error;
+                return this.destroyed ? createSDKError('SDK_DESTROYED', '小程序 SDK 已销毁') : undefined;
+            });
+        }
+        else {
+            await this.waitForHandshake();
+        }
         if (this.destroyed) {
             throw createSDKError('SDK_DESTROYED', '小程序 SDK 已销毁');
         }
         if (this.runtimeUnavailable) {
             throw this.getRuntimeUnavailableError();
         }
-        const payload = args[0];
+        if (options.signal?.aborted) {
+            throw options.createAbortError?.() ?? createSDKError('REQUEST_CANCELLED', `${method} 已取消`);
+        }
         const id = createMessageId();
         const message = {
             namespace: MINI_PROGRAM_MESSAGE_NAMESPACE,
@@ -762,27 +910,46 @@ class MiniProgramBridgeClient {
             payload,
         };
         return new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
-                this.pendingRequests.delete(id);
-                reject(createSDKError('REQUEST_TIMEOUT', `${method} 调用超时`));
-            }, this.timeout);
-            this.pendingRequests.set(id, {
+            const pending = {
                 resolve: resolve,
                 reject,
-                timer,
-            });
+                isOperation: !useTimeout,
+                ...(options.onProgress ? { onProgress: options.onProgress } : {}),
+                ...(options.signal ? { signal: options.signal } : {}),
+            };
+            if (useTimeout) {
+                pending.timer = setTimeout(() => {
+                    const active = this.pendingRequests.get(id);
+                    if (!active) {
+                        return;
+                    }
+                    this.cleanupPending(active);
+                    this.pendingRequests.delete(id);
+                    reject(createSDKError('REQUEST_TIMEOUT', `${method} 调用超时`));
+                }, this.timeout);
+            }
+            this.pendingRequests.set(id, pending);
             try {
                 this.postMessage(message);
             }
             catch (error) {
-                clearTimeout(timer);
+                this.cleanupPending(pending);
                 this.pendingRequests.delete(id);
                 reject(error);
+                return;
+            }
+            if (options.signal) {
+                pending.abortHandler = () => this.sendCancel(id);
+                options.signal.addEventListener('abort', pending.abortHandler, { once: true });
+                if (options.signal.aborted) {
+                    pending.abortHandler();
+                }
             }
         });
     }
     /** 销毁 SDK 实例，并拒绝尚未完成的请求。 */
     destroy() {
+        this.pendingRequests.forEach((_pending, id) => this.sendCancel(id));
         this.destroyed = true;
         this.selfWindow?.removeEventListener('message', this.handleMessage);
         this.selfWindow?.removeEventListener('popstate', this.handlePopState);
@@ -835,16 +1002,12 @@ class MiniProgramBridgeClient {
                     this.postHandshake();
                 }
                 catch (error) {
-                    this.failHandshake(error instanceof HbMiniProgramSDKError
-                        ? error
-                        : createSDKError('HANDSHAKE_FAILED', '小程序沙盒握手发送失败', error));
+                    this.failHandshake(error instanceof HbMiniProgramSDKError ? error : createSDKError('HANDSHAKE_FAILED', '小程序沙盒握手发送失败', error));
                 }
             }, HANDSHAKE_RETRY_INTERVAL);
         }
         catch (error) {
-            this.failHandshake(error instanceof HbMiniProgramSDKError
-                ? error
-                : createSDKError('HANDSHAKE_FAILED', '小程序沙盒握手发送失败', error));
+            this.failHandshake(error instanceof HbMiniProgramSDKError ? error : createSDKError('HANDSHAKE_FAILED', '小程序沙盒握手发送失败', error));
         }
     }
     postHandshake() {
@@ -873,6 +1036,10 @@ class MiniProgramBridgeClient {
             return;
         }
         if (event.data.type === 'event') {
+            if (event.data.id && event.data.method === MINI_PROGRAM_OPERATION_PROGRESS_METHOD) {
+                this.handleOperationProgress(event.data);
+                return;
+            }
             this.handleEvent(event.data);
             return;
         }
@@ -954,7 +1121,7 @@ class MiniProgramBridgeClient {
         if (!pending) {
             return;
         }
-        clearTimeout(pending.timer);
+        this.cleanupPending(pending);
         this.pendingRequests.delete(message.id);
         if (message.error) {
             pending.reject(new HbMiniProgramSDKError(message.error));
@@ -962,6 +1129,52 @@ class MiniProgramBridgeClient {
         }
         pending.resolve(message.payload);
     }
+    handleOperationProgress(message) {
+        if (!message.id) {
+            return;
+        }
+        const pending = this.pendingRequests.get(message.id);
+        if (!pending?.onProgress) {
+            return;
+        }
+        try {
+            pending.onProgress(message.payload);
+        }
+        catch {
+            // Mini-program 回调失败不能改变 Host 长操作的生命周期。
+        }
+    }
+    sendCancel(id) {
+        const pending = this.pendingRequests.get(id);
+        if (!pending?.isOperation || pending.cancelSent) {
+            return;
+        }
+        pending.cancelSent = true;
+        try {
+            const message = {
+                namespace: MINI_PROGRAM_MESSAGE_NAMESPACE,
+                version: MINI_PROGRAM_MESSAGE_VERSION,
+                nonce: this.nonce,
+                type: 'cancel',
+                id,
+            };
+            this.postMessage(message);
+        }
+        catch {
+            // cancel 只是意图，发送失败后仍等待唯一 terminal response。
+        }
+    }
+    cleanupPending(pending) {
+        if (pending.timer) {
+            clearTimeout(pending.timer);
+        }
+        if (pending.signal && pending.abortHandler) {
+            pending.signal.removeEventListener('abort', pending.abortHandler);
+        }
+        pending.onProgress = undefined;
+        pending.abortHandler = undefined;
+        pending.signal = undefined;
+    }
     postMessage(message) {
         if (!this.targetWindow) {
             throw createSDKError('NOT_IN_IFRAME', '当前页面不在小程序沙盒 iframe 中');
@@ -1013,13 +1226,34 @@ class MiniProgramBridgeClient {
         return this.runtimeUnavailableError;
     }
     rejectAllPending(error) {
-        this.pendingRequests.forEach(pending => {
-            clearTimeout(pending.timer);
+        this.pendingRequests.forEach((pending) => {
+            this.cleanupPending(pending);
             pending.reject(error);
         });
         this.pendingRequests.clear();
     }
 }
+function waitForHandshakeOrAbort(handshake, signal, createAbortError, getTerminalError) {
+    if (!signal)
+        return handshake;
+    if (signal.aborted)
+        return Promise.reject(createAbortError());
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const settle = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener('abort', onAbort);
+            callback();
+        };
+        const onAbort = () => settle(() => reject(getTerminalError() ?? createAbortError()));
+        signal.addEventListener('abort', onAbort, { once: true });
+        handshake.then(() => settle(() => (signal.aborted ? reject(createAbortError()) : resolve())), (error) => settle(() => reject(error)));
+        if (signal.aborted)
+            onAbort();
+    });
+}
 
 /** 获取短期授权码。 */
 function login(requester, options) {
@@ -1048,10 +1282,10 @@ function createCloudModule(requester) {
 /**
  * 复制当前小程序的通用分享链接。
  *
- * @param requester 底层 bridge 请求能力。
- * @param options 分享扩展数据；不传时复制默认首页链接。
+ * @param requester - 底层 bridge 请求能力。
+ * @param options - 分享扩展数据；不传时复制默认首页链接。
  * @returns 已写入系统剪贴板的完整分享链接。
- * @throws {HbMiniProgramSDKError} 当参数、bridge、父容器或剪贴板能力调用失败时抛出。
+ * @throws {@link HbMiniProgramSDKError} 当参数、bridge、父容器或剪贴板能力调用失败时抛出。
  */
 function copyLink(requester, options) {
     return requester.request(SHARE_COPY_LINK_METHOD, options);
@@ -2251,22 +2485,22 @@ function decodeBase64Url(value) {
 /**
  * 截图并唤起分享。
  *
- * @param requester 底层 bridge 请求能力。
- * @param options 截图区域、延迟与保存相册等配置。
+ * @param requester - 底层 bridge 请求能力。
+ * @param options - 截图区域、延迟与保存相册等配置。
  * @returns 由宿主客户端协议决定的结果。
- * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ * @throws {@link HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
  */
 function screenshot(requester, options) {
     return requester.request(SHARE_SCREENSHOT_METHOD, options);
 }
 
 /**
- * 展示基础分享面板。
+ * 展示以当前小程序通用分享页为落地页的基础分享面板。
  *
- * @param requester 底层 bridge 请求能力。
- * @param options 基础分享参数。
+ * @param requester - 底层 bridge 请求能力。
+ * @param options - 基础分享参数。
  * @returns 由宿主客户端协议决定的结果。
- * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ * @throws {@link HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
  */
 function showShareMenu(requester, options) {
     return requester.request(SHARE_SHOW_SHARE_MENU_METHOD, options);
@@ -2275,25 +2509,25 @@ function showShareMenu(requester, options) {
 /**
  * 创建分享模块。
  *
- * @param requester 底层 bridge 请求能力。
+ * @param requester - 底层 bridge 请求能力。
  * @returns 面向业务层的分享模块对象。
  */
 function createShareModule(requester, launchHref) {
     return {
-        copyLink: options => copyLink(requester, options),
+        copyLink: (options) => copyLink(requester, options),
         getExtra: () => readMiniProgramShareExtra(launchHref),
-        showShareMenu: options => showShareMenu(requester, options),
-        screenshot: options => screenshot(requester, options),
+        showShareMenu: (options) => showShareMenu(requester, options),
+        screenshot: (options) => screenshot(requester, options),
     };
 }
 
 /**
  * 获取小程序隔离 storage。
  *
- * @param requester 底层 bridge 请求能力。
- * @param options 读取的 storage key。
+ * @param requester - 底层 bridge 请求能力。
+ * @param options - 读取的 storage key。
  * @returns 对应 key 的标准化读取结果。
- * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ * @throws {@link HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
  */
 function getStorage(requester, options) {
     return requester.request(STORAGE_GET_STORAGE_METHOD, options);
@@ -2301,10 +2535,10 @@ function getStorage(requester, options) {
 /**
  * 写入小程序隔离 storage。
  *
- * @param requester 底层 bridge 请求能力。
- * @param options 要写入的 storage key 与数据。
+ * @param requester - 底层 bridge 请求能力。
+ * @param options - 要写入的 storage key 与数据。
  * @returns 当写入完成后 resolve。
- * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ * @throws {@link HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
  */
 function setStorage(requester, options) {
     return requester.request(STORAGE_SET_STORAGE_METHOD, options);
@@ -2312,15 +2546,382 @@ function setStorage(requester, options) {
 /**
  * 创建 storage 模块。
  *
- * @param requester 底层 bridge 请求能力。
+ * @param requester - 底层 bridge 请求能力。
  * @returns 面向业务层的 storage 模块对象。
  */
 function createStorageModule(requester) {
     return {
-        getStorage: options => getStorage(requester, options),
-        setStorage: options => setStorage(requester, options),
+        getStorage: (options) => getStorage(requester, options),
+        setStorage: (options) => setStorage(requester, options),
+    };
+}
+
+const registries = new WeakMap();
+const brandedFileSystemValues = new WeakSet();
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/;
+function invalidParams$1(message, data) {
+    return createSDKError('INVALID_PARAMS', message, data);
+}
+function clonePathRootRef(ref) {
+    return ref.kind === 'sandbox' ? Object.freeze({ kind: 'sandbox' }) : Object.freeze({ kind: 'directory', handleId: ref.handleId });
+}
+function cloneFileRef(ref) {
+    return 'handleId' in ref
+        ? Object.freeze({ kind: 'file', handleId: ref.handleId })
+        : Object.freeze({
+            kind: 'file',
+            root: clonePathRootRef(ref.root),
+            relativePath: ref.relativePath,
+        });
+}
+function cloneDirectoryRef(ref) {
+    return 'handleId' in ref
+        ? Object.freeze({ kind: 'directory', handleId: ref.handleId })
+        : Object.freeze({
+            kind: 'directory',
+            root: clonePathRootRef(ref.root),
+            relativePath: ref.relativePath,
+        });
+}
+function assertMode(mode) {
+    if (mode !== 'read' && mode !== 'readwrite') {
+        throw createSDKError('FILE_IO_FAILED', 'Host 返回了无效的文件访问模式');
+    }
+}
+function assertName(name) {
+    if (typeof name !== 'string' || name.length === 0 || name.includes('/') || name.includes('\\') || CONTROL_CHARACTER_PATTERN.test(name)) {
+        throw createSDKError('FILE_IO_FAILED', 'Host 返回了无效的文件名');
+    }
+}
+function assertFileRef(ref) {
+    if (!isMiniProgramFileRef(ref)) {
+        throw createSDKError('FILE_IO_FAILED', 'Host 返回了无效的 File handle');
+    }
+}
+function assertDirectoryRef(ref) {
+    if (!isMiniProgramDirectoryRef(ref)) {
+        throw createSDKError('FILE_IO_FAILED', 'Host 返回了无效的 Directory handle');
+    }
+}
+function defineReadonlyValue(target, key, value, enumerable = true) {
+    Object.defineProperty(target, key, {
+        value,
+        enumerable,
+        configurable: false,
+        writable: false,
+    });
+}
+function joinRelativePath(prefix, relativePath) {
+    return prefix ? `${prefix}/${relativePath}` : relativePath;
+}
+function basename(relativePath) {
+    const segments = relativePath.split('/');
+    return segments[segments.length - 1];
+}
+function assertWritable(mode) {
+    if (mode !== 'readwrite') {
+        throw createSDKError('FILE_ACCESS_DENIED', '当前文件句柄不允许写入');
+    }
+}
+function assertSandboxRef(ref) {
+    if ('handleId' in ref || ref.root.kind !== 'sandbox') {
+        throw createSDKError('FILE_ACCESS_DENIED', '外部文件授权不允许删除');
+    }
+}
+function normalizeCreateOptions(options) {
+    if (options !== undefined && (!options || typeof options !== 'object' || Array.isArray(options))) {
+        throw invalidParams$1('create options 必须是对象');
+    }
+    if (options?.recursive !== undefined && typeof options.recursive !== 'boolean') {
+        throw invalidParams$1('recursive 必须是 boolean');
+    }
+    if (options?.exclusive !== undefined && typeof options.exclusive !== 'boolean') {
+        throw invalidParams$1('exclusive 必须是 boolean');
+    }
+    return {
+        recursive: options?.recursive ?? false,
+        exclusive: options?.exclusive ?? false,
     };
 }
+function normalizeListOptions(options) {
+    if (options !== undefined && (!options || typeof options !== 'object' || Array.isArray(options))) {
+        throw invalidParams$1('list options 必须是对象');
+    }
+    if (options?.limit !== undefined && (!Number.isSafeInteger(options.limit) || options.limit <= 0)) {
+        throw invalidParams$1('limit 必须是正的 safe integer');
+    }
+    return options?.limit;
+}
+function normalizeRemoveOptions(options) {
+    if (options !== undefined && (!options || typeof options !== 'object' || Array.isArray(options))) {
+        throw invalidParams$1('remove options 必须是对象');
+    }
+    if (options?.recursive !== undefined && typeof options.recursive !== 'boolean') {
+        throw invalidParams$1('recursive 必须是 boolean');
+    }
+    return { recursive: options?.recursive ?? false };
+}
+function cloneBytes(content) {
+    if (!(content instanceof Uint8Array)) {
+        throw invalidParams$1('content 必须是 Uint8Array');
+    }
+    if (typeof SharedArrayBuffer !== 'undefined' && content.buffer instanceof SharedArrayBuffer) {
+        throw invalidParams$1('content 不能由 SharedArrayBuffer 承载');
+    }
+    return new Uint8Array(content);
+}
+function normalizeStat(stat) {
+    if (!isMiniProgramFileStat(stat)) {
+        throw createSDKError('FILE_IO_FAILED', 'Host 返回了无效的 FileStat');
+    }
+    return {
+        kind: 'file',
+        size: stat.size,
+        ...(stat.modifiedAt === undefined ? {} : { modifiedAt: stat.modifiedAt }),
+        ...(stat.createdAt === undefined ? {} : { createdAt: stat.createdAt }),
+    };
+}
+/** 校验并返回平台无关的 `/` 分隔逻辑相对路径。 */
+function normalizeRelativePath(value) {
+    if (!isMiniProgramRelativePath(value)) {
+        throw invalidParams$1('relativePath 必须是规范的 `/` 分隔逻辑相对路径');
+    }
+    return value;
+}
+class MiniProgramFileHandleRegistry {
+    requester;
+    fileStates = new WeakMap();
+    directoryStates = new WeakMap();
+    pathRootStates = new WeakMap();
+    sandboxRoot;
+    constructor(requester) {
+        this.requester = requester;
+    }
+    getSandbox() {
+        if (this.sandboxRoot) {
+            return this.sandboxRoot;
+        }
+        const sandbox = {};
+        const state = {
+            root: Object.freeze({ kind: 'sandbox' }),
+            prefix: '',
+            mode: 'readwrite',
+        };
+        this.definePathRootMethods(sandbox, state);
+        this.pathRootStates.set(sandbox, state);
+        brandedFileSystemValues.add(sandbox);
+        this.sandboxRoot = Object.freeze(sandbox);
+        return this.sandboxRoot;
+    }
+    createFile(descriptor) {
+        this.assertFileDescriptor(descriptor);
+        const ref = cloneFileRef(descriptor.ref);
+        const state = { ref, mode: descriptor.mode };
+        const handle = {};
+        defineReadonlyValue(handle, 'kind', 'file');
+        defineReadonlyValue(handle, 'name', descriptor.name);
+        defineReadonlyValue(handle, 'mode', descriptor.mode);
+        defineReadonlyValue(handle, 'create', async (options) => {
+            assertWritable(state.mode);
+            await this.requester.request(FILE_CREATE_METHOD, {
+                target: state.ref,
+                ...normalizeCreateOptions(options),
+            });
+            return handle;
+        }, false);
+        defineReadonlyValue(handle, 'remove', async () => {
+            assertWritable(state.mode);
+            assertSandboxRef(state.ref);
+            await this.requester.request(FILE_REMOVE_METHOD, { target: state.ref });
+        }, false);
+        defineReadonlyValue(handle, 'exists', async () => {
+            const result = await this.requester.request(FILE_EXISTS_METHOD, { target: state.ref });
+            if (typeof result !== 'boolean') {
+                throw createSDKError('FILE_IO_FAILED', 'Host 返回了无效的 exists 结果');
+            }
+            return result;
+        }, false);
+        defineReadonlyValue(handle, 'readText', async () => {
+            const result = await this.requester.request(FILE_READ_TEXT_METHOD, { target: state.ref });
+            if (typeof result !== 'string') {
+                throw createSDKError('FILE_IO_FAILED', 'Host 返回了无效的文本内容');
+            }
+            return result;
+        }, false);
+        defineReadonlyValue(handle, 'writeText', async (content) => {
+            assertWritable(state.mode);
+            if (typeof content !== 'string') {
+                throw invalidParams$1('content 必须是 string');
+            }
+            await this.requester.request(FILE_WRITE_TEXT_METHOD, { target: state.ref, content });
+        }, false);
+        defineReadonlyValue(handle, 'readBytes', async () => {
+            const result = await this.requester.request(FILE_READ_BYTES_METHOD, { target: state.ref });
+            if (!isMiniProgramByteArray(result)) {
+                throw createSDKError('FILE_IO_FAILED', 'Host 返回了无效的二进制内容');
+            }
+            return new Uint8Array(result);
+        }, false);
+        defineReadonlyValue(handle, 'writeBytes', async (content) => {
+            assertWritable(state.mode);
+            const snapshot = cloneBytes(content);
+            await this.requester.request(FILE_WRITE_BYTES_METHOD, { target: state.ref, content: snapshot });
+        }, false);
+        defineReadonlyValue(handle, 'stat', async () => {
+            const result = await this.requester.request(FILE_STAT_METHOD, { target: state.ref });
+            return normalizeStat(result);
+        }, false);
+        this.fileStates.set(handle, state);
+        brandedFileSystemValues.add(handle);
+        return Object.freeze(handle);
+    }
+    createDirectFile(descriptor) {
+        this.assertFileDescriptor(descriptor);
+        if (!('handleId' in descriptor.ref)) {
+            throw createSDKError('FILE_IO_FAILED', 'Host 返回的 File 不是精确文件授权');
+        }
+        return this.createFile(descriptor);
+    }
+    createDirectory(descriptor) {
+        this.assertDirectoryDescriptor(descriptor);
+        const ref = cloneDirectoryRef(descriptor.ref);
+        const state = { ref, mode: descriptor.mode };
+        const pathRootState = 'handleId' in ref ? { root: ref, prefix: '', mode: descriptor.mode } : { root: ref.root, prefix: ref.relativePath, mode: descriptor.mode };
+        const handle = {};
+        defineReadonlyValue(handle, 'kind', 'directory');
+        defineReadonlyValue(handle, 'name', descriptor.name);
+        defineReadonlyValue(handle, 'mode', descriptor.mode);
+        this.definePathRootMethods(handle, pathRootState);
+        defineReadonlyValue(handle, 'create', async (options) => {
+            assertWritable(state.mode);
+            await this.requester.request(DIRECTORY_CREATE_METHOD, {
+                target: state.ref,
+                ...normalizeCreateOptions(options),
+            });
+            return handle;
+        }, false);
+        defineReadonlyValue(handle, 'remove', async (options) => {
+            assertWritable(state.mode);
+            assertSandboxRef(state.ref);
+            await this.requester.request(DIRECTORY_REMOVE_METHOD, {
+                target: state.ref,
+                ...normalizeRemoveOptions(options),
+            });
+        }, false);
+        defineReadonlyValue(handle, 'exists', async () => {
+            const result = await this.requester.request(DIRECTORY_EXISTS_METHOD, { target: state.ref });
+            if (typeof result !== 'boolean') {
+                throw createSDKError('FILE_IO_FAILED', 'Host 返回了无效的 exists 结果');
+            }
+            return result;
+        }, false);
+        defineReadonlyValue(handle, 'list', async (options) => {
+            const limit = normalizeListOptions(options);
+            const result = await this.requester.request(DIRECTORY_LIST_METHOD, {
+                target: state.ref,
+                ...(limit === undefined ? {} : { limit }),
+            });
+            if (!Array.isArray(result)) {
+                throw createSDKError('FILE_IO_FAILED', 'Host 返回了无效的目录列表');
+            }
+            if (result.some((entry) => entry?.mode !== state.mode)) {
+                throw createSDKError('FILE_IO_FAILED', 'Host 返回的目录项未继承父目录 mode');
+            }
+            return result.map((entry) => this.createEntity(entry));
+        }, false);
+        this.directoryStates.set(handle, state);
+        this.pathRootStates.set(handle, pathRootState);
+        brandedFileSystemValues.add(handle);
+        return Object.freeze(handle);
+    }
+    createDirectDirectory(descriptor) {
+        this.assertDirectoryDescriptor(descriptor);
+        if (!('handleId' in descriptor.ref)) {
+            throw createSDKError('FILE_IO_FAILED', 'Host 返回的 Directory 不是精确目录授权');
+        }
+        return this.createDirectory(descriptor);
+    }
+    createEntity(descriptor) {
+        if (descriptor?.kind === 'file') {
+            return this.createFile(descriptor);
+        }
+        if (descriptor?.kind === 'directory') {
+            return this.createDirectory(descriptor);
+        }
+        throw createSDKError('FILE_IO_FAILED', 'Host 返回了无效的文件实体');
+    }
+    requireFile(handle) {
+        const state = handle && typeof handle === 'object' ? this.fileStates.get(handle) : undefined;
+        if (!state) {
+            throw invalidParams$1('to 必须是当前 SDK session 创建的 FileHandle');
+        }
+        return state;
+    }
+    requireDirectory(handle) {
+        const state = handle && typeof handle === 'object' ? this.directoryStates.get(handle) : undefined;
+        if (!state) {
+            throw invalidParams$1('to 必须是当前 SDK session 创建的 DirectoryHandle');
+        }
+        return state;
+    }
+    definePathRootMethods(target, state) {
+        defineReadonlyValue(target, 'file', (relativePath) => {
+            const normalized = normalizeRelativePath(relativePath);
+            const fullPath = joinRelativePath(state.prefix, normalized);
+            return this.createFile({
+                kind: 'file',
+                name: basename(normalized),
+                mode: state.mode,
+                ref: {
+                    kind: 'file',
+                    root: state.root,
+                    relativePath: fullPath,
+                },
+            });
+        }, false);
+        defineReadonlyValue(target, 'directory', (relativePath) => {
+            const normalized = normalizeRelativePath(relativePath);
+            const fullPath = joinRelativePath(state.prefix, normalized);
+            return this.createDirectory({
+                kind: 'directory',
+                name: basename(normalized),
+                mode: state.mode,
+                ref: {
+                    kind: 'directory',
+                    root: state.root,
+                    relativePath: fullPath,
+                },
+            });
+        }, false);
+    }
+    assertFileDescriptor(descriptor) {
+        if (!descriptor || descriptor.kind !== 'file') {
+            throw createSDKError('FILE_IO_FAILED', 'Host 返回了无效的 File descriptor');
+        }
+        assertName(descriptor.name);
+        assertMode(descriptor.mode);
+        assertFileRef(descriptor.ref);
+    }
+    assertDirectoryDescriptor(descriptor) {
+        if (!descriptor || descriptor.kind !== 'directory') {
+            throw createSDKError('FILE_IO_FAILED', 'Host 返回了无效的 Directory descriptor');
+        }
+        assertName(descriptor.name);
+        assertMode(descriptor.mode);
+        assertDirectoryRef(descriptor.ref);
+    }
+}
+function getFileHandleRegistry(requester) {
+    let registry = registries.get(requester);
+    if (!registry) {
+        registry = new MiniProgramFileHandleRegistry(requester);
+        registries.set(requester, registry);
+    }
+    return registry;
+}
+function isMiniProgramFileSystemValue(value) {
+    return !!value && typeof value === 'object' && brandedFileSystemValues.has(value);
+}
 
 const LOG_PREFIX = '[hb-sdk][network.request]';
 /**
@@ -2393,13 +2994,13 @@ function formatNetworkRequestFailureMessage(detail) {
     return `${detail.kind} ${detail.method} ${detail.url}${statusPart}${codePart}`;
 }
 
-const DEFAULT_VALIDATE_STATUS = status => status >= 200 && status < 300;
+const DEFAULT_VALIDATE_STATUS = (status) => status >= 200 && status < 300;
 function isPlainObject(value) {
     return Object.prototype.toString.call(value) === '[object Object]';
 }
 function clonePublicValue(value) {
     if (Array.isArray(value)) {
-        return value.map(item => clonePublicValue(item));
+        return value.map((item) => clonePublicValue(item));
     }
     if (isPlainObject(value)) {
         return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, clonePublicValue(item)]));
@@ -2453,11 +3054,11 @@ function toNetworkResponse(payload, config) {
 /**
  * 发起网络请求并返回标准化响应。
  *
- * @param requester 底层 bridge 请求能力。
- * @param config 面向业务层的网络请求配置。
+ * @param requester - 底层 bridge 请求能力。
+ * @param config - 面向业务层的网络请求配置。
  * @returns 标准化网络响应。HTTP 2xx 默认返回 resolve。
- * @throws {HbMiniProgramNetworkError} 当请求已完成但 HTTP 状态不满足 `validateStatus` 时抛出。
- * @throws {HbMiniProgramSDKError} 当 bridge、运行时或宿主能力调用失败时抛出。
+ * @throws {@link HbMiniProgramNetworkError} 当请求已完成但 HTTP 状态不满足 `validateStatus` 时抛出。
+ * @throws {@link HbMiniProgramSDKError} 当 bridge、运行时或宿主能力调用失败时抛出。
  *
  * @remarks
  * `validateStatus` 仅在 SDK 侧执行，不会跨 bridge 传输函数值。
@@ -2475,7 +3076,7 @@ async function request(requester, config) {
     const validateStatus = config.validateStatus || DEFAULT_VALIDATE_STATUS;
     try {
         assertSupportedPublicNetworkRequest(config);
-        const responsePayload = await requester.request(NETWORK_REQUEST_METHOD, toRequestPayload(config));
+        const responsePayload = (await requester.request(NETWORK_REQUEST_METHOD, toRequestPayload(config)));
         const response = toNetworkResponse(responsePayload, config);
         if (!validateStatus(response.status)) {
             const error = new HbMiniProgramNetworkError(response);
@@ -2523,25 +3124,319 @@ function assertSupportedPublicNetworkRequest(config) {
     if (isUnsupportedMultipartNetworkRequest(config)) {
         throw createSDKError('INVALID_PARAMS', NETWORK_REQUEST_MULTIPART_UNSUPPORTED_MESSAGE);
     }
+    if (containsUnsupportedNetworkData(config.data)) {
+        throw createSDKError('INVALID_PARAMS', 'network.request data 不支持 FileHandle、FileSystem、Blob、FormData 或二进制数据');
+    }
+}
+function containsUnsupportedNetworkData(value, visiting = new WeakSet(), scanned = new WeakSet()) {
+    if (isMiniProgramFileSystemValue(value))
+        return true;
+    if (typeof Blob !== 'undefined' && value instanceof Blob)
+        return true;
+    if (typeof FormData !== 'undefined' && value instanceof FormData)
+        return true;
+    if (value instanceof ArrayBuffer || ArrayBuffer.isView(value))
+        return true;
+    if (typeof SharedArrayBuffer !== 'undefined' && value instanceof SharedArrayBuffer)
+        return true;
+    if (!value || typeof value !== 'object' || value instanceof URLSearchParams)
+        return false;
+    if (visiting.has(value))
+        return true;
+    if (scanned.has(value))
+        return false;
+    visiting.add(value);
+    let unsupported = false;
+    if (Array.isArray(value))
+        unsupported = value.some((item) => containsUnsupportedNetworkData(item, visiting, scanned));
+    if (isPlainObject(value)) {
+        unsupported ||= Object.values(value).some((item) => containsUnsupportedNetworkData(item, visiting, scanned));
+    }
+    visiting.delete(value);
+    if (!unsupported)
+        scanned.add(value);
+    return unsupported;
+}
+function assertFinitePositive(value, name) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        throw createSDKError('INVALID_PARAMS', `${name} 必须是有限正数`);
+    }
+}
+function normalizeDownloadProgress(value) {
+    if (!value || typeof value !== 'object') {
+        throw createSDKError('INVALID_NETWORK_RESPONSE', 'network.download 返回了无效的进度');
+    }
+    if (!isMiniProgramDownloadProgressPayload(value)) {
+        throw createSDKError('INVALID_NETWORK_RESPONSE', 'network.download 返回了无效的进度');
+    }
+    return {
+        loaded: value.loaded,
+        ...(value.total === undefined ? {} : { total: value.total }),
+        lengthComputable: value.lengthComputable,
+    };
+}
+function normalizeDownloadPayload(options, to, isFileTarget) {
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+        throw createSDKError('INVALID_PARAMS', 'network.download options 必须是对象');
+    }
+    if (typeof options.url !== 'string' || options.url.length === 0) {
+        throw createSDKError('INVALID_PARAMS', 'url 必须是非空字符串');
+    }
+    if (options.params !== undefined && !isPlainObject(options.params)) {
+        throw createSDKError('INVALID_PARAMS', 'params 必须是对象');
+    }
+    if (options.headers !== undefined) {
+        if (!isPlainObject(options.headers) || Object.values(options.headers).some((value) => typeof value !== 'string')) {
+            throw createSDKError('INVALID_PARAMS', 'headers 必须是字符串字典');
+        }
+    }
+    if (options.timeout !== undefined) {
+        assertFinitePositive(options.timeout, 'timeout');
+    }
+    if (options.maxBytes !== undefined && (!Number.isSafeInteger(options.maxBytes) || options.maxBytes <= 0)) {
+        throw createSDKError('INVALID_PARAMS', 'maxBytes 必须是正的 safe integer');
+    }
+    if (options.withCredentials !== undefined && typeof options.withCredentials !== 'boolean') {
+        throw createSDKError('INVALID_PARAMS', 'withCredentials 必须是 boolean');
+    }
+    if (options.onProgress !== undefined && typeof options.onProgress !== 'function') {
+        throw createSDKError('INVALID_PARAMS', 'onProgress 必须是函数');
+    }
+    if (options.signal !== undefined &&
+        (typeof options.signal !== 'object' ||
+            typeof options.signal.aborted !== 'boolean' ||
+            typeof options.signal.addEventListener !== 'function' ||
+            typeof options.signal.removeEventListener !== 'function')) {
+        throw createSDKError('INVALID_PARAMS', 'signal 必须是 AbortSignal');
+    }
+    if ('method' in options || 'data' in options || 'body' in options) {
+        throw createSDKError('INVALID_PARAMS', 'network.download 固定使用 GET 且不接受 body');
+    }
+    const base = {
+        url: options.url,
+        to,
+        ...(options.params === undefined ? {} : { params: clonePublicValue(options.params) }),
+        ...(options.headers === undefined ? {} : { headers: clonePublicValue(options.headers) }),
+        ...(options.timeout === undefined ? {} : { timeout: options.timeout }),
+        ...(options.withCredentials === undefined ? {} : { withCredentials: options.withCredentials }),
+        ...(options.maxBytes === undefined ? {} : { maxBytes: options.maxBytes }),
+    };
+    if (isFileTarget) {
+        if (options.suggestedName !== undefined || options.overwrite !== undefined) {
+            throw createSDKError('INVALID_PARAMS', 'File target 不接受 suggestedName 或 overwrite');
+        }
+        return base;
+    }
+    if (options.overwrite !== undefined && typeof options.overwrite !== 'boolean') {
+        throw createSDKError('INVALID_PARAMS', 'overwrite 必须是 boolean');
+    }
+    let suggestedName;
+    if (options.suggestedName !== undefined) {
+        suggestedName = normalizeRelativePath(options.suggestedName);
+        if (suggestedName.includes('/')) {
+            throw createSDKError('INVALID_PARAMS', 'suggestedName 必须是 basename');
+        }
+    }
+    return {
+        ...base,
+        ...(suggestedName === undefined ? {} : { suggestedName }),
+        ...(options.overwrite === undefined ? {} : { overwrite: options.overwrite }),
+    };
+}
+function isSamePathRoot(left, right) {
+    if (left.kind !== right.kind)
+        return false;
+    return left.kind === 'sandbox' || (right.kind === 'directory' && left.handleId === right.handleId);
+}
+function isSameFileRef(left, right) {
+    if ('handleId' in left || 'handleId' in right) {
+        return 'handleId' in left && 'handleId' in right && left.handleId === right.handleId;
+    }
+    return left.relativePath === right.relativePath && isSamePathRoot(left.root, right.root);
+}
+function isDirectChildFileRef(directory, file) {
+    if ('handleId' in file)
+        return false;
+    if ('handleId' in directory) {
+        return file.root.kind === 'directory' && file.root.handleId === directory.handleId && !file.relativePath.includes('/');
+    }
+    if (!isSamePathRoot(directory.root, file.root))
+        return false;
+    const prefix = `${directory.relativePath}/`;
+    if (!file.relativePath.startsWith(prefix))
+        return false;
+    const childName = file.relativePath.slice(prefix.length);
+    return childName.length > 0 && !childName.includes('/');
+}
+function invalidDownloadResult(message) {
+    throw createSDKError('INVALID_NETWORK_RESPONSE', message);
+}
+/** 发起不使用 bridge 固定总时长 timer 的流式下载。 */
+async function download(requester, options) {
+    if (options?.signal?.aborted) {
+        throw createSDKError('DOWNLOAD_CANCELLED', '下载已取消');
+    }
+    const registry = getFileHandleRegistry(requester);
+    const isFileTarget = options?.to?.kind === 'file';
+    const target = isFileTarget ? registry.requireFile(options?.to) : registry.requireDirectory(options?.to);
+    if (target.mode !== 'readwrite') {
+        throw createSDKError('FILE_ACCESS_DENIED', '下载 target 必须是 readwrite');
+    }
+    const payload = normalizeDownloadPayload(options, target.ref, isFileTarget);
+    const result = await requester.requestOperation(NETWORK_DOWNLOAD_METHOD, payload, {
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+        ...(options.onProgress === undefined
+            ? {}
+            : {
+                onProgress: (progress) => {
+                    options.onProgress?.(normalizeDownloadProgress(progress));
+                },
+            }),
+        createAbortError: () => createSDKError('DOWNLOAD_CANCELLED', '下载已取消'),
+    });
+    const resultHandle = registry.createFile(result);
+    const resultState = registry.requireFile(resultHandle);
+    if (resultHandle.mode !== 'readwrite') {
+        invalidDownloadResult('network.download 返回的 File 不是 readwrite');
+    }
+    if (isFileTarget) {
+        const original = options.to;
+        if (resultHandle.name !== original.name || !isSameFileRef(target.ref, resultState.ref)) {
+            invalidDownloadResult('network.download 返回的 File 与 target 不一致');
+        }
+        return original;
+    }
+    if (!isDirectChildFileRef(target.ref, resultState.ref) ||
+        'handleId' in resultState.ref ||
+        resultHandle.name !== resultState.ref.relativePath.split('/').at(-1)) {
+        invalidDownloadResult('network.download 返回的 File 不在 target Directory 内');
+    }
+    return resultHandle;
 }
 /**
  * 创建 network 模块。
  *
- * @param requester 底层 bridge 请求能力。
+ * @param requester - 底层 bridge 请求能力。
  * @returns 面向业务层的网络模块对象。
  */
 function createNetworkModule(requester) {
     return {
-        request: config => request(requester, config),
+        request: (config) => request(requester, config),
+        download: (options) => download(requester, options),
     };
 }
 
+function invalidParams(message) {
+    return createSDKError('INVALID_PARAMS', message);
+}
+function normalizeMode(mode) {
+    if (mode === undefined) {
+        return undefined;
+    }
+    if (mode !== 'read' && mode !== 'readwrite') {
+        throw invalidParams('mode 必须是 read 或 readwrite');
+    }
+    return mode;
+}
+function assertOptionsObject(value, name) {
+    if (value !== undefined && (!value || typeof value !== 'object' || Array.isArray(value))) {
+        throw invalidParams(`${name} 必须是对象`);
+    }
+}
+function normalizeAccept(accept) {
+    if (accept === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(accept)) {
+        throw invalidParams('accept 必须是扩展名数组');
+    }
+    return accept.map((extension) => {
+        if (typeof extension !== 'string' ||
+            !/^\.[a-z0-9][a-z0-9._-]*$/i.test(extension)) {
+            throw invalidParams('accept 只能包含规范扩展名，例如 .json');
+        }
+        return extension;
+    });
+}
+function normalizePickFilesOptions(options) {
+    assertOptionsObject(options, 'pickFiles options');
+    if (options?.multiple !== undefined && typeof options.multiple !== 'boolean') {
+        throw invalidParams('multiple 必须是 boolean');
+    }
+    const mode = normalizeMode(options?.mode);
+    const accept = normalizeAccept(options?.accept);
+    if (options === undefined) {
+        return undefined;
+    }
+    return {
+        ...(mode === undefined ? {} : { mode }),
+        ...(accept === undefined ? {} : { accept }),
+        ...(options.multiple === undefined ? {} : { multiple: options.multiple }),
+    };
+}
+function normalizePickDirectoryOptions(options) {
+    assertOptionsObject(options, 'pickDirectory options');
+    const mode = normalizeMode(options?.mode);
+    return options === undefined ? undefined : mode === undefined ? {} : { mode };
+}
+function normalizeSaveFileOptions(options) {
+    assertOptionsObject(options, 'saveFile options');
+    if (!options || typeof options.suggestedName !== 'string') {
+        throw invalidParams('suggestedName 必须是非空字符串');
+    }
+    const suggestedName = normalizeRelativePath(options.suggestedName);
+    if (suggestedName.includes('/')) {
+        throw invalidParams('suggestedName 必须是 basename');
+    }
+    if ('accept' in options) {
+        throw invalidParams('saveFile V1 不支持 accept');
+    }
+    return { suggestedName };
+}
+/** 创建当前 SDK session 的 files 模块。 */
+function createFilesModule(requester) {
+    const registry = getFileHandleRegistry(requester);
+    return Object.freeze({
+        sandbox: registry.getSandbox(),
+        async pickFiles(options) {
+            const normalizedOptions = normalizePickFilesOptions(options);
+            const descriptors = await requester.request(FILES_PICK_FILES_METHOD, normalizedOptions);
+            if (!Array.isArray(descriptors) || descriptors.length === 0 || (normalizedOptions?.multiple !== true && descriptors.length > 1)) {
+                throw createSDKError('FILE_IO_FAILED', 'Host 返回了无效的 picker 结果');
+            }
+            const expectedMode = normalizedOptions?.mode ?? 'read';
+            const handles = descriptors.map((descriptor) => registry.createDirectFile(descriptor));
+            if (handles.some((handle) => handle.mode !== expectedMode)) {
+                throw createSDKError('FILE_IO_FAILED', 'Host 返回的 File mode 与 picker 请求不一致');
+            }
+            return handles;
+        },
+        async pickDirectory(options) {
+            const normalizedOptions = normalizePickDirectoryOptions(options);
+            const descriptor = await requester.request(FILES_PICK_DIRECTORY_METHOD, normalizedOptions);
+            const handle = registry.createDirectDirectory(descriptor);
+            if (handle.mode !== (normalizedOptions?.mode ?? 'read')) {
+                throw createSDKError('FILE_IO_FAILED', 'Host 返回的 Directory mode 与 picker 请求不一致');
+            }
+            return handle;
+        },
+        async saveFile(options) {
+            const descriptor = await requester.request(FILES_SAVE_FILE_METHOD, normalizeSaveFileOptions(options));
+            const handle = registry.createDirectFile(descriptor);
+            if (handle.mode !== 'readwrite') {
+                throw createSDKError('FILE_IO_FAILED', 'Host 返回的 saveFile 不是 readwrite 授权');
+            }
+            return handle;
+        },
+    });
+}
+
 /**
  * 获取当前小程序窗口信息。
  *
- * @param requester 底层 bridge 请求能力。
+ * @param requester - 底层 bridge 请求能力。
  * @returns 当前小程序可用窗口信息。
- * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ * @throws {@link HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
  */
 function getWindowInfo(requester) {
     return requester.request(VIEWPORT_GET_WINDOW_INFO_METHOD);
@@ -2549,10 +3444,10 @@ function getWindowInfo(requester) {
 /**
  * 设置导航栏关闭按钮与状态栏图标/文字的前景样式。
  *
- * @param requester 底层 bridge 请求能力。
- * @param options 导航栏样式配置。
+ * @param requester - 底层 bridge 请求能力。
+ * @param options - 导航栏样式配置。
  * @returns 宿主接受设置后 resolve。
- * @throws {HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
+ * @throws {@link HbMiniProgramSDKError} 当 bridge、父容器或宿主能力调用失败时抛出。
  */
 function setNavigationBarStyle(requester, options) {
     return requester.request(VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, options);
@@ -2560,13 +3455,13 @@ function setNavigationBarStyle(requester, options) {
 /**
  * 创建 Viewport 模块。
  *
- * @param requester 底层 bridge 请求能力。
+ * @param requester - 底层 bridge 请求能力。
  * @returns 面向业务层的 Viewport 模块对象。
  */
 function createViewportModule(requester) {
     return {
         getWindowInfo: () => getWindowInfo(requester),
-        setNavigationBarStyle: options => setNavigationBarStyle(requester, options),
+        setNavigationBarStyle: (options) => setNavigationBarStyle(requester, options),
     };
 }
 
@@ -2579,7 +3474,7 @@ function createViewportModule(requester) {
  * `app_user_id`，并隐式授予 `identity` 与 `profile` 后返回昵称与头像，不展示授权 UI。未登录时返回
  * `{ isHeyboxAppLoggedIn: false, authorization: null, userInfo: null }`。
  *
- * @throws {HbMiniProgramSDKError} 当 SDK 调用失败时抛出。
+ * @throws {@link HbMiniProgramSDKError} 当 SDK 调用失败时抛出。
  */
 function getInfo(requester) {
     return requester.request(USER_GET_INFO_METHOD);
@@ -2592,8 +3487,8 @@ function revokeAuthorization(requester) {
 /**
  * 获取当前用户 Steam 游戏库。
  *
- * @param requester 底层 bridge 请求能力。
- * @param options 查询与分页参数。
+ * @param requester - 底层 bridge 请求能力。
+ * @param options - 查询与分页参数。
  * @returns 当前用户 Steam 游戏库；未登录或未绑定 Steam 时返回状态对象。
  */
 function getSteamGameList(requester, options) {
@@ -2623,8 +3518,8 @@ function hideLoading(requester) {
 /** 创建 UI 模块。 */
 function createUiModule(requester) {
     return {
-        showToast: options => showToast(requester, options),
-        showLoading: options => showLoading(requester, options),
+        showToast: (options) => showToast(requester, options),
+        showLoading: (options) => showLoading(requester, options),
         hideLoading: () => hideLoading(requester),
     };
 }
@@ -2640,8 +3535,8 @@ function setClipboard(requester, options) {
 /** 创建设备能力模块。 */
 function createDeviceModule(requester) {
     return {
-        vibrate: options => vibrate(requester, options),
-        setClipboard: options => setClipboard(requester, options),
+        vibrate: (options) => vibrate(requester, options),
+        setClipboard: (options) => setClipboard(requester, options),
     };
 }
 
@@ -2752,7 +3647,7 @@ function createNavigationModule(requester) {
     return {
         close: () => close(requester),
         reload: () => reload(requester),
-        openAppPage: options => openAppPage(requester, options),
+        openAppPage: (options) => openAppPage(requester, options),
     };
 }
 
@@ -2782,6 +3677,8 @@ class MiniProgramSDK {
     storage;
     /** 网络请求相关开放能力。 */
     network;
+    /** 受控文件与目录能力。 */
+    files;
     /** UI 交互相关开放能力。 */
     ui;
     /** 设备相关开放能力。 */
@@ -2798,6 +3695,7 @@ class MiniProgramSDK {
         this.share = createShareModule(this.client, launchHref);
         this.viewport = createViewportModule(this.client);
         this.storage = createStorageModule(this.client);
+        this.files = createFilesModule(this.client);
         this.network = createNetworkModule(this.client);
         this.ui = createUiModule(this.client);
         this.device = createDeviceModule(this.client);
@@ -2815,8 +3713,8 @@ class MiniProgramSDK {
     /**
      * 注册小程序生命周期或业务事件。
      *
-     * @param eventName 要监听的事件名。
-     * @param handler 事件处理函数。
+     * @param eventName - 要监听的事件名。
+     * @param handler - 事件处理函数。
      * @returns 事件解绑函数。
      */
     on(eventName, handler) {
@@ -2825,8 +3723,8 @@ class MiniProgramSDK {
     /**
      * 移除小程序生命周期或业务事件。
      *
-     * @param eventName 要移除的事件名。
-     * @param handler 对应的事件处理函数。
+     * @param eventName - 要移除的事件名。
+     * @param handler - 对应的事件处理函数。
      */
     off(eventName, handler) {
         this.client.off(eventName, handler);
@@ -2845,7 +3743,7 @@ class MiniProgramSDK {
 /**
  * 创建独立 SDK 实例。
  *
- * @param options SDK 运行配置，例如超时时间、nonce 或测试环境注入的 window。
+ * @param options - SDK 运行配置，例如超时时间、nonce 或测试环境注入的 window。
  * @returns 可独立管理生命周期的 `MiniProgramSDK` 实例。
  *
  * @remarks
@@ -2871,20 +3769,59 @@ function getDefaultSDK() {
     }
     return defaultSDK;
 }
-/** 获取默认 SDK 实例的当前握手状态。 */
+/**
+ * 获取默认 SDK 实例的当前握手状态。
+ *
+ * @since 0.7.0-alpha.9
+ * @hbPlatform android
+ * @hbPlatform ios
+ * @hbPlatform ohos
+ * @hbPlatform windows
+ * @hbPlatform macos
+ * @hbClient android none
+ * @hbClient ios none
+ * @hbClient ohos none
+ * @hbClient windows none
+ * @hbClient macos none
+ */
 function getHandshakeState() {
     return getDefaultSDK().getHandshakeState();
 }
-/** 订阅默认 SDK 实例的握手状态，并立即接收当前状态。 */
+/**
+ * 订阅默认 SDK 实例的握手状态，并立即接收当前状态。
+ *
+ * @since 0.7.0-alpha.9
+ * @hbPlatform android
+ * @hbPlatform ios
+ * @hbPlatform ohos
+ * @hbPlatform windows
+ * @hbPlatform macos
+ * @hbClient android none
+ * @hbClient ios none
+ * @hbClient ohos none
+ * @hbClient windows none
+ * @hbClient macos none
+ */
 function onHandshakeStateChange(handler) {
     return getDefaultSDK().onHandshakeStateChange(handler);
 }
 /**
  * 注册默认 SDK 实例的事件监听。
  *
- * @param eventName 要监听的事件名。
- * @param handler 事件处理函数。
+ * @param eventName - 要监听的事件名。
+ * @param handler - 事件处理函数。
  * @returns 事件解绑函数。
+ * @since 0.2.0-alpha.0
+ * @hbPlatform android
+ * @hbPlatform ios
+ * @hbPlatform ohos
+ * @hbPlatform windows
+ * @hbPlatform macos
+ * @hbClient android none
+ * @hbClient ios none
+ * @hbClient ohos none
+ * @hbClient windows none
+ * @hbClient macos none
  */
 function on(eventName, handler) {
     return getDefaultSDK().on(eventName, handler);
@@ -2892,9 +3829,20 @@ function on(eventName, handler) {
 /**
  * 移除默认 SDK 实例的事件监听。
  *
- * @param eventName 要移除的事件名。
- * @param handler 对应的事件处理函数。
+ * @param eventName - 要移除的事件名。
+ * @param handler - 对应的事件处理函数。
  * @returns 无返回值。
+ * @since 0.2.0-alpha.0
+ * @hbPlatform android
+ * @hbPlatform ios
+ * @hbPlatform ohos
+ * @hbPlatform windows
+ * @hbPlatform macos
+ * @hbClient android none
+ * @hbClient ios none
+ * @hbClient ohos none
+ * @hbClient windows none
+ * @hbClient macos none
  */
 function off(eventName, handler) {
     getDefaultSDK().off(eventName, handler);
@@ -2929,6 +3877,16 @@ const storage = {
 /** 默认 SDK 实例的 network 模块。 */
 const network = {
     request: (config) => getDefaultSDK().network.request(config),
+    download: (options) => getDefaultSDK().network.download(options),
+};
+/** 默认 SDK 实例的 files 模块。 */
+const files = {
+    get sandbox() {
+        return getDefaultSDK().files.sandbox;
+    },
+    pickFiles: (options) => getDefaultSDK().files.pickFiles(options),
+    pickDirectory: (options) => getDefaultSDK().files.pickDirectory(options),
+    saveFile: (options) => getDefaultSDK().files.saveFile(options),
 };
 /** 默认 SDK 实例的 UI 模块。 */
 const ui = {
@@ -2968,6 +3926,7 @@ const hbSDK = {
     share,
     viewport,
     storage,
+    files,
     network,
     ui,
     device,
@@ -2975,4 +3934,4 @@ const hbSDK = {
     cloud,
 };
 
-export { HbMiniProgramNetworkError, HbMiniProgramSDKError, USER_INFO_AUTHORIZATION_SCOPES, auth, cloud, hbSDK as default, device, getHandshakeState, navigation, network, off, on, onHandshakeStateChange, share, storage, ui, user, viewport };
+export { HbMiniProgramNetworkError, HbMiniProgramSDKError, USER_INFO_AUTHORIZATION_SCOPES, auth, cloud, hbSDK as default, device, files, getHandshakeState, navigation, network, off, on, onHandshakeStateChange, share, storage, ui, user, viewport };