@heybox/hb-sdk 0.8.0-alpha → 0.8.0-alpha.12

package/dist/vite.esm.js

@@ -5,7 +5,30 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.0-alpha';
+    : '0.8.0-alpha.12';
+
+/**
+ * iframe 与调试台页面的开发期 console 捕获转发。
+ *
+ * 双条件门控（iframe 转发）：
+ * 1. 构建期：`hb-sdk dev`（vite serve）注入 `false`；`hb-sdk build` /
+ *    `vite build`（生产）永不注入或替换为 `false`，本模块被死代码消除。
+ * 2. 运行期：仅在 `window.name` 为 `__hb_sdk_mini_dev__` 的调试 iframe 中激活，
+ *    用户设备上的正式运行环境没有该标记。
+ *
+ * 无侵入 patch `console.log/debug/info/warn/error`：原样放行（DevTools 不受影响）+
+ * 通过 `window.parent.postMessage` 转发给调试台（CSP 的 connect-src 不约束 postMessage，
+ * 网络上报由调试台页面代理）。发送全程静默：失败不得回打 console，避免自触发死循环。
+ *
+ * 激活时机：由 SDK 默认单例初始化时调用（业务 `import '@heybox/hb-sdk'` 即生效）；
+ * iframe 标记由调试台 `iframe.name` 与 vite dev 注入的无依赖 bootstrap 共同设置。
+ * 调试台页面自身（runtime 跑在这里，`[hb-sdk-runtime]` 日志不经过 iframe）另用
+ * `installMiniDevConsoleSelfCapture` 接入「日志」页签（source: 'host'）。
+ */
+const MINI_DEV_IFRAME_WINDOW_NAME = '__hb_sdk_mini_dev__';
+const MINI_DEV_CONSOLE_EVENT_TYPE = 'hb-sdk:mini-dev-console';
+/** 调试台页面与 iframe bootstrap 共用的已安装标记（window/console 上的属性名）。 */
+const MINI_DEV_CONSOLE_INSTALL_FLAG = '__hb_sdk_mini_dev_console_installed__';
 
 var re = {exports: {}};
 
@@ -2792,6 +2815,197 @@ function requireSemver () {
 
 var semverExports = requireSemver();
 
+const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
+const MINI_PROGRAM_MESSAGE_VERSION = 2;
+const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
+
+const MINI_PROGRAM_PERMISSION_KEYS = [
+    'userInfo',
+    'steamLibrary',
+    'share',
+    'storage',
+    'filesystem',
+    'clipboard',
+    'leaderboard',
+    'network',
+];
+const MINI_PROGRAM_PERMISSION_CATALOG = [
+    {
+        key: 'userInfo',
+        name: '用户信息',
+        description: '登录小程序并读取当前用户的授权信息。',
+        access: 'declaration',
+        risk: 'medium',
+        config: {},
+        methods: ['auth.login', 'user.getInfo'],
+        conditions: ['继续执行黑盒登录、用户授权和可信手势规则。'],
+    },
+    {
+        key: 'steamLibrary',
+        name: 'Steam 游戏库',
+        description: '读取当前用户授权的 Steam 游戏库。',
+        access: 'declaration',
+        risk: 'high',
+        config: {},
+        methods: ['user.getSteamGameList'],
+        conditions: ['继续执行账号绑定和数据可用性规则。'],
+    },
+    {
+        key: 'share',
+        name: '分享',
+        description: '使用小程序分享、分享菜单和截图能力。',
+        access: 'declaration',
+        risk: 'medium',
+        config: {},
+        methods: ['share.copyLink', 'share.showShareMenu', 'share.screenshot'],
+        conditions: ['继续执行分享参数校验和 Host 支持检查。'],
+    },
+    {
+        key: 'storage',
+        name: '键值存储',
+        description: '读写按小程序隔离的简单键值数据。',
+        access: 'declaration',
+        risk: 'medium',
+        config: {},
+        methods: ['storage.getStorage', 'storage.setStorage'],
+        conditions: ['仅用于简单键值存储，不包含文件系统。'],
+    },
+    {
+        key: 'filesystem',
+        name: '文件系统',
+        description: '访问小程序沙盒文件和用户选择的外部文件。',
+        access: 'declaration',
+        risk: 'high',
+        config: {},
+        methods: [
+            'network.download',
+            'files.pickFiles',
+            'files.pickDirectory',
+            'files.saveFile',
+            'file.create',
+            'file.remove',
+            'file.exists',
+            'file.readText',
+            'file.writeText',
+            'file.readBytes',
+            'file.writeBytes',
+            'file.stat',
+            'directory.create',
+            'directory.remove',
+            'directory.exists',
+            'directory.list',
+        ],
+        conditions: ['外部文件继续要求有效的用户选择、会话句柄和匹配的读写模式。'],
+    },
+    {
+        key: 'clipboard',
+        name: '剪贴板',
+        description: '向系统剪贴板写入文本。',
+        access: 'declaration',
+        risk: 'medium',
+        config: {},
+        methods: ['device.setClipboard'],
+        conditions: ['继续执行文本长度和 Host 支持限制。'],
+    },
+    {
+        key: 'leaderboard',
+        name: '排行榜',
+        description: '读写小程序云排行榜。',
+        access: 'declaration',
+        risk: 'medium',
+        config: {},
+        methods: [
+            'cloud.leaderboard.submit',
+            'cloud.leaderboard.getList',
+            'cloud.leaderboard.getCurrentUserEntry',
+            'cloud.leaderboard.deleteCurrentUserEntry',
+            'cloud.leaderboard.getInfo',
+        ],
+        conditions: ['排行榜必须已创建，用户和资源规则保持不变。'],
+    },
+    {
+        key: 'network',
+        name: '网络',
+        description: '通过 network 模块请求或下载外部资源。',
+        access: 'platform-approval',
+        risk: 'high',
+        config: {
+            useOfficialDomain: {
+                type: 'boolean',
+                required: false,
+                default: false,
+                description: '是否申请访问小黑盒官方域名。',
+            },
+        },
+        methods: ['network.request', 'network.download'],
+        conditions: ['声明后仍需平台批准，并继续执行网络安全策略。'],
+    },
+];
+new Set(MINI_PROGRAM_PERMISSION_KEYS);
+
+new Set(MINI_PROGRAM_PERMISSION_KEYS);
+
+const MINIAPP_PERMISSION_KEYS = MINI_PROGRAM_PERMISSION_KEYS;
+function parseMiniappPermissions(value, options) {
+    const sourceLabel = options.sourceLabel ?? 'package.json#heybox.permissions';
+    if (!options.present) {
+        if (requiresExplicitPermissions(options.sdkVersion)) {
+            throw new Error(`${sourceLabel} 在 @heybox/hb-sdk ${options.sdkVersion} 中必须声明；无权限需求时请配置空对象 {}`);
+        }
+        return { declared: false };
+    }
+    if (!isRecord$1(value)) {
+        throw new Error(`${sourceLabel} 必须是 JSON 对象`);
+    }
+    const knownKeys = new Set(MINIAPP_PERMISSION_KEYS);
+    for (const key of Object.keys(value)) {
+        if (!knownKeys.has(key))
+            throw new Error(`${sourceLabel} 包含未知权限：${key}`);
+    }
+    const permissions = {};
+    for (const key of MINIAPP_PERMISSION_KEYS) {
+        if (!Object.prototype.hasOwnProperty.call(value, key))
+            continue;
+        const declaration = value[key];
+        const itemLabel = `${sourceLabel}.${key}`;
+        if (!isRecord$1(declaration))
+            throw new Error(`${itemLabel} 必须是 JSON 对象`);
+        const definition = MINI_PROGRAM_PERMISSION_CATALOG.find((item) => item.key === key);
+        if (!definition)
+            throw new Error(`权限目录缺少定义：${key}`);
+        const allowedFields = new Set(['enabled', ...Object.keys(definition.config)]);
+        for (const field of Object.keys(declaration)) {
+            if (!allowedFields.has(field))
+                throw new Error(`${itemLabel} 包含未知字段：${field}`);
+        }
+        if (typeof declaration.enabled !== 'boolean')
+            throw new Error(`${itemLabel}.enabled 必须是 boolean`);
+        let useOfficialDomain = false;
+        if (key === 'network') {
+            if (declaration.useOfficialDomain !== undefined && typeof declaration.useOfficialDomain !== 'boolean') {
+                throw new Error(`${itemLabel}.useOfficialDomain 必须是 boolean`);
+            }
+            useOfficialDomain = declaration.useOfficialDomain === true;
+        }
+        if (!declaration.enabled)
+            continue;
+        permissions[key] = key === 'network' ? { enabled: true, useOfficialDomain } : { enabled: true };
+    }
+    return { declared: true, permissions: permissions };
+}
+function requiresExplicitPermissions(sdkVersion) {
+    const parsed = semverExports.parse(sdkVersion);
+    if (!parsed)
+        throw new Error(`sdkVersion 必须是合法 SemVer：${sdkVersion}`);
+    return parsed.major > 0 || parsed.minor >= 9;
+}
+function getMissingPermissionsWarning(sourceLabel = 'package.json#heybox.permissions') {
+    return `${sourceLabel} 尚未声明。当前按 0.8 兼容行为构建；0.9.0 起将拒绝构建，请尽快补充权限声明（无权限需求时配置 {}）。`;
+}
+function isRecord$1(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 const MINIAPP_PLATFORM_VALUES = ['android', 'ios', 'ohos', 'windows', 'macos', 'linux'];
 function validateMiniappPackageVersionForBuild(version) {
     return validateMiniappManifestVersion(version, 'package.json.version');
@@ -2805,7 +3019,13 @@ function validateMiniappManifestVersion(version, sourceLabel = 'manifest.version
 }
 function renderMiniappManifest(manifest) {
     const platforms = validateMiniappPlatforms(manifest.platforms, 'manifest.platforms');
-    return `${JSON.stringify({ version: manifest.version, sdkVersion: manifest.sdkVersion, platforms }, null, 2)}\n`;
+    const output = {
+        version: manifest.version,
+        sdkVersion: manifest.sdkVersion,
+        platforms,
+        ...(manifest.permissions === undefined ? {} : { permissions: manifest.permissions }),
+    };
+    return `${JSON.stringify(output, null, 2)}\n`;
 }
 function validateMiniappPlatforms(platforms, sourceLabel = 'platforms') {
     if (!Array.isArray(platforms) || platforms.length === 0) {
@@ -2860,6 +3080,21 @@ function findNearestPackageJsonPath(startDir) {
     }
 }
 function readMiniappVersionFromPackageJson(root) {
+    return readMiniappPackageJson(root, true).version;
+}
+function readMiniappPermissionsFromPackageJson(root, sdkVersion) {
+    const { packageJson } = readMiniappPackageJson(root, false);
+    const heybox = packageJson.heybox;
+    if (heybox !== undefined && !isRecord(heybox)) {
+        throw new Error('@heybox/hb-sdk 提示：package.json#heybox 必须是 JSON 对象');
+    }
+    const present = isRecord(heybox) && Object.prototype.hasOwnProperty.call(heybox, 'permissions');
+    return parseMiniappPermissions(isRecord(heybox) ? heybox.permissions : undefined, {
+        present,
+        sdkVersion,
+    });
+}
+function readMiniappPackageJson(root, requireVersion) {
     const packageJsonPath = findNearestPackageJsonPath(root);
     let content;
     try {
@@ -2875,10 +3110,13 @@ function readMiniappVersionFromPackageJson(root) {
     catch (error) {
         throw new Error(`@heybox/hb-sdk 解析 package.json 失败：${formatReason(error)}`);
     }
-    if (typeof packageJson.version !== 'string' || packageJson.version.trim() === '') {
+    if (requireVersion && (typeof packageJson.version !== 'string' || packageJson.version.trim() === '')) {
         throw new Error('@heybox/hb-sdk 提示：package.json.version 必须是非空字符串');
     }
-    return packageJson.version.trim();
+    return { packageJson, version: typeof packageJson.version === 'string' ? packageJson.version.trim() : '' };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 function formatReason(error) {
     if (error instanceof Error && error.message) {
@@ -11317,10 +11555,6 @@ function parse(html, options) {
     return Parser.parse(html, options);
 }
 
-const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
-const MINI_PROGRAM_MESSAGE_VERSION = 2;
-const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
-
 const HTML_NAMESPACE = 'http://www.w3.org/1999/xhtml';
 const RUNTIME_GATE_MARKER = 'data-heybox-runtime-gate';
 const RUNTIME_GATE_STYLE_MARKER = 'data-heybox-runtime-gate-style';
@@ -11643,8 +11877,29 @@ function shouldSkipMiniappPlatformCspFromEnv(env = process.env) {
     return env[HB_SDK_RUNTIME_PERMISSION_CONTEXT_ENV] === VERIFIED_RUNTIME_PERMISSION_CONTEXT && env[HB_SDK_RUNTIME_USE_OFFICIAL_DOMAIN_ENV] === '1';
 }
 
+/**
+ * dev serve 时在入口 HTML 最早位置注入无依赖 console 捕获 bootstrap。
+ *
+ * 必须内联完整 patch 逻辑而非等 SDK 模块加载：vite client、业务代码的 console 调用
+ * 都可能早于 SDK 单例初始化（如 [vite] connecting）。捕获条件：
+ * 1. 构建期只有 vite serve 走到本分支（生产构建无此代码，双保险之 define 常量仍注入给 SDK 侧）；
+ * 2. 运行期仅调试 iframe（window.name 标记由调试台 iframe.name 与本 bootstrap 设置）激活。
+ * 转发经 window.parent.postMessage（CSP connect-src 不约束 postMessage），失败静默，
+ * 严禁回打 console 造成自触发循环。SDK 侧 installMiniDevConsoleForwarding 安装时
+ * 检测同款 INSTALL_FLAG，不会重复 patch。
+ */
+function injectMiniDevConsoleBootstrap(html) {
+    const bootstrap = `<script>(function(){var LEVELS=['log','debug','info','warn','error'];var FLAG='${MINI_DEV_CONSOLE_INSTALL_FLAG}';var TYPE='${MINI_DEV_CONSOLE_EVENT_TYPE}';if(window.name!=='${MINI_DEV_IFRAME_WINDOW_NAME}')window.name='${MINI_DEV_IFRAME_WINDOW_NAME}';if(window[FLAG])return;var patched=false;for(var i=0;i<LEVELS.length;i++)(function(level){var original=console[level];if(typeof original!=='function')return;console[level]=function(){try{parent.postMessage({type:TYPE,detail:{level:level,args:Array.prototype.slice.call(arguments),timestamp:Date.now()}},'*')}catch(e){}return original.apply(this,arguments)};patched=true})(LEVELS[i]);if(patched)window[FLAG]=true})();</script>`;
+    const headIndex = html.indexOf('<head>');
+    if (headIndex < 0) {
+        return html;
+    }
+    const insertAt = headIndex + '<head>'.length;
+    return `${html.slice(0, insertAt)}${bootstrap}${html.slice(insertAt)}`;
+}
 const sdkVersionPlaceholder = ['__HB_SDK', 'VERSION__'].join('_');
 const sdkVersionBuildConstant = ['__HB_SDK_BUILD', 'VERSION__'].join('_');
+const miniDevLoggingConstant = ['__HB_SDK_DEV', 'LOGGING__'].join('_');
 function miniappManifest(options) {
     const platforms = validateMiniappPlatforms(options?.platforms, 'miniappManifest().platforms');
     const skipPlatformCsp = shouldSkipMiniappPlatformCspFromEnv();
@@ -11656,12 +11911,17 @@ function miniappManifest(options) {
     let priorBuildError;
     return {
         name: 'heybox-miniapp-manifest',
-        config(config) {
+        config(config, env) {
             assertMiniappViteBase(config.base);
+            // command 在本钩子时序早于 configResolved，必须取自 env 命令而非闭包；
+            // 旧调用方（测试等）未传 env 时按 build 处理。
+            const isServe = env?.command === 'serve';
             return {
                 ...(config.base === undefined ? { base: './' } : {}),
                 define: {
                     [sdkVersionBuildConstant]: JSON.stringify(resolveSdkVersion()),
+                    // 仅 vite serve（hb-sdk dev）注入；vite build / hb-sdk build 永不注入，捕获模块被死代码消除。
+                    ...(isServe ? { [miniDevLoggingConstant]: 'true' } : {}),
                 },
             };
         },
@@ -11683,12 +11943,12 @@ function miniappManifest(options) {
             }
         },
         transformIndexHtml(html) {
-            return enforceMiniappHtmlPolicy(html, {
+            const enforced = enforceMiniappHtmlPolicy(html, {
                 ...(command === 'serve' ? { hmrWebSocketUrl } : {}),
                 skipPlatformCsp,
             });
-        },
-        async closeBundle() {
+            return command === 'serve' ? injectMiniDevConsoleBootstrap(enforced) : enforced;
+        }, async closeBundle() {
             // Rollup 在 buildStart/transform 失败后仍会调用 closeBundle。
             // 若此时再抛「缺 index.html」等二次错误，会掩盖真实失败原因。
             if (priorBuildError) {
@@ -11696,6 +11956,9 @@ function miniappManifest(options) {
             }
             const version = validateMiniappPackageVersionForBuild(readMiniappVersionFromPackageJson(root));
             const sdkVersion = resolveSdkVersion();
+            const parsedPermissions = readMiniappPermissionsFromPackageJson(root, sdkVersion);
+            if (!parsedPermissions.declared)
+                this.warn(getMissingPermissionsWarning());
             const outputRoot = path.resolve(root, outDir);
             const htmlFiles = collectHtmlFiles(outputRoot);
             const unexpectedHtmlFiles = htmlFiles.filter((file) => path.relative(outputRoot, file) !== 'index.html');
@@ -11711,7 +11974,12 @@ function miniappManifest(options) {
             writeFileSync(indexHtmlPath, enforceMiniappHtmlPolicy(readFileSync(indexHtmlPath, 'utf8'), { skipPlatformCsp }));
             const manifestPath = path.join(outputRoot, 'manifest.json');
             mkdirSync(path.dirname(manifestPath), { recursive: true });
-            writeFileSync(manifestPath, renderMiniappManifest({ version, sdkVersion, platforms }));
+            writeFileSync(manifestPath, renderMiniappManifest({
+                version,
+                sdkVersion,
+                platforms,
+                ...(parsedPermissions.permissions === undefined ? {} : { permissions: parsedPermissions.permissions }),
+            }));
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.8.0-alpha",
+  "version": "0.8.0-alpha.12",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -44,6 +44,7 @@
   "files": [
     "README.md",
     "CHANGELOG.md",
+    "THIRD_PARTY_NOTICES.md",
     "bin",
     "dist",
     "skill",
@@ -52,12 +53,16 @@
   "keywords": [],
   "author": "",
   "license": "ISC",
+  "engines": {
+    "node": ">=22.20.0"
+  },
   "dependencies": {
     "@msgpack/msgpack": "2.8.0",
     "parse5": "^7.3.0",
+    "skills": "1.5.23",
     "undici": "^7.28.0",
     "ws": "^8.18.0",
-    "@heybox/hb-sdk-protocol": "0.8.0-alpha"
+    "@heybox/hb-sdk-protocol": "0.8.0-alpha.12"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -73,7 +78,8 @@
     "@rollup/plugin-node-resolve": "^16.0.1",
     "@heybox/hb-types": "^1.0.1",
     "@playwright/test": "^1.55.1",
-    "@vitejs/plugin-vue2": "^2.3.3",
+    "@sneas/telephone": "1.1.2",
+    "@vitejs/plugin-vue": "^6.0.1",
     "@rollup/plugin-typescript": "^11.1.6",
     "@types/ejs": "^3.1.5",
     "@types/fs-extra": "^11.0.4",
@@ -82,6 +88,7 @@
     "@types/semver": "^7.7.1",
     "@types/ws": "^8.5.13",
     "@vitest/coverage-v8": "^3.2.4",
+    "@vue/test-utils": "^2",
     "commander": "^12.1.0",
     "cos-nodejs-sdk-v5": "2.15.4",
     "ejs": "^3.1.10",
@@ -89,19 +96,27 @@
     "fs-extra": "^11.3.0",
     "get-port": "^7.1.0",
     "happy-dom": "^19.0.2",
+    "lucide-vue-next": "1.0.0",
+    "markdown-it": "^14.1.0",
     "open": "^10.2.0",
     "ora": "^5.4.1",
     "picocolors": "^1.1.1",
     "qrcode": "^1.5.4",
     "rimraf": "^5.0.5",
+    "reka-ui": "2.10.4",
     "rollup": "^4.52.4",
     "semver": "^7.8.0",
+    "sass-embedded": "1.97.3",
+    "splitpanes": "^4.1.0",
     "typescript": "^5.9.3",
-    "vue": "^2.7.16",
+    "vue": "^3.5.22",
+    "vue-tsc": "^3.3.7",
     "vite": "^8.0.12",
     "vitest": "^3.2.4",
-    "@heybox/hb-api": "~1.25.23",
-    "@heybox/hb-sdk-runtime": "~0.8.0-alpha",
+    "@heybox-domain/heybox-theme": "~0.1.0",
+    "@heybox/hb-api": "~1.28.2",
+    "@heybox/hb-sdk-runtime": "~0.8.0-alpha.12",
+    "@heybox-domain/heybox-vue3-ui": "~0.1.0",
     "@heybox/runtime": "~0.2.0",
     "@heybox/runtime-policy": "~0.2.0",
     "@heybox/runtime-transport-fetch": "~0.2.0"
@@ -117,6 +132,10 @@
           "{projectRoot}/src/**/*",
           "{projectRoot}/devtools/browser-dev-host/**/*",
           "{projectRoot}/scripts/copy-browser-dev-host.cjs",
+          "{projectRoot}/scripts/check-browser-dev-host-assets.cjs",
+          "{projectRoot}/scripts/generate-browser-dev-host-notices.cjs",
+          "{projectRoot}/licenses/**/*",
+          "{projectRoot}/THIRD_PARTY_NOTICES.md",
           "{projectRoot}/rollup.config.ts",
           "{projectRoot}/tsconfig*.json",
           "{workspaceRoot}/packages/hb-sdk-runtime/src/**/*",
@@ -144,30 +163,34 @@
     "build:lib:bundle": "rollup -c rollup.config.ts  --configPlugin 'typescript={\"tsconfig\":\"tsconfig.build.json\"}'",
     "build:cli": "pnpm run build:hb-sdk-protocol && pnpm run build:hb-api-contract && pnpm run build:cli:bundle",
     "build:cli:bundle": "rollup -c rollup.config.ts --environment HB_SDK_BUILD:cli --configPlugin 'typescript={\"tsconfig\":\"tsconfig.build.json\"}' && pnpm run build:browser-dev-host",
-    "build:browser-dev-host": "node scripts/copy-browser-dev-host.cjs",
+    "build:browser-dev-host": "vite build --config vite.browser-dev-host.config.ts && node scripts/check-browser-dev-host-assets.cjs && node scripts/generate-browser-dev-host-notices.cjs",
     "build:templates": "node scripts/copy-cli-templates.cjs",
     "build:types": "tsc -p tsconfig.dts.json",
     "check:boundary": "node scripts/check-boundary.cjs",
-    "check:docs-sync": "pnpm -w exec hbexec hb-sdk check",
+    "check:docs-sync": "pnpm --filter @heybox-docs/docs-hb_sdk run check:reference && node scripts/skill/check-references.mjs && node scripts/skill/validate-skill.mjs",
     "check:compatibility-evidence": "node scripts/validate-compatibility-evidence.mjs",
     "check:api-semver": "node ../../ops/jobs/hb-sdk-docs-contract/semantic-diff.cjs",
     "clean": "rimraf ./dist && rimraf ./types",
     "test:unit": "NODE_OPTIONS='--conditions=heybox' vitest run",
     "test:types:characterization": "tsc -p tsconfig.characterization.json --noEmit --pretty false",
-    "test:types:browser-dev-host": "tsc -p tsconfig.browser-dev-host.json --noEmit --pretty false",
+    "test:types:browser-dev-host": "vue-tsc -p tsconfig.browser-dev-host.json --noEmit --pretty false",
     "test:types": "pnpm run test:types:characterization && pnpm run test:types:browser-dev-host",
     "test:e2e:browser-dev-host": "pnpm run build:browser-dev-host && NODE_OPTIONS='--conditions=heybox' vitest run --config vitest.browser-dev-host-e2e.config.ts",
+    "test:create-template:artifact": "node scripts/test-create-template-artifact.mjs",
     "test:unit:coverage": "NODE_OPTIONS='--conditions=heybox' vitest run --coverage",
     "test:vite": "pnpm run build:hb-sdk-protocol && pnpm run build:hb-api-contract && vitest run --config vitest.vite.config.ts",
     "test:watch": "NODE_OPTIONS='--conditions=heybox' vitest",
     "changelog:draft": "node scripts/changelog-draft.cjs",
     "check:changelog": "node scripts/check-changelog.cjs",
-    "test:release": "node --test scripts/release-family.test.cjs ../../ops/jobs/publish-changed-packages/publish.test.cjs ../../ops/jobs/release-hb-sdk/docs-release-contract.test.cjs",
+    "release:verify-tarball": "node scripts/skill/verify-tarball-install.mjs",
+    "test:release": "node --test scripts/public-changelog.test.mjs scripts/public-changelog-workflow.test.cjs scripts/release-family.test.cjs ../../ops/jobs/publish-changed-packages/publish.test.cjs ../../ops/jobs/release-hb-sdk/docs-release-contract.test.cjs ../../ops/jobs/release-hb-sdk/stable-promote-coordinator.test.cjs",
     "test:compatibility-evidence": "node --test scripts/validate-compatibility-evidence.test.mjs",
     "release:prepare": "node scripts/release-prepare.cjs",
     "release:tag": "node scripts/release-tag.cjs",
     "release:family:dry-run": "node ../../ops/jobs/publish-changed-packages/publish.cjs --dry-run",
     "release:family:promote": "node ../../ops/jobs/publish-changed-packages/publish.cjs --family-action promote",
-    "release:family:rollback": "node ../../ops/jobs/publish-changed-packages/publish.cjs --family-action rollback"
+    "release:family:rollback": "node ../../ops/jobs/publish-changed-packages/publish.cjs --family-action rollback",
+    "release:stable:promote": "node ../../ops/jobs/release-hb-sdk/stable-promote-coordinator.cjs --action promote",
+    "release:stable:rollback": "node ../../ops/jobs/release-hb-sdk/stable-promote-coordinator.cjs --action rollback"
   }
 }

package/skill/SKILL.md

@@ -39,34 +39,35 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 ## Step 4: Implement workshop mini-program code
 
 1. Import the root package eagerly; the SDK starts its handshake automatically and capability calls wait for it internally.
-2. For a network-enabled mini-program, use `auth.login({ scopes? })` to obtain `{ code, expiresIn: 300, scopes }`. Identity is always implicit; request only optional scopes the business actually needs.
-3. Send the code only to the developer's backend. That backend follows the backend OpenAPI documentation to exchange it for a token; mini-program code must never exchange application credentials itself.
-4. For a network-disabled mini-program, call `user.getInfo()` to read the current login state, `userInfo.app_user_id`, and `userInfo.profile`. The Host silently grants the current local user scopes (`identity` and `profile`), so this call does not require a trusted user action or authorization UI. It still cannot obtain a code or call OpenAPI.
+2. Declare protected capabilities in `package.json#heybox.permissions`. `auth.login()` and `user.getInfo()` require `userInfo`; `user.getSteamGameList()` requires `steamLibrary`; none of them implicitly require the public `network` permission.
+3. Use `auth.login({ scopes? })` to obtain `{ code, expiresIn: 300, scopes }`. Identity is always implicit; request only optional scopes the business actually needs.
+4. Send the code only to the developer's backend. That backend follows the backend OpenAPI documentation to exchange it for a token; mini-program code must never exchange application credentials itself.
 5. Handle `HbMiniProgramSDKError` for SDK initialization and capability failures.
 6. Handle `HbMiniProgramNetworkError` separately when HTTP completed but `validateStatus` rejected the status.
 7. Use `getHandshakeState()` for the current persistent handshake state and `onHandshakeStateChange()` for an immediate replay plus future changes. Cancel the returned subscription when the page or component unmounts.
 8. Treat the non-replayed `ready` lifecycle event only as an edge notification. After a duplicate handshake it may repeat, so never use it as state or as the source for enabling a late-mounted control.
 9. Use the default SDK instance exposed by the root package. For gesture-gated controls, initialize from the current handshake state, subscribe to changes, and enable the control only when `status === 'ready'`. Keep calls such as `auth.login()` in the original user-action callback; do not wait for handshake inside that callback.
 10. When authorization UI is required, call `auth.login()` from a trusted user action. Missing gesture returns `USER_GESTURE_REQUIRED`; cancelling, rejecting, or closing returns `AUTHORIZATION_CANCELLED` and does not confirm or change authorization. An already-authorized `auth.login()` request may return a new code silently.
-11. `user.getSteamGameList()` is available only to network-disabled mini-programs. In a network-enabled mini-program it returns `SERVER_API_REQUIRED`, and there is no Steam library authorization scope or OpenAPI resource. Treat `user.getInfo()` returning `SERVER_API_REQUIRED` as a server-boundary signal, not as logged-out state.
-12. Use `share.showShareMenu({ post })` or `share.screenshot({ post })` to preset editable community destinations and topics. Pass partition IDs through `topicIds` and topic text without surrounding `#` through `topics`; do not construct the underlying client post protocol.
-13. Use `share.showShareMenu({ extra })` to open the share menu or `share.copyLink({ extra })` to copy and return the default mini-program share link. Read the JSON-compatible page state synchronously with `share.getExtra()` after launch, validate the developer-defined fields, and fall back to the default page when it returns `undefined`.
+11. Use `share.showShareMenu({ post })` or `share.screenshot({ post })` to preset editable community destinations and topics. Pass partition IDs through `topicIds` and topic text without surrounding `#` through `topics`; do not construct the underlying client post protocol.
+12. Use `share.showShareMenu({ extra })` to open the share menu or `share.copyLink({ extra })` to copy and return the mini-program share link. `share.showShareMenu()` always uses the platform `common_share` landing page and does not accept a custom `url`. Read the JSON-compatible page state synchronously with `share.getExtra()` after launch, validate the developer-defined fields, and fall back to the default page when it returns `undefined`.
+13. New PC enables the retained `files` and `network.download()` contract with persistent sandbox storage, single-file/directory pickers, exact File saving, and public-network streaming downloads. Mobile, Web, Browser Dev Host, and legacy PC return `METHOD_FORBIDDEN` and provide no memory/Blob fallback. Call `files.pickFiles()` / `pickDirectory()` / `saveFile()` only from trusted user actions; `saveFile()` accepts only `suggestedName`, `remove()` only deletes sandbox objects, and non-empty directories require `remove({ recursive: true })`.
+14. Use `network.download()` only with an SDK-created File/Directory target. It is GET-only, does not follow redirects, and exposes local `AbortSignal` / progress callbacks without sending functions over the bridge. Abort is a cancellation intent; a Host commit that already won still resolves successfully.
 
 ## Step 5: Use CLI workflows
 
 1. Use `hb-sdk create <project-name>` to scaffold a workshop mini-program.
-2. Use `hb-sdk dev` for Browser Mock, Mac App, or Mobile App debugging. It requires an active CLI login, a bound Mini-program, and an available remote Dev Context; it must stop before starting Vite or any debugging service when a prerequisite is missing. Mobile uses the `open_inapp` and `heybox://` `openWindow` wrapper with a LAN short URL, then opens `heybox-mini-dev://sandbox` with the complete launch context.
-3. Treat debugging-page permission overrides as local development behavior; overrides do not change remote permissions. Use `--port`, `--browser-dev-host-port`, and `--no-open` to control local endpoints and browser opening. Select a Mobile network interface the device can reach. `launch.json` is a LAN discovery document, not authentication, encryption, signing, or HMAC protection.
+2. Use `hb-sdk dev` for Browser Mock and Mobile App debugging. Browser debugging can start without CLI login, project binding, or a remote Dev Context; capabilities that need those inputs fail explicitly. Mobile uses the single QR entry with the `open_inapp` and `heybox://` `openWindow` wrapper around a LAN short URL, then opens `heybox-mini-dev://sandbox` with the complete launch context.
+3. The debugging page does not edit permissions. Treat the validated remote permission snapshot as canonical Runtime input. Use `--port`, `--browser-dev-host-port`, and `--no-open` to control local endpoints and browser opening. Select a Mobile network interface the device can reach. `launch.json` is a LAN discovery document, not authentication, encryption, signing, or HMAC protection.
 4. Use `hb-sdk build [--env <name>] [--verbose]` as the recommended production build entry. It directly owns the Vite build, always cleans and writes `dist/`, and works without CLI login, project binding, or network access.
 5. Keep `miniappManifest()` explicitly enabled in `vite.config.ts`; `hb-sdk build` must fail when the required Manifest or Runtime gate output is missing.
 6. Keep project typechecking in `scripts.build`, for example `vue-tsc --noEmit && hb-sdk build`; `hb-sdk build` does not run typechecking or invoke `scripts.build` itself.
 7. Existing projects may continue to use `vite build`; do not auto-migrate them. Do not invent `--mode`, `--json`, config, or output-directory flags for `hb-sdk build`.
-8. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` for development, publishing, and Browser Mock Host `heybox-session` requests. Mini-program code must still call `auth.login()`; the debug page only confirms authorization. Do not paste CLI credentials into page JavaScript. Phone debugging continues to use the App login.
+8. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` for remote management, publishing, Mobile debugging, and optional Browser Mock Host `heybox-session` requests. Browser debugging itself can start without CLI login. Mini-program code must still call `auth.login()`; the debug page only confirms authorization. Do not paste CLI credentials into page JavaScript. Phone debugging continues to use the App login.
 9. Use `hb-sdk remote entity current` to confirm the current developer account and `hb-sdk remote entity switch <entity-id>` to change it before remote operations.
 10. Use `hb-sdk remote create` to create and bind a mini-program; use `hb-sdk remote bind <mini-program-id>` to bind an existing manageable mini-program.
 11. Use `hb-sdk remote info`, `hb-sdk remote list`, `hb-sdk remote access`, `hb-sdk remote versions`, `hb-sdk remote preview <version>`, and `hb-sdk remote allowlist ...` for remote inspection and preview management.
 12. Use `hb-sdk remote deploy --release-note <text>` to run the project's `scripts.build`, upload, and submit the current project for audit. Do not recommend the removed top-level `hb-sdk deploy` alias.
-13. `hb-sdk dev` and `hb-sdk remote deploy` skip the platform CSP only when the validated remote permission snapshot has `network.request.status=enabled`. `useOfficialDomain` does not participate in CSP skip decisions. Direct `hb-sdk build`, direct Vite build, anonymous or invalid snapshots, and local Dev Context overrides must keep the platform CSP. Runtime Gate, Manifest, and HTML validation always remain active.
+13. `hb-sdk dev` and `hb-sdk remote deploy` skip the platform CSP only when the current version declares and the platform approves `network`. `useOfficialDomain` does not participate in CSP skip decisions. Direct `hb-sdk build`, direct Vite build, anonymous or invalid snapshots, and local Dev Context overrides must keep the platform CSP. Runtime Gate, Manifest, and HTML validation always remain active.
 14. After approval, use `hb-sdk remote release <version>` for manual release or `--auto-publish` when an eligible low-risk version should release automatically.
 15. Treat approval, release, and public display as separate states. Do not promise square, search, or recommendation visibility after release.
 16. Use `hb-sdk remote withdraw`, `hb-sdk remote take-down`, `hb-sdk remote reopen`, and square visibility commands only after showing the target and obtaining required confirmation.
@@ -81,11 +82,12 @@ For workshop mini-program business code:
 1. Do not read or request tokens, cookies, phone numbers, or private credentials from the SDK.
 2. Do not expose raw share protocol fields, JS callbacks, activity reporting, custom buttons, direct post publishing, or upload-only flows. Public `share.*({ post })` options only preset an editable client post flow and never publish automatically.
 3. Do not use unsupported storage operations such as delete, clear, info listing, or global client storage access.
-4. Use only the public `network.request` configuration.
+4. Use only the public `network.request` / `network.download` configurations.
 5. Do not use private package paths or client protocols.
 6. Build artifacts may include `dist/manifest.json`; business code should not fetch a deployed manifest directly because it is not a CDN asset.
 7. Do not use `network.request()` to reach platform-reserved runtime auth or OpenAPI internal paths.
 8. Do not expose credentials or describe internal Host authorization state machines and routes in app-facing guidance.
+9. Do not invent string paths, File System Access API handles, Blob downloads, uploads, Range/resume, external deletion, move, append, or persistent external grants. Public file operations use only SDK-created handles; deletion is limited to SDK sandbox handles.
 
 For CLI and local development:
 
@@ -93,8 +95,9 @@ For CLI and local development:
 2. Do not skip `auth.login()` in mini-program code. Browser Mock may reuse the Node `hb-sdk login` session for Host network requests, but the page must still call `auth.login()` and handle the authorization dialog. Never paste CLI credentials into page JavaScript.
 3. Use the built-in local debugging page instead of creating another browser Mock.
 4. Keep the Vite `miniappManifest()` plugin enabled.
-5. Treat permission changes made in the `hb-sdk dev` debugging page as local debugging overrides, not online configuration changes. Use the page's reset action to return to the remote baseline.
+5. Do not suggest changing or resetting permissions in the `hb-sdk dev` debugging page; that UI does not exist. Diagnose permission behavior from the remote snapshot and capability result.
 6. Treat browser Mock results as development feedback only. Validate permissions, identity flows, and user interactions again in a real Heybox client before publishing.
+7. The Browser Dev Host offers iPhone 16 Pro Max (`440 x 956`) and Pixel 9 Pro (`410 x 914`) presets. Switching a preset must preserve the iframe, Runtime session, and page state. Authorization/action dialogs, Toast, Loading, and vibration feedback render inside the preview. Use the upper-right QR popover as the only Mobile QR entry.
 
 For host/runtime/protocol-maintenance code:
 
@@ -110,17 +113,16 @@ For host/runtime/protocol-maintenance code:
    - `cat packages/hb-sdk/DOC_SYNC_CHECKLIST.md`
 3. When preparing a package release, run `pnpm --filter @heybox/hb-sdk run release:prepare -- --bump patch` or `pnpm --filter @heybox/hb-sdk run release:prepare -- --version <x.y.z>`. The release assistant updates the Protocol/Runtime/SDK family versions, inserts `packages/hb-sdk/CHANGELOG.md`, and runs `check:changelog`. Use `--ai-command "<command>"` or `HB_SDK_CHANGELOG_AI_COMMAND` when an AI writer should rewrite the Conventional Commit draft. Review the entry for Mini-program developers and Host/Runtime integration maintainers, and do not expose Runtime internal adapter, state-machine, or security-policy details.
 4. When modifying this repo's source skill at `packages/hb-sdk/skill` and preparing distributable artifacts, also run:
-   - `node packages/hb-sdk/skill/scripts/package-skill.mjs`
+   - `node packages/hb-sdk/scripts/skill/sync-references.mjs`
+   - `node packages/hb-sdk/scripts/skill/validate-skill.mjs`
 5. When modifying CLI, local debugging, package exports, or package dependency direction, also run:
    - `pnpm --filter @heybox/hb-sdk run check:boundary`
    - `pnpm --filter @heybox/hb-sdk run test:unit`
-6. Inspect the generated zip before distribution:
-   - `unzip -l packages/hb-sdk/hb-sdk.zip | sed -n '1,120p'`
-7. When adding or modifying the deploy command or its upload pipeline, also run:
+6. When adding or modifying the deploy command or its upload pipeline, also run:
    - `pnpm --filter @heybox/hb-sdk run check:boundary`
    - `pnpm --filter @heybox/hb-sdk run test:unit`
    - Verify `dist/cli.cjs` does not have any `require('cos-nodejs-sdk-v5')` left after `build:cli`; the boundary check enforces this automatically.
-8. Verify the canonical payload before publishing:
-   - `pnpm exec hbexec hb-sdk sync`
-   - `pnpm exec hbexec hb-sdk check`
-   - For a release artifact, run `pnpm exec hbexec hb-sdk sync --out-dir <payload-dir>` and then `pnpm exec hbexec hb-sdk check-artifact --artifact-dir <payload-dir>`.
+7. Verify the canonical payload before publishing:
+   - `node packages/hb-sdk/scripts/skill/sync-references.mjs`
+   - `node packages/hb-sdk/scripts/skill/validate-skill.mjs`
+   - For a release artifact, run `npm pack --dry-run` and `node packages/hb-sdk/scripts/skill/verify-tarball-install.mjs`.