@adep/web-container 0.1.0

package/README.md

@@ -0,0 +1,39 @@
+# @adep/web-container — AgentDeploy 浏览器原生开发环境 SDK
+
+> **浏览器端开发/运行环境 SDK**（任务单 FN-012）：虚拟文件系统 + 进程/shell + JS 运行时适配接口 + npm-relay 客户端。对标 [WebContainers](https://webcontainers.io) API——**Node 可测、浏览器可跑**。
+
+```bash
+npm install @adep/web-container
+# 或
+pnpm add @adep/web-container
+```
+
+## 能力总览
+
+| 能力            | 说明                        |
+| ------------- | ------------------------- |
+| 虚拟文件系统 (VFS)  | 内存文件树：读写 / 查找 / 变更通知      |
+| 进程 / shell    | 在虚拟环境中执行命令、管道输入输出         |
+| 运行时适配接口       | 用适配器接宿主运行时（预览 / 沙箱执行）     |
+| npm-relay 客户端 | 经平台 npm-relay 安装 / 解析前端依赖 |
+
+## 用法
+
+```ts
+import { createWebContainer } from '@adep/web-container'
+
+const container = await createWebContainer({
+  // 传入文件系统与运行时适配器
+})
+
+await container.fs.mkdir('/hello')
+await container.fs.writeFile('/hello/index.txt', 'hi')
+const text = await container.fs.readFile('/hello/index.txt', 'utf8')
+```
+
+## 说明
+
+- 面向浏览器，同时成 Node 可测；依赖 `@adep/types` 提供类型契约。
+
+- 需要浏览器内作为 `<script>` 全局加载的 IIFE 变体见 `scripts.build:sdk`（`dist/web-container.iife.js`，`globalName = AdepWebContainer`）。
+

package/dist/container.d.ts

@@ -0,0 +1,26 @@
+/**
+ * WebContainer（FN-012 对外 SDK 主体）——对标 WebContainers `bootstrap()` 返回的实例。
+ *
+ * 组装虚拟文件系统 + shell + JS 运行时适配 + npm 客户端，对外暴露：
+ * `mount` / `writeFile` / `readFile` / `listDirectory` / `createDirectory` / `deleteFile` /
+ * `exists` / `spawn` / `run` / `on` / `off` / `install` / `registries` / `close`。
+ *
+ * `spawn` 走内置 shell（重定向/管道/内建命令），`node`/`js` 命令走可替换 JS 运行时适配
+ * （QuickJS WASM 浏览器端 / Node vm 测试端）。`bootstrap` 是唯一工厂。
+ */
+import type { WebContainer, WebContainerDirectoryTree } from '@adep/types';
+import type { CloudFetch } from '@adep/types';
+import { type JsRuntime } from './shell';
+export interface BootstrapOptions {
+    /**
+     * 平台 npm 中继基础路径（浏览器端相对当前源，如 `/api/v1/npm-relay`）。
+     */
+    npmRelayBaseUrl: string;
+    /** 初始目录树（同 `mount` 入参）。 */
+    initialTree?: WebContainerDirectoryTree;
+    /** JS 运行时适配（缺省禁用 `node` 命令；提供 QuickJS WASM 实现后注入）。 */
+    runtime?: JsRuntime;
+    /** npm 中继网络实现（缺省 globalThis.fetch；测试注入假中继）。 */
+    fetchImpl?: CloudFetch;
+}
+export declare function bootstrap(options: BootstrapOptions): WebContainer;

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `@adep/web-container` —— adep 平台浏览器原生开发环境对外 SDK（FN-012）。
+ *
+ * 对标 WebContainers API（`bootstrap` / `mount` / `spawn` / `writeFile` / `on`）：
+ * - 虚拟文件系统（`VirtualFileSystem`）；
+ * - shell（内建命令 + 重定向/管道，`Shell` / `JsRuntime` 适配接口）；
+ * - `bootstrap()` 组装完整容器，浏览器端缺省注入 Web Worker 沙箱运行时（`node` 命令可执行 JS）；
+ * - npm 经平台 `/npm-relay/*` 中继取真实 registry（`createNpmClient`）。
+ *
+ * Node 可测、浏览器可跑（零 node 依赖）。Node vm 实现（`vm.ts`）不在此导出，
+ * 以免把 `node:vm` 带进浏览器包；浏览器端缺省走 `createWorkerRuntime`（Web Worker），
+ * 也可整体替换为 QuickJS WASM 实现 `JsRuntime`。
+ */
+export { bootstrap } from './container';
+export type { BootstrapOptions } from './container';
+export { VirtualFileSystem } from './vfs';
+export { Shell } from './shell';
+export type { JsRuntime, ShellResult } from './shell';
+export { createWorkerRuntime, evaluateSource } from './worker-runtime';
+export type { WorkerRuntimeOptions, WorkerLike } from './worker-runtime';
+export { createNpmClient, parseSpec } from './npm-client';
+export type { NpmClientOptions, NpmInstallResult } from './npm-client';
+export * as posix from './path';
+export type { WebContainer, WebContainerDirectoryTree, WebContainerEventMap, WebContainerFsEntry, WebContainerProcess, } from '@adep/types';

package/dist/index.js

@@ -0,0 +1,899 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// packages/web-container/src/path.ts
+var path_exports = {};
+__export(path_exports, {
+  SEP: () => SEP,
+  basename: () => basename,
+  dirname: () => dirname,
+  extname: () => extname,
+  isAbsolute: () => isAbsolute,
+  isValidSegment: () => isValidSegment,
+  join: () => join,
+  normalize: () => normalize
+});
+function normalize(path) {
+  const isAbs = path.startsWith(SEP);
+  const parts = path.split(SEP);
+  const out = [];
+  for (const part of parts) {
+    if (part === "" || part === ".") continue;
+    if (part === "..") {
+      if (out.length > 0) out.pop();
+      else if (!isAbs) out.push("..");
+      continue;
+    }
+    out.push(part);
+  }
+  const joined = out.join(SEP);
+  const rooted = isAbs || joined.startsWith("..");
+  if (rooted) return `${SEP}${joined.replace(/^\/+/, "")}`;
+  return joined === "" ? "/" : joined;
+}
+function isAbsolute(path) {
+  return path.startsWith(SEP);
+}
+function join(base, ...paths) {
+  let result = base;
+  for (const p of paths) {
+    if (isAbsolute(p)) result = p;
+    else if (result === "" || result === SEP) result = `${SEP}${p.replace(/^\/+/, "")}`;
+    else result = `${result.replace(/\/+$/, "")}${SEP}${p.replace(/^\/+/, "")}`;
+  }
+  return normalize(result);
+}
+function dirname(path) {
+  const normalized = normalize(path);
+  if (normalized === SEP) return SEP;
+  const index = normalized.lastIndexOf(SEP);
+  if (index <= 0) return SEP;
+  return normalized.slice(0, index);
+}
+function basename(path) {
+  const normalized = normalize(path);
+  if (normalized === SEP) return "";
+  const index = normalized.lastIndexOf(SEP);
+  return index === -1 ? normalized : normalized.slice(index + 1);
+}
+function extname(path) {
+  const name = basename(path);
+  const index = name.lastIndexOf(".");
+  return index <= 0 ? "" : name.slice(index);
+}
+function isValidSegment(name) {
+  return name.length > 0 && name !== "." && name !== ".." && !name.includes(SEP) && name !== "\\";
+}
+var SEP;
+var init_path = __esm({
+  "packages/web-container/src/path.ts"() {
+    "use strict";
+    SEP = "/";
+  }
+});
+
+// packages/web-container/src/preview.ts
+var preview_exports = {};
+__export(preview_exports, {
+  buildPreviewDocument: () => buildPreviewDocument,
+  createPreviewServer: () => createPreviewServer,
+  inlineAssets: () => inlineAssets
+});
+function resolveLocal(vfs, src, baseDir) {
+  if (EXTERNAL_SRC.test(src) || /^data:|^blob:|^#/i.test(src)) return null;
+  const abs = src.startsWith("/") ? normalize(src) : join(baseDir, src);
+  if (!vfs.exists(abs) || vfs.isDirectory(abs)) return null;
+  return abs;
+}
+function inlineAssets(html, vfs, baseDir) {
+  let out = html.replace(
+    /<script\b([^>]*?)\bsrc\s*=\s*(["'])(.*?)\2([^>]*)><\/script>/gi,
+    (whole, pre, _q, orig, post) => {
+      if (/\btype\s*=\s*["']module["']/i.test(pre + post)) return whole;
+      const abs = resolveLocal(vfs, orig, baseDir);
+      if (abs === null) return whole;
+      const code = vfs.readFile(abs);
+      return `<script${pre}${post}>${code}</script>`;
+    }
+  );
+  out = out.replace(
+    /<link\b([^>]*?)\brel\s*=\s*(["'])stylesheet\2([^>]*?)\bhref\s*=\s*(["'])(.*?)\4([^>]*?)\/?\s*>/gi,
+    (whole, _pre, _q, _post, _r, orig) => {
+      const abs = resolveLocal(vfs, orig, baseDir);
+      if (abs === null) return whole;
+      return `<style>${vfs.readFile(abs)}</style>`;
+    }
+  );
+  return out;
+}
+function directoryListing(cwd, vfs) {
+  const rows = vfs.listDirectory(cwd).map((entry) => `<li>${entry.type === "file" ? "\u{1F4C4}" : "\u{1F4C1}"} <code>${entry.path}</code></li>`).join("");
+  return `<!doctype html><html><head><meta charset="utf-8"><title>\u9884\u89C8 ${cwd}</title></head>
+<body><h3>\u9884\u89C8\u5DE5\u4F5C\u533A\uFF1A<code>${cwd}</code></h3><p>\u672A\u627E\u5230\u5165\u53E3\u6587\u4EF6 <code>index.html</code>\uFF0C\u5217\u51FA\u5982\u4E0B\uFF1A</p>
+<ul>${rows}</ul></body></html>`;
+}
+function buildPreviewDocument(vfs, options) {
+  const entryAbs = join(options.cwd, options.entry);
+  const html = vfs.exists(entryAbs) && !vfs.isDirectory(entryAbs) ? vfs.readFile(entryAbs) ?? "" : directoryListing(options.cwd, vfs);
+  let doc = inlineAssets(html, vfs, dirname(entryAbs));
+  const hmr = `<script>(function(){if(typeof BroadcastChannel==='undefined')return;var bc=new BroadcastChannel(${JSON.stringify(
+    options.channelName
+  )});bc.onmessage=function(e){var d=e.data;if(d&&d.type==='update'&&d.url&&d.url!==location.href){location.replace(d.url);}};})();</script>`;
+  if (/<\/body>/i.test(doc)) doc = doc.replace(/<\/(body)>/i, `${hmr}</$1>`);
+  else doc += hmr;
+  return doc;
+}
+function createPreviewServer(vfs, options = {}) {
+  const cwd = normalize(options.cwd ?? "/");
+  const entry = options.entry ?? "index.html";
+  const createObjectURL = options.createObjectURL ?? ((blob) => URL.createObjectURL(blob));
+  const revokeObjectURL = options.revokeObjectURL ?? ((url) => URL.revokeObjectURL(url));
+  const channelName = `adep:preview:${Math.random().toString(36).slice(2)}`;
+  const port = 5173;
+  let currentUrl = "";
+  let lastDoc = null;
+  let bc = null;
+  const broadcast = (url) => {
+    try {
+      bc ??= new BroadcastChannel(channelName);
+      bc.postMessage({ type: "update", url });
+    } catch {
+    }
+  };
+  const serve = () => {
+    const doc = buildPreviewDocument(vfs, { cwd, entry, channelName });
+    const changed = doc !== lastDoc;
+    lastDoc = doc;
+    if (currentUrl !== "") revokeObjectURL(currentUrl);
+    currentUrl = createObjectURL(new Blob([doc], { type: "text/html" }));
+    return { url: currentUrl, changed };
+  };
+  serve();
+  return {
+    get url() {
+      return currentUrl;
+    },
+    get port() {
+      return port;
+    },
+    touch() {
+      const { url: next, changed } = serve();
+      if (changed) broadcast(next);
+    },
+    stop() {
+      if (currentUrl !== "") revokeObjectURL(currentUrl);
+      currentUrl = "";
+      bc?.close();
+      bc = null;
+      return Promise.resolve();
+    }
+  };
+}
+var EXTERNAL_SRC;
+var init_preview = __esm({
+  "packages/web-container/src/preview.ts"() {
+    "use strict";
+    init_path();
+    EXTERNAL_SRC = /(?:^https?:)?\/\//i;
+  }
+});
+
+// packages/web-container/src/vfs.ts
+init_path();
+var ensureAbs = (path) => path.startsWith("/") ? normalize(path) : `/${normalize(path).replace(/^\/+/, "")}`;
+var ROOT = "/";
+var isRoot = (abs) => abs === ROOT;
+var VirtualFileSystem = class {
+  nodes = /* @__PURE__ */ new Map([[ROOT, { kind: "dir" }]]);
+  /** 挂载一棵目录树（WebContainers `mount` 入参形态）。 */
+  mount(tree) {
+    for (const [name, value] of Object.entries(tree)) {
+      if (!isValidSegment(name)) continue;
+      const dir = `/`;
+      if (typeof value === "string") {
+        this.writeFile(`/${name}`, value);
+      } else if (value === null) {
+        this.mkdir(`/${name}`);
+      } else {
+        this.mkdir(`/${name}`);
+        this.mountWithin(`/${name}`, value);
+      }
+      void dir;
+    }
+  }
+  mountWithin(base, tree) {
+    for (const [name, value] of Object.entries(tree)) {
+      if (!isValidSegment(name)) continue;
+      if (typeof value === "string") this.writeFile(`${base}/${name}`, value);
+      else if (value === null) this.mkdir(`${base}/${name}`);
+      else {
+        this.mkdir(`${base}/${name}`);
+        this.mountWithin(`${base}/${name}`, value);
+      }
+    }
+  }
+  /** 写文件（自动补父目录；`../` 与绝对越界段交由 normalize 折叠）。 */
+  writeFile(path, contents) {
+    const abs = ensureAbs(path);
+    this.ensureParent(abs);
+    this.nodes.set(abs, { kind: "file", contents });
+  }
+  /** 读文件文本；路径是目录或不存在时抛错。 */
+  readFile(path) {
+    const abs = ensureAbs(path);
+    const node = this.nodes.get(abs);
+    if (node === void 0) throw new Error(`ENOENT: \u6587\u4EF6\u4E0D\u5B58\u5728 ${abs}`);
+    if (node.kind !== "file") throw new Error(`EISDIR: ${abs} \u662F\u76EE\u5F55\u4E0D\u662F\u6587\u4EF6`);
+    return node.contents;
+  }
+  /** 是否存在（文件或目录）。 */
+  exists(path) {
+    return this.nodes.has(ensureAbs(path));
+  }
+  /** 是否为目录。 */
+  isDirectory(path) {
+    return this.nodes.get(ensureAbs(path))?.kind === "dir";
+  }
+  /** 创建目录（缺省 recursive，自动补父）。 */
+  mkdir(path, recursive = true) {
+    const abs = ensureAbs(path);
+    if (recursive) this.ensureParent(abs);
+    else if (!isRoot(dirname(abs)) && !this.nodes.has(dirname(abs)))
+      throw new Error(`ENOENT: \u7236\u76EE\u5F55\u4E0D\u5B58\u5728 ${dirname(abs)}`);
+    if (this.nodes.has(abs)) {
+      if (this.nodes.get(abs).kind !== "dir") throw new Error(`EEXIST: ${abs} \u5DF2\u5B58\u5728\u4E14\u4E0D\u662F\u76EE\u5F55`);
+      return;
+    }
+    this.nodes.set(abs, { kind: "dir" });
+  }
+  /** 列目录条目；目录不存在抛错。条目 path 为相对宿主根（POSIX）。 */
+  listDirectory(path) {
+    const abs = isRoot(ensureAbs(path)) ? ROOT : ensureAbs(path);
+    if (!this.exists(abs)) throw new Error(`ENOENT: \u76EE\u5F55\u4E0D\u5B58\u5728 ${abs}`);
+    if (!this.isDirectory(abs)) throw new Error(`ENOTDIR: ${abs} \u4E0D\u662F\u76EE\u5F55`);
+    const prefix = abs === ROOT ? ROOT : `${abs}/`;
+    const names = /* @__PURE__ */ new Set();
+    for (const key of this.nodes.keys()) {
+      if (key === ROOT) continue;
+      if (key.startsWith(prefix)) {
+        const rest = key.slice(prefix.length);
+        if (rest === "" || rest.includes("/")) continue;
+        names.add(rest);
+      }
+    }
+    const parent = abs === ROOT ? "" : abs;
+    const namesToSort = [...names];
+    namesToSort.sort();
+    return namesToSort.map((name) => ({
+      path: `${parent}/${name}`,
+      type: this.nodes.get(`${parent}/${name}`)?.kind === "file" ? "file" : "directory"
+    }));
+  }
+  /** 删除文件（非递归）；不存在抛错。 */
+  deleteFile(path) {
+    const abs = ensureAbs(path);
+    const node = this.nodes.get(abs);
+    if (node === void 0) throw new Error(`ENOENT: \u4E0D\u5B58\u5728 ${abs}`);
+    if (node.kind === "dir") throw new Error(`EISDIR: ${abs} \u662F\u76EE\u5F55\uFF0C\u8BF7\u7528 rm \u9012\u5F52\u5220\u9664`);
+    this.nodes.delete(abs);
+  }
+  /** 递归删除文件或目录。 */
+  rm(path) {
+    const abs = ensureAbs(path);
+    if (!this.nodes.has(abs)) throw new Error(`ENOENT: \u4E0D\u5B58\u5728 ${abs}`);
+    if (this.nodes.get(abs).kind === "file") {
+      this.nodes.delete(abs);
+      return;
+    }
+    const prefix = abs === ROOT ? ROOT : `${abs}/`;
+    for (const key of this.nodes.keys()) {
+      if (key === abs || key.startsWith(prefix)) this.nodes.delete(key);
+    }
+  }
+  /** 移动/重命名（跨目录亦可）；目标父目录须存在。 */
+  move(from, to) {
+    const src = ensureAbs(from);
+    const dst = ensureAbs(to);
+    const node = this.nodes.get(src);
+    if (node === void 0) throw new Error(`ENOENT: \u4E0D\u5B58\u5728 ${src}`);
+    this.ensureParent(dst);
+    if (this.nodes.has(dst)) throw new Error(`EEXIST: \u76EE\u6807\u5DF2\u5B58\u5728 ${dst}`);
+    const renames = [];
+    if (node.kind === "dir") {
+      const prefix = src === ROOT ? ROOT : `${src}/`;
+      for (const key of this.nodes.keys()) {
+        if (key === src) renames.push([src, dst]);
+        else if (key.startsWith(prefix)) renames.push([key, dst + key.slice(src.length)]);
+      }
+    } else {
+      renames.push([src, dst]);
+    }
+    for (const [oldKey, newKey] of renames) {
+      this.nodes.set(newKey, this.nodes.get(oldKey));
+      this.nodes.delete(oldKey);
+    }
+  }
+  /** 复制文件（不复制目录子树；复制目录用 mount。保持一致的最小实现）。 */
+  copyFile(from, to) {
+    const src = ensureAbs(from);
+    const dst = ensureAbs(to);
+    const node = this.nodes.get(src);
+    if (node === void 0) throw new Error(`ENOENT: \u4E0D\u5B58\u5728 ${src}`);
+    if (node.kind !== "file") throw new Error(`EISDIR: ${src} \u662F\u76EE\u5F55\uFF0C\u6682\u4E0D\u652F\u6301\u6574\u76EE\u5F55\u590D\u5236`);
+    this.ensureParent(dst);
+    this.nodes.set(dst, { kind: "file", contents: node.contents });
+  }
+  /** 文件系统树（WebContainers `getFileSystemTree` 对等物）：便于 IDE 渲染目录树。 */
+  getFileSystemTree() {
+    const tree = {};
+    for (const [key, node] of this.nodes) {
+      if (key === ROOT) continue;
+      const names = key.replace(/^\/+/, "").split("/");
+      let cursor = tree;
+      names.forEach((name, index) => {
+        if (index === names.length - 1) {
+          if (node.kind === "file") cursor[name] = node.contents;
+          else cursor[name] = cursor[name] ?? {};
+        } else {
+          const existing = cursor[name];
+          if (existing === null || typeof existing === "string")
+            cursor[name] = typeof existing === "object" && existing !== null ? existing : {};
+          cursor = cursor[name];
+        }
+      });
+    }
+    return tree;
+  }
+  /** 列出兴趣路径的全部路径（用于模块解析 / glob 预载）。 */
+  keys() {
+    return [...this.nodes.keys()].filter((key) => key !== ROOT);
+  }
+  ensureParent(abs) {
+    const parent = dirname(abs);
+    if (isRoot(parent)) return;
+    if (!this.nodes.has(parent)) this.mkdirEnsureRecursive(parent);
+    if (this.nodes.get(parent)?.kind !== "dir")
+      throw new Error(`ENOTDIR: \u7236\u7EA7 ${parent} \u662F\u6587\u4EF6\uFF0C\u65E0\u6CD5\u4F5C\u4E3A\u76EE\u5F55`);
+  }
+  mkdirEnsureRecursive(abs) {
+    const parent = dirname(abs);
+    if (!isRoot(parent)) this.mkdirEnsureRecursive(parent);
+    this.nodes.set(abs, { kind: "dir" });
+  }
+};
+
+// packages/web-container/src/shell.ts
+init_path();
+function tokenize(line) {
+  const tokens = [];
+  let current = "";
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === "'" && !inDouble) inSingle = !inSingle;
+    else if (ch === '"' && !inSingle) inDouble = !inDouble;
+    else if ((ch === " " || ch === "	") && !inSingle && !inDouble) {
+      if (current !== "") {
+        tokens.push(current);
+        current = "";
+      }
+    } else current += ch;
+  }
+  if (current !== "") tokens.push(current);
+  return tokens;
+}
+var newSegment = () => ({
+  argv: [],
+  stdoutRedirect: null,
+  stdoutAppend: false,
+  stderrRedirect: null,
+  link: "end"
+});
+function splitSegments(tokens) {
+  const segments = [];
+  let current = newSegment();
+  const flush = () => {
+    segments.push(current);
+    current = newSegment();
+  };
+  let i = 0;
+  while (i < tokens.length) {
+    const token = tokens[i];
+    if (token === "|") {
+      current.link = "pipe";
+      flush();
+      i++;
+      continue;
+    }
+    if (token === "&&") {
+      current.link = "and";
+      flush();
+      i++;
+      continue;
+    }
+    if (token === ";") {
+      current.link = "seq";
+      flush();
+      i++;
+      continue;
+    }
+    if (token === ">") {
+      current.stdoutRedirect = tokens[i + 1] ?? null;
+      current.stdoutAppend = false;
+      i += 2;
+      continue;
+    }
+    if (token === ">>") {
+      current.stdoutRedirect = tokens[i + 1] ?? null;
+      current.stdoutAppend = true;
+      i += 2;
+      continue;
+    }
+    if (token === "2>") {
+      current.stderrRedirect = tokens[i + 1] ?? null;
+      i += 2;
+      continue;
+    }
+    current.argv.push(token);
+    i++;
+  }
+  flush();
+  return segments;
+}
+function applyRedirect(ctx, output, target, append) {
+  if (target === null) return output;
+  const existing = ctx.vfs.exists(target) ? ctx.vfs.readFile(target) : "";
+  ctx.vfs.writeFile(target, append ? existing + output : output);
+  return "";
+}
+var Shell = class {
+  constructor(ctx) {
+    this.ctx = ctx;
+  }
+  /** 执行一行命令；返回 stdout/stderr 与退出码。 */
+  async execute(line) {
+    const segments = splitSegments(tokenize(line));
+    let pipelineInput = "";
+    let stdout = "";
+    let stderr = "";
+    for (let idx = 0; idx < segments.length; idx++) {
+      const seg = segments[idx];
+      const result = await this.runSegment(seg, pipelineInput);
+      stdout += result.stdout;
+      stderr += result.stderr;
+      const isLast = idx === segments.length - 1;
+      if (isLast) return { code: result.code, stdout, stderr };
+      if (seg.link === "pipe") pipelineInput = result.stdout;
+      else pipelineInput = "";
+      if (result.code !== 0 && seg.link !== "seq") return { code: result.code, stdout, stderr };
+    }
+    return { code: 0, stdout, stderr };
+  }
+  async runSegment(seg, stdin) {
+    const argv = seg.argv;
+    if (argv.length === 0) return { code: 0, stdout: "", stderr: "" };
+    const command = argv[0];
+    let stdout = "";
+    let stderr = "";
+    switch (command) {
+      case "pwd":
+        stdout = `${this.ctx.getCwd()}
+`;
+        break;
+      case "ls":
+        stdout = `${this.ls(argv.slice(1)).join("\n")}${this.ls(argv.slice(1)).length ? "\n" : ""}`;
+        break;
+      case "echo":
+        stdout = `${argv.slice(1).join(" ")}
+`;
+        break;
+      case "cat": {
+        const files = argv.slice(1);
+        if (files.length === 0) stdout = stdin;
+        else for (const file of files) stdout += `${this.ctx.vfs.readFile(this.resolve(file))}
+`;
+        break;
+      }
+      case "mkdir":
+        for (const dir of argv.slice(1)) this.ctx.vfs.mkdir(this.resolve(dir));
+        break;
+      case "touch":
+        for (const file of argv.slice(1)) {
+          const target = this.resolve(file);
+          if (!this.ctx.vfs.exists(target)) this.ctx.vfs.writeFile(target, "");
+        }
+        break;
+      case "rm": {
+        for (const file of argv.slice(1)) {
+          if (file === "-r" || file === "-rf") continue;
+          this.ctx.vfs.rm(this.resolve(file));
+        }
+        break;
+      }
+      case "rmdir":
+        for (const file of argv.slice(1)) this.ctx.vfs.deleteFile(this.resolve(file));
+        break;
+      case "cp": {
+        const [from, to] = argv.slice(1);
+        this.ctx.vfs.copyFile(this.resolve(from ?? ""), this.resolve(to ?? ""));
+        break;
+      }
+      case "mv": {
+        const [from, to] = argv.slice(1);
+        this.ctx.vfs.move(this.resolve(from ?? ""), this.resolve(to ?? ""));
+        break;
+      }
+      case "cd": {
+        const target = argv[1] ?? "/";
+        if (!this.ctx.vfs.isDirectory(this.resolve(target)))
+          return { code: 1, stdout: "", stderr: `cd: \u4E0D\u662F\u76EE\u5F55: ${target}` };
+        this.ctx.setCwd(this.resolve(target));
+        break;
+      }
+      case "head": {
+        const lines = stdin !== "" ? stdin.split("\n") : this.ctx.vfs.readFile(this.resolve(argv[1] ?? "")).split("\n");
+        stdout = `${lines.slice(0, argv.includes("-n") ? Number(argv[argv.indexOf("-n") + 1]) : 10).join("\n")}${"\n"}`;
+        break;
+      }
+      case "tail": {
+        const lines = stdin !== "" ? stdin.split("\n") : this.ctx.vfs.readFile(this.resolve(argv[1] ?? "")).split("\n");
+        const n = argv.includes("-n") ? Number(argv[argv.indexOf("-n") + 1]) : 10;
+        stdout = `${lines.slice(-n).join("\n")}${"\n"}`;
+        break;
+      }
+      case "help":
+        stdout = "\u5185\u5EFA\u547D\u4EE4\uFF1Apwd ls cat echo mkdir touch rm rmdir cp mv cd head tail node js\uFF08\u652F\u6301 > >> 2> \u4E0E |\uFF09\n";
+        break;
+      case "node":
+      case "js": {
+        if (this.ctx.runtime === void 0)
+          return {
+            code: 1,
+            stdout: "",
+            stderr: "node: \u672A\u6CE8\u5165 JS \u8FD0\u884C\u65F6\uFF08\u6D4F\u89C8\u5668\u7AEF\u9700\u63D0\u4F9B QuickJS WASM \u9002\u914D\uFF09"
+          };
+        try {
+          stdout = `${await this.ctx.runtime.run(this.resolve(argv[1] ?? "index.js"), argv.slice(2), this.ctx.getCwd())}${"\n"}`;
+        } catch (error) {
+          stderr = `${error instanceof Error ? error.message : String(error)}
+`;
+          break;
+        }
+        break;
+      }
+      default:
+        stderr = `${command}: command not found
+`;
+        return { code: 127, stdout: "", stderr };
+    }
+    stdout = applyRedirect(this.ctx, stdout, seg.stdoutRedirect, seg.stdoutAppend);
+    if (seg.stderrRedirect !== null) {
+      this.ctx.vfs.writeFile(this.resolve(seg.stderrRedirect), stderr);
+      stderr = "";
+    }
+    return { code: 0, stdout, stderr };
+  }
+  ls(args) {
+    const dirs = args.length ? args.filter((a) => !a.startsWith("-")) : ["."];
+    const out = [];
+    for (const dir of dirs) {
+      const entries = this.ctx.vfs.listDirectory(this.resolve(dir));
+      for (const entry of entries)
+        out.push(`${entry.type === "directory" ? "d " : "- "}${entry.path}`);
+    }
+    return out;
+  }
+  /** 相对 cwd 解析为绝对路径（VFS key）。 */
+  resolve(target) {
+    if (target.startsWith("/")) return target.replace(/\/+/g, "/");
+    return join(this.ctx.getCwd(), target);
+  }
+};
+
+// packages/web-container/src/npm-client.ts
+var defaultFetch = (url, init) => globalThis.fetch(url, init).then((res) => res);
+function parseSpec(spec) {
+  if (spec.startsWith("@")) {
+    const at2 = spec.indexOf("@", 1);
+    if (at2 === -1) return { name: spec };
+    return { name: spec.slice(0, at2), spec: spec.slice(at2 + 1) };
+  }
+  const at = spec.indexOf("@");
+  if (at === -1) return { name: spec };
+  return { name: spec.slice(0, at), spec: spec.slice(at + 1) };
+}
+var readBinary = async (res) => {
+  const buf = await res.arrayBuffer();
+  return new Uint8Array(buf);
+};
+function createNpmClient(options) {
+  const fetchImpl = options.fetchImpl ?? defaultFetch;
+  const base = options.baseUrl.replace(/\/+$/, "");
+  const storage = options.storage;
+  return {
+    async registries() {
+      const res = await fetchImpl(`${base}/registry`);
+      if (!res.ok) throw new Error(`\u83B7\u53D6 registry \u5217\u8868\u5931\u8D25\uFF1AHTTP ${res.status}`);
+      const body = await res.json();
+      return body.registries;
+    },
+    async install(specArg) {
+      const { name, spec } = parseSpec(specArg);
+      const params = new URLSearchParams({ name });
+      if (spec !== void 0) params.set("spec", spec);
+      const resolveRes = await fetchImpl(`${base}/package?${params.toString()}`);
+      if (!resolveRes.ok)
+        throw new Error(`\u89E3\u6790\u5305\u5931\u8D25 ${name}@${spec ?? "latest"}\uFF1AHTTP ${resolveRes.status}`);
+      const meta = await resolveRes.json();
+      const tarballPath = `.adep-cache/${meta.name.replaceAll("/", "__")}-${meta.version}.tgz`;
+      if (storage.exists(tarballPath)) {
+        return { ...meta, tarballPath, downloaded: false };
+      }
+      const tarballRes = await fetchImpl(
+        `${base}/tarball?${new URLSearchParams({ name: meta.name, version: meta.version }).toString()}`
+      );
+      if (!tarballRes.ok)
+        throw new Error(`\u4E0B\u8F7D tarball \u5931\u8D25 ${meta.name}@${meta.version}\uFF1AHTTP ${tarballRes.status}`);
+      const bytes = await readBinary(tarballRes);
+      storage.writeFile(tarballPath, new TextDecoder("utf-8", { fatal: false }).decode(bytes));
+      return { ...meta, tarballPath, downloaded: true };
+    }
+  };
+}
+
+// packages/web-container/src/worker-runtime.ts
+async function evaluateSource(source, filename, args) {
+  const output = [];
+  const fakeConsole = {
+    log: (...parts) => output.push(parts.map((p) => String(p)).join(" ")),
+    error: (...parts) => output.push(parts.map((p) => String(p)).join(" ")),
+    warn: (...parts) => output.push(parts.map((p) => String(p)).join(" "))
+  };
+  const sandbox = {
+    console: fakeConsole,
+    Math,
+    JSON,
+    Date,
+    __args: [...args],
+    __filename: filename
+  };
+  const fn = new Function(
+    "sandbox",
+    "with (sandbox) { return (async function(){ " + source + "\n })(); }"
+  );
+  const result = await fn(sandbox);
+  if (result !== void 0) output.push(String(result));
+  return output.join("\n");
+}
+var WORKER_SCRIPT = (
+  /* javascript */
+  `
+const evaluate = async (source, filename, args) => {
+  const output = []
+  const fakeConsole = {
+    log: (...parts) => output.push(parts.map((p) => String(p)).join(' ')),
+    error: (...parts) => output.push(parts.map((p) => String(p)).join(' ')),
+    warn: (...parts) => output.push(parts.map((p) => String(p)).join(' ')),
+  }
+  const sandbox = { console: fakeConsole, Math, JSON, Date, __args: [...args], __filename: filename }
+  const fn = new Function('sandbox', 'with (sandbox) { return (async function(){ ' + source + '\\n })(); }')
+  const result = await fn(sandbox)
+  if (result !== undefined) output.push(String(result))
+  return output.join('\\n')
+}
+self.onmessage = async (event) => {
+  const { id, source, filename, args } = event.data
+  try {
+    const output = await evaluate(source, filename, args)
+    self.postMessage({ id, output })
+  } catch (error) {
+    self.postMessage({ id, error: error && error.message ? error.message : String(error) })
+  }
+}
+`
+);
+function createWorkerRuntime(vfs, options = {}) {
+  const workerFactory = options.workerFactory ?? ((url) => new Worker(url));
+  const scriptUrl = options.workerFactory === void 0 ? URL.createObjectURL(new Blob([WORKER_SCRIPT], { type: "application/javascript" })) : "";
+  const worker = workerFactory(scriptUrl);
+  const pending = /* @__PURE__ */ new Map();
+  let seq = 0;
+  worker.onmessage = (event) => {
+    const msg = event.data;
+    const task = pending.get(msg.id);
+    if (task === void 0) return;
+    pending.delete(msg.id);
+    if (msg.error !== void 0) task.reject(new Error(msg.error));
+    else task.resolve(msg.output ?? "");
+  };
+  worker.onerror = (event) => {
+    const reason = event.message ?? "worker error";
+    for (const [, task] of pending) task.reject(new Error(reason));
+    pending.clear();
+  };
+  return {
+    async run(file, args, _cwd) {
+      const source = vfs.readFile(file);
+      const id = seq++;
+      return new Promise((resolve, reject) => {
+        pending.set(id, { resolve, reject });
+        worker.postMessage({ id, source, filename: file, args: [...args] });
+      });
+    },
+    close() {
+      pending.clear();
+      worker.terminate();
+      if (options.cleanup !== false && scriptUrl !== "") URL.revokeObjectURL(scriptUrl);
+    }
+  };
+}
+
+// packages/web-container/src/container.ts
+function bootstrap(options) {
+  const vfs = new VirtualFileSystem();
+  if (options.initialTree !== void 0) vfs.mount(options.initialTree);
+  let cwd = "/";
+  const setCwd = (path) => {
+    cwd = path;
+  };
+  const defaultRuntime = typeof Worker !== "undefined" ? createWorkerRuntime(vfs) : void 0;
+  const runtime = options.runtime ?? defaultRuntime;
+  const shell = new Shell({
+    vfs,
+    getCwd: () => cwd,
+    setCwd,
+    ...runtime === void 0 ? {} : { runtime }
+  });
+  const npmClient = createNpmClient({
+    baseUrl: options.npmRelayBaseUrl,
+    storage: vfs,
+    ...options.fetchImpl === void 0 ? {} : { fetchImpl: options.fetchImpl }
+  });
+  const listeners = /* @__PURE__ */ new Map();
+  const emit = (event, payload) => {
+    const set = listeners.get(event);
+    if (set === void 0) return;
+    for (const fn of set) fn(payload);
+  };
+  let preview = null;
+  const buildProcess = (cmdLine) => {
+    let outputController;
+    const output = new ReadableStream({
+      start(c) {
+        outputController = c;
+      }
+    });
+    const input = new WritableStream({ write() {
+    } });
+    let resolveExit;
+    const exit = new Promise((resolve) => {
+      resolveExit = resolve;
+    });
+    const proc = { exit, input, output, stderr: output };
+    const encoder = new TextEncoder();
+    const writeAll = (text) => {
+      outputController.enqueue(encoder.encode(text));
+    };
+    emit("process", { pty: proc, event: "start" });
+    (async () => {
+      try {
+        const result = await shell.execute(cmdLine);
+        if (result.stdout !== "") writeAll(result.stdout);
+        if (result.stderr !== "") writeAll(result.stderr);
+        outputController.close();
+        emit("process", { pty: proc, event: "exit", code: result.code });
+        resolveExit(result.code);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        writeAll(message);
+        outputController.close();
+        emit("process", { pty: proc, event: "error", error });
+        resolveExit(1);
+      }
+    })();
+    return proc;
+  };
+  return {
+    async mount(tree) {
+      vfs.mount(tree);
+      preview?.touch("/");
+    },
+    async writeFile(path, contents) {
+      vfs.writeFile(path, contents);
+      preview?.touch(path);
+    },
+    async readFile(path) {
+      return vfs.readFile(path);
+    },
+    async listDirectory(path) {
+      return vfs.listDirectory(path);
+    },
+    async createDirectory(path, recursive = true) {
+      vfs.mkdir(path, recursive);
+    },
+    async deleteFile(path) {
+      vfs.rm(path);
+      preview?.touch(path);
+    },
+    async exists(path) {
+      return vfs.exists(path);
+    },
+    spawn(command, args) {
+      const cmdLine = [command, ...args ?? []].join(" ");
+      return buildProcess(cmdLine);
+    },
+    async run(command, args, opts) {
+      const proc = this.spawn(command, args, opts);
+      await proc.exit;
+      const reader = proc.output.getReader();
+      const chunks = [];
+      for (; ; ) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        chunks.push(new TextDecoder().decode(value));
+      }
+      return chunks.join("");
+    },
+    on(event, callback) {
+      const set = listeners.get(event) ?? /* @__PURE__ */ new Set();
+      set.add(callback);
+      listeners.set(event, set);
+    },
+    off(event, callback) {
+      const set = listeners.get(event);
+      set?.delete(callback);
+    },
+    async install(spec) {
+      emit("installprogress", { kind: "start", spec });
+      try {
+        await npmClient.install(spec);
+        emit("installprogress", { kind: "complete", spec });
+      } catch (error) {
+        emit("installprogress", {
+          kind: "fail",
+          spec,
+          message: error instanceof Error ? error.message : String(error)
+        });
+        throw error;
+      }
+    },
+    async registries() {
+      return npmClient.registries();
+    },
+    async preview(previewOptions) {
+      if (preview === null) {
+        const { createPreviewServer: createPreviewServer2 } = await Promise.resolve().then(() => (init_preview(), preview_exports));
+        preview = createPreviewServer2(vfs, previewOptions);
+        emit("serverready", { port: preview.port, url: preview.url });
+      }
+      return { url: preview.url, port: preview.port };
+    },
+    async close() {
+      listeners.clear();
+      defaultRuntime?.close?.();
+      await preview?.stop();
+      preview = null;
+    }
+  };
+}
+
+// packages/web-container/src/index.ts
+init_path();
+export {
+  Shell,
+  VirtualFileSystem,
+  bootstrap,
+  createNpmClient,
+  createWorkerRuntime,
+  evaluateSource,
+  parseSpec,
+  path_exports as posix
+};

package/dist/npm-client.d.ts

@@ -0,0 +1,38 @@
+/**
+ * npm 客户端（FN-012 对外 SDK）：经平台 `/npm-relay/*` 中继取真实 registry 依赖。
+ *
+ * 浏览器虚拟系统无法直连 npm registry（跨域）→ 全部请求走平台中继；
+ * tarball 下载后写入虚拟文件系统 `.adep-cache/<name>-<version>.tgz`（本地离线复用，
+ * 与中继的「元数据 + tarball 双层缓存」呼应；完整解包到 node_modules 属后续增强）。
+ */
+import type { CloudFetch } from '@adep/types';
+export interface NpmPersistence {
+    exists(path: string): boolean;
+    writeFile(path: string, contents: string): void;
+}
+export interface NpmClientOptions {
+    /** 平台 npm 中继基础路径（如 `/api/v1/npm-relay`；相对绝对均可）。 */
+    baseUrl: string;
+    /** 本地 tarball 落盘（写虚拟文件系统）。 */
+    storage: NpmPersistence;
+    /** 网络实现（缺省 globalThis.fetch）。 */
+    fetchImpl?: CloudFetch;
+}
+export interface NpmInstallResult {
+    name: string;
+    version: string;
+    distTags: string[];
+    /** 本地缓存 tarball 的 VFS 路径。 */
+    tarballPath: string;
+    /** 本次是否发生了真实下载（false = 本地缓存命中）。 */
+    downloaded: boolean;
+}
+/** 解析 `name` 或 `name@spec` 到 { name, spec? }（含 scoped 包）。 */
+export declare function parseSpec(spec: string): {
+    name: string;
+    spec?: string;
+};
+export declare function createNpmClient(options: NpmClientOptions): {
+    registries(): Promise<string[]>;
+    install(spec: string): Promise<NpmInstallResult>;
+};

package/dist/path.d.ts

@@ -0,0 +1,21 @@
+/**
+ * POSIX 路径工具（虚拟文件系统的路径语义）。
+ *
+ * 与 `node:path` 的 posix 行为保持一致，但**零运行时依赖**、浏览器可跑
+ * （virtual fs 由浏览器原生开发环境与 Node 单测共用，禁止 import node 内建模块）。
+ */
+export declare const SEP = "/";
+/** 规范化路径：折叠 `.`、`..`，拒绝绝对路径（VF 根固定 `/`，入参一律相对根）。 */
+export declare function normalize(path: string): string;
+/** 判断是否绝对路径（以 `/` 开头）。虚拟系统根为 `/`。 */
+export declare function isAbsolute(path: string): boolean;
+/** 把相对路径接在给定基础路径后（基础不必已规范化）。 */
+export declare function join(base: string, ...paths: string[]): string;
+/** 返回父目录（根目录的父是根）。 */
+export declare function dirname(path: string): string;
+/** 返回末级文件名。 */
+export declare function basename(path: string): string;
+/** 返回扩展名（含点；无扩展名返回空串）。 */
+export declare function extname(path: string): string;
+/** 把 `/` 分隔的字符串当作单一段（用于校验段名，禁止空段与 `..` 穿越）。 */
+export declare function isValidSegment(name: string): boolean;

package/dist/preview.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 浏览器原生开发环境的「dev server 内联预览 + HMR」（FN-012 Scenario 1 / 验收 5）。
+ *
+ * 真实浏览器里没有 Node / Vite 运行时，预习用「虚拟静态 dev server」实现（全程浏览器内、
+ * 零依赖、无需本机运行时）：
+ * - serve 时把入口 HTML 里的**本地**资源（`<script src>` / `<link rel=stylesheet>`）内联进文档，
+ *   生成一份自包含的 blob URL 文档——等价于 dev build 的静态输出，可被 `<iframe>` 直接预览；
+ * - 内联后注入一段 HMR 接收脚本：订阅稳定名的 `BroadcastChannel`，收到 `{type:'update', url}` 时
+ *   `location.replace(url)` 自刷新。SDK 侧在文件变更时重取文档、比对 hash，内容变才广播新 URL；
+ * - 对外经 `serverready` 事件暴露 `{ port, url }`（`port` 为虚拟端口号）。
+ *
+ * 边界（与 task 超出范围相称）：不跑真实的 Vite/TS 编译管道，只贴原位静态资源；`type=module`
+ * 脚本与外部 URL 原样保留不内联。需要全量编译时替换为真正的 WASM/Vite pipeline（接口可替换）。
+ */
+import type { VirtualFileSystem } from './vfs';
+import type { PreviewServerOptions as PreviewServerOptionsContract } from '@adep/types';
+export interface PreviewServerOptions extends PreviewServerOptionsContract {
+    /** blob URL 工厂（Node 无 `URL.createObjectURL`，单测注入假实现）。 */
+    createObjectURL?: (blob: Blob) => string;
+    revokeObjectURL?: (url: string) => void;
+}
+export interface PreviewDocumentOptions {
+    cwd: string;
+    entry: string;
+    /** HMR 通道名（同一 preview 实例内稳定，文档与主线程共享）。 */
+    channelName: string;
+}
+/** 服务结果：`url` 为当前文档 blob URL，`changed` 标记与上次是否不同。 */
+export interface PreviewServeResult {
+    url: string;
+    changed: boolean;
+}
+/** dev server 句柄：向容器暴露 `url` / `port`，变更经 `touch` 广播 HMR。 */
+export interface PreviewServer {
+    readonly url: string;
+    readonly port: number;
+    /** 某路径发生变更：重取文档，内容变则广播新 URL 驱动预览自刷新（HMR）。 */
+    touch(path: string): void;
+    /** 关闭：撤销 URL、关闭 HMR 通道。 */
+    stop(): Promise<void>;
+}
+/**
+ * 把入口 HTML 里的本地 `<script src>` / `<link rel=stylesheet>` 内联为内嵌内容（纯函数，Node 可测）。
+ * `type="module"` 脚本与外部 URL 一律保持原样，避免破坏 import 语义。
+ */
+export declare function inlineAssets(html: string, vfs: VirtualFileSystem, baseDir: string): string;
+/** 组装最终预览文档：读入口 → 内联本地资源 → 注入 HMR 接收脚本。纯函数，Node 可测。 */
+export declare function buildPreviewDocument(vfs: VirtualFileSystem, options: PreviewDocumentOptions): string;
+/** 创建虚拟静态 dev server：`serve`+`touch` 驱动 blob 文档与 HMR 广播。 */
+export declare function createPreviewServer(vfs: VirtualFileSystem, options?: PreviewServerOptions): PreviewServer;

package/dist/shell.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shell（FN-012 对外 SDK）：UNIX-like 命令解析与执行。
+ *
+ * 解析器支持：双引号/单引号、空格分隔、`>`/`>>` 输出重定向、`|` 管道（内置命令之间）。
+ * 每个内置命令对 `VirtualFileSystem` 操作；`node <file>` / `js <file>` 走注入的 JS 运行时适配。
+ * 输出以 `stdout` / `stderr` 分通道收集，供上层包装成 WebContainerProcess 双工流。
+ *
+ * 浏览器可跑（零 node 依赖），`runtime` 为可替换适配（QuickJS WASM / Node vm）。
+ */
+import type { VirtualFileSystem } from './vfs';
+/** JS 运行时适配接口：能加载并执行一段 JS 模块（QuickJS WASM / Web Worker 沙箱 / Node vm 等实现）。 */
+export interface JsRuntime {
+    /** 执行脚本文件，返回标准输出文本；实现抛错时以 `stderr` 语义上报。 */
+    run(file: string, args: readonly string[], cwd: string): Promise<string>;
+    /** 释放运行时常驻的线程/句柄（如浏览器 Worker）。未定义表示无需清理（如 vm 单次求值）。 */
+    close?(): void;
+}
+export interface ShellResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export interface ShellCtx {
+    vfs: VirtualFileSystem;
+    getCwd(): string;
+    setCwd(path: string): void;
+    runtime?: JsRuntime;
+}
+export declare class Shell {
+    private readonly ctx;
+    constructor(ctx: ShellCtx);
+    /** 执行一行命令；返回 stdout/stderr 与退出码。 */
+    execute(line: string): Promise<ShellResult>;
+    private runSegment;
+    private ls;
+    /** 相对 cwd 解析为绝对路径（VFS key）。 */
+    private resolve;
+}
+/** 构造一个在给定 VFS 上、cwd 为根 `/` 的 shell。 */
+export declare function createShell(vfs: VirtualFileSystem, runtime?: JsRuntime): {
+    shell: Shell;
+    getCwd(): string;
+    setCwd(path: string): void;
+};

package/dist/vfs.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 虚拟文件系统（FN-012 浏览器原生开发环境 / 对外 SDK 核心）。
+ *
+ * 对标 WebContainers `mount` / `writeFile` / `readFile` / `listDirectory` / `deleteFile`。
+ * 实现为**内存中的 dict**，key 一律是**以 `/` 开头的规范化绝对路径**（`/src/index.ts`），
+ * 目录与文件共享同一 key 空间（`dir` vs `file` 二元自描述），枚举靠前缀扫描。
+ *
+ * 浏览器可跑（零 node 依赖）；`mount(tree)` 递归建目录、`writeFile` 自动补父目录、
+ * `move`/`rm` 支持递归。持久化由上层（IndexedDB / 平台 ST-001）负责，本类只管内存态。
+ */
+import { basename } from './path';
+import type { WebContainerDirectoryTree, WebContainerFsEntry } from '@adep/types';
+/** 根目录的规范化形态。 */
+export declare const ROOT = "/";
+export declare class VirtualFileSystem {
+    private readonly nodes;
+    /** 挂载一棵目录树（WebContainers `mount` 入参形态）。 */
+    mount(tree: WebContainerDirectoryTree): void;
+    private mountWithin;
+    /** 写文件（自动补父目录；`../` 与绝对越界段交由 normalize 折叠）。 */
+    writeFile(path: string, contents: string): void;
+    /** 读文件文本；路径是目录或不存在时抛错。 */
+    readFile(path: string): string;
+    /** 是否存在（文件或目录）。 */
+    exists(path: string): boolean;
+    /** 是否为目录。 */
+    isDirectory(path: string): boolean;
+    /** 创建目录（缺省 recursive，自动补父）。 */
+    mkdir(path: string, recursive?: boolean): void;
+    /** 列目录条目；目录不存在抛错。条目 path 为相对宿主根（POSIX）。 */
+    listDirectory(path: string): WebContainerFsEntry[];
+    /** 删除文件（非递归）；不存在抛错。 */
+    deleteFile(path: string): void;
+    /** 递归删除文件或目录。 */
+    rm(path: string): void;
+    /** 移动/重命名（跨目录亦可）；目标父目录须存在。 */
+    move(from: string, to: string): void;
+    /** 复制文件（不复制目录子树；复制目录用 mount。保持一致的最小实现）。 */
+    copyFile(from: string, to: string): void;
+    /** 文件系统树（WebContainers `getFileSystemTree` 对等物）：便于 IDE 渲染目录树。 */
+    getFileSystemTree(): WebContainerDirectoryTree;
+    /** 列出兴趣路径的全部路径（用于模块解析 / glob 预载）。 */
+    keys(): string[];
+    private ensureParent;
+    private mkdirEnsureRecursive;
+}
+export type { WebContainerDirectoryTree };
+export { basename };

package/dist/worker-runtime.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 浏览器端 JS 运行时适配（FN-012 验收 2）：Web Worker 沙箱执行，零 WASM 依赖、可替换。
+ *
+ * `vm.ts` 是 Node-only（import `node:vm`），浏览器端没有 node:vm。本模块用浏览器自己的
+ * V8 引擎，在一个 `blob:` URL 内联 Worker 里执行 JS——Worker 与主线程隔离（无 DOM、无
+ * 主线程全局）、独立 global，作为对外 SDK `JsRuntime` 的浏览器实现。执行逻辑与 OW
+ * 上游同款契约：读取 VFS 文件 → 隔离上下文求值 → 捕获 console 输出 → 返回 stdout 文本，
+ * 可整体替换为 QuickJS WASM 实现（`JsRuntime` 只暴露一个 `run` 方法）。
+ *
+ * 包形态与 vm.ts 对称：vm.ts 仅在 Node 加载（不进浏览器包），本模块可在浏览器 / Node 双跑
+ * （Node 下 `Worker` 全局由 options.workerFactory 注入，供单测驱动消息协议）。
+ */
+import type { VirtualFileSystem } from './vfs';
+import type { JsRuntime } from './shell';
+/** 主线程 → Worker 的求值请求。 */
+interface WorkerRequest {
+    id: number;
+    source: string;
+    filename: string;
+    args: readonly string[];
+}
+/** Worker → 主线程的求值结果。 */
+export interface WorkerResponse {
+    id: number;
+    output?: string;
+    error?: string;
+}
+/** 隔离上下文求值：等价于 vm.ts 的 IFFE 包装，但跑在浏览器任意全局（Node 测试 / Worker 共用）。 */
+export declare function evaluateSource(source: string, filename: string, args: readonly string[]): Promise<string>;
+/** 极简 Worker 形态（鸭子类型：Node 测试注入假 Worker 走同一协议）。 */
+export interface WorkerLike {
+    postMessage(message: WorkerRequest): void;
+    onmessage: ((event: MessageEvent<WorkerResponse>) => void) | null;
+    onerror: ((event: ErrorEvent) => void) | null;
+    terminate(): void;
+}
+export interface WorkerRuntimeOptions {
+    /** Worker 构造函数（缺省 `new Worker(blobUrl)`；Node 单测注入假 Worker）。 */
+    workerFactory?: (scriptUrl: string) => WorkerLike;
+    /** 是否在 close 时 terminate Worker。缺省 true。 */
+    cleanup?: boolean;
+}
+/**
+ * 在浏览器内执行 JS 的 `JsRuntime` 实现：读 VFS 文件 → 交给 Worker 沙箱求值 → 返回 stdout。
+ * `node <file>` / `js <file>` 内建命令经此在**浏览器**内（而非服务端沙箱）跑用户代码。
+ */
+export declare function createWorkerRuntime(vfs: VirtualFileSystem, options?: WorkerRuntimeOptions): JsRuntime;
+export {};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@adep/web-container",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "description": "adep 平台浏览器原生开发环境对外 SDK（FN-012）：虚拟文件系统 + 进程/shell + JS 运行时适配接口 + npm-relay 客户端，对标 WebContainers API，Node 可测、浏览器可跑。",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "build": "bun run ../../scripts/build-package.ts web-container",
+    "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:*"
+  },
+  "publishConfig": {
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "./*": {
+        "types": "./dist/*.d.ts",
+        "default": "./dist/*.js"
+      }
+    }
+  }
+}