@skillbuilder/miniapp-simulator 0.0.0-beta-20261023084421 → 0.2.0

package/README.md

@@ -45,6 +45,57 @@ import {
 } from "@skillbuilder/miniapp-simulator";
 ```
 
+## Worker Guard
+
+设备封印与 Worker Guard 合并在同一份安全 IIFE 中，只在页面业务代码之前执行。**用户 `worker.js` 必须原字节加载，
+不解析、不拼接、不包装、不注入代码**；Worker 内保持原生 API，限制由入口响应 CSP 执行。
+
+```ts
+const simulator = createMiniAppSimulator({
+  mount: "#preview",
+  serviceWorker: { scriptUrl: "/miniapp-simulator/service-worker.js" },
+  security: { worker: { enabled: true } },
+});
+// 业务按原生 URL 规则加载脚本，例如 new Worker("./tasks/compute.js")。
+```
+
+默认关闭 Worker，`loadZip` / `loadFiles` 通过 `enabled` 开关启用 classic Worker。
+脚本地址按原生 URL 规则解析，资源 SW 为当前包中的 Worker 文件返回原始字节与 CSP。
+页面 CSP 仅允许同源 Worker 资源；module、SharedWorker 与业务 Service Worker 禁用。
+`loadApp` 远程加载和 Electron webview 使用关闭配置。
+
+安全脚本在 miniapp-js-api 仓库的 miniapp-secure-runtime 中构建。
+模拟器只消费构建好的 `device-capabilities-seal.iife.min.js` 文件，不依赖该 npm 包或其源码、函数、类型。
+模拟器自己维护能力枚举、配置、CSP 策略及 `src/worker/adapters/` 中的资源与宿主生命周期接线。
+客户端与模拟器使用相同脚本字节，通过 `sync:secure-runtime` 显式同步到本地注入文件。
+构建上限为 20,000 字节（UTF-8，未 gzip），超限失败。无解析器、外部 import 或运行时加载。
+
+宿主在安全脚本执行前注入只读 `__MINITOOL_WORKER_CONTEXT__`，配置包含 `protocolVersion: 1`、
+独立执行 `sessionId`、`enabled` 与可选初始可见状态 `initialState`。
+页面每次执行最多一个原生 Worker，支持原生消息、继承和数据转移；页面销毁后永久关闭。
+连续隐藏 30 秒后回收；未满 30 秒恢复可见取消计时。`Worker.prototype.onTerminate/offTerminate`
+订阅终止原因：业务主动为 `主动`，平台回收为 `system`；恢复后由业务自行重建。
+宿主用只读 `__MINITOOL_WORKER_CONTEXT__` 配置 Worker；`__MINITOOL_WORKER_STATE__` 和启动参数输出实时状态。
+客户端只维护 Worker 总开关，OffscreenCanvas、WebGL、ArrayBuffer 转移与 ImageBitmap 由业务 JS 检测原生支持情况。
+显式 terminate 释放名额，普通 error 不释放。`self.close()` 无法从页面可靠感知，名额保守保留到
+父页面显式 terminate 或会话结束，不增加任何管理消息。
+
+资源层校验文件与页面归属，原样返回文件字节并设置独立 CSP、MIME 与 nosniff；失败直接 403，
+不回源。`connect-src 'none'` 限制网络，`script-src 'none'` 限制追加脚本与动态求值，
+`worker-src 'none'` 与 `child-src 'none'` 限制子 Worker。客户端需在资源加载层下发相同 Worker CSP。
+
+公共运行时协议为 1，模拟器资源 Service Worker 协议为 4，Runtime 与资源 SW 随同一 release 发布。
+JS 配额属于当前 Realm 的软限制，其他 Realm、硬 CPU/内存限制和 Worker 内额外平台 API 由容器控制。
+具体多端接入与限制见 [Worker Guard 接入说明](docs/worker-runtime.md)。
+Worker CSP 支持独立 Apollo Key `miniappSimulatorWorkerCspPolicies`，经 runtime-config 的
+`workerCsp` 字段下发；本地配置为 `security.workerCsp`。配置缺失或非法时采用内置策略，
+仅对新建连接及挂载生效，不改变用户文件内容。
+
+```bash
+pnpm --filter @skillbuilder/miniapp-simulator test:worker
+# 使用已有 Chromium：WORKER_SEAL_CHROMIUM_EXECUTABLE=/absolute/path/to/chrome pnpm --filter @skillbuilder/miniapp-simulator test:worker
+```
+
 ## 快速接入
 
 ```ts
@@ -146,7 +197,7 @@ const workbench = createMiniAppWorkbench({
   projectName: "demo-minitool",
   viewport: { width: 393, height: 852 },
   remote: {
-    serviceUrl: "https://miniapp-sandbox.beta.xiaohongshu.com/simulator/",
+    serviceUrl: "https://miniapp-sandbox.xiaohongshu.com/simulator/",
     appId: "demo-minitool",
     businessLine: BusinessLine.skillDesignable,
   },
@@ -193,7 +244,6 @@ pnpm --filter @skillbuilder/miniapp-simulator mock:cli-dev -- \
 外部 CLI 只需直接安装本包：`--dir` 对应 Node 入口的 `rootDir`，`--no-open` 由 CLI 自己控制打开浏览器，`-h` / `--help` 输出帮助。
 设备、场景、入口识别和文件监听由工作台处理；完整参数与职责见 [`external-cli-workbench.md`](./docs/external-cli-workbench.md)。
 
-发布前运行 `pnpm --filter @skillbuilder/miniapp-simulator test:package`，会真实打包并在仓库外从 tarball 安装，验证导出、类型和本地服务。
 `prepack` 自动执行本地构建；不执行上传或发布。Runtime / SW 仍从远程服务动态加载，外网可达性需单独验收。
 当前验证范围及外发门禁见 [`npm-integration-verification.md`](./docs/npm-integration-verification.md)。