@heybox/hb-sdk 0.9.3-alpha.6 → 0.9.3

package/dist/index.esm.js

@@ -440,6 +440,7 @@ 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 MEDIA_PICK_METHOD = 'media.pick';
 const UI_SHOW_TOAST_METHOD = 'ui.showToast';
 const UI_SHOW_LOADING_METHOD = 'ui.showLoading';
 const UI_HIDE_LOADING_METHOD = 'ui.hideLoading';
@@ -837,6 +838,184 @@ function isMiniProgramDirectoryRef(value) {
     }
     return (isMiniProgramPathRootRef(value.root) && (value.relativePath === '.' || isMiniProgramRelativePath(value.relativePath)) && hasOnlyKeys(value, ['kind', 'root', 'relativePath']));
 }
+/**
+ * 判断未知值是否具有文件 descriptor 的最低 wire 结构。
+ *
+ * @param value - 来自 Host、bridge response、目录列表或其他不可信边界的候选 descriptor。
+ * @returns 顶层字段及嵌套文件引用都满足协议结构时返回 `true`，并将 TypeScript 类型收窄为
+ * {@link MiniProgramFileDescriptor}；否则返回 `false`。
+ *
+ * @remarks
+ * guard 会读取并校验以下四个属性；对通常的对象字面量，它们也是唯一允许的可枚举自有字符串字段：
+ *
+ * - `kind`：固定为 `'file'`。
+ * - `name`：非空字符串。该 guard 不检查空白、`.`、`..`、`/`、反斜杠、控制字符、平台保留名或
+ *   `name` 是否等于 `ref.relativePath` 的 basename；SDK 创建 `FileHandle` 时还会执行更严格的名称校验。
+ * - `mode`：只能是 `'read'` 或 `'readwrite'`。这是 descriptor 声明值，不证明 Host 实际授予了读写权限。
+ * - `ref`：必须通过 {@link isMiniProgramFileRef}。
+ *
+ * `ref` 可以是 `{ kind: 'file', handleId }` 形式的 direct file ref，其中 `handleId` 只要求非空；也可以是
+ * `{ kind: 'file', root, relativePath }` 形式的 derived ref。derived root 只能是精确的 sandbox root 或
+ * 带非空 `handleId` 的 direct directory root，不能是 file ref 或再次派生的 directory ref；`relativePath`
+ * 必须是非空、非绝对、无尾随 `/`、无空段、`.` / `..` 点段、反斜杠或控制字符的相对路径。与目录 ref
+ * 不同，文件 ref 不接受 `relativePath: '.'`，因为它必须指向 root 下的具体文件。
+ *
+ * 顶层 descriptor、`ref` 与 `root` 的额外可枚举自有字符串键都会导致失败，包括值为 `undefined` 的额外键；
+ * 非枚举属性、symbol 键和继承属性不在 `Object.keys()` 检查范围内，必需属性本身也不要求是自有或可枚举
+ * 属性。该函数不会复制、冻结或规范化输入。
+ *
+ * 返回 `true` 只建立结构类型收窄，不证明 direct `handleId` 或 root handle 由当前 Runtime 签发、属于当前
+ * session/origin、仍然有效且确为预期类型，也不证明文件存在、名称真实、`filesystem` 权限已启用、mode
+ * 允许当前操作或 Host 支持对应 capability。实际文件操作仍须由 Runtime 查询 handle registry、执行权限、
+ * provenance、目标类型和存在性校验。
+ *
+ * {@link isMiniProgramFileSystemEntityDescriptor} 使用本 guard 与目录 descriptor guard 识别目录列表项。
+ * `files.pickFiles()` 与 `files.saveFile()` 的成功结果要求更窄的 direct file ref，而 sandbox/path API 返回的
+ * descriptor 可以使用 derived ref；本 guard 本身不会区分 descriptor 的来源。
+ *
+ * @example
+ * ```ts
+ * import { isMiniProgramFileDescriptor } from '@heybox/hb-sdk/protocol';
+ *
+ * const candidate = {
+ *   kind: 'file',
+ *   name: 'report.json',
+ *   mode: 'readwrite',
+ *   ref: {
+ *     kind: 'file',
+ *     root: { kind: 'sandbox' },
+ *     relativePath: 'exports/report.json',
+ *   },
+ * };
+ * const untrusted: unknown = candidate;
+ *
+ * if (isMiniProgramFileDescriptor(untrusted)) {
+ *   // 这里只能安全读取 wire 字段；文件 I/O 仍交给 files API/Runtime。
+ *   console.log(untrusted.name, untrusted.mode, untrusted.ref);
+ * }
+ *
+ * isMiniProgramFileDescriptor({ ...candidate, size: 1024 }); // false：顶层存在额外键
+ * ```
+ *
+ * @see [MiniProgramFileDescriptor](/reference/symbols/protocol/interfaces/MiniProgramFileDescriptor) descriptor 字段类型。
+ * @see [isMiniProgramFileRef](/reference/symbols/protocol/functions/isMiniProgramFileRef) 嵌套 direct/derived 文件引用校验。
+ * @see [isMiniProgramFileSystemEntityDescriptor](/reference/symbols/protocol/functions/isMiniProgramFileSystemEntityDescriptor) 文件与目录 descriptor 联合 guard。
+ * @see [FileHandle](/reference/symbols/root/interfaces/FileHandle) 校验后由 SDK 建立的文件代理。
+ * @see [PickFilesResult](/reference/symbols/protocol/types/PickFilesResult) picker 的 direct-ref 文件结果。
+ * @see [SaveFileResult](/reference/symbols/protocol/types/SaveFileResult) save picker 的 direct-ref 文件结果。
+ * @since 0.8.0
+ */
+function isMiniProgramFileDescriptor(value) {
+    return (isRecord$3(value) &&
+        value.kind === 'file' &&
+        isNonEmptyString$1(value.name) &&
+        isFileMode(value.mode) &&
+        isMiniProgramFileRef(value.ref) &&
+        hasOnlyKeys(value, ['kind', 'name', 'mode', 'ref']));
+}
+/** `media.pick` 结果数组允许的最大项数，与协议 `maxCount` 上限一致。 */
+const MAX_MEDIA_PICK_COUNT = 20;
+/** `media.pick` 单项结果的公共 canonical key 集合。 */
+const MEDIA_PICK_ITEM_KEYS = ['type', 'mimeType', 'size', 'width', 'height', 'previewUrl', 'file'];
+/**
+ * 判断未知值是否为单个 `media.pick` 媒体项。
+ *
+ * @param value - 来自 Host response、bridge result 或其他不可信边界的候选媒体项。
+ * @returns 字段组合满足 {@link MediaPickItem} 判别联合的最低结构时返回 `true`，并将 TypeScript 类型
+ * 收窄为图片或视频项；否则返回 `false`。
+ *
+ * @remarks
+ * 以 `type` 为判别字段，两个分支都要求 `mimeType` 非空字符串、`size` 为非负安全整数、`width` /
+ * `height` 为正安全整数、`previewUrl` 非空字符串，且 `file` 是通过
+ * {@link isMiniProgramFileDescriptor} 的 direct file ref（`ref.kind === 'file'` 且带非空 `handleId`），
+ * `mode` 必须固定为 `'read'`。图片分支只允许公共 key；视频分支额外要求非负安全整数的 `durationMs`，
+ * 并拒绝图片携带该字段。
+ *
+ * `size` 单位为字节，`width` / `height` 是考虑方向后的显示像素尺寸，`durationMs` 单位为毫秒。
+ * 该 guard 只校验结构与数值范围，不证明元数据与 `file` 实际内容一致、`previewUrl` 属于当前会话、
+ * `file` 句柄由当前 Runtime 签发或仍在有效期内，也不检查 `media` 权限与 Host 能力。
+ *
+ * @example
+ * ```ts
+ * import { isMiniProgramMediaPickItem } from '@heybox/hb-sdk/protocol';
+ *
+ * const video = {
+ *   type: 'video',
+ *   mimeType: 'video/mp4',
+ *   size: 5_242_880,
+ *   width: 1280,
+ *   height: 720,
+ *   durationMs: 12_000,
+ *   previewUrl: 'hb-media-preview://session/resource_2',
+ *   file: { kind: 'file', name: 'clip.mp4', mode: 'read', ref: { kind: 'file', handleId: 'media_handle_2' } },
+ * };
+ *
+ * isMiniProgramMediaPickItem(video); // true
+ * isMiniProgramMediaPickItem({ ...video, type: 'image' }); // false：图片不允许 durationMs
+ * ```
+ *
+ * @see [MediaPickItem](/reference/symbols/protocol/types/MediaPickItem) 判别联合定义。
+ * @see [isMiniProgramFileDescriptor](/reference/symbols/protocol/functions/isMiniProgramFileDescriptor) 嵌套文件句柄校验。
+ * @since 0.9.3
+ */
+function isMiniProgramMediaPickItem(value) {
+    if (!isRecord$3(value) || (value.type !== 'image' && value.type !== 'video'))
+        return false;
+    const isVideo = value.type === 'video';
+    if (!hasOnlyKeys(value, isVideo ? [...MEDIA_PICK_ITEM_KEYS, 'durationMs'] : MEDIA_PICK_ITEM_KEYS))
+        return false;
+    if (!isNonEmptyString$1(value.mimeType) ||
+        !isNonNegativeSafeInteger(value.size) ||
+        !isPositiveSafeInteger$1(value.width) ||
+        !isPositiveSafeInteger$1(value.height) ||
+        !isNonEmptyString$1(value.previewUrl) ||
+        !isDirectFileDescriptor(value.file)) {
+        return false;
+    }
+    return isVideo ? isNonNegativeSafeInteger(value.durationMs) : true;
+}
+/**
+ * 判断未知值是否为整批 `media.pick` 结果。
+ *
+ * @param value - 来自 Host response、bridge result 或其他不可信边界的候选结果。
+ * @returns 值为 1–20 项且每项都通过 {@link isMiniProgramMediaPickItem} 的稠密数组时返回 `true`，
+ * 并将 TypeScript 类型收窄为 {@link MediaPickResult}；否则返回 `false`。
+ *
+ * @remarks
+ * 成功结果必须是非空数组：用户取消或任一项准备失败时走整批错误，不得返回空数组或部分结果。
+ * 本 guard 只校验全局上限 20，不校验调用方本次请求的 `maxCount`、相机必须恰好 1 项、项之间是否
+ * 重复或顺序，也不确认结果来自当前 request 或会话仍然有效。这些约束由 Runtime 的状态机、可信手势、
+ * 权限与句柄注册表继续执行。
+ *
+ * @example
+ * ```ts
+ * import { isMiniProgramMediaPickResult } from '@heybox/hb-sdk/protocol';
+ *
+ * isMiniProgramMediaPickResult([]); // false：取消不是空数组成功
+ * isMiniProgramMediaPickResult([imageItem]); // true
+ * ```
+ *
+ * @see [MediaPickResult](/reference/symbols/protocol/types/MediaPickResult) wire 返回类型。
+ * @see [isMiniProgramMediaPickItem](/reference/symbols/protocol/functions/isMiniProgramMediaPickItem) 单项结构与数值校验。
+ * @since 0.9.3
+ */
+function isMiniProgramMediaPickResult(value) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > MAX_MEDIA_PICK_COUNT)
+        return false;
+    for (let index = 0; index < value.length; index += 1) {
+        if (!Object.prototype.hasOwnProperty.call(value, index) || !isMiniProgramMediaPickItem(value[index]))
+            return false;
+    }
+    return true;
+}
+function isDirectFileDescriptor(value) {
+    if (!isMiniProgramFileDescriptor(value))
+        return false;
+    // 媒体结果只允许只读 direct 句柄；derived ref、readwrite 与目录引用都不符合媒体契约。
+    if (value.mode !== 'read')
+        return false;
+    return value.ref.kind === 'file' && 'handleId' in value.ref && isNonEmptyString$1(value.ref.handleId);
+}
 /**
  * 判断未知值是否为使用普通 `ArrayBuffer` 存储的 `Uint8Array` 字节视图。
  *
@@ -1046,9 +1225,15 @@ function isSDKHandshakePayload(value) {
 function isBridgeError(value) {
     return isRecord$3(value) && isNonEmptyString$1(value.code) && typeof value.message === 'string';
 }
+function isFileMode(value) {
+    return value === 'read' || value === 'readwrite';
+}
 function isNonNegativeSafeInteger(value) {
     return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
 }
+function isPositiveSafeInteger$1(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}
 function isNonNegativeFiniteNumber(value) {
     return typeof value === 'number' && Number.isFinite(value) && value >= 0;
 }
@@ -1070,6 +1255,7 @@ const MINI_PROGRAM_PERMISSION_KEYS = [
     'storage',
     'cloud_storage',
     'filesystem',
+    'media',
     'clipboard',
     'leaderboard',
     'network',
@@ -7295,7 +7481,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.3-alpha.6';
+    : '0.9.3';
 
 const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
 const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);
@@ -7916,7 +8102,7 @@ function createCloudModule(requester) {
 const registries = new WeakMap();
 const brandedFileSystemValues = new WeakSet();
 const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/;
-function invalidParams$1(message, data) {
+function invalidParams$2(message, data) {
     return createSDKError('INVALID_PARAMS', message, data);
 }
 function clonePathRootRef(ref) {
@@ -7991,13 +8177,13 @@ function assertSandboxRef(ref) {
 }
 function normalizeCreateOptions(options) {
     if (options !== undefined && (!options || typeof options !== 'object' || Array.isArray(options))) {
-        throw invalidParams$1('create options 必须是对象');
+        throw invalidParams$2('create options 必须是对象');
     }
     if (options?.recursive !== undefined && typeof options.recursive !== 'boolean') {
-        throw invalidParams$1('recursive 必须是 boolean');
+        throw invalidParams$2('recursive 必须是 boolean');
     }
     if (options?.exclusive !== undefined && typeof options.exclusive !== 'boolean') {
-        throw invalidParams$1('exclusive 必须是 boolean');
+        throw invalidParams$2('exclusive 必须是 boolean');
     }
     return {
         recursive: options?.recursive ?? false,
@@ -8006,28 +8192,28 @@ function normalizeCreateOptions(options) {
 }
 function normalizeListOptions(options) {
     if (options !== undefined && (!options || typeof options !== 'object' || Array.isArray(options))) {
-        throw invalidParams$1('list options 必须是对象');
+        throw invalidParams$2('list options 必须是对象');
     }
     if (options?.limit !== undefined && (!Number.isSafeInteger(options.limit) || options.limit <= 0)) {
-        throw invalidParams$1('limit 必须是正的 safe integer');
+        throw invalidParams$2('limit 必须是正的 safe integer');
     }
     return options?.limit;
 }
 function normalizeRemoveOptions(options) {
     if (options !== undefined && (!options || typeof options !== 'object' || Array.isArray(options))) {
-        throw invalidParams$1('remove options 必须是对象');
+        throw invalidParams$2('remove options 必须是对象');
     }
     if (options?.recursive !== undefined && typeof options.recursive !== 'boolean') {
-        throw invalidParams$1('recursive 必须是 boolean');
+        throw invalidParams$2('recursive 必须是 boolean');
     }
     return { recursive: options?.recursive ?? false };
 }
 function cloneBytes$1(content) {
     if (!(content instanceof Uint8Array)) {
-        throw invalidParams$1('content 必须是 Uint8Array');
+        throw invalidParams$2('content 必须是 Uint8Array');
     }
     if (typeof SharedArrayBuffer !== 'undefined' && content.buffer instanceof SharedArrayBuffer) {
-        throw invalidParams$1('content 不能由 SharedArrayBuffer 承载');
+        throw invalidParams$2('content 不能由 SharedArrayBuffer 承载');
     }
     return new Uint8Array(content);
 }
@@ -8045,7 +8231,7 @@ function normalizeStat(stat) {
 /** 校验并返回平台无关的 `/` 分隔逻辑相对路径。 */
 function normalizeRelativePath(value) {
     if (!isMiniProgramRelativePath(value)) {
-        throw invalidParams$1('relativePath 必须是规范的 `/` 分隔逻辑相对路径');
+        throw invalidParams$2('relativePath 必须是规范的 `/` 分隔逻辑相对路径');
     }
     return value;
 }
@@ -8112,7 +8298,7 @@ class MiniProgramFileHandleRegistry {
         defineReadonlyValue(handle, 'writeText', async (content) => {
             assertWritable(state.mode);
             if (typeof content !== 'string') {
-                throw invalidParams$1('content 必须是 string');
+                throw invalidParams$2('content 必须是 string');
             }
             await this.requester.request(FILE_WRITE_TEXT_METHOD, { target: state.ref, content });
         }, false);
@@ -8214,14 +8400,14 @@ class MiniProgramFileHandleRegistry {
     requireFile(handle) {
         const state = handle && typeof handle === 'object' ? this.fileStates.get(handle) : undefined;
         if (!state) {
-            throw invalidParams$1('to 必须是当前 SDK session 创建的 FileHandle');
+            throw invalidParams$2('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');
+            throw invalidParams$2('to 必须是当前 SDK session 创建的 DirectoryHandle');
         }
         return state;
     }
@@ -10859,7 +11045,7 @@ async function upload(requester, options) {
     return response;
 }
 
-function invalidParams(message) {
+function invalidParams$1(message) {
     return createSDKError('INVALID_PARAMS', message);
 }
 function normalizeMode(mode) {
@@ -10867,13 +11053,13 @@ function normalizeMode(mode) {
         return undefined;
     }
     if (mode !== 'read' && mode !== 'readwrite') {
-        throw invalidParams('mode 必须是 read 或 readwrite');
+        throw invalidParams$1('mode 必须是 read 或 readwrite');
     }
     return mode;
 }
-function assertOptionsObject(value, name) {
+function assertOptionsObject$1(value, name) {
     if (value !== undefined && (!value || typeof value !== 'object' || Array.isArray(value))) {
-        throw invalidParams(`${name} 必须是对象`);
+        throw invalidParams$1(`${name} 必须是对象`);
     }
 }
 function normalizeAccept(accept) {
@@ -10881,20 +11067,20 @@ function normalizeAccept(accept) {
         return undefined;
     }
     if (!Array.isArray(accept)) {
-        throw invalidParams('accept 必须是扩展名数组');
+        throw invalidParams$1('accept 必须是扩展名数组');
     }
     return accept.map((extension) => {
         if (typeof extension !== 'string' ||
             !/^\.[a-z0-9][a-z0-9._-]*$/i.test(extension)) {
-            throw invalidParams('accept 只能包含规范扩展名，例如 .json');
+            throw invalidParams$1('accept 只能包含规范扩展名，例如 .json');
         }
         return extension;
     });
 }
 function normalizePickFilesOptions(options) {
-    assertOptionsObject(options, 'pickFiles options');
+    assertOptionsObject$1(options, 'pickFiles options');
     if (options?.multiple !== undefined && typeof options.multiple !== 'boolean') {
-        throw invalidParams('multiple 必须是 boolean');
+        throw invalidParams$1('multiple 必须是 boolean');
     }
     const mode = normalizeMode(options?.mode);
     const accept = normalizeAccept(options?.accept);
@@ -10908,21 +11094,21 @@ function normalizePickFilesOptions(options) {
     };
 }
 function normalizePickDirectoryOptions(options) {
-    assertOptionsObject(options, 'pickDirectory options');
+    assertOptionsObject$1(options, 'pickDirectory options');
     const mode = normalizeMode(options?.mode);
     return options === undefined ? undefined : mode === undefined ? {} : { mode };
 }
 function normalizeSaveFileOptions(options) {
-    assertOptionsObject(options, 'saveFile options');
+    assertOptionsObject$1(options, 'saveFile options');
     if (!options || typeof options.suggestedName !== 'string') {
-        throw invalidParams('suggestedName 必须是非空字符串');
+        throw invalidParams$1('suggestedName 必须是非空字符串');
     }
     const suggestedName = normalizeRelativePath(options.suggestedName);
     if (suggestedName.includes('/')) {
-        throw invalidParams('suggestedName 必须是 basename');
+        throw invalidParams$1('suggestedName 必须是 basename');
     }
     if ('accept' in options) {
-        throw invalidParams('saveFile V1 不支持 accept');
+        throw invalidParams$1('saveFile V1 不支持 accept');
     }
     return { suggestedName };
 }
@@ -10964,6 +11150,97 @@ function createFilesModule(requester) {
     });
 }
 
+const MEDIA_SOURCES = ['album', 'camera'];
+const MEDIA_SELECTION_TYPES = ['image', 'video', 'all'];
+const MEDIA_PICK_MAX_COUNT = 20;
+const MEDIA_PICK_OPTION_KEYS = ['source', 'mediaType', 'maxCount'];
+function invalidParams(message) {
+    return createSDKError('INVALID_PARAMS', message);
+}
+function assertOptionsObject(value) {
+    if (value !== undefined && (!value || typeof value !== 'object' || Array.isArray(value))) {
+        throw invalidParams('pick options 必须是对象');
+    }
+}
+function assertKnownKeys(options) {
+    for (const key of Object.keys(options)) {
+        if (!MEDIA_PICK_OPTION_KEYS.includes(key)) {
+            throw invalidParams(`pick options 包含未知字段 ${key}`);
+        }
+    }
+}
+function normalizeSource(value) {
+    if (value === undefined) {
+        return 'album';
+    }
+    if (typeof value !== 'string' || !MEDIA_SOURCES.includes(value)) {
+        throw invalidParams('source 必须是 album 或 camera');
+    }
+    return value;
+}
+function normalizeSelectionType(value) {
+    if (value === undefined) {
+        return 'all';
+    }
+    if (typeof value !== 'string' || !MEDIA_SELECTION_TYPES.includes(value)) {
+        throw invalidParams('mediaType 必须是 image、video 或 all');
+    }
+    return value;
+}
+function normalizeMaxCount(value, source) {
+    if (value === undefined) {
+        return 1;
+    }
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1 || value > MEDIA_PICK_MAX_COUNT) {
+        throw invalidParams(`maxCount 必须是 1 到 ${MEDIA_PICK_MAX_COUNT} 的安全整数`);
+    }
+    if (source === 'camera' && value > 1) {
+        throw invalidParams('camera 的 maxCount 只能是 1');
+    }
+    return value;
+}
+/** 把公开选项收窄为 wire payload，缺省值显式补齐且不携带 undefined 键。 */
+function normalizePickOptions(options) {
+    assertOptionsObject(options);
+    if (options === undefined) {
+        return { source: 'album', mediaType: 'all', maxCount: 1 };
+    }
+    const raw = options;
+    assertKnownKeys(raw);
+    const source = normalizeSource(raw.source);
+    const mediaType = normalizeSelectionType(raw.mediaType);
+    const maxCount = normalizeMaxCount(raw.maxCount, source);
+    return { source, mediaType, maxCount };
+}
+/** 创建当前 SDK session 的 media 模块。 */
+function createMediaModule(requester) {
+    const registry = getFileHandleRegistry(requester);
+    return Object.freeze({
+        async pick(options) {
+            const payload = normalizePickOptions(options);
+            // 图库选择与拍摄等待用户确认，不使用普通请求的固定超时；销毁仍沿用 bridge cancel。
+            const result = await requester.requestOperation(MEDIA_PICK_METHOD, payload);
+            if (!isMiniProgramMediaPickResult(result)) {
+                throw createSDKError('FILE_IO_FAILED', 'Host 返回了无效的媒体 picker 结果');
+            }
+            if (result.length > payload.maxCount) {
+                throw createSDKError('FILE_IO_FAILED', 'Host 返回的媒体项数量超过本次请求上限');
+            }
+            if (payload.source === 'camera' && result.length !== 1) {
+                throw createSDKError('FILE_IO_FAILED', 'Host 返回的相机结果必须恰好一项');
+            }
+            const items = result.map((item) => {
+                const handle = registry.createDirectFile(item.file);
+                if (handle.mode !== 'read') {
+                    throw createSDKError('FILE_IO_FAILED', 'Host 返回的媒体 File mode 不是 read');
+                }
+                return Object.freeze({ ...item, file: handle });
+            });
+            return Object.freeze(items);
+        },
+    });
+}
+
 /**
  * 获取当前小程序窗口信息。
  *
@@ -11349,6 +11626,8 @@ class MiniProgramSDK {
     network;
     /** 受控文件与目录能力。 */
     files;
+    /** 受控媒体选择能力。 */
+    media;
     /** UI 交互相关开放能力。 */
     ui;
     /** 设备相关开放能力。 */
@@ -11373,6 +11652,7 @@ class MiniProgramSDK {
         this.viewport = createViewportModule(this.client);
         this.storage = createStorageModule(this.client);
         this.files = createFilesModule(this.client);
+        this.media = createMediaModule(this.client);
         this.network = createNetworkModule(this.client);
         this.ui = createUiModule(this.client);
         this.device = createDeviceModule(this.client);
@@ -11917,6 +12197,10 @@ const files = {
     pickDirectory: (options) => getDefaultSDK().files.pickDirectory(options),
     saveFile: (options) => getDefaultSDK().files.saveFile(options),
 };
+/** 默认 SDK 实例的 media 模块。 */
+const media = {
+    pick: (options) => getDefaultSDK().media.pick(options),
+};
 /** 默认 SDK 实例的 UI 模块。 */
 const ui = {
     showToast: (options) => getDefaultSDK().ui.showToast(options),
@@ -11983,6 +12267,7 @@ const hbSDK = {
     viewport,
     storage,
     files,
+    media,
     network,
     ui,
     device,
@@ -11993,4 +12278,4 @@ const hbSDK = {
     workspaceCards,
 };
 
-export { HbMiniProgramNetworkError, HbMiniProgramSDKError, USER_INFO_AUTHORIZATION_SCOPES, auth, cloud, companion, hbSDK as default, device, environment, files, getHandshakeState, navigation, network, off, on, onHandshakeStateChange, share, storage, ui, user, viewport, workspaceCards };
+export { HbMiniProgramNetworkError, HbMiniProgramSDKError, USER_INFO_AUTHORIZATION_SCOPES, auth, cloud, companion, hbSDK as default, device, environment, files, getHandshakeState, media, navigation, network, off, on, onHandshakeStateChange, share, storage, ui, user, viewport, workspaceCards };

package/dist/miniapp-publish.cjs.js

@@ -14,6 +14,7 @@ const MINI_PROGRAM_PERMISSION_KEYS = [
     'storage',
     'cloud_storage',
     'filesystem',
+    'media',
     'clipboard',
     'leaderboard',
     'network',
@@ -100,6 +101,16 @@ const MINI_PROGRAM_PERMISSION_CATALOG = [
         ],
         conditions: ['外部文件继续要求有效的用户选择、会话句柄和匹配的读写模式。'],
     },
+    {
+        key: 'media',
+        name: '媒体',
+        description: '通过系统图库或相机选择图片、视频。',
+        access: 'declaration',
+        risk: 'high',
+        config: {},
+        methods: ['media.pick'],
+        conditions: ['图库授权范围仅限本次用户选择的媒体，不包含任意文件或沙盒访问权；继续执行可信手势、Host 能力与会话资源规则。'],
+    },
     {
         key: 'clipboard',
         name: '剪贴板',

package/dist/miniapp-publish.esm.js

@@ -12,6 +12,7 @@ const MINI_PROGRAM_PERMISSION_KEYS = [
     'storage',
     'cloud_storage',
     'filesystem',
+    'media',
     'clipboard',
     'leaderboard',
     'network',
@@ -98,6 +99,16 @@ const MINI_PROGRAM_PERMISSION_CATALOG = [
         ],
         conditions: ['外部文件继续要求有效的用户选择、会话句柄和匹配的读写模式。'],
     },
+    {
+        key: 'media',
+        name: '媒体',
+        description: '通过系统图库或相机选择图片、视频。',
+        access: 'declaration',
+        risk: 'high',
+        config: {},
+        methods: ['media.pick'],
+        conditions: ['图库授权范围仅限本次用户选择的媒体，不包含任意文件或沙盒访问权；继续执行可信手势、Host 能力与会话资源规则。'],
+    },
     {
         key: 'clipboard',
         name: '剪贴板',