@xiaobuyu/nodesign 0.0.1

package/server/api/board.js

@@ -0,0 +1,57 @@
+/**
+ * server/api/board.js — 工作台画布布局持久化（2026-07-27 分区版）
+ *
+ * GET   /api/projects/:pid/board  → shared/board.json（无则返回默认空布局）
+ * PATCH /api/projects/:pid/board  → diff 合并写（前端拖拽/建区只发脏条目；null=删）
+ * PUT   /api/projects/:pid/board  → 全量替换（保留给 reset 场景）
+ *
+ * 读写统一走 server/projects/board-store.js（带 per-project 写锁，
+ * 与 agent 侧 pin_to_board 工具共享，互不覆盖）。
+ */
+
+import express from 'express';
+import { validateProjectId, getProject } from '../projects/store.js';
+import { guardProject } from './_guard.js';
+import { readBoard, replaceBoard, patchBoard } from '../projects/board-store.js';
+
+const router = express.Router();
+
+function guard(req, res) {
+  // pid 校验 + 存在性 + 归属（2026-07-30 多用户）统一走 guardProject
+  return !!guardProject(req, res);
+}
+
+router.get('/:pid/board', async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    res.json({ board: await readBoard(req.params.pid) });
+  } catch (err) { next(err); }
+});
+
+router.patch('/:pid/board', express.json({ limit: '600kb' }), async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    const patch = req.body?.patch;
+    if (!patch || typeof patch !== 'object') return res.status(400).json({ error: 'patch required' });
+    const board = await patchBoard(req.params.pid, patch);
+    res.json({ ok: true, board });
+  } catch (err) {
+    if (err?.status === 400) return res.status(400).json({ error: err.message });
+    next(err);
+  }
+});
+
+router.put('/:pid/board', express.json({ limit: '600kb' }), async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    const body = req.body?.board;
+    if (!body || typeof body !== 'object') return res.status(400).json({ error: 'board required' });
+    const board = await replaceBoard(req.params.pid, body);
+    res.json({ ok: true, board });
+  } catch (err) {
+    if (err?.status === 400) return res.status(400).json({ error: err.message });
+    next(err);
+  }
+});
+
+export default router;

package/server/api/browse.js

@@ -0,0 +1,138 @@
+/**
+ * server/api/browse.js — 桌面上那张浏览器卡片背后的三个端点（2026-08-18）
+ *
+ * ## GET /api/projects/:pid/browse → { live, url, title, at, busy, help }
+ *
+ * 「现在是什么状况」。为什么需要：浏览器窗原来完全由一次性的
+ * `run.browser_opened` / `run.browser_help` 事件驱动，于是刷新一下页面：
+ *   - 窗没了，而且没有任何入口能再把它开出来；
+ *   - 如果 agent 正举着手等人过验证码，**用户从头到尾看不见它举手**，
+ *     两分钟后 agent 超时、告诉用户"这个站过不去"——一次白等。
+ *
+ * `live` 是**进程内的瞬态事实**（浏览器活着就是活着，pm2 重启就没了）；
+ * `url/title/at` 来自落盘的 `.browser/state.json`，所以**浏览器被空闲回收之后
+ * 卡片还在**，还知道上次停在哪一页。两种性质混在一个响应里是刻意的：
+ * 前端要的就是"卡上写什么"+"点进去有没有活画面"。
+ *
+ * ⚠️ 桌面上那张浏览器卡也吃这个响应，**刻意不塞进 `/artifacts`**：那条是磁盘扫描
+ * 的结果（"工作区里有哪些文件"），而浏览器卡的真相在进程里。混进去的话每次列
+ * 产物都要多一次 stat + 读 json，而且会给人一种"它是一份产物"的错觉 —— 它不是。
+ *
+ * ## GET …/browse/preview → image/webp
+ *
+ * 卡片上那块预览 = **上次看到的样子**（跟 word 卡的页图同一路数）。
+ * ⭐ 活着且空闲时现截一张（顺手把缓存也刷新）；否则回上次那张；都没有 → 204。
+ * ⚠️ **不走 `withBrowser`**：那把锁是给 agent 的，画布刷张缩略图不该排在
+ * agent 的导航后面、更不该让 agent 排在缩略图后面。用 `peek` 直接截，
+ * 撞上 agent 正在导航就抛错 —— 抛了就回缓存，无所谓。
+ *
+ * ## DELETE …/browse → 关实例 + 删痕迹（卡片消失，profile 留着）
+ *
+ * ## POST …/browse/open → { live, url, title }
+ *
+ * **用户主动进去**。这是「随时能进」的那条路：浏览器空闲 5 分钟被回收之后，
+ * 卡还在，双击它就走这里把浏览器起回来、回到上次那一页。
+ * 地址只接受两种来源：落盘状态里的 url，或者请求里给的 url——后者照样过出网闸。
+ *
+ * ⚠️ 这里刻意允许"用户起浏览器"，而 WS 画面通道刻意**不允许**（那边用 `peek`，
+ * 理由是别让看客占掉 1 vCPU 上的常驻名额）。区别是意图：订阅画面是被动看，
+ * 双击卡片是明确要用。
+ */
+
+import express from 'express';
+import { guardProject } from './_guard.js';
+import { browseState, peek, withBrowser, touchProject, closeFor, _limits } from '../engine/browse/registry.js';
+import { pendingHelp } from '../engine/browse/handover.js';
+import { readVisit, readFrame, saveFrame, recordVisit, forgetVisit } from '../engine/browse/state.js';
+import { browseCard } from '../engine/browse/card.js';
+import { checkUrl } from '../lib/ssrf-guard.js';
+
+const router = express.Router();
+
+/** 现截一张的最小间隔 —— 画布会重复问，1 vCPU 上截图要 0.2~4 秒 */
+const RESHOOT_MS = 8000;
+const lastShot = new Map();
+
+router.get('/:pid/browse', async (req, res, next) => {
+  try {
+    if (!guardProject(req, res)) return;
+    const pid = req.params.pid;
+    const help = pendingHelp(pid);
+    // card = 桌面那张卡要的一切（逛过站才非 null）；help 只有窗要
+    const card = await browseCard(pid);
+    res.json({ live: false, url: null, title: null, at: null, busy: false,
+      ...(card || {}), help: help ? help.reason : null });
+  } catch (err) { next(err); }
+});
+
+router.get('/:pid/browse/preview', async (req, res, next) => {
+  try {
+    if (!guardProject(req, res)) return;
+    const pid = req.params.pid;
+    const live = peek(pid);
+    const state = browseState(pid);
+    const stale = (Date.now() - (lastShot.get(pid) || 0)) > RESHOOT_MS;
+    if (live && !state.busy && stale) {
+      lastShot.set(pid, Date.now());
+      try {
+        const buf = await live.page.screenshot({ type: 'png', fullPage: false, timeout: 8000 });
+        await saveFrame(pid, buf);
+      } catch { /* agent 正在导航之类 —— 回缓存那张就好 */ }
+    }
+    const frame = await readFrame(pid);
+    if (!frame) return res.status(204).end();
+    res.set('Content-Type', 'image/webp');
+    // 会变的东西不许缓存：卡片要看到 agent 刚翻到的那一页
+    res.set('Cache-Control', 'no-store');
+    res.set('Last-Modified', frame.mtime.toUTCString());
+    res.end(frame.buf);
+  } catch (err) { next(err); }
+});
+
+router.post('/:pid/browse/open', async (req, res, next) => {
+  try {
+    if (!guardProject(req, res)) return;
+    const pid = req.params.pid;
+    const visit = await readVisit(pid);
+    const want = String(req.body?.url || visit?.url || '');
+    if (!/^https?:\/\//i.test(want)) {
+      return res.status(400).json({ error: '没有可打开的地址（这个项目还没逛过任何站）' });
+    }
+    // 用户点的也过闸 —— 闸是硬边界，不因为"是人点的"就放行
+    const pre = await checkUrl(want);
+    if (!pre.ok) return res.status(403).json({ error: `网络闸拒了这个地址：${pre.reason}` });
+
+    const out = await withBrowser(pid, async ({ page }) => {
+      if (page.url() !== want) {
+        await page.goto(want, { timeout: _limits.NAV_TIMEOUT_MS, waitUntil: 'domcontentloaded' });
+      }
+      await recordVisit(pid, page);
+      return { url: page.url(), title: await page.title().catch(() => '') };
+    });
+    touchProject(pid);
+    res.json({ live: true, ...out });
+  } catch (err) {
+    // 常驻名额满了是 503（registry 抛的），照原样告诉用户，别静默排队
+    if (err?.status === 503) return res.status(503).json({ error: err.message });
+    next(err);
+  }
+});
+
+/**
+ * DELETE …/browse —— 「这张卡我不看了」。
+ *
+ * 关掉活实例 + 删掉浏览痕迹（卡片消失）。**profile 留着** —— 用户是在收拾桌面，
+ * 不是要退出在那个站的登录；下次 agent 再逛同一个站还是登录状态。
+ */
+router.delete('/:pid/browse', async (req, res, next) => {
+  try {
+    if (!guardProject(req, res)) return;
+    const pid = req.params.pid;
+    await closeFor(pid, 'user dismissed the card');
+    await forgetVisit(pid);
+    lastShot.delete(pid);
+    res.json({ ok: true });
+  } catch (err) { next(err); }
+});
+
+export default router;

package/server/api/canvas.js

@@ -0,0 +1,444 @@
+/**
+ * server/api/canvas.js — Canvas + Spec read/write/history/revert
+ *
+ * 路径（2026-08-13 起**项目级**，会话级留作 alias —— 同 pending-changes.js）：
+ *   GET    /api/projects/:pid/assets/*subPath      单文件（iframe 内相对资源）
+ *   GET    /api/projects/:pid/canvas               → text/html
+ *   GET    /api/projects/:pid/canvas/deck-meta     deck 比例信息
+ *   PUT    /api/projects/:pid/canvas               { html, source?, path? }
+ *   GET    /api/projects/:pid/canvas/history       git log
+ *   POST   /api/projects/:pid/canvas/revert        { commit }
+ *   POST   /api/projects/:pid/canvas/undo
+ *   GET    /api/projects/:pid/spec                 spec.json（agent 私域档案）
+ *   GET    /api/projects/:pid/config               session-config.json
+ *   PATCH  /api/projects/:pid/config
+ *   （/:pid/sessions/:sid/... 同 handler 双挂载 —— 老前端和 jsonl 里的历史引用
+ *     还打得通；扁平化后 sessionRoot === 工作区根，这批文件从来就是每项目一份。
+ *     真正 per-session 的数据（.nd/<sid>/、PUT /sessions/:sid/model）不在本文件，
+ *     那些保持 sid 专属，见 sessions.js。）
+ *
+ * 文件实际位置（扁平化后全在工作区根）：
+ *   <workspace>/canvas.html、spec.json、session-config.json、assets/、.git/
+ */
+
+import express from 'express';
+import { promises as fs } from 'fs';
+import path from 'path';
+import { validateProjectId, getProject } from '../projects/store.js';
+import { guardProject } from './_guard.js';
+import {
+  getSessionWorkspace, ensureSessionWorkspace, validateSessionId,
+  getWorkspaceRoot, ensureProjectWorkspace,
+  commitWorkspace, listHistory, revertWorkspace,
+} from '../projects/workspace.js';
+import { fitInjectionBlock } from './standalone-fit.js';
+import { resolveDeckSize, extractDeckAspect } from '../shared/deck.js';
+import { kindOfPath } from '../lib/artifact-target.js';
+import {
+  sendImage, isThumbPath, findOriginalForThumbnail, imageCacheControl,
+  THUMBNAIL_MAX_DIM, THUMBNAIL_QUALITY,
+} from '../lib/image-variant.js';
+import { sendVideo, isVideo } from '../lib/video-variant.js';
+import { readUiConfigFile, withUiDefaults, writeUiConfig } from '../projects/ui-config.js';
+
+const router = express.Router();
+
+const MAX_HTML_BYTES = 8 * 1024 * 1024; // 8MB
+
+function guard(req, res) {
+  // sid 只在走老 alias 时存在 —— 有就校验形状，没有就是项目级路由
+  if (req.params.sid !== undefined) {
+    try {
+      validateSessionId(req.params.sid);
+    } catch (err) {
+      res.status(400).json({ error: err.message || 'invalid pid/sid' });
+      return null;
+    }
+  }
+  // pid 校验 + 存在性 + 归属（2026-07-30 多用户）统一走 guardProject
+  return guardProject(req, res);
+}
+
+/** 两条挂载共用（只读路径）：alias 带 sid 走原路，项目级直接取工作区根 */
+function rootOf(req) {
+  return req.params.sid !== undefined
+    ? getSessionWorkspace(req.params.pid, req.params.sid)
+    : getWorkspaceRoot(req.params.pid);
+}
+
+/** 两条挂载共用（写路径）：同上，但先 ensure 工作区存在 */
+function ensureRootOf(req) {
+  return req.params.sid !== undefined
+    ? ensureSessionWorkspace(req.params.pid, req.params.sid)
+    : ensureProjectWorkspace(req.params.pid);
+}
+
+// 单文件 GET（assets/* 子树）—— 让 iframe 里 <img src="assets/generated/x.jpg">
+// 自然解析 + chat 渲染 image content block 缩略图也走这个 endpoint。
+// 走 sessions/<sid>/assets softlink 透到 shared/assets，路径限 assets/* 子树
+// 防 traversal。MIME 按扩展名定。
+const ASSET_MIME = {
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp', '.gif': 'image/gif', '.svg': 'image/svg+xml',
+  '.pdf': 'application/pdf', '.mp4': 'video/mp4', '.webm': 'video/webm',
+  '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.ogg': 'audio/ogg',
+};
+// thumbnail 地址的解析与兜底（缺 thumb → 回原图 → 现编 512 webp）在
+// lib/image-variant.js，artifact-file 路由吃的是同一份，两条路由行为一致。
+
+router.get(['/:pid/assets/*subPath', '/:pid/sessions/:sid/assets/*subPath'], async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    const sessionRoot = rootOf(req);
+    // Express 5 named wildcard：req.params.subPath 是 string[] 或 string
+    const raw = req.params.subPath;
+    const subPath = Array.isArray(raw) ? raw.join('/') : (raw || '');
+    if (!subPath) return res.status(400).json({ error: 'asset path required' });
+
+    let absPath = path.resolve(sessionRoot, 'assets', subPath);
+    const assetsRoot = path.resolve(sessionRoot, 'assets');
+    // 防 traversal：resolve 后必须在 sessions/<sid>/assets/ 下
+    if (absPath !== assetsRoot && !absPath.startsWith(assetsRoot + path.sep)) {
+      return res.status(403).json({ error: 'path escapes assets/' });
+    }
+
+    // 请求的是不是缩略图地址 —— 决定 fallback 到原图之后要不要顺手缩到 512
+    const wantsThumb = isThumbPath(absPath);
+
+    let stat;
+    let servedOriginalForThumb = false;
+    try {
+      stat = await fs.stat(absPath);
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+      // ENOENT 兜底：thumbnail 路径不存在 → fallback 到原图（老图 / 生成失败 case）
+      if (wantsThumb) {
+        const original = await findOriginalForThumbnail(absPath);
+        if (original) {
+          absPath = original;
+          stat = await fs.stat(original);
+          servedOriginalForThumb = true;
+        } else {
+          return res.status(404).json({ error: 'thumbnail and original both missing' });
+        }
+      } else {
+        return res.status(404).json({ error: 'asset not found' });
+      }
+    }
+    if (!stat.isFile()) return res.status(400).json({ error: 'not a file' });
+
+    const ext = path.extname(absPath).toLowerCase();
+    // 带 ?v= 的是内容寻址 URL（源图一变 v 就变），可以永久缓存；不带的只能短缓存
+    res.setHeader('Cache-Control', imageCacheControl(req));
+    // 视频走 Range + 派生档（deck 里 <video src="assets/x.mp4"> 也打这条路由）
+    if (isVideo(ext)) {
+      return sendVideo(req, res, absPath, stat, {
+        fallbackMime: ASSET_MIME[ext] || 'application/octet-stream',
+      });
+    }
+
+    // 显示路径一律发派生图（原图只留给导出，见 lib/image-variant.js）。
+    // 走 thumbnail 地址却拿到原图时补上 512 长边，等于把当年该生成的那张现补出来。
+    return sendImage(req, res, absPath, stat, {
+      fallbackMime: ASSET_MIME[ext] || 'application/octet-stream',
+      maxDim: servedOriginalForThumb ? THUMBNAIL_MAX_DIM : null,
+      quality: servedOriginalForThumb ? THUMBNAIL_QUALITY : undefined,
+    });
+  } catch (err) { next(err); }
+});
+
+/**
+ * Preview-only：把 canvas.html 里 <img src="assets/generated/<name>.<ext>"> 透明
+ * 重写成 src="assets/generated/.thumbnails/<name>.thumb.webp"。仅 GET /canvas serve
+ * 时改输出，**不动** agent 写的源文件。
+ *
+ * 理由：单图原始 6-8MB（Gemini 默认 1080×1920+ PNG），iframe 缩放（zoom=transform
+ * scale）+ 多图同时渲染让 GPU/RAM 暴涨，preview 体感卡。thumbnail 长边 512 / ~20KB
+ * 足够 preview 看清布局。导出走 build-standalone 仍 inline 原图，最终交付不损质量。
+ *
+ * 也覆盖 CSS 内 url(...) 引用的图片（agent 用 background-image 时常见）。
+ *
+ * thumbnail 不存在时 asset endpoint 会自动 fallback 到原图（见下方 ENOENT 分支），
+ * 老图（thumbnail 没生成的）/ 生成失败的都能正常显示。
+ */
+/**
+ * 注入唯一权威 fit injection block（<script> + <style>）到 </body> 前。
+ *
+ * preview iframe 路径跟离线 / 导出 HTML 走同一份 standalone-fit，确保渲染一致：
+ * 每 section 包 100vw×100vh frame + scroll-snap + CSS min() 缩放。
+ *
+ * 已含 __nd-standard-fit script 的跳过（重启场景：HTML 已经 saved 了）。
+ */
+function injectFitBlock(html) {
+  if (/__nd-standard-fit\b/.test(html)) return html;
+  const block = fitInjectionBlock();
+  if (html.includes('</body>')) return html.replace('</body>', block + '\n</body>');
+  if (html.includes('</html>')) return html.replace('</html>', block + '\n</html>');
+  return html + block;
+}
+
+function rewriteImagesToThumbnails(html) {
+  const imgRe = /(<img\b[^>]*\bsrc\s*=\s*["'])assets\/generated\/(?!\.thumbnails\/)([^"']+?)\.(png|jpg|jpeg|webp|gif)(["'])/gi;
+  const cssUrlRe = /(url\(\s*["']?)assets\/generated\/(?!\.thumbnails\/)([^"')]+?)\.(png|jpg|jpeg|webp|gif)(["']?\s*\))/gi;
+  return html
+    .replace(imgRe, (_m, prefix, name, _ext, suffix) =>
+      `${prefix}assets/generated/.thumbnails/${name}.thumb.webp${suffix}`)
+    .replace(cssUrlRe, (_m, prefix, name, _ext, suffix) =>
+      `${prefix}assets/generated/.thumbnails/${name}.thumb.webp${suffix}`);
+}
+
+router.get(['/:pid/canvas', '/:pid/sessions/:sid/canvas'], async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    const sessionRoot = rootOf(req);
+    const file = path.join(sessionRoot, 'canvas.html');
+    try {
+      let content = await fs.readFile(file, 'utf8');
+      // 注入 <base href>：让 iframe 内 <img src="assets/...">/url("assets/...") 等
+      // 相对资源解析显式锚到本工作区，不依赖 iframe.src 的隐式 base URL
+      // （src 带 ?v=xxx query / 部署 redirect 等都可能让浏览器解析跑偏）。
+      // 已含 <base> 时跳过；正则只匹配开始 <head> tag。
+      // base 跟着请求进来的那条路走（项目级 / sid alias）——assets 两边都挂了，
+      // 项目级页面锚到 sid 路径（或反过来）虽然也能通，但没必要跨范式。
+      if (!/<base\s+href=/i.test(content)) {
+        const baseHref = req.params.sid !== undefined
+          ? `/api/projects/${encodeURIComponent(req.params.pid)}/sessions/${encodeURIComponent(req.params.sid)}/`
+          : `/api/projects/${encodeURIComponent(req.params.pid)}/`;
+        content = content.replace(/<head([^>]*)>/i, `<head$1>\n  <base href="${baseHref}">`);
+      }
+      // 透明替换 generated 图片为 thumbnail（preview 流畅；导出 / agent 看到的源
+      // 文件不动）。env NODESIGN_DISABLE_THUMBNAIL_REWRITE=1 关掉这行为（应急）。
+      if (process.env.NODESIGN_DISABLE_THUMBNAIL_REWRITE !== '1') {
+        content = rewriteImagesToThumbnails(content);
+      }
+      // 注入唯一权威 fit script（每 section 自动包 100vw×100vh frame + scroll-snap）
+      // preview iframe 跟离线打开 / 导出 HTML 共享同一 fit 行为，渲染一致
+      content = injectFitBlock(content);
+      res.setHeader('Content-Type', 'text/html; charset=utf-8');
+      res.setHeader('Cache-Control', 'no-store');
+      res.send(content);
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        // 还没生成（session 刚建，agent 没跑过）—— 占位 HTML
+        res.setHeader('Content-Type', 'text/html; charset=utf-8');
+        res.setHeader('Cache-Control', 'no-store');
+        res.status(200).send(EMPTY_CANVAS_HTML);
+      } else {
+        throw err;
+      }
+    }
+  } catch (err) { next(err); }
+});
+
+/**
+ * GET /:pid/canvas/deck-meta —— 返 deck 比例信息
+ *
+ * 读 canvas.html wrap data-deck-aspect 属性 → resolve 到 4 档预设
+ * （16:9 / 16:10 / 9:16 / 4:3），返 { aspect, width, height }。
+ *
+ * 用途：前端 Home 缩略图 / Workspace ThumbnailBox 需要在挂载前知道 deck
+ * 比例才能正确设容器 aspectRatio + iframe size。Canvas 主路径自己会读
+ * data-deck-aspect 不需要这个 endpoint。
+ *
+ * canvas.html 还没生成 → 返默认 16:9（让前端能用 fallback 占位）
+ */
+router.get(['/:pid/canvas/deck-meta', '/:pid/sessions/:sid/canvas/deck-meta'], async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    const sessionRoot = rootOf(req);
+    // ?path= 让任务 deck 也能问自己的比例（缺省旧式 cwd/canvas.html）
+    const rel = typeof req.query.path === 'string' && req.query.path ? req.query.path : 'canvas.html';
+    const file = path.resolve(sessionRoot, rel);
+    let html = '';
+    if (file === sessionRoot || file.startsWith(sessionRoot + path.sep)) {
+      try { html = await fs.readFile(file, 'utf8'); } catch { /* canvas 还没生成 → 默认 16:9 fallback */ }
+    }
+    // kind 一起返回：站点没有"比例"这回事（响应式、高度不定），前端拿到
+    // kind='site' 就别用下面这组数去套固定画框。不返 kind 的话前端只能拿到
+    // 静默 fallback 的 16:9，把一个网站塞进 1920×1080 的信箱框里。
+    const kind = await kindOfPath(sessionRoot, rel);
+    const aspect = extractDeckAspect(html);
+    const { width, height } = resolveDeckSize(aspect);
+    res.setHeader('Cache-Control', 'no-store');
+    res.json({ kind, aspect, width, height });
+  } catch (err) { next(err); }
+});
+
+/**
+ * PUT /:pid/canvas —— 落库用户在画布上的直接编辑
+ *
+ * body.path（2026-07-28）：任务模型下 deck 住 tasks/<任务>/canvas.html，
+ * 不带这个字段就会把用户的改动写进 sessions/<sid>/canvas.html —— 前端显示
+ * "已保存"，用户看的那份却纹丝不动。缺省仍是旧式 cwd/canvas.html。
+ */
+router.put(['/:pid/canvas', '/:pid/sessions/:sid/canvas'], async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    const { html, source = 'user', path: relPath } = req.body || {};
+    if (typeof html !== 'string' || html.length === 0) {
+      return res.status(400).json({ error: 'html string required' });
+    }
+    if (Buffer.byteLength(html, 'utf8') > MAX_HTML_BYTES) {
+      return res.status(413).json({ error: 'html too large (>8MB)' });
+    }
+
+    const sessionRoot = await ensureRootOf(req);
+    const file = path.resolve(sessionRoot, typeof relPath === 'string' && relPath ? relPath : 'canvas.html');
+    if (file !== sessionRoot && !file.startsWith(sessionRoot + path.sep)) {
+      return res.status(400).json({ error: 'path escapes workspace' });
+    }
+    if (!file.endsWith('.html')) {
+      return res.status(400).json({ error: 'path must be an .html file' });
+    }
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, html, 'utf8');
+
+    const ts = new Date().toISOString();
+    const commit = await commitWorkspace(
+      req.params.pid, req.params.sid,
+      `${source}-edit: ${ts}`,
+      { author: source === 'agent' ? 'agent' : 'user' },
+    );
+    res.json({ ok: true, commit });
+  } catch (err) { next(err); }
+});
+
+// history / revert / undo：git 仓是项目级一个，workspace.js 三个 git helper 的
+// sessionId 参数只是记出处 / 已不参与路径 —— 项目级挂载直接把 undefined 传下去
+router.get(['/:pid/canvas/history', '/:pid/sessions/:sid/canvas/history'], async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    const limit = Math.min(Number(req.query.limit) || 50, 200);
+    const entries = await listHistory(req.params.pid, req.params.sid, { limit });
+    res.json({ entries });
+  } catch (err) { next(err); }
+});
+
+router.post(['/:pid/canvas/revert', '/:pid/sessions/:sid/canvas/revert'], async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    const { commit } = req.body || {};
+    if (!commit || typeof commit !== 'string') {
+      return res.status(400).json({ error: 'commit hash required' });
+    }
+    const newCommit = await revertWorkspace(req.params.pid, req.params.sid, commit);
+    res.json({ ok: true, commit: newCommit });
+  } catch (err) {
+    if (err.code === 'INVALID_COMMIT') return res.status(400).json({ error: err.message });
+    next(err);
+  }
+});
+
+router.post(['/:pid/canvas/undo', '/:pid/sessions/:sid/canvas/undo'], async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    const entries = await listHistory(req.params.pid, req.params.sid, { limit: 5 });
+    if (!entries || entries.length < 2) {
+      return res.status(400).json({
+        error: 'no previous version to undo to',
+        code: 'NO_PREV_COMMIT',
+      });
+    }
+    const prevCommit = entries[1].commit || entries[1].hash || entries[1].sha;
+    if (!prevCommit) {
+      return res.status(500).json({ error: 'history entry missing commit hash' });
+    }
+    const newCommit = await revertWorkspace(req.params.pid, req.params.sid, prevCommit);
+    res.json({ ok: true, commit: newCommit, revertedTo: prevCommit });
+  } catch (err) {
+    if (err.code === 'INVALID_COMMIT') return res.status(400).json({ error: err.message });
+    next(err);
+  }
+});
+
+/**
+ * GET /:pid/spec —— 读工作区根的 spec.json（agent 私域档案）
+ *
+ * 不存在或解析失败时返回 {} —— 让前端不会因 spec 缺失崩。
+ * 这是只读 endpoint —— spec.json 完全由 agent 维护（mutateSpecJson 写的就是
+ * 工作区根这份，hooks.js 读的也是它 —— 项目级挂载跟写入方同一落点）。
+ * 注意：.nd/<sid>/ 里也有一份叫 spec.json 的会话私档（压缩摘要），那是另一回事，
+ * 不走这条路由。
+ */
+router.get(['/:pid/spec', '/:pid/sessions/:sid/spec'], async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    const sessionRoot = rootOf(req);
+    const file = path.join(sessionRoot, 'spec.json');
+    try {
+      const raw = await fs.readFile(file, 'utf8');
+      let spec = {};
+      try { spec = JSON.parse(raw); } catch { spec = {}; }
+      if (!spec || typeof spec !== 'object' || Array.isArray(spec)) spec = {};
+      res.json({ spec });
+    } catch (err) {
+      if (err.code === 'ENOENT') return res.json({ spec: {} });
+      throw err;
+    }
+  } catch (err) { next(err); }
+});
+
+// GET /plan endpoint 已删（Phase 4）；plan mode 整条线 2026-08-21 整体移除。
+
+/**
+ * GET /:pid/config —— 读项目级 UI 配置（ui-config.json，#25 从
+ * session-config.json 改名 —— 扁平化后它就是项目级的了，旧名跟
+ * .nd/<sid>/session-config.json（模型域，session-model.js 专管）同名不同域。
+ * 读写细节和迁移策略在 projects/ui-config.js）
+ *
+ * 跟 spec.json 区分：
+ *   - spec.json = agent 私域档案（agent 通过 record_decision/expose_tweaks/PostCompact 写）
+ *   - ui-config.json = 用户/前端偏好（toggle 状态、UI 偏好）
+ *
+ * 当前字段：
+ *   - tweaks_mode_enabled: bool   是否启用 Tweaks 模式（agent 主动暴露微调参数）
+ *
+ * 文件不存在时返回默认 config。
+ */
+router.get(['/:pid/config', '/:pid/sessions/:sid/config'], async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    const sessionRoot = rootOf(req);
+    res.json({ config: withUiDefaults(await readUiConfigFile(sessionRoot)) });
+  } catch (err) { next(err); }
+});
+
+/**
+ * PATCH /:pid/config —— 部分更新 ui-config.json
+ *
+ * body: 任意 partial config（只覆盖传进来的字段）
+ * 返回：merge 后的完整 config
+ */
+router.patch(['/:pid/config', '/:pid/sessions/:sid/config'], async (req, res, next) => {
+  try {
+    if (!guard(req, res)) return;
+    const sessionRoot = await ensureRootOf(req);
+    const patch = req.body || {};
+    if (typeof patch !== 'object' || Array.isArray(patch)) {
+      return res.status(400).json({ error: 'body must be object' });
+    }
+    // model 不能从这条泛用通道改：改模型除了写字段还要让跑着的 query 认账
+    // （空闲时关掉重启），只写文件会让配置和进程各说各话。走
+    // PUT /sessions/:sid/model —— 那条把两步绑在一起。
+    if ('model' in patch) {
+      return res.status(400).json({
+        error: 'model 不能通过 config PATCH 修改，请用 PUT /sessions/:sid/model',
+        code: 'USE_MODEL_ENDPOINT',
+      });
+    }
+    const current = withUiDefaults(await readUiConfigFile(sessionRoot));
+    const merged = { ...current, ...patch, updatedAt: new Date().toISOString() };
+    await writeUiConfig(sessionRoot, merged);
+    res.json({ config: merged });
+  } catch (err) { next(err); }
+});
+
+const EMPTY_CANVAS_HTML = `<!doctype html>
+<html lang="zh"><head><meta charset="utf-8"><title>NoDesign canvas</title>
+<style>html,body{margin:0;height:100%;font-family:system-ui;background:#F9F8F6}
+.placeholder{display:flex;align-items:center;justify-content:center;height:100%;
+color:#3a2a18aa;font-size:14px;letter-spacing:.02em}</style></head>
+<body><div class="placeholder">canvas.html 还没生成 · 等 agent 跑一次 turn</div></body></html>
+`;
+
+export default router;