@heybox/hb-sdk 0.9.1-alpha.11 → 0.9.1-alpha.13

package/dist/devtools/browser-dev-host/index.html

@@ -5,9 +5,9 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="theme-color" content="#f4f5f7" />
     <title>小程序工坊调试台</title>
-    <script type="module" crossorigin src="/assets/index-CuH8wWTJ.js"></script>
-    <link rel="modulepreload" crossorigin href="/assets/desktop-app-launch-D1z3MxUY.js">
-    <link rel="stylesheet" crossorigin href="/assets/index-BRxbUJVN.css">
+    <script type="module" crossorigin src="/assets/index-V5tDukHZ.js"></script>
+    <link rel="modulepreload" crossorigin href="/assets/desktop-app-launch-DHAqShPh.js">
+    <link rel="stylesheet" crossorigin href="/assets/index-7Cq8iNcD.css">
   </head>
   <body>
     <div id="app"></div>

package/dist/index.cjs.js

@@ -282,7 +282,7 @@ function isPlainObject$2(value) {
  * `data` 仅作为可选调试信息，不保证结构稳定。错误码是跨 Host 的分支契约；
  * `message` 只用于日志和开发者提示，不应作为机器判断条件。
  *
- * 常见处理类别包括：`INVALID_PARAMS`（修正调用参数）、`PERMISSION_NOT_DECLARED`
+ * 常见处理类别包括：`INVALID_PARAMS`（修正调用参数）、`PERMISSION_NOT_IN_SNAPSHOT`
  * 或 `PERMISSION_DENIED`（检查 Manifest/平台批准）、`USER_GESTURE_REQUIRED`
  *（改为用户点击后重试）、`AUTHORIZATION_CANCELLED`（结束当前流程），以及
  * `METHOD_FORBIDDEN`（当前 Host 不支持该能力）。具体能力还可能返回模块专属错误码。
@@ -7278,7 +7278,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.1-alpha.11';
+    : '0.9.1-alpha.13';
 
 const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
 const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);
@@ -10270,6 +10270,12 @@ function decodeBase64Url(value) {
  * @see {@link MiniProgramScreenshotOptions}
  */
 function screenshot(requester, options) {
+    try {
+        console.warn('[hb-sdk] share.screenshot 行为变更提醒：正式版 SDK 0.9.1 及以上默认添加小程序品牌水印；低于 0.9.1（含预发布版本）的 SDK 保持无水印截图。升级前请在目标截图区域底部预留至少 57 个逻辑像素，避免遮挡重要内容；watermarkTheme 的 light 为黑色水印，dark 为白色水印且是默认值，不自动跟随系统主题。系统按键截图不在此能力范围内。');
+    }
+    catch {
+        // 日志输出失败不能阻断截图调用。
+    }
     return requester.request(SHARE_SCREENSHOT_METHOD, options);
 }
 

package/dist/index.esm.js

@@ -278,7 +278,7 @@ function isPlainObject$2(value) {
  * `data` 仅作为可选调试信息，不保证结构稳定。错误码是跨 Host 的分支契约；
  * `message` 只用于日志和开发者提示，不应作为机器判断条件。
  *
- * 常见处理类别包括：`INVALID_PARAMS`（修正调用参数）、`PERMISSION_NOT_DECLARED`
+ * 常见处理类别包括：`INVALID_PARAMS`（修正调用参数）、`PERMISSION_NOT_IN_SNAPSHOT`
  * 或 `PERMISSION_DENIED`（检查 Manifest/平台批准）、`USER_GESTURE_REQUIRED`
  *（改为用户点击后重试）、`AUTHORIZATION_CANCELLED`（结束当前流程），以及
  * `METHOD_FORBIDDEN`（当前 Host 不支持该能力）。具体能力还可能返回模块专属错误码。
@@ -7274,7 +7274,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.1-alpha.11';
+    : '0.9.1-alpha.13';
 
 const RUNTIME_MODES = new Set(['production', 'preview', 'development', 'unknown']);
 const OPERATING_SYSTEM_NAMES = new Set(['android', 'ios', 'ohos', 'windows', 'macos', 'linux', 'unknown']);
@@ -10266,6 +10266,12 @@ function decodeBase64Url(value) {
  * @see {@link MiniProgramScreenshotOptions}
  */
 function screenshot(requester, options) {
+    try {
+        console.warn('[hb-sdk] share.screenshot 行为变更提醒：正式版 SDK 0.9.1 及以上默认添加小程序品牌水印；低于 0.9.1（含预发布版本）的 SDK 保持无水印截图。升级前请在目标截图区域底部预留至少 57 个逻辑像素，避免遮挡重要内容；watermarkTheme 的 light 为黑色水印，dark 为白色水印且是默认值，不自动跟随系统主题。系统按键截图不在此能力范围内。');
+    }
+    catch {
+        // 日志输出失败不能阻断截图调用。
+    }
     return requester.request(SHARE_SCREENSHOT_METHOD, options);
 }
 

package/dist/protocol.cjs.js

@@ -1299,7 +1299,7 @@ function isManagedMiniProgramRuntimePermissionKey(key) {
  * `requirement`：`kind: 'none'` 不读取权限；`kind: 'all'` 要求列出的每个 canonical entry 都存在
  * 且 `status === 'enabled'`。之后仍需通过 Host capability、可信手势、用户授权、参数和业务
  * policy。当前 Runtime 对 `valid: false` 按空权限表 fail closed，受保护 method 会得到
- * `PERMISSION_NOT_DECLARED`，而不是沿用输入中的部分 enabled entry。
+ * `PERMISSION_NOT_IN_SNAPSHOT`，而不是沿用输入中的部分 enabled entry。
  *
  * @example
  * ```ts

package/dist/protocol.esm.js

@@ -1297,7 +1297,7 @@ function isManagedMiniProgramRuntimePermissionKey(key) {
  * `requirement`：`kind: 'none'` 不读取权限；`kind: 'all'` 要求列出的每个 canonical entry 都存在
  * 且 `status === 'enabled'`。之后仍需通过 Host capability、可信手势、用户授权、参数和业务
  * policy。当前 Runtime 对 `valid: false` 按空权限表 fail closed，受保护 method 会得到
- * `PERMISSION_NOT_DECLARED`，而不是沿用输入中的部分 enabled entry。
+ * `PERMISSION_NOT_IN_SNAPSHOT`，而不是沿用输入中的部分 enabled entry。
  *
  * @example
  * ```ts

package/dist/vite.cjs.js

@@ -10282,7 +10282,7 @@ async function ensureBasicInfoDirectory(rootPath, relative) {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.1-alpha.11';
+    : '0.9.1-alpha.13';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。

package/dist/vite.esm.js

@@ -10279,7 +10279,7 @@ async function ensureBasicInfoDirectory(rootPath, relative) {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.9.1-alpha.11';
+    : '0.9.1-alpha.13';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。

package/docs/runtime-host-migration.md

@@ -89,7 +89,9 @@ Storage 面板只通过 `runtime.diagnostics.storage?.getSnapshot()` 读取 Runt
 | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
 | Browser Dev Host       | 私有 WebSocket channel 优先，HTTP/SSE 保留为兼容路径。账号 identity 的 canonical 读取仍由 HTTP session status 完成；channel 只发 revision hint，收到 hint 后重新读取 HTTP 状态。                                                                                                                                          | WebSocket 握手、重连或消息失败不阻断 Browser Mock；回退 HTTP/SSE 并继续有界轮询。                  |
 | Mobile Release         | 当前稳定客户端继续把原生 `mini_url` launch 交给详情 H5/Native Host；二维码保持 HTTPS `open_inapp` 与 `heybox://` `openWindow`，但短链这一跳是普通 H5。跳转页打开完整 sandbox query（`mini_url`、身份、启动票和 LAN Dev Context）后延迟 `closeWindow`。真机 WebView 基址是 `http://127.0.0.1` 详情页且 HTML 来自线上缓存。 | 生成真机二维码前仍需 CLI 登录、项目绑定和有效 Dev Context；这些条件不阻断 Browser 调试台启动。     |
-| Mobile Debug/Ad-Hoc H5 | `dev_context_url` 是可选的 Dev Session 输入；读取成功后采用本地 network proxy，代理不参与 Runtime 权限判断。 | Dev Context 缺失、过期、不可达或校验失败时记录脱敏诊断，继续使用原生 Host 的账号、网络与远端权限。 |
+| Mobile Debug/Ad-Hoc H5 | `dev_context_url` 是可选的 Dev Session 输入；读取成功后采用本地 network proxy，代理不参与 Runtime 权限判断。 | 历史协议 Dev Context 不可用时保留原生适配；新开发协议缺少有效描述时阻断并提示重试或更新 CLI。 |
+
+开发快照与凭据续期的权威约定见[开发会话](./development-session.md)。
 
 `DevSession` 同时携带本地声明、独立的 `local_dev_grant` 与 context revision，不会反向修改线上配置。真实 H5 必须先以启动票取得 canonical identity，再将可信线上基线与声明及严格解析的 grant 合成普通 Runtime 快照；没有有效票据或非法 grant 时不临时放权。临时授权仅允许 `network` / `companion`，不包含 `useOfficialDomain`，且每次启动由用户确认。
 
@@ -101,7 +103,7 @@ Node 负责 CLI-owned stable context endpoint、短跳转 registry 和 Launch Re
 
 ## Mobile 短跳转安全边界
 
-默认 Mobile 二维码编码现有 `https://api.xiaoheihe.cn/open_inapp/#heybox://...` 启动契约，但短链这一跳是普通 H5 `openWindow`（不带 `mini_program`），`webview.url` 只放局域网短链 `http://<lan-ip>:<port>/l/<token>`。短链返回 HTML 跳转页：先 `location.href` 打开完整 `heybox-mini-dev://sandbox` 协议，约 500ms 后再发 `closeWindow` 关掉中间页。不要对自定义协议做 HTTP 302，WebView 会把它当成相对路径。真机 WebView 基址是 `http://127.0.0.1/tools/user_miniprogram/detail`，HTML 来自线上详情页缓存，因此最终协议携带 `mini_url`、`mini_program_id`、`local_dev_launch_token`、`sdk_version` 和稳定 CLI-owned `dev_context_url`；二维码短期 token 轮换不会让已打开页面失效。`launch.json` 仍可作为同分支详情 Host 的补充发现。Dev Context 过期或校验失败时记录脱敏诊断，继续使用原生网络与已发现的权限。
+默认 Mobile 二维码编码现有 `https://api.xiaoheihe.cn/open_inapp/#heybox://...` 启动契约，但短链这一跳是普通 H5 `openWindow`（不带 `mini_program`），`webview.url` 只放局域网短链 `http://<lan-ip>:<port>/l/<token>`。短链返回 HTML 跳转页：先 `location.href` 打开完整 `heybox-mini-dev://sandbox` 协议，约 500ms 后再发 `closeWindow` 关掉中间页。不要对自定义协议做 HTTP 302，WebView 会把它当成相对路径。真机 WebView 基址是 `http://127.0.0.1/tools/user_miniprogram/detail`，HTML 来自线上详情页缓存，因此最终协议携带 `mini_url`、`mini_program_id`、`local_dev_launch_token`、`sdk_version` 和稳定 CLI-owned `dev_context_url`；二维码短期 token 轮换不会让已打开页面失效。`launch.json` 仍可作为同分支详情 Host 的补充发现。新开发协议的 Dev Context 过期或校验失败时不能生成新运行快照；历史适配边界见开发会话文档。
 
 `launch.json` 和短链都只减少二维码编码长度，不是认证、加密、签名或 HMAC：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.9.1-alpha.11",
+  "version": "0.9.1-alpha.13",
   "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.1-alpha.11"
+    "@heybox/hb-sdk-protocol": "0.9.1-alpha.13"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -129,7 +129,7 @@
     "@ai-desktop/view-contract": "file:../hb-sdk-protocol/vendor/view-contract-2.2.2-6ac49bbf6410.tgz",
     "rollup-plugin-dts": "6.4.0",
     "@heybox-domain/heybox-theme": "~0.1.0",
-    "@heybox/hb-sdk-runtime": "~0.9.1-alpha.11",
+    "@heybox/hb-sdk-runtime": "~0.9.1-alpha.13",
     "@heybox/hb-api": "~1.28.14",
     "@heybox-domain/heybox-vue3-ui": "~0.1.0",
     "@heybox/runtime": "~0.2.1",

package/skill/SKILL.md

@@ -7,6 +7,16 @@ description: Uses @heybox/hb-sdk and the hb-sdk CLI to build, debug, review, and
 
 Use this Skill for workshop mini-program application code, project declarations, public SDK APIs, CLI workflows, Host/Runtime protocol maintenance, and publishing review.
 
+## Screenshot API Changes: Mandatory Upgrade Checks
+
+Before implementing screenshot flows or upgrading the SDK, use the canonical documentation index to read the screenshot Reference, community-sharing Recipe, and upgrade notes. Explicitly explain these changes to the developer:
+
+- Check the installed SDK against the watermark version cutoff, including prerelease ordering. Explain the warning emitted by the SDK screenshot entry and the Runtime's compatibility behavior for legacy screenshots versus the default watermark behavior for newer SDKs.
+- Check the required reserved area at the bottom of the capture region, the content that must remain unobstructed, and the corresponding rules for custom capture rectangles.
+- Check the light/dark theme option, default colors, system-theme behavior, and the support boundary between SDK screenshots and physical-button screenshots.
+
+Before upgrading, verify both the page layout and the captured image. Do not only update the dependency or invocation without explaining screenshot behavior changes. Read exact version cutoffs, dimensions, parameters, and Host support from the canonical documentation fetched for this task; never substitute an older installed Skill snapshot.
+
 ## Canonical Documentation
 
 The only maintained hb-sdk guidance source is:

package/skill/skill.json

@@ -1,16 +1,16 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.9.1-alpha.11+skill.3260e7d71ada",
+  "skillVersion": "0.9.1-alpha.13+skill.c3a240ca503a",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.9.1-alpha.11",
-    "compatibility": "0.9.1-alpha.11"
+    "version": "0.9.1-alpha.13",
+    "compatibility": "0.9.1-alpha.13"
   },
   "distribution": {
     "type": "npm",
     "package": "@heybox/hb-sdk",
-    "version": "0.9.1-alpha.11",
+    "version": "0.9.1-alpha.13",
     "path": "skill"
   },
-  "integrity": "sha256-3260e7d71ada646d5d8b269490e3de4b5ecd3fe824b18cdb73fe64247738ffea"
+  "integrity": "sha256-c3a240ca503a1e5f3b15033e091f1fa79a8b70585aa0d8d8fa0b332daec60ac5"
 }

package/types/index.d.ts

@@ -2079,7 +2079,7 @@ interface MiniProgramNetworkModule {
  * `data` 仅作为可选调试信息，不保证结构稳定。错误码是跨 Host 的分支契约；
  * `message` 只用于日志和开发者提示，不应作为机器判断条件。
  *
- * 常见处理类别包括：`INVALID_PARAMS`（修正调用参数）、`PERMISSION_NOT_DECLARED`
+ * 常见处理类别包括：`INVALID_PARAMS`（修正调用参数）、`PERMISSION_NOT_IN_SNAPSHOT`
  * 或 `PERMISSION_DENIED`（检查 Manifest/平台批准）、`USER_GESTURE_REQUIRED`
  *（改为用户点击后重试）、`AUTHORIZATION_CANCELLED`（结束当前流程），以及
  * `METHOD_FORBIDDEN`（当前 Host 不支持该能力）。具体能力还可能返回模块专属错误码。
@@ -3451,7 +3451,12 @@ interface MiniProgramShareModule {
      * `pixelRatio` 换算，也不把越界矩形夹取到窗口内。JavaScript 的 coercible 非 number 值可能被
      * 当前 Runtime 接受，但这不是 TypeScript 公共合同，不应依赖。
      *
-     * Runtime 会在截图区域底部居中叠加「小黑盒 + 搜索图标 + 当前小程序名称」胶囊，
+     * SDK 每次调用都会输出 warning，提醒水印行为变化及布局、配色要求；日志失败不阻断截图。
+     * 新 Runtime 按 Version record 中已校验的 SDK 版本启用水印：低于正式版 `0.9.1`
+     * （包括 `0.9.1-alpha.*`）或兼容模式下版本缺失时，静默保持无水印截图；
+     * `0.9.1` 及以上默认添加水印。升级 SDK 前应同步调整截图布局。
+     *
+     * 启用水印时，Runtime 会在截图区域底部居中叠加「小黑盒 + 搜索图标 + 当前小程序名称」胶囊，
      * 下方显示灰色「小黑盒工坊小程序」。开发者应在目标截图区域底部预留至少 57 个逻辑
      * 像素的空白背景，不放置成绩、正文、按钮等重要内容，并保证背景与所选水印配色
      * 有足够对比度；自定义 `rect` 也按该区域的底部预留。水印不增加图片尺寸，只在本次