@heybox/hb-sdk 0.6.3 → 0.6.4

package/dist/devtools/mock-host/main.js

@@ -7,6 +7,58 @@ const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
 /** SDK 向 Runtime 报告 CSP 违规的内部方法名。 */
 const SDK_CSP_VIOLATION_METHOD = 'sdk.csp.violation';
 
+const MANAGED_RUNTIME_PERMISSION_KEYS = new Set(['network.request']);
+/**
+ * 判断 permission key 是否由 Runtime 权限快照管理。
+ *
+ * @param key 待判断的 permission key。
+ * @returns 该 key 需要读取 Runtime 权限快照时返回 `true`。
+ */
+function isManagedMiniProgramRuntimePermissionKey(key) {
+    return MANAGED_RUNTIME_PERMISSION_KEYS.has(key);
+}
+/**
+ * 解析服务端权限快照；格式不完整时整份快照失效并 fail closed。
+ *
+ * @param snapshot 待校验的服务端权限快照。
+ * @returns 解析状态和通过校验的受管权限。
+ */
+function parseMiniProgramRuntimePermissions(snapshot) {
+    if (!isRecord$2(snapshot) || snapshot.schema_version !== 1 || !Array.isArray(snapshot.entries)) {
+        return { valid: false, permissions: {} };
+    }
+    if (snapshot.revision !== undefined && (typeof snapshot.revision !== 'number' || !Number.isInteger(snapshot.revision) || snapshot.revision < 0)) {
+        return { valid: false, permissions: {} };
+    }
+    const seenKeys = new Set();
+    const permissions = {};
+    for (const rawEntry of snapshot.entries) {
+        if (!isRecord$2(rawEntry) || typeof rawEntry.key !== 'string' || !rawEntry.key.trim()) {
+            return { valid: false, permissions: {} };
+        }
+        const key = rawEntry.key.trim();
+        if (seenKeys.has(key) || (rawEntry.status !== 'enabled' && rawEntry.status !== 'disabled') || !isRecord$2(rawEntry.config)) {
+            return { valid: false, permissions: {} };
+        }
+        seenKeys.add(key);
+        if (!isManagedMiniProgramRuntimePermissionKey(key)) {
+            continue;
+        }
+        if (key === 'network.request' && typeof rawEntry.config.useOfficialDomain !== 'boolean') {
+            return { valid: false, permissions: {} };
+        }
+        permissions[key] = {
+            key,
+            status: rawEntry.status,
+            config: { useOfficialDomain: rawEntry.config.useOfficialDomain },
+        };
+    }
+    return { valid: true, permissions };
+}
+function isRecord$2(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 /**
  * 登录授权能力方法名。
  *
@@ -3445,6 +3497,91 @@ function formatBlockedResource(payload) {
     return '未知资源';
 }
 
+const DEFAULT_PERMISSION_STATE = {
+    networkRequest: {
+        status: 'disabled',
+        useOfficialDomain: false,
+    },
+};
+function createMiniProgramMockPermissionState(context) {
+    const parsed = parseMiniProgramRuntimePermissions(context.runtimePermissions);
+    const networkRequest = parsed.permissions['network.request'];
+    return parsed.valid && networkRequest
+        ? {
+            networkRequest: {
+                status: networkRequest.status,
+                useOfficialDomain: networkRequest.config.useOfficialDomain === true,
+            },
+        }
+        : cloneDefaultPermissionState();
+}
+function createMiniProgramMockRuntimePermissions(state) {
+    return {
+        schema_version: 1,
+        entries: [
+            {
+                key: 'network.request',
+                status: state.networkRequest.status,
+                config: {
+                    useOfficialDomain: state.networkRequest.useOfficialDomain,
+                },
+            },
+        ],
+    };
+}
+function createMiniProgramDevReleaseDiagnostics(context, localState) {
+    if (context.source === 'anonymous') {
+        return [
+            {
+                code: 'REMOTE_CONTEXT_UNAVAILABLE',
+                severity: 'warning',
+                message: `未获取到线上权限配置，本地模拟不代表上线状态${context.warning ? `：${context.warning}` : ''}`,
+            },
+        ];
+    }
+    const parsedRemote = parseMiniProgramRuntimePermissions(context.runtimePermissions);
+    if (!parsedRemote.valid) {
+        return [
+            {
+                code: 'REMOTE_PERMISSIONS_INVALID',
+                severity: 'warning',
+                message: '线上权限配置不可用，本地模拟不代表上线状态。',
+            },
+        ];
+    }
+    const remoteNetworkRequest = parsedRemote.permissions['network.request'];
+    const remoteState = remoteNetworkRequest
+        ? {
+            status: remoteNetworkRequest.status,
+            useOfficialDomain: remoteNetworkRequest.config.useOfficialDomain === true,
+        }
+        : DEFAULT_PERMISSION_STATE.networkRequest;
+    if (localState.networkRequest.status === 'enabled' && remoteState.status !== 'enabled') {
+        return [
+            {
+                code: 'NETWORK_REQUEST_DISABLED_ONLINE',
+                severity: 'warning',
+                message: '当前本地允许 network.request，但线上权限已关闭；上线后请求会返回 PERMISSION_DENIED。',
+            },
+        ];
+    }
+    if (localState.networkRequest.status === 'enabled' && localState.networkRequest.useOfficialDomain && !remoteState.useOfficialDomain) {
+        return [
+            {
+                code: 'OFFICIAL_DOMAIN_DISABLED_ONLINE',
+                severity: 'warning',
+                message: '当前本地允许访问小黑盒官方域名，但线上权限未开放；上线后相关请求会返回 PERMISSION_DENIED。',
+            },
+        ];
+    }
+    return [];
+}
+function cloneDefaultPermissionState() {
+    return {
+        networkRequest: { ...DEFAULT_PERMISSION_STATE.networkRequest },
+    };
+}
+
 async function getMiniProgramRuntimeUserInfo(platformAdapter) {
     const userId = await resolveCurrentUserId(platformAdapter);
     if (!userId) {
@@ -5031,46 +5168,11 @@ function isOfficialMiniProgramNetworkUrl(value) {
     }
 }
 
-const MANAGED_RUNTIME_PERMISSION_KEYS = new Set(['network.request']);
-/** 解析服务端权限快照；格式不完整时整份快照失效并 fail closed。 */
-function parseMiniProgramRuntimePermissions(snapshot) {
-    if (!isRecord$1(snapshot) || snapshot.schema_version !== 1 || !Array.isArray(snapshot.entries)) {
-        return { valid: false, permissions: {} };
-    }
-    if (snapshot.revision !== undefined &&
-        (typeof snapshot.revision !== 'number' || !Number.isInteger(snapshot.revision) || snapshot.revision < 0)) {
-        return { valid: false, permissions: {} };
-    }
-    const seenKeys = new Set();
-    const permissions = {};
-    for (const rawEntry of snapshot.entries) {
-        if (!isRecord$1(rawEntry) || typeof rawEntry.key !== 'string' || !rawEntry.key.trim()) {
-            return { valid: false, permissions: {} };
-        }
-        const key = rawEntry.key.trim();
-        if (seenKeys.has(key) || (rawEntry.status !== 'enabled' && rawEntry.status !== 'disabled') || !isRecord$1(rawEntry.config)) {
-            return { valid: false, permissions: {} };
-        }
-        seenKeys.add(key);
-        if (!MANAGED_RUNTIME_PERMISSION_KEYS.has(key)) {
-            continue;
-        }
-        if (key === 'network.request' && typeof rawEntry.config.useOfficialDomain !== 'boolean') {
-            return { valid: false, permissions: {} };
-        }
-        permissions[key] = {
-            key,
-            status: rawEntry.status,
-            config: { useOfficialDomain: rawEntry.config.useOfficialDomain },
-        };
-    }
-    return { valid: true, permissions };
-}
 /** 创建只依赖启动快照的纯权限 evaluator，供正式 Runtime 与 Mock Host 共用。 */
 function createMiniProgramRuntimePermissionEvaluator(snapshot) {
     const parsed = parseMiniProgramRuntimePermissions(snapshot);
     return (permissionKey, payload) => {
-        if (!MANAGED_RUNTIME_PERMISSION_KEYS.has(permissionKey)) {
+        if (!isManagedMiniProgramRuntimePermissionKey(permissionKey)) {
             return { allowed: true };
         }
         const entry = parsed.valid ? parsed.permissions[permissionKey] : undefined;
@@ -6306,6 +6408,7 @@ const elements = {
     cspViolations: queryElement('#csp-violations'),
     debugPageCopyStatus: queryElement('#debug-page-copy-status'),
     debugPageUrl: queryElement('#debug-page-url'),
+    devContextStatus: queryElement('#dev-context-status'),
     device: queryElement('#device'),
     logs: queryElement('#logs'),
     macAppButton: queryElement('#mac-app-button'),
@@ -6315,6 +6418,9 @@ const elements = {
     mobileQrImage: queryElement('#mobile-qr-image'),
     mobileQrStatus: queryElement('#mobile-qr-status'),
     nicknameInput: queryElement('#nickname-input'),
+    networkPermissionSelect: queryElement('#network-permission-select'),
+    releaseDiagnostics: queryElement('#release-diagnostics'),
+    resetPermissionsButton: queryElement('#reset-permissions-button'),
     storageSnapshot: queryElement('#storage-snapshot'),
     userStatus: queryElement('#user-status'),
 };
@@ -6325,13 +6431,15 @@ if (!miniUrl) {
 }
 const miniProgramUrl = miniUrl;
 const bootstrap = await loadMockHostBootstrap();
-const runtimePermissions = bootstrap.runtimePermissions;
+const devContext = bootstrap.devContext;
+const initialPermissionState = createMiniProgramMockPermissionState(devContext);
+let permissionState = clonePermissionState(initialPermissionState);
 const iframe = document.createElement('iframe');
 iframe.src = appendNonce(miniProgramUrl, nonce);
 iframe.allow = 'clipboard-read; clipboard-write';
 elements.device.appendChild(iframe);
 elements.miniUrl.textContent = miniProgramUrl;
-const runtime = new MiniProgramMockRuntime(createBrowserMockRuntimePlatformAdapter({
+const platformAdapter = createBrowserMockRuntimePlatformAdapter({
     iframe,
     getCurrentHref: () => location.href,
     getCurrentUser: () => currentUser,
@@ -6353,12 +6461,11 @@ const runtime = new MiniProgramMockRuntime(createBrowserMockRuntimePlatformAdapt
         storage.set(key, value);
         updateStorageSnapshot();
     },
-}), {
-    onAuthChange: (result) => postEvent('authChange', result),
-    runtimePermissions,
 });
+let runtime = createRuntime();
 updateUserStatus();
 updateStorageSnapshot();
+updatePermissionControls();
 window.addEventListener('message', handleMessage);
 window.addEventListener('beforeunload', () => {
     postEvent('unload', { timestamp: Date.now() });
@@ -6386,7 +6493,42 @@ elements.copyDebugPageUrlButton.addEventListener('click', () => {
 elements.mobileLanSelect.addEventListener('change', () => {
     void updateMobileQrCode();
 });
+elements.networkPermissionSelect.addEventListener('change', () => {
+    permissionState.networkRequest.status =
+        elements.networkPermissionSelect.value === 'enabled' ? 'enabled' : 'disabled';
+    rebuildRuntimeWithPermissions();
+});
+elements.resetPermissionsButton.addEventListener('click', () => {
+    permissionState = clonePermissionState(initialPermissionState);
+    rebuildRuntimeWithPermissions();
+});
 const mobileAppQrReady = setupMobileAppQr();
+function createRuntime() {
+    return new MiniProgramMockRuntime(platformAdapter, {
+        onAuthChange: (result) => postEvent('authChange', result),
+        runtimePermissions: createMiniProgramMockRuntimePermissions(permissionState),
+    });
+}
+function rebuildRuntimeWithPermissions() {
+    runtime = createRuntime();
+    updatePermissionControls();
+}
+function updatePermissionControls() {
+    elements.devContextStatus.textContent =
+        devContext.source === 'remote'
+            ? `已连接线上配置${devContext.miniProgramId ? ` · ${devContext.miniProgramId}` : ''}`
+            : '匿名本地沙箱';
+    elements.networkPermissionSelect.value = permissionState.networkRequest.status;
+    const diagnostics = createMiniProgramDevReleaseDiagnostics(devContext, permissionState);
+    elements.releaseDiagnostics.innerHTML = diagnostics
+        .map((diagnostic) => `<li>${escapeHtml(diagnostic.message)}</li>`)
+        .join('');
+}
+function clonePermissionState(state) {
+    return {
+        networkRequest: { ...state.networkRequest },
+    };
+}
 function handleMessage(event) {
     if (event.source !== iframe.contentWindow || !isBridgeMessage(event.data)) {
         return;
@@ -6599,10 +6741,17 @@ async function loadMockHostBootstrap() {
         });
         const payload = await response.json();
         if (!isRecord(payload)) {
-            return { lanAddresses: [] };
+            return {
+                devContext: {
+                    source: 'anonymous',
+                    warning: 'dev context 响应格式无效。',
+                },
+                lanAddresses: [],
+            };
         }
         return {
             defaultLanAddressId: typeof payload.defaultLanAddressId === 'string' ? payload.defaultLanAddressId : undefined,
+            devContext: readDevContext(payload.devContext, payload.runtimePermissions),
             lanAddresses: Array.isArray(payload.lanAddresses) ? payload.lanAddresses.filter(isLanAddress) : [],
             macAppProtocol: typeof payload.macAppProtocol === 'string' ? payload.macAppProtocol : undefined,
             nativeAppLaunchUnavailableReason: typeof payload.nativeAppLaunchUnavailableReason === 'string'
@@ -6613,11 +6762,33 @@ async function loadMockHostBootstrap() {
     }
     catch {
         return {
+            devContext: {
+                source: 'anonymous',
+                warning: '真机调试配置加载失败，请重启 hb-sdk dev 后重试。',
+            },
             lanAddresses: [],
             nativeAppLaunchUnavailableReason: '真机调试配置加载失败，请重启 hb-sdk dev 后重试。',
         };
     }
 }
+function readDevContext(value, legacyRuntimePermissions) {
+    if (isRecord(value) && value.source === 'remote') {
+        return {
+            source: 'remote',
+            miniProgramId: typeof value.miniProgramId === 'string' ? value.miniProgramId : undefined,
+            runtimePermissions: value.runtimePermissions ?? legacyRuntimePermissions,
+        };
+    }
+    if (isRecord(value) && value.source === 'anonymous') {
+        return {
+            source: 'anonymous',
+            warning: typeof value.warning === 'string' ? value.warning : undefined,
+        };
+    }
+    return legacyRuntimePermissions === undefined
+        ? { source: 'anonymous', warning: '未获取到 dev context。' }
+        : { source: 'remote', runtimePermissions: legacyRuntimePermissions };
+}
 function setupMobileLanSelect() {
     elements.mobileLanSelect.innerHTML = '';
     lanAddresses.forEach((address) => {

package/dist/index.cjs.js

@@ -325,7 +325,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.3';
+    : '0.6.4';
 
 /**
  * 判断未知数据是否符合小程序 bridge 消息信封。

package/dist/index.esm.js

@@ -321,7 +321,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.3';
+    : '0.6.4';
 
 /**
  * 判断未知数据是否符合小程序 bridge 消息信封。

package/dist/protocol.cjs.js

@@ -32,6 +32,58 @@ function isMiniProgramBridgeMessage(value) {
         typeof message.type === 'string');
 }
 
+const MANAGED_RUNTIME_PERMISSION_KEYS = new Set(['network.request']);
+/**
+ * 判断 permission key 是否由 Runtime 权限快照管理。
+ *
+ * @param key 待判断的 permission key。
+ * @returns 该 key 需要读取 Runtime 权限快照时返回 `true`。
+ */
+function isManagedMiniProgramRuntimePermissionKey(key) {
+    return MANAGED_RUNTIME_PERMISSION_KEYS.has(key);
+}
+/**
+ * 解析服务端权限快照；格式不完整时整份快照失效并 fail closed。
+ *
+ * @param snapshot 待校验的服务端权限快照。
+ * @returns 解析状态和通过校验的受管权限。
+ */
+function parseMiniProgramRuntimePermissions(snapshot) {
+    if (!isRecord(snapshot) || snapshot.schema_version !== 1 || !Array.isArray(snapshot.entries)) {
+        return { valid: false, permissions: {} };
+    }
+    if (snapshot.revision !== undefined && (typeof snapshot.revision !== 'number' || !Number.isInteger(snapshot.revision) || snapshot.revision < 0)) {
+        return { valid: false, permissions: {} };
+    }
+    const seenKeys = new Set();
+    const permissions = {};
+    for (const rawEntry of snapshot.entries) {
+        if (!isRecord(rawEntry) || typeof rawEntry.key !== 'string' || !rawEntry.key.trim()) {
+            return { valid: false, permissions: {} };
+        }
+        const key = rawEntry.key.trim();
+        if (seenKeys.has(key) || (rawEntry.status !== 'enabled' && rawEntry.status !== 'disabled') || !isRecord(rawEntry.config)) {
+            return { valid: false, permissions: {} };
+        }
+        seenKeys.add(key);
+        if (!isManagedMiniProgramRuntimePermissionKey(key)) {
+            continue;
+        }
+        if (key === 'network.request' && typeof rawEntry.config.useOfficialDomain !== 'boolean') {
+            return { valid: false, permissions: {} };
+        }
+        permissions[key] = {
+            key,
+            status: rawEntry.status,
+            config: { useOfficialDomain: rawEntry.config.useOfficialDomain },
+        };
+    }
+    return { valid: true, permissions };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 /**
  * 登录授权能力方法名。
  *
@@ -364,4 +416,6 @@ exports.USER_GET_PLATFORM_ACCOUNT_OVERVIEW_METHOD = USER_GET_PLATFORM_ACCOUNT_OV
 exports.USER_GET_STEAM_GAME_LIST_METHOD = USER_GET_STEAM_GAME_LIST_METHOD;
 exports.VIEWPORT_GET_WINDOW_INFO_METHOD = VIEWPORT_GET_WINDOW_INFO_METHOD;
 exports.VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD = VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD;
+exports.isManagedMiniProgramRuntimePermissionKey = isManagedMiniProgramRuntimePermissionKey;
 exports.isMiniProgramBridgeMessage = isMiniProgramBridgeMessage;
+exports.parseMiniProgramRuntimePermissions = parseMiniProgramRuntimePermissions;

package/dist/protocol.esm.js

@@ -30,6 +30,58 @@ function isMiniProgramBridgeMessage(value) {
         typeof message.type === 'string');
 }
 
+const MANAGED_RUNTIME_PERMISSION_KEYS = new Set(['network.request']);
+/**
+ * 判断 permission key 是否由 Runtime 权限快照管理。
+ *
+ * @param key 待判断的 permission key。
+ * @returns 该 key 需要读取 Runtime 权限快照时返回 `true`。
+ */
+function isManagedMiniProgramRuntimePermissionKey(key) {
+    return MANAGED_RUNTIME_PERMISSION_KEYS.has(key);
+}
+/**
+ * 解析服务端权限快照；格式不完整时整份快照失效并 fail closed。
+ *
+ * @param snapshot 待校验的服务端权限快照。
+ * @returns 解析状态和通过校验的受管权限。
+ */
+function parseMiniProgramRuntimePermissions(snapshot) {
+    if (!isRecord(snapshot) || snapshot.schema_version !== 1 || !Array.isArray(snapshot.entries)) {
+        return { valid: false, permissions: {} };
+    }
+    if (snapshot.revision !== undefined && (typeof snapshot.revision !== 'number' || !Number.isInteger(snapshot.revision) || snapshot.revision < 0)) {
+        return { valid: false, permissions: {} };
+    }
+    const seenKeys = new Set();
+    const permissions = {};
+    for (const rawEntry of snapshot.entries) {
+        if (!isRecord(rawEntry) || typeof rawEntry.key !== 'string' || !rawEntry.key.trim()) {
+            return { valid: false, permissions: {} };
+        }
+        const key = rawEntry.key.trim();
+        if (seenKeys.has(key) || (rawEntry.status !== 'enabled' && rawEntry.status !== 'disabled') || !isRecord(rawEntry.config)) {
+            return { valid: false, permissions: {} };
+        }
+        seenKeys.add(key);
+        if (!isManagedMiniProgramRuntimePermissionKey(key)) {
+            continue;
+        }
+        if (key === 'network.request' && typeof rawEntry.config.useOfficialDomain !== 'boolean') {
+            return { valid: false, permissions: {} };
+        }
+        permissions[key] = {
+            key,
+            status: rawEntry.status,
+            config: { useOfficialDomain: rawEntry.config.useOfficialDomain },
+        };
+    }
+    return { valid: true, permissions };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 /**
  * 登录授权能力方法名。
  *
@@ -327,4 +379,4 @@ const MINI_PROGRAM_PROTOCOL_CAPABILITIES = [
     },
 ];
 
-export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_METHOD, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_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_CURRENT_USER_DETAIL_METHOD, USER_GET_CURRENT_USER_PROFILE_METHOD, USER_GET_INFO_METHOD, USER_GET_PLATFORM_ACCOUNT_INFO_METHOD, USER_GET_PLATFORM_ACCOUNT_OVERVIEW_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, isMiniProgramBridgeMessage };
+export { AUTH_LOGIN_METHOD, CLOUD_LEADERBOARD_DELETE_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_CURRENT_USER_ENTRY_METHOD, CLOUD_LEADERBOARD_GET_INFO_METHOD, CLOUD_LEADERBOARD_GET_LIST_METHOD, CLOUD_LEADERBOARD_SUBMIT_METHOD, DEVICE_SET_CLIPBOARD_METHOD, DEVICE_VIBRATE_METHOD, MINI_PROGRAM_BRIDGE_NONCE_PARAM, MINI_PROGRAM_MESSAGE_NAMESPACE, MINI_PROGRAM_MESSAGE_VERSION, MINI_PROGRAM_PROTOCOL_CAPABILITIES, NAVIGATION_CLOSE_METHOD, NAVIGATION_OPEN_APP_PAGE_METHOD, NAVIGATION_RELOAD_METHOD, NETWORK_REQUEST_METHOD, RUNTIME_LOCATION_PROBE_METHOD, SDK_CSP_VIOLATION_METHOD, SDK_HANDSHAKE_METHOD, SDK_LOCATION_REPORT_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_CURRENT_USER_DETAIL_METHOD, USER_GET_CURRENT_USER_PROFILE_METHOD, USER_GET_INFO_METHOD, USER_GET_PLATFORM_ACCOUNT_INFO_METHOD, USER_GET_PLATFORM_ACCOUNT_OVERVIEW_METHOD, USER_GET_STEAM_GAME_LIST_METHOD, VIEWPORT_GET_WINDOW_INFO_METHOD, VIEWPORT_SET_NAVIGATION_BAR_STYLE_METHOD, isManagedMiniProgramRuntimePermissionKey, isMiniProgramBridgeMessage, parseMiniProgramRuntimePermissions };

package/dist/vite.cjs.js

@@ -7,7 +7,7 @@ var _documentCurrentScript = typeof document !== 'undefined' ? document.currentS
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.3';
+    : '0.6.4';
 
 var re = {exports: {}};
 

package/dist/vite.esm.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.3';
+    : '0.6.4';
 
 var re = {exports: {}};
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -92,7 +92,7 @@
     "vue": "^2.7.16",
     "vite": "^8.0.12",
     "vitest": "^3.2.4",
-    "@heybox/hb-api": "~1.25.1"
+    "@heybox/hb-api": "~1.25.3"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/skill/SKILL.md

@@ -49,7 +49,7 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 ## Step 5: Use CLI workflows
 
 1. Use `hb-sdk create <project-name>` to scaffold a standalone external mini-program template.
-2. Use `hb-sdk dev` for local browser debugging through the built-in mock runtime host. The project must bind `package.json.heybox.miniProgramId` and the CLI must be logged in so dev can load the real Runtime permission snapshot before starting Vite.
+2. Use `hb-sdk dev` for local browser, Mac App, or mobile App debugging through the built-in mock runtime host. Vite and native dev-shell entrypoints only require the local `mini_url`: a missing project binding, CLI login, remote dev-context failure, or the 3-second context timeout must fall back to an anonymous local sandbox instead of blocking startup. Anonymous mode denies managed capabilities by default. When a verified remote dev context is available, the Mock Host uses its Runtime permission snapshot as the initial local simulation and reports local-versus-online permission differences.
 3. Use `hb-sdk remote ...` for developer-owned remote mini-program management. Top-level `hb-sdk deploy` has been hard-cut and must not be recommended as a compatibility alias.
 4. Use `hb-sdk remote entity list`, `hb-sdk remote entity current`, and `hb-sdk remote entity switch <entity-id>` to inspect or change the developer platform server-side current entity before remote management commands.
 5. Use `hb-sdk remote create` to create a remote mini-program under the server-side current entity and bind the returned id into `package.json.heybox.miniProgramId`; use `hb-sdk remote bind <mini-program-id>` to bind an existing remote mini-program after current-entity manageability is verified. CLI project configuration contains only `package.json.heybox.miniProgramId`; mini-program name, icon, and cover images are maintained on the Open platform version-publish flow. On first submit without prior approved profile, the server injects a default name and default images.
@@ -64,7 +64,7 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 14. Add `--verbose` / `-v` only when diagnosing failures; default CLI errors are intentionally concise, while verbose output includes backend envelope, HTTP status, trace fields, raw body, or original submit-audit failure details.
 15. Use `--json` for script consumption of `hb-sdk remote` commands. With `--json`, stdout must contain exactly one JSON object; progress, warnings, update reminders, and verbose diagnostics must not pollute stdout.
 16. Do not expect custom base URLs to affect `hb-sdk doctor`, npm latest checks, or mock-host `network.request()`.
-17. Use the Mock runtime host's "在 Mac 版 APP 中启动" button for Mac App debugging, or the "Mobile App" QR code after selecting a LAN interface for phone App debugging; the phone must be on the same LAN and use a Heybox App version that supports the mini-program dev shell.
+17. Use the Mock runtime host's "在 Mac 版 APP 中启动" button for Mac App debugging, or the "Mobile App" QR code after selecting a LAN interface for phone App debugging; these entrypoints remain available in anonymous mode. The phone must be on the same LAN and use a Heybox App version that supports the mini-program dev shell.
 18. Use `--port`, `--mock-port`, and `--no-open` when the default Vite/mock ports or browser opening behavior need to be controlled.
 19. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` only for the CLI's own Heybox auth cache. Keep `hb-sdk login` top-level; it is not a remote mini-program command.
 20. Treat `selectedEntity` in the CLI auth cache as a non-authoritative hint snapshot only. Every remote command must use the server-side current entity as the source of truth.
@@ -93,6 +93,8 @@ For CLI and local development:
 2. Do not use `hb-sdk login` as a workaround for iframe SDK authentication.
 3. Do not bypass `hb-sdk dev` by adding a second browser mock host.
 4. Keep the Vite `miniappManifest()` plugin enabled so builds only start in a compatible APP Runtime. Normal deploy always runs the project build.
+5. Keep Mock Host permission overrides in devtools-only memory. They must not rebuild the iframe, interrupt Vite HMR, mutate online permissions, or be passed through URL query parameters.
+6. Treat remote dev context as optional diagnostics and initialization data. Do not use a public mini-program detail request as a dev startup gate.
 
 For host/runtime/protocol-maintenance code:
 

package/skill/references/api-protocol.md

@@ -31,6 +31,13 @@ export {
   SDK_LOCATION_REPORT_METHOD,
 } from './protocol/constants';
 export { isMiniProgramBridgeMessage } from './protocol/guards';
+export { isManagedMiniProgramRuntimePermissionKey, parseMiniProgramRuntimePermissions } from './protocol/runtime-permissions';
+export type {
+  MiniProgramRuntimePermissionEntry,
+  MiniProgramRuntimePermissionStatus,
+  MiniProgramRuntimePermissionsSnapshot,
+  ParsedMiniProgramRuntimePermissions,
+} from './protocol/runtime-permissions';
 export type {
   MiniProgramBridgeError,
   MiniProgramBridgeMessage,
@@ -139,11 +146,7 @@ export type {
   MiniProgramShareChannel,
   MiniProgramShowShareMenuOptions,
 } from './modules/share';
-export type {
-  GetStoragePayload,
-  GetStorageResult,
-  SetStoragePayload,
-} from './modules/storage';
+export type { GetStoragePayload, GetStorageResult, SetStoragePayload } from './modules/storage';
 export type {
   GetWindowInfoPayload,
   GetWindowInfoResult,
@@ -173,13 +176,7 @@ export type {
   ShowToastPayload,
   ShowToastResult,
 } from './modules/ui';
-export type {
-  MiniProgramVibrateIntensity,
-  SetClipboardPayload,
-  SetClipboardResult,
-  VibratePayload,
-  VibrateResult,
-} from './modules/device';
+export type { MiniProgramVibrateIntensity, SetClipboardPayload, SetClipboardResult, VibratePayload, VibrateResult } from './modules/device';
 export type {
   ClosePayload,
   CloseResult,
@@ -210,18 +207,22 @@ Reference 由 `@heybox/hb-sdk` 的公开导出与源码注释自动生成，不
 
 | 导出面 | 说明 |
 | --- | --- |
-| [Root API](api-root.md) | 来自 `src/index.ts` 的默认导出、命名导出与公开能力。 |
-| [Protocol API](#public-protocol-entrypoint) | 来自 `src/protocol.ts` 的协议常量、消息类型与 method 契约。 |
+| [Root API](api-root.md) | `@heybox/hb-sdk` 的默认导出、命名导出与公开能力。 |
+| [Protocol API](#public-protocol-entrypoint) | `@heybox/hb-sdk/protocol` 的协议常量、消息类型与 method 契约。 |
+| [Miniapp Publish API](https://open.xiaoheihe.cn/docs/hb_sdk/reference/miniapp-publish/) | `@heybox/hb-sdk/miniapp-publish` 的构建产物发布前的公开校验工具。 |
+| [Vite API](https://open.xiaoheihe.cn/docs/hb_sdk/reference/vite/) | `@heybox/hb-sdk/vite` 的Vite 工坊小程序插件。 |
 
 ## 查询建议
 
 - 想查业务接入路径：先看 [Guide](recipes.md)。
-- 想查导出符号：从 Root API 或 Protocol API 进入对应分类页。
+- 想查导出符号：从上方对应公开入口进入分类页。
 - 想看场景化用法：优先看 Guide / Recipes 页面中的“进一步阅读”。
 
 ## 统计
 
 | 导出面 | Classes | Functions | Interfaces | Types | Constants |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| Root API | 2 | 3 | 66 | 57 | 4 |
-| Protocol API | 0 | 1 | 43 | 68 | 35 |
+| Root API | 2 | 3 | 66 | 57 | 0 |
+| Protocol API | 0 | 3 | 43 | 67 | 32 |
+| Miniapp Publish API | 0 | 5 | 2 | 0 | 0 |
+| Vite API | 0 | 1 | 0 | 0 | 0 |

package/skill/references/api-root.md

@@ -19,7 +19,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.6.3`
+- Version at generation time: `0.6.4`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -450,7 +450,9 @@ SDK 需要在黑盒小程序 iframe 容器内运行。父容器会为页面注
 npm run dev
 ```
 
-调试页会通过 iframe 加载本地页面并补齐小程序 bridge 环境；浏览器 Mock 从 mock host 的同源只读 bootstrap 接口读取服务端保留的 Runtime 权限快照，URL query 不能提供或覆盖权限。项目已绑定 `heybox.miniProgramId` 时，可以点击调试页里的「在 Mac 版 APP 中启动」按钮，或在「Mobile App」区域选择局域网网卡后用手机小黑盒 APP 扫码；真机 dev shell 只携带绑定的小程序 ID 和本地页面地址，H5 宿主按 ID 从公开详情接口读取可信 Runtime 权限快照。项目未绑定时仍可使用默认拒绝受管能力的浏览器 Mock，但 Mac 和手机真机入口会明确提示先运行 `hb-sdk remote create` 或 `hb-sdk remote bind <mini-program-id>`，并保持不可用。真实容器加载开发 `mini_url` 前会提示“即将打开未经验证的开发网页。该页面可能由本机或局域网服务提供，请确认来源可信后继续。”，用户确认后才继续加载。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
+调试页会通过 iframe 加载本地页面并补齐小程序 bridge 环境。`hb-sdk dev` 的基础启动只依赖本地页面地址：即使项目未绑定、CLI 未登录或远端暂时不可用，浏览器 Mock、Mac 启动协议和手机二维码也会继续生成，真机 dev shell 以匿名本地沙箱加载 `mini_url`，不会把公开 `detail` 查询作为启动门禁。项目已绑定时会限时 3 秒读取远端 dev context；成功后 Mock Host 用真实 Runtime 权限快照初始化本地模拟，失败或超时则显示脱敏警告，并默认拒绝 `network.request` 等受管能力。需要定位降级原因时可使用 `hb-sdk dev --verbose`；详细错误只写入本地调试日志，其中 URL 用户名、密码和敏感 query/hash 会被遮蔽，不会进入 LAN bootstrap。
+
+Mock Host 可以在内存中切换 devtools-only 的 `network.request` 权限，不会重建 iframe，因此不影响 Vite HMR；官方域名权限只读取线上快照，本地设置不会修改线上权限。调试页会对比已读取的线上快照，提示本地放开但上线后会返回 `PERMISSION_DENIED` 的差异。权限快照只通过 mock host 的同源只读 bootstrap 接口传递，URL query 不能提供或覆盖权限。真实容器加载开发 `mini_url` 前会提示“即将打开未经验证的开发网页。该页面可能由本机或局域网服务提供，请确认来源可信后继续。”，用户确认后才继续加载。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP；遇到这种情况时，请在系统浏览器中打开同一个调试页后重试。
 
 在未使用脚手架的 Vite 项目中，可以把命令加到 `package.json`：