@adep/web-container 0.1.0 → 0.2.0

package/dist/sim/kv.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 浏览器模拟运行时的持久化后端（FN-023）：异步键值端口，IndexedDB / 内存双实现。
+ *
+ * 设计与 `persistence.ts`（终端 fs 快照）同一取向：浏览器 IndexedDB、Node 内存，零运行时依赖。
+ * 键空间约定（组合层 `runtime.ts` 分配，本文件不管语义）：
+ * - `db:<projectId>` → SimSqlEngine 的整库表快照（JSON 可结构化克隆值）；
+ * - `storage:<projectId>` → 项目存储桶 `{ [path]: StoredObject }`。
+ *
+ * 每次写都是「整值 put」：模拟运行时的写频度与数据量都是开发态规模，不值得做去抖/增量，
+ * 简单形状才没有「漏删 / 孤儿」这类错（同 `persistence.ts` 头注释的取舍）。
+ */
+/** 浏览器模拟运行时的持久化端口（值必须是可结构化克隆的；内存实现按引用存）。 */
+export interface SimKvBackend {
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+/** 内存后端（Node 单测 / SSR / 隐私模式降级）。每次调用产出独立实例，测试之间互不串味。 */
+export declare function createMemorySimKv(): SimKvBackend;
+/** IndexedDB 后端：单库单仓（`key` 为主键），一 KV 一记录。 */
+export declare function createIdbSimKv(dbName?: string): SimKvBackend;
+/** 缺省后端：浏览器 IndexedDB，其余（Node 单测 / SSR）内存。 */
+export declare function pickDefaultSimKv(): SimKvBackend;

package/dist/sim/realtime.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 浏览器模拟 `cloud.realtime`（FN-023）：离线内存广播总线（@adep/runtime/sim/realtime 的
+ * `SimRealtime`，与 CLI sim 同一份语义）+ **回网切真实 WS** 的传输切换。
+ *
+ * 语义层（广播 / 拉取式缓冲 / 订阅上限 / 错误码）与 CLI sim / 线上提供方共用一份真相源：
+ * - 错误码取 `capability-keys` 的 `REALTIME_CAPABILITY_CODES`（跨 realm 常量的家）；
+ * - 期望表（publish 回执 / 未知订阅 / except 不可用 / 未知方法）在本仓测试里对浏览器 handler
+ *   逐条复跑（同 CLI 侧 REALTIME_SIM_CASES 一族）。
+ *
+ * 回网切换（Gherkin 场景 3）：`goOnline()` 为每个活跃订阅开真实 WS（换票 →
+ * `Sec-WebSocket-Protocol` 携带票据，与服务端握手契约对齐）；WS 下行消息**只**经
+ * 「直接推入该订阅缓冲」这一条路径进入，本地总线的监听保持挂载——两条摄入源的
+ * 消息集合不相交（本地 publish 只进总线、服务端消息只进 WS 推送），且每条消息
+ * 恰好走一条路径一次，因此不会出现双份。`goOffline()` 关 WS 回到纯本地广播。
+ *
+ * 边界：在线态下浏览器草稿的 publish 仍只进本地总线（浏览器侧没有「以平台身份发布」的
+ * HTTP 面；函数发布语义属于服务端执行面）。WS 断开不自动重连——重试发生在下一次
+ * `goOnline()`（重连风暴防护与 networkMonitor 的低频探测同口径）。
+ */
+import { SimRealtime } from '@adep/runtime/sim/realtime';
+import type { CapabilityBundle } from '@adep/types';
+/** 换票回执（`POST /api/v1/realtime/ticket` 的响应形状）。 */
+export interface TicketResult {
+    ticket: string;
+}
+/** 最小 WebSocket 面（鸭子类型：Node 测试注入假 WS 走同一协议）。 */
+export interface MinimalWebSocket {
+    close(code?: number): void;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((event: {
+        code?: number;
+    }) => void) | null;
+}
+export interface BrowserRealtimeOptions {
+    /** 项目 id（换票入参）。 */
+    projectId: string;
+    /** WS 基址（缺省由 `location.origin` 推导为 ws(s)://）；Node 测试注入。 */
+    wsBaseUrl?: string;
+    /** 换票提供者（缺省 POST /api/v1/realtime/ticket，credentials include）。 */
+    ticketProvider?: () => Promise<TicketResult>;
+    /** WebSocket 工厂（Node 测试注入假 WS）。 */
+    wsFactory?: (url: string, protocols: string[]) => MinimalWebSocket;
+    /** 一次会话内的订阅上限（与 CLI sim 同参 64）。 */
+    maxSubscriptions?: number;
+    /** 单订阅缓冲上限（与 CLI sim 同参 64，超出丢最旧）。 */
+    maxBufferedMessages?: number;
+}
+/**
+ * 构造浏览器侧 `cloud.realtime` 能力 bundle + 回网切换器。
+ * 传输切换器暴露给组合层（IDE 侧随 networkMonitor 状态调用 `goOnline` / `goOffline`）。
+ */
+export declare function createBrowserRealtime(options: BrowserRealtimeOptions): {
+    bundle: CapabilityBundle;
+    realtime: SimRealtime;
+    goOnline(): Promise<void>;
+    goOffline(): void;
+    /** 当前处于 WS 摄入态的订阅数（诊断用）。 */
+    wsConnectedCount(): number;
+};

package/dist/sim/runner.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 离线函数运行器（FN-023 范围 3）：断网在浏览器里执行「用 cloud.* 的草稿」，语义与线上执行面同形。
+ *
+ * 执行链与 FN-022 测试运行器同族：`stripTypes`（TS 类型擦除）→ `transformModule`
+ * （@adep/runtime 的 ESM→CJS 精简变换，`export default` → `module.default`，与线上沙箱
+ * 同一份）→ `evaluateModuleSource`（import 变换 + require 注入 + `with (sandbox)` 隔离求值）。
+ * `ctx` 按线上同形构造（`sim/ctx.ts` 的 cloud 装配 + method/path/query/headers/body/files/user）。
+ *
+ * 日志：沙箱 console 落**本地环形缓冲**（超上限丢最旧），条目带 `local: true`——
+ * 调试面板离线态渲染时标注「本地」（范围 4）。
+ *
+ * 边界（fail loud，不静默降级）：不支持的 TS 构造 → `UnsupportedTsSyntaxError` 如实上报；
+ * 草稿没有 default 导出 → `FN_NO_HANDLER`；执行超时 → `FN_EXEC_TIMEOUT`（浏览器主线程
+ * 无法强杀一个卡死的异步句柄，超时只是放弃等待并如实回报）。
+ */
+import type { CapabilityBundle } from '@adep/types';
+/** 一条本地执行日志（调试面板离线态的渲染源）。 */
+export interface LocalLogEntry {
+    id: number;
+    level: 'log' | 'warn' | 'error';
+    message: string;
+    /** ISO 8601（本地时钟；离线态没有服务端时间戳）。 */
+    ts: string;
+}
+/** 离线执行的请求构造（与调试面板在线 payload 同形状）。 */
+export interface OfflineRunRequest {
+    method: string;
+    path: string;
+    query?: Record<string, string | readonly string[]>;
+    headers?: Record<string, string>;
+    body?: unknown;
+}
+/** 离线执行结果（调试面板 RunResult 的超集：日志带 local 标记）。 */
+export interface OfflineRunResult {
+    status: number;
+    body: unknown;
+    durationMs: number;
+    logs: LocalLogEntry[];
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export interface OfflineRunInput {
+    /** 草稿整组文件（相对函数根，含入口 index.ts）。 */
+    files: Record<string, string>;
+    /** 入口文件（相对函数根，如 `index.ts`）。 */
+    entry: string;
+    request: OfflineRunRequest;
+    /** 能力 bundle（`createBrowserSimRuntime` 合并后的那份）。 */
+    bundle: CapabilityBundle;
+}
+export interface OfflineRunnerOptions {
+    /** 单次执行超时（缺省 10s）。 */
+    timeoutMs?: number;
+    /** 日志环形缓冲上限（缺省 200，超出丢最旧）。 */
+    maxLogEntries?: number;
+    now?: () => number;
+}
+/**
+ * 创建离线函数运行器。每次 `run` 用全新 VFS / 沙箱（无跨次状态泄漏；
+ * 跨次共享的状态只存在于能力 bundle 背后的持久层——IndexedDB，这正是 Gherkin 场景 1 要的）。
+ */
+export declare function createOfflineFunctionRunner(options?: OfflineRunnerOptions): {
+    run(input: OfflineRunInput): Promise<OfflineRunResult>;
+};

package/dist/sim/runtime.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 浏览器模拟运行时组合根（FN-023）：db / storage / realtime 三能力合并成一份 bundle，
+ * 加上离线函数运行器——与 CLI `createSimRuntime` 同构（能力 + rpcHandlers 合并 + 生命周期），
+ * 浏览器侧多暴露「回网切换」与「离线执行」两个入口给 IDE 消费。
+ *
+ * 一致性红线同 CLI：能力装配**只读复用线上工厂**（createDbCapability / createStorageCapability /
+ * SimRealtime 语义层），本文件只做合并与生命周期；契约由 `shared/sim-contract.ts` 钉死。
+ */
+import type { CapabilityBundle } from '@adep/types';
+import { createBrowserSimDb } from './db';
+import { createBrowserRealtime } from './realtime';
+import type { BrowserRealtimeOptions } from './realtime';
+import { createBrowserSimStorage } from './storage';
+import { createOfflineFunctionRunner } from './runner';
+import type { OfflineRunnerOptions } from './runner';
+import type { SimKvBackend } from './kv';
+export interface BrowserSimRuntimeOptions {
+    /** 项目 id（db / storage 分区 + realtime 换票入参）。 */
+    projectId: string;
+    /** 持久化后端（缺省浏览器 IndexedDB / 其余内存）；测试注入内存后端。 */
+    kv?: SimKvBackend;
+    /** 签名 URL 基址（浏览器缺省 location.origin）。 */
+    baseUrl?: string;
+    /** 签名密钥（模拟密钥）。 */
+    secret?: string;
+    /** 项目存储配额字节（缺省与线上同参 1GiB）。 */
+    quotaBytes?: number;
+    /** realtime 传输切换的接线（换票 / WS 工厂；Node 测试注入）。 */
+    realtime?: Omit<BrowserRealtimeOptions, 'projectId'>;
+    /** 离线运行器参数（超时 / 日志上限）。 */
+    runner?: OfflineRunnerOptions;
+}
+export interface BrowserSimRuntime {
+    /** 合并后的能力 bundle（capabilities + rpcHandlers），喂给离线运行器。 */
+    bundle: CapabilityBundle;
+    /** cloud.db 背后的引擎（schema 水合 / 测试断言面）。 */
+    db: ReturnType<typeof createBrowserSimDb>;
+    /** cloud.storage 背后的驱动（测试断言面）。 */
+    storage: ReturnType<typeof createBrowserSimStorage>;
+    /** cloud.realtime 背后的广播与传输切换器。 */
+    realtime: ReturnType<typeof createBrowserRealtime>;
+    /** 离线函数运行器（断网在浏览器执行草稿）。 */
+    runner: ReturnType<typeof createOfflineFunctionRunner>;
+    /** 释放资源（当前无长持句柄；与 CLI createSimRuntime.dispose 对称保留）。 */
+    dispose(): Promise<void>;
+}
+/** 装配浏览器模拟运行时（async：db 引擎要先把 IndexedDB 里的快照灌回来）。 */
+export declare function createBrowserSimRuntime(options: BrowserSimRuntimeOptions): Promise<BrowserSimRuntime>;

package/dist/sim/storage.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 浏览器模拟 `cloud.storage`（FN-023）：IndexedDB/内存 `StorageDriver` → 线上
+ * `createStorageCapability` 装配（含同款签名 URL——HMAC 本体已纯化，全 realm 同一份实现）。
+ *
+ * 一致性红线：只替换「持久化落点」（磁盘目录 → KV 记录），路径校验 / 错误码 / 配额语义 /
+ * 列表排序 / 签名 URL 形状全部对齐 `driver/local.ts` 与 `storage/cloud.ts`——
+ * 契约表（STORAGE_PROVIDER_CASES）在本仓测试里钉死。
+ *
+ * 边界（与 CLI sim 同族，启动/文档不再各写一份）：签名 URL 的密钥是本地模拟密钥，
+ * 离线态该 URL 不可访问；回网后由平台校验的是**平台**密钥签发的 URL，本模拟 URL 不跨系统有效。
+ */
+import type { CapabilityBundle } from '@adep/types';
+import type { StorageDriver } from '@adep/runtime/storage/driver';
+import type { SimKvBackend } from './kv';
+export interface CreateBrowserSimStorageOptions {
+    /** 项目 id（桶绑定 + 持久化分区键）。 */
+    projectId: string;
+    /** 持久化后端；缺省按环境自动选。 */
+    kv?: SimKvBackend;
+    /** 签名 URL 基址；浏览器缺省 `location.origin`，Node 测试注入。 */
+    baseUrl?: string;
+    /** 签名密钥（模拟密钥，一次运行期一致即可）。 */
+    secret?: string;
+    /** 项目配额字节；缺省 1GiB（与线上同参，测试可注入小值）。 */
+    quotaBytes?: number;
+}
+/** storage 持久化键。 */
+export declare function simStorageKey(projectId: string): string;
+/**
+ * 浏览器侧 StorageDriver：语义逐条对齐 `driver/local.ts`（路径校验 / 404 / 配额净增计 /
+ * 前缀列举字典序），只把「文件系统 + 旁载 meta」换成「单 KV 记录桶」。
+ */
+export declare function createBrowserStorageDriver(options: {
+    projectId: string;
+    kv: SimKvBackend;
+    quotaBytes?: number;
+}): StorageDriver;
+/** 构造浏览器侧 `cloud.storage` 能力 bundle（线上 `createStorageCapability` 原样装配）。 */
+export declare function createBrowserSimStorage(options: CreateBrowserSimStorageOptions): {
+    bundle: CapabilityBundle;
+    driver: StorageDriver;
+};

package/dist/strip-types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * TypeScript 类型擦除器（FN-022）：把 `*.test.ts` 的源码降级成浏览器可 `new Function` 求值的 JS。
+ *
+ * **为什么自己写**：浏览器沙箱求值（`worker-runtime.ts` 的 `evaluateSource`）走 `new Function`，
+ * 而浏览器既没有 `Bun.Transpiler`，任务单也要求「自实现、不引第三方运行依赖」。
+ * `@adep/runtime` 的 `transpile()` 是宿主能力探测（Bun / `node:module`），浏览器里两条都没有；
+ * 更要紧的是同一份测试文件在 Node 单测与浏览器里必须**同语义**，能力探测会带来两套结果——
+ * 所以这里做确定性的单遍扫描擦除，两个 realm 同一实现、同一输出。
+ *
+ * **三条安全纪律**（由 `strip-types.test.ts` 逐条守住）：
+ * 1. **对纯 JS 恒等**：只有规则明确命中的区间才擦成等长空白（换行照抄，行号不漂），其余字节
+ *    原样保留；字符串 / 模板串 / 正则字面量 / 注释里的 `:` `//` `<` 永不被当语法。
+ * 2. **判不准就不擦**：漏擦的后果是 `new Function` 抛 `SyntaxError`，由运行器如实上报该文件
+ *    「加载失败」——响亮地失败，绝不静默改写语义（例如把三元表达式的中间段当类型标注吃掉）。
+ * 3. **需要改写而非擦除的构造直接抛错**（`enum` / `namespace`）：与 runtime 沙箱
+ *    「超出子集承诺就报错」同口径，不假装能跑。
+ *
+ * 支持子集：`interface`、`type` 别名、`import type` / `export type`、参数 / 返回值 / 变量 /
+ * 类成员的类型标注、解构参数标注 `{ a }: T`、可选参数 `?:`、非空断言 `!`、`as` / `satisfies`、
+ * 声明位泛型、`implements` 子句、类成员 TS 修饰符（`private` / `readonly` …；`static` 是真 JS，保留）。
+ */
+/** 不受支持的 TypeScript 构造（需要真正改写代码，不是擦除）。 */
+export declare class UnsupportedTsSyntaxError extends Error {
+    readonly construct: string;
+    readonly line: number;
+    constructor(construct: string, line: number);
+}
+/**
+ * 擦除 TypeScript 类型标注，返回可被 `new Function` 求值的 JS。
+ * 对不含 TS 语法的输入**逐字节恒等**；不受支持的构造抛 `UnsupportedTsSyntaxError`。
+ */
+export declare function stripTypes(source: string): string;

package/dist/tar.d.ts

@@ -0,0 +1,30 @@
+/**
+ * tar.gz 解包（FN-021 浏览器依赖安装闭环）：gzip 解压 + ustar 归档读取，零依赖。
+ *
+ * npm registry 的 `.tgz` = gzip(tar(ustar, "package/..."))。`DecompressionStream('gzip')`
+ * 在 Chromium 与 Node ≥18 双端可用（同一代码路径可在 vitest 直接跑），tar 读取按 ustar
+ * 头（512 字节块：name/size/typeflag/prefix）手写——手写先例见 SRC-002：
+ * `server/domains/src` 下的 `zip.ts` 手写 STORE-only ZIP 写器，因为新增依赖要过审计门，
+ * 手写百来行反而便宜。
+ *
+ * 安全：条目路径拒绝绝对路径与 `..` 穿越（zip-slip 同型攻击）；不支持的 typeflag
+ * （硬/软链接、字符设备等）直接报错而非静默跳过，避免装出缺件半成品。
+ */
+/** 一个 tar 文件条目（内容为原始字节，路径已去掉 `package/` 前缀之前的形态）。 */
+export interface TarEntry {
+    path: string;
+    contents: Uint8Array;
+}
+/** gzip 解压（`DecompressionStream`：Chromium / Node ≥18 双端内建）。非 gzip 输入报可读错误。 */
+export declare function gunzip(bytes: Uint8Array): Promise<Uint8Array>;
+/**
+ * 读 ustar 归档为条目列表（仅 regular file；目录隐式由文件路径承载，跳过）。
+ * 支持 prefix 字段拼接与 GNU `L` 长文件名；pax 扩展头（`x`/`g`）按 npm 打包形态跳过；
+ * 链接/设备等类型 flag 抛错（本 SDK 只服务 registry tarball 的文件树）。
+ */
+export declare function unpackTar(bytes: Uint8Array): TarEntry[];
+/**
+ * 解 npm `.tgz` 字节为条目列表；剥掉 registry 归档统一的 `package/` 顶层前缀。
+ * 缺 `package.json` 或含两个顶层目录形态一律报错（fail loud，不产出半成品结构）。
+ */
+export declare function unpackNpmTarball(bytes: Uint8Array): Promise<TarEntry[]>;

package/dist/test-framework.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 浏览器内的轻量测试框架（FN-022 范围 1）：`describe` / `it` / `expect` 最小集，自实现零依赖。
+ *
+ * 为什么不用 vitest：`@adep/web-container` 要在浏览器里跑（`sideEffects: false`、依赖只有
+ * `@adep/types`），而 vitest 需要 Node 进程与转换管线。任务单口径是「沙箱注入
+ * `describe/it/expect` 最小集，自实现、不引第三方运行依赖」。
+ *
+ * 分工：
+ * - 本文件只管**用例注册与断言语义**（`createTestScope` 产出一组可注入沙箱的全局 + 一个执行器），
+ *   不碰文件系统、不碰求值路径；
+ * - 谁把源码喂进来（`test-runner.ts` 经 `worker-runtime` 的模块求值路径）、结果怎么打印，都在那边。
+ *
+ * 明确不支持（超出「最小集」即报错或忽略，不假装兼容 vitest）：快照、模块 mock、`it.only` /
+ * `it.skip`、`concurrent`、异步 `describe` 体（用例注册以文件求值结束为准）、覆盖率。
+ */
+/** 单条用例的执行结果。 */
+export interface TestCaseResult {
+    /** 展示名（`describe` 链以 ` › ` 连接）。 */
+    name: string;
+    status: 'passed' | 'failed';
+    durationMs: number;
+    /** 失败原因（断言消息或抛错消息）。 */
+    message?: string;
+    /** 断言失败时的「期望值」文本（终端报告按行打印，Gherkin 的失败定位判据）。 */
+    expected?: string;
+    /** 断言失败时的「实际值」文本。 */
+    received?: string;
+}
+/** 单个测试文件的聚合结果。 */
+export interface TestFileResult {
+    /** 展示路径（相对 VFS 根，不带前导 `/`）。 */
+    file: string;
+    cases: TestCaseResult[];
+    /** 文件求值本身失败（语法错误 / import 失败 / 注册期抛错）时非空，此时 `cases` 为空。 */
+    loadError?: string;
+    /** 用例里 `console.log` 的输出（与 `node <file>` 同一收集路径，报告按行缩进展示）。 */
+    output?: string;
+}
+/** 一次 `test` 命令的完整报告（同时供终端打印与 IDE 面板消费）。 */
+export interface TestReport {
+    files: TestFileResult[];
+    passed: number;
+    failed: number;
+    /** 求值失败的文件数（与「用例失败」分列：前者是跑不起来，后者是断言不成立）。 */
+    errors: number;
+    total: number;
+    durationMs: number;
+    /** `failed === 0 && errors === 0`（退出码语义的唯一判据）。 */
+    ok: boolean;
+}
+/** 用例体：可同步可异步，抛错即失败。 */
+export type TestFn = () => void | Promise<void>;
+type HookFn = () => void | Promise<void>;
+export interface TestRegistration {
+    /** `it()` 自己的用例名（`chain` 只含所属 `describe` 链）。 */
+    name: string;
+    chain: readonly string[];
+    fn: TestFn;
+    /** 注册时所在 `describe` 节点的钩子链（含祖先）。 */
+    hooks: {
+        beforeEach: readonly HookFn[];
+        afterEach: readonly HookFn[];
+    };
+}
+/** 断言失败（与用例内抛错区分开：前者带 expected / received，报告里要分行打印）。 */
+export declare class TestAssertionError extends Error {
+    readonly expected?: string | undefined;
+    readonly received?: string | undefined;
+    constructor(message: string, expected?: string | undefined, received?: string | undefined);
+}
+/** 一个测试文件对应一个作用域（注册表 + 注入沙箱的全局对象）。 */
+export interface TestScope {
+    /** 注入沙箱的全局：`describe` / `it` / `test` / `expect` / `beforeEach` / `afterEach`。 */
+    globals: Record<string, unknown>;
+    /** 求值结束后按注册顺序取出用例。 */
+    drain(): TestRegistration[];
+}
+/** 创建一次文件求值用的测试作用域（超时由 `runCollectedTests` 在执行阶段把关）。 */
+export declare function createTestScope(): TestScope;
+/** 用例全名（`describe` 链 + 用例名）。 */
+export declare function fullName(test: TestRegistration): string;
+/**
+ * 执行一个文件里注册的全部用例：逐条 `beforeEach → 用例 → afterEach`，任何一条抛错只记在该条上
+ * （不中断整个文件——一次改坏一个断言不该让后面的用例失去可见性）。
+ */
+export declare function runCollectedTests(tests: readonly TestRegistration[], options?: {
+    timeoutMs?: number;
+    now?: () => number;
+}): Promise<TestCaseResult[]>;
+/** 一条断言链（`.not` 取反，其余匹配器失败抛 `TestAssertionError`）。 */
+export interface Expectation {
+    toBe(expected: unknown): void;
+    toEqual(expected: unknown): void;
+    toBeTruthy(): void;
+    toBeFalsy(): void;
+    toBeNull(): void;
+    toBeUndefined(): void;
+    toBeDefined(): void;
+    toContain(expected: unknown): void;
+    toHaveLength(length: number): void;
+    toThrow(expected?: string | RegExp): void;
+    readonly not: Expectation;
+}
+/** 沙箱注入的 `expect`：`expect(value).toBe(expected)`。 */
+export declare function expect(actual: unknown): Expectation;
+/** 深相等：数组 / 普通对象 / Date / RegExp 递归比对，其余按引用（`Object.is`）。 */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/** 值的展示形式（报告与断言消息共用；不可序列化的一律降级，绝不让打印本身抛错）。 */
+export declare function formatValue(value: unknown): string;
+export {};

package/dist/test-runner.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 浏览器内测试运行器（FN-022）：`test <file|dir>` 的收集、执行与报告。
+ *
+ * 与 `node <file>` **共用求值路径**（任务单范围 4）：源码经 `strip-types.ts` 擦掉类型标注后，
+ * 交给 `worker-runtime.evaluateModuleSource`——同一条「import 变换 + require 注入 + `evaluateSource`」
+ * 链，所以测试里的 `console.log` 收集方式与 `with (sandbox)` 隔离语义跟直接跑脚本完全一致。
+ * 这里不另起执行器，也不走 Worker：测试全局是同步注入的，Worker 的异步消息协议做不到。
+ *
+ * 约定（README 与模板注释同源）：**文件名以 `.test.ts` / `.spec.ts` 结尾即被收集**，目录递归，
+ * `node_modules/` 与隐藏目录不进入。`describe` / `it` / `expect` 是沙箱注入的全局，
+ * 测试文件不需要 import 任何测试框架。
+ *
+ * 退出码语义（与 vitest 对齐）：全部通过 0；有失败 / 有加载错误 / 没找到用例 → 非 0。
+ */
+import type { VirtualFileSystem } from './vfs';
+import { type TestReport } from './test-framework';
+/** 收集约定：`*.test.ts` / `*.spec.ts`（`.js` / `.mjs` / `.cjs` 同样收，`.d.ts` 不算）。 */
+export declare const TEST_FILE_PATTERN: RegExp;
+/** 求值适配：`(擦除类型后的源码, 文件绝对路径, 注入全局) → 沙箱 console 输出文本`。 */
+export type TestEvaluator = (source: string, file: string, globals: Record<string, unknown>) => Promise<string>;
+export interface TestRunnerOptions {
+    vfs: VirtualFileSystem;
+    /** 求值实现（缺省走 `evaluateModuleSource`，与 `node <file>` 同一条路径）。 */
+    evaluate?: TestEvaluator;
+    /** 单条用例超时（默认 5s：浏览器主线程不能把一个卡住的 `await` 放任成挂死的终端）。 */
+    timeoutMs?: number;
+    now?: () => number;
+}
+/** 一次 `test` 命令的产物：终端打印用 `stdout` / `stderr` / `code`，IDE 面板用 `report`。 */
+export interface TestRunOutcome {
+    code: number;
+    stdout: string;
+    stderr: string;
+    report: TestReport;
+}
+/** shell 侧消费的最小接口（`ShellCtx.test`）：容器在装配处包一层，把报告回灌给 IDE 面板。 */
+export interface TestCommandPort {
+    run(target: string): Promise<{
+        code: number;
+        stdout: string;
+        stderr: string;
+    }>;
+}
+/** 创建测试运行器：`run(target)` 的 `target` 是已按 cwd 解析过的绝对路径。 */
+export declare function createTestRunner(options: TestRunnerOptions): {
+    run(target: string): Promise<TestRunOutcome>;
+};
+/** 递归收集测试文件（按路径字典序，报告才稳定可比）。 */
+export declare function collectTestFiles(vfs: VirtualFileSystem, root: string): string[];
+/**
+ * 报告文本：逐文件列用例（`✓` / `✗`），失败项紧跟期望 / 实际值，最后一行汇总计数。
+ * 汇总行以 `N passed` 开头（Gherkin 的通过判据），失败时补 `M failed` / `K error`。
+ */
+export declare function formatTestReport(report: TestReport): string;
+/** 汇总行（退出码 0 时只会出现 `N passed`）。 */
+export declare function summaryLine(report: TestReport): string;
+/** VFS 绝对路径 → 展示路径（去掉前导 `/`，终端与面板同一形态）。 */
+export declare function displayPath(absPath: string): string;
+/**
+ * `*.test.ts` 示例源码：`adep init` 模板 / 平台模板 / IDE 新建文件脚手架**共用这一份**，
+ * 避免「测试怎么写」的约定在多处各写一遍（§9 唯一真相源）。两条断言全过，新建即可跑绿。
+ */
+export declare function exampleTestSource(name?: string): string;

package/dist/vfs.d.ts

@@ -14,6 +14,14 @@ import type { WebContainerDirectoryTree, WebContainerFsEntry } from '@adep/types
 export declare const ROOT = "/";
 export declare class VirtualFileSystem {
     private readonly nodes;
+    /** 变更订阅者（`onMutate` 注册）：任意一次写操作后同步回调，供持久化 / HMR 等上层消费。 */
+    private readonly mutators;
+    /**
+     * 订阅文件系统变更（FE-022 持久化的接入点）：返回取消订阅函数。
+     * 回调在写操作**之后**同步触发，一次 `mount` 可能触发多次（内部逐条目写）——
+     * 消费方应自行合并（如 `createFsPersistence` 的去抖落盘），不要在此做重活。
+     */
+    onMutate(listener: () => void): () => void;
     /** 挂载一棵目录树（WebContainers `mount` 入参形态）。 */
     mount(tree: WebContainerDirectoryTree): void;
     private mountWithin;
@@ -41,6 +49,8 @@ export declare class VirtualFileSystem {
     getFileSystemTree(): WebContainerDirectoryTree;
     /** 列出兴趣路径的全部路径（用于模块解析 / glob 预载）。 */
     keys(): string[];
+    /** 通知全部变更订阅者（快照一份再遍历，允许订阅者在回调里退订）。 */
+    private notify;
     private ensureParent;
     private mkdirEnsureRecursive;
 }

package/dist/vite-dev.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 浏览器内 Vite 兼容 dev server（`vite` 命令本体）。
+ *
+ * preview.ts 的「虚拟静态 dev server」只内联经典脚本（`<script src>`），明确不跑
+ * ESM / TS / npm 依赖的编译管线（其文件头留了「替换为真正的 Vite pipeline」的接口）。
+ * 本模块补上这一层——在浏览器内、零第三方运行时约束下实现 Vite dev server 的核心语义：
+ *
+ * - **入口**：root 下的 `index.html`（或选项指定），`<script type="module">` 是模块入口；
+ * - **模块图**：递归解析 ESM import / export…from / 动态 import()，每个模块转换后生成
+ *   一个 `blob:` URL，模块里的说明符被改写成目标的 blob URL——整条链是浏览器原生 ESM
+ *   （真 live binding、真模块隔离），不是 CJS 打平；
+ * - **转换**：`.ts` 复用 stripTypes 擦类型；`.css` 变成「注入 `<style>` 的副作用模块」；
+ *   `.json` 变成默认导出对象；`.vue` 经注入的 SFC 编译器（IDE 侧装 `vue/compiler-sfc`）；
+ * - **依赖**：裸说明符经 node-resolve 命中 VFS `node_modules/`（终端 `npm install` 的产物），
+ *   与 CLI / 线上同一套解析规则；相对说明符支持 Vite 风格省略扩展名（.ts/.js/.vue/…）；
+ * - **HMR**：订阅 VFS 变更（`vfs.onMutate`，IDE 保存 / shell 写入 / npm 解包皆触发）→
+ *   防抖全量重建模块图 → 入口文档变化则经 `BroadcastChannel` 广播新 blob URL，预览 iframe
+ *   `location.replace` 自刷新（整页刷新式 HMR，组件级热替换留后续）；构建 / 解析失败时生成
+ *   「红屏错误页」而不是静默白屏。
+ *
+ * 边界（响亮失败，不静默降级）：
+ * - **循环依赖直接报错**（与 ide-widget-bundle 同口径）：blob 链的改写发生在加载期，
+ *   环会让「先有 URL 才能写引用」无解，如实报告环路径链；
+ * - `.tsx` / `.jsx` 不支持（stripTypes 只擦类型标注，不转 JSX），明确报错；
+ * - Node 内建模块（`node:`）与 CJS-only 包不支持（解析器只认 ESM 入口），明确报错。
+ */
+import type { VirtualFileSystem } from './vfs';
+/** SFC 编译器注入契约：`vue/compiler-sfc` 的适配（IDE 侧装配，本包零依赖不引 vue）。 */
+export interface SfcCompiler {
+    /**
+     * 编译单个 `.vue` 文件。`script` 必须是纯 JS（可含 ESM import，供后续 blob 改写），
+     * `styles` 为已编译的 CSS 文本（逐条注入副作用模块）。
+     */
+    (source: string, filename: string): {
+        script: string;
+        styles: string[];
+    };
+}
+export interface ViteServerOptions {
+    /** dev server 根目录（VFS 绝对路径，缺省 '/'）。 */
+    root?: string;
+    /** 入口文件名（相对 root，缺省 'index.html'）。 */
+    entry?: string;
+    /** SFC 编译器（缺省时 `.vue` 模块报「未装配」）。 */
+    sfcCompiler?: SfcCompiler;
+    /** blob URL 工厂（Node 单测注入假实现）。 */
+    createObjectURL?: (blob: Blob) => string;
+    revokeObjectURL?: (url: string) => void;
+}
+/** dev server 句柄：url / root 对外只读，`touch` 驱动 HMR，`stop` 释放资源。 */
+export interface ViteServer {
+    /** 当前入口文档的 blob URL（首次 `ready` 完成后有效）。 */
+    readonly url: string;
+    /** 虚拟端口（Vite 默认 5173，仅语义展示）。 */
+    readonly port: number;
+    /** root 的规范化绝对路径（幂等启动判定用）。 */
+    readonly root: string;
+    /** 首次构建完成（含错误文档——失败也是一次完成）。 */
+    readonly ready: Promise<void>;
+    /** 某路径发生变更：防抖全量重建，文档变化则广播 HMR。 */
+    touch(path: string): void;
+    /** 停止：撤销全部 blob URL、关闭 HMR 通道。 */
+    stop(): Promise<void>;
+}
+/** vite 构建期错误（红屏文档的 reason + message）。 */
+export declare class ViteDevError extends Error {
+    readonly reason: string;
+    constructor(reason: string, message: string);
+}
+/** `vite` 命令端口（shell 的 `case 'vite'` 消费；`bootstrap` 装配实现）。 */
+export interface ViteCommandPort {
+    /** `vite [dir]` / `vite dev [dir]`：启动（同根幂等复用，异根重启）。 */
+    start(args: readonly string[]): Promise<ViteCommandOutcome>;
+    /** `vite stop`：停止并释放。 */
+    stop(): Promise<ViteCommandOutcome>;
+}
+export interface ViteCommandOutcome {
+    code: number;
+    stdout: string;
+}
+/** 一次说明符命中：`start`/`end` 为含引号的原文区间（end 不含），改写按此切片替换。 */
+export interface EsmSpecifierHit {
+    specifier: string;
+    start: number;
+    end: number;
+}
+/**
+ * 扫描源码里的 ESM 模块说明符（静态 import / export…from / 动态 import()）。
+ * 说明符是这些语句里唯一的字符串字面量（`from` 别名 / 对象键等场景的字符串前必有
+ * `=` `:` `,` `(` 等标点，天然不命中），因此「字符串 + 前一个 token」即可可靠判定。
+ * 模板串整体跳过（`${}` 里的动态 import 不在支持范围，见文件头边界注）。
+ */
+export declare function scanEsmSpecifiers(source: string): EsmSpecifierHit[];
+export declare function createViteServer(vfs: VirtualFileSystem, options?: ViteServerOptions): ViteServer;

package/dist/worker-runtime.d.ts

@@ -26,7 +26,22 @@ export interface WorkerResponse {
     error?: string;
 }
 /** 隔离上下文求值：等价于 vm.ts 的 IFFE 包装，但跑在浏览器任意全局（Node 测试 / Worker 共用）。 */
-export declare function evaluateSource(source: string, filename: string, args: readonly string[]): Promise<string>;
+export declare function evaluateSource(source: string, filename: string, args: readonly string[], extraGlobals?: Record<string, unknown>): Promise<string>;
+/** `evaluateModuleSource` 的入参。 */
+export interface ModuleEvalOptions {
+    /** 传给脚本的 `__args`（`node <file> a b` 的参数）。 */
+    args?: readonly string[];
+    /** 追加注入的沙箱全局（测试运行器用它塞 `describe/it/expect`）。 */
+    globals?: Record<string, unknown>;
+    /** 覆盖源码（测试运行器传入的是擦除类型标注后的版本）；省略则从 VFS 读该文件。 */
+    source?: string;
+}
+/**
+ * 模块形态程序（`require` / 静态 `import`）的求值：读 VFS → import 变换 → 注入 require 全局 →
+ * `evaluateSource`。`node <file>` 的模块分支与 FN-022 的 `test` 命令**共用这一条路径**
+ * （任务单范围 4），隔离语义与 Worker 路径同款（同一 `fakeConsole` / `with (sandbox)`）。
+ */
+export declare function evaluateModuleSource(vfs: VirtualFileSystem, file: string, options?: ModuleEvalOptions): Promise<string>;
 /** 极简 Worker 形态（鸭子类型：Node 测试注入假 Worker 走同一协议）。 */
 export interface WorkerLike {
     postMessage(message: WorkerRequest): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adep/web-container",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -16,7 +16,8 @@
     "build:sdk": "pnpm exec esbuild src/index.ts --bundle --format=esm --platform=browser --outfile=dist/web-container.esm.js && pnpm exec esbuild src/index.ts --bundle --format=iife --global-name=AdepWebContainer --platform=browser --outfile=dist/web-container.iife.js"
   },
   "dependencies": {
-    "@adep/types": "workspace:*"
+    "@adep/runtime": "0.2.0",
+    "@adep/types": "0.2.0"
   },
   "publishConfig": {
     "main": "./dist/index.js",
@@ -31,5 +32,6 @@
         "default": "./dist/*.js"
       }
     }
-  }
+  },
+  "gitHead": "9c29cbb2a942afe4d4c7ae2987bcc229f6b99f9b"
 }