@adep/web-container 0.1.0 → 0.1.1

package/dist/module-loader.d.ts

@@ -0,0 +1,34 @@
+/**
+ * VFS 上的 CommonJS 模块加载器 + 静态 ESM import 变换（FN-021）。
+ *
+ * 安装后的 `node_modules/` 只有按 Node 解析规则命中还不够，还要**跑得起来**：
+ * - `createRequire(vfs, file)`：同步从 VFS 读文件、以 CJS 包装（`module/exports/require`）
+ *   求值，带按文件缓存与 `.json` 支持；解析全部委托 `node-resolve.ts`（含 main/exports）。
+ * - `transformStaticImports(source)`：把**单行静态** `import ... from '...'` 改写为 require
+ *   调用（default / 具名 / 命名空间 / side-effect 与组合形态）。多行 import、动态
+ *   `import()` 与 `export` 语句不在变换范围——沙箱执行器（worker/vm）历史上就不支持
+ *   ESM 导出，这里只补「import 第三方包」这一条首页承诺，不支持的形态保持原生语法错误
+ *   而不会被静默吃掉。
+ */
+import type { VirtualFileSystem } from './vfs';
+import { type ExportCondition } from './node-resolve';
+/** 已加载模块缓存：绝对路径 → module.exports。 */
+export type ModuleCache = Map<string, {
+    exports: unknown;
+}>;
+export interface RequireOptions {
+    /** exports 条件（`require()` 用 require，变换后的 ESM import 用 import）。 */
+    condition?: ExportCondition;
+    /** 共享模块缓存（同一轮执行内幂等，Node 的 require cache 语义）。 */
+    cache?: ModuleCache;
+}
+/** interop：`import d from 'x'` 的默认值取法（与 Node ESM-CJS 互操作一致）。 */
+export declare function interopDefault(value: unknown): unknown;
+/** 在给定 VFS 与导入方文件上构造同步 `require`。找不到 / 求值失败抛可读错误。 */
+export declare function createRequire(vfs: VirtualFileSystem, fromFileAbs: string, options?: RequireOptions): (specifier: string) => unknown;
+/** 是否使用了模块语法（require 调用或静态 import 行）——决定是否走模块加载路径。 */
+export declare function usesModuleSyntax(source: string): boolean;
+/** 把单行静态 import 语句改写为 require 调用（变换后源码交给 CJS 执行器）。 */
+export declare function transformStaticImports(source: string): string;
+/** 变换 + require 注入所需的沙箱全局（供 worker/vm 运行时组装）。 */
+export declare function createSandboxModuleGlobals(vfs: VirtualFileSystem, entryFileAbs: string): Record<string, unknown>;

package/dist/node-resolve.d.ts

@@ -0,0 +1,38 @@
+/** 解析所需的最小文件系统视图（`VirtualFileSystem` 天然满足）。 */
+export interface ResolveFs {
+    exists(path: string): boolean;
+    readFile(path: string): string;
+}
+/** package.json 中本模块消费的字段（其余字段忽略）。 */
+export interface PackageMeta {
+    name?: string;
+    version?: string;
+    main?: unknown;
+    exports?: unknown;
+    dependencies?: Record<string, string>;
+}
+/** Node 条件名：`import`（ESM 入口）与 `require`（CJS 入口）。 */
+export type ExportCondition = 'import' | 'require';
+/** 按扩展名 / 目录索引补全的文件候选后缀（顺序即优先级，与 Node 一致）。 */
+export declare const RESOLVE_EXTENSIONS: readonly [".js", ".mjs", ".cjs", ".json"];
+/** 解析失败错误（消息面向终端用户可读）。 */
+export declare class ResolveError extends Error {
+    constructor(message: string);
+}
+/** 安全解析 package.json 文本；非法 JSON / 非对象一律 ResolveError。 */
+export declare function parsePackageMeta(content: string, context: string): PackageMeta;
+/**
+ * 解析包的入口文件绝对路径（不校验文件存在——存在性由调用方经 `resolveFile` 兜底）。
+ * 规则见文件头注释；不支持的形状抛可读错误。
+ */
+export declare function resolvePackageEntry(meta: PackageMeta, pkgDirAbs: string, condition: ExportCondition): string;
+/** 拆分裸说明符为包名 + 子路径（scoped 包取两段）。 */
+export declare function splitPackageSpecifier(spec: string): {
+    name: string;
+    subpath: string;
+};
+/**
+ * 解析一个说明符到 VFS 文件绝对路径。`fromFileAbs` 是导入方文件（绝对路径）。
+ * 找不到抛 ResolveError（消息含导入方与说明符，可操作）。
+ */
+export declare function resolveImport(fs: ResolveFs, specifier: string, fromFileAbs: string, condition?: ExportCondition): string;

package/dist/npm-client.d.ts

@@ -1,22 +1,42 @@
 /**
- * npm 客户端（FN-012 对外 SDK）：经平台 `/npm-relay/*` 中继取真实 registry 依赖。
+ * npm 客户端（FN-012 对外 SDK / FN-021 安装闭环）：经平台 `/npm-relay/*` 中继取真实
+ * registry 依赖，并把 tarball **解包进虚拟文件系统 `node_modules/`**。
  *
- * 浏览器虚拟系统无法直连 npm registry（跨域）→ 全部请求走平台中继；
- * tarball 下载后写入虚拟文件系统 `.adep-cache/<name>-<version>.tgz`（本地离线复用，
- * 与中继的「元数据 + tarball 双层缓存」呼应；完整解包到 node_modules 属后续增强）。
+ * 浏览器虚拟系统无法直连 npm registry（跨域）→ 全部请求走平台中继。`install` 的完整链路：
+ * 1. `/package` 解析包名 + spec 到确定版本（服务端缓存元数据）；
+ * 2. 本地 `node_modules/<name>` 已有同版本 → 直接命中返回（重复安装幂等、零下载）；
+ * 3. 否则 `/tarball` 下载 `.tgz` 字节 → gzip 解压 + ustar 解包（`tar.ts`，零依赖手写）；
+ * 4. 读取包内 package.json 的 `dependencies`，按同一链路**递归**安装传递依赖
+ *    （深度上限 + 循环依赖硬错误）；
+ * 5. **先暂存、后提交**：整棵依赖闭包全部抓取 + 解包成功后才一次性写入 VFS——
+ *    任何一步失败（非白名单包、中继不可达、tarball 损坏）都不落一个字节的
+ *    `node_modules/`，杜绝「装了个半成品、import 时半可用」的状态。
+ *
+ * VFS 的文件内容是字符串（UTF-8），解包按文本解码落盘；纯二进制条目（如 `.node`）
+ * 为 lossy 形态——这类包本来就不该进浏览器沙箱，解析期会以可读错误暴露。
  */
 import type { CloudFetch } from '@adep/types';
 export interface NpmPersistence {
     exists(path: string): boolean;
     writeFile(path: string, contents: string): void;
 }
+/** `install` 需要读回已装包的 package.json 做幂等判定（VirtualFileSystem 满足）。 */
+export interface NpmInstallStorage extends NpmPersistence {
+    readFile(path: string): string;
+}
 export interface NpmClientOptions {
     /** 平台 npm 中继基础路径（如 `/api/v1/npm-relay`；相对绝对均可）。 */
     baseUrl: string;
-    /** 本地 tarball 落盘（写虚拟文件系统）。 */
-    storage: NpmPersistence;
+    /** 本地落盘（虚拟文件系统：tarball 缓存 + node_modules 解包）。 */
+    storage: NpmInstallStorage;
     /** 网络实现（缺省 globalThis.fetch）。 */
     fetchImpl?: CloudFetch;
+    /** 传递依赖递归深度上限（缺省 5，超限显式报错而非静默截断）。 */
+    maxDepth?: number;
+}
+export interface NpmInstalledPackage {
+    name: string;
+    version: string;
 }
 export interface NpmInstallResult {
     name: string;
@@ -24,9 +44,15 @@ export interface NpmInstallResult {
     distTags: string[];
     /** 本地缓存 tarball 的 VFS 路径。 */
     tarballPath: string;
-    /** 本次是否发生了真实下载（false = 本地缓存命中）。 */
+    /** 本次是否发生了真实下载（false = 已安装 / 本地缓存命中）。 */
     downloaded: boolean;
+    /** 本次闭包安装到的全部包（含传递依赖，拓扑序：根包在前）。 */
+    packages: NpmInstalledPackage[];
+    /** 根包在 VFS 中的安装目录（相对根）。 */
+    nodeModulesPath: string;
 }
+/** 传递依赖递归深度上限：真实浅树（lodash 零依赖、dayjs 零依赖）远低于它；超它即失控。 */
+export declare const DEFAULT_MAX_INSTALL_DEPTH = 5;
 /** 解析 `name` 或 `name@spec` 到 { name, spec? }（含 scoped 包）。 */
 export declare function parseSpec(spec: string): {
     name: string;

package/dist/offline/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 离线工作区模块（FN-017）。
+ *
+ * 浏览器侧离线能力：网络状态探测 / 待发布队列 / 源码工作区持久化。
+ * 模拟 Provider（sim-db / sim-storage）在后续任务中补充，本单先交付核心基础设施。
+ */
+export * from './net';
+export * from './queue';
+export * from './workspace';

package/dist/offline/net.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 网络状态探测与在线/离线切换（FN-017，PRD §2.14.2）。
+ *
+ * 设计原则：
+ * - 浏览器 `online` / `offline` 事件作为主信号，但不盲信（有时事件触发但实际仍不可达）；
+ * - 主动探测仅打 `GET /api/v1/health`（轻量、无鉴权、无副作用），**禁止轮询风暴**：
+ *   离线态下最多每 30s 探测一次，在线态下不主动探测（由事件驱动）；
+ * - 状态切换是单向的：offline → online 必须经过一次成功的 health 探测才确认（避免假在线）；
+ *   online → offline 由 `offline` 事件或 fetch 失败立即触发。
+ *
+ * 本文件零 DOM 依赖之外的运行时 API（仅用 `window.addEventListener` / `fetch`），
+ * 可在浏览器与 Service Worker 中复用；Node 环境下退化为「永远在线」。
+ */
+export type NetworkStatus = 'online' | 'offline' | 'checking';
+export interface NetworkState {
+    status: NetworkStatus;
+    /** 最近一次状态切换的时间戳（ms）。 */
+    lastChangedAt: number;
+    /** 最近一次成功 health 探测的时间戳（ms），离线时为 null。 */
+    lastHealthOkAt: number | null;
+}
+type StatusListener = (state: NetworkState) => void;
+declare class NetworkMonitor {
+    private state;
+    private listeners;
+    private healthTimer;
+    private started;
+    /** 启动监听（幂等）。在浏览器环境下绑定 online/offline 事件。 */
+    start(): void;
+    /** 停止监听并清理定时器。 */
+    stop(): void;
+    /** 获取当前网络状态快照。 */
+    getState(): NetworkState;
+    /** 订阅状态变化；返回取消订阅函数。 */
+    subscribe(listener: StatusListener): () => void;
+    /** 主动触发一次 health 探测（用于用户手动点击「重试连接」等场景）。 */
+    checkNow(): Promise<boolean>;
+    private handleOnlineEvent;
+    private handleOfflineEvent;
+    private probeHealth;
+    private startHealthTimer;
+    private stopHealthTimer;
+    private setState;
+}
+/** 单例：全局共享一个网络监视器（避免多个实例各自起定时器导致探测风暴）。 */
+export declare const networkMonitor: NetworkMonitor;
+/** 便捷函数：当前是否在线。 */
+export declare function isOnline(): boolean;
+/** 便捷函数：订阅在线状态变化。 */
+export declare function onNetworkChange(listener: StatusListener): () => void;
+export {};

package/dist/offline/queue.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 待发布队列的客户端存储（FN-017，PRD §2.14.3）。
+ *
+ * 离线时的发布意图不落服务端版本（版本号只能由服务端生成），而是进本地队列，
+ * 回网后由用户确认重放（服务端冲突判定与幂等重放在 FN-018，UI 在 FE-016）。
+ *
+ * 本单只交付 headless 存储与状态机：
+ * - 入队：生成幂等键 queueId（projectId + intentType + baseVersion + 变更文件摘要的 hash），
+ *   同键重复入队不产生第二条（幂等）；
+ * - 出队：按创建时间 FIFO，标记为「重放中」；
+ * - 状态机：pending → replaying → done / failed；
+ * - 持久化：localStorage（简单、同步、零依赖；后续可换 IndexedDB 但本单不做）。
+ *
+ * 队列项不含任何 secret（变更文件摘要只含路径 + hash，不含内容）。
+ */
+export type PublishIntentType = 'function_publish' | 'function_delete' | 'env_update' | 'deployment';
+export type QueueItemStatus = 'pending' | 'replaying' | 'done' | 'failed';
+export interface QueueItem {
+    /** 幂等键：projectId + intentType + baseVersion + fileSummaryHash 的 SHA-256 前 16 位。 */
+    queueId: string;
+    projectId: string;
+    intentType: PublishIntentType;
+    /** 变更文件摘要：[{ path, contentHash }]，只含路径与内容 hash，不含文件内容本身。 */
+    fileSummary: Array<{
+        path: string;
+        contentHash: string;
+    }>;
+    /** 发布时的基线版本（用于回网后服务端冲突判定）。 */
+    baseVersion: string;
+    status: QueueItemStatus;
+    createdAt: number;
+    updatedAt: number;
+    /** 失败时的错误信息（status=failed 时存在）。 */
+    error?: string;
+    /** 重放后的服务端版本号（status=done 时存在）。 */
+    serverVersion?: string;
+}
+export interface EnqueueOptions {
+    projectId: string;
+    intentType: PublishIntentType;
+    fileSummary: Array<{
+        path: string;
+        contentHash: string;
+    }>;
+    baseVersion: string;
+}
+declare class PublishQueue {
+    private items;
+    private loaded;
+    /** 从 localStorage 加载队列（懒加载，首次调用时执行）。 */
+    private ensureLoaded;
+    /** 持久化到 localStorage。 */
+    private persist;
+    /** 入队：幂等，同 queueId 不重复入队。返回队列项（新入队或已存在）。 */
+    enqueue(options: EnqueueOptions): QueueItem;
+    /** 出队：按创建时间 FIFO，取第一个 pending 项并标记为 replaying。 */
+    dequeue(): QueueItem | null;
+    /** 标记重放成功。 */
+    markDone(queueId: string, serverVersion: string): void;
+    /** 标记重放失败。 */
+    markFailed(queueId: string, error: string): void;
+    /** 重试失败项：把 failed 项重置为 pending。 */
+    retry(queueId: string): void;
+    /** 移除队列项（用户取消或已完成后清理）。 */
+    remove(queueId: string): void;
+    /** 清空已完成的项（done 状态）。 */
+    clearDone(): void;
+    /** 获取所有队列项（按创建时间排序）。 */
+    list(): QueueItem[];
+    /** 按状态筛选。 */
+    listByStatus(status: QueueItemStatus): QueueItem[];
+    /** 按项目筛选。 */
+    listByProject(projectId: string): QueueItem[];
+    /** 待发布项数量（pending + replaying）。 */
+    pendingCount(): number;
+    /** 是否有未同步的改动（pending 或 failed）。 */
+    hasUnsyncedChanges(): boolean;
+}
+/** 单例：全局共享一个发布队列。 */
+export declare const publishQueue: PublishQueue;
+export {};

package/dist/offline/workspace.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 离线工作区（FN-017，PRD §2.14.4）。
+ *
+ * 源码工作副本的浏览器端持久化：逐项目分区，文件路径 → 内容的键值存储。
+ * 后端为 IndexedDB（异步、大容量、支持 Blob）；Node 环境下退化为内存 Map（仅用于测试）。
+ *
+ * 设计原则：
+ * - 逐项目分区：每个项目一个 object store（`workspace:{projectId}`），避免跨项目污染；
+ * - 文件级读写：get/put/delete/list，路径为键，内容为字符串（源码文本）或 Blob（二进制资源）；
+ * - 快照与恢复：snapshot() 返回整个项目的文件树，restore() 从快照恢复（用于离线初始化）；
+ * - 变更追踪：记录最后修改时间，用于「未同步」计数与冲突判定；
+ * - **secret 不进工作区**：环境变量中的 secret 项只存键名，不存值（值在内存中，刷新后需重新输入）。
+ *
+ * 本文件不依赖任何 UI 框架，可在 Service Worker 与主线程中复用。
+ */
+export interface WorkspaceFile {
+    path: string;
+    content: string;
+    /** 最后修改时间（ms）。 */
+    lastModifiedAt: number;
+    /** 是否为 secret 项（secret 项不持久化内容）。 */
+    isSecret?: boolean;
+}
+export interface WorkspaceSnapshot {
+    projectId: string;
+    files: Array<{
+        path: string;
+        content: string;
+        lastModifiedAt: number;
+    }>;
+    /** 快照生成时间（ms）。 */
+    createdAt: number;
+}
+declare class OfflineWorkspace {
+    private backend;
+    constructor();
+    /** 读取文件。 */
+    getFile(projectId: string, path: string): Promise<WorkspaceFile | null>;
+    /** 写入文件（自动更新 lastModifiedAt）。 */
+    putFile(projectId: string, path: string, content: string, isSecret?: boolean): Promise<void>;
+    /** 删除文件。 */
+    deleteFile(projectId: string, path: string): Promise<void>;
+    /** 列出项目所有文件。 */
+    listFiles(projectId: string): Promise<WorkspaceFile[]>;
+    /** 检查文件是否存在。 */
+    hasFile(projectId: string, path: string): Promise<boolean>;
+    /** 生成项目快照（用于离线初始化或导出）。 */
+    snapshot(projectId: string): Promise<WorkspaceSnapshot>;
+    /** 从快照恢复（覆盖现有文件）。 */
+    restore(projectId: string, snapshot: WorkspaceSnapshot): Promise<void>;
+    /** 清空项目工作区。 */
+    clear(projectId: string): Promise<void>;
+    /** 获取项目文件数。 */
+    fileCount(projectId: string): Promise<number>;
+    /** 获取最近修改的文件（用于「未同步」展示）。 */
+    recentlyModified(projectId: string, limit?: number): Promise<WorkspaceFile[]>;
+}
+/** 单例：全局共享一个离线工作区。 */
+export declare const offlineWorkspace: OfflineWorkspace;
+export {};

package/dist/persistence.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 浏览器终端文件系统的可插拔持久化（FE-022，PRD §2.14）。
+ *
+ * `vfs.ts` 自 FN-012 起就写着「持久化由上层负责」，但上层从未接上：`bootstrap()` 每次新建内存 VFS，
+ * 终端里 `mkdir` / `echo > file` 建出来的文件刷新即丢（本单修的就是这一段）。
+ *
+ * 设计（与 `offline/workspace.ts` 同一取向：浏览器 IndexedDB、Node 内存，零运行时依赖）：
+ * - **整树快照**而非逐条目写：VFS 是全内存的小树（浏览器内工作区），一次 `save(namespace, entries)`
+ *   比逐文件 put/delete 少一类「漏删」的错（VFS 里删掉的文件不会在库里留孤儿）；
+ * - **namespace 分区**：按项目 / 按用途隔离（IDE 终端用 `terminal-fs:<projectId>`），互不污染；
+ * - **去抖落盘**：订阅 `vfs.onMutate`，合并一次命令引发的多次写之后再写库；提供显式 `flush()`
+ *   给「刷新前必须落盘」与 e2e 用（不依赖定时器，判据确定）。
+ *
+ * 本文件零 node 依赖，浏览器与 Node 单测共用；`indexedDB` / `localStorage` 不可用时自动降级为内存。
+ */
+import type { WebContainerDirectoryTree } from '@adep/types';
+import { VirtualFileSystem } from './vfs';
+/** 快照中的一个条目（目录与文件分记，`contents` 只对文件有意义）。 */
+export interface FsPersistEntry {
+    path: string;
+    kind: 'file' | 'dir';
+    contents?: string;
+}
+export interface FsPersistenceBackend {
+    load(namespace: string): Promise<FsPersistEntry[]>;
+    save(namespace: string, entries: FsPersistEntry[]): Promise<void>;
+    clear(namespace: string): Promise<void>;
+}
+/** 把当前 VFS 拍平成快照条目（目录与文件都含，根 `/` 不入库——它是常量）。 */
+export declare function snapshotVfs(vfs: VirtualFileSystem): FsPersistEntry[];
+/** 从快照恢复：先目录后文件（`writeFile` 本身会自动补父，分序只为语义清晰与空目录可恢复）。 */
+export declare function restoreVfs(vfs: VirtualFileSystem, entries: readonly FsPersistEntry[]): void;
+/**
+ * 快照 → 目录树（`WebContainerDirectoryTree` 形态）：供只能经 `WebContainer.mount()` 消费的上层复用，
+ * 不必持有 `VirtualFileSystem` 实例。
+ */
+export declare function entriesToTree(entries: readonly FsPersistEntry[]): WebContainerDirectoryTree;
+/** 内存后端（Node 单测 / SSR / 无 IndexedDB 环境）。每次调用产出独立实例，测试之间互不串味。 */
+export declare function createMemoryFsBackend(): FsPersistenceBackend;
+/** IndexedDB 后端：单库单仓（`namespace` 为主键），整棵树的快照一条记录。 */
+export declare function createIndexedDbFsBackend(dbName?: string): FsPersistenceBackend;
+/** 缺省后端：浏览器 IndexedDB，其余（Node 单测 / SSR）内存。 */
+export declare function pickDefaultFsBackend(): FsPersistenceBackend;
+export interface FsPersistenceOptions {
+    /** 要持久化的 VFS（与 `bootstrap({ vfs })` 同一个实例）。 */
+    vfs: VirtualFileSystem;
+    /** 分区键，如 `terminal-fs:<projectId>`。 */
+    namespace: string;
+    /** 后端（缺省按环境自动选）。 */
+    backend?: FsPersistenceBackend;
+    /** 去抖窗口（ms，默认 150）。 */
+    debounceMs?: number;
+}
+export interface FsPersistence {
+    /** 启动时灌回历史（返回恢复的条目数）；必须在挂载初始文件之前调用，让服务端草稿覆盖为权威。 */
+    hydrate(): Promise<number>;
+    /** 立即落盘（取消挂起的去抖）。 */
+    flush(): Promise<void>;
+    /** 清空该 namespace 的持久化内容（不动当前 VFS）。 */
+    clear(): Promise<void>;
+    /** 是否有尚未落盘的变更。 */
+    pending(): boolean;
+    /** 最后一次成功落盘时间（ms），未落过为 null。 */
+    lastSavedAt(): number | null;
+    /** 退订 VFS 变更（组件卸载时调用）。 */
+    dispose(): void;
+}
+/**
+ * 把 VFS 接到持久化后端上：`hydrate()` 灌回 → 订阅变更去抖落盘 → `flush()` 强制落盘。
+ * 恢复期间自身写操作不再触发落盘（否则「读回来又写回去」会白跑一次并可能覆盖更新中的快照）。
+ */
+export declare function createFsPersistence(options: FsPersistenceOptions): FsPersistence;
+/** 键值存储端口（`localStorage` 形态；测试可注入替身）。 */
+export interface KvStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** 内存 KV（Node / 隐私模式 localStorage 不可用时的降级）。 */
+export declare function createMemoryKvStorage(): KvStorage;
+export interface CommandHistory {
+    /** 全部历史（旧 → 新）。 */
+    list(): string[];
+    /** 追加一条（空串与上一条重复忽略），返回当前列表。 */
+    push(line: string): string[];
+    clear(): void;
+}
+/**
+ * 终端命令历史的持久化存储（FE-022）：刷新 / 重开会话后 ↑ 仍可回溯。
+ * 与 fs 快照分放两处（KV vs IndexedDB）是刻意的：历史是小而频繁的字符串数组，`localStorage` 同步读写
+ * 最贴合（与 FN-017 的待发布队列同口径），不值得为它开一次异步事务。
+ */
+export declare function createCommandHistory(options: {
+    key: string;
+    limit?: number;
+    storage?: KvStorage;
+}): CommandHistory;

package/dist/shell.d.ts

@@ -8,6 +8,8 @@
  * 浏览器可跑（零 node 依赖），`runtime` 为可替换适配（QuickJS WASM / Node vm）。
  */
 import type { VirtualFileSystem } from './vfs';
+import { type CompletionResult } from './completion';
+import type { TestCommandPort } from './test-runner';
 /** JS 运行时适配接口：能加载并执行一段 JS 模块（QuickJS WASM / Web Worker 沙箱 / Node vm 等实现）。 */
 export interface JsRuntime {
     /** 执行脚本文件，返回标准输出文本；实现抛错时以 `stderr` 语义上报。 */
@@ -25,6 +27,8 @@ export interface ShellCtx {
     getCwd(): string;
     setCwd(path: string): void;
     runtime?: JsRuntime;
+    /** `test` 命令的运行器（FN-022）：由 `bootstrap` 装配；裸 Shell 未注入时如实报「未装配」。 */
+    test?: TestCommandPort;
 }
 export declare class Shell {
     private readonly ctx;
@@ -33,6 +37,11 @@ export declare class Shell {
     execute(line: string): Promise<ShellResult>;
     private runSegment;
     private ls;
+    /**
+     * 对当前输入行求 Tab 补全候选（FE-022）：命令位补内建命令名，参数位补 VFS 路径。
+     * 无候选不抛错（Tab 不该让终端报错），由调用方决定「不响应」还是「列出可能项」。
+     */
+    complete(line: string): CompletionResult;
     /** 相对 cwd 解析为绝对路径（VFS key）。 */
     private resolve;
 }

package/dist/sim/ctx.d.ts

@@ -0,0 +1,19 @@
+import type { Cloud } from '@adep/types';
+import type { CapabilityBundle, CapabilityRpcHandler } from '@adep/types';
+/** worker 端口协议的最小投影（`WorkerPort` 的结构子集，进程内实现）。 */
+export interface MinimalPort {
+    postMessage(message: unknown): void;
+    on(listener: (message: unknown) => void): void;
+}
+/**
+ * 把宿主能力 handler 包成进程内 port：上行 `{type:'rpc', id, capability, method, args}` →
+ * 直调 handler → 以 `{type:'rpc-response', id, ok, result|error}` 回执。
+ * 错误归一为 `Error(message)`——与 worker 跨线程路径的回执形状一致（码已由 handler 装进 message）。
+ */
+export declare function createLocalPort(handler: CapabilityRpcHandler): MinimalPort;
+/**
+ * 按 bundle 产出用户函数侧的 `ctx.cloud`：
+ * - 注册语义与 `worker-entry.runWorker` 相同（链式 / 命令通道 / 原值三分支）；
+ * - 未注册能力访问时抛与线上同文案的可操作提示（createCloudContainer 守卫）。
+ */
+export declare function buildCloudFromBundle(bundle: CapabilityBundle): Cloud;

package/dist/sim/db.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 浏览器模拟 `cloud.db`（FN-023）：`SimSqlEngine`（@adep/runtime/sim/sql-engine，与 CLI sim
+ * 同一份语义）+ IndexedDB/内存持久层 → 线上 `createDbCapability` 装配。
+ *
+ * 一致性红线（与 CLI-004 同一条）：**只读复用线上 Provider 的装配逻辑**（`createDbCapability`），
+ * 只把驱动换成本文件绑定的进程内引擎——CRUD / 事务 / owned 变更流 / 安全硬约束全走与线上
+ * 完全相同的那份代码，契约必然一致（`shared/sim-contract.ts` 契约表在本仓测试里钉死）。
+ *
+ * 持久化：整库表快照存 `db:<projectId>` 键（`SimKvBackend`），刷新后数据仍在
+ * （Gherkin 场景 1 的 IndexedDB 判据）。
+ */
+import type { CapabilityBundle } from '@adep/types';
+import type { ProjectDriver } from '@adep/runtime/db/project-driver';
+import { SimSqlEngine } from '@adep/runtime/sim/sql-engine';
+import type { SimKvBackend } from './kv';
+export interface CreateBrowserSimDbOptions {
+    /** 项目 id（持久化分区键；`db:<projectId>`）。 */
+    projectId: string;
+    /** 持久化后端；缺省按环境自动选（浏览器 IndexedDB / 其余内存）。 */
+    kv?: SimKvBackend;
+}
+/** db 持久化键（`runtime.ts` 与诊断面共用；导出便于测试直读）。 */
+export declare function simDbKey(projectId: string): string;
+/**
+ * 构造浏览器侧 `cloud.db` 能力 bundle，并暴露绑定它的 `engine`（schema 水合 / 测试断言面）
+ * 与 `driver`（ProjectDriver 形状）。内部复用线上 `createDbCapability`，
+ * bundle 的 `capabilities[].value`（链式规格）与 `rpcHandlers.db` 与线上完全一致。
+ */
+export declare function createBrowserSimDb(options: CreateBrowserSimDbOptions): {
+    bundle: CapabilityBundle;
+    engine: SimSqlEngine;
+    driver: ProjectDriver;
+};

package/dist/sim/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 浏览器模拟运行时（FN-023）：断网在浏览器内执行 cloud.* 真实语义。
+ *
+ * 能力装配复用 `@adep/runtime` 的线上工厂（只换持久化与传输落点，不改 API 语义）：
+ * - `cloud.db`：SimSqlEngine（与 CLI sim 同一份引擎语义）+ IndexedDB 持久化（按项目分区）；
+ * - `cloud.storage`：IndexedDB/blob 驱动，接口与线上 `createStorageCapability` 一致；
+ * - `cloud.realtime`：离线内存广播（CLI sim 同源语义）+ 回网切真实 WS 的传输切换；
+ * - 离线函数运行器：stripTypes → transformModule → evaluateModuleSource，`ctx` 与线上同形。
+ *
+ * 与 CLI / 线上的一致性由 `@adep/runtime/shared/sim-contract.ts` 的同一张契约表钉死
+ * （本包测试对浏览器驱动逐条复跑该表）。
+ */
+export { pickDefaultSimKv, createMemorySimKv, createIdbSimKv } from './kv';
+export type { SimKvBackend } from './kv';
+export { createBrowserSimDb, simDbKey } from './db';
+export { createBrowserSimStorage, createBrowserStorageDriver, simStorageKey } from './storage';
+export { createBrowserRealtime } from './realtime';
+export type { BrowserRealtimeOptions, MinimalWebSocket, TicketResult } from './realtime';
+export { createLocalPort, buildCloudFromBundle } from './ctx';
+export type { MinimalPort } from './ctx';
+export { createOfflineFunctionRunner } from './runner';
+export type { LocalLogEntry, OfflineRunInput, OfflineRunRequest, OfflineRunResult, OfflineRunnerOptions, } from './runner';
+export { createBrowserSimRuntime } from './runtime';
+export type { BrowserSimRuntime, BrowserSimRuntimeOptions } from './runtime';

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;
+};