@skillbuilder/miniapp-simulator 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,264 @@
-# Temporary Holding Version
+# @skillbuilder/miniapp-simulator
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+技术栈无关的小应用 PC 模拟器 SDK，支持 iframe 预览和 Electron webview 审核场景。
+模拟器默认**无贴图外壳**（`phoneFrame: false`），保留创作发布标准深色圆角设备边框；需要 iPhone / Nexus 贴图壳时显式传 `phoneFrame`。默认开启 `stageFit` 自适应撑满挂载区域；手动拖拽缩放需传 `stageFit: { resizeHandle: true }`。
+
+```bash
+pnpm --filter @skillbuilder/miniapp-simulator run playground
+```
+
+Smoke 联调：`testsuits/miniapp-simulator-sdk-smoke` 以 ESM `import` 引用本包 `lib/`；改源码后 `pnpm --filter @skillbuilder/miniapp-simulator run build:npm`，再 `pnpm --filter miniapp-simulator-sdk-smoke dev` 即可。
+
+**设备能力封印**由本包自维护：封印 IIFE 以本地文件形式存放在
+`src/injection/modules/device-capabilities-seal.iife.min.js`，注入时以 `?raw` 引入（更新封印时替换该文件即可）。
+
+兼容性基线：iOS WKWebView (iOS 13+) / Android WebView (Chrome 49+) / 现代 PC 浏览器。
+
+**按业务灵活放开能力**（白名单语义）：
+
+```ts
+import { createMiniAppSimulator, MiniAppCapability } from "@skillbuilder/miniapp-simulator";
+
+createMiniAppSimulator({
+  deviceCapabilities: {
+    sealAllow: [
+      MiniAppCapability.Camera,
+      MiniAppCapability.Microphone,
+      MiniAppCapability.PhotoLibrary,
+      // 后续要放开定位时只追加这一行：
+      // MiniAppCapability.Geolocation,
+    ],
+  },
+});
+```
+
+`sealAllow` 不传 → 等价于 `[Camera, Microphone, PhotoLibrary]`；`sealAllow: []` → 严格模式全封禁。Android / iOS 注入路径见 `docs/local-dev.md`。
+
+**支持的能力已枚举化对外**，可直接用于配置面板 / 校验（由本包自维护，`src/seal-config.ts`）：
+
+```ts
+import {
+  MINI_APP_CAPABILITIES, // 全量能力元数据（value / controlledBy / description / permissionNames）
+  SEAL_CONTROLLED_CAPABILITIES, // 受 sealAllow 白名单实际控制的能力
+  isMiniAppCapability,
+  sanitizeCapabilityList,
+} 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
+import { createMiniAppSimulator } from "@skillbuilder/miniapp-simulator";
+
+// 1) 创建实例（mount 为 CSS 选择器或 HTMLElement；create 只管配置，不传入口）
+const simulator = createMiniAppSimulator({
+  mount: "#preview",
+  viewport: { width: 390, height: 844 },
+});
+
+// 2) 加载入口（三选一）：远程 URL / .zip 包 / 目录文件表
+await simulator.loadApp("https://cdn.../index.html", { query: { versionId: "v2" } });
+```
+
+## DOM / Canvas 场景对象 Visual Inspector
+
+Visual Inspector 统一输出 DOM 与 PixiJS、Three.js、自定义 Canvas 场景对象。DOM 继续兼容
+`elementSelected`；新消费方应订阅 `visualSelected` / `visualSelectionChange`，并通过
+`getSceneTree()` 与 `selectByRef()` 实现 Viewport、Hierarchy、Inspector 双向联动：
+
+```ts
+simulator.on("visualSelected", (selection) => {
+  if (selection.kind === "scene") {
+    console.log(selection.engine, selection.nodePath, selection.properties, selection.source);
+  }
+});
+
+const tree = await simulator.inspector.getSceneTree();
+const firstSceneNode = tree.providers[0]?.roots[0]?.children[0];
+if (firstSceneNode) await simulator.inspector.selectByRef(firstSceneNode.ref);
+```
+
+场景 Provider 由小应用模板主动注册；Provider 缺失或失败时仍会降级为普通 canvas DOM
+选择。普通预览默认不代理页面调度器；明确的 2D / 3D 游戏由上游传入
+`visualInspector: { pauseRuntime: true }`。此时进入选取模式会冻结 RAF、timer、CSS 动画与媒体，
+并调用 Provider 可选的 `pause()`；退出时按原状态恢复，因此运动对象可以稳定命中。
+完整职责、协议和分期见
+[`design/mini-app/mini-app-visual-inspector-design.md`](./design/mini-app/mini-app-visual-inspector-design.md)。
+
+独立验证 2D / 3D 场景圈选：
+
+```bash
+pnpm --filter @skillbuilder/miniapp-simulator demo:inspector
+```
+
+打开 `http://127.0.0.1:5181`，可手动点击运动元素，也可运行层级读取和反向选择 Case。
+
+独立验证 AI 对话 Bridge（非流式完整消息与流式增量渲染）：
+
+```bash
+pnpm --filter @skillbuilder/miniapp-simulator demo:ai
+```
+
+打开 `http://127.0.0.1:5182`，两个 Case 会自动运行并展示业务层最终渲染结果。
+
+## 加载 .zip 应用包
+
+实例方法 `loadZip` 自动完成「解压 → 解析 `manifest.json` → 内联相对资源 → 建 blob URL 加载」，
+入参支持 `Blob | File | ArrayBuffer | Uint8Array`：
+
+```ts
+import { createMiniAppSimulator } from "@skillbuilder/miniapp-simulator";
+import JSZip from "jszip"; // 或在全局挂载 window.JSZip（CDN / UMD）
+
+const simulator = createMiniAppSimulator({ mount: "#preview" });
+await simulator.load();
+
+// 拖拽 / 选择得到的 .zip File 直接喂入；返回包元信息（文件清单 + manifest 解析结果）
+const result = await simulator.loadZip(zipFile, { jszip: JSZip });
+console.log(result.files, result.manifest.window, result.manifest.warnings);
+```
+
+> 本包**技术栈无关**、不强依赖 JSZip：通过 `loadZip(source, { jszip })` 传入 JSZip 兼容对象，
+> 或在全局挂载 `window.JSZip`（不传时自动回退）；二者皆缺失会抛出 `ZIP_LOAD_FAILED`。
+
+更多说明见：
+
+- [`docs/remote-architecture.md`](./docs/remote-architecture.md)：远程模式架构、版本发布、动态更新与隔离边界
+- [`docs/remote-usage.md`](./docs/remote-usage.md)：远程模式接入、实例 API、Host API 与多实例用法
+- [`docs/server-playground-https-debugging.md`](./docs/server-playground-https-debugging.md)：Server Playground 本地 HTTPS、证书信任与 Creator AI 独立泳道联调
+- [`docs/external-cli-workbench.md`](./docs/external-cli-workbench.md)：外部 CLI 的 `xxx dev` 参数与本地托管契约
+- `docs/sdk-usage.md`
+- `docs/local-dev.md`
+- `docs/electron-review.md`
+
+## 外部 AI 调试工作台
+
+`@skillbuilder/miniapp-simulator/workbench` 在现有 Simulator 外增加一层轻量工作台壳，面向
+Codex、CodeBuddy 和本地 CLI 展示运行状态、诊断事件、重新加载与截图入口。它不会改变 Simulator
+的加载、渲染或调试协议：调用方仍可通过 `workbench.simulator` 使用完整 SDK 能力。
+
+```ts
+import { createMiniAppWorkbench } from "@skillbuilder/miniapp-simulator/workbench";
+import { BusinessLine } from "@skillbuilder/miniapp-simulator/remote";
+
+const workbench = createMiniAppWorkbench({
+  mount: "#app",
+  projectName: "demo-minitool",
+  viewport: { width: 393, height: 852 },
+  remote: {
+    serviceUrl: "https://miniapp-sandbox.xiaohongshu.com/simulator/",
+    appId: "demo-minitool",
+    businessLine: BusinessLine.skillDesignable,
+  },
+});
+
+// 本地 Agent 调试使用目录文件表，不需要 ZIP。
+await workbench.loadFiles({
+  "index.html": htmlText,
+  "main.js": scriptText,
+  "logo.png": pngBytes,
+}, { entry: "index.html" });
+```
+
+工作台使用宿主侧薄 SDK 连接 Simulator Server：薄 SDK 通过 `runtime-manifest` 动态选择远端 Runtime，
+Runtime 再注册同源、版本化的 Service Worker。CLI 不复制或托管 Runtime / SW，也不直接执行小工具代码。
+
+包内同时提供 `@skillbuilder/miniapp-simulator/workbench.html` 静态入口，供 CLI 等本地服务直接托管；
+页面结构、样式和 Simulator 编排均由本包维护。
+
+CLI 可直接调用独立的 Node 服务入口，传入调试根目录即可启动完整工作台：
+
+```ts
+import { startWorkbenchServer } from "@skillbuilder/miniapp-simulator/workbench/server";
+
+const server = await startWorkbenchServer({ rootDir: "./dist" });
+console.log(server.url);
+// CLI 退出时调用 await server.close()。
+```
+
+Node 入口统一负责 HTML 入口识别、文件清单与原始资源托管，工作台通过 `loadFiles()` 加载目录文件，
+继续经 Remote SDK 连接远端 Runtime / SW。根目录及子目录中的 HTML、JS、CSS 变化会自动重载小工具，
+无需重启服务或手动刷新；“重新运行”仍可手动触发。连续写入会合并，重载期间的新变更会串行处理。
+
+工作台固定使用 SDK 的 `rednote` 壳层，保留状态栏、返回等原生控件。支持全屏小工具、半屏小工具、笔记页、个人页四种场景，设备尺寸独立切换。
+可通过工作台控件或 `workbench.setScene("half")` 切换；文件更新后保持当前选定场景。
+
+仓库内可用 Mock 脚本模拟另一套 CLI 的调用：
+
+```shell
+pnpm --filter @skillbuilder/miniapp-simulator mock:cli-dev -- \
+  --dir /absolute/path/to/minitool/dist
+```
+
+外部 CLI 只需直接安装本包：`--dir` 对应 Node 入口的 `rootDir`，`--no-open` 由 CLI 自己控制打开浏览器，`-h` / `--help` 输出帮助。
+设备、场景、入口识别和文件监听由工作台处理；完整参数与职责见 [`external-cli-workbench.md`](./docs/external-cli-workbench.md)。
+
+`prepack` 自动执行本地构建；不执行上传或发布。Runtime / SW 仍从远程服务动态加载，外网可达性需单独验收。
+当前验证范围及外发门禁见 [`npm-integration-verification.md`](./docs/npm-integration-verification.md)。
+
+### 仅发布模拟器 npm（仓库根目录执行）
+
+```shell
+pnpm release:simulator snapshot --registry public --dry-run  # 构建、打包、检查，不发布
+pnpm release:simulator snapshot --registry public            # beta 快照，仅发布本包
+pnpm release:simulator stable --registry public              # 当前版本 → latest
+pnpm release:simulator snapshot --registry internal          # 同样支持内部源
+```
+
+默认源为 `public`，也支持 `--registry <url>`。真实发布需最终确认，CI 显式传 `--yes`。
+正式版沿用本包版本，且只允许在 `release/release_*` 分支发布；快照版本仅写入临时目录，不修改仓库版本、lockfile 或 changeset。
+构建依赖 `endpoints` 不发布；脚本不执行全仓构建或 CDN 上传，外部运行依赖出现内部包时会阻断发布。
+真实发布成功后向现有两个机器人发送版本与安装命令；dry-run 不发送通知，通知失败只告警、不重试发布。
+发布归档会移除开发依赖、构建/发布脚本与源覆盖配置；dry-run 产物及清单保留在打印的临时目录中。
+该脚本不替代包内文档/资源的外发审查、npm scope 发布权限或远程 Runtime / SW 外网可达性验收。

package/assets/workbench/index.html

@@ -0,0 +1,77 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>小红书小工具 · 本地调试工作台</title>
+    <style>
+      html,
+      body,
+      #workbench {
+        width: 100%;
+        height: 100%;
+        margin: 0;
+        overflow: hidden;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="workbench"></div>
+    <script type="module">
+      async function fetchResource(url, init) {
+        const response = await fetch(url, { cache: "no-store", ...init });
+        if (!response.ok) throw new Error(`${url} 加载失败：HTTP ${response.status}`);
+        return response;
+      }
+
+      async function start() {
+        const config = await fetchResource("/__miniapp_workbench__/config.json").then((response) =>
+          response.json(),
+        );
+        if (config.artifact.type !== "files") {
+          throw new Error(`不支持的产物类型：${config.artifact.type}`);
+        }
+        const loadLocalFiles = async () => {
+          const { entry, files } = await fetchResource(config.artifact.url).then((response) =>
+            response.json(),
+          );
+          const entries = await Promise.all(
+            files.map(async (file) => {
+              const url =
+                config.artifact.baseUrl + file.split("/").map(encodeURIComponent).join("/");
+              const content = await fetchResource(url).then((response) => response.arrayBuffer());
+              return [file, content];
+            }),
+          );
+          await workbench.loadFiles(Object.fromEntries(entries), { entry });
+        };
+        const { createMiniAppWorkbench } = await import(config.sdkUrl);
+        const workbench = createMiniAppWorkbench({
+          mount: "#workbench",
+          projectName: config.projectName,
+          viewport: config.viewport,
+          remote: config.remote,
+          onReload: loadLocalFiles,
+        });
+        window.__MINIAPP_WORKBENCH__ = workbench;
+
+        const changes = new EventSource(config.artifact.eventsUrl);
+        changes.addEventListener("reload", () => void workbench.reload());
+        changes.addEventListener("watch-error", (event) =>
+          console.error("[miniapp-workbench]", event.data),
+        );
+        window.addEventListener("beforeunload", () => changes.close(), { once: true });
+      }
+
+      start().catch((error) => {
+        console.error("[miniapp-workbench]", error);
+        if (window.__MINIAPP_WORKBENCH__) return;
+        const mount = document.querySelector("#workbench");
+        if (!mount) return;
+        mount.style.cssText =
+          "display:grid;place-items:center;padding:24px;box-sizing:border-box;background:#f5f6f8;color:#34353a;font:13px/1.6 -apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif";
+        mount.textContent = `工作台启动失败：${error instanceof Error ? error.message : String(error)}`;
+      });
+    </script>
+  </body>
+</html>