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

package/dist/protocol.cjs.js

@@ -63,6 +63,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';
@@ -323,6 +324,13 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
         requirement: { kind: 'all', permissions: ['filesystem'] },
         risk: 'high',
     },
+    {
+        method: MEDIA_PICK_METHOD,
+        module: 'media',
+        capability: MEDIA_PICK_METHOD,
+        requirement: { kind: 'all', permissions: ['media'] },
+        risk: 'high',
+    },
     { method: UI_SHOW_TOAST_METHOD, module: 'ui', capability: UI_SHOW_TOAST_METHOD, requirement: { kind: 'none' }, risk: 'low' },
     { method: UI_SHOW_LOADING_METHOD, module: 'ui', capability: UI_SHOW_LOADING_METHOD, requirement: { kind: 'none' }, risk: 'low' },
     { method: UI_HIDE_LOADING_METHOD, module: 'ui', capability: UI_HIDE_LOADING_METHOD, requirement: { kind: 'none' }, risk: 'low' },
@@ -1008,6 +1016,159 @@ function isMiniProgramDirectoryDescriptor(value) {
 function isMiniProgramFileSystemEntityDescriptor(value) {
     return isMiniProgramFileDescriptor(value) || isMiniProgramDirectoryDescriptor(value);
 }
+/** `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` payload 的最低 wire 结构。
+ *
+ * @param value - 来自 App-facing 参数、bridge request 或其他不可信边界的候选 payload。`undefined`
+ * 表示调用方省略整个 payload，会通过本 guard 并使用全部缺省值。
+ * @returns 值满足 {@link MediaPickPayload} 的枚举、取值范围和键集合约束时返回 `true`，并将
+ * TypeScript 类型收窄为 payload 类型；否则返回 `false`。
+ *
+ * @remarks
+ * 对通常的对象字面量，仅允许 `source`、`mediaType`、`maxCount` 三个 canonical key：
+ *
+ * - `source` 可省略或为 `album` / `camera`；`mediaType` 可省略或为 `image` / `video` / `all`。
+ * - `maxCount` 可省略，或为 1–20 的安全整数。`0`、负数、小数、`NaN`、`Infinity`、unsafe integer、
+ *   bigint 和数字字符串都会被拒绝。
+ * - `source === 'camera'` 且提供 `maxCount` 时，只接受 `1`；大于 1 的值在此处即可拒绝，
+ *   Runtime 不应静默收窄。
+ *
+ * 该 guard 只建立结构类型收窄，不应用缺省值、不证明 `media` 权限已声明或启用、不检查可信用户手势、
+ * 不确认 Host 支持 `media.pick`，也不保证系统选择器一定交付 `maxCount` 项。`all` 仅表示图片与视频，
+ * 不包含音频或任意文件。
+ *
+ * @example
+ * ```ts
+ * import { isMiniProgramMediaPickPayload } from '@heybox/hb-sdk/protocol';
+ *
+ * isMiniProgramMediaPickPayload(undefined); // true：使用全部缺省值
+ * isMiniProgramMediaPickPayload({ source: 'album', maxCount: 20 }); // true
+ * isMiniProgramMediaPickPayload({ source: 'camera', maxCount: 2 }); // false：相机只能单选
+ * ```
+ *
+ * @see [MediaPickPayload](/reference/symbols/protocol/interfaces/MediaPickPayload) wire 字段定义。
+ * @since 0.9.3
+ */
+function isMiniProgramMediaPickPayload(value) {
+    if (value === undefined)
+        return true;
+    if (!isRecord$3(value) || !hasOnlyKeys(value, ['source', 'mediaType', 'maxCount']))
+        return false;
+    if (value.source !== undefined && value.source !== 'album' && value.source !== 'camera')
+        return false;
+    if (value.mediaType !== undefined && value.mediaType !== 'image' && value.mediaType !== 'video' && value.mediaType !== 'all')
+        return false;
+    if (value.maxCount !== undefined) {
+        if (!isIntegerInRange(value.maxCount, 1, MAX_MEDIA_PICK_COUNT))
+            return false;
+        if (value.source === 'camera' && value.maxCount !== 1)
+            return false;
+    }
+    return true;
+}
+/**
+ * 判断未知值是否为单个 `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` 字节视图。
  *
@@ -1223,6 +1384,12 @@ function isFileMode(value) {
 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 isIntegerInRange(value, min, max) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= min && value <= max;
+}
 function isNonNegativeFiniteNumber(value) {
     return typeof value === 'number' && Number.isFinite(value) && value >= 0;
 }
@@ -1244,6 +1411,7 @@ const MINI_PROGRAM_PERMISSION_KEYS = [
     'storage',
     'cloud_storage',
     'filesystem',
+    'media',
     'clipboard',
     'leaderboard',
     'network',
@@ -7271,6 +7439,7 @@ exports.FILE_REMOVE_METHOD = FILE_REMOVE_METHOD;
 exports.FILE_STAT_METHOD = FILE_STAT_METHOD;
 exports.FILE_WRITE_BYTES_METHOD = FILE_WRITE_BYTES_METHOD;
 exports.FILE_WRITE_TEXT_METHOD = FILE_WRITE_TEXT_METHOD;
+exports.MEDIA_PICK_METHOD = MEDIA_PICK_METHOD;
 exports.MINI_PROGRAM_BRIDGE_NONCE_PARAM = MINI_PROGRAM_BRIDGE_NONCE_PARAM;
 exports.MINI_PROGRAM_MESSAGE_NAMESPACE = MINI_PROGRAM_MESSAGE_NAMESPACE;
 exports.MINI_PROGRAM_MESSAGE_VERSION = MINI_PROGRAM_MESSAGE_VERSION;
@@ -7311,6 +7480,9 @@ exports.isMiniProgramFileDescriptor = isMiniProgramFileDescriptor;
 exports.isMiniProgramFileRef = isMiniProgramFileRef;
 exports.isMiniProgramFileStat = isMiniProgramFileStat;
 exports.isMiniProgramFileSystemEntityDescriptor = isMiniProgramFileSystemEntityDescriptor;
+exports.isMiniProgramMediaPickItem = isMiniProgramMediaPickItem;
+exports.isMiniProgramMediaPickPayload = isMiniProgramMediaPickPayload;
+exports.isMiniProgramMediaPickResult = isMiniProgramMediaPickResult;
 exports.isMiniProgramPathRootRef = isMiniProgramPathRootRef;
 exports.isMiniProgramRelativePath = isMiniProgramRelativePath;
 exports.parseMiniProgramRuntimePermissions = parseMiniProgramRuntimePermissions;

package/dist/protocol.esm.js

@@ -61,6 +61,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';
@@ -321,6 +322,13 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
         requirement: { kind: 'all', permissions: ['filesystem'] },
         risk: 'high',
     },
+    {
+        method: MEDIA_PICK_METHOD,
+        module: 'media',
+        capability: MEDIA_PICK_METHOD,
+        requirement: { kind: 'all', permissions: ['media'] },
+        risk: 'high',
+    },
     { method: UI_SHOW_TOAST_METHOD, module: 'ui', capability: UI_SHOW_TOAST_METHOD, requirement: { kind: 'none' }, risk: 'low' },
     { method: UI_SHOW_LOADING_METHOD, module: 'ui', capability: UI_SHOW_LOADING_METHOD, requirement: { kind: 'none' }, risk: 'low' },
     { method: UI_HIDE_LOADING_METHOD, module: 'ui', capability: UI_HIDE_LOADING_METHOD, requirement: { kind: 'none' }, risk: 'low' },
@@ -1006,6 +1014,159 @@ function isMiniProgramDirectoryDescriptor(value) {
 function isMiniProgramFileSystemEntityDescriptor(value) {
     return isMiniProgramFileDescriptor(value) || isMiniProgramDirectoryDescriptor(value);
 }
+/** `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` payload 的最低 wire 结构。
+ *
+ * @param value - 来自 App-facing 参数、bridge request 或其他不可信边界的候选 payload。`undefined`
+ * 表示调用方省略整个 payload，会通过本 guard 并使用全部缺省值。
+ * @returns 值满足 {@link MediaPickPayload} 的枚举、取值范围和键集合约束时返回 `true`，并将
+ * TypeScript 类型收窄为 payload 类型；否则返回 `false`。
+ *
+ * @remarks
+ * 对通常的对象字面量，仅允许 `source`、`mediaType`、`maxCount` 三个 canonical key：
+ *
+ * - `source` 可省略或为 `album` / `camera`；`mediaType` 可省略或为 `image` / `video` / `all`。
+ * - `maxCount` 可省略，或为 1–20 的安全整数。`0`、负数、小数、`NaN`、`Infinity`、unsafe integer、
+ *   bigint 和数字字符串都会被拒绝。
+ * - `source === 'camera'` 且提供 `maxCount` 时，只接受 `1`；大于 1 的值在此处即可拒绝，
+ *   Runtime 不应静默收窄。
+ *
+ * 该 guard 只建立结构类型收窄，不应用缺省值、不证明 `media` 权限已声明或启用、不检查可信用户手势、
+ * 不确认 Host 支持 `media.pick`，也不保证系统选择器一定交付 `maxCount` 项。`all` 仅表示图片与视频，
+ * 不包含音频或任意文件。
+ *
+ * @example
+ * ```ts
+ * import { isMiniProgramMediaPickPayload } from '@heybox/hb-sdk/protocol';
+ *
+ * isMiniProgramMediaPickPayload(undefined); // true：使用全部缺省值
+ * isMiniProgramMediaPickPayload({ source: 'album', maxCount: 20 }); // true
+ * isMiniProgramMediaPickPayload({ source: 'camera', maxCount: 2 }); // false：相机只能单选
+ * ```
+ *
+ * @see [MediaPickPayload](/reference/symbols/protocol/interfaces/MediaPickPayload) wire 字段定义。
+ * @since 0.9.3
+ */
+function isMiniProgramMediaPickPayload(value) {
+    if (value === undefined)
+        return true;
+    if (!isRecord$3(value) || !hasOnlyKeys(value, ['source', 'mediaType', 'maxCount']))
+        return false;
+    if (value.source !== undefined && value.source !== 'album' && value.source !== 'camera')
+        return false;
+    if (value.mediaType !== undefined && value.mediaType !== 'image' && value.mediaType !== 'video' && value.mediaType !== 'all')
+        return false;
+    if (value.maxCount !== undefined) {
+        if (!isIntegerInRange(value.maxCount, 1, MAX_MEDIA_PICK_COUNT))
+            return false;
+        if (value.source === 'camera' && value.maxCount !== 1)
+            return false;
+    }
+    return true;
+}
+/**
+ * 判断未知值是否为单个 `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` 字节视图。
  *
@@ -1221,6 +1382,12 @@ function isFileMode(value) {
 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 isIntegerInRange(value, min, max) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= min && value <= max;
+}
 function isNonNegativeFiniteNumber(value) {
     return typeof value === 'number' && Number.isFinite(value) && value >= 0;
 }
@@ -1242,6 +1409,7 @@ const MINI_PROGRAM_PERMISSION_KEYS = [
     'storage',
     'cloud_storage',
     'filesystem',
+    'media',
     'clipboard',
     'leaderboard',
     'network',
@@ -7240,4 +7408,4 @@ object({
   regions: array(viewRegionSchema).max(VIEW_BUDGET.maxRegions)
 });
 
-export { AUTH_GET_ACCOUNT_STATE_METHOD, 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, CLOUD_STORAGE_GET_KEYS_METHOD, CLOUD_STORAGE_GET_STORAGE_METHOD, CLOUD_STORAGE_REMOVE_ITEM_METHOD, CLOUD_STORAGE_SET_STORAGE_METHOD, DEVICE_EXECUTE_PROTOCOL_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, DIRECTORY_CREATE_METHOD, DIRECTORY_EXISTS_METHOD, DIRECTORY_LIST_METHOD, DIRECTORY_REMOVE_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_DOWNLOAD_METHOD, NETWORK_REQUEST_METHOD, NETWORK_UPLOAD_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_GET_INFO_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_INFO_AUTHORIZATION_SCOPES, USER_REVOKE_AUTHORIZATION_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_DISPLAY_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, isManagedMiniProgramRuntimePermissionKey, isMiniProgramBridgeMessage, isMiniProgramByteArray, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramPathRootRef, isMiniProgramRelativePath, parseMiniProgramRuntimePermissions };
+export { AUTH_GET_ACCOUNT_STATE_METHOD, 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, CLOUD_STORAGE_GET_KEYS_METHOD, CLOUD_STORAGE_GET_STORAGE_METHOD, CLOUD_STORAGE_REMOVE_ITEM_METHOD, CLOUD_STORAGE_SET_STORAGE_METHOD, DEVICE_EXECUTE_PROTOCOL_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, DIRECTORY_CREATE_METHOD, DIRECTORY_EXISTS_METHOD, DIRECTORY_LIST_METHOD, DIRECTORY_REMOVE_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, MEDIA_PICK_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_DOWNLOAD_METHOD, NETWORK_REQUEST_METHOD, NETWORK_UPLOAD_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_GET_INFO_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, USER_INFO_AUTHORIZATION_SCOPES, USER_REVOKE_AUTHORIZATION_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_DISPLAY_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, isManagedMiniProgramRuntimePermissionKey, isMiniProgramBridgeMessage, isMiniProgramByteArray, isMiniProgramDirectoryDescriptor, isMiniProgramDirectoryRef, isMiniProgramDownloadProgressPayload, isMiniProgramFileDescriptor, isMiniProgramFileRef, isMiniProgramFileStat, isMiniProgramFileSystemEntityDescriptor, isMiniProgramMediaPickItem, isMiniProgramMediaPickPayload, isMiniProgramMediaPickResult, isMiniProgramPathRootRef, isMiniProgramRelativePath, parseMiniProgramRuntimePermissions };

package/dist/vite.cjs.js

@@ -64,6 +64,7 @@ const MINI_PROGRAM_PERMISSION_KEYS = [
     'storage',
     'cloud_storage',
     'filesystem',
+    'media',
     'clipboard',
     'leaderboard',
     'network',
@@ -150,6 +151,16 @@ const MINI_PROGRAM_PERMISSION_CATALOG = [
         ],
         conditions: ['外部文件继续要求有效的用户选择、会话句柄和匹配的读写模式。'],
     },
+    {
+        key: 'media',
+        name: '媒体',
+        description: '通过系统图库或相机选择图片、视频。',
+        access: 'declaration',
+        risk: 'high',
+        config: {},
+        methods: ['media.pick'],
+        conditions: ['图库授权范围仅限本次用户选择的媒体，不包含任意文件或沙盒访问权；继续执行可信手势、Host 能力与会话资源规则。'],
+    },
     {
         key: 'clipboard',
         name: '剪贴板',
@@ -10304,7 +10315,7 @@ async function ensureBasicInfoDirectory(rootPath, relative) {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.3-alpha.6';
+    : '0.9.3';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。
@@ -20289,6 +20300,9 @@ const FORBIDDEN_RESOURCE_HINTS = new Set(['dns-prefetch', 'preconnect', 'prerend
 const RELATIVE_URL_BASE = new URL('https://heybox-relative.invalid/');
 const OFFICIAL_RESOURCE_ROOT_DOMAINS = ['xiaoheihe.cn', 'max-c.com', 'debugmode.cn', 'maxjia.com'];
 const OFFICIAL_RESOURCE_SOURCES = OFFICIAL_RESOURCE_ROOT_DOMAINS.flatMap((rootDomain) => [`https://${rootDomain}`, `https://*.${rootDomain}`]);
+// 受控媒体预览通道：iOS `hbmini-media://preview/...`、鸿蒙 OHOS `hbmedia://<sessionId>/<previewId>`。
+// 两者是宿主注册的自定义 scheme，只允许出现在图片/媒体资源加载指令中，不放宽其它指令。
+const MEDIA_PREVIEW_SCHEME_SOURCES = ['hbmini-media:', 'hbmedia:'];
 const URL_ATTRIBUTES = {
     audio: ['src'],
     embed: ['src'],
@@ -20306,9 +20320,9 @@ const PRODUCTION_CSP = [
     "connect-src 'none'",
     `script-src 'self' 'unsafe-inline' ${OFFICIAL_RESOURCE_SOURCES.join(' ')}`,
     `style-src 'self' 'unsafe-inline' ${OFFICIAL_RESOURCE_SOURCES.join(' ')}`,
-    `img-src 'self' data: blob: ${OFFICIAL_RESOURCE_SOURCES.join(' ')}`,
+    `img-src 'self' data: blob: ${MEDIA_PREVIEW_SCHEME_SOURCES.join(' ')} ${OFFICIAL_RESOURCE_SOURCES.join(' ')}`,
     `font-src 'self' data: ${OFFICIAL_RESOURCE_SOURCES.join(' ')}`,
-    `media-src 'self' blob: ${OFFICIAL_RESOURCE_SOURCES.join(' ')}`,
+    `media-src 'self' blob: ${MEDIA_PREVIEW_SCHEME_SOURCES.join(' ')} ${OFFICIAL_RESOURCE_SOURCES.join(' ')}`,
     "manifest-src 'self'",
     "frame-src 'none'",
     "child-src 'none'",

package/dist/vite.esm.js

@@ -61,6 +61,7 @@ const MINI_PROGRAM_PERMISSION_KEYS = [
     'storage',
     'cloud_storage',
     'filesystem',
+    'media',
     'clipboard',
     'leaderboard',
     'network',
@@ -147,6 +148,16 @@ const MINI_PROGRAM_PERMISSION_CATALOG = [
         ],
         conditions: ['外部文件继续要求有效的用户选择、会话句柄和匹配的读写模式。'],
     },
+    {
+        key: 'media',
+        name: '媒体',
+        description: '通过系统图库或相机选择图片、视频。',
+        access: 'declaration',
+        risk: 'high',
+        config: {},
+        methods: ['media.pick'],
+        conditions: ['图库授权范围仅限本次用户选择的媒体，不包含任意文件或沙盒访问权；继续执行可信手势、Host 能力与会话资源规则。'],
+    },
     {
         key: 'clipboard',
         name: '剪贴板',
@@ -10301,7 +10312,7 @@ async function ensureBasicInfoDirectory(rootPath, relative) {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.3-alpha.6';
+    : '0.9.3';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。
@@ -20286,6 +20297,9 @@ const FORBIDDEN_RESOURCE_HINTS = new Set(['dns-prefetch', 'preconnect', 'prerend
 const RELATIVE_URL_BASE = new URL('https://heybox-relative.invalid/');
 const OFFICIAL_RESOURCE_ROOT_DOMAINS = ['xiaoheihe.cn', 'max-c.com', 'debugmode.cn', 'maxjia.com'];
 const OFFICIAL_RESOURCE_SOURCES = OFFICIAL_RESOURCE_ROOT_DOMAINS.flatMap((rootDomain) => [`https://${rootDomain}`, `https://*.${rootDomain}`]);
+// 受控媒体预览通道：iOS `hbmini-media://preview/...`、鸿蒙 OHOS `hbmedia://<sessionId>/<previewId>`。
+// 两者是宿主注册的自定义 scheme，只允许出现在图片/媒体资源加载指令中，不放宽其它指令。
+const MEDIA_PREVIEW_SCHEME_SOURCES = ['hbmini-media:', 'hbmedia:'];
 const URL_ATTRIBUTES = {
     audio: ['src'],
     embed: ['src'],
@@ -20303,9 +20317,9 @@ const PRODUCTION_CSP = [
     "connect-src 'none'",
     `script-src 'self' 'unsafe-inline' ${OFFICIAL_RESOURCE_SOURCES.join(' ')}`,
     `style-src 'self' 'unsafe-inline' ${OFFICIAL_RESOURCE_SOURCES.join(' ')}`,
-    `img-src 'self' data: blob: ${OFFICIAL_RESOURCE_SOURCES.join(' ')}`,
+    `img-src 'self' data: blob: ${MEDIA_PREVIEW_SCHEME_SOURCES.join(' ')} ${OFFICIAL_RESOURCE_SOURCES.join(' ')}`,
     `font-src 'self' data: ${OFFICIAL_RESOURCE_SOURCES.join(' ')}`,
-    `media-src 'self' blob: ${OFFICIAL_RESOURCE_SOURCES.join(' ')}`,
+    `media-src 'self' blob: ${MEDIA_PREVIEW_SCHEME_SOURCES.join(' ')} ${OFFICIAL_RESOURCE_SOURCES.join(' ')}`,
     "manifest-src 'self'",
     "frame-src 'none'",
     "child-src 'none'",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.9.3-alpha.6",
+  "version": "0.9.3",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -76,7 +76,7 @@
     "undici": "^7.28.0",
     "ws": "^8.18.0",
     "sharp": "^0.34.5",
-    "@heybox/hb-sdk-protocol": "0.9.3-alpha.6"
+    "@heybox/hb-sdk-protocol": "0.9.3"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -128,13 +128,13 @@
     "vitest": "^3.2.4",
     "@ai-desktop/view-contract": "file:../hb-sdk-protocol/vendor/view-contract-2.2.2-6ac49bbf6410.tgz",
     "rollup-plugin-dts": "6.4.0",
-    "@heybox/hb-sdk-runtime": "~0.9.3-alpha.6",
-    "@heybox-domain/heybox-vue3-ui": "~0.1.0",
     "@heybox-domain/heybox-theme": "~0.1.0",
-    "@heybox/runtime": "~0.2.1",
-    "@heybox/runtime-policy": "~0.2.1",
+    "@heybox-domain/heybox-vue3-ui": "~0.1.0",
+    "@heybox/hb-sdk-runtime": "~0.9.3",
     "@heybox/hb-api": "~1.28.17",
-    "@heybox/runtime-transport-fetch": "~0.2.1"
+    "@heybox/runtime": "~0.2.1",
+    "@heybox/runtime-transport-fetch": "~0.2.1",
+    "@heybox/runtime-policy": "~0.2.1"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/skill/skill.json

@@ -1,15 +1,15 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.9.3-alpha.6+skill.d0d502673711",
+  "skillVersion": "0.9.3+skill.d0d502673711",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.9.3-alpha.6",
-    "compatibility": "0.9.3-alpha.6"
+    "version": "0.9.3",
+    "compatibility": "0.9.3"
   },
   "distribution": {
     "type": "npm",
     "package": "@heybox/hb-sdk",
-    "version": "0.9.3-alpha.6",
+    "version": "0.9.3",
     "path": "skill"
   },
   "integrity": "sha256-d0d502673711f5d077ee62e657749125788e396d5203894b7077dfe866fd2990"