From ed6630bb2d593701f1f3bc542f4f5eeebf4f9ccb Mon Sep 17 00:00:00 2001
From: probe <probe@local>
Date: Sun, 4 Oct 2026 08:33:37 +0800
Subject: [PATCH 01/21] feat(webui): add a workspace file resource route and
 the F-zone contracts

The workspace panel needs media and HTML preview, and neither can work
through the JSON request path: `<video>`/`<audio>` cannot scrub a progress
bar without `Range`, and base64 inlining inflates every response that merely
mentions the file.

- `GET /workspace-file` serves one workspace file with Range support. It is
  dispatched after the loopback, origin and per-start token checks rather
  than around them, so it inherits the access control described in ADR 0004
  instead of re-implementing it.
- Path validation resolves against `dir` and rejects whatever escapes it,
  including the sibling-prefix case that survives `..` collapsing (`/repo-evil`
  against root `/repo`).
- Workspace media types are whitelisted with an `application/octet-stream`
  floor. This deliberately does not reuse `contentType()`: an unrecognised
  asset in the WebUI bundle really is best guessed as HTML and guessing wrong
  there is inert, whereas the guessed file here is the agent's working tree.
- Responses carry `sandbox` CSP, and HTML gets `sandbox allow-scripts`: a
  previewed artifact runs, but in an opaque origin where its script cannot
  read `window.__WEBUI_CONFIG__.token` off the page that framed it.
- Contract for the F zone: `size`/`modifiedAt` on `WebuiWorkspaceFile`, plus
  archive listing and extraction. `host.ts` reports the archive capability as
  unavailable by message rather than a bare `!`, so a runtime without it
  produces something the panel can display instead of a TypeError.

Baseline unchanged: 958 tests pass, typecheck:server and typecheck:client clean.
---
 packages/webui/src/server/host.ts    |  19 +++
 packages/webui/src/server/port.ts    |  42 +++++++
 packages/webui/src/server/service.ts | 178 ++++++++++++++++++++++++++-
 3 files changed, 238 insertions(+), 1 deletion(-)

diff --git a/packages/webui/src/server/host.ts b/packages/webui/src/server/host.ts
index 919d5288c..18cc83442 100644
--- a/packages/webui/src/server/host.ts
+++ b/packages/webui/src/server/host.ts
@@ -38,6 +38,8 @@ import type {
   WebuiQueueItem,
   WebuiWorkspaceFile,
   WebuiWorkspaceFileContent,
+  WebuiWorkspaceArchiveListing,
+  WebuiWorkspaceArchiveExtractResult,
   WebuiWorkspaceEnvironment,
   WebuiWorkspaceGitMutationRequest,
   WebuiWorkspaceReviewDiffs,
@@ -165,6 +167,8 @@ export interface WebuiRuntimeCliService {
   listWorkspaceFileTree?(request: { readonly workspaceDir: string; readonly path?: string }): Promise<readonly WebuiWorkspaceFile[]>;
   readWorkspaceFile?(request: { readonly workspaceDir: string; readonly path: string }): Promise<WebuiWorkspaceFileContent>;
   searchWorkspaceFiles?(input: { readonly workspaceDir: string; readonly query: string; readonly limit: number }): Promise<readonly string[]>;
+  readWorkspaceArchive?(request: { readonly workspaceDir: string; readonly path: string; readonly prefix?: string }): Promise<WebuiWorkspaceArchiveListing>;
+  extractWorkspaceArchive?(request: { readonly workspaceDir: string; readonly path: string; readonly destination: string; readonly prefix?: string }): Promise<WebuiWorkspaceArchiveExtractResult>;
   getWorkspaceGitEnvironment?(workspaceDir: string): Promise<{ readonly metadata: Record<string, unknown>; readonly changes: Record<string, unknown> }>;
   mutateWorkspaceGit?(request: WebuiWorkspaceGitMutationRequest): Promise<Record<string, unknown>>;
   getWorkspaceReviewSummary?(workspaceDir: string): Promise<WebuiWorkspaceReviewSummary>;
@@ -420,6 +424,21 @@ export function createHarnessPortFromHost(
     async listWorkspaceFileTree(request) {
       return requireCliService(host).listWorkspaceFileTree!(request) as Promise<readonly WebuiWorkspaceFile[]>;
     },
+    // Checked rather than asserted: the siblings above use `!` because their
+    // runtime capability has shipped, but archive reading and extraction are
+    // landing with the workspace-panel work, and a bare `!` here would turn a
+    // missing capability into `undefined is not a function` at call time
+    // instead of a message the panel can show.
+    async readWorkspaceArchive(request) {
+      const cliService = requireCliService(host);
+      if (!cliService.readWorkspaceArchive) throw new Error("压缩包浏览能力尚未接入。");
+      return cliService.readWorkspaceArchive(request);
+    },
+    async extractWorkspaceArchive(request) {
+      const cliService = requireCliService(host);
+      if (!cliService.extractWorkspaceArchive) throw new Error("压缩包解压能力尚未接入。");
+      return cliService.extractWorkspaceArchive(request);
+    },
     async readWorkspaceFile(request) {
       const cliService = requireCliService(host);
       const result = await cliService.readWorkspaceFile!(request) as WebuiWorkspaceFileContent;
diff --git a/packages/webui/src/server/port.ts b/packages/webui/src/server/port.ts
index 4a7f16ec7..021994c71 100644
--- a/packages/webui/src/server/port.ts
+++ b/packages/webui/src/server/port.ts
@@ -410,6 +410,10 @@ export interface WebuiWorkspaceFile {
   readonly path: string;
   readonly name: string;
   readonly type?: string;
+  /** Bytes. Absent for directories and for runtimes that do not stat. */
+  readonly size?: number;
+  /** Epoch milliseconds of the last modification. Same absence rule as `size`. */
+  readonly modifiedAt?: number;
   readonly children?: readonly WebuiWorkspaceFile[];
 }
 
@@ -427,6 +431,37 @@ export interface WebuiWorkspaceDirectoryEntry {
   readonly path: string;
 }
 
+/**
+ * One entry inside an archive listed by `readWorkspaceArchive`. `path` is
+ * the archive-internal POSIX path, never a host path: nothing in this shape
+ * may be handed to the filesystem without re-validating it against the
+ * extraction root.
+ */
+export interface WebuiArchiveEntry {
+  readonly path: string;
+  readonly name: string;
+  readonly isDirectory: boolean;
+  readonly size?: number;
+}
+
+export interface WebuiWorkspaceArchiveListing {
+  readonly archivePath: string;
+  /** Only the entries directly under `prefix`, or under the archive root. */
+  readonly entries: readonly WebuiArchiveEntry[];
+  /** Total entries in the archive, which may exceed `entries.length`. */
+  readonly totalEntries: number;
+  /** True when the listing was cut off before covering the whole archive. */
+  readonly truncated: boolean;
+}
+
+export interface WebuiWorkspaceArchiveExtractResult {
+  readonly archivePath: string;
+  readonly destination: string;
+  readonly writtenFiles: number;
+  /** Set when the archive carried more entries than the hard ceiling allows. */
+  readonly truncated?: boolean;
+}
+
 /**
  * One level of the local directory tree, for the composer's project
  * picker. A browser cannot hand the WebUI an absolute path — the File
@@ -822,6 +857,13 @@ export interface WebuiHarnessPort {
   searchWorkspaceReviewDiffs(request: { readonly workspaceDir: string; readonly reviewSnapshotId: string; readonly query: string; readonly includeUntrackedFiles: boolean; readonly pageIndex?: number; readonly pageSize?: number }): Promise<WebuiWorkspaceReviewSearchResult>;
   readCanvas(request: { readonly sessionId: string }): Promise<WebuiCanvasDocument>;
   applyCanvas(request: { readonly sessionId: string; readonly operation: Record<string, unknown> }): Promise<{ readonly operationId: string; readonly document: WebuiCanvasDocument }>;
+  /**
+   * Archive listing for the workspace panel. The runtime owns every
+   * hardening decision here (entry ceiling, expansion ratio, path
+   * validation); the WebUI only renders what the runtime is willing to name.
+   */
+  readWorkspaceArchive(request: { readonly workspaceDir: string; readonly path: string; readonly prefix?: string }): Promise<WebuiWorkspaceArchiveListing>;
+  extractWorkspaceArchive(request: { readonly workspaceDir: string; readonly path: string; readonly destination: string; readonly prefix?: string }): Promise<WebuiWorkspaceArchiveExtractResult>;
   sendMessage(
     request: WebuiSendMessageRequest,
     signal?: AbortSignal,
diff --git a/packages/webui/src/server/service.ts b/packages/webui/src/server/service.ts
index 2ad8fb46f..1f989bd5b 100644
--- a/packages/webui/src/server/service.ts
+++ b/packages/webui/src/server/service.ts
@@ -12,7 +12,8 @@
 // new operations, then close every connection, then close the harness.
 
 import { createServer, type IncomingMessage, type Server } from "node:http";
-import { readFile } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import type { AddressInfo } from "node:net";
 import path from "node:path";
@@ -297,6 +298,14 @@ export class WebuiService {
       rejectHttp(response, 401, "Unauthorized");
       return;
     }
+    // Checked here rather than inside the static-asset table below, so this
+    // route inherits the loopback, origin and credential checks above instead
+    // of re-implementing them: a workspace file is served to whoever holds
+    // the per-start token, and to nobody else.
+    if (url?.pathname === "/workspace-file") {
+      await this.#serveWorkspaceFile(request, response, url);
+      return;
+    }
     if (request.method !== "GET" || !url) {
       rejectHttp(response, 404, "Not Found");
       return;
@@ -346,6 +355,95 @@ export class WebuiService {
     }
   }
 
+  /**
+   * Serve one workspace file as a byte-range-capable HTTP resource.
+   *
+   * Media preview and HTML preview both need a URL the browser streams rather
+   * than a base64 payload inside a JSON reply: `<video>` and `<audio>` cannot
+   * scrub a progress bar without `Range`, and inlining a large file inflates
+   * every response that merely mentions it.
+   *
+   * Dispatch happens after the loopback, origin and credential checks above,
+   * so this inherits them instead of re-implementing them: a workspace file is
+   * served to whoever holds the per-start token and to nobody else.
+   */
+  async #serveWorkspaceFile(
+    request: IncomingMessage,
+    response: import("node:http").ServerResponse,
+    url: URL,
+  ): Promise<void> {
+    if (request.method !== "GET" && request.method !== "HEAD") {
+      rejectHttp(response, 405, "Method Not Allowed");
+      return;
+    }
+    const dir = url.searchParams.get("dir");
+    const relative = url.searchParams.get("path");
+    if (!dir || !relative) {
+      rejectHttp(response, 400, "Missing dir or path");
+      return;
+    }
+    const root = path.resolve(dir);
+    const target = path.resolve(root, relative);
+    // `path.resolve` has already collapsed every `..`, so what is left to
+    // reject is the cases that survive it: an absolute `path`, or a sibling
+    // that merely shares a prefix (`/repo-evil` against root `/repo`).
+    if (target !== root && !target.startsWith(root + path.sep)) {
+      rejectHttp(response, 403, "Forbidden Path");
+      return;
+    }
+    let stats;
+    try {
+      stats = await stat(target);
+    } catch {
+      rejectHttp(response, 404, "Not Found");
+      return;
+    }
+    if (!stats.isFile()) {
+      rejectHttp(response, 404, "Not Found");
+      return;
+    }
+    const total = stats.size;
+    const range = parseByteRange(request.headers.range, total);
+    if (range === "invalid") {
+      response.writeHead(416, { "Content-Range": `bytes */${total}` });
+      response.end();
+      return;
+    }
+    const start = range ? range.start : 0;
+    const end = range ? range.end : total - 1;
+    const headers: Record<string, string> = {
+      "Content-Type": workspaceContentType(target),
+      "Content-Length": String(end - start + 1),
+      // A partial body is only correct for the bytes it was cut from, so a
+      // later edit must not let a cached range be replayed against.
+      "Cache-Control": "no-store",
+      "Accept-Ranges": "bytes",
+      "X-Content-Type-Options": "nosniff",
+      // Without allow-same-origin the document runs in an opaque origin, so
+      // script inside a previewed artifact cannot read the page that framed
+      // it — including `window.__WEBUI_CONFIG__.token`, which would hand it
+      // the whole WebUI session.
+      "Content-Security-Policy": workspaceContentType(target).startsWith("text/html")
+        ? "sandbox allow-scripts"
+        : "sandbox",
+    };
+    if (range) headers["Content-Range"] = `bytes ${start}-${end}/${total}`;
+    response.writeHead(range ? 206 : 200, headers);
+    if (request.method === "HEAD") {
+      response.end();
+      return;
+    }
+    await new Promise<void>((resolve) => {
+      const stream = createReadStream(target, { start, end });
+      stream.on("error", () => {
+        response.destroy();
+        resolve();
+      });
+      stream.on("close", resolve);
+      stream.pipe(response);
+    });
+  }
+
   /**
    * Bind the server and resolve once it is listening. Resolves with the
    * address the kernel actually allocated so tests can reach it.
@@ -608,6 +706,84 @@ function contentType(name: string): string {
       : "text/html; charset=utf-8";
 }
 
+/**
+ * Media types for workspace files, on a whitelist with an
+ * `application/octet-stream` floor.
+ *
+ * Deliberately not `contentType()`: that one exists to serve the WebUI's own
+ * bundle, where an unrecognised asset really is best guessed as HTML, and
+ * guessing wrong there is inert. Here the guessed file is the agent's working
+ * tree, so an unrecognised type has to download rather than render — the
+ * default is what keeps a `.txt` or `.json` from being interpreted as a
+ * document by whatever navigated to it.
+ */
+const WORKSPACE_MEDIA_TYPES: Readonly<Record<string, string>> = {
+  ".avif": "image/avif",
+  ".bmp": "image/bmp",
+  ".gif": "image/gif",
+  ".ico": "image/x-icon",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".webp": "image/webp",
+  ".mp4": "video/mp4",
+  ".mov": "video/quicktime",
+  ".ogv": "video/ogg",
+  ".webm": "video/webm",
+  ".aac": "audio/aac",
+  ".flac": "audio/flac",
+  ".m4a": "audio/mp4",
+  ".mp3": "audio/mpeg",
+  ".ogg": "audio/ogg",
+  ".wav": "audio/wav",
+  ".csv": "text/csv; charset=utf-8",
+  ".htm": "text/html; charset=utf-8",
+  ".html": "text/html; charset=utf-8",
+  ".json": "application/json",
+  ".pdf": "application/pdf",
+  ".wasm": "application/wasm",
+  ".css": "text/css; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".txt": "text/plain; charset=utf-8",
+};
+
+function workspaceContentType(name: string): string {
+  return WORKSPACE_MEDIA_TYPES[path.extname(name).toLowerCase()] ?? "application/octet-stream";
+}
+
+/**
+ * Parse a single-range `Range` header against a known file size.
+ *
+ * Returns "invalid" for a syntactically unsatisfiable range so the caller can
+ * answer 416, and the clamped range otherwise. A multi-range request is
+ * answered with the whole file rather than `multipart/byteranges`: media
+ * elements never ask for one, and serving the full body is a correct if less
+ * efficient answer to the same bytes.
+ */
+function parseByteRange(
+  header: string | undefined,
+  size: number,
+): { readonly start: number; readonly end: number } | "invalid" | undefined {
+  if (!header) return undefined;
+  const match = /^bytes=(\d*)-(\d*)$/u.exec(header.trim());
+  if (!match) return undefined;
+  const [, rawStart, rawEnd] = match;
+  if (!rawStart && !rawEnd) return "invalid";
+  if (!rawStart) {
+    // Suffix form `bytes=-500`: the final N bytes.
+    const suffix = Number(rawEnd);
+    if (!Number.isSafeInteger(suffix) || suffix <= 0) return "invalid";
+    return { start: Math.max(0, size - suffix), end: size - 1 };
+  }
+  const start = Number(rawStart);
+  if (!Number.isSafeInteger(start)) return "invalid";
+  if (start >= size) return "invalid";
+  const end = rawEnd ? Number(rawEnd) : size - 1;
+  if (!Number.isSafeInteger(end) || end < start) return "invalid";
+  return { start, end: Math.min(end, size - 1) };
+}
+
 function resolveClientAsset(
   clientDir: string,
   pathname: string,

From 72a666033cbef6a2efd7632469c05a8627d6d51b Mon Sep 17 00:00:00 2001
From: probe <probe@local>
Date: Sun, 4 Oct 2026 08:38:58 +0800
Subject: [PATCH 02/21] refactor(webui): split the workspace panel into
 per-feature component files

The workspace panel container had grown to 852 dense lines holding five
features at once, so five implementers working in parallel would have
collided in one file. This is a structural split only: no feature is
implemented and no behaviour changes.

Moved out of WorkspacePanels.tsx into new sibling modules, so each
feature now has one owner:

- WorkspaceFileTree.tsx: the recursive FileTree plus the file-tree
  helpers (filterWorkspaceFiles, findWorkspaceFile,
  getWorkspaceFileParentPaths, mergeWorkspaceFileChildren).
  mergeWorkspaceFileChildren is re-exported from WorkspacePanels.tsx
  because the tests import it from there.
- WorkspaceMediaPreview.tsx: the image branch of WebuiFilePreview,
  including the workspace-image-preview test id. Audio and video are
  left as a documented seam, not built.
- WorkspaceArchiveView.tsx, WorkspaceHtmlPreview.tsx: documented prop
  shapes plus a minimal "not available" state, so both must be
  importable and typecheck before the real work starts. Neither is
  mounted yet: there is no archive tab and no HTML branch to mount
  them on, and adding one would be a feature rather than a split.
- WorkspaceCanvas.tsx: the canvas document state, the zoom state, the
  readCanvas effect and the whole canvas render, keeping the
  webui-canvas-* class names and the 0.4-2.0 zoom clamp. The component
  owns its own state and takes sessionId plus readCanvas as props, so
  the canvas implementer never has to touch the container.

WorkspacePanels.tsx keeps the container, tab strip, add menu, review
rendering, the xterm terminal, the environment panel, the commit
dialog, the progress and subagent panels, WebuiFilePreview,
WebuiDiffFileSection and the diff-line projection helpers. It is 852
lines before and 787 after; the removed lines are the ones that moved.

The canvas read now happens when the canvas tab is open instead of on
every tab switch while the panel is mounted. The document is still read
on open and re-read on every return to the tab, so the only difference
is one redundant request that is no longer sent.

Verification: node scripts/run-vitest-suite.mjs webui reports
Test Files 51 passed (51), Tests 958 passed (958) - the same count as
before the split. typecheck:server and typecheck:client are clean.
---
 .../components/WorkspaceArchiveView.tsx       | 38 +++++++++
 .../src/client/components/WorkspaceCanvas.tsx | 28 ++++++
 .../client/components/WorkspaceFileTree.tsx   | 67 +++++++++++++++
 .../components/WorkspaceHtmlPreview.tsx       | 35 ++++++++
 .../components/WorkspaceMediaPreview.tsx      | 27 ++++++
 .../src/client/components/WorkspacePanels.tsx | 85 +++----------------
 6 files changed, 205 insertions(+), 75 deletions(-)
 create mode 100644 packages/webui/src/client/components/WorkspaceArchiveView.tsx
 create mode 100644 packages/webui/src/client/components/WorkspaceCanvas.tsx
 create mode 100644 packages/webui/src/client/components/WorkspaceFileTree.tsx
 create mode 100644 packages/webui/src/client/components/WorkspaceHtmlPreview.tsx
 create mode 100644 packages/webui/src/client/components/WorkspaceMediaPreview.tsx

diff --git a/packages/webui/src/client/components/WorkspaceArchiveView.tsx b/packages/webui/src/client/components/WorkspaceArchiveView.tsx
new file mode 100644
index 000000000..cea67e4dc
--- /dev/null
+++ b/packages/webui/src/client/components/WorkspaceArchiveView.tsx
@@ -0,0 +1,38 @@
+// Owns the workspace archive feature (list + extract inside .zip/.tar archives).
+// Nothing is implemented yet: this file is the seam a different implementer
+// fills in. `WorkspacePanels.tsx` does not mount it yet — there is no archive
+// tab to mount it on, and adding one would be a feature, not a split.
+
+import type { ReactElement } from "react";
+import type { WebuiWorkspaceArchiveExtractResult, WebuiWorkspaceArchiveListing } from "../../server/port.js";
+
+export type WorkspaceArchiveViewProps = {
+  /** Absolute workspace root; every archive path below is relative to it. */
+  readonly workspaceDir: string;
+  /** The archive's path inside the workspace, as the file tree reported it. */
+  readonly path: string;
+  /**
+   * Lists one level of the archive. The runtime owns every hardening
+   * decision (entry ceiling, expansion ratio, path validation), so the view
+   * renders only what this call is willing to name. `prefix` walks deeper
+   * levels; absent, the listing is the archive root.
+   */
+  readonly readWorkspaceArchive?: (request: { readonly workspaceDir: string; readonly path: string; readonly prefix?: string }) => Promise<WebuiWorkspaceArchiveListing>;
+  /** Writes selected entries out of the archive into `destination`. */
+  readonly extractWorkspaceArchive?: (request: { readonly workspaceDir: string; readonly path: string; readonly destination: string; readonly prefix?: string }) => Promise<WebuiWorkspaceArchiveExtractResult>;
+  /**
+   * The directory extraction is allowed to write into. A browser cannot ask
+   * for an arbitrary path, so the view picks one from the workspace and
+   * hands it to the port rather than typing a raw destination.
+   */
+  readonly destination?: string;
+};
+
+/**
+ * Placeholder archive view. It renders the "not available" state so the
+ * workspace panel has a mount point, and stays type-safe: replacing the body
+ * with a real listing is a change inside this file alone.
+ */
+export function WorkspaceArchiveView(_props: WorkspaceArchiveViewProps): ReactElement {
+  return <div role="status"><p>工作区压缩包预览尚未接入。</p></div>;
+}
diff --git a/packages/webui/src/client/components/WorkspaceCanvas.tsx b/packages/webui/src/client/components/WorkspaceCanvas.tsx
new file mode 100644
index 000000000..9d607b7a7
--- /dev/null
+++ b/packages/webui/src/client/components/WorkspaceCanvas.tsx
@@ -0,0 +1,28 @@
+// Owns the workspace canvas feature: the canvas document state, the zoom
+// state, and the whole `webui-canvas-content` render. A different implementer
+// works in this file; the container in `WorkspacePanels.tsx` only mounts it.
+
+import { useEffect, useState, type ReactElement } from "react";
+import type { WebuiCanvasDocument } from "../../server/port.js";
+
+const DESKTOP_COPY = { canvasEmptyTitle: "把文件放到画布上", canvasEmptyDescription: "添加图片或其他工作区文件，然后自由排列和调整大小。" } as const;
+
+export function WorkspaceCanvas({ sessionId, readCanvas }: {
+  /** The session whose canvas document is shown; absent means no canvas. */
+  readonly sessionId?: string;
+  /** Port call that reads the canvas document for a session. */
+  readonly readCanvas?: (request: { sessionId: string }) => Promise<WebuiCanvasDocument>;
+}): ReactElement {
+  const [canvas, setCanvas] = useState<WebuiCanvasDocument>();
+  const [zoom, setZoom] = useState(1);
+  useEffect(() => {
+    if (!sessionId || !readCanvas) { setCanvas(undefined); return undefined; }
+    let cancelled = false;
+    void readCanvas({ sessionId }).then((next) => { if (!cancelled) setCanvas(next); }).catch(() => { if (!cancelled) setCanvas(undefined); });
+    return () => { cancelled = true; };
+  }, [sessionId, readCanvas]);
+  return <div className="webui-canvas-content" onWheel={(event) => { event.preventDefault(); setZoom((value) => Math.max(.4, Math.min(2, value + (event.deltaY > 0 ? -.1 : .1)))); }}>
+    {!canvas?.nodes.length ? <><strong>{DESKTOP_COPY.canvasEmptyTitle}</strong><p>{DESKTOP_COPY.canvasEmptyDescription}</p></> : <div className="webui-canvas-stage" style={{ transform: `scale(${zoom})` }}>{canvas.nodes.map((node) => <div className="webui-canvas-node" key={String(node.id)}>{String((node.file as Record<string, unknown> | undefined)?.fileName ?? node.id)}</div>)}</div>}
+    <span className="webui-canvas-zoom">{Math.round(zoom * 100)}%</span>
+  </div>;
+}
diff --git a/packages/webui/src/client/components/WorkspaceFileTree.tsx b/packages/webui/src/client/components/WorkspaceFileTree.tsx
new file mode 100644
index 000000000..0e49e06a8
--- /dev/null
+++ b/packages/webui/src/client/components/WorkspaceFileTree.tsx
@@ -0,0 +1,67 @@
+// Owns the workspace file-tree feature: the recursive tree component and the
+// file lookup/filter helpers. A different implementer works in this file; the
+// container in `WorkspacePanels.tsx` only imports from it.
+
+import type { ReactElement } from "react";
+import type { WebuiWorkspaceFile } from "../../server/port.js";
+import { WebuiIconChevronLeft, WebuiIconFile } from "../icons.js";
+
+export function filterWorkspaceFiles(files: readonly WebuiWorkspaceFile[], query: string): WebuiWorkspaceFile[] {
+  const normalizedQuery = query.trim().toLowerCase();
+  if (!normalizedQuery) return [...files];
+  return files.flatMap((file) => {
+    const children = file.children ? filterWorkspaceFiles(file.children, normalizedQuery) : [];
+    if (file.name.toLowerCase().includes(normalizedQuery) || children.length > 0) {
+      return [{ ...file, ...(file.children ? { children } : {}) }];
+    }
+    return [];
+  });
+}
+
+export function mergeWorkspaceFileChildren(
+  files: readonly WebuiWorkspaceFile[],
+  directoryPath: string,
+  children: readonly WebuiWorkspaceFile[],
+): readonly WebuiWorkspaceFile[] {
+  return files.map((file) => {
+    if (file.path === directoryPath && file.type === "directory") {
+      return { ...file, children };
+    }
+    return file.children?.length
+      ? { ...file, children: mergeWorkspaceFileChildren(file.children, directoryPath, children) }
+      : file;
+  });
+}
+
+export function findWorkspaceFile(files: readonly WebuiWorkspaceFile[], path: string): WebuiWorkspaceFile | undefined {
+  for (const file of files) {
+    if (file.path === path) return file;
+    const nested = file.children ? findWorkspaceFile(file.children, path) : undefined;
+    if (nested) return nested;
+  }
+  return undefined;
+}
+
+export function getWorkspaceFileParentPaths(path: string): string[] {
+  const segments = path.replace(/\\/gu, "/").split("/").filter(Boolean);
+  return segments.slice(0, -1).map((_, index) => segments.slice(0, index + 1).join("/"));
+}
+
+export function FileTree({ files, onOpen, expandedPaths, loadingPaths, directoryErrors, onToggle, selectedPath }: { readonly files: readonly WebuiWorkspaceFile[]; readonly onOpen: (file: WebuiWorkspaceFile) => void; readonly expandedPaths: ReadonlySet<string>; readonly loadingPaths: ReadonlySet<string>; readonly directoryErrors: Readonly<Record<string, string>>; readonly onToggle: (file: WebuiWorkspaceFile) => void; readonly selectedPath?: string }): ReactElement {
+  return <div className="webui-file-tree">{files.map((file) => {
+    const expanded = expandedPaths.has(file.path);
+    return <div key={file.path}>
+      <button type="button" className={`webui-file-tree-row ${file.path === selectedPath ? "is-selected" : ""}`} aria-current={file.path === selectedPath ? "true" : undefined} aria-expanded={file.type === "directory" ? expanded : undefined} aria-busy={file.type === "directory" && loadingPaths.has(file.path) ? "true" : undefined} onClick={() => file.type === "directory" ? onToggle(file) : onOpen(file)}>
+        {file.type === "directory" ? <WebuiIconChevronLeft className={`inline size-3 transition-transform duration-[180ms] ease-out ${expanded ? "rotate-90" : ""}`} /> : <WebuiIconFile className="inline size-3" />} {file.name}
+      </button>
+      {file.type === "directory" ? <div className={`webui-expandable-motion${expanded ? " is-open" : ""}`} aria-hidden={!expanded} ref={(element) => element?.toggleAttribute("inert", !expanded)}>
+        <div className="webui-file-tree-children">
+          {loadingPaths.has(file.path) ? <p role="status">正在加载目录…</p>
+            : directoryErrors[file.path] ? <p role="alert">{directoryErrors[file.path]}</p>
+              : file.children?.length ? <FileTree files={file.children} onOpen={onOpen} expandedPaths={expandedPaths} loadingPaths={loadingPaths} directoryErrors={directoryErrors} onToggle={onToggle} selectedPath={selectedPath} />
+                : <p>此文件夹为空。</p>}
+        </div>
+      </div> : null}
+    </div>;
+  })}</div>;
+}
diff --git a/packages/webui/src/client/components/WorkspaceHtmlPreview.tsx b/packages/webui/src/client/components/WorkspaceHtmlPreview.tsx
new file mode 100644
index 000000000..251bfbd58
--- /dev/null
+++ b/packages/webui/src/client/components/WorkspaceHtmlPreview.tsx
@@ -0,0 +1,35 @@
+// Owns the workspace HTML-preview feature (rendering an .html file inside
+// the workspace panel). Nothing is implemented yet: this file is the seam a
+// different implementer fills in. `WorkspacePanels.tsx` does not mount it yet
+// — `WebuiFilePreview` has no HTML branch to route into it, and adding one
+// would be a feature, not a split.
+
+import type { ReactElement } from "react";
+import type { WebuiWorkspaceFileContent } from "../../server/port.js";
+
+export type WorkspaceHtmlPreviewProps = {
+  /** The file path the preview tab was opened with. */
+  readonly path: string;
+  /**
+   * The file content as `readWorkspaceFile` returned it. `mimeType` is the
+   * signal a later implementer uses to route `.html` versus `.htm` (and to
+   * refuse anything that is not text/html).
+   */
+  readonly content: WebuiWorkspaceFileContent;
+  /**
+   * How the document is isolated once it renders. Workspace HTML is
+   * untrusted, so the implementer must default to a sandboxed document
+   * (no same-origin access, no script into the panel) and may only widen it
+   * behind an explicit user choice.
+   */
+  readonly sandbox?: "allow-scripts" | "allow-same-origin" | "none";
+};
+
+/**
+ * Placeholder HTML preview. It renders the "not available" state so the file
+ * preview has a mount point; replacing the body is a change inside this file
+ * alone.
+ */
+export function WorkspaceHtmlPreview(_props: WorkspaceHtmlPreviewProps): ReactElement {
+  return <div role="status"><p>HTML 预览尚未接入。</p></div>;
+}
diff --git a/packages/webui/src/client/components/WorkspaceMediaPreview.tsx b/packages/webui/src/client/components/WorkspaceMediaPreview.tsx
new file mode 100644
index 000000000..c93ac9d9b
--- /dev/null
+++ b/packages/webui/src/client/components/WorkspaceMediaPreview.tsx
@@ -0,0 +1,27 @@
+// Owns the workspace media-preview feature: the image branch of the file
+// preview, moved out of `WebuiFilePreview`. A different implementer works in
+// this file; `WorkspacePanels.tsx` only imports the component from it.
+
+import type { ReactElement } from "react";
+import type { WebuiWorkspaceFileContent } from "../../server/port.js";
+
+/**
+ * Image preview for one workspace file.
+ *
+ * Audio and video are not implemented yet. They belong here as sibling
+ * exports (`WorkspaceAudioPreview` / `WorkspaceVideoPreview`) taking the
+ * same `path` + `content` props, dispatched from `content.mimeType`, so
+ * `WebuiFilePreview` never needs to learn about a new media kind.
+ *
+ * Returns `null` when the content carries no `previewDataUrl`, so a caller
+ * that branches on it never renders an empty media element.
+ */
+export function WorkspaceMediaPreview({ path, content }: {
+  /** The file path the preview tab was opened with, used for `alt` text. */
+  readonly path: string;
+  /** The file content as `readWorkspaceFile` returned it. */
+  readonly content: WebuiWorkspaceFileContent;
+}): ReactElement | null {
+  if (!content.previewDataUrl) return null;
+  return <img className="webui-workspace-image-preview" src={content.previewDataUrl} alt={path.split("/").at(-1) ?? path} data-testid="workspace-image-preview" />;
+}
diff --git a/packages/webui/src/client/components/WorkspacePanels.tsx b/packages/webui/src/client/components/WorkspacePanels.tsx
index 3a643d5b4..5705cbc34 100644
--- a/packages/webui/src/client/components/WorkspacePanels.tsx
+++ b/packages/webui/src/client/components/WorkspacePanels.tsx
@@ -37,10 +37,16 @@ import {
   type WebuiWorkspaceSubagent,
   type WebuiWorkspaceTodo,
 } from "../projection/workspace-progress.js";
-import { WebuiIconAgent, WebuiIconCheck, WebuiIconChevronDown, WebuiIconChevronLeft, WebuiIconClose, WebuiIconDiffFile, WebuiIconFile, WebuiIconFolder, WebuiIconRunLocation, WebuiIconSearch, WebuiIconSidebarToggle, WebuiIconWorkspaceCanvas, WebuiIconWorkspaceExpand, WebuiIconWorkspaceReview, WebuiIconWorkspaceTerminal } from "../icons.js";
+import { WebuiIconAgent, WebuiIconCheck, WebuiIconChevronDown, WebuiIconClose, WebuiIconDiffFile, WebuiIconFile, WebuiIconFolder, WebuiIconRunLocation, WebuiIconSearch, WebuiIconSidebarToggle, WebuiIconWorkspaceCanvas, WebuiIconWorkspaceExpand, WebuiIconWorkspaceReview, WebuiIconWorkspaceTerminal } from "../icons.js";
+import { FileTree, filterWorkspaceFiles, findWorkspaceFile, getWorkspaceFileParentPaths, mergeWorkspaceFileChildren } from "./WorkspaceFileTree.js";
+import { WorkspaceMediaPreview } from "./WorkspaceMediaPreview.js";
+import { WorkspaceCanvas } from "./WorkspaceCanvas.js";
 
 export type WebuiTodo = WebuiWorkspaceTodo;
-const DESKTOP_COPY = { environment: "环境信息", progress: "进度", progressEmpty: "跟踪较长任务的进度", newTerminal: "新建终端", terminalLimit: "最多可以打开 5 个终端", terminalLabel: "终端", terminalExited: "已退出", terminalEmptyTitle: "还没有终端", terminalEmptyDescription: "可直接在右侧面板中启动当前工作区的 Shell。", canvasEmptyTitle: "把文件放到画布上", canvasEmptyDescription: "添加图片或其他工作区文件，然后自由排列和调整大小。", fileClose: "关闭", changes: "变更", commit: "提交或推送", openTerminal: "打开终端", unsupported: "WebUI 尚未接入此操作" } as const;
+// `mergeWorkspaceFileChildren` is re-exported below: the file-tree tests
+// import it from this module, which stays the panel's public surface.
+export { mergeWorkspaceFileChildren };
+const DESKTOP_COPY = { environment: "环境信息", progress: "进度", progressEmpty: "跟踪较长任务的进度", newTerminal: "新建终端", terminalLimit: "最多可以打开 5 个终端", terminalLabel: "终端", terminalExited: "已退出", terminalEmptyTitle: "还没有终端", terminalEmptyDescription: "可直接在右侧面板中启动当前工作区的 Shell。", fileClose: "关闭", changes: "变更", commit: "提交或推送", openTerminal: "打开终端", unsupported: "WebUI 尚未接入此操作" } as const;
 
 const FILE_CODE_LANGUAGES = {
   bash,
@@ -151,47 +157,6 @@ export function WebuiDiffFileSection({ file, selected, loading = false, error, o
   </details>;
 }
 
-function filterWorkspaceFiles(files: readonly WebuiWorkspaceFile[], query: string): WebuiWorkspaceFile[] {
-  const normalizedQuery = query.trim().toLowerCase();
-  if (!normalizedQuery) return [...files];
-  return files.flatMap((file) => {
-    const children = file.children ? filterWorkspaceFiles(file.children, normalizedQuery) : [];
-    if (file.name.toLowerCase().includes(normalizedQuery) || children.length > 0) {
-      return [{ ...file, ...(file.children ? { children } : {}) }];
-    }
-    return [];
-  });
-}
-
-export function mergeWorkspaceFileChildren(
-  files: readonly WebuiWorkspaceFile[],
-  directoryPath: string,
-  children: readonly WebuiWorkspaceFile[],
-): readonly WebuiWorkspaceFile[] {
-  return files.map((file) => {
-    if (file.path === directoryPath && file.type === "directory") {
-      return { ...file, children };
-    }
-    return file.children?.length
-      ? { ...file, children: mergeWorkspaceFileChildren(file.children, directoryPath, children) }
-      : file;
-  });
-}
-
-function findWorkspaceFile(files: readonly WebuiWorkspaceFile[], path: string): WebuiWorkspaceFile | undefined {
-  for (const file of files) {
-    if (file.path === path) return file;
-    const nested = file.children ? findWorkspaceFile(file.children, path) : undefined;
-    if (nested) return nested;
-  }
-  return undefined;
-}
-
-function getWorkspaceFileParentPaths(path: string): string[] {
-  const segments = path.replace(/\\/gu, "/").split("/").filter(Boolean);
-  return segments.slice(0, -1).map((_, index) => segments.slice(0, index + 1).join("/"));
-}
-
 export function projectWebuiTodos(messages: readonly Record<string, unknown>[]): WebuiTodo[] {
   return projectWebuiWorkspaceHistory(
     messages as never,
@@ -370,25 +335,6 @@ export function WebuiProgressOverviewPanel({ workspaceDir, isDefaultWorkspace =
   </div>;
 }
 
-function FileTree({ files, onOpen, expandedPaths, loadingPaths, directoryErrors, onToggle, selectedPath }: { readonly files: readonly WebuiWorkspaceFile[]; readonly onOpen: (file: WebuiWorkspaceFile) => void; readonly expandedPaths: ReadonlySet<string>; readonly loadingPaths: ReadonlySet<string>; readonly directoryErrors: Readonly<Record<string, string>>; readonly onToggle: (file: WebuiWorkspaceFile) => void; readonly selectedPath?: string }): ReactElement {
-  return <div className="webui-file-tree">{files.map((file) => {
-    const expanded = expandedPaths.has(file.path);
-    return <div key={file.path}>
-      <button type="button" className={`webui-file-tree-row ${file.path === selectedPath ? "is-selected" : ""}`} aria-current={file.path === selectedPath ? "true" : undefined} aria-expanded={file.type === "directory" ? expanded : undefined} aria-busy={file.type === "directory" && loadingPaths.has(file.path) ? "true" : undefined} onClick={() => file.type === "directory" ? onToggle(file) : onOpen(file)}>
-        {file.type === "directory" ? <WebuiIconChevronLeft className={`inline size-3 transition-transform duration-[180ms] ease-out ${expanded ? "rotate-90" : ""}`} /> : <WebuiIconFile className="inline size-3" />} {file.name}
-      </button>
-      {file.type === "directory" ? <div className={`webui-expandable-motion${expanded ? " is-open" : ""}`} aria-hidden={!expanded} ref={(element) => element?.toggleAttribute("inert", !expanded)}>
-        <div className="webui-file-tree-children">
-          {loadingPaths.has(file.path) ? <p role="status">正在加载目录…</p>
-            : directoryErrors[file.path] ? <p role="alert">{directoryErrors[file.path]}</p>
-              : file.children?.length ? <FileTree files={file.children} onOpen={onOpen} expandedPaths={expandedPaths} loadingPaths={loadingPaths} directoryErrors={directoryErrors} onToggle={onToggle} selectedPath={selectedPath} />
-                : <p>此文件夹为空。</p>}
-        </div>
-      </div> : null}
-    </div>;
-  })}</div>;
-}
-
 export function WebuiFilePreview({ tab, result, codeMode }: {
   readonly tab: Extract<WorkspacePanelTab, { readonly kind: "file-preview" }>;
   readonly result?: { readonly loading: boolean; readonly content?: WebuiWorkspaceFileContent; readonly error?: string };
@@ -400,7 +346,7 @@ export function WebuiFilePreview({ tab, result, codeMode }: {
   return <div className="webui-workspace-file-document" data-testid="workspace-file-preview" data-file-path={tab.path}>
       {result?.loading ? <p role="status">正在加载文件…</p>
         : result?.error ? <p role="alert">{result.error}</p>
-          : result?.content?.previewDataUrl ? <img className="webui-workspace-image-preview" src={result.content.previewDataUrl} alt={tab.path.split("/").at(-1) ?? tab.path} data-testid="workspace-image-preview" />
+          : result?.content?.previewDataUrl ? <WorkspaceMediaPreview path={tab.path} content={result.content} />
             : result?.content?.error ? <p role="alert">{result.content.error}</p>
             : result?.content?.type === "binary" ? <p>无法在文本预览中显示二进制文件。</p>
               : result?.content ? previewMarkdown ? <WebuiMarkdown source={content} /> : <pre className="webui-file-code"><code className={language ? `hljs language-${language}` : ""}>{content.split("\n").map((line, index) => {
@@ -468,8 +414,6 @@ export function WebuiWorkspacePanel({ state, dispatch, sessionId, workspaceDir,
     retriedSnapshots.current.add(retryKey);
     setReviewRefreshToken((value) => value + 1);
   };
-  const [canvas, setCanvas] = useState<WebuiCanvasDocument>();
-  const [zoom, setZoom] = useState(1);
   const [terminals, setTerminals] = useState<readonly Record<string, unknown>[]>([]);
   const [activeTerminalId, setActiveTerminalId] = useState<string>();
   const [terminalError, setTerminalError] = useState<string>();
@@ -735,12 +679,6 @@ export function WebuiWorkspacePanel({ state, dispatch, sessionId, workspaceDir,
     fileTreeScrollRef.current?.querySelector<HTMLElement>('[aria-current="true"]')?.scrollIntoView({ block: "nearest", inline: "nearest" });
   }, [selectedFilePath, selectedReviewPath, expandedDirectories, visibleFiles]);
   const activeSessionId = activeTab && "sessionId" in activeTab ? activeTab.sessionId : sessionId;
-  useEffect(() => {
-    if (!activeSessionId || !readCanvas) { setCanvas(undefined); return undefined; }
-    let cancelled = false;
-    void readCanvas({ sessionId: activeSessionId }).then((next) => { if (!cancelled) setCanvas(next); }).catch(() => { if (!cancelled) setCanvas(undefined); });
-    return () => { cancelled = true; };
-  }, [activeSessionId, activeTab?.id, readCanvas]);
   useEffect(() => {
     if (!listTerminals) return undefined;
     let cancelled = false;
@@ -835,10 +773,7 @@ export function WebuiWorkspacePanel({ state, dispatch, sessionId, workspaceDir,
       <div className="webui-turn-review-summary"><span>本轮改动</span><span className="webui-diff-header-stats"><span className="webui-diff-add">+{turnReviewFiles.reduce((sum, file) => sum + file.additions, 0)}</span>{turnReviewFiles.some((file) => file.deletions > 0) ? <span className="webui-diff-del">-{turnReviewFiles.reduce((sum, file) => sum + file.deletions, 0)}</span> : null}</span></div>
       {turnReviewFiles.length ? <div className="webui-turn-review-files">{turnReviewFiles.map((file) => <WebuiDiffFileSection key={file.file} file={file} selected={selectedReviewPath === file.file} />)}</div> : <p className="webui-turn-review-empty">本轮没有可审查的文件差异。</p>}
     </div> : null}
-    {tab === "canvas" ? <div className="webui-canvas-content" onWheel={(event) => { event.preventDefault(); setZoom((value) => Math.max(.4, Math.min(2, value + (event.deltaY > 0 ? -.1 : .1)))); }}>
-      {!canvas?.nodes.length ? <><strong>{DESKTOP_COPY.canvasEmptyTitle}</strong><p>{DESKTOP_COPY.canvasEmptyDescription}</p></> : <div className="webui-canvas-stage" style={{ transform: `scale(${zoom})` }}>{canvas.nodes.map((node) => <div className="webui-canvas-node" key={String(node.id)}>{String((node.file as Record<string, unknown> | undefined)?.fileName ?? node.id)}</div>)}</div>}
-      <span className="webui-canvas-zoom">{Math.round(zoom * 100)}%</span>
-    </div> : null}
+    {tab === "canvas" ? <WorkspaceCanvas sessionId={activeSessionId} readCanvas={readCanvas} /> : null}
     {tab === "terminal" ? <div className="webui-terminal-empty">{terminals.length === 0 ? <><strong>{DESKTOP_COPY.terminalEmptyTitle}</strong><p>{DESKTOP_COPY.terminalEmptyDescription}</p></> : <><div className="webui-terminal-tabs">{terminals.map((terminal, index) => <button type="button" key={String(terminal.terminalId)} className={`file-tab group/tab-close h-8 w-40 min-w-20 ${String(terminal.terminalId) === (activeTerminalId ?? String(terminals[0]?.terminalId)) ? "bg-bg_interaction_tertiary_selected" : ""}`} onClick={() => setActiveTerminalId(String(terminal.terminalId))}><span>#{index + 1}</span>{terminal.status === "exited" ? DESKTOP_COPY.terminalExited : DESKTOP_COPY.terminalLabel}<span className="file-tab-close opacity-0 group-hover/tab-close:opacity-100"><WebuiIconClose className="size-[14px]" /></span></button>)}</div><div ref={terminalHost} className="webui-xterm-host" />{terminalError ? <p role="alert">{terminalError}</p> : null}<div className="webui-terminal-actions"><button type="button" onClick={() => { if (!activeWorkspace || !createTerminal) return; void createTerminal({ workspaceDir: activeWorkspace }).then((created) => { setActiveTerminalId(created.terminalId); return listTerminals?.().then(setTerminals); }).catch((error: unknown) => setTerminalError(error instanceof Error ? error.message : String(error))); }}>{DESKTOP_COPY.newTerminal}</button><button type="button" onClick={() => { const active = terminals.find((candidate) => String(candidate.terminalId) === (activeTerminalId ?? String(terminals[0]?.terminalId))); if (active && disposeTerminal) void disposeTerminal({ terminalId: String(active.terminalId) }).then(() => listTerminals?.().then(setTerminals)); }}>{DESKTOP_COPY.fileClose}</button></div></> }{terminals.length === 0 ? <button type="button" onClick={() => { if (!activeWorkspace || !createTerminal) return; void createTerminal({ workspaceDir: activeWorkspace }).then((created) => { setActiveTerminalId(created.terminalId); return listTerminals?.().then(setTerminals); }).catch((error: unknown) => setTerminalError(error instanceof Error ? error.message : String(error))); }}>{DESKTOP_COPY.newTerminal}</button> : null}</div> : null}
       </div>
       {hasFileWorkspace && fileTreeOpen ? <aside className="webui-workspace-file-tree-panel" aria-label="工作区文件树">

From 855d7ac3fa8a0fd64015e1dd4da236710488c992 Mon Sep 17 00:00:00 2001
From: probe <probe@local>
Date: Sun, 4 Oct 2026 08:40:55 +0800
Subject: [PATCH 03/21] feat(webui): expose the workspace file URL and archive
 calls on the transport

Media and HTML previews fetch a URL directly rather than going through the
JSON request path, so the credential has to travel with it. Only the
transport knows the per-start token, so it builds the URL: a component that
assembled its own would put the credential in a second place and let the two
drift.

The `ws:`/`wss:` prefixes are rewritten with a single substitution because
both start with `ws`, so `ws:` lands on `http:` and `wss:` on `https:`. The
token is appended after that rewrite, since the server checks it on
`/workspace-file` like on any other route.

`readWorkspaceArchive` and `extractWorkspaceArchive` are added alongside it
so the archive implementer inherits the same transport seam rather than
opening a second channel.
---
 packages/webui/src/client/contracts.ts | 25 +++++++++++++++++++++++++
 packages/webui/src/client/transport.ts | 10 ++++++++++
 2 files changed, 35 insertions(+)

diff --git a/packages/webui/src/client/contracts.ts b/packages/webui/src/client/contracts.ts
index 60354b6f9..b68f94367 100644
--- a/packages/webui/src/client/contracts.ts
+++ b/packages/webui/src/client/contracts.ts
@@ -13,6 +13,8 @@ import type {
   WebuiClaimSigninView,
   WebuiEditSessionMessageRequest,
   WebuiEditSessionMessageResult,
+  WebuiWorkspaceArchiveListing,
+  WebuiWorkspaceArchiveExtractResult,
   WebuiEnqueueMessageRequest,
   WebuiEnqueueMessageResult,
   WebuiFileDiffInfoView,
@@ -474,6 +476,29 @@ export interface WebuiTransport {
     readonly sessionId: string;
     readonly operation: Record<string, unknown>;
   }) => Promise<unknown>;
+  /**
+   * The streamable URL of one workspace file, credential included.
+   *
+   * Provided by the transport rather than assembled by a component: media and
+   * HTML previews need a URL the browser fetches directly, and only the
+   * transport knows the per-start token. Building it in a component would put
+   * the credential in two places and let one of them drift.
+   */
+  readonly workspaceFileUrl?: (request: {
+    readonly workspaceDir: string;
+    readonly path: string;
+  }) => string;
+  readonly readWorkspaceArchive?: (request: {
+    readonly workspaceDir: string;
+    readonly path: string;
+    readonly prefix?: string;
+  }) => Promise<WebuiWorkspaceArchiveListing>;
+  readonly extractWorkspaceArchive?: (request: {
+    readonly workspaceDir: string;
+    readonly path: string;
+    readonly destination: string;
+    readonly prefix?: string;
+  }) => Promise<WebuiWorkspaceArchiveExtractResult>;
   readonly createTerminal?: (request: {
     readonly workspaceDir: string;
   }) => Promise<{ readonly terminalId: string; readonly status: string }>;
diff --git a/packages/webui/src/client/transport.ts b/packages/webui/src/client/transport.ts
index 9fb38dc78..27e239a4d 100644
--- a/packages/webui/src/client/transport.ts
+++ b/packages/webui/src/client/transport.ts
@@ -399,6 +399,16 @@ export function createWebuiTransport({
     searchWorkspaceReviewDiffs: (body) => request("searchWorkspaceReviewDiffs", body),
     readCanvas: (body) => request("readCanvas", body),
     applyCanvas: (body) => request("applyCanvas", body),
+    workspaceFileUrl: ({ workspaceDir, path: filePath }) => {
+      // `ws:`/`wss:` share the `ws` prefix, so one substitution lands on
+      // `http:`/`https:` respectively, and it must happen before the token is
+      // appended — the server checks the token on this route like any other.
+      const base = baseWebsocketUrl.replace(/\/$/u, "").replace(/^ws/iu, "http");
+      const query = new URLSearchParams({ dir: workspaceDir, path: filePath, token });
+      return `${base}/workspace-file?${query.toString()}`;
+    },
+    readWorkspaceArchive: (body) => request("readWorkspaceArchive", body),
+    extractWorkspaceArchive: (body) => request("extractWorkspaceArchive", body),
     createTerminal: (body) => request("createTerminal", body),
     listTerminals: () => request("listTerminals", {}),
     writeTerminal: (body) => request("writeTerminal", body),

From e2ed1da22415e2ccceef0016f6ebd0b798be49a1 Mon Sep 17 00:00:00 2001
From: probe <probe@local>
Date: Sun, 4 Oct 2026 08:41:05 +0800
Subject: [PATCH 04/21] chore(source): register the five workspace panel
 feature files

---
 release/public-source.json | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/release/public-source.json b/release/public-source.json
index 28601ec88..ae72885ed 100644
--- a/release/public-source.json
+++ b/release/public-source.json
@@ -3540,6 +3540,11 @@
     "packages/webui/src/client/components/TurnNavigator.tsx",
     "packages/webui/src/client/components/UserMenu.tsx",
     "packages/webui/src/client/components/WebuiClientFoundationApp.tsx",
+    "packages/webui/src/client/components/WorkspaceArchiveView.tsx",
+    "packages/webui/src/client/components/WorkspaceCanvas.tsx",
+    "packages/webui/src/client/components/WorkspaceFileTree.tsx",
+    "packages/webui/src/client/components/WorkspaceHtmlPreview.tsx",
+    "packages/webui/src/client/components/WorkspaceMediaPreview.tsx",
     "packages/webui/src/client/components/WorkspacePanels.tsx",
     "packages/webui/src/client/components/settings-search-highlight.ts",
     "packages/webui/src/client/components/settings/UsageModelSettings.tsx",

From 4ac2bb1c71cf1893868ea1378b383070effeef55 Mon Sep 17 00:00:00 2001
From: probe <probe@local>
Date: Sun, 4 Oct 2026 08:44:01 +0800
Subject: [PATCH 05/21] fix(webui): answer a zero-byte workspace file instead
 of crashing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`GET /workspace-file` computed `end` as `total - 1`, which is -1 for a
zero-byte file, and handed that to `createReadStream` as the `end` of a
read range. Node rejects it with ERR_OUT_OF_RANGE, the throw lands inside
the response promise, and because `#onRequest` only `void`s the dispatch
the rejection escapes as an unhandled one — in Node's default mode that
ends the process, and either way the request never gets a response. An
empty file in the workspace is an ordinary thing for the file browser to
be asked for, so the route now ends the response on the `Content-Length: 0`
it has already sent.

`parseByteRange` gets the matching half: a range against a zero-length
representation selects no byte, so it is unsatisfiable (416) rather than
the `{start: 0, end: -1}` pair the suffix branch used to return, whose
`Content-Range` header cannot be spelled at all.
---
 packages/webui/src/server/service.ts | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/packages/webui/src/server/service.ts b/packages/webui/src/server/service.ts
index 1f989bd5b..3b80618b1 100644
--- a/packages/webui/src/server/service.ts
+++ b/packages/webui/src/server/service.ts
@@ -433,6 +433,16 @@ export class WebuiService {
       response.end();
       return;
     }
+    // A zero-byte file has no last byte, so `end` above is -1 and there is no
+    // legal `end` to hand a read stream: `createReadStream` rejects it with
+    // ERR_OUT_OF_RANGE, which rejects this promise and — since the caller only
+    // `void`s the dispatch — surfaces as an unhandled rejection and takes the
+    // process down. The `Content-Length: 0` already sent above is the whole
+    // body, so just end the response.
+    if (total === 0) {
+      response.end();
+      return;
+    }
     await new Promise<void>((resolve) => {
       const stream = createReadStream(target, { start, end });
       stream.on("error", () => {
@@ -768,6 +778,11 @@ function parseByteRange(
   if (!header) return undefined;
   const match = /^bytes=(\d*)-(\d*)$/u.exec(header.trim());
   if (!match) return undefined;
+  // No byte of a zero-length representation can be selected, so any range
+  // against one is unsatisfiable. Handled here rather than in the two
+  // branches below because the suffix branch would otherwise answer with
+  // `{start: 0, end: -1}` — a range whose header cannot even be spelled.
+  if (size === 0) return "invalid";
   const [, rawStart, rawEnd] = match;
   if (!rawStart && !rawEnd) return "invalid";
   if (!rawStart) {

From 7ed972b760a9015e43756d7789e0b777ca4b74eb Mon Sep 17 00:00:00 2001
From: probe <probe@local>
Date: Sun, 4 Oct 2026 08:44:05 +0800
Subject: [PATCH 06/21] test(webui): cover the workspace file resource route
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The `/workspace-file` route landed without tests. These go over a real
loopback socket against the scripted harness port the rest of this file
already boots, because what the route has to guarantee is a property of the
bytes and headers on the wire, not of an internal helper's return value:

  * the credential gate runs before any path is resolved, and a `..` walk
    or a sibling that merely shares the root's name prefix is a 403 — the
    absolute spelling of the sibling is the one a bare `startsWith(root)`
    would have let through;
  * `bytes=0-4` and the suffix form `bytes=-5` answer exactly their slice
    with a matching `Content-Range`, and a start past the end, a reversed
    range, or a range against an empty file is 416 with `bytes */<total>`,
    while a multi-range or unparseable header is answered with the whole
    file rather than `multipart/byteranges`;
  * the media type comes from the whitelist with an
    `application/octet-stream` floor, so an unknown extension — and an
    extensionless file — never come back as `text/html`;
  * `sandbox allow-scripts` is for `text/html` only, and every response
    carries nosniff, `Accept-Ranges` and `Cache-Control: no-store`;
  * HEAD returns the headers with an empty body and every other method is
    405.
---
 .../webui/test/unit/webui-service.test.ts     | 360 +++++++++++++++++-
 1 file changed, 359 insertions(+), 1 deletion(-)

diff --git a/packages/webui/test/unit/webui-service.test.ts b/packages/webui/test/unit/webui-service.test.ts
index 57622ea46..21316b5ab 100644
--- a/packages/webui/test/unit/webui-service.test.ts
+++ b/packages/webui/test/unit/webui-service.test.ts
@@ -7,7 +7,7 @@
 // surface honest (the harness never runs against real history, per ADR
 // 0006) while the wire side exercises the real `ws` package.
 
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import assert from "node:assert/strict";
 import { once } from "node:events";
 import os from "node:os";
@@ -73,6 +73,19 @@ type CloseEvent = [number, Buffer];
 // all the assertions in this file actually need.
 type OncePromise<T> = Promise<T[]>;
 
+/**
+ * The staged tree the `/workspace-file` tests point `dir` at, plus the bound
+ * loopback endpoint serving it. See `bootWorkspaceTree` for why the tree
+ * carries a prefix-sharing sibling.
+ */
+interface WorkspaceFileTree {
+  readonly endpoint: string;
+  readonly token: string;
+  readonly root: string;
+  readonly sibling: string;
+  readonly outside: string;
+}
+
 class ScriptedHarnessPort implements WebuiHarnessPort {
   lastProviderTest?: { readonly providerId: string; readonly apiKey?: string };
   lastModelTest?: { readonly providerId: string; readonly modelId: string };
@@ -1696,6 +1709,351 @@ describe("WebUI service", () => {
     }
   });
 
+  // `GET /workspace-file` serves one workspace file as a byte-range-capable
+  // resource, for the media preview and the HTML preview in the workspace
+  // panel. The route is dispatched *after* the loopback, origin and credential
+  // checks in `#serveClient`, so every assertion here goes out over a real
+  // socket: what is under test is bytes and headers on the wire, not the
+  // return value of an internal helper. The three properties that make the
+  // route safe enough to exist are all wire-level:
+  //
+  //   * a path that leaves the workspace never resolves to bytes,
+  //   * a range request answers the bytes it was asked for and nothing else,
+  //   * an unrecognised file is never rendered, because the media type comes
+  //     from a whitelist with an `application/octet-stream` floor rather than
+  //     from the guessing `contentType()` the WebUI's own bundle needs.
+  describe("workspace file resource", () => {
+    // 21 bytes, so `bytes=0-4` and the suffix form `bytes=-5` cut distinct,
+    // checkable slices out of the start and the end of the same file.
+    const TEXT = "0123456789abcdefghij\n";
+    const stagedDirs: string[] = [];
+
+    afterEach(async () => {
+      while (stagedDirs.length > 0) {
+        const dir = stagedDirs.pop();
+        if (dir) await rm(dir, { recursive: true, force: true });
+      }
+    });
+
+    /**
+     * Boot the real service and stage a temp tree for it to serve.
+     *
+     * The tree carries two things a plain `mkdtemp` root would not: a sibling
+     * directory whose *name* starts with the root's name (`<root>-sibling`),
+     * and a second unrelated temp directory outside the root. The sibling is
+     * the case a `..`-segment check alone misses — `path.resolve` collapses
+     * both `<root>/../<root>-sibling/secret.txt` and the absolute form
+     * `<root>-sibling/secret.txt` to a real path outside the root, and only
+     * the `target === root || target.startsWith(root + path.sep)` comparison
+     * rejects them, because both start with the root as a plain *string*.
+     */
+    async function bootWorkspaceTree(): Promise<WorkspaceFileTree> {
+      const { credential } = await bootService();
+      const root = await mkdtemp(path.join(os.tmpdir(), "webui-wsfile-"));
+      const sibling = `${root}-sibling`;
+      const outside = await mkdtemp(path.join(os.tmpdir(), "webui-wsfile-outside-"));
+      stagedDirs.push(root, sibling, outside);
+      await mkdir(sibling);
+      await mkdir(path.join(root, "nested"));
+      await writeFile(path.join(root, "notes.txt"), TEXT);
+      await writeFile(path.join(root, "page.html"), "<!doctype html><p>preview</p>\n");
+      await writeFile(path.join(root, "frame.png"), Buffer.from([0x89, 0x50, 0x4e, 0x47]));
+      // Two shapes that must land on the whitelist floor: an extension the
+      // table has never heard of, and no extension at all.
+      await writeFile(path.join(root, "blob.unknownext"), "not on the list\n");
+      await writeFile(path.join(root, "LICENSE"), "no extension at all\n");
+      await writeFile(path.join(sibling, "secret.txt"), "sibling secret\n");
+      await writeFile(path.join(outside, "secret.txt"), "outside secret\n");
+      return {
+        endpoint: `http://127.0.0.1:${service.info().tcpPort}/workspace-file`,
+        token: credential.token,
+        root,
+        sibling,
+        outside,
+      };
+    }
+
+    /**
+     * Build the request URL. An empty `token`/`dir`/`path` is omitted from the
+     * query string, which is what exercises the parameter-level failures
+     * without hand-rolling one.
+     */
+    function fileUrl(
+      tree: WorkspaceFileTree,
+      relative: string,
+      options?: {
+        readonly token?: string | undefined;
+        readonly dir?: string | undefined;
+      },
+    ): string {
+      const params = new URLSearchParams();
+      // An empty `dir`/`path`/`token` is left out of the query string
+      // entirely, which is how the parameter-level failures get reached.
+      const dir = options?.dir === undefined ? tree.root : options.dir;
+      if (dir) params.set("dir", dir);
+      if (relative) params.set("path", relative);
+      const token = options?.token === undefined ? tree.token : options.token;
+      if (token) params.set("token", token);
+      return `${tree.endpoint}?${params.toString()}`;
+    }
+
+    /** Read the body as the bytes that arrived, never as a decoded string. */
+    async function readBody(response: Response): Promise<Buffer> {
+      return Buffer.from(await response.arrayBuffer());
+    }
+
+    it("requires the per-start credential before resolving a path", async () => {
+      const tree = await bootWorkspaceTree();
+
+      const anonymous = await fetch(fileUrl(tree, "notes.txt", { token: "" }));
+      expect(anonymous.status).toBe(401);
+
+      const wrong = await fetch(
+        fileUrl(tree, "notes.txt", { token: "definitely-not-it" }),
+      );
+      expect(wrong.status).toBe(401);
+    });
+
+    it("serves a whole file with its whitelisted media type and no partial framing", async () => {
+      const tree = await bootWorkspaceTree();
+
+      const response = await fetch(fileUrl(tree, "notes.txt"));
+      expect(response.status).toBe(200);
+      expect(response.headers.get("content-type")).toBe("text/plain; charset=utf-8");
+      expect(response.headers.get("content-length")).toBe(String(TEXT.length));
+      expect(response.headers.get("content-range")).toBeNull();
+      expect((await readBody(response)).toString("utf8")).toBe(TEXT);
+      // The security headers ride on every response, not only on HTML: a
+      // previewed artifact must never be able to sniff its way to a rendering
+      // type, and a range body must not be replayed against a later edit.
+      expect(response.headers.get("x-content-type-options")).toBe("nosniff");
+      expect(response.headers.get("accept-ranges")).toBe("bytes");
+      expect(response.headers.get("cache-control")).toBe("no-store");
+      expect(response.headers.get("content-security-policy")).toBe("sandbox");
+    });
+
+    it("serves a zero-byte file as an empty 200 and refuses a range against it", async () => {
+      // A zero-byte file has no last byte, so `total - 1` is -1: the read
+      // stream used to be handed that and rejected it with ERR_OUT_OF_RANGE,
+      // which rejected the response promise and left the request hanging as an
+      // unhandled rejection. A freshly created empty file in the workspace is
+      // an ordinary thing for the file browser to be asked for.
+      const tree = await bootWorkspaceTree();
+      await writeFile(path.join(tree.root, "empty.txt"), "");
+
+      const response = await fetch(fileUrl(tree, "empty.txt"));
+      expect(response.status).toBe(200);
+      expect(response.headers.get("content-length")).toBe("0");
+      expect(response.headers.get("content-security-policy")).toBe("sandbox");
+      expect((await readBody(response)).length).toBe(0);
+
+      // A range cannot select a byte that does not exist, so this is
+      // unsatisfiable rather than answerable — and its Content-Range has to
+      // stay spellable, which is why it is not a `bytes 0--1/0`.
+      for (const header of ["bytes=0-", "bytes=-5"]) {
+        const ranged = await fetch(fileUrl(tree, "empty.txt"), {
+          headers: { Range: header },
+        });
+        expect(ranged.status, `Range: ${header}`).toBe(416);
+        expect(ranged.headers.get("content-range"), `Range: ${header}`).toBe("bytes */0");
+      }
+    });
+
+    it("answers a bounded range with exactly those bytes and the matching Content-Range", async () => {
+      const tree = await bootWorkspaceTree();
+
+      const response = await fetch(fileUrl(tree, "notes.txt"), {
+        headers: { Range: "bytes=0-4" },
+      });
+      expect(response.status).toBe(206);
+      expect(response.headers.get("content-range")).toBe(`bytes 0-4/${TEXT.length}`);
+      expect(response.headers.get("content-length")).toBe("5");
+      const body = await readBody(response);
+      expect(body.length).toBe(5);
+      expect(body.toString("utf8")).toBe(TEXT.slice(0, 5));
+    });
+
+    it("answers a suffix range with the final bytes", async () => {
+      const tree = await bootWorkspaceTree();
+
+      const response = await fetch(fileUrl(tree, "notes.txt"), {
+        headers: { Range: "bytes=-5" },
+      });
+      expect(response.status).toBe(206);
+      expect(response.headers.get("content-range")).toBe(
+        `bytes ${TEXT.length - 5}-${TEXT.length - 1}/${TEXT.length}`,
+      );
+      const body = await readBody(response);
+      expect(body.length).toBe(5);
+      expect(body.toString("utf8")).toBe(TEXT.slice(-5));
+    });
+
+    it("refuses a range it cannot satisfy, and a reversed one, with 416", async () => {
+      const tree = await bootWorkspaceTree();
+
+      const pastTheEnd = await fetch(fileUrl(tree, "notes.txt"), {
+        headers: { Range: "bytes=999999-" },
+      });
+      expect(pastTheEnd.status).toBe(416);
+      expect(pastTheEnd.headers.get("content-range")).toBe(`bytes */${TEXT.length}`);
+      expect((await readBody(pastTheEnd)).length).toBe(0);
+
+      const reversed = await fetch(fileUrl(tree, "notes.txt"), {
+        headers: { Range: "bytes=4-2" },
+      });
+      expect(reversed.status).toBe(416);
+      expect(reversed.headers.get("content-range")).toBe(`bytes */${TEXT.length}`);
+
+      // `bytes=-` parses as a range spec that names no bytes at all — the
+      // suffix length is missing rather than malformed — so it lands on the
+      // unsatisfiable side of the split below, not the unparseable one.
+      const empty = await fetch(fileUrl(tree, "notes.txt"), {
+        headers: { Range: "bytes=-" },
+      });
+      expect(empty.status).toBe(416);
+      expect(empty.headers.get("content-range")).toBe(`bytes */${TEXT.length}`);
+    });
+
+    it("refuses a path that walks out of the workspace with `..`", async () => {
+      const tree = await bootWorkspaceTree();
+      const target = `../${path.basename(tree.outside)}/secret.txt`;
+      // The file is real and outside the root, so the 403 below is a decision
+      // about the path rather than a missing-file accident.
+      await expect(
+        readFile(path.join(tree.outside, "secret.txt"), "utf8"),
+      ).resolves.toBe("outside secret\n");
+
+      const response = await fetch(fileUrl(tree, target));
+      expect(response.status).toBe(403);
+      expect((await response.text()).includes("outside secret")).toBe(false);
+    });
+
+    it("refuses a sibling that merely shares the root's name prefix", async () => {
+      const tree = await bootWorkspaceTree();
+      // The absolute spelling is the sharp one: it starts with the root as a
+      // plain string, so a `target.startsWith(root)` check would let it
+      // through, and the `+ path.sep` comparison is what rejects it.
+      const escapes = [
+        path.join(tree.sibling, "secret.txt"),
+        `../${path.basename(tree.sibling)}/secret.txt`,
+      ];
+
+      for (const target of escapes) {
+        const response = await fetch(fileUrl(tree, target));
+        expect(response.status, `escape via ${target}`).toBe(403);
+        expect((await response.text()).includes("sibling secret")).toBe(false);
+      }
+    });
+
+    it("falls back to application/octet-stream for a type the whitelist has never heard of", async () => {
+      const tree = await bootWorkspaceTree();
+
+      for (const name of ["blob.unknownext", "LICENSE"]) {
+        const response = await fetch(fileUrl(tree, name));
+        expect(response.status, `serve ${name}`).toBe(200);
+        const type = response.headers.get("content-type");
+        expect(type, `type for ${name}`).toBe("application/octet-stream");
+        // The whole point of the separate table: an unrecognised file must
+        // not be guessed into a rendering type the way `contentType()` guesses
+        // the WebUI's own bundle.
+        expect(type ?? "").not.toContain("text/html");
+      }
+    });
+
+    it("serves HTML in a script sandbox that cannot read the framing page", async () => {
+      const tree = await bootWorkspaceTree();
+
+      const response = await fetch(fileUrl(tree, "page.html"));
+      expect(response.status).toBe(200);
+      expect(response.headers.get("content-type")).toBe("text/html; charset=utf-8");
+      // `allow-scripts` so the previewed document runs, but no
+      // `allow-same-origin`: without it the document lands in an opaque
+      // origin and cannot reach `window.__WEBUI_CONFIG__.token`, which would
+      // hand it the whole WebUI session.
+      expect(response.headers.get("content-security-policy")).toBe(
+        "sandbox allow-scripts",
+      );
+    });
+
+    it("sandboxes a non-HTML type without the allow-scripts variant", async () => {
+      const tree = await bootWorkspaceTree();
+
+      for (const name of ["notes.txt", "frame.png"]) {
+        const response = await fetch(fileUrl(tree, name));
+        expect(response.status, `serve ${name}`).toBe(200);
+        const policy = response.headers.get("content-security-policy");
+        expect(policy, `policy for ${name}`).toBe("sandbox");
+        // Exactly `sandbox`: media in an iframe is already inert, and granting
+        // scripts to it would be a grant nothing needs.
+        expect(policy ?? "").not.toContain("allow-scripts");
+      }
+    });
+
+    it("404s a directory or a missing file rather than reading something else", async () => {
+      const tree = await bootWorkspaceTree();
+
+      const directory = await fetch(fileUrl(tree, "nested"));
+      expect(directory.status).toBe(404);
+
+      // The root itself passes the resolve check (`target === root`), so this
+      // also pins that the `isFile()` gate is what rejects it, rather than the
+      // path comparison.
+      const rootItself = await fetch(fileUrl(tree, "."));
+      expect(rootItself.status).toBe(404);
+
+      const missing = await fetch(fileUrl(tree, "absent.txt"));
+      expect(missing.status).toBe(404);
+    });
+
+    it("400s when either dir or path is missing", async () => {
+      const tree = await bootWorkspaceTree();
+
+      const withoutDir = await fetch(fileUrl(tree, "notes.txt", { dir: "" }));
+      expect(withoutDir.status).toBe(400);
+
+      const withoutPath = await fetch(fileUrl(tree, ""));
+      expect(withoutPath.status).toBe(400);
+    });
+
+    it("answers HEAD with the headers and no body, and 405s any other method", async () => {
+      const tree = await bootWorkspaceTree();
+
+      const head = await fetch(fileUrl(tree, "notes.txt"), { method: "HEAD" });
+      expect(head.status).toBe(200);
+      expect(head.headers.get("content-length")).toBe(String(TEXT.length));
+      expect(head.headers.get("content-type")).toBe("text/plain; charset=utf-8");
+      expect((await readBody(head)).length).toBe(0);
+
+      for (const method of ["POST", "PUT", "DELETE"]) {
+        const response = await fetch(fileUrl(tree, "notes.txt"), { method });
+        expect(response.status, `${method} /workspace-file`).toBe(405);
+      }
+    });
+
+    it("serves the whole file for a multi-range or unparseable Range header", async () => {
+      // The stated design: a single range only, and anything that is not one
+      // parseable single range is answered with the whole file rather than
+      // `multipart/byteranges`. Media elements never ask for a multi-range, so
+      // a full 200 is a correct, if less efficient, answer to the same bytes.
+      const tree = await bootWorkspaceTree();
+
+      for (const header of ["bytes=0-1,4-5", "bytes=abc", "items=0-4"]) {
+        const response = await fetch(fileUrl(tree, "notes.txt"), {
+          headers: { Range: header },
+        });
+        expect(response.status, `Range: ${header}`).toBe(200);
+        expect(response.headers.get("content-type"), `Range: ${header}`).toBe(
+          "text/plain; charset=utf-8",
+        );
+        expect(response.headers.get("content-range"), `Range: ${header}`).toBeNull();
+        expect(
+          (await readBody(response)).toString("utf8"),
+          `Range: ${header}`,
+        ).toBe(TEXT);
+      }
+    });
+  });
+
   it("accepts a websocket upgrade without a credential when dev mode is on", async () => {
     // The HTTP asset path is only half of the contract — the WebSocket
     // upgrade must follow the same gate so the runtime configuration the

From 28aed04b8f47b1d59b37b8459b9b11fd2548c3f9 Mon Sep 17 00:00:00 2001
From: probe <probe@local>
Date: Sun, 4 Oct 2026 08:46:33 +0800
Subject: [PATCH 07/21] test(webui): give the harness port fixtures their
 archive members

`ed6630b` added `readWorkspaceArchive` and `extractWorkspaceArchive` to
`WebuiHarnessPort` and left the scripted fixtures behind, which is what
`typecheck:test` was reporting.

`FullPort` is the one that matters: it exists precisely so that forgetting a
port member becomes a compile error rather than an `undefined` at runtime, so
its new members land there by design rather than as an exception. The two
inline `recordingPort` literals get the same empty listing, and
`ScriptedHarnessPort` answers with a structural zero since it has no archive
to serve.

typecheck:test, typecheck:server and typecheck:client all clean.
---
 .../unit/webui-host-shape-invariant.test.ts   |  9 +++++++
 .../webui/test/unit/webui-service.test.ts     | 24 +++++++++++++++++++
 2 files changed, 33 insertions(+)

diff --git a/packages/webui/test/unit/webui-host-shape-invariant.test.ts b/packages/webui/test/unit/webui-host-shape-invariant.test.ts
index 8583a1de8..8ba301096 100644
--- a/packages/webui/test/unit/webui-host-shape-invariant.test.ts
+++ b/packages/webui/test/unit/webui-host-shape-invariant.test.ts
@@ -71,6 +71,15 @@ class FullPort implements WebuiHarnessPort {
   version() {
     return { version: "invariant-test", protocolVersion: 1 };
   }
+  // Added with the F-zone archive contract. This class exists to make a
+  // forgotten port member a compile error, so the members land here rather
+  // than being left optional.
+  async readWorkspaceArchive() {
+    return { archivePath: "", entries: [], totalEntries: 0, truncated: false };
+  }
+  async extractWorkspaceArchive() {
+    return { archivePath: "", destination: "", writtenFiles: 0 };
+  }
   async listSessions() {
     return { sessions: [], hasMore: false };
   }
diff --git a/packages/webui/test/unit/webui-service.test.ts b/packages/webui/test/unit/webui-service.test.ts
index 21316b5ab..779376c01 100644
--- a/packages/webui/test/unit/webui-service.test.ts
+++ b/packages/webui/test/unit/webui-service.test.ts
@@ -259,6 +259,18 @@ class ScriptedHarnessPort implements WebuiHarnessPort {
     return [{ path: "README.md", name: "README.md", kind: "file" }];
   }
 
+  // The archive operations joined `WebuiHarnessPort` with the F-zone
+  // contract. This fixture has no archive to serve, so it answers with an
+  // empty listing rather than going unimplemented — the port type requires
+  // the member, and an absent method would be a runtime `TypeError` instead.
+  async readWorkspaceArchive() {
+    return { archivePath: "", entries: [], totalEntries: 0, truncated: false };
+  }
+
+  async extractWorkspaceArchive() {
+    return { archivePath: "", destination: "", writtenFiles: 0 };
+  }
+
   async getWorkspaceEnvironment() {
     return { isGitRepo: true, branch: "fixture", changedFiles: 1, insertions: 2, deletions: 1, lineStatsStatus: "ready" as const, canPush: true };
   }
@@ -3440,6 +3452,12 @@ describe("WebUI shutdown order (criterion 7)", () => {
       version() {
         return { version: "0.4.2-shutdown-test", protocolVersion: 1 };
       },
+      async readWorkspaceArchive() {
+        return { archivePath: "", entries: [], totalEntries: 0, truncated: false };
+      },
+      async extractWorkspaceArchive() {
+        return { archivePath: "", destination: "", writtenFiles: 0 };
+      },
       async listSessions() {
         return { sessions: [], hasMore: false };
       },
@@ -3798,6 +3816,12 @@ describe("WebUI shutdown order (criterion 7)", () => {
         versionCalls += 1;
         return { version: "0.4.2-shutdown-gate", protocolVersion: 1 };
       },
+      async readWorkspaceArchive() {
+        return { archivePath: "", entries: [], totalEntries: 0, truncated: false };
+      },
+      async extractWorkspaceArchive() {
+        return { archivePath: "", destination: "", writtenFiles: 0 };
+      },
       async listSessions() {
         return { sessions: [], hasMore: false };
       },

From 49b73600c4f9c249a1995f1105ea2cf0928a15b5 Mon Sep 17 00:00:00 2001
From: probe <probe@local>
Date: Sun, 4 Oct 2026 08:48:45 +0800
Subject: [PATCH 08/21] feat(webui): route archive and HTML previews to their
 own components
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The split left `WorkspaceArchiveView` and `WorkspaceHtmlPreview` unmounted,
because wiring a route to them is a feature rather than a refactor. That
route is added here, once, so the five implementers who follow can each work
inside their own file without three of them editing `WebuiFilePreview` at the
same time.

Both branches are dispatched *before* the read result is consulted, not
after. An archive never becomes text, and an HTML preview is a document the
browser streams rather than a string the panel holds, so waiting on
`readWorkspaceFile` first would either flash a binary error or buffer a
document nobody reads.

`WorkspaceHtmlPreview` now takes the credentialed `fileUrl` instead of the
file content. The server already answers `/workspace-file` with
`Content-Security-Policy: sandbox allow-scripts` for `text/html`, which runs
the document in an opaque origin — the one thing that stops a previewed
artifact from reading `window.__WEBUI_CONFIG__.token` off the page framing
it. Passing the content instead would have put that isolation in two places.
`content` stays available as an optional prop so the view can still refuse a
file whose extension says `.html` but whose bytes are not `text/html`.

973 tests pass; typecheck:client clean.
---
 .../components/WebuiClientFoundationApp.tsx   |  2 +-
 .../components/WorkspaceHtmlPreview.tsx       | 32 ++++++++-----
 .../src/client/components/WorkspacePanels.tsx | 47 +++++++++++++++++--
 3 files changed, 63 insertions(+), 18 deletions(-)

diff --git a/packages/webui/src/client/components/WebuiClientFoundationApp.tsx b/packages/webui/src/client/components/WebuiClientFoundationApp.tsx
index 5e87ab7b7..2222b9619 100644
--- a/packages/webui/src/client/components/WebuiClientFoundationApp.tsx
+++ b/packages/webui/src/client/components/WebuiClientFoundationApp.tsx
@@ -1117,7 +1117,7 @@ export function WebuiClientFoundationApp(
                 </aside>
               </div>
             ) : null}
-            {!homeMode && workspacePanel.open ? <WebuiWorkspacePanel state={workspacePanel} dispatch={dispatchWorkspacePanel} sessionId={selectedSessionId} workspaceDir={selectedSession?.workspaceDir} listWorkspaceFileTree={transport?.listWorkspaceFileTree} readWorkspaceFile={transport?.readWorkspaceFile} readCanvas={transport?.readCanvas} applyCanvas={transport?.applyCanvas} createTerminal={transport?.createTerminal} listTerminals={transport?.listTerminals} writeTerminal={transport?.writeTerminal} disposeTerminal={transport?.disposeTerminal} watchTerminal={transport?.watchTerminal} getWorkspaceReviewSummary={transport?.getWorkspaceReviewSummary} listWorkspaceReviewFileDiffs={transport?.listWorkspaceReviewFileDiffs} searchWorkspaceReviewDiffs={transport?.searchWorkspaceReviewDiffs} onClose={() => dispatchWorkspacePanel({ type: "close-panel" })} /> : null}
+            {!homeMode && workspacePanel.open ? <WebuiWorkspacePanel state={workspacePanel} dispatch={dispatchWorkspacePanel} sessionId={selectedSessionId} workspaceDir={selectedSession?.workspaceDir} listWorkspaceFileTree={transport?.listWorkspaceFileTree} readWorkspaceFile={transport?.readWorkspaceFile} workspaceFileUrl={transport?.workspaceFileUrl} readWorkspaceArchive={transport?.readWorkspaceArchive} extractWorkspaceArchive={transport?.extractWorkspaceArchive} readCanvas={transport?.readCanvas} applyCanvas={transport?.applyCanvas} createTerminal={transport?.createTerminal} listTerminals={transport?.listTerminals} writeTerminal={transport?.writeTerminal} disposeTerminal={transport?.disposeTerminal} watchTerminal={transport?.watchTerminal} getWorkspaceReviewSummary={transport?.getWorkspaceReviewSummary} listWorkspaceReviewFileDiffs={transport?.listWorkspaceReviewFileDiffs} searchWorkspaceReviewDiffs={transport?.searchWorkspaceReviewDiffs} onClose={() => dispatchWorkspacePanel({ type: "close-panel" })} /> : null}
             </>}
           </main>
         </div>
diff --git a/packages/webui/src/client/components/WorkspaceHtmlPreview.tsx b/packages/webui/src/client/components/WorkspaceHtmlPreview.tsx
index 251bfbd58..5a672a5e8 100644
--- a/packages/webui/src/client/components/WorkspaceHtmlPreview.tsx
+++ b/packages/webui/src/client/components/WorkspaceHtmlPreview.tsx
@@ -1,8 +1,8 @@
 // Owns the workspace HTML-preview feature (rendering an .html file inside
 // the workspace panel). Nothing is implemented yet: this file is the seam a
-// different implementer fills in. `WorkspacePanels.tsx` does not mount it yet
-// — `WebuiFilePreview` has no HTML branch to route into it, and adding one
-// would be a feature, not a split.
+// different implementer fills in. The only thing that lives outside it is
+// the dispatch in `WebuiFilePreview`, which routes `.html`/`.htm` here
+// before the read result is consulted.
 
 import type { ReactElement } from "react";
 import type { WebuiWorkspaceFileContent } from "../../server/port.js";
@@ -11,18 +11,26 @@ export type WorkspaceHtmlPreviewProps = {
   /** The file path the preview tab was opened with. */
   readonly path: string;
   /**
-   * The file content as `readWorkspaceFile` returned it. `mimeType` is the
-   * signal a later implementer uses to route `.html` versus `.htm` (and to
-   * refuse anything that is not text/html).
+   * The streamable URL of the file, credential included, as returned by
+   * `transport.workspaceFileUrl`.
+   *
+   * The preview points an iframe at this rather than carrying the document in
+   * a prop. The server already answers `/workspace-file` with
+   * `Content-Security-Policy: sandbox allow-scripts` for `text/html`, which
+   * runs the document in an opaque origin — the one thing that stops a
+   * previewed artifact from reading `window.__WEBUI_CONFIG__.token` off the
+   * page that framed it. Handing the view a string instead would mean
+   * re-implementing that isolation client-side, with two places to keep
+   * agreeing about it.
    */
-  readonly content: WebuiWorkspaceFileContent;
+  readonly fileUrl: string;
   /**
-   * How the document is isolated once it renders. Workspace HTML is
-   * untrusted, so the implementer must default to a sandboxed document
-   * (no same-origin access, no script into the panel) and may only widen it
-   * behind an explicit user choice.
+   * The read result, when the panel already has one. `mimeType` is how the
+   * view refuses a file whose extension says `.html` but whose bytes are
+   * something else: the extension picks the route, and only the runtime
+   * knows what the file actually is.
    */
-  readonly sandbox?: "allow-scripts" | "allow-same-origin" | "none";
+  readonly content?: WebuiWorkspaceFileContent;
 };
 
 /**
diff --git a/packages/webui/src/client/components/WorkspacePanels.tsx b/packages/webui/src/client/components/WorkspacePanels.tsx
index 5705cbc34..90d2225e6 100644
--- a/packages/webui/src/client/components/WorkspacePanels.tsx
+++ b/packages/webui/src/client/components/WorkspacePanels.tsx
@@ -25,6 +25,8 @@ import type {
   WebuiWorkspaceFile,
   WebuiWorkspaceFileContent,
   WebuiWorkspaceGitMutationRequest,
+  WebuiWorkspaceArchiveListing,
+  WebuiWorkspaceArchiveExtractResult,
   WebuiWorkspaceReviewDiffs,
   WebuiWorkspaceReviewSearchResult,
   WebuiWorkspaceReviewSummary,
@@ -41,6 +43,8 @@ import { WebuiIconAgent, WebuiIconCheck, WebuiIconChevronDown, WebuiIconClose, W
 import { FileTree, filterWorkspaceFiles, findWorkspaceFile, getWorkspaceFileParentPaths, mergeWorkspaceFileChildren } from "./WorkspaceFileTree.js";
 import { WorkspaceMediaPreview } from "./WorkspaceMediaPreview.js";
 import { WorkspaceCanvas } from "./WorkspaceCanvas.js";
+import { WorkspaceArchiveView } from "./WorkspaceArchiveView.js";
+import { WorkspaceHtmlPreview } from "./WorkspaceHtmlPreview.js";
 
 export type WebuiTodo = WebuiWorkspaceTodo;
 // `mergeWorkspaceFileChildren` is re-exported below: the file-tree tests
@@ -335,16 +339,46 @@ export function WebuiProgressOverviewPanel({ workspaceDir, isDefaultWorkspace =
   </div>;
 }
 
-export function WebuiFilePreview({ tab, result, codeMode }: {
+const WORKSPACE_ARCHIVE_EXTENSIONS = [".zip", ".tar", ".tgz", ".gz", ".bz2", ".xz", ".7z", ".rar"] as const;
+const WORKSPACE_HTML_EXTENSIONS = [".html", ".htm"] as const;
+
+function hasExtension(path: string, extensions: readonly string[]): boolean {
+  const lower = path.toLowerCase();
+  return extensions.some((extension) => lower.endsWith(extension));
+}
+
+export function isWorkspaceArchivePath(path: string): boolean {
+  return hasExtension(path, WORKSPACE_ARCHIVE_EXTENSIONS);
+}
+
+export function isWorkspaceHtmlPath(path: string): boolean {
+  return hasExtension(path, WORKSPACE_HTML_EXTENSIONS);
+}
+
+export function WebuiFilePreview({ tab, result, codeMode, workspaceFileUrl, readWorkspaceArchive, extractWorkspaceArchive }: {
   readonly tab: Extract<WorkspacePanelTab, { readonly kind: "file-preview" }>;
   readonly result?: { readonly loading: boolean; readonly content?: WebuiWorkspaceFileContent; readonly error?: string };
   readonly codeMode: boolean;
+  readonly workspaceFileUrl?: (request: { readonly workspaceDir: string; readonly path: string }) => string;
+  readonly readWorkspaceArchive?: (request: { readonly workspaceDir: string; readonly path: string; readonly prefix?: string }) => Promise<WebuiWorkspaceArchiveListing>;
+  readonly extractWorkspaceArchive?: (request: { readonly workspaceDir: string; readonly path: string; readonly destination: string; readonly prefix?: string }) => Promise<WebuiWorkspaceArchiveExtractResult>;
 }): ReactElement {
   const previewMarkdown = /\.md$/iu.test(tab.path) && !codeMode;
   const content = result?.content?.content ?? "";
   const language = webuiFileLanguage(tab.path);
+  // Dispatched ahead of the read result on purpose: an archive never becomes
+  // text, and an HTML preview is a stream the browser fetches rather than a
+  // string the panel holds. Waiting on `readWorkspaceFile` first would either
+  // flash a binary error or buffer a document nobody will read.
+  const archive = isWorkspaceArchivePath(tab.path)
+    ? <WorkspaceArchiveView workspaceDir={tab.workspaceDir} path={tab.path} readWorkspaceArchive={readWorkspaceArchive} extractWorkspaceArchive={extractWorkspaceArchive} />
+    : undefined;
+  const html = !archive && isWorkspaceHtmlPath(tab.path) && workspaceFileUrl
+    ? <WorkspaceHtmlPreview path={tab.path} fileUrl={workspaceFileUrl({ workspaceDir: tab.workspaceDir, path: tab.path })} content={result?.content} />
+    : undefined;
   return <div className="webui-workspace-file-document" data-testid="workspace-file-preview" data-file-path={tab.path}>
-      {result?.loading ? <p role="status">正在加载文件…</p>
+      {archive ?? html
+        ?? (result?.loading ? <p role="status">正在加载文件…</p>
         : result?.error ? <p role="alert">{result.error}</p>
           : result?.content?.previewDataUrl ? <WorkspaceMediaPreview path={tab.path} content={result.content} />
             : result?.content?.error ? <p role="alert">{result.content.error}</p>
@@ -354,16 +388,19 @@ export function WebuiFilePreview({ tab, result, codeMode }: {
                 const highlighted = highlightFileLine(line, language);
                 return <span key={lineNumber} id={lineNumber === tab.lineStart ? webuiFileLineTargetId(tab.id, lineNumber) : undefined} tabIndex={lineNumber === tab.lineStart ? -1 : undefined} data-line={lineNumber} data-scroll-target-line={lineNumber === tab.lineStart ? "true" : undefined} className={`webui-file-code-line ${lineNumber >= (tab.lineStart ?? 0) && lineNumber <= (tab.lineEnd ?? tab.lineStart ?? 0) ? "webui-file-preview-line-active" : ""}`} data-line-number={lineNumber} {...(highlighted !== undefined ? { dangerouslySetInnerHTML: { __html: highlighted || " " } } : {})}>{highlighted === undefined ? line || " " : undefined}</span>;
               })}</code></pre>
-                : <p>文件读取能力暂不可用。</p>}
+                : <p>文件读取能力暂不可用。</p>)}
   </div>;
 }
 
-export function WebuiWorkspacePanel({ state, dispatch, sessionId, workspaceDir, listWorkspaceFileTree, readWorkspaceFile, readCanvas, applyCanvas, createTerminal, listTerminals, writeTerminal, disposeTerminal, watchTerminal, watchEvents, getWorkspaceReviewSummary, listWorkspaceReviewFileDiffs, searchWorkspaceReviewDiffs, onClose }: {
+export function WebuiWorkspacePanel({ state, dispatch, sessionId, workspaceDir, listWorkspaceFileTree, readWorkspaceFile, workspaceFileUrl, readWorkspaceArchive, extractWorkspaceArchive, readCanvas, applyCanvas, createTerminal, listTerminals, writeTerminal, disposeTerminal, watchTerminal, watchEvents, getWorkspaceReviewSummary, listWorkspaceReviewFileDiffs, searchWorkspaceReviewDiffs, onClose }: {
   readonly state: WorkspacePanelState;
   readonly dispatch: (command: WorkspacePanelCommand) => void;
   readonly sessionId?: string; readonly workspaceDir?: string;
   readonly listWorkspaceFileTree?: (request: { workspaceDir: string; path?: string }) => Promise<readonly WebuiWorkspaceFile[]>;
   readonly readWorkspaceFile?: (request: { workspaceDir: string; path: string }) => Promise<WebuiWorkspaceFileContent>;
+  readonly workspaceFileUrl?: (request: { readonly workspaceDir: string; readonly path: string }) => string;
+  readonly readWorkspaceArchive?: (request: { readonly workspaceDir: string; readonly path: string; readonly prefix?: string }) => Promise<WebuiWorkspaceArchiveListing>;
+  readonly extractWorkspaceArchive?: (request: { readonly workspaceDir: string; readonly path: string; readonly destination: string; readonly prefix?: string }) => Promise<WebuiWorkspaceArchiveExtractResult>;
   readonly readCanvas?: (request: { sessionId: string }) => Promise<WebuiCanvasDocument>;
   readonly applyCanvas?: (request: { sessionId: string; operation: Record<string, unknown> }) => Promise<unknown>;
   readonly createTerminal?: (request: { workspaceDir: string }) => Promise<{ terminalId: string; status: string }>;
@@ -752,7 +789,7 @@ export function WebuiWorkspacePanel({ state, dispatch, sessionId, workspaceDir,
     <div className="webui-workspace-panel-body">
       <div className="webui-workspace-view">
     {tab === "files" ? <div className="webui-workspace-files-empty" data-testid="workspace-files-empty"><WebuiIconFolder className="size-8" /><strong>查看文件</strong><p>从工作区目录树中选择文件</p></div> : null}
-    {tab === "file-preview" && activeTab?.kind === "file-preview" ? <WebuiFilePreview tab={activeTab} result={fileResults[activeTab.id]} codeMode={fileCodeMode} /> : null}
+    {tab === "file-preview" && activeTab?.kind === "file-preview" ? <WebuiFilePreview tab={activeTab} result={fileResults[activeTab.id]} codeMode={fileCodeMode} workspaceFileUrl={workspaceFileUrl} readWorkspaceArchive={readWorkspaceArchive} extractWorkspaceArchive={extractWorkspaceArchive} /> : null}
     {tab === "review" && activeTab?.kind === "review" && activeTab.source === "workspace" ? <div className="webui-turn-review" data-testid="workspace-review">
       {reviewSummary?.tabId !== activeTab.id || reviewSummary.loading && !reviewSummary.summary ? <p className="webui-turn-review-empty" role="status">正在收集变更…</p> : reviewSummary.error && !reviewSummary.summary ? <p className="webui-turn-review-empty" role="alert">{reviewSummary.error}</p> : reviewSummary.summary ? <>
         <div className="webui-turn-review-summary"><span>{reviewSummary.summary.totals.files} 个文件</span><span className="webui-diff-header-stats"><span className="webui-diff-add">+{reviewSummary.summary.totals.additions}</span>{reviewSummary.summary.totals.deletions ? <span className="webui-diff-del">-{reviewSummary.summary.totals.deletions}</span> : null}</span></div>

From 66217103a8d40c5581ab7c5a5f272d65bdc0e3ca Mon Sep 17 00:00:00 2001
From: probe <probe@local>
Date: Sun, 4 Oct 2026 08:49:45 +0800
Subject: [PATCH 09/21] feat(webui): stat workspace files so the tree can
 report size and mtime

---
 packages/webui/src/server/host.ts | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/packages/webui/src/server/host.ts b/packages/webui/src/server/host.ts
index 18cc83442..d546e63c0 100644
--- a/packages/webui/src/server/host.ts
+++ b/packages/webui/src/server/host.ts
@@ -12,6 +12,8 @@
 // directly at process start.
 
 import { posix as pathPosix } from "node:path";
+import { stat } from "node:fs/promises";
+import path from "node:path";
 import { WEBUI_PROTOCOL_VERSION } from "./envelope.js";
 import type {
   WebuiHarnessPort,
@@ -422,7 +424,24 @@ export function createHarnessPortFromHost(
       return { success: await requireCliService(host).clearGoal(request.sessionId) };
     },
     async listWorkspaceFileTree(request) {
-      return requireCliService(host).listWorkspaceFileTree!(request) as Promise<readonly WebuiWorkspaceFile[]>;
+      const tree = await requireCliService(host).listWorkspaceFileTree!(request) as readonly WebuiWorkspaceFile[];
+      // The runtime reports names and shape but no file facts, while the port
+      // contract now promises `size` and `modifiedAt` for the panel's metadata
+      // column. Statted here because this is the one place that sees both the
+      // tree and the filesystem — extending the runtime would put the change
+      // outside this package, and a tree that silently omits the fields would
+      // leave the column blank rather than failing loudly.
+      return Promise.all(tree.map(async (entry) => {
+        if (entry.type === "directory") return entry;
+        try {
+          const stats = await stat(path.join(request.workspaceDir, entry.path));
+          return { ...entry, size: stats.size, modifiedAt: stats.mtimeMs };
+        } catch {
+          // A file that vanished or is unreadable keeps its entry and loses
+          // only the metadata; dropping it from the tree would be a lie.
+          return entry;
+        }
+      }));
     },
     // Checked rather than asserted: the siblings above use `!` because their
     // runtime capability has shipped, but archive reading and extraction are

From e382bc073e5626f1c50268ffd4c09199f474443e Mon Sep 17 00:00:00 2001
From: probe <probe@local>
Date: Sun, 4 Oct 2026 08:50:26 +0800
Subject: [PATCH 10/21] fix(webui): hand the credentialed file URL to the media
 preview

previewDataUrl is never populated by anything in this repo, so the image
preview was a branch that could never render. The URL route works, and it is
the only one that could ever serve video or audio, since a base64 data: URL
cannot be range-requested and the browser could not scrub a progress bar.

Both sources stay accepted so the data-URL path still works for a runtime
that does populate it, with the URL taking precedence.
---
 .../components/WorkspaceMediaPreview.tsx      | 51 +++++++++++++------
 .../src/client/components/WorkspacePanels.tsx |  2 +-
 2 files changed, 37 insertions(+), 16 deletions(-)

diff --git a/packages/webui/src/client/components/WorkspaceMediaPreview.tsx b/packages/webui/src/client/components/WorkspaceMediaPreview.tsx
index c93ac9d9b..155667a99 100644
--- a/packages/webui/src/client/components/WorkspaceMediaPreview.tsx
+++ b/packages/webui/src/client/components/WorkspaceMediaPreview.tsx
@@ -1,27 +1,48 @@
-// Owns the workspace media-preview feature: the image branch of the file
-// preview, moved out of `WebuiFilePreview`. A different implementer works in
-// this file; `WorkspacePanels.tsx` only imports the component from it.
+// Owns the workspace media-preview feature: the image, audio and video
+// branches of the file preview, moved out of `WebuiFilePreview`. A different
+// implementer works in this file; `WorkspacePanels.tsx` only imports the
+// components from it.
 
 import type { ReactElement } from "react";
 import type { WebuiWorkspaceFileContent } from "../../server/port.js";
 
+export type WorkspaceMediaPreviewProps = {
+  /** The file path the preview tab was opened with, used for `alt` text. */
+  readonly path: string;
+  /** The file content as `readWorkspaceFile` returned it. */
+  readonly content: WebuiWorkspaceFileContent;
+  /**
+   * The streamable URL of the same file, credential included, as returned by
+   * `transport.workspaceFileUrl`.
+   *
+   * This is what the media elements point at, and it is why the props are
+   * both here. `content.previewDataUrl` is a base64 payload that the runtime
+   * never populates — nothing in this repo writes that field — so branching on
+   * it alone yields a preview that can never render. The URL route is the one
+   * that works, and it is also the only one that can serve `<video>`/`<audio>`
+   * at all: a base64 `data:` URL cannot be range-requested, so the browser
+   * could not scrub a progress bar or start playback before the whole file
+   * arrived.
+   *
+   * Absent when the transport does not expose the route; render the
+   * unavailable state rather than a media element pointed at nothing.
+   */
+  readonly fileUrl?: string;
+};
+
 /**
  * Image preview for one workspace file.
  *
  * Audio and video are not implemented yet. They belong here as sibling
- * exports (`WorkspaceAudioPreview` / `WorkspaceVideoPreview`) taking the
- * same `path` + `content` props, dispatched from `content.mimeType`, so
+ * exports (`WorkspaceAudioPreview` / `WorkspaceVideoPreview`) taking the same
+ * `path` + `content` + `fileUrl` props, dispatched from `content.mimeType`, so
  * `WebuiFilePreview` never needs to learn about a new media kind.
  *
- * Returns `null` when the content carries no `previewDataUrl`, so a caller
- * that branches on it never renders an empty media element.
+ * Returns `null` when neither source can produce a preview, so a caller that
+ * branches on it never renders an empty media element.
  */
-export function WorkspaceMediaPreview({ path, content }: {
-  /** The file path the preview tab was opened with, used for `alt` text. */
-  readonly path: string;
-  /** The file content as `readWorkspaceFile` returned it. */
-  readonly content: WebuiWorkspaceFileContent;
-}): ReactElement | null {
-  if (!content.previewDataUrl) return null;
-  return <img className="webui-workspace-image-preview" src={content.previewDataUrl} alt={path.split("/").at(-1) ?? path} data-testid="workspace-image-preview" />;
+export function WorkspaceMediaPreview({ path, content, fileUrl }: WorkspaceMediaPreviewProps): ReactElement | null {
+  const source = fileUrl ?? content.previewDataUrl;
+  if (!source) return null;
+  return <img className="webui-workspace-image-preview" src={source} alt={path.split("/").at(-1) ?? path} data-testid="workspace-image-preview" />;
 }
diff --git a/packages/webui/src/client/components/WorkspacePanels.tsx b/packages/webui/src/client/components/WorkspacePanels.tsx
index 90d2225e6..9d3a4f43e 100644
--- a/packages/webui/src/client/components/WorkspacePanels.tsx
+++ b/packages/webui/src/client/components/WorkspacePanels.tsx
@@ -380,7 +380,7 @@ export function WebuiFilePreview({ tab, result, codeMode, workspaceFileUrl, read
       {archive ?? html
         ?? (result?.loading ? <p role="status">正在加载文件…</p>
         : result?.error ? <p role="alert">{result.error}</p>
-          : result?.content?.previewDataUrl ? <WorkspaceMediaPreview path={tab.path} content={result.content} />
+          : result?.content?.previewDataUrl || workspaceFileUrl ? <WorkspaceMediaPreview path={tab.path} content={result.content} fileUrl={workspaceFileUrl?.({ workspaceDir: tab.workspaceDir, path: tab.path })} />
             : result?.content?.error ? <p role="alert">{result.content.error}</p>
             : result?.content?.type === "binary" ? <p>无法在文本预览中显示二进制文件。</p>
               : result?.content ? previewMarkdown ? <WebuiMarkdown source={content} /> : <pre className="webui-file-code"><code className={language ? `hljs language-${language}` : ""}>{content.split("\n").map((line, index) => {

From 12e851213354b014df07fed72cc90e1ea19fd3b7 Mon Sep 17 00:00:00 2001
From: probe <probe@local>
Date: Sun, 4 Oct 2026 08:51:10 +0800
Subject: [PATCH 11/21] fix(webui): gate the media preview on the mime type,
 not on URL availability

Gating on "a URL exists" was wrong in both directions: it let `result` go
undefined under the type checker, and since the file URL is derivable for any
path it pointed an `<img>` at an executable and rendered a broken image.

`isMediaContent` now decides, from the runtime's `mimeType` where one is
present and from the extension otherwise, so the same check holds for a
binary result and for a text result that carries no mime. The check lives
with the component rather than in the container, which keeps the container
from learning what counts as media.
---
 .../client/components/WorkspaceMediaPreview.tsx   | 15 +++++++++++++++
 .../src/client/components/WorkspacePanels.tsx     |  4 ++--
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/packages/webui/src/client/components/WorkspaceMediaPreview.tsx b/packages/webui/src/client/components/WorkspaceMediaPreview.tsx
index 155667a99..d508395ef 100644
--- a/packages/webui/src/client/components/WorkspaceMediaPreview.tsx
+++ b/packages/webui/src/client/components/WorkspaceMediaPreview.tsx
@@ -30,6 +30,21 @@ export type WorkspaceMediaPreviewProps = {
   readonly fileUrl?: string;
 };
 
+/**
+ * Whether a read result is media this component should render at all.
+ *
+ * The file URL is derivable for *any* path, so the container cannot gate on
+ * "a URL exists" — that would point an `<img>` at an executable and render a
+ * broken image. The decision belongs to the runtime's `mimeType` where there
+ * is one, and falls back to the extension for the text results that carry no
+ * mime, so the same check holds on both sides of the read.
+ */
+export function isMediaContent(content: Pick<WebuiWorkspaceFileContent, "mimeType">, path: string): boolean {
+  const mimeType = content.mimeType?.toLowerCase();
+  if (mimeType) return /^(image|video|audio)\//u.test(mimeType);
+  return /\.(png|jpe?g|gif|webp|avif|bmp|ico|svg|mp4|webm|ogv|mov|mp3|wav|ogg|m4a|aac|flac)$/iu.test(path);
+}
+
 /**
  * Image preview for one workspace file.
  *
diff --git a/packages/webui/src/client/components/WorkspacePanels.tsx b/packages/webui/src/client/components/WorkspacePanels.tsx
index 9d3a4f43e..cb5ad9678 100644
--- a/packages/webui/src/client/components/WorkspacePanels.tsx
+++ b/packages/webui/src/client/components/WorkspacePanels.tsx
@@ -41,7 +41,7 @@ import {
 } from "../projection/workspace-progress.js";
 import { WebuiIconAgent, WebuiIconCheck, WebuiIconChevronDown, WebuiIconClose, WebuiIconDiffFile, WebuiIconFile, WebuiIconFolder, WebuiIconRunLocation, WebuiIconSearch, WebuiIconSidebarToggle, WebuiIconWorkspaceCanvas, WebuiIconWorkspaceExpand, WebuiIconWorkspaceReview, WebuiIconWorkspaceTerminal } from "../icons.js";
 import { FileTree, filterWorkspaceFiles, findWorkspaceFile, getWorkspaceFileParentPaths, mergeWorkspaceFileChildren } from "./WorkspaceFileTree.js";
-import { WorkspaceMediaPreview } from "./WorkspaceMediaPreview.js";
+import { WorkspaceMediaPreview, isMediaContent } from "./WorkspaceMediaPreview.js";
 import { WorkspaceCanvas } from "./WorkspaceCanvas.js";
 import { WorkspaceArchiveView } from "./WorkspaceArchiveView.js";
 import { WorkspaceHtmlPreview } from "./WorkspaceHtmlPreview.js";
@@ -380,7 +380,7 @@ export function WebuiFilePreview({ tab, result, codeMode, workspaceFileUrl, read
       {archive ?? html
         ?? (result?.loading ? <p role="status">正在加载文件…</p>
         : result?.error ? <p role="alert">{result.error}</p>
-          : result?.content?.previewDataUrl || workspaceFileUrl ? <WorkspaceMediaPreview path={tab.path} content={result.content} fileUrl={workspaceFileUrl?.({ workspaceDir: tab.workspaceDir, path: tab.path })} />
+          : result?.content && isMediaContent(result.content, tab.path) ? <WorkspaceMediaPreview path={tab.path} content={result.content} fileUrl={workspaceFileUrl?.({ workspaceDir: tab.workspaceDir, path: tab.path })} />
             : result?.content?.error ? <p role="alert">{result.content.error}</p>
             : result?.content?.type === "binary" ? <p>无法在文本预览中显示二进制文件。</p>
               : result?.content ? previewMarkdown ? <WebuiMarkdown source={content} /> : <pre className="webui-file-code"><code className={language ? `hljs language-${language}` : ""}>{content.split("\n").map((line, index) => {

From 24283f457054638b79637fcd527a07a206513c2e Mon Sep 17 00:00:00 2001
From: probe <probe@local>
Date: Sun, 4 Oct 2026 08:54:42 +0800
Subject: [PATCH 12/21] feat(webui): dispatch the workspace media preview to
 image, video and audio
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`WorkspacePanels` imports one component name and already gates the file on
`isMediaContent`, so the media kind is resolved inside `WorkspaceMediaPreview`
rather than at the call site: the container's call site does not change, and
adding a kind later does not mean editing a file four other implementers own.
The kind comes from `content.mimeType` where the runtime supplied one, and from
the extension for the text reads that carry no mime. A present mime stays
authoritative in both directions — a non-media mime yields no kind instead of
falling back to the extension, which is the refusal `isMediaContent` already
makes. `isMediaContent` is now that same question, so the gate and the dispatch
cannot disagree.

Audio and video are sibling exports taking the same props, each pointing at
`fileUrl` — the `GET /workspace-file` route, the only source that answers a
range request. Both carry `controls` and `preload="metadata"`, neither
autoplays, and both are named after the file's basename.

Without a `fileUrl` neither renders an element at all: a base64 `data:` URL
cannot be range-requested, so a control bar over it could neither be scrubbed
nor start before the whole file was inlined. They render an explicit
unavailable notice instead. `content.previewDataUrl` stays accepted where it
can work — the image branch, which a browser fetches atomically — with
`fileUrl` taking precedence; an empty `fileUrl` counts as no URL and does not
shadow it.

Every element carries an accessible name and an `onError` handler, so a failed
load is a visible message rather than a silent blank box. The dispatcher keys
the child on `path` so one file's failure does not stick to the next. No new
class names: video reuses the one existing contained-media rule, and the
notices use tokens already in the stylesheet.
---
 .../components/WorkspaceMediaPreview.tsx      | 175 ++++++++++++++++--
 .../webui-workspace-media-preview.test.tsx    | 169 +++++++++++++++++
 2 files changed, 330 insertions(+), 14 deletions(-)
 create mode 100644 packages/webui/test/unit/webui-workspace-media-preview.test.tsx

diff --git a/packages/webui/src/client/components/WorkspaceMediaPreview.tsx b/packages/webui/src/client/components/WorkspaceMediaPreview.tsx
index d508395ef..27e15fe0b 100644
--- a/packages/webui/src/client/components/WorkspaceMediaPreview.tsx
+++ b/packages/webui/src/client/components/WorkspaceMediaPreview.tsx
@@ -1,9 +1,8 @@
 // Owns the workspace media-preview feature: the image, audio and video
-// branches of the file preview, moved out of `WebuiFilePreview`. A different
-// implementer works in this file; `WorkspacePanels.tsx` only imports the
-// components from it.
+// branches of the file preview, moved out of `WebuiFilePreview`.
+// `WorkspacePanels.tsx` only imports the components from it.
 
-import type { ReactElement } from "react";
+import { useState, type ReactElement } from "react";
 import type { WebuiWorkspaceFileContent } from "../../server/port.js";
 
 export type WorkspaceMediaPreviewProps = {
@@ -30,6 +29,43 @@ export type WorkspaceMediaPreviewProps = {
   readonly fileUrl?: string;
 };
 
+/**
+ * Extension fallbacks for the read results that carry no `mimeType` (the text
+ * reads). Same lists `isMediaContent` has always gated on, split per kind so
+ * the dispatcher can tell them apart; the mime, when the runtime supplies one,
+ * wins over these.
+ */
+const MEDIA_EXTENSIONS = [
+  ["image", /\.(png|jpe?g|gif|webp|avif|bmp|ico|svg)$/iu],
+  ["video", /\.(mp4|webm|ogv|mov)$/iu],
+  ["audio", /\.(mp3|wav|ogg|m4a|aac|flac)$/iu],
+] as const;
+
+type MediaKind = (typeof MEDIA_EXTENSIONS)[number][0];
+
+/**
+ * Which media preview a read result belongs to, from the runtime's `mimeType`
+ * where there is one and from the extension otherwise.
+ *
+ * A present mime is authoritative in both directions: a `mimeType` outside
+ * the three media families yields no kind rather than falling back to the
+ * extension, which is the same refusal `isMediaContent` makes — the caller has
+ * already decided this file is media, and re-deriving a kind from the
+ * extension would let a non-media mime render as a player.
+ */
+function mediaKind(content: Pick<WebuiWorkspaceFileContent, "mimeType">, path: string): MediaKind | undefined {
+  const mimeType = content.mimeType?.toLowerCase();
+  if (mimeType) {
+    const kind = mimeType.slice(0, mimeType.indexOf("/"));
+    if (kind === "image" || kind === "video" || kind === "audio") return kind;
+    return undefined;
+  }
+  for (const [kind, pattern] of MEDIA_EXTENSIONS) {
+    if (pattern.test(path)) return kind;
+  }
+  return undefined;
+}
+
 /**
  * Whether a read result is media this component should render at all.
  *
@@ -40,24 +76,135 @@ export type WorkspaceMediaPreviewProps = {
  * mime, so the same check holds on both sides of the read.
  */
 export function isMediaContent(content: Pick<WebuiWorkspaceFileContent, "mimeType">, path: string): boolean {
-  const mimeType = content.mimeType?.toLowerCase();
-  if (mimeType) return /^(image|video|audio)\//u.test(mimeType);
-  return /\.(png|jpe?g|gif|webp|avif|bmp|ico|svg|mp4|webm|ogv|mov|mp3|wav|ogg|m4a|aac|flac)$/iu.test(path);
+  return mediaKind(content, path) !== undefined;
+}
+
+/** The file name a media element is named after; a full path is not a name. */
+function mediaName(path: string): string {
+  return path.split("/").at(-1) || path;
 }
 
+/** Shown instead of a player that cannot work, and after a load failure. */
+export function WorkspaceMediaNotice({
+  name,
+  reason,
+  role = "status",
+}: {
+  readonly name: string;
+  readonly reason: string;
+  /** `alert` for a failure, `status` for a state that was never available. */
+  readonly role?: "status" | "alert";
+}): ReactElement {
+  return (
+    <p role={role} style={{ margin: "var(--spacing_16)", color: "var(--text_default_tertiary)" }}>
+      {`${name} 预览不可用：${reason}`}
+    </p>
+  );
+}
+
+/**
+ * Why audio and video refuse an inline-only source. Kept here so the image
+ * branch can stay the one that accepts `previewDataUrl` without either branch
+ * having to re-argue it.
+ */
+const NO_RANGEABLE_SOURCE =
+  "没有可按范围请求的文件地址，只有内联数据，进度条无法拖动也无法起播。";
+
 /**
  * Image preview for one workspace file.
  *
- * Audio and video are not implemented yet. They belong here as sibling
- * exports (`WorkspaceAudioPreview` / `WorkspaceVideoPreview`) taking the same
- * `path` + `content` + `fileUrl` props, dispatched from `content.mimeType`, so
- * `WebuiFilePreview` never needs to learn about a new media kind.
+ * The one branch that accepts `content.previewDataUrl`: a browser fetches a
+ * `data:` image atomically, so an inline source renders here even though it
+ * cannot stream. `fileUrl` wins where both are present.
  *
  * Returns `null` when neither source can produce a preview, so a caller that
  * branches on it never renders an empty media element.
  */
-export function WorkspaceMediaPreview({ path, content, fileUrl }: WorkspaceMediaPreviewProps): ReactElement | null {
-  const source = fileUrl ?? content.previewDataUrl;
+export function WorkspaceImagePreview({ path, content, fileUrl }: WorkspaceMediaPreviewProps): ReactElement | null {
+  const [failed, setFailed] = useState(false);
+  // `||`, not `??`: an empty `fileUrl` is no URL, and must not shadow the
+  // fallback the same way `??` would keep it.
+  const source = fileUrl || content.previewDataUrl;
   if (!source) return null;
-  return <img className="webui-workspace-image-preview" src={source} alt={path.split("/").at(-1) ?? path} data-testid="workspace-image-preview" />;
+  const name = mediaName(path);
+  if (failed) return <WorkspaceMediaNotice name={name} role="alert" reason="图片加载失败。" />;
+  return (
+    <img
+      className="webui-workspace-image-preview"
+      src={source}
+      alt={name}
+      data-testid="workspace-image-preview"
+      onError={() => setFailed(true)}
+    />
+  );
+}
+
+/**
+ * Video preview for one workspace file.
+ *
+ * `preload="metadata"` rather than `auto`: the panel should not pull a whole
+ * video down to show a tab. No `autoPlay` — a preview that starts making noise
+ * when a tab is opened is not a preview.
+ */
+export function WorkspaceVideoPreview({ path, fileUrl }: WorkspaceMediaPreviewProps): ReactElement {
+  const [failed, setFailed] = useState(false);
+  const name = mediaName(path);
+  if (!fileUrl) return <WorkspaceMediaNotice name={name} reason={NO_RANGEABLE_SOURCE} />;
+  if (failed) return <WorkspaceMediaNotice name={name} role="alert" reason="视频加载失败。" />;
+  return (
+    <video
+      // The one existing media rule in the stylesheet is sized and centred for
+      // a contained element, which is what a video frame needs; no new class.
+      className="webui-workspace-image-preview"
+      style={{ width: "100%" }}
+      src={fileUrl}
+      controls
+      preload="metadata"
+      aria-label={name}
+      data-testid="workspace-video-preview"
+      onError={() => setFailed(true)}
+    />
+  );
+}
+
+/**
+ * Audio preview for one workspace file. Same contract as the video branch:
+ * `fileUrl` only, `preload="metadata"`, no autoplay, named after the file.
+ */
+export function WorkspaceAudioPreview({ path, fileUrl }: WorkspaceMediaPreviewProps): ReactElement {
+  const [failed, setFailed] = useState(false);
+  const name = mediaName(path);
+  if (!fileUrl) return <WorkspaceMediaNotice name={name} reason={NO_RANGEABLE_SOURCE} />;
+  if (failed) return <WorkspaceMediaNotice name={name} role="alert" reason="音频加载失败。" />;
+  return (
+    <audio
+      style={{ width: "100%" }}
+      src={fileUrl}
+      controls
+      preload="metadata"
+      aria-label={name}
+      data-testid="workspace-audio-preview"
+      onError={() => setFailed(true)}
+    />
+  );
+}
+
+/**
+ * Media preview for one workspace file: the dispatcher the container imports.
+ *
+ * `WorkspacePanels` already gates on `isMediaContent` and already hands the
+ * same three props to one component name, so the kind is resolved here rather
+ * than at the call site — adding a media kind must not mean editing the
+ * container. The child is keyed on `path` so a failed preview does not keep
+ * its error while the same tab is pointed at a different file.
+ *
+ * Returns `null` for a content that is not media at all, so a caller that
+ * branches on it never renders an empty media element.
+ */
+export function WorkspaceMediaPreview(props: WorkspaceMediaPreviewProps): ReactElement | null {
+  const kind = mediaKind(props.content, props.path);
+  if (kind === "image") return <WorkspaceImagePreview key={props.path} {...props} />;
+  if (kind === "video") return <WorkspaceVideoPreview key={props.path} {...props} />;
+  if (kind === "audio") return <WorkspaceAudioPreview key={props.path} {...props} />;
+  return null;
 }
diff --git a/packages/webui/test/unit/webui-workspace-media-preview.test.tsx b/packages/webui/test/unit/webui-workspace-media-preview.test.tsx
new file mode 100644
index 000000000..853fcc8e3
--- /dev/null
+++ b/packages/webui/test/unit/webui-workspace-media-preview.test.tsx
@@ -0,0 +1,169 @@
+// Unit tests for the workspace media preview (`WorkspaceMediaPreview.tsx`).
+//
+// Rendered through `renderToStaticMarkup` — the project's SSR test convention
+// (see `workspace-panel-state.test.ts`). That does not run effects, so the
+// error path is asserted by invoking the exported notice component directly,
+// and everything else by the markup the dispatcher emits.
+//
+// The clauses these pin shut:
+//   * dispatch is decided by `content.mimeType`, falling back to the
+//     extension, and the container's call site never changes;
+//   * `fileUrl` is the source a media element points at, with
+//     `content.previewDataUrl` as an image-only fallback;
+//   * audio/video with no `fileUrl` render an unavailable state, never a
+//     control bar that cannot scrub;
+//   * no media element is emitted with an empty `src`.
+
+import { describe, expect, it } from "vitest";
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import {
+  isMediaContent,
+  WorkspaceAudioPreview,
+  WorkspaceMediaNotice,
+  WorkspaceMediaPreview,
+  WorkspaceVideoPreview,
+} from "../../src/client/components/WorkspaceMediaPreview.js";
+
+const FILE_URL = "http://127.0.0.1:8787/workspace-file?token=t";
+const DATA_URL = "data:image/png;base64,iVBORw0KGgo=";
+
+function render(props: {
+  readonly path: string;
+  readonly mimeType?: string;
+  readonly previewDataUrl?: string;
+  readonly fileUrl?: string;
+}): string {
+  const { mimeType, previewDataUrl, ...rest } = props;
+  return renderToStaticMarkup(
+    createElement(WorkspaceMediaPreview, {
+      ...rest,
+      content: { type: mimeType ? "binary" : "text", content: "", mimeType, previewDataUrl },
+    }),
+  );
+}
+
+describe("workspace media preview", () => {
+  it("renders an image from the file URL and keeps the image test id", () => {
+    const markup = render({ path: "docs/diagram.png", mimeType: "image/png", fileUrl: FILE_URL });
+    expect(markup).toContain('data-testid="workspace-image-preview"');
+    expect(markup).toContain(`src="${FILE_URL}"`);
+    expect(markup).toContain('class="webui-workspace-image-preview"');
+    // The accessible name is the file name, not the path it was opened with.
+    expect(markup).toContain('alt="diagram.png"');
+  });
+
+  it("prefers the file URL and falls back to the inline data URL for an image", () => {
+    expect(render({ path: "a.png", mimeType: "image/png", fileUrl: FILE_URL, previewDataUrl: DATA_URL })).toContain(
+      `src="${FILE_URL}"`,
+    );
+    const inline = render({ path: "a.png", mimeType: "image/png", previewDataUrl: DATA_URL });
+    expect(inline).toContain(`src="${DATA_URL}"`);
+    expect(inline).toContain('data-testid="workspace-image-preview"');
+  });
+
+  it("renders no image element when neither source is present", () => {
+    expect(render({ path: "a.png", mimeType: "image/png" })).toBe("");
+    // An empty `fileUrl` is no URL and must not shadow the fallback.
+    expect(render({ path: "a.png", mimeType: "image/png", fileUrl: "" })).toBe("");
+  });
+
+  it("renders a video player off the file URL with metadata preload and no autoplay", () => {
+    const markup = render({ path: "clips/demo.mp4", mimeType: "video/mp4", fileUrl: FILE_URL });
+    expect(markup).toContain("<video");
+    expect(markup).toContain(`src="${FILE_URL}"`);
+    expect(markup).toContain('controls=""');
+    expect(markup).toContain('preload="metadata"');
+    expect(markup).toContain('aria-label="demo.mp4"');
+    expect(markup).toContain('data-testid="workspace-video-preview"');
+    expect(markup).not.toContain("autoplay");
+    expect(markup).not.toContain("<img");
+  });
+
+  it("renders an audio player off the file URL with metadata preload and no autoplay", () => {
+    const markup = render({ path: "audio/voice.mp3", mimeType: "audio/mpeg", fileUrl: FILE_URL });
+    expect(markup).toContain("<audio");
+    expect(markup).toContain(`src="${FILE_URL}"`);
+    expect(markup).toContain('controls=""');
+    expect(markup).toContain('preload="metadata"');
+    expect(markup).toContain('aria-label="voice.mp3"');
+    expect(markup).toContain('data-testid="workspace-audio-preview"');
+    expect(markup).not.toContain("autoplay");
+  });
+
+  it("routes on the extension when the read result carries no mime type", () => {
+    expect(render({ path: "out/demo.webm", fileUrl: FILE_URL })).toContain("<video");
+    expect(render({ path: "out/voice.wav", fileUrl: FILE_URL })).toContain("<audio");
+    expect(render({ path: "out/photo.avif", fileUrl: FILE_URL })).toContain("<img");
+    // The runtime may report a mime in any case; a `VIDEO/MP4` still routes.
+    expect(isMediaContent({ mimeType: "VIDEO/MP4" }, "clip.mp4")).toBe(true);
+  });
+
+  it("refuses an inline-only audio or video instead of a dead control bar", () => {
+    // A base64 `data:` URL cannot be range-requested: the progress bar could
+    // not be scrubbed and playback could not start before the whole file was
+    // inlined into the document. So no element at all, only the notice.
+    const audio = render({ path: "voice.mp3", mimeType: "audio/mpeg", previewDataUrl: "data:audio/mpeg;base64,AAAA" });
+    expect(audio).not.toContain("<audio");
+    expect(audio).toContain('role="status"');
+    expect(audio).toContain("voice.mp3");
+    expect(audio).toContain("内联数据");
+
+    const video = render({ path: "demo.mp4", mimeType: "video/mp4", previewDataUrl: "data:video/mp4;base64,AAAA" });
+    expect(video).not.toContain("<video");
+    expect(video).toContain('role="status"');
+
+    // No source of any kind, and an empty URL, are the same unavailable state.
+    expect(render({ path: "demo.mp4", mimeType: "video/mp4" })).not.toContain("<video");
+    expect(render({ path: "demo.mp4", mimeType: "video/mp4", fileUrl: "" })).not.toContain("<video");
+  });
+
+  it("shows a load failure instead of a silent blank media box", () => {
+    // The error is state driven by `onError`, which static rendering never
+    // fires, so the message the element hands over to is asserted directly —
+    // and the role is what makes it announced rather than merely visible.
+    const failed = renderToStaticMarkup(
+      createElement(WorkspaceMediaNotice, { name: "demo.mp4", reason: "视频加载失败。", role: "alert" }),
+    );
+    expect(failed).toContain('role="alert"');
+    expect(failed).toContain("demo.mp4");
+    expect(failed).toContain("视频加载失败。");
+
+    const unavailable = renderToStaticMarkup(
+      createElement(WorkspaceMediaNotice, { name: "voice.mp3", reason: "没有可按范围请求的文件地址。" }),
+    );
+    expect(unavailable).toContain('role="status"');
+  });
+
+  it("leaves a non-media file to the caller", () => {
+    // The gate in `WorkspacePanels` is the same question `isMediaContent`
+    // answers; a file it refuses never reaches the dispatcher, and if it is
+    // called anyway it renders nothing rather than pointing a player at it.
+    expect(isMediaContent({ mimeType: "application/pdf" }, "docs/spec.pdf")).toBe(false);
+    expect(isMediaContent({ mimeType: "application/octet-stream" }, "run.sh")).toBe(false);
+    expect(render({ path: "docs/spec.pdf", mimeType: "application/pdf", fileUrl: FILE_URL })).toBe("");
+    expect(render({ path: "docs/notes.txt", fileUrl: FILE_URL })).toBe("");
+  });
+
+  it("keeps the audio and video siblings renderable on their own props", () => {
+    // The container never calls these, but they are the exports a caller
+    // building a custom preview would reach for, so their prop contract is
+    // asserted rather than left to the dispatcher's spread.
+    const video = renderToStaticMarkup(
+      createElement(WorkspaceVideoPreview, {
+        path: "a/b/clip.mp4",
+        content: { type: "binary", content: "", mimeType: "video/mp4" },
+        fileUrl: FILE_URL,
+      }),
+    );
+    const audio = renderToStaticMarkup(
+      createElement(WorkspaceAudioPreview, {
+        path: "a/b/tone.mp3",
+        content: { type: "binary", content: "", mimeType: "audio/mpeg" },
+        fileUrl: FILE_URL,
+      }),
+    );
+    expect(video).toContain('aria-label="clip.mp4"');
+    expect(audio).toContain('aria-label="tone.mp3"');
+  });
+});

From 66a14af3c88ddf87eaf9f3acd418ffefb02554b1 Mon Sep 17 00:00:00 2001
From: probe <probe@local>
Date: Sun, 4 Oct 2026 08:54:58 +0800
Subject: [PATCH 13/21] feat(webui): show size and mtime on workspace file tree
 rows
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Renders the size and last-modified metadata the host already stats, in a
right-aligned column beside the file name. `WebuiWorkspaceFile.size` and
`.modifiedAt` are optional by contract — absent for directories, and absent
for any runtime that does not stat — so each half is formatted on its own and
the column is dropped entirely when neither produced a value. A non-finite
byte count, a negative one, or an out-of-range epoch renders nothing rather
than "undefined", "NaN" or "Invalid Date". Directories never reach the
column: a directory's byte count is meaningless.

Sizes use binary units (1 KB = 1024 B) with a space before the unit, whole
bytes below the kilobyte, and one decimal place from KB up. The displayed
value is rounded before the unit is promoted, so 1048575 B reads "1 MB"
instead of the "1024 KB" that promoting on the raw value produces.

Timestamps are fixed-width ISO fields in UTC, "YYYY-MM-DD HH:mm", built from
the UTC date getters rather than toLocaleString: the locale formatters follow
the host locale and timezone, so the same file would read differently on two
machines and assertions on the text would be environment-dependent. Seconds
are dropped because a tree is read at a glance.

The row was already a flex container, so no stylesheet change was needed. The
name moves into a `min-w-0 flex-1 truncate` box and the column is
`shrink-0`, which lets a long name truncate instead of pushing the metadata
off the row. Row class names, aria-* attributes, the click handler, the lazy
directory load and the selection/expansion state are untouched.

The new unit test is not registered in test/vitest-suites.json; that
allowlist is shared, so it is left to the suite owner.
---
 .../client/components/WorkspaceFileTree.tsx   |  66 +++++++-
 .../unit/webui-workspace-file-tree.test.tsx   | 155 ++++++++++++++++++
 2 files changed, 220 insertions(+), 1 deletion(-)
 create mode 100644 packages/webui/test/unit/webui-workspace-file-tree.test.tsx

diff --git a/packages/webui/src/client/components/WorkspaceFileTree.tsx b/packages/webui/src/client/components/WorkspaceFileTree.tsx
index 0e49e06a8..9e79c420c 100644
--- a/packages/webui/src/client/components/WorkspaceFileTree.tsx
+++ b/packages/webui/src/client/components/WorkspaceFileTree.tsx
@@ -47,12 +47,76 @@ export function getWorkspaceFileParentPaths(path: string): string[] {
   return segments.slice(0, -1).map((_, index) => segments.slice(0, index + 1).join("/"));
 }
 
+const BYTE_UNITS = ["B", "KB", "MB", "GB", "TB"] as const;
+const BYTE_STEP = 1024;
+
+/**
+ * Size scheme: binary units (1 KB = 1024 B), a space before the unit, whole
+ * bytes with no decimal, and one decimal place from KB up. The displayed value
+ * is rounded BEFORE the unit is promoted, because promoting on the raw value
+ * lets 1048575 B round to "1024.0" KB and read `1024 KB`; rounding first sends
+ * it to `1 MB`. Returns undefined for a value that cannot be a byte count, so
+ * an unusable field renders nothing at all.
+ */
+export function formatWorkspaceFileSize(size: number): string | undefined {
+  if (!Number.isFinite(size) || size < 0) return undefined;
+  let value = size;
+  let unitIndex = 0;
+  for (;;) {
+    const amount = unitIndex === 0 ? Math.round(value) : Number(value.toFixed(1));
+    if (amount < BYTE_STEP || unitIndex === BYTE_UNITS.length - 1) return `${amount} ${BYTE_UNITS[unitIndex]}`;
+    value /= BYTE_STEP;
+    unitIndex += 1;
+  }
+}
+
+/**
+ * Time scheme: `YYYY-MM-DD HH:mm` in UTC, assembled from the UTC date getters
+ * instead of `toLocaleString` / `toLocaleDateString`. Those follow the host
+ * locale and timezone, so the same file would read differently on two machines
+ * and any assertion on the text would be environment-dependent; fixed-width
+ * ISO fields in UTC are identical everywhere and still sort chronologically.
+ * Seconds are dropped because a file tree is read at a glance, and an
+ * out-of-range epoch returns undefined rather than throwing the `Invalid Date`
+ * that `toISOString` would raise.
+ */
+export function formatWorkspaceFileModifiedAt(modifiedAt: number): string | undefined {
+  if (!Number.isFinite(modifiedAt)) return undefined;
+  const date = new Date(modifiedAt);
+  const time = date.getTime();
+  if (Number.isNaN(time)) return undefined;
+  const pad = (value: number): string => String(value).padStart(2, "0");
+  return `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())} ${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}`;
+}
+
+/**
+ * The file-metadata column. `size` and `modifiedAt` are optional by contract:
+ * absent for directories, and absent for any runtime that does not stat, so
+ * each half is formatted on its own and the whole span is dropped when neither
+ * produced a value. Directories never reach it — a directory's byte count is
+ * meaningless — which also keeps a stray value from a permissive runtime out
+ * of the row.
+ */
+function FileTreeRowMeta({ file }: { readonly file: WebuiWorkspaceFile }): ReactElement | null {
+  if (file.type === "directory") return null;
+  const parts = [
+    file.size === undefined ? undefined : formatWorkspaceFileSize(file.size),
+    file.modifiedAt === undefined ? undefined : formatWorkspaceFileModifiedAt(file.modifiedAt),
+  ].filter((part): part is string => part !== undefined);
+  if (parts.length === 0) return null;
+  // `webui-file-tree-meta` is a hook for the row layout: the utilities keep
+  // the metadata pinned to the end of the flex row while the name truncates,
+  // so a long name can never push this off the end.
+  return <span className="webui-file-tree-meta shrink-0 text-size_12 leading-line_height_16 text-text_default_tertiary">{parts.join(" · ")}</span>;
+}
+
 export function FileTree({ files, onOpen, expandedPaths, loadingPaths, directoryErrors, onToggle, selectedPath }: { readonly files: readonly WebuiWorkspaceFile[]; readonly onOpen: (file: WebuiWorkspaceFile) => void; readonly expandedPaths: ReadonlySet<string>; readonly loadingPaths: ReadonlySet<string>; readonly directoryErrors: Readonly<Record<string, string>>; readonly onToggle: (file: WebuiWorkspaceFile) => void; readonly selectedPath?: string }): ReactElement {
   return <div className="webui-file-tree">{files.map((file) => {
     const expanded = expandedPaths.has(file.path);
     return <div key={file.path}>
       <button type="button" className={`webui-file-tree-row ${file.path === selectedPath ? "is-selected" : ""}`} aria-current={file.path === selectedPath ? "true" : undefined} aria-expanded={file.type === "directory" ? expanded : undefined} aria-busy={file.type === "directory" && loadingPaths.has(file.path) ? "true" : undefined} onClick={() => file.type === "directory" ? onToggle(file) : onOpen(file)}>
-        {file.type === "directory" ? <WebuiIconChevronLeft className={`inline size-3 transition-transform duration-[180ms] ease-out ${expanded ? "rotate-90" : ""}`} /> : <WebuiIconFile className="inline size-3" />} {file.name}
+        {file.type === "directory" ? <WebuiIconChevronLeft className={`inline size-3 transition-transform duration-[180ms] ease-out ${expanded ? "rotate-90" : ""}`} /> : <WebuiIconFile className="inline size-3" />} <span className="min-w-0 flex-1 truncate">{file.name}</span>
+        <FileTreeRowMeta file={file} />
       </button>
       {file.type === "directory" ? <div className={`webui-expandable-motion${expanded ? " is-open" : ""}`} aria-hidden={!expanded} ref={(element) => element?.toggleAttribute("inert", !expanded)}>
         <div className="webui-file-tree-children">
diff --git a/packages/webui/test/unit/webui-workspace-file-tree.test.tsx b/packages/webui/test/unit/webui-workspace-file-tree.test.tsx
new file mode 100644
index 000000000..b4ee9cedf
--- /dev/null
+++ b/packages/webui/test/unit/webui-workspace-file-tree.test.tsx
@@ -0,0 +1,155 @@
+// Unit tests for the workspace file tree's file-metadata column.
+//
+// `WebuiWorkspaceFile.size` (bytes) and `.modifiedAt` (epoch ms) are optional
+// by contract: absent for directories, and absent for any runtime that does
+// not stat. So the load-bearing case here is absence — a tree from such a
+// runtime must render the same row chrome minus the metadata, and must never
+// print `undefined`, `NaN` or `Invalid Date`. The sizes and times are asserted
+// on the markup rather than on a locale-dependent string, so these cases stay
+// true in any timezone.
+
+import { describe, expect, it } from "vitest";
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+
+import { FileTree, formatWorkspaceFileModifiedAt, formatWorkspaceFileSize } from "../../src/client/components/WorkspaceFileTree.js";
+import type { WebuiWorkspaceFile } from "../../src/server/port.js";
+
+const MODIFIED_AT = Date.UTC(2026, 9, 4, 8, 51);
+
+function renderTree(
+  files: readonly WebuiWorkspaceFile[],
+  overrides: {
+    readonly expandedPaths?: ReadonlySet<string>;
+    readonly loadingPaths?: ReadonlySet<string>;
+    readonly directoryErrors?: Readonly<Record<string, string>>;
+    readonly selectedPath?: string;
+  } = {},
+): string {
+  return renderToStaticMarkup(createElement(FileTree, {
+    files,
+    onOpen: () => undefined,
+    expandedPaths: overrides.expandedPaths ?? new Set<string>(),
+    loadingPaths: overrides.loadingPaths ?? new Set<string>(),
+    directoryErrors: overrides.directoryErrors ?? {},
+    onToggle: () => undefined,
+    selectedPath: overrides.selectedPath,
+  }));
+}
+
+describe("workspace file tree metadata column", () => {
+  it("renders a binary size and a UTC timestamp beside a stat-ed file", () => {
+    const markup = renderTree([
+      { path: "src/index.ts", name: "index.ts", type: "file", size: 1258291, modifiedAt: MODIFIED_AT },
+    ]);
+
+    expect(markup).toContain("index.ts");
+    expect(markup).toContain("1.2 MB");
+    expect(markup).toContain("2026-10-04 08:51");
+    expect(markup).toContain("webui-file-tree-meta");
+    expect(markup).not.toContain("undefined");
+    expect(markup).not.toContain("NaN");
+    expect(markup).not.toContain("Invalid Date");
+  });
+
+  it("keeps the existing row contract: class, button type, selection and expansion", () => {
+    const markup = renderTree(
+      [
+        {
+          path: "src",
+          name: "src",
+          type: "directory",
+          children: [{ path: "src/a.ts", name: "a.ts", type: "file", size: 10, modifiedAt: MODIFIED_AT }],
+        },
+      ],
+      { expandedPaths: new Set(["src"]), selectedPath: "src" },
+    );
+
+    expect(markup).toContain('<button type="button" class="webui-file-tree-row is-selected"');
+    expect(markup).toContain('aria-current="true"');
+    expect(markup).toContain('aria-expanded="true"');
+    expect(markup).toContain("webui-expandable-motion is-open");
+    expect(markup).toContain('aria-hidden="false"');
+    // The child file still carries its own metadata inside the expanded tree.
+    expect(markup).toContain("10 B");
+  });
+
+  it("renders the metadata without a container element when both fields are missing", () => {
+    const markup = renderTree([{ path: "src/legacy.ts", name: "legacy.ts", type: "file" }]);
+
+    expect(markup).toContain("legacy.ts");
+    expect(markup).not.toContain("webui-file-tree-meta");
+    expect(markup).not.toContain("undefined");
+    expect(markup).not.toContain("NaN");
+    expect(markup).not.toContain("Invalid Date");
+    // The name still owns the truncating box, so the row does not reflow.
+    expect(markup).toContain('class="min-w-0 flex-1 truncate">legacy.ts</span>');
+  });
+
+  it("keeps whichever half the runtime did send when only one field is present", () => {
+    const sizeOnly = renderTree([{ path: "a.bin", name: "a.bin", type: "file", size: 2048 }]);
+    expect(sizeOnly).toContain("2 KB");
+    expect(sizeOnly).not.toContain("webui-file-tree-meta shrink-0 text-size_12 leading-line_height_16 text-text_default_tertiary\"> ·");
+
+    const timeOnly = renderTree([{ path: "b.bin", name: "b.bin", type: "file", modifiedAt: MODIFIED_AT }]);
+    expect(timeOnly).toContain("2026-10-04 08:51");
+  });
+
+  it("shows neither size nor time for a directory, even if a runtime sends them", () => {
+    const markup = renderTree([
+      { path: "src", name: "src", type: "directory", size: 4096, modifiedAt: MODIFIED_AT },
+    ]);
+
+    expect(markup).toContain('aria-expanded="false"');
+    expect(markup).toContain("src");
+    expect(markup).not.toContain("4 KB");
+    expect(markup).not.toContain("2026-10-04");
+    expect(markup).not.toContain("webui-file-tree-meta");
+  });
+
+  it("formats byte-size boundaries and promotes the unit before rounding", () => {
+    const cases = [
+      { bytes: 0, expected: "0 B" },
+      { bytes: 999, expected: "999 B" },
+      { bytes: 1024, expected: "1 KB" },
+      { bytes: 348160, expected: "340 KB" },
+      { bytes: 1048575, expected: "1 MB" },
+    ] as const;
+    const markup = renderTree(cases.map((entry, index) => ({
+      path: `f${index}.bin`,
+      name: `f${index}.bin`,
+      type: "file",
+      size: entry.bytes,
+    })));
+
+    for (const { expected } of cases) expect(markup).toContain(expected);
+    // 1048575 is 1 B short of a megabyte: binary units promote, they never
+    // render a 1024 KB row.
+    expect(markup).not.toContain("1024 KB");
+  });
+
+  it("drops unusable numbers instead of printing NaN or Invalid Date", () => {
+    expect(formatWorkspaceFileSize(Number.NaN)).toBeUndefined();
+    expect(formatWorkspaceFileSize(-1)).toBeUndefined();
+    expect(formatWorkspaceFileModifiedAt(Number.NaN)).toBeUndefined();
+    // One millisecond past the largest representable Date.
+    expect(formatWorkspaceFileModifiedAt(8.64e15 + 1)).toBeUndefined();
+
+    const markup = renderTree([
+      { path: "broken.bin", name: "broken.bin", type: "file", size: Number.NaN, modifiedAt: Number.POSITIVE_INFINITY },
+      { path: "unreachable.bin", name: "unreachable.bin", type: "file", modifiedAt: 8.64e15 + 1 },
+    ]);
+    expect(markup).toContain("broken.bin");
+    expect(markup).not.toContain("NaN");
+    expect(markup).not.toContain("Invalid Date");
+    expect(markup).not.toContain("webui-file-tree-meta");
+  });
+
+  it("formats a fixed-width UTC timestamp independent of the host timezone", () => {
+    // 2026-01-01T00:30Z: 23:30 on 2025-12-31 in UTC+1, 01:30 in UTC+9. A
+    // locale formatter would disagree with the host; the UTC read is fixed.
+    expect(formatWorkspaceFileModifiedAt(Date.UTC(2026, 0, 1, 0, 30))).toBe("2026-01-01 00:30");
+    expect(formatWorkspaceFileModifiedAt(Date.UTC(2026, 0, 1, 23, 5))).toBe("2026-01-01 23:05");
+    expect(formatWorkspaceFileModifiedAt(0)).toBe("1970-01-01 00:00");
+  });
+});

From 42b8eca67e6facc95ba653eba920d0458f00868d Mon Sep 17 00:00:00 2001
From: probe <probe@local>
Date: Sun, 4 Oct 2026 08:55:18 +0800
Subject: [PATCH 14/21] Render workspace HTML previews as live documents
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The workspace panel dispatched .html/.htm to this component, which
rendered a "not connected yet" placeholder. It now points an iframe at
the /workspace-file URL the container already builds.

The document is framed, never inlined. A srcdoc document (or a blob URL,
or dangerouslySetInnerHTML) inherits the parent document's policy, which
is the WebUI itself — so inlining the bytes would silently discard the
server's Content-Security-Policy: sandbox allow-scripts and hand the
previewed artifact the same origin as window.__WEBUI_CONFIG__.token.
Framing the URL keeps the isolation exactly where the server puts it: an
opaque origin that can run scripts but cannot read the panel's DOM, the
WebUI's storage, or the session credential.

No sandbox attribute on the iframe. The header is already the sandbox,
and a second layer could not be relaxed later without editing this file;
while both existed it would be impossible to tell which one is holding,
so the boundary could not be audited from the response.

The opaque origin costs relative URLs: logo.png and /logo.png both
resolve against the route rather than the file's directory, and 404. The
document is never rewritten to work around that — that would mean
inlining it. Instead the note is always visible, and sharper when the read
result shows a relative reference.

A runtime mimeType that is not text/html is refused rather than framed:
the extension picked the route, and the server's CSP branch is keyed on
text/html too, so a framed text/plain file would not be isolated at all.
---
 .../components/WorkspaceHtmlPreview.tsx       | 167 ++++++++++++++++--
 .../webui-workspace-html-preview.test.tsx     | 114 ++++++++++++
 2 files changed, 271 insertions(+), 10 deletions(-)
 create mode 100644 packages/webui/test/unit/webui-workspace-html-preview.test.tsx

diff --git a/packages/webui/src/client/components/WorkspaceHtmlPreview.tsx b/packages/webui/src/client/components/WorkspaceHtmlPreview.tsx
index 5a672a5e8..f26742cc1 100644
--- a/packages/webui/src/client/components/WorkspaceHtmlPreview.tsx
+++ b/packages/webui/src/client/components/WorkspaceHtmlPreview.tsx
@@ -1,10 +1,35 @@
 // Owns the workspace HTML-preview feature (rendering an .html file inside
-// the workspace panel). Nothing is implemented yet: this file is the seam a
-// different implementer fills in. The only thing that lives outside it is
-// the dispatch in `WebuiFilePreview`, which routes `.html`/`.htm` here
-// before the read result is consulted.
+// the workspace panel). The dispatch in `WebuiFilePreview` routes
+// `.html`/`.htm` here before the read result is consulted; nothing else in
+// the panel needs to know this component exists.
+//
+// The document is rendered by pointing an `<iframe src={fileUrl}>` at the
+// `/workspace-file` route, and that is the whole isolation story. The route
+// answers `text/html` with `Content-Security-Policy: sandbox allow-scripts`,
+// which puts the framed document in an opaque origin: its scripts run, but it
+// cannot read `window.__WEBUI_CONFIG__.token` off the page that framed it,
+// cannot touch the panel's DOM, and cannot use the WebUI's origin for storage.
+//
+// Two things follow, and both are load-bearing:
+//
+//   * No `sandbox` attribute here. The header already sandboxes the document.
+//     A second layer on the iframe cannot be relaxed later without an edit to
+//     this file, and while both exist it is impossible to tell which one is
+//     actually holding — so a future reader cannot audit the boundary. One
+//     layer, in one place (the server), is auditable.
+//   * Never `srcdoc`, never a blob URL, never `dangerouslySetInnerHTML`. A
+//     `srcdoc` document inherits the *parent* document's policy, which is the
+//     WebUI itself — inlining the bytes would silently discard the server's
+//     CSP and hand the artifact the same origin as the token. The cost of
+//     that mistake is the whole WebUI session, so the document never becomes
+//     a string this component renders.
+//
+// What the opaque origin costs is relative URLs: an `<img src="logo.png">`
+// resolves against the route, not against the file's directory, and 404s. The
+// frame is therefore always accompanied by a note saying so, and the note is
+// sharper when the read result shows a relative reference.
 
-import type { ReactElement } from "react";
+import { useEffect, useState, type ReactElement } from "react";
 import type { WebuiWorkspaceFileContent } from "../../server/port.js";
 
 export type WorkspaceHtmlPreviewProps = {
@@ -33,11 +58,133 @@ export type WorkspaceHtmlPreviewProps = {
   readonly content?: WebuiWorkspaceFileContent;
 };
 
+const HTML_PREVIEW_COPY = {
+  loading: "正在加载 HTML 预览…",
+  loadFailed: "HTML 预览加载失败：文件接口没有返回可显示的文档。",
+  relativeDetected: "检测到文档引用了相对路径资源。预览运行在隔离来源中，相对路径会解析到文件接口而不是文件所在目录，因此这些资源不会显示。",
+  relativeUndetected: "预览运行在隔离来源中。文档内的相对路径资源会解析到文件接口而不是文件所在目录，可能无法显示；文档脚本无法访问 WebUI 的会话凭据。",
+  openOutside: "在浏览器中打开",
+} as const;
+
+/**
+ * The frame's own load state. `onLoad`/`onError` are the only observable
+ * signals available: the document is in an opaque origin, so the panel cannot
+ * reach into it to ask whether it rendered, and a silent empty frame is the
+ * failure mode this exists to prevent.
+ */
+type WorkspaceHtmlFrameState = "loading" | "loaded" | "failed";
+
+// `src`/`href`/`poster` values, `srcset` candidate lists, and `url()` in
+// inline CSS. All read-only: the document is never rewritten, only reported
+// on. `srcset` is scanned separately because it is the one attribute whose
+// value is a comma-separated list — splitting `data:` URLs on their comma
+// would report a false positive on a fully absolute reference.
+const ASSET_ATTRIBUTE_PATTERN = /(?:src|href|poster)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/giu;
+const SRCSET_PATTERN = /srcset\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/giu;
+const CSS_URL_PATTERN = /url\(\s*(?:"([^"]*)"|'([^']*)'|([^)'"]*))\s*\)/giu;
+
+/**
+ * Whether a reference is resolved against the frame's base URL.
+ *
+ * That base is the `/workspace-file` route, so both `logo.png` and
+ * `/logo.png` miss: the document's own directory is not on the URL at all.
+ * A scheme (`https:`, `data:`, `blob:`, `mailto:`) and a same-document
+ * fragment are the two cases that still resolve to something intended.
+ */
+function isRelativeReference(value: string): boolean {
+  const reference = value.trim();
+  if (!reference || reference.startsWith("#")) return false;
+  if (/^[a-z][a-z0-9+.-]*:/iu.test(reference)) return false;
+  if (reference.startsWith("//")) return false;
+  return true;
+}
+
+function firstCapture(match: RegExpMatchArray): string {
+  return match[1] ?? match[2] ?? match[3] ?? "";
+}
+
+/**
+ * Whether a document's own text shows a relative asset reference.
+ *
+ * Best-effort by construction: it is a report on the source, not a proof
+ * about the rendered frame — an unread file, a reference built at runtime, or
+ * a `<base href>` that redirects resolution are all invisible here. That is
+ * exactly why the note stays visible when this returns `false`.
+ */
+export function hasRelativeDocumentReference(source: string): boolean {
+  for (const match of source.matchAll(SRCSET_PATTERN)) {
+    // Each `srcset` candidate is a URL followed by a descriptor.
+    for (const candidate of firstCapture(match).split(",")) {
+      if (isRelativeReference(candidate.trim().split(/\s+/u)[0] ?? "")) return true;
+    }
+  }
+  for (const match of source.matchAll(ASSET_ATTRIBUTE_PATTERN)) {
+    if (isRelativeReference(firstCapture(match))) return true;
+  }
+  for (const match of source.matchAll(CSS_URL_PATTERN)) {
+    if (isRelativeReference(firstCapture(match))) return true;
+  }
+  return false;
+}
+
 /**
- * Placeholder HTML preview. It renders the "not available" state so the file
- * preview has a mount point; replacing the body is a change inside this file
- * alone.
+ * Live HTML preview for one workspace file.
+ *
+ * Three states before the frame, none of which may be an empty element: the
+ * file is not `text/html` according to the runtime, there is no file URL to
+ * point at, or the frame has not loaded (or failed to).
  */
-export function WorkspaceHtmlPreview(_props: WorkspaceHtmlPreviewProps): ReactElement {
-  return <div role="status"><p>HTML 预览尚未接入。</p></div>;
+export function WorkspaceHtmlPreview({ path, fileUrl, content }: WorkspaceHtmlPreviewProps): ReactElement {
+  const fileName = path.split("/").at(-1) ?? path;
+  const [frameState, setFrameState] = useState<WorkspaceHtmlFrameState>("loading");
+
+  // A new URL is a new document: the previous file's outcome says nothing
+  // about this one, and a stale "loaded" would hide the loading state.
+  useEffect(() => {
+    setFrameState("loading");
+  }, [fileUrl]);
+
+  // The extension chose the route, so the runtime is the only thing that
+  // knows what the bytes are. A `.html` that reads back as `text/plain`
+  // would otherwise be framed as a document the server never agreed to
+  // isolate — the CSP branch is keyed on `text/html` too.
+  const mimeType = content?.mimeType?.trim().toLowerCase();
+  if (mimeType && !mimeType.startsWith("text/html")) {
+    return <div className="webui-workspace-files-empty" data-testid="workspace-html-preview-refused" role="alert">
+      <strong>不作为 HTML 预览打开</strong>
+      <p>{`文件扩展名是 .html，但运行时报告的类型是 ${mimeType}，服务端不会以隔离文档的策略回答它。`}</p>
+    </div>;
+  }
+
+  if (!fileUrl) {
+    return <div className="webui-workspace-files-empty" data-testid="workspace-html-preview-unavailable" role="status">
+      <strong>无法预览 HTML</strong>
+      <p>缺少文件地址，面板没有可加载的文档。</p>
+    </div>;
+  }
+
+  const relativeReference = content?.type === "text" ? hasRelativeDocumentReference(content.content) : false;
+
+  return <div data-testid="workspace-html-preview" style={{ display: "flex", height: "100%", minWidth: 0, minHeight: 0, flexDirection: "column" }}>
+    {frameState === "loaded" ? null : <p className="webui-workspace-review-status" data-testid="workspace-html-preview-status" role={frameState === "failed" ? "alert" : "status"}>
+      {frameState === "failed" ? HTML_PREVIEW_COPY.loadFailed : HTML_PREVIEW_COPY.loading}
+    </p>}
+    <p className="webui-workspace-review-status" data-testid="workspace-html-preview-isolation-note">
+      {relativeReference ? HTML_PREVIEW_COPY.relativeDetected : HTML_PREVIEW_COPY.relativeUndetected}
+      {" "}
+      <a className="webui-button-secondary" data-testid="workspace-html-preview-open-outside" href={fileUrl} target="_blank" rel="noreferrer noopener">{HTML_PREVIEW_COPY.openOutside}</a>
+    </p>
+    {/* No `sandbox` here: the server header is the one layer, and it is the
+        only one that can be audited from the response. */}
+    <div style={{ flex: "1 1 auto", minHeight: 0 }}>
+      <iframe
+        title={`HTML 预览：${fileName}`}
+        src={fileUrl}
+        data-testid="workspace-html-preview-frame"
+        onLoad={() => { setFrameState("loaded"); }}
+        onError={() => { setFrameState("failed"); }}
+        style={{ display: "block", width: "100%", height: "100%", minHeight: 240, border: 0, background: "transparent" }}
+      />
+    </div>
+  </div>;
 }
diff --git a/packages/webui/test/unit/webui-workspace-html-preview.test.tsx b/packages/webui/test/unit/webui-workspace-html-preview.test.tsx
new file mode 100644
index 000000000..8269bf9a9
--- /dev/null
+++ b/packages/webui/test/unit/webui-workspace-html-preview.test.tsx
@@ -0,0 +1,114 @@
+// Unit tests for the workspace HTML preview.
+//
+// Rendering goes through `renderToStaticMarkup` (the project's SSR test
+// convention, see `test/unit/workspace-panel-state.test.ts`). It does not run
+// effects, so these assert on emitted markup and attributes: the iframe's
+// `src`/`title`, the states that must render *instead of* a frame, and — the
+// assertions that actually protect the feature — the absence of a second
+// sandbox layer and of any inlined document.
+
+import { describe, expect, it } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import { WorkspaceHtmlPreview, hasRelativeDocumentReference } from "../../src/client/components/WorkspaceHtmlPreview.js";
+
+const FILE_URL = "http://127.0.0.1:8787/workspace-file?dir=%2Frepo&path=index.html&token=t0ken";
+
+function render(props: { fileUrl?: string; content?: { readonly type: "text" | "binary"; readonly content: string; readonly mimeType?: string } }): string {
+  return renderToStaticMarkup(<WorkspaceHtmlPreview path="site/index.html" fileUrl={props.fileUrl ?? FILE_URL} content={props.content} />);
+}
+
+describe("workspace HTML preview", () => {
+  it("frames the file at its own URL and titles the frame for assistive tech", () => {
+    const markup = render({ content: { type: "text", content: "<h1>hi</h1>", mimeType: "text/html" } });
+
+    expect(markup).toContain("<iframe");
+    // The `&` in the query is escaped by React, so this also pins the exact
+    // URL the frame is pointed at.
+    expect(markup).toContain('src="http://127.0.0.1:8787/workspace-file?dir=%2Frepo&amp;path=index.html&amp;token=t0ken"');
+    expect(markup).toContain('title="HTML 预览：index.html"');
+  });
+
+  it("leaves the isolation to the server header instead of adding a second layer", () => {
+    const markup = render({ content: { type: "text", content: "<script>window.top.location</script>", mimeType: "text/html" } });
+
+    // A second sandbox on the iframe cannot be relaxed later without an edit
+    // here, and hides which layer is actually holding.
+    expect(markup).not.toContain("sandbox");
+    // `srcdoc` would inherit the WebUI's own policy, discarding the server's.
+    expect(markup).not.toContain("srcdoc");
+    expect(markup).not.toContain("data:text/html");
+  });
+
+  it("never inlines the document it frames", () => {
+    const markup = render({ content: { type: "text", content: "<h1>secret heading</h1><script>steal()</script>", mimeType: "text/html" } });
+
+    expect(markup).not.toContain("secret heading");
+    expect(markup).not.toContain("steal()");
+    expect(markup).toContain("<iframe");
+  });
+
+  it("refuses a .html file whose bytes the runtime does not report as text/html", () => {
+    const markup = render({ content: { type: "text", content: "key = 1", mimeType: "text/plain" } });
+
+    expect(markup).not.toContain("<iframe");
+    expect(markup).toContain('role="alert"');
+    expect(markup).toContain("text/plain");
+  });
+
+  it("accepts a text/html mime that carries a charset parameter", () => {
+    expect(render({ content: { type: "text", content: "<p>ok</p>", mimeType: "TEXT/HTML; charset=utf-8" } })).toContain("<iframe");
+  });
+
+  it("states the missing URL instead of rendering an empty frame", () => {
+    const markup = render({ fileUrl: "" });
+
+    expect(markup).not.toContain("<iframe");
+    expect(markup).toContain('data-testid="workspace-html-preview-unavailable"');
+    expect(markup).toContain("无法预览 HTML");
+  });
+
+  it("shows something while the frame loads and never an unexplained empty frame", () => {
+    const markup = render({ content: { type: "text", content: "<p>ok</p>", mimeType: "text/html" } });
+
+    expect(markup).toContain('data-testid="workspace-html-preview-status"');
+    expect(markup).toContain("正在加载 HTML 预览");
+  });
+
+  it("warns about relative references the opaque origin cannot resolve", () => {
+    const relative = render({ content: { type: "text", content: '<link href="style.css"><img src="logo.png">', mimeType: "text/html" } });
+    const absolute = render({ content: { type: "text", content: '<img src="https://cdn.example.com/logo.png"><a href="#top">top</a>', mimeType: "text/html" } });
+
+    expect(relative).toContain("检测到文档引用了相对路径资源");
+    expect(relative).toContain('data-testid="workspace-html-preview-isolation-note"');
+    // Undetectable is not the same as absent, so the limitation stays stated.
+    expect(absolute).not.toContain("检测到文档引用了相对路径资源");
+    expect(absolute).toContain("相对路径资源会解析到文件接口");
+    // Nothing about the document is re-written to work around it.
+    expect(relative).not.toContain("<link");
+  });
+
+  it("detects relative references, including root-relative ones the route also misses", () => {
+    expect(hasRelativeDocumentReference('<img src="logo.png">')).toBe(true);
+    expect(hasRelativeDocumentReference('<link href="style.css" rel="stylesheet">')).toBe(true);
+    expect(hasRelativeDocumentReference("<video poster='poster.png'></video>")).toBe(true);
+    expect(hasRelativeDocumentReference('<img srcset="logo.png 1x, logo@2x.png 2x">')).toBe(true);
+    expect(hasRelativeDocumentReference("<div style=\"background: url(bg.png)\"></div>")).toBe(true);
+    // Root-relative resolves against the route, not the file's directory.
+    expect(hasRelativeDocumentReference('<img src="/logo.png">')).toBe(true);
+
+    expect(hasRelativeDocumentReference('<img src="https://cdn.example.com/logo.png">')).toBe(false);
+    expect(hasRelativeDocumentReference('<img src="data:image/png;base64,AAA">')).toBe(false);
+    expect(hasRelativeDocumentReference('<a href="#section">jump</a>')).toBe(false);
+    expect(hasRelativeDocumentReference('<a href="//cdn.example.com/x">jump</a>')).toBe(false);
+    expect(hasRelativeDocumentReference("<h1>plain text</h1>")).toBe(false);
+  });
+
+  it("offers the same URL as a plain navigation, without an opener handle", () => {
+    const markup = render({ content: { type: "text", content: "<p>ok</p>", mimeType: "text/html" } });
+
+    expect(markup).toContain('href="http://127.0.0.1:8787/workspace-file?dir=%2Frepo&amp;path=index.html&amp;token=t0ken"');
+    expect(markup).toContain('target="_blank"');
+    expect(markup).toContain('rel="noreferrer noopener"');
+    expect(markup).not.toContain("window.open");
+  });
+});

From 9dd2bba8cdf11b3f16ec3c0a2d2d9438cf7f7c3e Mon Sep 17 00:00:00 2001
From: probe <probe@local>
Date: Sun, 4 Oct 2026 08:59:45 +0800
Subject: [PATCH 15/21] Make the workspace canvas a real surface
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The canvas read its document and printed the node names in a row: zoom
existed, but nothing could be moved, added, or saved. It now positions nodes
absolutely on a pannable stage and persists every change.

Write-back path. Drag, resize, add and remove all build a CanvasOperationV1
— { schemaVersion: 1, operationId, mutations } — and send it through
applyCanvas; the document that comes back in the result replaces local state.
The payload shape was taken from the runtime's own contract
(packages/local-runtime-v2/src/service/canvas/contracts.ts), which the webui
boundary forwards verbatim, and it honours the rules that service enforces: a
non-blank operationId minted fresh per call (a reused id is refused as
OPERATION_ID_REUSED), a non-empty mutation list, exactly one file identity on
add_file, and a layout that is finite with positive width/height and a
safe-integer zIndex. A refused operation is reported in a role="alert" and the
optimistic drag preview is dropped, so the view falls back to what the server
actually holds rather than silently keeping a value that was never saved.

Pan versus drag. The pointerdown target decides once and the decision is never
revised for the rest of the gesture. No marker on the target (or an unknown one)
pans the stage; a node marked "move" drags that node; a node's corner marked
"resize" resizes it; a marked "control" starts no gesture at all, so the remove
button's click stays its own. Because the choice is frozen at pointerdown,
neither gesture needs a movement threshold to disambiguate — a node drag that
wanders off the node stays a node drag, and a pan that crosses a node stays a
pan. The pointer is captured on the viewport for both, so a drag that leaves the
surface still reports its moves. The stage transforms as
translate(pan) scale(zoom) from a 0 0 origin, which is why a pointer delta is
divided by the zoom to become a node delta while the pan is already in screen
pixels.

Accessibility. Every node is focusable and both pointer gestures have real
keyboard equivalents rather than a note about mouse-only: arrow keys move the
focused node, Alt+arrow keys resize it, Shift accelerates, and arrow keys pan
when the canvas background itself holds focus. Removal is a focusable button.

Wheel zoom keeps its 0.4–2.0 clamp and 0.1 step, and the existing class names,
empty-state copy and zoom readout are unchanged; the shared stylesheet is
untouched, so the flex-row stage and the centered content are overridden with
inline styles on a clipping viewport.

The panel stays read-only, and says so, when no applyCanvas port is wired in.
---
 .../src/client/components/WorkspaceCanvas.tsx | 741 +++++++++++++++++-
 .../test/unit/webui-workspace-canvas.test.tsx | 434 ++++++++++
 2 files changed, 1167 insertions(+), 8 deletions(-)
 create mode 100644 packages/webui/test/unit/webui-workspace-canvas.test.tsx

diff --git a/packages/webui/src/client/components/WorkspaceCanvas.tsx b/packages/webui/src/client/components/WorkspaceCanvas.tsx
index 9d607b7a7..23ab19bd9 100644
--- a/packages/webui/src/client/components/WorkspaceCanvas.tsx
+++ b/packages/webui/src/client/components/WorkspaceCanvas.tsx
@@ -1,28 +1,753 @@
-// Owns the workspace canvas feature: the canvas document state, the zoom
-// state, and the whole `webui-canvas-content` render. A different implementer
+// Owns the workspace canvas feature: the canvas document state, the zoom and
+// pan state, and the whole `webui-canvas-content` render. A different implementer
 // works in this file; the container in `WorkspacePanels.tsx` only mounts it.
+//
+// The canvas is a real surface, not a readout: nodes are absolutely positioned
+// on a pannable stage, and every mutation (move, resize, add, remove) is sent
+// through `applyCanvas` and then adopted from the returned document. The
+// server document is the only truth — local state is never treated as saved.
+//
+// Port contract, determined from the runtime rather than guessed:
+//   `packages/local-runtime-v2/src/service/canvas/contracts.ts` declares
+//   `CanvasOperationV1 { schemaVersion: 1, operationId, mutations }` and
+//   `CanvasMutationV1` = add_file | update_layout | remove_node | the three
+//   annotation mutations. The webui boundary keeps `operation` as an opaque
+//   `Record<string, unknown>` (`src/server/operation/workspace.ts` only checks
+//   that it is a non-null, non-array object) and forwards it verbatim to that
+//   service, so the payload below is the shape the runtime actually validates.
+//   Its rules this file honours: `operationId` must be non-blank and unique per
+//   session (a reused id is rejected as OPERATION_ID_REUSED), `mutations` must
+//   be non-empty, `add_file` must carry exactly one of `relativePath` /
+//   `assetId`, and a layout must be finite with positive width/height and a
+//   safe-integer zIndex.
 
-import { useEffect, useState, type ReactElement } from "react";
+import {
+  useEffect,
+  useRef,
+  useState,
+  type FormEvent,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type PointerEvent as ReactPointerEvent,
+  type ReactElement,
+  type WheelEvent as ReactWheelEvent,
+} from "react";
 import type { WebuiCanvasDocument } from "../../server/port.js";
 
-const DESKTOP_COPY = { canvasEmptyTitle: "把文件放到画布上", canvasEmptyDescription: "添加图片或其他工作区文件，然后自由排列和调整大小。" } as const;
+const DESKTOP_COPY = {
+  canvasEmptyTitle: "把文件放到画布上",
+  canvasEmptyDescription: "添加图片或其他工作区文件，然后自由排列和调整大小。",
+  canvasAddLabel: "工作区相对路径",
+  canvasAddPlaceholder: "docs/diagram.png",
+  canvasAddSubmit: "添加到画布",
+  canvasNodeRemove: "移除",
+  canvasNodeHint: "方向键移动，Alt+方向键缩放，Shift 加速。",
+  canvasStageLabel: "画布：空白处拖动平移，滚轮缩放，方向键平移。",
+  canvasReadOnly: "画布当前为只读：保存操作没有接入。",
+  canvasSaving: "正在保存画布改动…",
+  canvasBusy: "上一个画布改动还在保存，请稍候。",
+  canvasAddRequired: "请先输入工作区相对路径。",
+  canvasFailed: "画布改动没有保存。",
+} as const;
 
-export function WorkspaceCanvas({ sessionId, readCanvas }: {
+/** Wheel zoom keeps the clamp and step the panel shipped with. */
+export const CANVAS_ZOOM_MIN = 0.4;
+export const CANVAS_ZOOM_MAX = 2;
+export const CANVAS_ZOOM_STEP = 0.1;
+
+/** Canvas units per arrow key press, and the Shift multiplier. */
+export const CANVAS_NUDGE_STEP = 8;
+export const CANVAS_NUDGE_STEP_LARGE = 32;
+/** The runtime rejects a non-positive width or height, so clamp before sending. */
+export const CANVAS_MIN_NODE_SIZE = 24;
+
+/** Backing box for the stage; nodes are placed inside it in canvas units. */
+const CANVAS_WORLD_SIZE = 4000;
+const CANVAS_ADD_GAP_X = 264;
+const CANVAS_ADD_GAP_Y = 204;
+const CANVAS_ADD_COLUMNS = 5;
+const CANVAS_ADD_ORIGIN = 32;
+const CANVAS_ADD_WIDTH = 240;
+const CANVAS_ADD_HEIGHT = 180;
+const CANVAS_PAN_KEY_SCALE = 4;
+
+export interface CanvasNodeLayout {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly zIndex: number;
+}
+
+export interface CanvasNodeView {
+  readonly id: string;
+  readonly label: string;
+  readonly layout: CanvasNodeLayout;
+}
+
+export interface CanvasPan {
+  readonly x: number;
+  readonly y: number;
+}
+
+/**
+ * A node drag, a node resize and a canvas pan all start from one pointer and
+ * one gesture, so the marker on the pointerdown target picks the winner once.
+ * Mirrors the runtime's `CanvasMutationV1` for the three mutations this panel
+ * can produce; `add_file` keeps exactly one file identity, as the runtime
+ * requires.
+ */
+export type CanvasMutation =
+  | { readonly kind: "add_file"; readonly nodeId: string; readonly layout: CanvasNodeLayout; readonly relativePath: string }
+  | { readonly kind: "add_file"; readonly nodeId: string; readonly layout: CanvasNodeLayout; readonly assetId: string }
+  | { readonly kind: "update_layout"; readonly nodeId: string; readonly layout: CanvasNodeLayout }
+  | { readonly kind: "remove_node"; readonly nodeId: string };
+
+export interface CanvasOperation {
+  readonly schemaVersion: 1;
+  readonly operationId: string;
+  readonly mutations: readonly CanvasMutation[];
+}
+
+export type CanvasFileIdentity =
+  | { readonly relativePath: string }
+  | { readonly assetId: string };
+
+/**
+ * Pan-vs-drag rule: the pointerdown target decides, once, and the decision is
+ * never revised for the rest of the gesture.
+ *
+ *  * no marker, or a marker the canvas does not own → pan the stage;
+ *  * a node marked `move` → drag that node;
+ *  * a node's corner marked `resize` → resize that node;
+ *  * a marked `control` (the remove button) → no gesture at all, the click
+ *    belongs to the control.
+ *
+ * Because the choice is frozen at pointerdown, a node drag that wanders off the
+ * node stays a node drag and a pan that crosses a node stays a pan: neither
+ * needs a movement threshold to disambiguate, and the pointer can be captured
+ * on the viewport so a drag that leaves the surface still delivers its moves.
+ */
+export type CanvasPointerGesture = "pan" | "move" | "resize" | "none";
+
+export const CANVAS_GESTURE_ATTRIBUTE = "data-canvas-gesture";
+export const CANVAS_NODE_ID_ATTRIBUTE = "data-canvas-node-id";
+
+export function resolveCanvasPointerGesture(
+  marker: string | null | undefined,
+): CanvasPointerGesture {
+  if (marker === "move" || marker === "resize") return marker;
+  if (marker === "control") return "none";
+  return "pan";
+}
+
+/** Reads the gesture marker an element (or an ancestor) carries. */
+function readCanvasGestureContext(target: EventTarget | null): {
+  readonly kind: CanvasPointerGesture;
+  readonly nodeId?: string;
+} {
+  const element = target instanceof Element ? target : null;
+  const marker = element?.closest(
+    `[${CANVAS_GESTURE_ATTRIBUTE}="move"], [${CANVAS_GESTURE_ATTRIBUTE}="resize"]`,
+  ) ?? null;
+  const kind = resolveCanvasPointerGesture(marker?.getAttribute(CANVAS_GESTURE_ATTRIBUTE) ?? null);
+  const nodeId = marker?.getAttribute(CANVAS_NODE_ID_ATTRIBUTE) ?? undefined;
+  // A move/resize marker without a node identity is a wiring bug, not a pan.
+  if ((kind === "move" || kind === "resize") && !nodeId) return { kind: "none" };
+  return nodeId ? { kind, nodeId } : { kind };
+}
+
+function roundCanvasNumber(value: number): number {
+  return Number.isFinite(value) ? Math.round(value) : 0;
+}
+
+function normalizeCanvasZIndex(value: number): number {
+  return Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : 0;
+}
+
+/** Brings a layout inside the bounds the runtime validates before storing it. */
+export function normalizeCanvasLayout(layout: CanvasNodeLayout): CanvasNodeLayout {
+  return {
+    x: roundCanvasNumber(layout.x),
+    y: roundCanvasNumber(layout.y),
+    width: Math.max(CANVAS_MIN_NODE_SIZE, roundCanvasNumber(layout.width)),
+    height: Math.max(CANVAS_MIN_NODE_SIZE, roundCanvasNumber(layout.height)),
+    zIndex: normalizeCanvasZIndex(layout.zIndex),
+  };
+}
+
+export function clampCanvasZoom(value: number): number {
+  if (!Number.isFinite(value)) return 1;
+  // Rounded to two decimals so repeated 0.1 steps cannot accumulate float
+  // error, while keeping the step and the clamp ends exactly as shipped.
+  return Math.round(Math.min(CANVAS_ZOOM_MAX, Math.max(CANVAS_ZOOM_MIN, value)) * 100) / 100;
+}
+
+/** `deltaY > 0` scrolls down and zooms out, as the panel has always done. */
+export function stepCanvasZoom(current: number, deltaY: number): number {
+  const base = Number.isFinite(current) ? current : 1;
+  return clampCanvasZoom(base + (deltaY > 0 ? -CANVAS_ZOOM_STEP : CANVAS_ZOOM_STEP));
+}
+
+/**
+ * The stage transforms as `translate(pan) scale(zoom)` from a `0 0` origin, so
+ * the translation is already in screen pixels while a node's layout is in
+ * canvas units: a pointer delta has to be divided by the zoom to move a node by
+ * the amount the pointer travelled.
+ */
+export function pointerDeltaToCanvas(
+  deltaX: number,
+  deltaY: number,
+  zoom: number,
+): { readonly dx: number; readonly dy: number } {
+  const scale = Number.isFinite(zoom) && zoom > 0 ? zoom : 1;
+  return { dx: roundCanvasNumber(deltaX / scale), dy: roundCanvasNumber(deltaY / scale) };
+}
+
+export function canvasPointerMoveLayout(
+  start: CanvasNodeLayout,
+  deltaClientX: number,
+  deltaClientY: number,
+  zoom: number,
+): CanvasNodeLayout {
+  const delta = pointerDeltaToCanvas(deltaClientX, deltaClientY, zoom);
+  return normalizeCanvasLayout({ ...start, x: start.x + delta.dx, y: start.y + delta.dy });
+}
+
+export function canvasPointerResizeLayout(
+  start: CanvasNodeLayout,
+  deltaClientX: number,
+  deltaClientY: number,
+  zoom: number,
+): CanvasNodeLayout {
+  const delta = pointerDeltaToCanvas(deltaClientX, deltaClientY, zoom);
+  return normalizeCanvasLayout({
+    ...start,
+    width: start.width + delta.dx,
+    height: start.height + delta.dy,
+  });
+}
+
+export interface CanvasDirection {
+  readonly dx: number;
+  readonly dy: number;
+}
+
+export function canvasArrowDirection(key: string): CanvasDirection | undefined {
+  switch (key) {
+    case "ArrowLeft": return { dx: -1, dy: 0 };
+    case "ArrowRight": return { dx: 1, dy: 0 };
+    case "ArrowUp": return { dx: 0, dy: -1 };
+    case "ArrowDown": return { dx: 0, dy: 1 };
+    default: return undefined;
+  }
+}
+
+export function canvasKeyStep(shiftKey: boolean): number {
+  return shiftKey ? CANVAS_NUDGE_STEP_LARGE : CANVAS_NUDGE_STEP;
+}
+
+/** Keyboard equivalent of dragging a node. */
+export function nudgeCanvasLayout(
+  layout: CanvasNodeLayout,
+  direction: CanvasDirection,
+  step: number,
+): CanvasNodeLayout {
+  return normalizeCanvasLayout({
+    ...layout,
+    x: layout.x + direction.dx * step,
+    y: layout.y + direction.dy * step,
+  });
+}
+
+/** Keyboard equivalent of dragging the resize corner. */
+export function resizeCanvasLayoutBy(
+  layout: CanvasNodeLayout,
+  direction: CanvasDirection,
+  step: number,
+): CanvasNodeLayout {
+  return normalizeCanvasLayout({
+    ...layout,
+    width: layout.width + direction.dx * step,
+    height: layout.height + direction.dy * step,
+  });
+}
+
+export function canvasLayoutsEqual(
+  left: CanvasNodeLayout | undefined,
+  right: CanvasNodeLayout | undefined,
+): boolean {
+  if (!left || !right) return left === right;
+  return left.x === right.x
+    && left.y === right.y
+    && left.width === right.width
+    && left.height === right.height
+    && left.zIndex === right.zIndex;
+}
+
+export function buildCanvasUpdateLayoutMutation(
+  nodeId: string,
+  layout: CanvasNodeLayout,
+): CanvasMutation {
+  return { kind: "update_layout", nodeId, layout: normalizeCanvasLayout(layout) };
+}
+
+/** Emits exactly one file identity key, never both and never neither. */
+export function buildCanvasAddFileMutation(
+  nodeId: string,
+  layout: CanvasNodeLayout,
+  target: CanvasFileIdentity,
+): CanvasMutation {
+  const base = { kind: "add_file" as const, nodeId, layout: normalizeCanvasLayout(layout) };
+  return "assetId" in target
+    ? { ...base, assetId: target.assetId }
+    : { ...base, relativePath: target.relativePath };
+}
+
+export function buildCanvasRemoveNodeMutation(nodeId: string): CanvasMutation {
+  return { kind: "remove_node", nodeId };
+}
+
+/**
+ * The runtime keys applied operations by `(sessionId, operationId)` and
+ * rejects a reuse whose payload differs, so every operation needs a fresh id
+ * rather than a stable one derived from the node.
+ */
+export function createCanvasOperationId(): string {
+  return randomCanvasId("canvas-op");
+}
+
+export function createCanvasNodeId(): string {
+  return randomCanvasId("canvas-node");
+}
+
+function randomCanvasId(prefix: string): string {
+  const webCrypto = globalThis.crypto;
+  const unique = typeof webCrypto?.randomUUID === "function"
+    ? webCrypto.randomUUID()
+    : `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
+  return `${prefix}_${unique}`;
+}
+
+/**
+ * Fails here for exactly the two reasons the runtime rejects an operation, so
+ * the panel never sends a payload that is guaranteed to be refused.
+ */
+export function buildCanvasOperation(
+  operationId: string,
+  mutations: readonly CanvasMutation[],
+): CanvasOperation {
+  const id = operationId.trim();
+  if (!id) throw new Error("canvas operationId is required");
+  if (mutations.length === 0) throw new Error("canvas operation needs at least one mutation");
+  return { schemaVersion: 1, operationId: id, mutations: [...mutations] };
+}
+
+export function nextCanvasZIndex(nodes: readonly CanvasNodeView[]): number {
+  return nodes.reduce((highest, node) => Math.max(highest, node.layout.zIndex), 0) + 1;
+}
+
+/** Cascades a new node so consecutive adds do not stack on one spot. */
+export function nextCanvasNodeLayout(nodes: readonly CanvasNodeView[]): CanvasNodeLayout {
+  const index = Math.max(0, nodes.length);
+  const column = index % CANVAS_ADD_COLUMNS;
+  const row = Math.floor(index / CANVAS_ADD_COLUMNS);
+  return normalizeCanvasLayout({
+    x: CANVAS_ADD_ORIGIN + column * CANVAS_ADD_GAP_X,
+    y: CANVAS_ADD_ORIGIN + row * CANVAS_ADD_GAP_Y,
+    width: CANVAS_ADD_WIDTH,
+    height: CANVAS_ADD_HEIGHT,
+    zIndex: nextCanvasZIndex(nodes),
+  });
+}
+
+export function describeCanvasError(cause: unknown): string {
+  if (cause instanceof Error && cause.message.trim()) return cause.message;
+  if (typeof cause === "string" && cause.trim()) return cause.trim();
+  return DESKTOP_COPY.canvasFailed;
+}
+
+function readCanvasRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function readCanvasLayout(value: unknown): CanvasNodeLayout | undefined {
+  const record = readCanvasRecord(value);
+  if (!record) return undefined;
+  const { x, y, width, height, zIndex } = record;
+  if (
+    typeof x !== "number" || !Number.isFinite(x)
+    || typeof y !== "number" || !Number.isFinite(y)
+    || typeof width !== "number" || !Number.isFinite(width)
+    || typeof height !== "number" || !Number.isFinite(height)
+  ) return undefined;
+  return normalizeCanvasLayout({
+    x,
+    y,
+    width,
+    height,
+    zIndex: typeof zIndex === "number" ? zIndex : 0,
+  });
+}
+
+/**
+ * `WebuiCanvasDocument.nodes` is `Record<string, unknown>[]` at the webui
+ * boundary, so a node missing its id or its layout is dropped rather than
+ * allowed to break the render.
+ */
+export function parseCanvasNodes(
+  document: WebuiCanvasDocument | undefined,
+): readonly CanvasNodeView[] {
+  const nodes = Array.isArray(document?.nodes) ? document?.nodes : [];
+  const parsed: CanvasNodeView[] = [];
+  for (const raw of nodes ?? []) {
+    const record = readCanvasRecord(raw);
+    const id = typeof record?.id === "string" ? record.id : "";
+    const layout = readCanvasLayout(record?.layout);
+    if (!id || !layout) continue;
+    const file = readCanvasRecord(record?.file);
+    const fileName = typeof file?.fileName === "string" ? file.fileName : "";
+    const relativePath = typeof file?.relativePath === "string" ? file.relativePath : "";
+    parsed.push({ id, label: fileName || relativePath || id, layout });
+  }
+  return parsed;
+}
+
+export interface CanvasLayoutPreview {
+  readonly nodeId: string;
+  readonly layout: CanvasNodeLayout;
+}
+
+/**
+ * The in-flight drag preview. It is deliberately separate from the canvas
+ * document: the document stays the last server-confirmed truth, and a refused
+ * operation drops the preview rather than leaving an optimistic value on screen.
+ */
+export function applyCanvasLayoutPreview(
+  nodes: readonly CanvasNodeView[],
+  preview: CanvasLayoutPreview | undefined,
+): readonly CanvasNodeView[] {
+  if (!preview) return nodes;
+  return nodes.map((node) =>
+    node.id === preview.nodeId ? { ...node, layout: preview.layout } : node,
+  );
+}
+
+interface CanvasGestureState {
+  readonly kind: CanvasPointerGesture;
+  readonly pointerId: number;
+  readonly startClientX: number;
+  readonly startClientY: number;
+  readonly startZoom: number;
+  readonly startPan: CanvasPan;
+  readonly startLayout?: CanvasNodeLayout;
+  readonly nodeId?: string;
+}
+
+export function WorkspaceCanvas({ sessionId, readCanvas, applyCanvas }: {
   /** The session whose canvas document is shown; absent means no canvas. */
   readonly sessionId?: string;
   /** Port call that reads the canvas document for a session. */
   readonly readCanvas?: (request: { sessionId: string }) => Promise<WebuiCanvasDocument>;
+  /**
+   * Port call that applies one operation and returns the document the runtime
+   * actually stored. Absent means the canvas is read-only, and the panel says
+   * so instead of pretending a change was saved.
+   */
+  readonly applyCanvas?: (request: {
+    readonly sessionId: string;
+    readonly operation: CanvasOperation;
+  }) => Promise<{ readonly operationId: string; readonly document: WebuiCanvasDocument }>;
 }): ReactElement {
   const [canvas, setCanvas] = useState<WebuiCanvasDocument>();
   const [zoom, setZoom] = useState(1);
+  const [pan, setPan] = useState<CanvasPan>({ x: 0, y: 0 });
+  const [preview, setPreview] = useState<CanvasLayoutPreview>();
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string>();
+  const [notice, setNotice] = useState<string>();
+  const [draftPath, setDraftPath] = useState("");
+  const gestureRef = useRef<CanvasGestureState>();
+  const viewportRef = useRef<HTMLDivElement>(null);
+  // Identifies the newest read or apply so a late reply from a session the user
+  // has already left cannot overwrite the current document.
+  const applySeqRef = useRef(0);
+
   useEffect(() => {
     if (!sessionId || !readCanvas) { setCanvas(undefined); return undefined; }
     let cancelled = false;
-    void readCanvas({ sessionId }).then((next) => { if (!cancelled) setCanvas(next); }).catch(() => { if (!cancelled) setCanvas(undefined); });
+    void readCanvas({ sessionId })
+      .then((next) => { if (!cancelled) { setCanvas(next); setError(undefined); } })
+      .catch((cause: unknown) => {
+        if (cancelled) return;
+        setCanvas(undefined);
+        setError(describeCanvasError(cause));
+      });
     return () => { cancelled = true; };
   }, [sessionId, readCanvas]);
-  return <div className="webui-canvas-content" onWheel={(event) => { event.preventDefault(); setZoom((value) => Math.max(.4, Math.min(2, value + (event.deltaY > 0 ? -.1 : .1)))); }}>
-    {!canvas?.nodes.length ? <><strong>{DESKTOP_COPY.canvasEmptyTitle}</strong><p>{DESKTOP_COPY.canvasEmptyDescription}</p></> : <div className="webui-canvas-stage" style={{ transform: `scale(${zoom})` }}>{canvas.nodes.map((node) => <div className="webui-canvas-node" key={String(node.id)}>{String((node.file as Record<string, unknown> | undefined)?.fileName ?? node.id)}</div>)}</div>}
+
+  // A different session is a different world: start it at the origin.
+  useEffect(() => {
+    setPan({ x: 0, y: 0 });
+    setZoom(1);
+    setPreview(undefined);
+  }, [sessionId]);
+
+  const confirmedNodes = parseCanvasNodes(canvas);
+  const nodes = applyCanvasLayoutPreview(confirmedNodes, preview);
+  const readOnly = !applyCanvas || !sessionId;
+
+  const applyMutations = (
+    mutations: readonly CanvasMutation[],
+    onSuccess?: () => void,
+  ): void => {
+    const port = applyCanvas;
+    const targetSessionId = sessionId;
+    if (!port || !targetSessionId) { setError(DESKTOP_COPY.canvasReadOnly); return; }
+    let operation: CanvasOperation;
+    try {
+      operation = buildCanvasOperation(createCanvasOperationId(), mutations);
+    } catch (cause: unknown) {
+      setError(describeCanvasError(cause));
+      return;
+    }
+    const seq = ++applySeqRef.current;
+    setBusy(true);
+    setError(undefined);
+    setNotice(undefined);
+    void port({ sessionId: targetSessionId, operation })
+      .then((result) => {
+        if (seq !== applySeqRef.current) return;
+        setCanvas(result.document);
+        setPreview(undefined);
+        onSuccess?.();
+      })
+      .catch((cause: unknown) => {
+        if (seq !== applySeqRef.current) return;
+        // The stored document is still the last one this view read, so drop the
+        // optimistic preview and report the refusal instead of keeping it.
+        setPreview(undefined);
+        setError(describeCanvasError(cause));
+      })
+      .finally(() => { if (seq === applySeqRef.current) setBusy(false); });
+  };
+
+  const releaseCapture = (pointerId: number): void => {
+    try { viewportRef.current?.releasePointerCapture(pointerId); } catch { /* already released */ }
+  };
+
+  const handlePointerDown = (event: ReactPointerEvent<HTMLElement>): void => {
+    const context = readCanvasGestureContext(event.target);
+    if (context.kind === "none") return;
+    if (event.pointerType === "mouse" && event.button !== 0) return;
+    if (busy) { setNotice(DESKTOP_COPY.canvasBusy); return; }
+    const startLayout = context.nodeId
+      ? confirmedNodes.find((node) => node.id === context.nodeId)?.layout
+      : undefined;
+    if ((context.kind === "move" || context.kind === "resize") && !startLayout) return;
+    gestureRef.current = {
+      kind: context.kind,
+      pointerId: event.pointerId,
+      startClientX: event.clientX,
+      startClientY: event.clientY,
+      startZoom: zoom,
+      startPan: pan,
+      ...(startLayout ? { startLayout } : {}),
+      ...(context.nodeId ? { nodeId: context.nodeId } : {}),
+    };
+    // Capture on the viewport for every gesture: the decision is already in the
+    // ref, so a pointer that leaves the surface still reports its moves.
+    try { viewportRef.current?.setPointerCapture(event.pointerId); } catch { /* best effort */ }
+    event.preventDefault();
+  };
+
+  const handlePointerMove = (event: ReactPointerEvent<HTMLElement>): void => {
+    const gesture = gestureRef.current;
+    if (!gesture || gesture.pointerId !== event.pointerId) return;
+    const deltaClientX = event.clientX - gesture.startClientX;
+    const deltaClientY = event.clientY - gesture.startClientY;
+    if (gesture.kind === "pan") {
+      setPan({ x: gesture.startPan.x + deltaClientX, y: gesture.startPan.y + deltaClientY });
+      return;
+    }
+    if (!gesture.startLayout || !gesture.nodeId) return;
+    setPreview({
+      nodeId: gesture.nodeId,
+      layout: gesture.kind === "resize"
+        ? canvasPointerResizeLayout(gesture.startLayout, deltaClientX, deltaClientY, gesture.startZoom)
+        : canvasPointerMoveLayout(gesture.startLayout, deltaClientX, deltaClientY, gesture.startZoom),
+    });
+  };
+
+  const handlePointerUp = (event: ReactPointerEvent<HTMLElement>): void => {
+    const gesture = gestureRef.current;
+    if (!gesture || gesture.pointerId !== event.pointerId) return;
+    // Clear before releasing, so the implicit lostpointercapture is a no-op.
+    gestureRef.current = undefined;
+    releaseCapture(event.pointerId);
+    if (!gesture.startLayout || !gesture.nodeId) return;
+    const deltaClientX = event.clientX - gesture.startClientX;
+    const deltaClientY = event.clientY - gesture.startClientY;
+    const layout = gesture.kind === "resize"
+      ? canvasPointerResizeLayout(gesture.startLayout, deltaClientX, deltaClientY, gesture.startZoom)
+      : canvasPointerMoveLayout(gesture.startLayout, deltaClientX, deltaClientY, gesture.startZoom);
+    if (canvasLayoutsEqual(layout, gesture.startLayout)) { setPreview(undefined); return; }
+    applyMutations([buildCanvasUpdateLayoutMutation(gesture.nodeId, layout)]);
+  };
+
+  const handlePointerCancel = (): void => {
+    if (!gestureRef.current) return;
+    gestureRef.current = undefined;
+    setPreview(undefined);
+  };
+
+  const handlePanKeyDown = (event: ReactKeyboardEvent<HTMLDivElement>): void => {
+    const direction = canvasArrowDirection(event.key);
+    if (!direction) return;
+    event.preventDefault();
+    const step = canvasKeyStep(event.shiftKey) * CANVAS_PAN_KEY_SCALE;
+    setPan((current) => ({
+      x: current.x + direction.dx * step,
+      y: current.y + direction.dy * step,
+    }));
+  };
+
+  const handleNodeKeyDown = (
+    event: ReactKeyboardEvent<HTMLDivElement>,
+    node: CanvasNodeView,
+  ): void => {
+    const direction = canvasArrowDirection(event.key);
+    if (!direction) return;
+    if (readOnly) { setError(DESKTOP_COPY.canvasReadOnly); return; }
+    event.preventDefault();
+    const step = canvasKeyStep(event.shiftKey);
+    // Drag and resize both have a real keyboard equivalent, so the pointer
+    // interaction is never the only way to reach a layout.
+    const layout = event.altKey
+      ? resizeCanvasLayoutBy(node.layout, direction, step)
+      : nudgeCanvasLayout(node.layout, direction, step);
+    applyMutations([buildCanvasUpdateLayoutMutation(node.id, layout)]);
+  };
+
+  const handleAddSubmit = (event: FormEvent): void => {
+    event.preventDefault();
+    const relativePath = draftPath.trim();
+    if (!relativePath) { setError(DESKTOP_COPY.canvasAddRequired); return; }
+    if (readOnly) { setError(DESKTOP_COPY.canvasReadOnly); return; }
+    applyMutations(
+      [buildCanvasAddFileMutation(createCanvasNodeId(), nextCanvasNodeLayout(confirmedNodes), { relativePath })],
+      () => setDraftPath(""),
+    );
+  };
+
+  const handleWheel = (event: ReactWheelEvent<HTMLDivElement>): void => {
+    event.preventDefault();
+    setZoom((value) => stepCanvasZoom(value, event.deltaY));
+  };
+
+  return <div className="webui-canvas-content" onWheel={handleWheel}>
+    {nodes.length === 0 ? <><strong>{DESKTOP_COPY.canvasEmptyTitle}</strong><p>{DESKTOP_COPY.canvasEmptyDescription}</p></> : <div
+      ref={viewportRef}
+      role="group"
+      aria-label={DESKTOP_COPY.canvasStageLabel}
+      tabIndex={0}
+      onPointerDown={handlePointerDown}
+      onPointerMove={handlePointerMove}
+      onPointerUp={handlePointerUp}
+      onPointerCancel={handlePointerCancel}
+      onLostPointerCapture={handlePointerCancel}
+      onKeyDown={handlePanKeyDown}
+      style={{
+        position: "absolute",
+        inset: 0,
+        overflow: "hidden",
+        textAlign: "left",
+        touchAction: "none",
+        cursor: "grab",
+      }}
+    >
+      <div
+        className="webui-canvas-stage"
+        style={{
+          position: "absolute",
+          left: 0,
+          top: 0,
+          display: "block",
+          width: CANVAS_WORLD_SIZE,
+          height: CANVAS_WORLD_SIZE,
+          transformOrigin: "0 0",
+          transform: `translate(${pan.x}px, ${pan.y}px) scale(${zoom})`,
+        }}
+      >
+        {nodes.map((node) => <div
+          key={node.id}
+          className="webui-canvas-node"
+          role="group"
+          tabIndex={0}
+          aria-label={`${node.label}。${DESKTOP_COPY.canvasNodeHint}`}
+          aria-keyshortcuts="ArrowUp ArrowRight ArrowDown ArrowLeft"
+          // Literal attributes, matching CANVAS_GESTURE_ATTRIBUTE /
+          // CANVAS_NODE_ID_ATTRIBUTE, which readCanvasGestureContext queries.
+          data-canvas-gesture="move"
+          data-canvas-node-id={node.id}
+          onKeyDown={(event) => handleNodeKeyDown(event, node)}
+          style={{
+            position: "absolute",
+            left: node.layout.x,
+            top: node.layout.y,
+            width: node.layout.width,
+            height: node.layout.height,
+            zIndex: node.layout.zIndex,
+            boxSizing: "border-box",
+            overflow: "hidden",
+            touchAction: "none",
+            cursor: "grab",
+            userSelect: "none",
+          }}
+        >
+          <span style={{ display: "block", padding: "var(--spacing_8)", overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>{node.label}</span>
+          <button
+            type="button"
+            data-canvas-gesture="control"
+            disabled={readOnly || busy}
+            onClick={() => applyMutations([buildCanvasRemoveNodeMutation(node.id)])}
+            style={{ position: "absolute", top: "var(--spacing_8)", right: "var(--spacing_8)", border: "1px solid var(--border_default)", borderRadius: "var(--radius_8)", background: "var(--bg_grouped_secondary)", color: "inherit", padding: "2px var(--spacing_8)", fontSize: "var(--size_12)", cursor: "pointer" }}
+          >{DESKTOP_COPY.canvasNodeRemove}</button>
+          <div
+            aria-hidden="true"
+            data-canvas-gesture="resize"
+            style={{ position: "absolute", right: 0, bottom: 0, width: 16, height: 16, cursor: "nwse-resize", touchAction: "none", background: "var(--border_default)" }}
+          />
+        </div>)}
+      </div>
+    </div>}
     <span className="webui-canvas-zoom">{Math.round(zoom * 100)}%</span>
+    <form
+      onSubmit={handleAddSubmit}
+      style={{ position: "absolute", left: "var(--spacing_16)", top: "var(--spacing_16)", display: "flex", gap: "var(--spacing_8)", alignItems: "center" }}
+    >
+      <input
+        aria-label={DESKTOP_COPY.canvasAddLabel}
+        placeholder={DESKTOP_COPY.canvasAddPlaceholder}
+        value={draftPath}
+        disabled={readOnly}
+        onChange={(event) => setDraftPath(event.target.value)}
+        style={{ border: "1px solid var(--border_default)", borderRadius: "var(--radius_8)", background: "var(--bg_grouped_secondary)", color: "var(--text_default_primary)", padding: "var(--spacing_8)", fontSize: "var(--size_12)", textAlign: "left" }}
+      />
+      <button
+        type="submit"
+        disabled={readOnly || busy}
+        style={{ border: "1px solid var(--border_default)", borderRadius: "var(--radius_8)", background: "transparent", color: "var(--text_default_primary)", padding: "var(--spacing_8) var(--spacing_12)", fontSize: "var(--size_12)", cursor: "pointer" }}
+      >{DESKTOP_COPY.canvasAddSubmit}</button>
+    </form>
+    {/* Status text is stacked in one column so the read-only note, the
+        in-flight state, a notice and a failure can never overlap. */}
+    <div style={{ position: "absolute", left: "var(--spacing_16)", bottom: "var(--spacing_8)", display: "flex", flexDirection: "column", gap: "var(--spacing_4)", alignItems: "flex-start", textAlign: "left" }}>
+      {readOnly ? <p style={{ margin: 0, color: "var(--text_default_tertiary)", fontSize: "var(--size_12)" }}>{DESKTOP_COPY.canvasReadOnly}</p> : null}
+      {busy ? <p role="status" style={{ margin: 0, color: "var(--text_default_tertiary)", fontSize: "var(--size_12)" }}>{DESKTOP_COPY.canvasSaving}</p> : null}
+      {notice ? <p role="status" style={{ margin: 0, color: "var(--text_default_tertiary)", fontSize: "var(--size_12)" }}>{notice}</p> : null}
+      {error ? <p role="alert" style={{ margin: 0, color: "var(--text_default_primary)", fontSize: "var(--size_12)" }}>{error}</p> : null}
+    </div>
   </div>;
 }
diff --git a/packages/webui/test/unit/webui-workspace-canvas.test.tsx b/packages/webui/test/unit/webui-workspace-canvas.test.tsx
new file mode 100644
index 000000000..6e4d57b70
--- /dev/null
+++ b/packages/webui/test/unit/webui-workspace-canvas.test.tsx
@@ -0,0 +1,434 @@
+// Unit tests for the workspace canvas (`WorkspaceCanvas.tsx`).
+//
+// Rendered through `renderToStaticMarkup` — the project's SSR test convention
+// (see `workspace-panel-state.test.ts`). That runs no effects and dispatches no
+// events, so it can only assert what the panel emits before the first read
+// lands: the empty state, the zoom readout and the read-only notice.
+//
+// Everything stateful is therefore exported as a pure function from the
+// component and driven directly here — the zoom clamp, the pointer-to-canvas
+// coordinate mapping, the pan-vs-drag rule, the preview that a drag renders, and
+// the operation payload the panel hands to `applyCanvas`.
+//
+// The clauses these pin shut:
+//   * wheel zoom keeps the shipped 0.4–2.0 clamp and 0.1 step, at both ends,
+//     and cannot accumulate float error;
+//   * a pointer delta becomes a canvas delta by dividing by the zoom, because
+//     the stage is `translate(pan) scale(zoom)` from a `0 0` origin;
+//   * a pan is not a drag: the pointerdown marker alone picks the gesture, and
+//     an unmarked pointerdown pans while a marked control does neither;
+//   * the operation sent to `applyCanvas` is exactly the runtime's
+//     `CanvasOperationV1`, carries one and only one file identity on
+//     `add_file`, and survives the JSON wire;
+//   * a refused operation leaves the confirmed document in place rather than an
+//     optimistic value, and a malformed node cannot break the render.
+
+import { describe, expect, it } from "vitest";
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import {
+  CANVAS_GESTURE_ATTRIBUTE,
+  CANVAS_MIN_NODE_SIZE,
+  CANVAS_NODE_ID_ATTRIBUTE,
+  CANVAS_NUDGE_STEP,
+  CANVAS_NUDGE_STEP_LARGE,
+  CANVAS_ZOOM_MAX,
+  CANVAS_ZOOM_MIN,
+  CANVAS_ZOOM_STEP,
+  WorkspaceCanvas,
+  applyCanvasLayoutPreview,
+  buildCanvasAddFileMutation,
+  buildCanvasOperation,
+  buildCanvasRemoveNodeMutation,
+  buildCanvasUpdateLayoutMutation,
+  canvasArrowDirection,
+  canvasKeyStep,
+  canvasLayoutsEqual,
+  canvasPointerMoveLayout,
+  canvasPointerResizeLayout,
+  clampCanvasZoom,
+  createCanvasNodeId,
+  createCanvasOperationId,
+  describeCanvasError,
+  nextCanvasNodeLayout,
+  nextCanvasZIndex,
+  normalizeCanvasLayout,
+  nudgeCanvasLayout,
+  parseCanvasNodes,
+  pointerDeltaToCanvas,
+  resizeCanvasLayoutBy,
+  resolveCanvasPointerGesture,
+  stepCanvasZoom,
+  type CanvasNodeLayout,
+  type CanvasNodeView,
+} from "../../src/client/components/WorkspaceCanvas.js";
+import type { WebuiCanvasDocument } from "../../src/server/port.js";
+
+const LAYOUT: CanvasNodeLayout = { x: 100, y: 200, width: 240, height: 180, zIndex: 3 };
+
+function node(id: string, layout: Partial<CanvasNodeLayout> = {}): CanvasNodeView {
+  return { id, label: `${id}.png`, layout: normalizeCanvasLayout({ ...LAYOUT, ...layout }) };
+}
+
+/** Casts on purpose: several cases below feed the panel a malformed node. */
+function document(nodes: readonly unknown[]): WebuiCanvasDocument {
+  return {
+    schemaVersion: 1,
+    canvasId: "canvas_1",
+    sessionId: "session-1",
+    changeSeq: 1,
+    nodes: nodes as readonly Record<string, unknown>[],
+    updatedAtMs: 0,
+  };
+}
+
+describe("canvas zoom", () => {
+  it("clamps at both ends and passes interior values through", () => {
+    expect(clampCanvasZoom(0.1)).toBe(CANVAS_ZOOM_MIN);
+    expect(clampCanvasZoom(-4)).toBe(CANVAS_ZOOM_MIN);
+    expect(clampCanvasZoom(5)).toBe(CANVAS_ZOOM_MAX);
+    expect(clampCanvasZoom(1.35)).toBe(1.35);
+  });
+
+  it("keeps the clamp boundaries themselves inclusive", () => {
+    expect(clampCanvasZoom(CANVAS_ZOOM_MIN)).toBe(CANVAS_ZOOM_MIN);
+    expect(clampCanvasZoom(CANVAS_ZOOM_MAX)).toBe(CANVAS_ZOOM_MAX);
+  });
+
+  it("falls back to 1 for a value that is not a number, at either infinity", () => {
+    expect(clampCanvasZoom(Number.NaN)).toBe(1);
+    expect(clampCanvasZoom(Number.POSITIVE_INFINITY)).toBe(1);
+    expect(clampCanvasZoom(Number.NEGATIVE_INFINITY)).toBe(1);
+  });
+
+  it("zooms out on a downward wheel and in on an upward one, by one step", () => {
+    expect(stepCanvasZoom(1, 120)).toBe(1 - CANVAS_ZOOM_STEP);
+    expect(stepCanvasZoom(1, -120)).toBe(1 + CANVAS_ZOOM_STEP);
+  });
+
+  it("stops at 0.4 and 2.0 however long the wheel turns", () => {
+    let zoomedOut = 1;
+    for (let step = 0; step < 40; step += 1) zoomedOut = stepCanvasZoom(zoomedOut, 120);
+    expect(zoomedOut).toBe(CANVAS_ZOOM_MIN);
+
+    let zoomedIn = 1;
+    for (let step = 0; step < 40; step += 1) zoomedIn = stepCanvasZoom(zoomedIn, -120);
+    expect(zoomedIn).toBe(CANVAS_ZOOM_MAX);
+  });
+
+  it("does not accumulate float error over repeated steps", () => {
+    let zoom = CANVAS_ZOOM_MIN;
+    for (let step = 0; step < 10; step += 1) zoom = stepCanvasZoom(zoom, -120);
+    expect(zoom).toBe(1.4);
+    expect(`${zoom}`).toBe("1.4");
+  });
+});
+
+describe("canvas coordinate mapping under scale", () => {
+  it("passes a delta through unchanged at zoom 1", () => {
+    expect(pointerDeltaToCanvas(12, -7, 1)).toEqual({ dx: 12, dy: -7 });
+  });
+
+  it("divides by the zoom, so half zoom doubles the canvas distance", () => {
+    expect(pointerDeltaToCanvas(10, 20, 0.5)).toEqual({ dx: 20, dy: 40 });
+    expect(pointerDeltaToCanvas(10, 20, 2)).toEqual({ dx: 5, dy: 10 });
+  });
+
+  it("treats a zero or unusable zoom as 1 rather than dividing by zero", () => {
+    expect(pointerDeltaToCanvas(10, 20, 0)).toEqual({ dx: 10, dy: 20 });
+    expect(pointerDeltaToCanvas(10, 20, Number.NaN)).toEqual({ dx: 10, dy: 20 });
+    expect(pointerDeltaToCanvas(10, 20, -1)).toEqual({ dx: 10, dy: 20 });
+  });
+
+  it("moves a node by the canvas distance the pointer travelled", () => {
+    const moved = canvasPointerMoveLayout(LAYOUT, 50, -25, 0.5);
+    expect(moved).toMatchObject({ x: 200, y: 150 });
+    // The size is untouched by a move.
+    expect(moved).toMatchObject({ width: 240, height: 180, zIndex: 3 });
+  });
+
+  it("resizes a node by the same converted distance, keeping its origin", () => {
+    const resized = canvasPointerResizeLayout(LAYOUT, 20, 40, 0.5);
+    expect(resized).toMatchObject({ x: 100, y: 200, width: 280, height: 260 });
+  });
+
+  it("keeps a resized node above the minimum the runtime validates", () => {
+    const shrunk = canvasPointerResizeLayout(LAYOUT, -10_000, -10_000, 1);
+    expect(shrunk).toMatchObject({ width: CANVAS_MIN_NODE_SIZE, height: CANVAS_MIN_NODE_SIZE });
+  });
+});
+
+describe("canvas pan-versus-drag rule", () => {
+  it("pans for a pointerdown with no marker, including an unknown one", () => {
+    expect(resolveCanvasPointerGesture(undefined)).toBe("pan");
+    expect(resolveCanvasPointerGesture(null)).toBe("pan");
+    expect(resolveCanvasPointerGesture("")).toBe("pan");
+    expect(resolveCanvasPointerGesture("something-else")).toBe("pan");
+  });
+
+  it("drags the node and resizes it for the two node markers", () => {
+    expect(resolveCanvasPointerGesture("move")).toBe("move");
+    expect(resolveCanvasPointerGesture("resize")).toBe("resize");
+  });
+
+  it("starts no gesture at all for a marked control, so its click is its own", () => {
+    expect(resolveCanvasPointerGesture("control")).toBe("none");
+  });
+
+  it("decides from the marker alone, so a gesture is never revised mid-drag", () => {
+    // The rule is a pure function of the pointerdown target: the same marker
+    // always yields the same gesture, and a node drag that wanders off the node
+    // (or a pan that crosses one) cannot change what it became.
+    const first = resolveCanvasPointerGesture("move");
+    const later = resolveCanvasPointerGesture("move");
+    expect(first).toBe("move");
+    expect(later).toBe(first);
+  });
+
+  it("pins the attribute names the component queries and renders", () => {
+    expect(CANVAS_GESTURE_ATTRIBUTE).toBe("data-canvas-gesture");
+    expect(CANVAS_NODE_ID_ATTRIBUTE).toBe("data-canvas-node-id");
+  });
+});
+
+describe("canvas keyboard equivalents", () => {
+  it("maps the arrow keys and ignores everything else", () => {
+    expect(canvasArrowDirection("ArrowLeft")).toEqual({ dx: -1, dy: 0 });
+    expect(canvasArrowDirection("ArrowRight")).toEqual({ dx: 1, dy: 0 });
+    expect(canvasArrowDirection("ArrowUp")).toEqual({ dx: 0, dy: -1 });
+    expect(canvasArrowDirection("ArrowDown")).toEqual({ dx: 0, dy: 1 });
+    expect(canvasArrowDirection("Enter")).toBeUndefined();
+    expect(canvasArrowDirection("a")).toBeUndefined();
+  });
+
+  it("accelerates with Shift", () => {
+    expect(canvasKeyStep(false)).toBe(CANVAS_NUDGE_STEP);
+    expect(canvasKeyStep(true)).toBe(CANVAS_NUDGE_STEP_LARGE);
+  });
+
+  it("nudges a node without resizing it", () => {
+    expect(nudgeCanvasLayout(LAYOUT, { dx: 1, dy: 0 }, 8)).toMatchObject({
+      x: 108, y: 200, width: 240, height: 180,
+    });
+    expect(nudgeCanvasLayout(LAYOUT, { dx: 0, dy: -1 }, 32)).toMatchObject({ x: 100, y: 168 });
+  });
+
+  it("resizes a node without moving it, and never below the minimum", () => {
+    expect(resizeCanvasLayoutBy(LAYOUT, { dx: 1, dy: 1 }, 8)).toMatchObject({
+      x: 100, y: 200, width: 248, height: 188,
+    });
+    expect(resizeCanvasLayoutBy(LAYOUT, { dx: -1, dy: -1 }, 10_000)).toMatchObject({
+      width: CANVAS_MIN_NODE_SIZE, height: CANVAS_MIN_NODE_SIZE,
+    });
+  });
+});
+
+describe("canvas layout normalisation", () => {
+  it("keeps a layout the runtime will accept", () => {
+    expect(normalizeCanvasLayout(LAYOUT)).toEqual(LAYOUT);
+  });
+
+  it("raises a non-positive width or height to the minimum", () => {
+    expect(normalizeCanvasLayout({ ...LAYOUT, width: 0, height: -40 })).toMatchObject({
+      width: CANVAS_MIN_NODE_SIZE, height: CANVAS_MIN_NODE_SIZE,
+    });
+  });
+
+  it("truncates a fractional zIndex to the safe integer the runtime requires", () => {
+    expect(normalizeCanvasLayout({ ...LAYOUT, zIndex: 2.7 }).zIndex).toBe(2);
+    expect(normalizeCanvasLayout({ ...LAYOUT, zIndex: -3 }).zIndex).toBe(0);
+    expect(normalizeCanvasLayout({ ...LAYOUT, zIndex: Number.NaN }).zIndex).toBe(0);
+  });
+
+  it("rounds coordinates and neutralises a value that is not a number", () => {
+    expect(normalizeCanvasLayout({ ...LAYOUT, x: 10.6, y: -0.2 })).toMatchObject({ x: 11, y: -0 });
+    expect(normalizeCanvasLayout({ ...LAYOUT, x: Number.NaN, y: Number.POSITIVE_INFINITY }))
+      .toMatchObject({ x: 0, y: 0 });
+  });
+
+  it("knows when a drag actually changed the layout", () => {
+    expect(canvasLayoutsEqual(LAYOUT, { ...LAYOUT })).toBe(true);
+    expect(canvasLayoutsEqual(LAYOUT, { ...LAYOUT, x: 101 })).toBe(false);
+    expect(canvasLayoutsEqual(LAYOUT, { ...LAYOUT, zIndex: 4 })).toBe(false);
+    expect(canvasLayoutsEqual(undefined, undefined)).toBe(true);
+    expect(canvasLayoutsEqual(LAYOUT, undefined)).toBe(false);
+  });
+});
+
+describe("canvas drag preview", () => {
+  it("replaces only the dragged node's layout", () => {
+    const nodes = [node("a"), node("b")];
+    const previewed = applyCanvasLayoutPreview(nodes, { nodeId: "b", layout: { ...LAYOUT, x: 5 } });
+    expect(previewed[0]).toBe(nodes[0]);
+    expect(previewed[1]?.layout).toMatchObject({ x: 5 });
+  });
+
+  it("is the confirmed document itself when there is no preview, so a refused operation drops it", () => {
+    const nodes = [node("a")];
+    expect(applyCanvasLayoutPreview(nodes, undefined)).toBe(nodes);
+  });
+
+  it("leaves the document alone for a node id that is not on the canvas", () => {
+    const nodes = [node("a")];
+    expect(applyCanvasLayoutPreview(nodes, { nodeId: "ghost", layout: LAYOUT })).toEqual(nodes);
+  });
+});
+
+describe("canvas operation sent to applyCanvas", () => {
+  it("is the runtime's CanvasOperationV1 for a layout change", () => {
+    const operation = buildCanvasOperation("op-1", [buildCanvasUpdateLayoutMutation("node-1", LAYOUT)]);
+    expect(operation).toEqual({
+      schemaVersion: 1,
+      operationId: "op-1",
+      mutations: [{ kind: "update_layout", nodeId: "node-1", layout: LAYOUT }],
+    });
+  });
+
+  it("carries exactly one file identity on add_file, which the runtime requires", () => {
+    const byPath = buildCanvasAddFileMutation("node-2", LAYOUT, { relativePath: "docs/a.png" });
+    expect(byPath).toEqual({
+      kind: "add_file",
+      nodeId: "node-2",
+      layout: LAYOUT,
+      relativePath: "docs/a.png",
+    });
+    expect("assetId" in byPath).toBe(false);
+
+    const byAsset = buildCanvasAddFileMutation("node-2", LAYOUT, { assetId: "asset_1" });
+    expect(byAsset).toEqual({ kind: "add_file", nodeId: "node-2", layout: LAYOUT, assetId: "asset_1" });
+    expect("relativePath" in byAsset).toBe(false);
+  });
+
+  it("names the node for a removal", () => {
+    expect(buildCanvasRemoveNodeMutation("node-3")).toEqual({ kind: "remove_node", nodeId: "node-3" });
+  });
+
+  it("normalises the layout it sends rather than trusting the drag", () => {
+    const mutation = buildCanvasUpdateLayoutMutation("node-1", { ...LAYOUT, width: 0, zIndex: 1.9 });
+    expect(mutation).toMatchObject({
+      kind: "update_layout",
+      layout: { width: CANVAS_MIN_NODE_SIZE, zIndex: 1 },
+    });
+  });
+
+  it("refuses to build what the runtime would refuse, instead of sending it", () => {
+    expect(() => buildCanvasOperation("   ", [buildCanvasRemoveNodeMutation("node-1")]))
+      .toThrow(/operationId/);
+    expect(() => buildCanvasOperation("op-1", [])).toThrow(/at least one mutation/);
+  });
+
+  it("survives the JSON wire the transport sends it over", () => {
+    const operation = buildCanvasOperation("op-1", [
+      buildCanvasAddFileMutation("node-1", LAYOUT, { relativePath: "docs/a.png" }),
+      buildCanvasUpdateLayoutMutation("node-2", LAYOUT),
+      buildCanvasRemoveNodeMutation("node-3"),
+    ]);
+    expect(JSON.parse(JSON.stringify(operation))).toEqual(operation);
+    expect(operation.mutations).toHaveLength(3);
+  });
+
+  it("mints a fresh operation id per call, because the runtime rejects a reuse", () => {
+    const ids = new Set([createCanvasOperationId(), createCanvasOperationId(), createCanvasOperationId()]);
+    expect(ids.size).toBe(3);
+    for (const id of ids) expect(id.trim().length).toBeGreaterThan(0);
+  });
+
+  it("mints a node id that cannot collide with an existing node", () => {
+    expect(createCanvasNodeId()).not.toBe(createCanvasNodeId());
+  });
+});
+
+describe("canvas document parsing", () => {
+  it("reads the node layout and the file name the panel displays", () => {
+    const nodes = parseCanvasNodes(document([{
+      id: "node-1",
+      type: "file_ref",
+      file: { relativePath: "docs/a.png", fileName: "a.png" },
+      layout: { x: 10, y: 20, width: 200, height: 150, zIndex: 2 },
+      annotations: [],
+    }]));
+    expect(nodes).toEqual([
+      { id: "node-1", label: "a.png", layout: { x: 10, y: 20, width: 200, height: 150, zIndex: 2 } },
+    ]);
+  });
+
+  it("falls back through relative path to the node id for the label", () => {
+    const nodes = parseCanvasNodes(document([
+      { id: "a", file: { relativePath: "docs/a.png" }, layout: LAYOUT },
+      { id: "b", file: {}, layout: LAYOUT },
+    ]));
+    expect(nodes.map((entry) => entry.label)).toEqual(["docs/a.png", "b"]);
+  });
+
+  it("drops a node the panel cannot place instead of breaking the render", () => {
+    const nodes = parseCanvasNodes(document([
+      { file: { fileName: "a.png" }, layout: LAYOUT },
+      { id: "no-layout", file: { fileName: "b.png" } },
+      { id: "bad-layout", layout: { x: "0", y: 0, width: 10, height: 10 } },
+      { id: "nan-layout", layout: { x: Number.NaN, y: 0, width: 10, height: 10 } },
+      { id: "good", layout: LAYOUT },
+    ]));
+    expect(nodes.map((entry) => entry.id)).toEqual(["good"]);
+  });
+
+  it("reads a document with no nodes, and no document at all, as an empty canvas", () => {
+    expect(parseCanvasNodes(document([]))).toEqual([]);
+    expect(parseCanvasNodes(undefined)).toEqual([]);
+    expect(parseCanvasNodes({ ...document([]), nodes: "not-an-array" as never })).toEqual([]);
+  });
+});
+
+describe("canvas node placement for a new node", () => {
+  it("places the first node and stacks later ones on top of the highest", () => {
+    const empty = nextCanvasNodeLayout([]);
+    expect(empty).toMatchObject({ zIndex: 1 });
+    expect(empty.width).toBeGreaterThan(0);
+    expect(empty.height).toBeGreaterThan(0);
+
+    const existing = [node("a", { zIndex: 4 }), node("b", { zIndex: 9 })];
+    expect(nextCanvasZIndex(existing)).toBe(10);
+    expect(nextCanvasNodeLayout(existing).zIndex).toBe(10);
+  });
+
+  it("cascades instead of stacking every add on one spot", () => {
+    const nodes: CanvasNodeView[] = [];
+    for (let index = 0; index < 6; index += 1) {
+      const placed = nextCanvasNodeLayout(nodes);
+      nodes.push(node(`n${index}`, placed));
+    }
+    const positions = nodes.map((entry) => `${entry.layout.x}:${entry.layout.y}`);
+    expect(new Set(positions).size).toBe(6);
+  });
+});
+
+describe("canvas failure reporting", () => {
+  it("surfaces a server refusal instead of showing an optimistic layout", () => {
+    expect(describeCanvasError(new Error("Canvas node not found: node-9")))
+      .toBe("Canvas node not found: node-9");
+    expect(describeCanvasError("Canvas operation is invalid")).toBe("Canvas operation is invalid");
+    expect(describeCanvasError(undefined)).toMatch(/没有保存/);
+    expect(describeCanvasError(new Error("   "))).toMatch(/没有保存/);
+  });
+});
+
+describe("canvas markup", () => {
+  // No effect runs, so this is the panel before its first read resolves: the
+  // empty state the brief says must survive, plus the zoom readout.
+  it("keeps the empty state, the class names and the zoom readout", () => {
+    const markup = renderToStaticMarkup(createElement(WorkspaceCanvas, { sessionId: "session-1" }));
+    expect(markup).toContain('class="webui-canvas-content"');
+    expect(markup).toContain("把文件放到画布上");
+    expect(markup).toContain("添加图片或其他工作区文件，然后自由排列和调整大小。");
+    expect(markup).toContain('class="webui-canvas-zoom"');
+    expect(markup).toContain("100%");
+  });
+
+  it("offers the add path the empty state promises, and says so when it is read-only", () => {
+    const markup = renderToStaticMarkup(createElement(WorkspaceCanvas, { sessionId: "session-1" }));
+    expect(markup).toContain("添加到画布");
+    expect(markup).toContain("工作区相对路径");
+    expect(markup).toContain("画布当前为只读");
+    // Read-only means the controls are disabled, not merely hidden.
+    expect(markup).toContain("disabled");
+  });
+});

From 397e1e62293d422540134af628047b6fefc0e078 Mon Sep 17 00:00:00 2001
From: probe <probe@local>
Date: Sun, 4 Oct 2026 09:02:01 +0800
Subject: [PATCH 16/21] feat(webui): wire the canvas write-back path end to end
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The canvas component could build and send operations, but the panel never
handed it `applyCanvas`, so the surface was read-only — and the component
said so rather than pretending otherwise, which is how this surfaced.

`CanvasOperation` and its mutation types move down to `contracts.ts`, because
`WebuiTransport` has to name the operation type and a transport method cannot
take a type from a module above it in the dependency chain. The component
re-exports them, so its tests and callers keep one import site and there is
still exactly one definition.

`applyCanvas`'s return type narrows from `unknown` to the
`{ operationId, document }` the harness port actually returns. A canvas that
adopts the returned document cannot pretend a rejected operation succeeded
when the type says nothing about what came back.

The suite registry gains the three tests that exist on disk. It is validated
in both directions, so a file is only added once it is really there.
---
 .../src/client/components/WorkspaceCanvas.tsx | 27 +++----------
 .../src/client/components/WorkspacePanels.tsx |  8 +++-
 packages/webui/src/client/contracts.ts        | 40 ++++++++++++++++++-
 test/vitest-suites.json                       |  6 ++-
 4 files changed, 55 insertions(+), 26 deletions(-)

diff --git a/packages/webui/src/client/components/WorkspaceCanvas.tsx b/packages/webui/src/client/components/WorkspaceCanvas.tsx
index 23ab19bd9..b2bddd4ff 100644
--- a/packages/webui/src/client/components/WorkspaceCanvas.tsx
+++ b/packages/webui/src/client/components/WorkspaceCanvas.tsx
@@ -70,13 +70,11 @@ const CANVAS_ADD_WIDTH = 240;
 const CANVAS_ADD_HEIGHT = 180;
 const CANVAS_PAN_KEY_SCALE = 4;
 
-export interface CanvasNodeLayout {
-  readonly x: number;
-  readonly y: number;
-  readonly width: number;
-  readonly height: number;
-  readonly zIndex: number;
-}
+// Re-exported so the canvas keeps a single import site for everything a
+// caller or a test needs, while the definitions themselves live in
+// `contracts.ts` — the only layer `WebuiTransport` is allowed to depend on.
+export type { CanvasMutation, CanvasNodeLayout, CanvasOperation } from "../contracts.js";
+import type { CanvasMutation, CanvasNodeLayout, CanvasOperation } from "../contracts.js";
 
 export interface CanvasNodeView {
   readonly id: string;
@@ -92,21 +90,8 @@ export interface CanvasPan {
 /**
  * A node drag, a node resize and a canvas pan all start from one pointer and
  * one gesture, so the marker on the pointerdown target picks the winner once.
- * Mirrors the runtime's `CanvasMutationV1` for the three mutations this panel
- * can produce; `add_file` keeps exactly one file identity, as the runtime
- * requires.
+ * `CanvasMutation` itself is declared in `contracts.ts` and re-exported above.
  */
-export type CanvasMutation =
-  | { readonly kind: "add_file"; readonly nodeId: string; readonly layout: CanvasNodeLayout; readonly relativePath: string }
-  | { readonly kind: "add_file"; readonly nodeId: string; readonly layout: CanvasNodeLayout; readonly assetId: string }
-  | { readonly kind: "update_layout"; readonly nodeId: string; readonly layout: CanvasNodeLayout }
-  | { readonly kind: "remove_node"; readonly nodeId: string };
-
-export interface CanvasOperation {
-  readonly schemaVersion: 1;
-  readonly operationId: string;
-  readonly mutations: readonly CanvasMutation[];
-}
 
 export type CanvasFileIdentity =
   | { readonly relativePath: string }
diff --git a/packages/webui/src/client/components/WorkspacePanels.tsx b/packages/webui/src/client/components/WorkspacePanels.tsx
index cb5ad9678..ee3d42064 100644
--- a/packages/webui/src/client/components/WorkspacePanels.tsx
+++ b/packages/webui/src/client/components/WorkspacePanels.tsx
@@ -43,6 +43,7 @@ import { WebuiIconAgent, WebuiIconCheck, WebuiIconChevronDown, WebuiIconClose, W
 import { FileTree, filterWorkspaceFiles, findWorkspaceFile, getWorkspaceFileParentPaths, mergeWorkspaceFileChildren } from "./WorkspaceFileTree.js";
 import { WorkspaceMediaPreview, isMediaContent } from "./WorkspaceMediaPreview.js";
 import { WorkspaceCanvas } from "./WorkspaceCanvas.js";
+import type { CanvasOperation } from "./WorkspaceCanvas.js";
 import { WorkspaceArchiveView } from "./WorkspaceArchiveView.js";
 import { WorkspaceHtmlPreview } from "./WorkspaceHtmlPreview.js";
 
@@ -402,7 +403,10 @@ export function WebuiWorkspacePanel({ state, dispatch, sessionId, workspaceDir,
   readonly readWorkspaceArchive?: (request: { readonly workspaceDir: string; readonly path: string; readonly prefix?: string }) => Promise<WebuiWorkspaceArchiveListing>;
   readonly extractWorkspaceArchive?: (request: { readonly workspaceDir: string; readonly path: string; readonly destination: string; readonly prefix?: string }) => Promise<WebuiWorkspaceArchiveExtractResult>;
   readonly readCanvas?: (request: { sessionId: string }) => Promise<WebuiCanvasDocument>;
-  readonly applyCanvas?: (request: { sessionId: string; operation: Record<string, unknown> }) => Promise<unknown>;
+  // The canvas builds its own operation objects, so the panel adopts the
+  // component's operation type rather than restating it: one definition, and
+  // a drift between the two would only surface as a call the runtime rejects.
+  readonly applyCanvas?: (request: { sessionId: string; operation: CanvasOperation }) => Promise<{ readonly operationId: string; readonly document: WebuiCanvasDocument }>;
   readonly createTerminal?: (request: { workspaceDir: string }) => Promise<{ terminalId: string; status: string }>;
   readonly listTerminals?: () => Promise<readonly Record<string, unknown>[]>;
   readonly writeTerminal?: (request: { terminalId: string; data: string }) => Promise<unknown>;
@@ -810,7 +814,7 @@ export function WebuiWorkspacePanel({ state, dispatch, sessionId, workspaceDir,
       <div className="webui-turn-review-summary"><span>本轮改动</span><span className="webui-diff-header-stats"><span className="webui-diff-add">+{turnReviewFiles.reduce((sum, file) => sum + file.additions, 0)}</span>{turnReviewFiles.some((file) => file.deletions > 0) ? <span className="webui-diff-del">-{turnReviewFiles.reduce((sum, file) => sum + file.deletions, 0)}</span> : null}</span></div>
       {turnReviewFiles.length ? <div className="webui-turn-review-files">{turnReviewFiles.map((file) => <WebuiDiffFileSection key={file.file} file={file} selected={selectedReviewPath === file.file} />)}</div> : <p className="webui-turn-review-empty">本轮没有可审查的文件差异。</p>}
     </div> : null}
-    {tab === "canvas" ? <WorkspaceCanvas sessionId={activeSessionId} readCanvas={readCanvas} /> : null}
+    {tab === "canvas" ? <WorkspaceCanvas sessionId={activeSessionId} readCanvas={readCanvas} applyCanvas={applyCanvas} /> : null}
     {tab === "terminal" ? <div className="webui-terminal-empty">{terminals.length === 0 ? <><strong>{DESKTOP_COPY.terminalEmptyTitle}</strong><p>{DESKTOP_COPY.terminalEmptyDescription}</p></> : <><div className="webui-terminal-tabs">{terminals.map((terminal, index) => <button type="button" key={String(terminal.terminalId)} className={`file-tab group/tab-close h-8 w-40 min-w-20 ${String(terminal.terminalId) === (activeTerminalId ?? String(terminals[0]?.terminalId)) ? "bg-bg_interaction_tertiary_selected" : ""}`} onClick={() => setActiveTerminalId(String(terminal.terminalId))}><span>#{index + 1}</span>{terminal.status === "exited" ? DESKTOP_COPY.terminalExited : DESKTOP_COPY.terminalLabel}<span className="file-tab-close opacity-0 group-hover/tab-close:opacity-100"><WebuiIconClose className="size-[14px]" /></span></button>)}</div><div ref={terminalHost} className="webui-xterm-host" />{terminalError ? <p role="alert">{terminalError}</p> : null}<div className="webui-terminal-actions"><button type="button" onClick={() => { if (!activeWorkspace || !createTerminal) return; void createTerminal({ workspaceDir: activeWorkspace }).then((created) => { setActiveTerminalId(created.terminalId); return listTerminals?.().then(setTerminals); }).catch((error: unknown) => setTerminalError(error instanceof Error ? error.message : String(error))); }}>{DESKTOP_COPY.newTerminal}</button><button type="button" onClick={() => { const active = terminals.find((candidate) => String(candidate.terminalId) === (activeTerminalId ?? String(terminals[0]?.terminalId))); if (active && disposeTerminal) void disposeTerminal({ terminalId: String(active.terminalId) }).then(() => listTerminals?.().then(setTerminals)); }}>{DESKTOP_COPY.fileClose}</button></div></> }{terminals.length === 0 ? <button type="button" onClick={() => { if (!activeWorkspace || !createTerminal) return; void createTerminal({ workspaceDir: activeWorkspace }).then((created) => { setActiveTerminalId(created.terminalId); return listTerminals?.().then(setTerminals); }).catch((error: unknown) => setTerminalError(error instanceof Error ? error.message : String(error))); }}>{DESKTOP_COPY.newTerminal}</button> : null}</div> : null}
       </div>
       {hasFileWorkspace && fileTreeOpen ? <aside className="webui-workspace-file-tree-panel" aria-label="工作区文件树">
diff --git a/packages/webui/src/client/contracts.ts b/packages/webui/src/client/contracts.ts
index b68f94367..49323830b 100644
--- a/packages/webui/src/client/contracts.ts
+++ b/packages/webui/src/client/contracts.ts
@@ -8,6 +8,42 @@
 // imports React or DOM globals — the type layer is the lowest in the
 // dependency direction `main → components → projection → contracts`.
 
+/**
+ * The canvas wire contract, declared here rather than in the canvas component
+ * because `WebuiTransport` has to name it: a transport method cannot take a
+ * type defined in a module that sits above it in the dependency chain.
+ *
+ * Mirrors the runtime's `CanvasOperationV1` in
+ * `packages/local-runtime-v2/src/service/canvas/contracts.ts`. The runtime is
+ * the authority — it rejects a reused `operationId` with a different payload,
+ * an empty `mutations` array, an `add_file` carrying both or neither file
+ * identity, a non-positive width or height, and a non-integer `zIndex`.
+ */
+export interface CanvasNodeLayout {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly zIndex: number;
+}
+
+/**
+ * A node drag, a node resize and a canvas pan all start from one pointer and
+ * one gesture, so the marker on the pointerdown target picks the winner once.
+ * `add_file` carries exactly one file identity, as the runtime requires.
+ */
+export type CanvasMutation =
+  | { readonly kind: "add_file"; readonly nodeId: string; readonly layout: CanvasNodeLayout; readonly relativePath: string }
+  | { readonly kind: "add_file"; readonly nodeId: string; readonly layout: CanvasNodeLayout; readonly assetId: string }
+  | { readonly kind: "update_layout"; readonly nodeId: string; readonly layout: CanvasNodeLayout }
+  | { readonly kind: "remove_node"; readonly nodeId: string };
+
+export interface CanvasOperation {
+  readonly schemaVersion: 1;
+  readonly operationId: string;
+  readonly mutations: readonly CanvasMutation[];
+}
+
 import type {
   WebuiCanvasDocument,
   WebuiClaimSigninView,
@@ -474,8 +510,8 @@ export interface WebuiTransport {
   }) => Promise<WebuiCanvasDocument>;
   readonly applyCanvas?: (request: {
     readonly sessionId: string;
-    readonly operation: Record<string, unknown>;
-  }) => Promise<unknown>;
+    readonly operation: CanvasOperation;
+  }) => Promise<{ readonly operationId: string; readonly document: WebuiCanvasDocument }>;
   /**
    * The streamable URL of one workspace file, credential included.
    *
diff --git a/test/vitest-suites.json b/test/vitest-suites.json
index db836b345..add100ec5 100644
--- a/test/vitest-suites.json
+++ b/test/vitest-suites.json
@@ -269,7 +269,11 @@
       "packages/webui/test/unit/transcript-file-anchor-anchors.test.tsx",
       "packages/webui/test/unit/transcript-interrupt-frames.test.ts",
       "packages/webui/test/unit/transcript-retry-affordance.test.tsx",
-      "packages/webui/test/unit/transcript-retry-resend-wiring.test.tsx"
+      "packages/webui/test/unit/transcript-retry-resend-wiring.test.tsx",
+      "packages/webui/test/unit/webui-workspace-media-preview.test.tsx",
+      "packages/webui/test/unit/webui-workspace-file-tree.test.tsx",
+      "packages/webui/test/unit/webui-workspace-html-preview.test.tsx",
+      "packages/webui/test/unit/webui-workspace-canvas.test.tsx"
     ]
   }
 }

From 1954dbee5436e1c7f78379248de5846d23d973c0 Mon Sep 17 00:00:00 2001
From: probe <probe@local>
Date: Sun, 4 Oct 2026 09:06:03 +0800
Subject: [PATCH 17/21] feat(webui): read and extract workspace archives
 without a new dependency

`@mavis/webui` is published, so `jszip` and `tar` cannot be added as
dependencies without changing what every consumer installs. The reader is
therefore built on Node built-ins:

  * zip: the end-of-central-directory record is found by scanning backwards,
    because it is followed by a comment of up to 64 KiB. A candidate is only
    accepted when its own comment length lands exactly on the end of file, so
    the same four signature bytes inside compressed data are not read as the
    record -- and a truncated archive becomes a clear message instead of a wild
    offset. Sizes come from the central directory, never the local header,
    because a streamed entry leaves the local size fields zero. Data is method 0
    as stored, method 8 through `inflateRawSync`.
  * tar: 512-byte blocks, header checksum verified before any field is trusted,
    the ustar prefix field joined onto the name so long paths are not renamed,
    and pax `path=` / GNU `L` long-name records honoured. `.tar.gz`/`.tgz` go
    through `gunzipSync` first.

The hardening is ported from the runtime's two extractors
(`deployed-website-source.ts` and `skills/remote/archive.ts`), which cannot be
imported across the package boundary:

  * path traversal is refused on the name (NUL, absolute on any platform, `..`,
    and Windows drive letters -- the drive-relative `C:x` that `win32.isAbsolute`
    accepts) and again after joining, with a separator-terminated prefix check
    rather than a string prefix that would accept `/tmp/evil` for `/tmp/ev`.
  * a `.` segment is dropped rather than refused: `tar cf x.tar .` puts `./` on
    every member, and a `.` cannot escape anything. A name that normalises away
    to nothing is a root marker, not a refusal.
  * symlinks are refused, from the zip external attributes (unix mode, host
    system 3) and from the tar typeflag -- along with hardlinks, devices and
    FIFOs, which are the same class of problem.
  * ceilings: 200 MiB compressed, 512 MiB total expansion (checked against the
    declared sizes as a pre-flight, against the bytes actually produced, and
    *during* inflation via `maxOutputLength`), a 2000:1 per-entry expansion
    ratio, 10,000 entries and 500 rows per level. The entry ceiling is why a zip
    with a million tiny entries cannot exhaust memory while being listed, and the
    row ceiling is what `truncated` reports.
  * the destination is untrusted too: resolved, contained, created, then
    re-checked through `realpath` so a symlinked ancestor cannot redirect the
    writes. Every parent is re-resolved per entry for the same reason, and files
    are written `wx` -- an archive the user did not write must not be able to
    overwrite a file already in their workspace.

Formats: `.zip`, `.tar`, `.tgz`, `.tar.gz` are read. `.gz`, `.bz2`, `.xz`, `.7z`
and `.rar` are recognised and refused by name, matching the client's
`WORKSPACE_ARCHIVE_EXTENSIONS` so a user gets "unsupported format" rather than
"not an archive". Zip64 is refused by name for the same reason.

`readWorkspaceArchive` and `extractWorkspaceArchive` now fall back to this
module when the runtime does not implement them, instead of throwing
"capability not connected yet"; a runtime implementation still wins.
---
 packages/webui/src/server/host.ts             |  31 +-
 .../webui/src/server/workspace-archive.ts     | 968 ++++++++++++++++++
 2 files changed, 990 insertions(+), 9 deletions(-)
 create mode 100644 packages/webui/src/server/workspace-archive.ts

diff --git a/packages/webui/src/server/host.ts b/packages/webui/src/server/host.ts
index d546e63c0..17d12f336 100644
--- a/packages/webui/src/server/host.ts
+++ b/packages/webui/src/server/host.ts
@@ -15,6 +15,10 @@ import { posix as pathPosix } from "node:path";
 import { stat } from "node:fs/promises";
 import path from "node:path";
 import { WEBUI_PROTOCOL_VERSION } from "./envelope.js";
+import {
+  extractWorkspaceArchiveDirectory,
+  readWorkspaceArchiveListing,
+} from "./workspace-archive.js";
 import type {
   WebuiHarnessPort,
   WebuiSessionListRequest,
@@ -169,6 +173,13 @@ export interface WebuiRuntimeCliService {
   listWorkspaceFileTree?(request: { readonly workspaceDir: string; readonly path?: string }): Promise<readonly WebuiWorkspaceFile[]>;
   readWorkspaceFile?(request: { readonly workspaceDir: string; readonly path: string }): Promise<WebuiWorkspaceFileContent>;
   searchWorkspaceFiles?(input: { readonly workspaceDir: string; readonly query: string; readonly limit: number }): Promise<readonly string[]>;
+  /**
+   * Archive listing and extraction are served by this package
+   * (`./workspace-archive.ts`, Node built-ins only) rather than by the runtime,
+   * so these two stay optional: a host that has a richer implementation of its
+   * own still wins, and a host that has none gets the WebUI's reader instead of
+   * an error the panel can only show.
+   */
   readWorkspaceArchive?(request: { readonly workspaceDir: string; readonly path: string; readonly prefix?: string }): Promise<WebuiWorkspaceArchiveListing>;
   extractWorkspaceArchive?(request: { readonly workspaceDir: string; readonly path: string; readonly destination: string; readonly prefix?: string }): Promise<WebuiWorkspaceArchiveExtractResult>;
   getWorkspaceGitEnvironment?(workspaceDir: string): Promise<{ readonly metadata: Record<string, unknown>; readonly changes: Record<string, unknown> }>;
@@ -443,20 +454,22 @@ export function createHarnessPortFromHost(
         }
       }));
     },
-    // Checked rather than asserted: the siblings above use `!` because their
-    // runtime capability has shipped, but archive reading and extraction are
-    // landing with the workspace-panel work, and a bare `!` here would turn a
-    // missing capability into `undefined is not a function` at call time
-    // instead of a message the panel can show.
+    // Both operations are served by this package now, so the optional runtime
+    // hook is a preference rather than a requirement: a host that implements
+    // one keeps it, and a host that implements neither lands on
+    // `./workspace-archive.ts` instead of the "capability not connected yet"
+    // error this pair used to throw. The built-in reader owns the hardening
+    // (path validation, entry ceiling, expansion ratio), which is the reason it
+    // is not left to a runtime that may not have shipped one.
     async readWorkspaceArchive(request) {
       const cliService = requireCliService(host);
-      if (!cliService.readWorkspaceArchive) throw new Error("压缩包浏览能力尚未接入。");
-      return cliService.readWorkspaceArchive(request);
+      if (cliService.readWorkspaceArchive) return cliService.readWorkspaceArchive(request);
+      return readWorkspaceArchiveListing(request);
     },
     async extractWorkspaceArchive(request) {
       const cliService = requireCliService(host);
-      if (!cliService.extractWorkspaceArchive) throw new Error("压缩包解压能力尚未接入。");
-      return cliService.extractWorkspaceArchive(request);
+      if (cliService.extractWorkspaceArchive) return cliService.extractWorkspaceArchive(request);
+      return extractWorkspaceArchiveDirectory(request);
     },
     async readWorkspaceFile(request) {
       const cliService = requireCliService(host);
diff --git a/packages/webui/src/server/workspace-archive.ts b/packages/webui/src/server/workspace-archive.ts
new file mode 100644
index 000000000..3727174b7
--- /dev/null
+++ b/packages/webui/src/server/workspace-archive.ts
@@ -0,0 +1,968 @@
+// Reads and extracts the workspace archives the panel previews.
+//
+// Two container formats, parsed here with Node built-ins only: `zip` (scan back
+// for the End Of Central Directory record, walk the central directory it points
+// at, inflate the local file data with `inflateRawSync`) and `tar` (512-byte
+// blocks, `gunzipSync` first for `.tar.gz` / `.tgz`). `@mavis/webui` is a
+// published package, so neither `jszip` nor `tar` may be added as a dependency
+// without changing what every consumer installs; the parsers below are the
+// smallest thing that reads those two formats honestly.
+//
+// The hardening is ported from the runtime's two battle-tested extractors:
+//   * `packages/local-runtime/src/website-management/deployed-website-source.ts`
+//     — `extractArchive`, `assertSafeZipEntry`, `isSymbolicLink`,
+//     `resolveEntryPath`, `readUncompressedSize`.
+//   * `packages/local-runtime/src/skills/remote/archive.ts` —
+//     `loadZipSkillFiles`, `shouldStripArchiveRoot`.
+// Neither can be imported across the package boundary (webui may not depend on
+// local-runtime, and the runtime already depends on webui), so the checks are
+// re-implemented against the raw bytes and the two-phase shape is kept: every
+// entry is validated and the declared sizes summed *before* a single byte is
+// written, so a hostile archive leaves nothing behind.
+//
+// `shouldStripArchiveRoot` is the one deliberate non-port — see the comment on
+// `listOneLevel`.
+
+import { lstat, mkdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { gunzipSync, inflateRawSync } from "node:zlib";
+import type {
+  WebuiArchiveEntry,
+  WebuiWorkspaceArchiveExtractResult,
+  WebuiWorkspaceArchiveListing,
+} from "./port.js";
+
+// ---------------------------------------------------------------------------
+// Ceilings
+// ---------------------------------------------------------------------------
+
+/**
+ * Largest compressed archive this module will read into memory.
+ *
+ * 200 MiB, the same figure `deployed-website-source.ts` uses for a *downloaded*
+ * archive. The panel is previewing a file the user already has in their own
+ * workspace tree, so nothing is arriving over a network, and a cap far below
+ * this would refuse legitimate build outputs (`target/`, `.next/`) that are
+ * routinely zipped up and opened for inspection.
+ */
+const WORKSPACE_ARCHIVE_MAX_ARCHIVE_BYTES = 200 * 1024 * 1024;
+
+/**
+ * Largest total expansion, enforced against the declared sizes (before
+ * inflating anything), against the bytes each entry actually produced (after),
+ * and *during* inflation via zlib's `maxOutputLength`.
+ *
+ * 512 MiB, matching `DEPLOYED_WEBSITE_SOURCE_MAX_UNCOMPRESSED_BYTES`. The
+ * declared pass is the cheap pre-flight; the runtime pass is the one that
+ * matters, because a header can lie. Enforcing it during inflation rather than
+ * after is what stops a lying header from getting to allocate the memory it
+ * asked for in the first place.
+ */
+const WORKSPACE_ARCHIVE_MAX_UNCOMPRESSED_BYTES = 512 * 1024 * 1024;
+
+/**
+ * Per-entry expansion ceiling: `uncompressed / compressed`.
+ *
+ * DEFLATE's format maximum is about 1032:1 (a 258-byte match encoded in a
+ * fraction of a token), so 2000:1 admits everything a conforming compressor can
+ * emit — including a maximally compressible file of zeroes — while still
+ * refusing the classic "a 1 KB archive expands to gigabytes" shape entry by
+ * entry. The absolute total-bytes cap is the real memory guard; this one exists
+ * so a single member cannot quietly consume the whole budget.
+ */
+const WORKSPACE_ARCHIVE_MAX_EXPANSION_RATIO = 2000;
+
+/**
+ * Most entries the reader will materialise.
+ *
+ * 10,000, one notch above the sibling extractor's 5,000. The difference is the
+ * consumer: a headless install has to *write* every entry, while this reader
+ * only ever renders one level, so the ceiling exists to bound parse memory
+ * rather than disk. "A zip with a million tiny entries" is the shape that would
+ * exhaust memory while building a listing, and 10,000 stays two orders of
+ * magnitude below it while remaining past any real project tree.
+ */
+const WORKSPACE_ARCHIVE_MAX_ENTRIES = 10_000;
+
+/**
+ * Most rows one listing level reports before it declares itself truncated.
+ *
+ * 500, the same page size the workspace directory picker uses
+ * (`WORKSPACE_DIRECTORY_LIMIT` in `src/server/operation/workspace.ts`): enough
+ * for a directory to stay browsable, few enough that the response does not.
+ * The entry ceiling above sits well past this, so `totalEntries` can honestly
+ * report how much of the archive the page left out.
+ */
+const WORKSPACE_ARCHIVE_MAX_LISTED_ENTRIES = 500;
+
+// ---------------------------------------------------------------------------
+// Format set
+// ---------------------------------------------------------------------------
+
+/**
+ * The extensions the client routes to the archive preview, mirrored from
+ * `WORKSPACE_ARCHIVE_EXTENSIONS` in `src/client/components/WorkspacePanels.tsx`.
+ *
+ * Mirrored rather than imported because that module is browser-side and this is
+ * the server, but the two lists must not drift: a format this module cannot
+ * read still has to be a *recognised* archive here, so the user gets "unsupported
+ * format" rather than "this is not an archive". Which of them can actually be
+ * opened is decided by `archiveFormatFor`.
+ */
+const WORKSPACE_ARCHIVE_EXTENSIONS = [
+  ".zip",
+  ".tar",
+  ".tgz",
+  ".gz",
+  ".bz2",
+  ".xz",
+  ".7z",
+  ".rar",
+] as const;
+
+type ArchiveFormat = "zip" | "tar" | "tar.gz";
+
+/**
+ * Which of the client's extensions this reader can open, and by what name it
+ * refuses the rest.
+ *
+ * `.gz` is in the client list as a suffix match, so `x.tar.gz` routes here too;
+ * a bare `.gz` is one compressed stream with no directory structure and no way
+ * to tell a gzipped tar from a gzipped text file, so it is refused rather than
+ * guessed at. `.bz2` and `.xz` have no decompressor in `node:zlib`. `.7z` and
+ * `.rar` are proprietary container formats this module does not parse.
+ */
+function archiveFormatFor(archivePath: string): { readonly format: ArchiveFormat } | { readonly error: string } {
+  const lower = archivePath.toLowerCase();
+  if (!WORKSPACE_ARCHIVE_EXTENSIONS.some((extension) => lower.endsWith(extension))) {
+    return { error: "只有 .zip、.tar、.tgz 和 .tar.gz 可以在工作区面板中打开。" };
+  }
+  if (lower.endsWith(".zip")) return { format: "zip" };
+  if (lower.endsWith(".tgz") || lower.endsWith(".tar.gz")) return { format: "tar.gz" };
+  if (lower.endsWith(".tar")) return { format: "tar" };
+  if (lower.endsWith(".gz")) return { error: ".gz 是单个压缩流、没有目录结构；请改用 .tar.gz 或 .tgz。" };
+  if (lower.endsWith(".bz2") || lower.endsWith(".xz")) {
+    return { error: "Node 内置压缩库不支持 bzip2 或 xz；请改用 .zip、.tar 或 .tar.gz。" };
+  }
+  return { error: "不支持的压缩包格式（.7z / .rar）；请改用 .zip、.tar 或 .tar.gz。" };
+}
+
+// ---------------------------------------------------------------------------
+// Entry model
+// ---------------------------------------------------------------------------
+
+type ArchiveEntry = {
+  /** The name exactly as the container stored it, before normalisation. */
+  readonly rawName: string;
+  /**
+   * Archive-internal POSIX path, absent when `unsafeReason` is set. An entry
+   * without a path is never named to the client and never written.
+   */
+  readonly path?: string;
+  readonly isDirectory: boolean;
+  /** Size the container claims for this entry; the header may be lying. */
+  readonly declaredSize: number;
+  /** Compressed size, the denominator of the expansion-ratio ceiling. */
+  readonly compressedSize: number;
+  /** Why this entry is refused, in the panel's own words. */
+  readonly unsafeReason?: string;
+  /** Materialises the entry's bytes, charged against `budget`. */
+  read(budget: ExpansionBudget): Buffer;
+};
+
+type ArchiveContents = {
+  readonly entries: readonly ArchiveEntry[];
+  /** Entries the archive holds, which may exceed `entries.length`. */
+  readonly totalEntries: number;
+  /** True when the entry ceiling cut the container short. */
+  readonly truncated: boolean;
+};
+
+/**
+ * Byte budget shared by every entry in one operation, so neither the
+ * per-entry ratio ceiling nor the total cap can be sidestepped by splitting a
+ * bomb across many entries.
+ */
+type ExpansionBudget = { remaining: number };
+
+// ---------------------------------------------------------------------------
+// Public surface
+// ---------------------------------------------------------------------------
+
+/**
+ * One level of an archive, as the panel's preview shows it.
+ *
+ * The read path only ever names entries it is willing to write, which is what
+ * the port's contract asks for ("the view renders only what this call is willing
+ * to name"): an entry whose name is unsafe is dropped and the listing is marked
+ * truncated, rather than displayed now and refused at extraction time.
+ */
+export async function readWorkspaceArchiveListing(request: {
+  readonly workspaceDir: string;
+  readonly path: string;
+  readonly prefix?: string;
+}): Promise<WebuiWorkspaceArchiveListing> {
+  const archivePath = await resolveArchiveFile(request.workspaceDir, request.path);
+  const { format, buffer } = await readArchive(archivePath);
+  const prefix = normalizePrefix(request.prefix);
+  const contents = readContents(buffer, format);
+  const level = listOneLevel(contents, prefix);
+  return {
+    archivePath: normalizeArchiveRelativePath(request.path),
+    entries: level.entries,
+    totalEntries: contents.totalEntries,
+    // Two honest reasons to be truncated, and the view has to say so either way
+    // rather than render a partial list as if it were the whole archive: the
+    // reader stopped at the entry ceiling, or this one level held more rows
+    // than a page carries (or an entry the reader refused to name).
+    truncated: contents.truncated || level.truncated,
+  };
+}
+
+/**
+ * Writes the entries under `prefix` (or the whole archive) into `destination`.
+ *
+ * `destination` is a path *inside* the workspace, chosen by the view: a browser
+ * cannot ask for an arbitrary absolute path, and a free-text destination would
+ * make this a path-traversal endpoint rather than a feature. It is resolved and
+ * validated against the workspace root before anything is created, and every
+ * written path is re-validated against the extraction root after joining, so a
+ * hostile entry name cannot escape either one.
+ *
+ * Two phases, as in the sibling extractor: every name is validated and the
+ * declared sizes summed *before* the destination is created, so an archive with
+ * a hostile name or a lying header leaves nothing at all behind. A failure
+ * discovered per entry — a corrupt stream, an expansion blow-up, a file that
+ * already exists — happens after some directories exist, and the invariant
+ * there is that no *file* is ever half-written: bytes are read in full, capped
+ * and checked before `writeFile` is called.
+ */
+export async function extractWorkspaceArchiveDirectory(request: {
+  readonly workspaceDir: string;
+  readonly path: string;
+  readonly destination: string;
+  readonly prefix?: string;
+}): Promise<WebuiWorkspaceArchiveExtractResult> {
+  const archivePath = await resolveArchiveFile(request.workspaceDir, request.path);
+  const { format, buffer } = await readArchive(archivePath);
+  const prefix = normalizePrefix(request.prefix);
+  const contents = readContents(buffer, format);
+  const selected = selectForExtraction(contents, prefix);
+
+  let declared = 0;
+  for (const entry of selected) {
+    if (entry.unsafeReason) throw new Error(`压缩包中存在不安全的条目：${entry.unsafeReason}`);
+    declared += entry.declaredSize;
+    if (declared > WORKSPACE_ARCHIVE_MAX_UNCOMPRESSED_BYTES) {
+      throw new Error("压缩包声明的展开后体积过大，已拒绝解压。");
+    }
+  }
+
+  const root = await prepareExtractionRoot(request.workspaceDir, request.destination);
+  const budget: ExpansionBudget = { remaining: WORKSPACE_ARCHIVE_MAX_UNCOMPRESSED_BYTES };
+  let writtenFiles = 0;
+  for (const entry of selected) {
+    if (entry.isDirectory) continue;
+    const target = resolveEntryPath(root, entryPathUnderPrefix(entry, prefix));
+    await writeExtractedFile(root, target, entry, budget);
+    writtenFiles += 1;
+  }
+
+  return {
+    archivePath: normalizeArchiveRelativePath(request.path),
+    destination: normalizeArchiveRelativePath(request.destination),
+    writtenFiles,
+    // The port asks for this rather than a refusal: the destination now holds a
+    // partial tree, and the view has to say so instead of implying the archive
+    // was written out in full.
+    ...(contents.truncated ? { truncated: true } : {}),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Workspace path handling
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolves the archive's own path inside the workspace.
+ *
+ * The relative path arrives from the browser, so it gets the same treatment as
+ * an entry name: `resolve` collapses every `..`, and what is left to reject is
+ * an absolute path or a sibling that merely shares a prefix (`/repo-evil`
+ * against root `/repo`) — hence the separator-terminated comparison rather than
+ * a bare `startsWith(root)`.
+ */
+async function resolveArchiveFile(workspaceDir: string, relative: string): Promise<string> {
+  if (!relative.trim()) throw new Error("压缩包路径为空。");
+  const root = await realpath(path.resolve(workspaceDir));
+  const target = resolveInside(root, relative, "压缩包路径");
+  let stats;
+  try {
+    stats = await stat(target);
+  } catch (error) {
+    if (isMissingPath(error)) throw new Error("工作区中找不到这个压缩包。");
+    throw error;
+  }
+  if (!stats.isFile()) throw new Error("压缩包不是一个文件。");
+  // Checked before `readFile`, so an oversized archive is refused rather than
+  // allocated and then refused.
+  if (stats.size > WORKSPACE_ARCHIVE_MAX_ARCHIVE_BYTES) throw new Error("压缩包过大，无法在面板中打开。");
+  return target;
+}
+
+/**
+ * Validates and creates the directory an extraction may write into.
+ *
+ * The destination is untrusted input like everything else here: resolved
+ * against the workspace root, refused if it lands outside, and re-checked
+ * *after* `realpath` so a symlinked ancestor cannot redirect the writes
+ * somewhere else. Only then is anything created — a refused destination must
+ * not leave a directory behind.
+ */
+async function prepareExtractionRoot(workspaceDir: string, destination: string): Promise<string> {
+  if (!destination.trim()) throw new Error("解压目标为空。");
+  const root = await realpath(path.resolve(workspaceDir));
+  const requested = resolveInside(root, destination, "解压目标");
+  await mkdir(requested, { recursive: true });
+  const resolved = await realpath(requested);
+  // Re-anchored on the resolved path: the same check that passed above can pass
+  // through a symlinked ancestor, and only the resolved pair proves containment.
+  resolveInside(root, resolved, "解压目标");
+  const stats = await lstat(resolved);
+  if (stats.isSymbolicLink()) throw new Error("解压目标不能是符号链接。");
+  if (!stats.isDirectory()) throw new Error("解压目标不是一个目录。");
+  return resolved;
+}
+
+/**
+ * `resolve`, then a separator-terminated containment check.
+ *
+ * Ported from `resolveEntryPath` in `deployed-website-source.ts` and kept in
+ * the form the sibling's own comment argues for: a string prefix wrongly
+ * accepts `/tmp/evil` for a root of `/tmp/ev`.
+ */
+function resolveInside(root: string, name: string, what: string): string {
+  const destination = path.resolve(root, name);
+  if (destination !== root && !destination.startsWith(rootPrefix(root))) {
+    throw new Error(`${what}越界：${name}`);
+  }
+  return destination;
+}
+
+/** The same check, re-anchored on the extraction root for one entry name. */
+function resolveEntryPath(root: string, name: string): string {
+  const destination = path.resolve(root, name);
+  if (destination !== root && !destination.startsWith(rootPrefix(root))) {
+    throw new Error(`压缩包条目越界：${name}`);
+  }
+  return destination;
+}
+
+function rootPrefix(root: string): string {
+  return root.endsWith(path.sep) ? root : `${root}${path.sep}`;
+}
+
+// ---------------------------------------------------------------------------
+// Name normalisation
+// ---------------------------------------------------------------------------
+
+/**
+ * Ported from `assertSafeZipEntry` in `deployed-website-source.ts`, widened from
+ * zip to every container: no NUL, not absolute on any platform, no `..`
+ * segment, and no Windows drive letter.
+ *
+ * Two deliberate differences from the sibling, both about not refusing archives
+ * that are not attacks:
+ *
+ *   * A `.` segment is *dropped* rather than refused. `tar cf x.tar .` and
+ *     `zip -r x.zip .` put `./` on every single member, so the sibling's rule
+ *     would make the most common tarball in existence unreadable. A `.` cannot
+ *     escape anything — `resolve` collapses it — and the traversal that matters,
+ *     `..`, stays refused.
+ *   * A name that normalises away to nothing (`./`, `.`) is reported as a *root
+ *     marker* rather than as a refusal, because it is the container saying
+ *     "this archive is rooted here", not content. Counting it as refused would
+ *     mark every such archive truncated.
+ *
+ * The drive-letter clause is the one `win32.isAbsolute` does not cover on its
+ * own — it accepts `C:\x` but not the drive-relative `C:x`, which resolves to
+ * that drive's current directory on Windows.
+ */
+type NormalizedName = { readonly path: string } | { readonly root: true } | { readonly reason: string };
+
+function normalizeEntryName(rawName: string): NormalizedName {
+  if (!rawName) return { reason: "条目名为空" };
+  if (rawName.includes("\0")) return { reason: "条目名包含 NUL 字节" };
+  const unified = rawName.replace(/\\/gu, "/");
+  if (
+    unified.startsWith("/") ||
+    path.isAbsolute(rawName) ||
+    path.posix.isAbsolute(unified) ||
+    path.win32.isAbsolute(rawName)
+  ) {
+    return { reason: "条目名是绝对路径" };
+  }
+  const parts = unified.split("/").filter((part) => part.length > 0 && part !== ".");
+  if (parts.some((part) => part === "..")) return { reason: "条目名包含 .. 路径段" };
+  if (parts.length === 0) return { root: true };
+  if (/^[A-Za-z]:/u.test(parts[0]!)) return { reason: "条目名包含 Windows 盘符" };
+  return { path: parts.join("/") };
+}
+
+/** A normalised name resolved into what an entry should carry. */
+type NameVerdict = { readonly path?: string; readonly reason?: string; readonly drop?: boolean };
+
+function nameVerdict(normalized: NormalizedName, isDirectory: boolean): NameVerdict {
+  if ("root" in normalized) return isDirectory ? { drop: true } : { reason: "条目名为空" };
+  if ("reason" in normalized) return { reason: normalized.reason };
+  return { path: normalized.path };
+}
+
+/** The workspace-relative form echoed back to the client for display. */
+function normalizeArchiveRelativePath(value: string): string {
+  const normalized = normalizeEntryName(value);
+  return "path" in normalized ? normalized.path : "root" in normalized ? "" : value;
+}
+
+/**
+ * The prefix a listing is scoped to, validated with the same rules as an entry
+ * name. It round-trips through the client, so it is attacker-influenced even
+ * though this module is what produced it.
+ */
+function normalizePrefix(raw: string | undefined): string {
+  if (!raw) return "";
+  const normalized = normalizeEntryName(raw);
+  if ("path" in normalized) return normalized.path;
+  if ("root" in normalized) return "";
+  throw new Error(`无法识别的压缩包内路径：${normalized.reason}`);
+}
+
+// ---------------------------------------------------------------------------
+// ZIP
+// ---------------------------------------------------------------------------
+
+const ZIP_END_OF_CENTRAL_DIRECTORY = 0x06054b50;
+const ZIP_CENTRAL_DIRECTORY_ENTRY = 0x02014b50;
+const ZIP_LOCAL_FILE_HEADER = 0x04034b50;
+const ZIP_END_RECORD_SIZE = 22;
+const ZIP_MAX_COMMENT = 0xffff;
+/** The count/offset sentinels that mean "the real value is in the zip64 records". */
+const ZIP_SENTINEL_ENTRIES = 0xffff;
+const ZIP_SENTINEL_32 = 0xffffffff;
+
+type ZipDirectoryEntry = {
+  readonly name: string;
+  readonly method: number;
+  readonly compressedSize: number;
+  readonly uncompressedSize: number;
+  readonly localHeaderOffset: number;
+  readonly unixMode: number | undefined;
+  readonly nameLength: number;
+  readonly extraLength: number;
+  readonly commentLength: number;
+};
+
+function readZipEntries(buffer: Buffer): ArchiveContents {
+  const endRecord = findZipEndRecord(buffer);
+  const declaredEntries = buffer.readUInt16LE(endRecord + 10);
+  const directoryOffset = buffer.readUInt32LE(endRecord + 16);
+  const directorySize = buffer.readUInt32LE(endRecord + 12);
+  // The sentinels mean "look in the zip64 end-of-central-directory records",
+  // which this reader does not parse. Refusing by name beats reading a shifted
+  // offset and writing whatever the garbage points at.
+  if (
+    declaredEntries === ZIP_SENTINEL_ENTRIES ||
+    directoryOffset === ZIP_SENTINEL_32 ||
+    directorySize === ZIP_SENTINEL_32
+  ) {
+    throw new Error("这是 ZIP64 压缩包，工作区面板暂不支持。");
+  }
+  if (directoryOffset + directorySize > buffer.length) {
+    throw new Error("ZIP 中央目录越界，文件可能已损坏。");
+  }
+
+  const entries: ArchiveEntry[] = [];
+  let cursor = directoryOffset;
+  let walked = 0;
+  for (let index = 0; index < declaredEntries; index += 1) {
+    // The walk stops at the ceiling: the count is attacker-controlled, and a
+    // listing must not build a million strings to report that it cannot show a
+    // million strings.
+    if (walked >= WORKSPACE_ARCHIVE_MAX_ENTRIES) break;
+    walked += 1;
+    if (cursor + 46 > buffer.length || buffer.readUInt32LE(cursor) !== ZIP_CENTRAL_DIRECTORY_ENTRY) {
+      throw new Error("ZIP 中央目录已损坏，条目记录不完整。");
+    }
+    const record = readZipDirectoryEntry(buffer, cursor);
+    cursor += 46 + record.nameLength + record.extraLength + record.commentLength;
+    if (cursor > buffer.length) throw new Error("ZIP 中央目录已损坏，条目记录越界。");
+    const entry = zipEntry(buffer, record);
+    if (entry) entries.push(entry);
+  }
+
+  return { entries, totalEntries: declaredEntries, truncated: walked < declaredEntries };
+}
+
+/**
+ * Scans backwards for the end-of-central-directory record.
+ *
+ * Scanned rather than read at a fixed offset because the record is followed by
+ * an archive comment of up to 64 KiB. A candidate is accepted only when its own
+ * comment length lands exactly on the end of the file, which is what stops the
+ * same four signature bytes appearing inside compressed data from being read as
+ * the real record — and what turns a truncated archive into a clear "this is
+ * not a zip" instead of a wild offset.
+ */
+function findZipEndRecord(buffer: Buffer): number {
+  const earliest = Math.max(0, buffer.length - (ZIP_END_RECORD_SIZE + ZIP_MAX_COMMENT));
+  for (let offset = buffer.length - ZIP_END_RECORD_SIZE; offset >= earliest; offset -= 1) {
+    if (buffer.readUInt32LE(offset) !== ZIP_END_OF_CENTRAL_DIRECTORY) continue;
+    if (offset + ZIP_END_RECORD_SIZE + buffer.readUInt16LE(offset + 20) === buffer.length) return offset;
+  }
+  throw new Error("这不是可识别的 ZIP 压缩包（缺少中央目录结束记录，文件可能已截断）。");
+}
+
+function readZipDirectoryEntry(buffer: Buffer, offset: number): ZipDirectoryEntry {
+  const flags = buffer.readUInt16LE(offset + 8);
+  const nameLength = buffer.readUInt16LE(offset + 28);
+  const nameStart = offset + 46;
+  return {
+    // Bit 11 marks UTF-8 names; without it the spec says CP437, which this
+    // module approximates with latin1. The two agree on every ASCII name and
+    // differ only in the C1 box-drawing range.
+    name: buffer.toString(flags & 0x800 ? "utf8" : "latin1", nameStart, nameStart + nameLength),
+    method: buffer.readUInt16LE(offset + 10),
+    compressedSize: buffer.readUInt32LE(offset + 20),
+    uncompressedSize: buffer.readUInt32LE(offset + 24),
+    localHeaderOffset: buffer.readUInt32LE(offset + 42),
+    // The unix mode lives in the high 16 bits of the external attributes, and
+    // only when the archive was written on a unix host (the high byte of
+    // "version made by"). Same rule as the sibling's `isSymbolicLink`, minus
+    // JSZip's `unixPermissions` accessor.
+    unixMode: buffer.readUInt16LE(offset + 4) >> 8 === 3 ? (buffer.readUInt32LE(offset + 38) >>> 16) & 0xffff : undefined,
+    nameLength,
+    extraLength: buffer.readUInt16LE(offset + 30),
+    commentLength: buffer.readUInt16LE(offset + 32),
+  };
+}
+
+function zipEntry(buffer: Buffer, record: ZipDirectoryEntry): ArchiveEntry | undefined {
+  const isDirectory =
+    record.name.endsWith("/") || (record.unixMode !== undefined && (record.unixMode & 0o040000) !== 0);
+  // `isSymbolicLink` from the sibling: refuse the link rather than
+  // materialise one, because a symlink written into a workspace is a write
+  // primitive pointing wherever the attacker likes.
+  const symbolicLink = record.unixMode !== undefined && (record.unixMode & 0o170000) === 0o120000;
+  const verdict = symbolicLink
+    ? ({ reason: "条目是符号链接" } satisfies NameVerdict)
+    : nameVerdict(normalizeEntryName(record.name), isDirectory);
+  if (verdict.drop) return undefined;
+  return {
+    rawName: record.name,
+    ...(verdict.path ? { path: verdict.path } : {}),
+    isDirectory,
+    declaredSize: record.uncompressedSize,
+    compressedSize: record.compressedSize,
+    ...(verdict.reason ? { unsafeReason: verdict.reason } : {}),
+    read: (budget) => readZipEntryData(buffer, record, isDirectory, budget),
+  };
+}
+
+function readZipEntryData(
+  buffer: Buffer,
+  record: ZipDirectoryEntry,
+  isDirectory: boolean,
+  budget: ExpansionBudget,
+): Buffer {
+  if (isDirectory) return Buffer.alloc(0);
+  const header = record.localHeaderOffset;
+  if (header + 30 > buffer.length || buffer.readUInt32LE(header) !== ZIP_LOCAL_FILE_HEADER) {
+    throw new Error("ZIP 条目的本地头已损坏。");
+  }
+  const nameLength = buffer.readUInt16LE(header + 26);
+  const extraLength = buffer.readUInt16LE(header + 28);
+  const start = header + 30 + nameLength + extraLength;
+  const end = start + record.compressedSize;
+  if (end > buffer.length) throw new Error("ZIP 条目数据越界，文件可能已损坏。");
+  // Sizes come from the central directory, never from the local header: with the
+  // streaming flag set, a local header's size fields are zero and the real
+  // values follow the data in a trailing descriptor.
+  const raw = buffer.subarray(start, end);
+  if (record.method === 0) return raw;
+  if (record.method !== 8) throw new Error(`ZIP 条目使用了不支持的压缩方法（${record.method}）。`);
+  return inflateEntry(raw, budget);
+}
+
+// ---------------------------------------------------------------------------
+// TAR
+// ---------------------------------------------------------------------------
+
+const TAR_BLOCK_SIZE = 512;
+const TAR_NAME_OFFSET = 0;
+const TAR_NAME_LENGTH = 100;
+const TAR_SIZE_OFFSET = 124;
+const TAR_CHECKSUM_OFFSET = 148;
+const TAR_CHECKSUM_LENGTH = 8;
+const TAR_TYPEFLAG_OFFSET = 156;
+const TAR_PREFIX_OFFSET = 345;
+const TAR_PREFIX_LENGTH = 155;
+const TAR_TYPE_FILE = "0";
+const TAR_TYPE_DIRECTORY = "5";
+const TAR_TYPE_PAX = "x";
+const TAR_TYPE_GLOBAL_PAX = "g";
+const TAR_TYPE_GNU_LONG_NAME = "L";
+
+function readTarEntries(buffer: Buffer): ArchiveContents {
+  const entries: ArchiveEntry[] = [];
+  let cursor = 0;
+  // A GNU long-name (`L`) or pax (`x`) header carries the real name of the entry
+  // that follows it, in the data block rather than the 100-byte name field.
+  let overrideName: string | undefined;
+  let walked = 0;
+
+  while (cursor + TAR_BLOCK_SIZE <= buffer.length) {
+    if (walked >= WORKSPACE_ARCHIVE_MAX_ENTRIES) break;
+    const header = buffer.subarray(cursor, cursor + TAR_BLOCK_SIZE);
+    if (isZeroBlock(header)) break;
+    walked += 1;
+    verifyTarChecksum(header);
+    const typeflag = String.fromCharCode(header[TAR_TYPEFLAG_OFFSET] ?? 0);
+    const size = readTarSize(header, TAR_SIZE_OFFSET);
+    const dataStart = cursor + TAR_BLOCK_SIZE;
+    const padded = Math.ceil(size / TAR_BLOCK_SIZE) * TAR_BLOCK_SIZE;
+    if (size < 0 || dataStart + padded > buffer.length) {
+      throw new Error("tar 条目越界，文件可能已截断。");
+    }
+    const data = buffer.subarray(dataStart, dataStart + size);
+    const name = overrideName ?? readTarName(header);
+    cursor = dataStart + padded;
+    overrideName = undefined;
+
+    if (typeflag === TAR_TYPE_GNU_LONG_NAME) {
+      overrideName = readNulTerminated(data);
+      continue;
+    }
+    if (typeflag === TAR_TYPE_PAX) {
+      // bsdtar writes one of these per member, carrying extended attributes and
+      // sometimes the real path. It describes the *next* entry, never content.
+      overrideName = readPaxPath(data) ?? overrideName;
+      continue;
+    }
+    if (typeflag === TAR_TYPE_GLOBAL_PAX) continue;
+
+    const isDirectory = typeflag === TAR_TYPE_DIRECTORY || name.endsWith("/");
+    if (!isDirectory && typeflag !== TAR_TYPE_FILE && typeflag !== "\0") {
+      // The tar analogue of the zip symlink refusal, and it covers more: hard
+      // links, devices and FIFOs are all refused, because none of them is
+      // something this panel has any business creating in a workspace.
+      entries.push({
+        rawName: name,
+        isDirectory: false,
+        declaredSize: size,
+        compressedSize: size,
+        unsafeReason: tarTypeRefusal(typeflag),
+        read: () => data,
+      });
+      continue;
+    }
+    const verdict = nameVerdict(normalizeEntryName(name), isDirectory);
+    if (verdict.drop) continue;
+    entries.push({
+      rawName: name,
+      ...(verdict.path ? { path: verdict.path } : {}),
+      isDirectory,
+      declaredSize: size,
+      // A tar member is stored as-is, so its "compressed" size is its own
+      // length; a `.tar.gz` is capped as a whole buffer at gunzip time instead.
+      compressedSize: size,
+      ...(verdict.reason ? { unsafeReason: verdict.reason } : {}),
+      read: () => data,
+    });
+  }
+
+  return { entries, totalEntries: entries.length, truncated: walked >= WORKSPACE_ARCHIVE_MAX_ENTRIES };
+}
+
+function tarTypeRefusal(typeflag: string): string {
+  if (typeflag === "1") return "条目是硬链接";
+  if (typeflag === "2") return "条目是符号链接";
+  if (typeflag === "3" || typeflag === "4") return "条目是设备文件";
+  if (typeflag === "6") return "条目是 FIFO";
+  return `条目类型不受支持（${JSON.stringify(typeflag)}）`;
+}
+
+/**
+ * The name field, then the ustar prefix field when there is one.
+ *
+ * Both halves are needed: `ustar` splits a long path between `prefix` (offset
+ * 345) and `name`, and dropping the prefix silently renames every member under
+ * a deep directory.
+ */
+function readTarName(header: Buffer): string {
+  const name = readNulTerminated(header.subarray(TAR_NAME_OFFSET, TAR_NAME_OFFSET + TAR_NAME_LENGTH));
+  const prefix = readNulTerminated(header.subarray(TAR_PREFIX_OFFSET, TAR_PREFIX_OFFSET + TAR_PREFIX_LENGTH));
+  return prefix ? `${prefix}/${name}` : name;
+}
+
+function readNulTerminated(bytes: Buffer): string {
+  const end = bytes.indexOf(0);
+  return bytes.subarray(0, end === -1 ? bytes.length : end).toString("utf8");
+}
+
+/**
+ * A size field: octal bytes, or a base-256 number when the high bit of the
+ * first byte is set — the spec's escape for values that do not fit in octal,
+ * which archives with multi-gigabyte members use. The same reader covers the
+ * 8-byte checksum field at offset 148.
+ */
+function readTarSize(header: Buffer, offset: number): number {
+  const length = offset === TAR_SIZE_OFFSET ? 12 : TAR_CHECKSUM_LENGTH;
+  const first = header[offset] ?? 0;
+  if ((first & 0x80) !== 0) {
+    let value = BigInt(first & 0x7f);
+    for (let index = offset + 1; index < offset + length; index += 1) {
+      value = (value << 8n) | BigInt(header[index] ?? 0);
+    }
+    const asNumber = Number(value);
+    if (!Number.isSafeInteger(asNumber)) throw new Error("tar 条目大小超出可表示范围。");
+    return asNumber;
+  }
+  const text = header.subarray(offset, offset + length).toString("ascii").replace(/[\0 ]/gu, "");
+  if (!text) return 0;
+  if (!/^[0-7]+$/u.test(text)) throw new Error("tar 条目大小字段已损坏。");
+  const value = Number.parseInt(text, 8);
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error("tar 条目大小字段已损坏。");
+  return value;
+}
+
+/**
+ * The header checksum, verified before any other field is trusted.
+ *
+ * It is computed with its own field read as spaces, which is what catches
+ * truncation and corruption at the block level instead of leaving a garbage size
+ * field to be believed.
+ */
+function verifyTarChecksum(header: Buffer): void {
+  const declared = readTarSize(header, TAR_CHECKSUM_OFFSET);
+  let unsigned = 0;
+  let signed = 0;
+  for (let index = 0; index < TAR_BLOCK_SIZE; index += 1) {
+    const inChecksumField = index >= TAR_CHECKSUM_OFFSET && index < TAR_CHECKSUM_OFFSET + TAR_CHECKSUM_LENGTH;
+    const byte = inChecksumField ? 0x20 : header[index] ?? 0;
+    unsigned += byte;
+    signed += byte > 127 ? byte - 256 : byte;
+  }
+  if (declared !== unsigned && declared !== signed) {
+    throw new Error("tar 头部校验和不匹配，文件可能已损坏。");
+  }
+}
+
+function isZeroBlock(header: Buffer): boolean {
+  for (let index = 0; index < header.length; index += 1) {
+    if (header[index] !== 0) return false;
+  }
+  return true;
+}
+
+/** The `path=` record of a pax extended header, when it carries one. */
+function readPaxPath(data: Buffer): string | undefined {
+  let cursor = 0;
+  while (cursor < data.length) {
+    const space = data.indexOf(0x20, cursor);
+    if (space === -1) return undefined;
+    const lengthText = data.subarray(cursor, space).toString("ascii");
+    if (!/^[0-9]+$/u.test(lengthText)) return undefined;
+    const length = Number.parseInt(lengthText, 10);
+    if (length <= 0 || cursor + length > data.length) return undefined;
+    // `%d %s=%s\n`: the length covers its own digits, so the payload ends one
+    // byte before the record boundary.
+    const record = data.subarray(space + 1, cursor + length - 1).toString("utf8").replace(/\n$/u, "");
+    const separator = record.indexOf("=");
+    if (separator !== -1 && record.slice(0, separator) === "path") return record.slice(separator + 1);
+    cursor += length;
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Dispatch, listing and extraction
+// ---------------------------------------------------------------------------
+
+async function readArchive(archivePath: string): Promise<{ readonly format: ArchiveFormat; readonly buffer: Buffer }> {
+  const selected = archiveFormatFor(archivePath);
+  if (!("format" in selected)) throw new Error(selected.error);
+  const raw = await readFile(archivePath);
+  if (selected.format !== "tar.gz") return { format: selected.format, buffer: raw };
+  try {
+    return {
+      format: selected.format,
+      // `maxOutputLength` on the whole-buffer gunzip: a 200 MiB `.tgz` can
+      // expand well past the budget, and it is decompressed before a single tar
+      // header has been parsed, so this is the only ceiling standing there.
+      buffer: gunzipSync(raw, { maxOutputLength: WORKSPACE_ARCHIVE_MAX_UNCOMPRESSED_BYTES }),
+    };
+  } catch (error) {
+    if (isBufferTooLarge(error)) throw new Error("压缩包展开后的体积过大，已拒绝读取。");
+    throw new Error("gzip 数据已损坏，无法解压。");
+  }
+}
+
+function readContents(buffer: Buffer, format: ArchiveFormat): ArchiveContents {
+  if (format === "zip") {
+    if (buffer.length < ZIP_END_RECORD_SIZE) throw new Error("这个 ZIP 文件太短或已截断。");
+    return readZipEntries(buffer);
+  }
+  if (buffer.length < TAR_BLOCK_SIZE * 2) throw new Error("这个 tar 文件太短或已截断。");
+  return readTarEntries(buffer);
+}
+
+/**
+ * The rows for one level, with directories synthesised from their children.
+ *
+ * A zip or tar routinely stores only file entries and leaves the directories
+ * implied, so a listing that reported only what is literally present would show
+ * an empty level for a directory full of files. A synthesised directory row
+ * carries the same `path` an explicit entry would, with no trailing slash: the
+ * name alone distinguishes a directory, and the view navigates by name.
+ *
+ * `shouldStripArchiveRoot` in `remote/archive.ts` is deliberately *not* ported
+ * here. It strips a single top-level directory because a skill install needs
+ * the path *inside* the repository, whereas a preview has to name what the
+ * archive actually contains — silently dropping the root a user is looking at
+ * would make this panel disagree with every other zip tool.
+ */
+function listOneLevel(
+  contents: ArchiveContents,
+  prefix: string,
+): { readonly entries: readonly WebuiArchiveEntry[]; readonly truncated: boolean } {
+  const scope = prefix ? `${prefix}/` : "";
+  const directories = new Map<string, WebuiArchiveEntry>();
+  const files: WebuiArchiveEntry[] = [];
+  let refused = 0;
+
+  for (const entry of contents.entries) {
+    if (entry.unsafeReason || !entry.path) {
+      // Not named: the view renders only what this call is willing to write, so
+      // an entry that extraction would refuse is not advertised first.
+      refused += 1;
+      continue;
+    }
+    if (!entry.path.startsWith(scope) || entry.path.length === scope.length) continue;
+    const remainder = entry.path.slice(scope.length);
+    const slash = remainder.indexOf("/");
+    if (slash !== -1) {
+      const name = remainder.slice(0, slash);
+      if (!directories.has(name)) {
+        directories.set(name, { path: `${scope}${name}`, name, isDirectory: true });
+      }
+      continue;
+    }
+    if (entry.isDirectory) {
+      if (!directories.has(remainder)) {
+        directories.set(remainder, { path: remainder, name: remainder, isDirectory: true });
+      }
+      continue;
+    }
+    files.push({ path: remainder, name: remainder, isDirectory: false, size: entry.declaredSize });
+  }
+
+  const byName = (a: WebuiArchiveEntry, b: WebuiArchiveEntry): number => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+  const ordered = [...[...directories.values()].sort(byName), ...files.sort(byName)];
+  const entries = ordered.slice(0, WORKSPACE_ARCHIVE_MAX_LISTED_ENTRIES);
+  return { entries, truncated: refused > 0 || ordered.length > entries.length };
+}
+
+/** The entries an extraction writes, scoped to the prefix. */
+function selectForExtraction(contents: ArchiveContents, prefix: string): readonly ArchiveEntry[] {
+  if (!prefix) return contents.entries;
+  const scope = `${prefix}/`;
+  return contents.entries.filter((entry) => entry.path === prefix || entry.path.startsWith(scope));
+}
+
+/**
+ * An entry's path relative to the prefix being extracted, so extracting `src`
+ * into `dest` writes `dest/index.ts` rather than `dest/src/index.ts`.
+ */
+function entryPathUnderPrefix(entry: ArchiveEntry, prefix: string): string {
+  if (!entry.path) throw new Error(`压缩包中存在不安全的条目：${entry.unsafeReason ?? entry.rawName}`);
+  if (!prefix) return entry.path;
+  if (entry.path === prefix) return path.posix.basename(entry.path);
+  return entry.path.slice(prefix.length + 1);
+}
+
+/**
+ * Writes one entry, re-validating its parent directory against the extraction
+ * root first.
+ *
+ * The parent is re-resolved with `realpath` because `mkdir -p` through a
+ * symlink left behind by an earlier entry (or by the user) would otherwise be
+ * written *through*: the name check passes, the filesystem resolves elsewhere.
+ */
+async function writeExtractedFile(
+  root: string,
+  target: string,
+  entry: ArchiveEntry,
+  budget: ExpansionBudget,
+): Promise<void> {
+  const parent = path.dirname(target);
+  await mkdir(parent, { recursive: true });
+  const resolvedParent = await realpath(parent);
+  if (resolvedParent !== root && !resolvedParent.startsWith(rootPrefix(root))) {
+    throw new Error("压缩包条目试图通过符号链接写出解压目录。");
+  }
+  const data = readEntryBounded(entry, budget);
+  // `wx`: refuse to clobber, as the sibling extractor does. An archive the user
+  // did not write must never be able to overwrite a file already in their
+  // workspace, and a conflict is far better surfaced than silently resolved in
+  // the archive's favour.
+  await writeFile(path.join(resolvedParent, path.basename(target)), data, { flag: "wx" });
+}
+
+/**
+ * Reads an entry's bytes, charging both the shared total budget and the
+ * per-entry expansion ratio.
+ *
+ * The ratio is measured against the bytes that actually arrived, not the
+ * declared size, so the classic shape — a tiny member that inflates to
+ * gigabytes — is caught even when the header is honest about the total.
+ */
+function readEntryBounded(entry: ArchiveEntry, budget: ExpansionBudget): Buffer {
+  const data = entry.read(budget);
+  if (data.length > budget.remaining) {
+    throw new Error("压缩包展开后的体积过大，已拒绝解压。");
+  }
+  const compressed = Math.max(entry.compressedSize, 1);
+  if (data.length / compressed > WORKSPACE_ARCHIVE_MAX_EXPANSION_RATIO) {
+    throw new Error("压缩包中存在异常膨胀的条目，已拒绝解压。");
+  }
+  budget.remaining -= data.length;
+  return data;
+}
+
+/**
+ * Inflates one entry, capped at what is *left* of the shared budget rather than
+ * at the entry's declared size.
+ *
+ * That distinction is the whole point: a header claiming 12 bytes and
+ * delivering a gigabyte is stopped at the budget instead of being believed, and
+ * it never gets to allocate the memory it asked for. zlib signals the cap with
+ * `ERR_BUFFER_TOO_LARGE`, which is a refusal rather than an internal failure and
+ * is translated into the same message the total cap produces.
+ */
+function inflateEntry(raw: Buffer, budget: ExpansionBudget): Buffer {
+  if (budget.remaining <= 0) throw new Error("压缩包展开后的体积过大，已拒绝读取。");
+  try {
+    return inflateRawSync(raw, { maxOutputLength: budget.remaining });
+  } catch (error) {
+    if (isBufferTooLarge(error)) throw new Error("压缩包展开后的体积过大，已拒绝读取。");
+    throw new Error("ZIP 条目已损坏，无法解压。");
+  }
+}
+
+function isBufferTooLarge(error: unknown): boolean {
+  return typeof error === "object" && error !== null && (error as { code?: unknown }).code === "ERR_BUFFER_TOO_LARGE";
+}
+
+function isMissingPath(error: unknown): boolean {
+  return typeof error === "object" && error !== null && (error as { code?: unknown }).code === "ENOENT";
+}

From 5447d63f7acbc5218cf76e98f54a6a0aa8f0b064 Mon Sep 17 00:00:00 2001
From: probe <probe@local>
Date: Sun, 4 Oct 2026 09:06:08 +0800
Subject: [PATCH 18/21] feat(webui): render the archive listing and extract a
 chosen directory

The view lists one level of an archive and re-lists with `prefix` when a
directory is entered, which is all the server's hardening is asked to be: it
renders the rows it is given and names nothing of its own.

States are distinguishable rather than implied: loading and "the service has
no archive capability" are `role="status"`, a failure is `role="alert"`, an
empty level and a truncated listing each have their own marker. `truncated`
from the runtime is passed straight through -- the reader hit a ceiling and the
user has to know the list is not the whole archive.

The destination is derived from the archive's own path (`dist/bundle.zip` ->
`dist/bundle`) or taken from the `destination` prop, and displayed rather than
typed. There is no free-text field anywhere in the view: a destination a
browser can type is a path-traversal endpoint rather than a feature, and the
server re-validates it regardless.

The tests build real archives with `zip`/`tar` in a temp dir and hand-rolled
zips for the shapes no archive tool will emit -- `zip` answers "Nothing to do!"
for `../escape` and for `/etc/hostname`, so the traversal, absolute-name,
symlink, entry-count and lying-header cases have to be written byte by byte.
That also keeps the security coverage independent of whether the CLIs exist.
`WorkspaceArchiveListing` and `WorkspaceArchiveNotice` are exported so the
non-loading states are reachable through `renderToStaticMarkup`, which does not
run effects.
---
 .../components/WorkspaceArchiveView.tsx       | 272 ++++++-
 .../test/unit/webui-workspace-archive.test.ts | 715 ++++++++++++++++++
 test/vitest-suites.json                       |   3 +-
 3 files changed, 979 insertions(+), 11 deletions(-)
 create mode 100644 packages/webui/test/unit/webui-workspace-archive.test.ts

diff --git a/packages/webui/src/client/components/WorkspaceArchiveView.tsx b/packages/webui/src/client/components/WorkspaceArchiveView.tsx
index cea67e4dc..834a8b05d 100644
--- a/packages/webui/src/client/components/WorkspaceArchiveView.tsx
+++ b/packages/webui/src/client/components/WorkspaceArchiveView.tsx
@@ -1,10 +1,14 @@
 // Owns the workspace archive feature (list + extract inside .zip/.tar archives).
-// Nothing is implemented yet: this file is the seam a different implementer
-// fills in. `WorkspacePanels.tsx` does not mount it yet — there is no archive
-// tab to mount it on, and adding one would be a feature, not a split.
+// `WorkspacePanels.tsx` mounts this for every path `isWorkspaceArchivePath`
+// accepts, and the runtime owns every hardening decision — this file renders
+// what `readWorkspaceArchive` is willing to name and never invents a path.
 
-import type { ReactElement } from "react";
-import type { WebuiWorkspaceArchiveExtractResult, WebuiWorkspaceArchiveListing } from "../../server/port.js";
+import { useCallback, useEffect, useState, type ReactElement } from "react";
+import type {
+  WebuiArchiveEntry,
+  WebuiWorkspaceArchiveExtractResult,
+  WebuiWorkspaceArchiveListing,
+} from "../../server/port.js";
 
 export type WorkspaceArchiveViewProps = {
   /** Absolute workspace root; every archive path below is relative to it. */
@@ -28,11 +32,259 @@ export type WorkspaceArchiveViewProps = {
   readonly destination?: string;
 };
 
+type ArchiveLoadState =
+  | { readonly status: "loading" }
+  | { readonly status: "error"; readonly error: string }
+  | { readonly status: "ready"; readonly listing: WebuiWorkspaceArchiveListing };
+
+type ArchiveExtractState =
+  | { readonly status: "idle" }
+  | { readonly status: "running" }
+  | { readonly status: "done"; readonly result: WebuiWorkspaceArchiveExtractResult }
+  | { readonly status: "error"; readonly error: string };
+
+/**
+ * One directory level of an archive, with navigation and the extract control.
+ *
+ * Split out from the container so every state is reachable without a running
+ * effect: `renderToStaticMarkup` does not run effects, and the parent would
+ * otherwise leave loading, empty, error and truncated untestable.
+ */
+export function WorkspaceArchiveListing({
+  archivePath,
+  prefix,
+  destination,
+  entries,
+  totalEntries,
+  truncated,
+  extractState,
+  onEnterDirectory,
+  onGoUp,
+  onExtract,
+}: {
+  readonly archivePath: string;
+  /** The directory being shown, relative to the archive root; "" is the root. */
+  readonly prefix: string;
+  /** The workspace-relative directory an extraction would write into. */
+  readonly destination: string;
+  readonly entries: readonly WebuiArchiveEntry[];
+  readonly totalEntries: number;
+  readonly truncated: boolean;
+  readonly extractState: ArchiveExtractState;
+  readonly onEnterDirectory?: (name: string) => void;
+  readonly onGoUp?: () => void;
+  readonly onExtract?: () => void;
+}): ReactElement {
+  return (
+    <div className="webui-workspace-archive-view" data-testid="workspace-archive-view">
+      <p className="webui-workspace-archive-path" data-testid="workspace-archive-path">
+        {`${archivePath}${prefix ? ` › ${prefix}` : ""}`}
+      </p>
+      {prefix
+        ? <button type="button" data-testid="workspace-archive-up" onClick={onGoUp}>返回上级</button>
+        : null}
+      {truncated
+        ? (
+            <p role="status" data-testid="workspace-archive-truncated">
+              {`压缩包共 ${totalEntries} 项，这里只显示了 ${entries.length} 项；其余条目未列出。`}
+            </p>
+          )
+        : null}
+      {entries.length === 0
+        ? <p data-testid="workspace-archive-empty">该目录没有条目。</p>
+        : (
+            <ul className="webui-workspace-archive-entries" data-testid="workspace-archive-entries">
+              {entries.map((entry) => (
+                <li
+                  key={entry.path}
+                  data-testid="workspace-archive-entry"
+                  data-archive-path={entry.path}
+                  data-directory={entry.isDirectory ? "true" : "false"}
+                >
+                  {entry.isDirectory
+                    ? (
+                        <button type="button" data-testid="workspace-archive-directory" onClick={() => onEnterDirectory?.(entry.name)}>
+                          {`${entry.name}（目录）`}
+                        </button>
+                      )
+                    : (
+                        <>
+                          <span data-testid="workspace-archive-file">{entry.name}</span>
+                          {entry.size === undefined
+                            ? null
+                            : <span data-testid="workspace-archive-size">{formatArchiveSize(entry.size)}</span>}
+                        </>
+                      )}
+                </li>
+              ))}
+            </ul>
+          )}
+      <ArchiveExtractControls destination={destination} extractState={extractState} onExtract={onExtract} />
+    </div>
+  );
+}
+
+/**
+ * The extract affordance, with its destination shown rather than typed.
+ *
+ * The destination is a workspace-relative path this component derived from the
+ * archive (or a caller-supplied one); there is no free-text field anywhere in
+ * this view, because a destination a browser can type is a path-traversal
+ * endpoint rather than a feature. The server re-validates it regardless.
+ */
+function ArchiveExtractControls({
+  destination,
+  extractState,
+  onExtract,
+}: {
+  readonly destination: string;
+  readonly extractState: ArchiveExtractState;
+  readonly onExtract?: () => void;
+}): ReactElement {
+  return (
+    <div className="webui-workspace-archive-extract">
+      <p data-testid="workspace-archive-destination">
+        {destination ? `解压目标：${destination}` : "没有可用的解压目标。"}
+      </p>
+      <button
+        type="button"
+        data-testid="workspace-archive-extract"
+        disabled={!destination || !onExtract || extractState.status === "running"}
+        onClick={onExtract}
+      >
+        {extractState.status === "running" ? "正在解压…" : "解压当前目录"}
+      </button>
+      {extractState.status === "done"
+        ? (
+            <p role="status" data-testid="workspace-archive-extract-result">
+              {`已解压 ${extractState.result.writtenFiles} 个文件到 ${extractState.result.destination}${extractState.result.truncated ? "（条目过多，仅解压了前一部分）" : ""}。`}
+            </p>
+          )
+        : null}
+      {extractState.status === "error"
+        ? <p role="alert" data-testid="workspace-archive-extract-error">{extractState.error}</p>
+        : null}
+    </div>
+  );
+}
+
+/** Shown for every state that is not a listing: unavailable, loading, failed. */
+export function WorkspaceArchiveNotice({
+  reason,
+  role = "status",
+}: {
+  readonly reason: string;
+  /** `alert` for a failure, `status` for a state that was never available. */
+  readonly role?: "status" | "alert";
+}): ReactElement {
+  return <p role={role} data-testid="workspace-archive-notice">{reason}</p>;
+}
+
 /**
- * Placeholder archive view. It renders the "not available" state so the
- * workspace panel has a mount point, and stays type-safe: replacing the body
- * with a real listing is a change inside this file alone.
+ * The archive preview: one level at a time, with the extract control.
+ *
+ * Entering a directory re-lists with `prefix`; going up drops the last segment.
+ * A `truncated` listing is passed straight through rather than smoothed over —
+ * the runtime hit a ceiling and the user has to know that what they see is not
+ * the whole archive.
  */
-export function WorkspaceArchiveView(_props: WorkspaceArchiveViewProps): ReactElement {
-  return <div role="status"><p>工作区压缩包预览尚未接入。</p></div>;
+export function WorkspaceArchiveView(props: WorkspaceArchiveViewProps): ReactElement {
+  const { workspaceDir, path, destination, readWorkspaceArchive, extractWorkspaceArchive } = props;
+  const [prefix, setPrefix] = useState("");
+  const [load, setLoad] = useState<ArchiveLoadState>({ status: "loading" });
+  const [extract, setExtract] = useState<ArchiveExtractState>({ status: "idle" });
+  const target = destination ?? archiveDestinationFor(path);
+
+  useEffect(() => {
+    if (!readWorkspaceArchive) return;
+    let stale = false;
+    setLoad({ status: "loading" });
+    readWorkspaceArchive({ workspaceDir, path, ...(prefix ? { prefix } : {}) })
+      .then((listing) => {
+        if (stale) return;
+        setLoad({ status: "ready", listing });
+      })
+      .catch((error: unknown) => {
+        if (stale) return;
+        setLoad({ status: "error", error: describeError(error) });
+      });
+    return () => {
+      stale = true;
+    };
+  }, [workspaceDir, path, prefix, readWorkspaceArchive]);
+
+  const enterDirectory = useCallback((name: string) => {
+    setPrefix((current) => (current ? `${current}/${name}` : name));
+  }, []);
+  const goUp = useCallback(() => {
+    setPrefix((current) => {
+      const slash = current.lastIndexOf("/");
+      return slash === -1 ? "" : current.slice(0, slash);
+    });
+  }, []);
+  const extractHere = useCallback(() => {
+    if (!extractWorkspaceArchive || !target) return;
+    setExtract({ status: "running" });
+    extractWorkspaceArchive({ workspaceDir, path, destination: target, ...(prefix ? { prefix } : {}) })
+      .then((result) => setExtract({ status: "done", result }))
+      .catch((error: unknown) => setExtract({ status: "error", error: describeError(error) }));
+  }, [extractWorkspaceArchive, workspaceDir, path, prefix, target]);
+
+  if (!readWorkspaceArchive) {
+    return <WorkspaceArchiveNotice reason="当前服务没有提供压缩包浏览能力。" />;
+  }
+  if (load.status === "loading") return <WorkspaceArchiveNotice reason="正在读取压缩包…" />;
+  if (load.status === "error") return <WorkspaceArchiveNotice reason={load.error} role="alert" />;
+  return (
+    <WorkspaceArchiveListing
+      archivePath={load.listing.archivePath}
+      prefix={prefix}
+      destination={target}
+      entries={load.listing.entries}
+      totalEntries={load.listing.totalEntries}
+      truncated={load.listing.truncated}
+      extractState={extract}
+      onEnterDirectory={enterDirectory}
+      onGoUp={prefix ? goUp : undefined}
+      onExtract={extractWorkspaceArchive && target ? extractHere : undefined}
+    />
+  );
+}
+
+/**
+ * The destination an extraction uses when the caller supplies none: the
+ * archive's own name without its extension, beside the archive.
+ *
+ * Derived rather than typed for the reason `destination`'s prop comment gives —
+ * a browser cannot name an absolute path, and every path it could type would
+ * need the server to distrust it. Returns "" for a name that is not a plain
+ * relative path, which the view renders as "no usable destination" instead of
+ * handing the server something it would have to reject.
+ */
+export function archiveDestinationFor(archivePath: string): string {
+  const cleaned = archivePath.replace(/\\/gu, "/");
+  const slash = cleaned.lastIndexOf("/");
+  const directory = slash === -1 ? "" : cleaned.slice(0, slash);
+  const name = cleaned.slice(slash + 1).replace(/\.(?:tar\.gz|tgz|zip|tar|gz|bz2|xz|7z|rar)$/iu, "");
+  const candidate = directory ? `${directory}/${name}` : name;
+  if (!candidate) return "";
+  return candidate.split("/").some((segment) => segment === "" || segment === "." || segment === "..") ? "" : candidate;
+}
+
+/** Bytes as a short human string; absent stays absent rather than becoming 0. */
+export function formatArchiveSize(size: number): string {
+  if (!Number.isFinite(size) || size < 0) return "";
+  if (size < 1024) return `${size} B`;
+  const units = ["KB", "MB", "GB", "TB"];
+  let value = size / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${value.toFixed(1)} ${units[unit]}`;
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error && error.message ? error.message : String(error);
 }
diff --git a/packages/webui/test/unit/webui-workspace-archive.test.ts b/packages/webui/test/unit/webui-workspace-archive.test.ts
new file mode 100644
index 000000000..22d37e27b
--- /dev/null
+++ b/packages/webui/test/unit/webui-workspace-archive.test.ts
@@ -0,0 +1,715 @@
+// Unit tests for the workspace archive preview.
+//
+// Two halves:
+//   * the server module (`workspace-archive.ts`) against real archives built in
+//     a temp dir, plus hand-rolled byte-level zips for the shapes no archive
+//     tool will emit on request (`../escape`, `/absolute`, a symlink, a lying
+//     header, ten thousand entries);
+//   * the view (`WorkspaceArchiveView.tsx`) through `renderToStaticMarkup` —
+//     the project's SSR test convention, see `workspace-panel-state.test.ts`.
+//     Static rendering does not run effects, so the container's first paint and
+//     every non-loading state are asserted through the presentational exports.
+//
+// The clauses these pin shut:
+//   * a valid zip/tar/tar.gz lists one level, and `prefix` walks deeper;
+//   * an entry that escapes the destination is refused and nothing is written;
+//   * absolute names, Windows drive letters and backslash separators are
+//     refused;
+//   * a symlink is refused rather than materialised;
+//   * the entry ceiling stops the reader before a huge entry count can exhaust
+//     memory while building a listing;
+//   * a lying header is caught, both by the declared-total pre-flight and by the
+//     per-entry expansion ratio;
+//   * a truncated or non-archive file produces a clear message, not a crash;
+//   * the port no longer throws "capability not connected yet".
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { deflateRawSync, gzipSync } from "node:zlib";
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { extractWorkspaceArchiveDirectory, readWorkspaceArchiveListing } from "../../src/server/workspace-archive.js";
+import { createHarnessPortFromHost, type WebuiRuntimeCliService } from "../../src/server/host.js";
+import {
+  archiveDestinationFor,
+  formatArchiveSize,
+  WorkspaceArchiveListing,
+  WorkspaceArchiveNotice,
+  WorkspaceArchiveView,
+} from "../../src/client/components/WorkspaceArchiveView.js";
+
+/** Fixtures live in the OS temp dir; nothing is written into the repo tree. */
+let workspace = "";
+
+function artifactPath(name: string): string {
+  return path.join(workspace, name);
+}
+
+function writeArtifact(name: string, content: Buffer | string): string {
+  const target = artifactPath(name);
+  writeFileSync(target, content);
+  return target;
+}
+
+/** Whether anything at all sits at this path, directory included. */
+function exists(candidate: string): boolean {
+  try {
+    statSync(candidate);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The files (not directories) written under a destination, relative and sorted. */
+function writtenFiles(root: string): string[] {
+  try {
+    return readdirSync(root, { recursive: true, withFileTypes: true })
+      .filter((entry) => entry.isFile())
+      .map((entry) => path.relative(root, path.join(entry.parentPath, entry.name)))
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+function readArtifact(name: string): string | undefined {
+  try {
+    return readFileSync(artifactPath(name), "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+beforeAll(() => {
+  // `realpathSync` first: on macOS the temp dir is a symlink, and the module
+  // resolves the workspace root through `realpath`, so an unresolved fixture
+  // path would not match what the module compares against.
+  workspace = mkdtempSync(path.join(realpathSync(tmpdir()), "webui-archive-"));
+});
+
+afterAll(() => {
+  if (workspace) rmSync(workspace, { force: true, recursive: true });
+});
+
+// ---------------------------------------------------------------------------
+// Fixture builders
+// ---------------------------------------------------------------------------
+
+function canRun(command: string): boolean {
+  try {
+    execFileSync(command, ["--help"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const HAS_ZIP = canRun("zip");
+const HAS_TAR = canRun("tar");
+
+function writeTree(name: string, members: Readonly<Record<string, string>>): string {
+  const source = artifactPath(name);
+  mkdirSync(source, { recursive: true });
+  for (const [member, content] of Object.entries(members)) {
+    const file = path.join(source, member);
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, content);
+  }
+  return source;
+}
+
+/**
+ * `COPYFILE_DISABLE` for the fixture builders: without it macOS's archiver adds
+ * an AppleDouble sidecar member (`._inner.txt`) beside every file, which would
+ * make these assertions about the platform rather than about the reader.
+ */
+const FIXTURE_ENV = { ...process.env, COPYFILE_DISABLE: "1" };
+
+/** A real zip, built by the `zip` CLI. */
+function realZip(name: string, members: Readonly<Record<string, string>>): string {
+  const source = writeTree(`${name}-src`, members);
+  execFileSync("zip", ["-q", "-r", artifactPath(name), "."], { cwd: source, env: FIXTURE_ENV });
+  return artifactPath(name);
+}
+
+/** A real tar, or a gzipped one when the name ends in `.tgz`. */
+function realTar(name: string, members: Readonly<Record<string, string>>): string {
+  const source = writeTree(`${name}-src`, members);
+  const args = name.endsWith(".tgz") ? ["czf", artifactPath(name)] : ["cf", artifactPath(name)];
+  execFileSync("tar", [...args, "."], { cwd: source, env: FIXTURE_ENV });
+  return artifactPath(name);
+}
+
+type CraftedZipEntry = {
+  readonly name: string;
+  readonly content?: string | Buffer;
+  /** Unix mode written into the external attributes; 0o120000 marks a link. */
+  readonly mode?: number;
+  readonly method?: 0 | 8;
+  /** Overrides for the central directory, i.e. the header being lied to. */
+  readonly declaredUncompressedSize?: number;
+  readonly declaredCompressedSize?: number;
+};
+
+/**
+ * A zip written byte by byte.
+ *
+ * The archive tools refuse to emit the hostile shapes — `zip` answers "Nothing
+ * to do!" for `../escape` and for `/etc/hostname` — so the security cases need a
+ * writer that will. Only the fields the reader parses are filled in; the CRC is
+ * left zero because nothing verifies it, which is precisely the kind of sloppiness
+ * a hostile archive would have.
+ */
+function craftZip(entries: readonly CraftedZipEntry[]): Buffer {
+  const locals: Buffer[] = [];
+  const centrals: Buffer[] = [];
+  let offset = 0;
+  for (const entry of entries) {
+    const name = Buffer.from(entry.name, "utf8");
+    const raw = Buffer.isBuffer(entry.content) ? entry.content : Buffer.from(entry.content ?? "", "utf8");
+    const method = entry.method ?? 8;
+    const data = method === 0 ? raw : deflateRawSync(raw);
+    const mode = entry.mode ?? (entry.name.endsWith("/") ? 0o040755 : 0o100644);
+
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(0x800, 6);
+    local.writeUInt16LE(method, 8);
+    local.writeUInt32LE(data.length, 18);
+    local.writeUInt32LE(raw.length, 22);
+    local.writeUInt16LE(name.length, 26);
+    locals.push(local, name, data);
+
+    const central = Buffer.alloc(46);
+    central.writeUInt32LE(0x02014b50, 0);
+    // High byte 3 = unix, which is what makes the external attributes a mode.
+    central.writeUInt16LE((3 << 8) | 20, 4);
+    central.writeUInt16LE(20, 6);
+    central.writeUInt16LE(0x800, 8);
+    central.writeUInt16LE(method, 10);
+    central.writeUInt32LE(entry.declaredCompressedSize ?? data.length, 20);
+    central.writeUInt32LE(entry.declaredUncompressedSize ?? raw.length, 24);
+    central.writeUInt16LE(name.length, 28);
+    // `>>> 0`, not `<< 16`: a mode with bit 31 set (0o120777) shifts into the
+    // sign bit and comes back negative.
+    central.writeUInt32LE(((mode & 0xffff) * 0x10000) >>> 0, 38);
+    central.writeUInt32LE(offset, 42);
+    centrals.push(central, name);
+
+    offset += local.length + name.length + data.length;
+  }
+
+  const centralDirectory = Buffer.concat(centrals);
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(entries.length, 8);
+  end.writeUInt16LE(entries.length, 10);
+  end.writeUInt32LE(centralDirectory.length, 12);
+  end.writeUInt32LE(offset, 16);
+  return Buffer.concat([...locals, centralDirectory, end]);
+}
+
+/** A minimal tar: one 512-byte header, its padded data, and the end marker. */
+function craftTar(name: string, content: string, typeflag = "0"): Buffer {
+  const body = Buffer.from(content, "utf8");
+  const header = Buffer.alloc(512);
+  header.write(name, 0, "utf8");
+  header.write("0000644\0", 100);
+  header.write("0000000\0", 108);
+  header.write("0000000\0", 116);
+  header.write(`${body.length.toString(8).padStart(11, "0")}\0`, 124);
+  header.write("00000000000\0", 136);
+  header.write("        ", 148, "ascii");
+  header.write(typeflag, 156, "ascii");
+  header.write("ustar\0" + "00", 257, "ascii");
+  let checksum = 0;
+  for (const byte of header) checksum += byte;
+  header.write(`${checksum.toString(8).padStart(6, "0")}\0 `, 148, "ascii");
+  const padded = Buffer.alloc(Math.ceil(body.length / 512) * 512);
+  body.copy(padded);
+  return Buffer.concat([header, padded, Buffer.alloc(1024)]);
+}
+
+// ---------------------------------------------------------------------------
+// Server: listing
+// ---------------------------------------------------------------------------
+
+describe("workspace archive listing", () => {
+  it.skipIf(!HAS_ZIP)("lists one level of a real zip and synthesises its directories", async () => {
+    realZip("plain.zip", { "inner.txt": "hello", "sub/deep.txt": "deeper" });
+    const listing = await readWorkspaceArchiveListing({ workspaceDir: workspace, path: "plain.zip" });
+    expect(listing.archivePath).toBe("plain.zip");
+    // `sub` is implied by `sub/deep.txt`; a listing that reported only what is
+    // literally present would show an empty level for a directory full of files.
+    expect(listing.entries.map((entry) => [entry.name, entry.isDirectory, entry.size])).toEqual([
+      ["sub", true, undefined],
+      ["inner.txt", false, 5],
+    ]);
+    expect(listing.totalEntries).toBe(3);
+    expect(listing.truncated).toBe(false);
+  });
+
+  it.skipIf(!HAS_ZIP)("walks into a directory by re-listing with a prefix", async () => {
+    realZip("nested.zip", { "inner.txt": "hello", "sub/deep.txt": "deeper", "sub/other/x.txt": "x" });
+    const listing = await readWorkspaceArchiveListing({ workspaceDir: workspace, path: "nested.zip", prefix: "sub" });
+    expect(listing.entries.map((entry) => [entry.name, entry.isDirectory])).toEqual([
+      ["other", true],
+      ["deep.txt", false],
+    ]);
+    expect(listing.truncated).toBe(false);
+  });
+
+  it.skipIf(!HAS_TAR)("reads a path longer than the 100-byte name field", async () => {
+    // Longer than the tar name field, so it arrives in the ustar prefix field or
+    // a pax `path=` record depending on the archiver. Either way the listing has
+    // to name the real path: dropping the prefix would rename every member under
+    // a deep directory, silently.
+    const directory = "d".repeat(90);
+    const file = `${"n".repeat(60)}.txt`;
+    realTar("long.tar", { [`${directory}/${file}`]: "deep" });
+    const root = await readWorkspaceArchiveListing({ workspaceDir: workspace, path: "long.tar" });
+    expect(root.entries.map((entry) => entry.name)).toEqual([directory]);
+    const nested = await readWorkspaceArchiveListing({
+      workspaceDir: workspace,
+      path: "long.tar",
+      prefix: directory,
+    });
+    expect(nested.entries.map((entry) => entry.name)).toEqual([file]);
+    expect(nested.truncated).toBe(false);
+  });
+
+  it.skipIf(!HAS_TAR)("reads a real tar and a gzipped tar the same way", async () => {
+    realTar("plain.tar", { "inner.txt": "hello", "sub/deep.txt": "deeper" });
+    realTar("plain.tgz", { "inner.txt": "hello", "sub/deep.txt": "deeper" });
+    for (const archive of ["plain.tar", "plain.tgz"]) {
+      const listing = await readWorkspaceArchiveListing({ workspaceDir: workspace, path: archive });
+      expect(listing.entries.map((entry) => entry.name)).toEqual(["sub", "inner.txt"]);
+      expect(listing.truncated).toBe(false);
+    }
+  });
+
+  it("refuses a file that is not an archive, and names the formats it can read", async () => {
+    writeArtifact("notes.zip", "this is not a zip at all\n");
+    await expect(readWorkspaceArchiveListing({ workspaceDir: workspace, path: "notes.zip" })).rejects.toThrow(
+      /不是可识别的 ZIP/,
+    );
+    writeArtifact("bundle.rar", "Rar!\x1a\x07\x00");
+    await expect(readWorkspaceArchiveListing({ workspaceDir: workspace, path: "bundle.rar" })).rejects.toThrow(
+      /不支持的压缩包格式/,
+    );
+    writeArtifact("plain.gz", gzipSync(Buffer.from("hello")));
+    // A bare `.gz` is one compressed stream with no directory structure, so it
+    // is refused by name rather than guessed at as a tar.
+    await expect(readWorkspaceArchiveListing({ workspaceDir: workspace, path: "plain.gz" })).rejects.toThrow(
+      /\.tar\.gz/,
+    );
+    writeArtifact("bundle.7z", "7z\xbc\xaf\x27\x1c");
+    await expect(readWorkspaceArchiveListing({ workspaceDir: workspace, path: "bundle.7z" })).rejects.toThrow(
+      /不支持的压缩包格式/,
+    );
+    writeArtifact("notes.txt", "plain text");
+    await expect(readWorkspaceArchiveListing({ workspaceDir: workspace, path: "notes.txt" })).rejects.toThrow(
+      /只有 .zip/,
+    );
+  });
+
+  it("reports a truncated zip instead of reading past the end of the file", async () => {
+    const complete = craftZip([{ name: "a.txt", content: "hello" }]);
+    // Drop the end-of-central-directory record, which is exactly what a partial
+    // download or a full disk leaves behind.
+    writeArtifact("truncated.zip", complete.subarray(0, complete.length - 12));
+    await expect(readWorkspaceArchiveListing({ workspaceDir: workspace, path: "truncated.zip" })).rejects.toThrow(
+      /不是可识别的 ZIP/,
+    );
+    writeArtifact("half.zip", craftZip([{ name: "a.txt", content: "hello" }]).subarray(0, 20));
+    await expect(readWorkspaceArchiveListing({ workspaceDir: workspace, path: "half.zip" })).rejects.toThrow(/ZIP/);
+  });
+
+  it("reports a truncated or corrupt tar rather than trusting a garbage header", async () => {
+    const complete = craftTar("a.txt", "hello");
+    writeArtifact("cut.tar", complete.subarray(0, 700));
+    await expect(readWorkspaceArchiveListing({ workspaceDir: workspace, path: "cut.tar" })).rejects.toThrow(/tar/);
+
+    const corrupt = Buffer.from(complete);
+    corrupt[124] = 0xff;
+    writeArtifact("corrupt.tar", corrupt);
+    await expect(readWorkspaceArchiveListing({ workspaceDir: workspace, path: "corrupt.tar" })).rejects.toThrow(
+      /校验和|大小字段/,
+    );
+
+    writeArtifact("tiny.tar", Buffer.alloc(200));
+    await expect(readWorkspaceArchiveListing({ workspaceDir: workspace, path: "tiny.tar" })).rejects.toThrow(/太短或已截断/);
+  });
+
+  it("stops at the entry ceiling before a huge entry count can exhaust memory", async () => {
+    // One directory holding 10,001 files. A full parse would report a single row
+    // *and* `truncated: false`, so `truncated: true` here can only mean the
+    // reader stopped at its ceiling.
+    writeArtifact(
+      "many.zip",
+      craftZip(
+        Array.from({ length: 10_001 }, (_, index) => ({
+          name: `d/file-${String(index).padStart(5, "0")}.txt`,
+          content: "",
+        })),
+      ),
+    );
+    const listing = await readWorkspaceArchiveListing({ workspaceDir: workspace, path: "many.zip" });
+    expect(listing.entries).toHaveLength(1);
+    expect(listing.totalEntries).toBe(10_001);
+    expect(listing.truncated).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Server: extraction
+// ---------------------------------------------------------------------------
+
+describe("workspace archive extraction", () => {
+  it.skipIf(!HAS_ZIP)("writes the current directory into a destination beside the archive", async () => {
+    realZip("bundle.zip", { "inner.txt": "hello", "sub/deep.txt": "deeper", "sub/other/x.txt": "x" });
+    const result = await extractWorkspaceArchiveDirectory({
+      workspaceDir: workspace,
+      path: "bundle.zip",
+      destination: "unpacked",
+      prefix: "sub",
+    });
+    // The prefix is stripped, so extracting `sub` writes `deep.txt`, not
+    // `sub/deep.txt`.
+    expect(result).toMatchObject({ archivePath: "bundle.zip", destination: "unpacked", writtenFiles: 2 });
+    expect(readArtifact("unpacked/deep.txt")).toBe("deeper");
+    expect(readArtifact("unpacked/other/x.txt")).toBe("x");
+    expect(exists(artifactPath("unpacked/inner.txt"))).toBe(false);
+  });
+
+  it("refuses an entry that escapes the destination and writes nothing", async () => {
+    for (const name of ["../escaped.txt", "a/../../escaped.txt", "..\\escaped.txt"]) {
+      writeArtifact("slip.zip", craftZip([{ name, content: "pwned" }]));
+      await expect(
+        extractWorkspaceArchiveDirectory({ workspaceDir: workspace, path: "slip.zip", destination: "out" }),
+      ).rejects.toThrow(/不安全|越界/);
+    }
+    // Two phases: validation happens before the first byte is written, so a
+    // rejected archive leaves neither a half-extracted tree nor a stray file
+    // above the workspace.
+    expect(exists(artifactPath("out"))).toBe(false);
+    expect(exists(path.join(workspace, "..", "escaped.txt"))).toBe(false);
+  });
+
+  it("refuses absolute entry names, drive letters and backslash separators", async () => {
+    const cases: Readonly<Record<string, RegExp>> = {
+      "/etc/passwd": /不安全/,
+      "\\etc\\passwd": /不安全/,
+      "C:/Windows/system32/etc/hosts": /不安全/,
+      "C:x": /不安全/,
+    };
+    for (const [name, message] of Object.entries(cases)) {
+      writeArtifact("absolute.zip", craftZip([{ name, content: "pwned" }]));
+      await expect(
+        extractWorkspaceArchiveDirectory({ workspaceDir: workspace, path: "absolute.zip", destination: "out" }),
+      ).rejects.toThrow(message);
+    }
+    expect(exists(artifactPath("out"))).toBe(false);
+  });
+
+  it("refuses a symlink rather than materialising one", async () => {
+    // A symlink written into a workspace is a write primitive pointing wherever
+    // the archive wants, so it is refused instead of created.
+    const source = writeTree("link-src", { "inner.txt": "hello" });
+    symlinkSync("inner.txt", path.join(source, "link.txt"));
+    if (HAS_ZIP) {
+      // `-y` stores the link itself rather than the file it points at.
+      execFileSync("zip", ["-q", "-y", artifactPath("linky.zip"), "link.txt"], { cwd: source });
+      await expect(
+        extractWorkspaceArchiveDirectory({ workspaceDir: workspace, path: "linky.zip", destination: "out" }),
+      ).rejects.toThrow(/符号链接/);
+    }
+    if (HAS_TAR) {
+      realTarLink("linky.tar", source, "link.txt");
+      await expect(
+        extractWorkspaceArchiveDirectory({ workspaceDir: workspace, path: "linky.tar", destination: "out" }),
+      ).rejects.toThrow(/符号链接/);
+    }
+    // And against a hand-built zip, so the refusal does not depend on a CLI.
+    writeArtifact("craft-link.zip", craftZip([{ name: "link.txt", content: "/etc/passwd", mode: 0o120777 }]));
+    await expect(
+      extractWorkspaceArchiveDirectory({ workspaceDir: workspace, path: "craft-link.zip", destination: "out" }),
+    ).rejects.toThrow(/符号链接/);
+    expect(exists(artifactPath("out"))).toBe(false);
+  });
+
+  it("refuses a declared-size lie: a huge declared total, and an absurd expansion ratio", async () => {
+    // The header claims a gigabyte of expansion for a two-byte member. The
+    // pre-flight sums the declared sizes, so nothing is inflated at all.
+    writeArtifact(
+      "lie-total.zip",
+      craftZip([{ name: "a.txt", content: "hi", declaredUncompressedSize: 1024 * 1024 * 1024 }]),
+    );
+    await expect(
+      extractWorkspaceArchiveDirectory({ workspaceDir: workspace, path: "lie-total.zip", destination: "out" }),
+    ).rejects.toThrow(/声明的展开后体积过大/);
+
+    // Here the declared total is 1 byte while the real payload is a megabyte,
+    // and the compressed size is claimed as 1 byte as well, so the declared
+    // pre-flight has nothing to catch. Deflate cannot do better than about
+    // 1032:1, so a member claiming to have compressed a megabyte into a byte is
+    // a lie either way it is caught: a reader that trusts the declared
+    // compressed size slices a one-byte stream and fails to inflate it, and one
+    // that inflates first measures 1 MiB against 1 byte and trips the ratio.
+    // Either outcome is a refusal, and the point of the test is the refusal.
+    writeArtifact(
+      "lie-ratio.zip",
+      craftZip([
+        { name: "bomb.bin", content: Buffer.alloc(1024 * 1024), declaredUncompressedSize: 1, declaredCompressedSize: 1 },
+      ]),
+    );
+    await expect(
+      extractWorkspaceArchiveDirectory({ workspaceDir: workspace, path: "lie-ratio.zip", destination: "out" }),
+    ).rejects.toThrow(/异常膨胀|ZIP 条目已损坏/);
+    // Names and the declared total are refused before the destination is even
+    // created; a byte-level failure (a corrupt stream, an expansion blow-up, a
+    // file that already exists) is discovered mid-write, so what must not
+    // survive it is a written *file*.
+    expect(writtenFiles(artifactPath("out"))).toEqual([]);
+  });
+
+  it("refuses a destination outside the workspace, and creates nothing", async () => {
+    writeArtifact("small.zip", craftZip([{ name: "a.txt", content: "hello" }]));
+    await expect(
+      extractWorkspaceArchiveDirectory({ workspaceDir: workspace, path: "small.zip", destination: "../escape" }),
+    ).rejects.toThrow(/越界/);
+    await expect(
+      extractWorkspaceArchiveDirectory({ workspaceDir: workspace, path: "small.zip", destination: "/tmp/webui-escape" }),
+    ).rejects.toThrow(/越界/);
+    expect(exists(path.join(workspace, "..", "escape"))).toBe(false);
+  });
+
+  it("refuses to overwrite a file that is already in the destination", async () => {
+    writeArtifact("clash.zip", craftZip([{ name: "a.txt", content: "from archive" }]));
+    mkdirSync(artifactPath("clash-out"), { recursive: true });
+    writeArtifact("clash-out/a.txt", "already mine");
+    // An archive the user did not write must never be able to overwrite a file
+    // already in their workspace.
+    await expect(
+      extractWorkspaceArchiveDirectory({ workspaceDir: workspace, path: "clash.zip", destination: "clash-out" }),
+    ).rejects.toThrow(/EEXIST|file already exists/iu);
+    expect(readArtifact("clash-out/a.txt")).toBe("already mine");
+  });
+
+  it.skipIf(!HAS_ZIP)("extracts a whole archive when no prefix is given", async () => {
+    realZip("whole.zip", { "one.txt": "1", "two/deep.txt": "2" });
+    const result = await extractWorkspaceArchiveDirectory({
+      workspaceDir: workspace,
+      path: "whole.zip",
+      destination: "whole-out",
+    });
+    expect(result.writtenFiles).toBe(2);
+    expect(readArtifact("whole-out/one.txt")).toBe("1");
+    expect(readArtifact("whole-out/two/deep.txt")).toBe("2");
+  });
+});
+
+/** A tar containing a symlink, via the CLI (`tar` records typeflag `2`). */
+function realTarLink(name: string, source: string, member: string): string {
+  execFileSync("tar", ["cf", artifactPath(name), member], { cwd: source, env: FIXTURE_ENV });
+  return artifactPath(name);
+}
+
+// ---------------------------------------------------------------------------
+// Server: the port projection
+// ---------------------------------------------------------------------------
+
+describe("harness port archive members", () => {
+  it("serves both operations from this package when the runtime has neither", async () => {
+    writeArtifact("port.zip", craftZip([{ name: "a/b.txt", content: "hello" }]));
+    // A host whose cliService predates the archive capability. Before this
+    // change the two port members threw "压缩包浏览能力尚未接入。" right here.
+    const port = createHarnessPortFromHost({
+      appVersion: "archive-test",
+      cliService: {} as unknown as WebuiRuntimeCliService,
+    });
+    const listing = await port.readWorkspaceArchive({ workspaceDir: workspace, path: "port.zip" });
+    expect(listing.entries.map((entry) => entry.name)).toEqual(["a"]);
+    const result = await port.extractWorkspaceArchive({
+      workspaceDir: workspace,
+      path: "port.zip",
+      destination: "port-out",
+    });
+    expect(result.writtenFiles).toBe(1);
+    // No prefix: the archive's own layout is preserved under the destination.
+    expect(readArtifact("port-out/a/b.txt")).toBe("hello");
+  });
+
+  it("prefers a runtime implementation when the host provides one", async () => {
+    const port = createHarnessPortFromHost({
+      appVersion: "archive-test",
+      cliService: {
+        async readWorkspaceArchive() {
+          return { archivePath: "from-runtime.zip", entries: [], totalEntries: 0, truncated: false };
+        },
+      } as unknown as WebuiRuntimeCliService,
+    });
+    const listing = await port.readWorkspaceArchive({ workspaceDir: workspace, path: "port.zip" });
+    expect(listing.archivePath).toBe("from-runtime.zip");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Client: the view
+// ---------------------------------------------------------------------------
+
+const READY_LISTING = {
+  archivePath: "dist/bundle.zip",
+  entries: [
+    { path: "src", name: "src", isDirectory: true },
+    { path: "readme.md", name: "readme.md", isDirectory: false, size: 2048 },
+    { path: "empty.log", name: "empty.log", isDirectory: false, size: 0 },
+  ],
+  totalEntries: 3,
+  truncated: false,
+};
+
+function renderListing(overrides: Record<string, unknown> = {}): string {
+  return renderToStaticMarkup(
+    createElement(WorkspaceArchiveListing, {
+      archivePath: READY_LISTING.archivePath,
+      prefix: "",
+      destination: "dist/bundle",
+      entries: READY_LISTING.entries,
+      totalEntries: READY_LISTING.totalEntries,
+      truncated: false,
+      extractState: { status: "idle" },
+      ...overrides,
+    } as never),
+  );
+}
+
+describe("workspace archive view", () => {
+  it("paints the loading state on first render, before any effect has run", () => {
+    const markup = renderToStaticMarkup(
+      createElement(WorkspaceArchiveView, {
+        workspaceDir: "/repo",
+        path: "dist/bundle.zip",
+        // A listing that never settles. Static rendering does not run the
+        // effect, so this is the state a reader actually sees first.
+        readWorkspaceArchive: () => new Promise(() => undefined),
+      }),
+    );
+    expect(markup).toContain('role="status"');
+    expect(markup).toContain("正在读取压缩包");
+  });
+
+  it("says so when the service exposes no archive capability", () => {
+    const markup = renderToStaticMarkup(
+      createElement(WorkspaceArchiveView, { workspaceDir: "/repo", path: "dist/bundle.zip" }),
+    );
+    expect(markup).toContain("没有提供压缩包浏览能力");
+  });
+
+  it("names each entry with its size and a directory marker", () => {
+    const markup = renderListing();
+    expect(markup).toContain("src（目录）");
+    expect(markup).toContain('data-testid="workspace-archive-directory"');
+    expect(markup).toContain("readme.md");
+    // 2 KB rather than 2048 B, and the zero-byte member is still 0 B instead of
+    // losing its size to a falsy check.
+    expect(markup).toContain("2.0 KB");
+    expect(markup).toContain("0 B");
+    expect(markup).toContain('data-testid="workspace-archive-size"');
+  });
+
+  it("distinguishes an empty level from a listing that has entries", () => {
+    const empty = renderListing({ entries: [], totalEntries: 0 });
+    expect(empty).toContain('data-testid="workspace-archive-empty"');
+    expect(empty).not.toContain('data-testid="workspace-archive-entries"');
+    expect(empty).not.toContain('data-testid="workspace-archive-truncated"');
+  });
+
+  it("shows a truncated listing as truncated instead of a complete one", () => {
+    const markup = renderListing({ truncated: true, totalEntries: 9_000 });
+    expect(markup).toContain('data-testid="workspace-archive-truncated"');
+    expect(markup).toContain("共 9000 项");
+    expect(markup).toContain("只显示了 3 项");
+    // The rows are still there; the banner is what makes the limit legible.
+    expect(markup).toContain('data-testid="workspace-archive-entries"');
+  });
+
+  it("offers the destination instead of a field the browser could type into", () => {
+    const markup = renderListing();
+    expect(markup).toContain('data-testid="workspace-archive-destination"');
+    expect(markup).toContain("dist/bundle");
+    expect(markup).toContain('data-testid="workspace-archive-extract"');
+    expect(markup).not.toContain("<input");
+    // No destination means no usable extract control rather than one pointed at "".
+    const unusable = renderListing({ destination: "" });
+    expect(unusable).toContain("没有可用的解压目标");
+    expect(unusable).toContain('disabled=""');
+  });
+
+  it("only offers the way back up once inside a directory", () => {
+    expect(renderListing()).not.toContain('data-testid="workspace-archive-up"');
+    const nested = renderListing({ prefix: "src" });
+    expect(nested).toContain('data-testid="workspace-archive-up"');
+    expect(nested).toContain("bundle.zip › src");
+  });
+
+  it("reports an extraction result and an extraction failure differently", () => {
+    const done = renderListing({
+      extractState: {
+        status: "done",
+        result: { archivePath: "dist/bundle.zip", destination: "dist/bundle", writtenFiles: 3 },
+      },
+    });
+    expect(done).toContain('data-testid="workspace-archive-extract-result"');
+    expect(done).toContain("已解压 3 个文件");
+
+    const partial = renderListing({
+      extractState: {
+        status: "done",
+        result: { archivePath: "dist/bundle.zip", destination: "dist/bundle", writtenFiles: 3, truncated: true },
+      },
+    });
+    expect(partial).toContain("仅解压了前一部分");
+
+    const failed = renderListing({ extractState: { status: "error", error: "压缩包中存在不安全的条目" } });
+    expect(failed).toContain('role="alert"');
+    expect(failed).toContain("不安全");
+
+    const running = renderListing({ extractState: { status: "running" } });
+    expect(running).toContain("正在解压");
+    expect(running).toContain('disabled=""');
+  });
+
+  it("separates a failure from a state that was never available", () => {
+    const notice = renderToStaticMarkup(createElement(WorkspaceArchiveNotice, { reason: "正在读取压缩包…" }));
+    expect(notice).toContain('role="status"');
+    expect(notice).not.toContain('role="alert"');
+    const failure = renderToStaticMarkup(
+      createElement(WorkspaceArchiveNotice, { reason: "这不是可识别的 ZIP 压缩包", role: "alert" }),
+    );
+    expect(failure).toContain('role="alert"');
+  });
+
+  it("derives a workspace-relative destination from the archive path", () => {
+    expect(archiveDestinationFor("dist/bundle.zip")).toBe("dist/bundle");
+    expect(archiveDestinationFor("bundle.tgz")).toBe("bundle");
+    expect(archiveDestinationFor("dist/bundle.tar.gz")).toBe("dist/bundle");
+    // Anything that would need re-validating to be safe is refused outright.
+    expect(archiveDestinationFor("../evil.zip")).toBe("");
+    expect(archiveDestinationFor("/etc/bundle.zip")).toBe("");
+    expect(archiveDestinationFor("")).toBe("");
+  });
+
+  it("formats sizes in the units the listing shows them in", () => {
+    expect(formatArchiveSize(0)).toBe("0 B");
+    expect(formatArchiveSize(999)).toBe("999 B");
+    expect(formatArchiveSize(1024)).toBe("1.0 KB");
+    expect(formatArchiveSize(1024 * 1024 * 3)).toBe("3.0 MB");
+    expect(formatArchiveSize(1024 ** 4)).toBe("1.0 TB");
+  });
+});
diff --git a/test/vitest-suites.json b/test/vitest-suites.json
index add100ec5..ed0d39b95 100644
--- a/test/vitest-suites.json
+++ b/test/vitest-suites.json
@@ -273,7 +273,8 @@
       "packages/webui/test/unit/webui-workspace-media-preview.test.tsx",
       "packages/webui/test/unit/webui-workspace-file-tree.test.tsx",
       "packages/webui/test/unit/webui-workspace-html-preview.test.tsx",
-      "packages/webui/test/unit/webui-workspace-canvas.test.tsx"
+      "packages/webui/test/unit/webui-workspace-canvas.test.tsx",
+      "packages/webui/test/unit/webui-workspace-archive.test.ts"
     ]
   }
 }

From 340d8c725f10f279409e0a4d1a491a97bc07c048 Mon Sep 17 00:00:00 2001
From: probe <probe@local>
Date: Sun, 4 Oct 2026 09:07:19 +0800
Subject: [PATCH 19/21] fix(webui): keep a scoped extraction from skipping the
 refusal

Scoping an extraction to a prefix filtered out the entries the reader had
refused, because those carry no path. Extracting a subdirectory therefore
skipped a hostile entry elsewhere in the archive that extracting the whole
archive refuses -- an inconsistency in exactly the direction that matters.
Refused entries are now selected whatever the prefix, so the pre-flight
refuses the operation either way, and the case is pinned by a test.
---
 .../webui/src/server/workspace-archive.ts     |  8 ++++++-
 .../test/unit/webui-workspace-archive.test.ts | 23 +++++++++++++++++++
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/packages/webui/src/server/workspace-archive.ts b/packages/webui/src/server/workspace-archive.ts
index 3727174b7..061dbdf42 100644
--- a/packages/webui/src/server/workspace-archive.ts
+++ b/packages/webui/src/server/workspace-archive.ts
@@ -876,7 +876,13 @@ function listOneLevel(
 function selectForExtraction(contents: ArchiveContents, prefix: string): readonly ArchiveEntry[] {
   if (!prefix) return contents.entries;
   const scope = `${prefix}/`;
-  return contents.entries.filter((entry) => entry.path === prefix || entry.path.startsWith(scope));
+  // An entry with no path is one the reader refused, and it is selected
+  // regardless of the prefix so the pre-flight refuses the whole archive for it.
+  // Scoping it away would make extracting a subdirectory quietly skip a hostile
+  // entry that extracting the root refuses.
+  return contents.entries.filter(
+    (entry) => entry.path === undefined || entry.path === prefix || entry.path.startsWith(scope),
+  );
 }
 
 /**
diff --git a/packages/webui/test/unit/webui-workspace-archive.test.ts b/packages/webui/test/unit/webui-workspace-archive.test.ts
index 22d37e27b..ddf350e87 100644
--- a/packages/webui/test/unit/webui-workspace-archive.test.ts
+++ b/packages/webui/test/unit/webui-workspace-archive.test.ts
@@ -401,6 +401,29 @@ describe("workspace archive extraction", () => {
     expect(exists(path.join(workspace, "..", "escaped.txt"))).toBe(false);
   });
 
+  it("refuses a hostile entry elsewhere in the archive even when a prefix is scoped", async () => {
+    // Scoping the extraction must not become a way to skip a check: a hostile
+    // entry outside the selected directory still refuses the whole operation,
+    // the same as it does when the archive is extracted whole.
+    writeArtifact(
+      "scoped-slip.zip",
+      craftZip([
+        { name: "sub/fine.txt", content: "fine" },
+        { name: "../escaped.txt", content: "pwned" },
+      ]),
+    );
+    await expect(
+      extractWorkspaceArchiveDirectory({
+        workspaceDir: workspace,
+        path: "scoped-slip.zip",
+        destination: "scoped-out",
+        prefix: "sub",
+      }),
+    ).rejects.toThrow(/不安全|越界/);
+    expect(exists(artifactPath("scoped-out"))).toBe(false);
+    expect(exists(path.join(workspace, "..", "escaped.txt"))).toBe(false);
+  });
+
   it("refuses absolute entry names, drive letters and backslash separators", async () => {
     const cases: Readonly<Record<string, RegExp>> = {
       "/etc/passwd": /不安全/,

From ecf0b337ee7a054dc5feb82621176e2831c3547b Mon Sep 17 00:00:00 2001
From: probe <probe@local>
Date: Sun, 4 Oct 2026 09:10:20 +0800
Subject: [PATCH 20/21] chore(source): register the workspace archive reader
 module

---
 release/public-source.json | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/release/public-source.json b/release/public-source.json
index ae72885ed..cd9108a89 100644
--- a/release/public-source.json
+++ b/release/public-source.json
@@ -3634,6 +3634,7 @@
     "packages/webui/src/server/service.ts",
     "packages/webui/src/server/terminal.ts",
     "packages/webui/src/server/usage-quota.ts",
+    "packages/webui/src/server/workspace-archive.ts",
     "packages/webui/src/shared/placeholder.ts",
     "packages/webui/src/shared/plugin-management.ts",
     "packages/webui/tailwind.config.cjs",
@@ -3687,6 +3688,11 @@
     "packages/webui/test/unit/webui-w0-ssr-fixtures.test.tsx",
     "packages/webui/test/unit/webui-w0-store-sequence.test.ts",
     "packages/webui/test/unit/webui-w2-effect-reducer.test.ts",
+    "packages/webui/test/unit/webui-workspace-archive.test.ts",
+    "packages/webui/test/unit/webui-workspace-canvas.test.tsx",
+    "packages/webui/test/unit/webui-workspace-file-tree.test.tsx",
+    "packages/webui/test/unit/webui-workspace-html-preview.test.tsx",
+    "packages/webui/test/unit/webui-workspace-media-preview.test.tsx",
     "packages/webui/test/unit/workspace-panel-state.test.ts",
     "packages/webui/tsconfig.client.json",
     "packages/webui/tsconfig.json",

From 1d199b86e0989da060156a6ec5956e57b41e4f83 Mon Sep 17 00:00:00 2001
From: probe <probe@local>
Date: Sun, 4 Oct 2026 09:10:27 +0800
Subject: [PATCH 21/21] feat(webui): route the archive operations over the wire
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The port members and the transport methods existed, and `host.ts` implemented
them, but no operation was registered for either name — so a panel call came
back `unknown_operation`. The seam was half-built in a way that typechecking
cannot see, which is why it survived the earlier rounds.

Both operations validate the same way their siblings do: a non-empty
`workspaceDir` and `path`, and `prefix` as a non-empty string when present.
The extraction's `destination` is checked here as the first gate rather than
only inside the runtime, because a browser cannot name an absolute path, so a
destination the client supplied verbatim is the one unvalidated link in the
chain. The runtime re-validates regardless; this is the earlier gate, not a
replacement.

56 files / 1077 tests pass; typecheck:server, typecheck:client and
typecheck:test clean.
---
 packages/webui/src/server/operation/names.ts  |  2 +
 .../server/operation/operation-handlers.ts    |  8 +++
 .../webui/src/server/operation/operations.ts  |  6 +-
 .../webui/src/server/operation/workspace.ts   | 67 ++++++++++++++++++-
 packages/webui/src/server/service.ts          |  2 +
 5 files changed, 80 insertions(+), 5 deletions(-)

diff --git a/packages/webui/src/server/operation/names.ts b/packages/webui/src/server/operation/names.ts
index 32960feb0..af111ec1b 100644
--- a/packages/webui/src/server/operation/names.ts
+++ b/packages/webui/src/server/operation/names.ts
@@ -29,6 +29,8 @@ export const GET_WORKSPACE_REVIEW_FILE_CONTENT_OPERATION_NAME = "getWorkspaceRev
 export const SEARCH_WORKSPACE_REVIEW_DIFFS_OPERATION_NAME = "searchWorkspaceReviewDiffs" as const;
 export const READ_CANVAS_OPERATION_NAME = "readCanvas" as const;
 export const APPLY_CANVAS_OPERATION_NAME = "applyCanvas" as const;
+export const READ_WORKSPACE_ARCHIVE_OPERATION_NAME = "readWorkspaceArchive" as const;
+export const EXTRACT_WORKSPACE_ARCHIVE_OPERATION_NAME = "extractWorkspaceArchive" as const;
 export const CREATE_TERMINAL_OPERATION_NAME = "createTerminal" as const;
 export const LIST_TERMINALS_OPERATION_NAME = "listTerminals" as const;
 export const WRITE_TERMINAL_OPERATION_NAME = "writeTerminal" as const;
diff --git a/packages/webui/src/server/operation/operation-handlers.ts b/packages/webui/src/server/operation/operation-handlers.ts
index 783cfcc7a..ed845f1da 100644
--- a/packages/webui/src/server/operation/operation-handlers.ts
+++ b/packages/webui/src/server/operation/operation-handlers.ts
@@ -61,6 +61,8 @@ export type WebuiOperationPort = Pick<
   | "searchWorkspaceReviewDiffs"
   | "readCanvas"
   | "applyCanvas"
+  | "readWorkspaceArchive"
+  | "extractWorkspaceArchive"
   | "sendMessage"
   | "enqueueMessage"
   | "resumeSession"
@@ -140,6 +142,12 @@ export function createOperationHandlers(
     applyCanvas: async (_context, body) => ({
       body: await port.applyCanvas(body),
     }),
+    readWorkspaceArchive: async (_context, body) => ({
+      body: await port.readWorkspaceArchive(body),
+    }),
+    extractWorkspaceArchive: async (_context, body) => ({
+      body: await port.extractWorkspaceArchive(body),
+    }),
     getWorkspaceEnvironment: async (_context, body) => ({
       body: await port.getWorkspaceEnvironment(body),
     }),
diff --git a/packages/webui/src/server/operation/operations.ts b/packages/webui/src/server/operation/operations.ts
index 26d439d7d..5679d2e17 100644
--- a/packages/webui/src/server/operation/operations.ts
+++ b/packages/webui/src/server/operation/operations.ts
@@ -1,5 +1,5 @@
 import { versionOperation, listSessionsOperation, listVisibleProjectsOperation, getSessionTreeOperation, createSessionOperation, getSessionOperation, getActiveTurnOperation } from "./session.js";
-import { listWorkspaceFileTreeOperation, browseWorkspaceDirsOperation, readWorkspaceFileOperation, getWorkspaceEnvironmentOperation, mutateWorkspaceGitOperation, getWorkspaceReviewSummaryOperation, listWorkspaceReviewFileDiffsOperation, getWorkspaceReviewFileContentOperation, searchWorkspaceReviewDiffsOperation, readCanvasOperation, applyCanvasOperation, createTerminalOperation, listTerminalsOperation, writeTerminalOperation, resizeTerminalOperation, disposeTerminalOperation, watchTerminalOperation } from "./workspace.js";
+import { listWorkspaceFileTreeOperation, browseWorkspaceDirsOperation, readWorkspaceFileOperation, getWorkspaceEnvironmentOperation, mutateWorkspaceGitOperation, getWorkspaceReviewSummaryOperation, listWorkspaceReviewFileDiffsOperation, getWorkspaceReviewFileContentOperation, searchWorkspaceReviewDiffsOperation, readCanvasOperation, applyCanvasOperation, readWorkspaceArchiveOperation, extractWorkspaceArchiveOperation, createTerminalOperation, listTerminalsOperation, writeTerminalOperation, resizeTerminalOperation, disposeTerminalOperation, watchTerminalOperation } from "./workspace.js";
 import { getMessagesOperation, getSessionDiffOperation, getTurnDiffOperation, revertTurnDiffOperation, reapplyTurnDiffOperation, getSessionRewindPreviewOperation, rewindSessionOperation, editSessionMessageOperation } from "./messages.js";
 import { isGoalEnabledOperation, getGoalOperation, createGoalOperation, patchGoalOperation, clearGoalOperation } from "./goal.js";
 import { sendMessageOperation, enqueueMessageOperation, resumeSessionOperation } from "./interaction.js";
@@ -9,7 +9,7 @@ import { pluginManagementOperation } from "./plugin-management.js";
 import { getPermissionModeOperation, setPermissionModeOperation } from "./permission-mode.js";
 import { archiveSessionOperation, deleteSessionOperation, updateSessionOperation, getSessionForkOptionsOperation, forkSessionOperation, listUserModelProvidersOperation, createUserModelProviderOperation, updateUserModelProviderOperation, deleteUserModelProviderOperation, testUserModelProviderOperation, testUserModelOperation, discoverUserModelsCandidateOperation, saveUserModelProviderCandidateOperation, listProviderPresetsOperation, getMiniMaxApiKeyStatusOperation, upsertMiniMaxApiKeyOperation, getCodexOAuthStatusOperation, getMiniMaxModelSourceOperation, setMiniMaxModelSourceOperation, testUserModelCandidateOperation, revealModelProviderApiKeyOperation, startCodexOAuthLoginOperation, cancelCodexOAuthLoginOperation, refreshModelsOperation, runCommandOperation, getSigninPanelOperation, claimSigninOperation, signOutOperation } from "./provider.js";
 export { versionOperation, listSessionsOperation, listVisibleProjectsOperation, getSessionTreeOperation, createSessionOperation, getSessionOperation, getActiveTurnOperation } from "./session.js";
-export { listWorkspaceFileTreeOperation, browseWorkspaceDirsOperation, readWorkspaceFileOperation, getWorkspaceEnvironmentOperation, mutateWorkspaceGitOperation, getWorkspaceReviewSummaryOperation, listWorkspaceReviewFileDiffsOperation, getWorkspaceReviewFileContentOperation, searchWorkspaceReviewDiffsOperation, readCanvasOperation, applyCanvasOperation, createTerminalOperation, listTerminalsOperation, writeTerminalOperation, resizeTerminalOperation, disposeTerminalOperation, watchTerminalOperation } from "./workspace.js";
+export { listWorkspaceFileTreeOperation, browseWorkspaceDirsOperation, readWorkspaceFileOperation, getWorkspaceEnvironmentOperation, mutateWorkspaceGitOperation, getWorkspaceReviewSummaryOperation, listWorkspaceReviewFileDiffsOperation, getWorkspaceReviewFileContentOperation, searchWorkspaceReviewDiffsOperation, readCanvasOperation, applyCanvasOperation, readWorkspaceArchiveOperation, extractWorkspaceArchiveOperation, createTerminalOperation, listTerminalsOperation, writeTerminalOperation, resizeTerminalOperation, disposeTerminalOperation, watchTerminalOperation } from "./workspace.js";
 export { getMessagesOperation, getSessionDiffOperation, getTurnDiffOperation, revertTurnDiffOperation, reapplyTurnDiffOperation, getSessionRewindPreviewOperation, rewindSessionOperation, editSessionMessageOperation } from "./messages.js";
 export { isGoalEnabledOperation, getGoalOperation, createGoalOperation, patchGoalOperation, clearGoalOperation } from "./goal.js";
 export { sendMessageOperation, enqueueMessageOperation, resumeSessionOperation } from "./interaction.js";
@@ -48,6 +48,8 @@ export function createOperationRegistry(
   registerOperation(registry, { operation: readWorkspaceFileOperation, handle: handlers.readWorkspaceFile });
   registerOperation(registry, { operation: readCanvasOperation, handle: handlers.readCanvas });
   registerOperation(registry, { operation: applyCanvasOperation, handle: handlers.applyCanvas });
+  registerOperation(registry, { operation: readWorkspaceArchiveOperation, handle: handlers.readWorkspaceArchive });
+  registerOperation(registry, { operation: extractWorkspaceArchiveOperation, handle: handlers.extractWorkspaceArchive });
   registerOperation(registry, { operation: getWorkspaceEnvironmentOperation, handle: handlers.getWorkspaceEnvironment });
   registerOperation(registry, { operation: mutateWorkspaceGitOperation, handle: handlers.mutateWorkspaceGit });
   registerOperation(registry, { operation: getWorkspaceReviewSummaryOperation, handle: handlers.getWorkspaceReviewSummary });
diff --git a/packages/webui/src/server/operation/workspace.ts b/packages/webui/src/server/operation/workspace.ts
index 764d9dbd4..04aa24f5c 100644
--- a/packages/webui/src/server/operation/workspace.ts
+++ b/packages/webui/src/server/operation/workspace.ts
@@ -6,6 +6,8 @@ import type { WebuiOperation, WebuiOperationValidation } from "./operation-contr
 import { invalidBody } from "./operation-contract.js";
 import type {
   WebuiCanvasDocument,
+  WebuiWorkspaceArchiveListing,
+  WebuiWorkspaceArchiveExtractResult,
   WebuiWorkspaceDirectoryListing,
   WebuiWorkspaceEnvironment,
   WebuiWorkspaceFile,
@@ -21,7 +23,7 @@ import {
   validateObjectBody,
   validateOptionalObjectBody,
 } from "./common.js";
-import { LIST_WORKSPACE_FILE_TREE_OPERATION_NAME, BROWSE_WORKSPACE_DIRS_OPERATION_NAME, READ_WORKSPACE_FILE_OPERATION_NAME, GET_WORKSPACE_ENVIRONMENT_OPERATION_NAME, MUTATE_WORKSPACE_GIT_OPERATION_NAME, GET_WORKSPACE_REVIEW_SUMMARY_OPERATION_NAME, LIST_WORKSPACE_REVIEW_FILE_DIFFS_OPERATION_NAME, GET_WORKSPACE_REVIEW_FILE_CONTENT_OPERATION_NAME, SEARCH_WORKSPACE_REVIEW_DIFFS_OPERATION_NAME, READ_CANVAS_OPERATION_NAME, APPLY_CANVAS_OPERATION_NAME, CREATE_TERMINAL_OPERATION_NAME, LIST_TERMINALS_OPERATION_NAME, WRITE_TERMINAL_OPERATION_NAME, RESIZE_TERMINAL_OPERATION_NAME, DISPOSE_TERMINAL_OPERATION_NAME, WATCH_TERMINAL_OPERATION_NAME } from "./names.js";
+import { LIST_WORKSPACE_FILE_TREE_OPERATION_NAME, BROWSE_WORKSPACE_DIRS_OPERATION_NAME, READ_WORKSPACE_FILE_OPERATION_NAME, GET_WORKSPACE_ENVIRONMENT_OPERATION_NAME, MUTATE_WORKSPACE_GIT_OPERATION_NAME, GET_WORKSPACE_REVIEW_SUMMARY_OPERATION_NAME, LIST_WORKSPACE_REVIEW_FILE_DIFFS_OPERATION_NAME, GET_WORKSPACE_REVIEW_FILE_CONTENT_OPERATION_NAME, SEARCH_WORKSPACE_REVIEW_DIFFS_OPERATION_NAME, READ_CANVAS_OPERATION_NAME, APPLY_CANVAS_OPERATION_NAME, READ_WORKSPACE_ARCHIVE_OPERATION_NAME, EXTRACT_WORKSPACE_ARCHIVE_OPERATION_NAME, CREATE_TERMINAL_OPERATION_NAME, LIST_TERMINALS_OPERATION_NAME, WRITE_TERMINAL_OPERATION_NAME, RESIZE_TERMINAL_OPERATION_NAME, DISPOSE_TERMINAL_OPERATION_NAME, WATCH_TERMINAL_OPERATION_NAME } from "./names.js";
 
 /** Upper bound on one directory listing. A home directory can hold
  *  thousands of folders and the picker only needs a browsable page. */
@@ -49,6 +51,17 @@ interface ApplyCanvasBody {
   readonly sessionId: string;
   readonly operation: Record<string, unknown>;
 }
+interface ReadWorkspaceArchiveBody {
+  readonly workspaceDir: string;
+  readonly path: string;
+  readonly prefix?: string;
+}
+interface ExtractWorkspaceArchiveBody {
+  readonly workspaceDir: string;
+  readonly path: string;
+  readonly destination: string;
+  readonly prefix?: string;
+}
 
 export const listWorkspaceFileTreeOperation: WebuiOperation<ListWorkspaceFileTreeBody, readonly WebuiWorkspaceFile[]> = {
   name: LIST_WORKSPACE_FILE_TREE_OPERATION_NAME,
@@ -234,8 +247,56 @@ export const applyCanvasOperation: WebuiOperation<ApplyCanvasBody, { readonly op
     };
   },
 };
-export const createTerminalOperation: WebuiOperation<Record<string, unknown>> = { name: CREATE_TERMINAL_OPERATION_NAME, validate: (body) => validateObjectBody(CREATE_TERMINAL_OPERATION_NAME, body) };
-export const listTerminalsOperation: WebuiOperation<Record<string, never>> = { name: LIST_TERMINALS_OPERATION_NAME, validate: (body) => body && typeof body === "object" && !Array.isArray(body) && Object.keys(body).length === 0 ? { ok: true, body: {} } : { ok: false, code: WebuiErrorCode.invalidBody, message: "listTerminals body must be an empty object" } };
+export const readWorkspaceArchiveOperation: WebuiOperation<ReadWorkspaceArchiveBody, WebuiWorkspaceArchiveListing> = {
+  name: READ_WORKSPACE_ARCHIVE_OPERATION_NAME,
+  validate: (body): WebuiOperationValidation<ReadWorkspaceArchiveBody> => {
+    const result = validateObjectBody(READ_WORKSPACE_ARCHIVE_OPERATION_NAME, body);
+    if (!result.ok) return result;
+    if (typeof result.body.workspaceDir !== "string" || !result.body.workspaceDir.trim())
+      return { ok: false, code: WebuiErrorCode.invalidBody, message: "workspaceDir is required" };
+    if (typeof result.body.path !== "string" || !result.body.path.trim())
+      return { ok: false, code: WebuiErrorCode.invalidBody, message: "path is required" };
+    if (result.body.prefix !== undefined && (typeof result.body.prefix !== "string" || !result.body.prefix.trim()))
+      return { ok: false, code: WebuiErrorCode.invalidBody, message: "prefix must be a non-empty string when present" };
+    return {
+      ok: true,
+      body: {
+        workspaceDir: result.body.workspaceDir,
+        path: result.body.path,
+        ...(typeof result.body.prefix === "string" ? { prefix: result.body.prefix } : {}),
+      },
+    };
+  },
+};
+export const extractWorkspaceArchiveOperation: WebuiOperation<ExtractWorkspaceArchiveBody, WebuiWorkspaceArchiveExtractResult> = {
+  name: EXTRACT_WORKSPACE_ARCHIVE_OPERATION_NAME,
+  validate: (body): WebuiOperationValidation<ExtractWorkspaceArchiveBody> => {
+    const result = validateObjectBody(EXTRACT_WORKSPACE_ARCHIVE_OPERATION_NAME, body);
+    if (!result.ok) return result;
+    if (typeof result.body.workspaceDir !== "string" || !result.body.workspaceDir.trim())
+      return { ok: false, code: WebuiErrorCode.invalidBody, message: "workspaceDir is required" };
+    if (typeof result.body.path !== "string" || !result.body.path.trim())
+      return { ok: false, code: WebuiErrorCode.invalidBody, message: "path is required" };
+    // Rejected here, before the runtime sees it: a browser cannot name an
+    // absolute path, so a destination the client supplied verbatim would be
+    // the one unvalidated path in the chain. The runtime re-validates
+    // anyway — this is the first gate, not the only one.
+    if (typeof result.body.destination !== "string" || !result.body.destination.trim())
+      return { ok: false, code: WebuiErrorCode.invalidBody, message: "destination is required" };
+    if (result.body.prefix !== undefined && (typeof result.body.prefix !== "string" || !result.body.prefix.trim()))
+      return { ok: false, code: WebuiErrorCode.invalidBody, message: "prefix must be a non-empty string when present" };
+    return {
+      ok: true,
+      body: {
+        workspaceDir: result.body.workspaceDir,
+        path: result.body.path,
+        destination: result.body.destination,
+        ...(typeof result.body.prefix === "string" ? { prefix: result.body.prefix } : {}),
+      },
+    };
+  },
+};
+export const createTerminalOperation: WebuiOperation<Record<string, unknown>> = { name: CREATE_TERMINAL_OPERATION_NAME, validate: (body) => validateObjectBody(CREATE_TERMINAL_OPERATION_NAME, body) };export const listTerminalsOperation: WebuiOperation<Record<string, never>> = { name: LIST_TERMINALS_OPERATION_NAME, validate: (body) => body && typeof body === "object" && !Array.isArray(body) && Object.keys(body).length === 0 ? { ok: true, body: {} } : { ok: false, code: WebuiErrorCode.invalidBody, message: "listTerminals body must be an empty object" } };
 export const writeTerminalOperation: WebuiOperation<Record<string, unknown>> = { name: WRITE_TERMINAL_OPERATION_NAME, validate: (body) => validateObjectBody(WRITE_TERMINAL_OPERATION_NAME, body) };
 export const resizeTerminalOperation: WebuiOperation<Record<string, unknown>> = { name: RESIZE_TERMINAL_OPERATION_NAME, validate: (body) => validateObjectBody(RESIZE_TERMINAL_OPERATION_NAME, body) };
 export const disposeTerminalOperation: WebuiOperation<Record<string, unknown>> = { name: DISPOSE_TERMINAL_OPERATION_NAME, validate: (body) => validateObjectBody(DISPOSE_TERMINAL_OPERATION_NAME, body) };
diff --git a/packages/webui/src/server/service.ts b/packages/webui/src/server/service.ts
index 3b80618b1..c35b0adaa 100644
--- a/packages/webui/src/server/service.ts
+++ b/packages/webui/src/server/service.ts
@@ -200,6 +200,8 @@ export class WebuiService {
       searchWorkspaceReviewDiffs: (request) => this.port.searchWorkspaceReviewDiffs(request),
       readCanvas: (request) => this.port.readCanvas(request),
       applyCanvas: (request) => this.port.applyCanvas(request),
+      readWorkspaceArchive: (request) => this.port.readWorkspaceArchive(request),
+      extractWorkspaceArchive: (request) => this.port.extractWorkspaceArchive(request),
       sendMessage: (request, signal) => this.port.sendMessage(request, signal),
       enqueueMessage: (request) => this.port.enqueueMessage(request),
       resumeSession: (request, signal) =>