@xiaobuyu/nodesign 0.0.2 → 0.0.3

package/server/lib/sketch-layout.js

@@ -0,0 +1,277 @@
+/**
+ * server/lib/sketch-layout.js —— 黑板草图的排布与笔迹（2026-08-23）
+ *
+ * sketch_on_board 一次落一整张图：agent 说的是**结构**（节点、形状、线、模板、
+ * 局部网格坐标），这里把它翻译成世界像素和 SVG 路径。两层拆开是这件事的核心：
+ *   - 宏观落位（图落在无限画布哪里）归服务端：锚点旁 / 内容底下
+ *   - 微观排布（图里面怎么摆）归 agent：模板 + 离散网格（1 格 = UNIT px）
+ * 模型对连续坐标的空间推理弱、对小网格和"谁在谁右边"强，所以给的是网格不是像素。
+ *
+ * 形状（rect/ellipse/line/arrow/underline/circle/path）落成普通 scribble 对象：
+ * 路径在这里生成，带确定性的手绘抖动（种子 = 形状 id），前端一个字不用改。
+ * 路径只用 M/L/Q（board-sanitize 的字符白名单），数字保留一位小数。
+ *
+ * 全是纯函数；尺寸估算与 create-on-board 同一套公式。
+ */
+
+export const UNIT = 24;            // 1 网格 = 24 世界像素
+/**
+ * 可读性规范（2026-08-23，用户定）：黑板上的字要在 80%~100% 缩放下清晰可读。
+ * 手写/md 正文 16px 世界像素在 0.8 倍下是 12.8 屏幕像素 —— 这是底线，所以节点
+ * 字号不低于 md；一张图的尺寸要能在 0.8 倍下整张进一个普通视口（1400×900 屏
+ * ≈ 1750×1125 世界像素）。超过 SKETCH_MAX 直接拒：一张图说一件事，大了就拆。
+ */
+export const SKETCH_FIT = { w: 1700, h: 1100 };   // 推荐上限（0.8 倍一屏）
+export const SKETCH_MAX = { w: 2600, h: 1700 };   // 硬上限（再大就拆成两张）
+export const GAP = 16;             // 模板排布的节点间距
+const SIZE_PX = { sm: 13, md: 16, lg: 22, xl: 30 };
+
+/** 手写字身位估算（抄 create-on-board / 前端 handleCreateText 同款） */
+export function textBox(t, sizeKey, { md = false, wUnits = null } = {}) {
+  const px = SIZE_PX[sizeKey] || 16;
+  if (md) {
+    const raw = String(t);
+    const lines = raw.split('\n');
+    // 字宽按 em 估：CJK/全角 1em，其余 0.62em（"12 个汉字 200px 装不下"就是这么来的）
+    const em = (l) => [...l].reduce((n, c) => n + (/[\u3000-\u9fff\uff00-\uffef]/.test(c) ? 1 : 0.62), 0);
+    const longest = Math.max(8, ...lines.map(em));
+    const w = wUnits ? wUnits * UNIT : Math.min(440, Math.max(200, Math.round(longest * px) + 24));
+    const colsEm = Math.max(8, (w - 12) / px);
+    // 渲染侧（MdInk）单换行 = 真换行，所以按源码行数估；空行 = 段落间距（GAP.sm≈8）；
+    // 行高 1.6、上下 padding 4+4。前端还会把真实高度回写（useMeasuredSize），这里只求落位时别差太多
+    let n = 0; let paras = 0;
+    for (const l of lines) {
+      if (!l.trim()) { paras += 1; continue; }
+      n += Math.max(1, Math.ceil(em(l.replace(/[*_`#>]/g, '')) / colsEm));
+    }
+    // mermaid 盒子：横向（LR/RL）矮、纵向按语句数长；都只是估，真高度由渲染定
+    const mm = raw.match(/```mermaid\n([\s\S]*?)```/);
+    if (mm) {
+      const body = mm[1].split('\n').filter(l => l.trim()).length;
+      n += /\b(LR|RL)\b/.test(mm[1]) ? 3 : Math.max(4, body * 1.6);
+    }
+    return { w, h: Math.round(n * px * 1.6) + 8 + paras * 8 };
+  }
+  const cols = wUnits ? Math.max(4, Math.floor((wUnits * UNIT) / (px * 1.05))) : Math.min(26, Math.max(6, t.length));
+  const lines = Math.ceil(t.length / cols) + (t.match(/\n/g)?.length || 0);
+  return { w: wUnits ? wUnits * UNIT : Math.round(cols * px * 1.05) + 12, h: Math.round(lines * px * 1.6) + 10 };
+}
+
+/* ── 确定性随机（与前端 board-bindings 同款 FNV + mulberry32）── */
+function hashSeed(s) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i += 1) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193) >>> 0; }
+  return h >>> 0;
+}
+function rng(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6D2B79F5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+const f1 = (n) => (Math.round(n * 10) / 10).toString();
+
+/** 手绘一段：两点之间微抖的折线（带一点弧），返回 "L x y ..." 片段（不含起点 M） */
+function wobblySeg(rand, a, b, amp = 1.2) {
+  const dx = b.x - a.x; const dy = b.y - a.y;
+  const len = Math.hypot(dx, dy) || 1;
+  const nx = -dy / len; const ny = dx / len;
+  const segs = Math.max(2, Math.min(12, Math.round(len / 26)));
+  const bow = (rand() * 2 - 1) * Math.min(len * 0.03, 3);
+  let out = '';
+  for (let i = 1; i <= segs; i += 1) {
+    const t = i / segs;
+    const w = i === segs ? 0 : amp * (rand() * 2 - 1) + Math.sin(Math.PI * t) * bow;
+    out += ` L ${f1(a.x + dx * t + nx * w)} ${f1(a.y + dy * t + ny * w)}`;
+  }
+  return out;
+}
+
+/**
+ * 形状 → { d, w, h }（路径相对形状包围盒左上角，pad 留 6px 给抖动和线宽）。
+ * 输入尺寸是像素（调用方已把网格换成像素）。
+ */
+export function shapePath(kind, { w = 0, h = 0, to = null, d = null } = {}, seed = 'shape') {
+  const rand = rng(hashSeed(seed));
+  const P = 6;
+  if (kind === 'path') {
+    // 自由路径：agent 给的局部像素坐标，只做字符白名单与平移（调用方算 bbox）
+    return { d: String(d || ''), w, h };
+  }
+  if (kind === 'line' || kind === 'arrow' || kind === 'underline') {
+    // 从 (0,0) 到 (to.x,to.y) 的一笔；underline 是水平的 line 别名
+    const tx = to?.x ?? w; const ty = kind === 'underline' ? 0 : (to?.y ?? 0);
+    const minX = Math.min(0, tx); const minY = Math.min(0, ty);
+    const a = { x: P - minX, y: P - minY }; const b = { x: tx + P - minX, y: ty + P - minY };
+    let path = `M ${f1(a.x)} ${f1(a.y)}${wobblySeg(rand, a, b)}`;
+    if (kind === 'arrow') {
+      const len = Math.hypot(b.x - a.x, b.y - a.y) || 1;
+      const ux = (b.x - a.x) / len; const uy = (b.y - a.y) / len;
+      const L = Math.min(14, Math.max(8, len * 0.12));
+      const wing = (s) => ({ x: b.x - ux * L + (-uy) * s * L * 0.55, y: b.y - uy * L + ux * s * L * 0.55 });
+      const w1 = wing(1); const w2 = wing(-1);
+      path += ` M ${f1(w1.x)} ${f1(w1.y)}${wobblySeg(rand, w1, b, 0.6)} M ${f1(w2.x)} ${f1(w2.y)}${wobblySeg(rand, w2, b, 0.6)}`;
+    }
+    return { d: path, w: Math.abs(tx) + P * 2, h: Math.abs(ty) + P * 2 };
+  }
+  if (kind === 'rect') {
+    const x0 = P; const y0 = P; const x1 = P + w; const y1 = P + h;
+    const c = [{ x: x0, y: y0 }, { x: x1, y: y0 }, { x: x1, y: y1 }, { x: x0, y: y1 }];
+    // 角上微微出头（手画的框角会交叉），起笔点随机落在四角之一
+    let path = `M ${f1(c[0].x - 1)} ${f1(c[0].y)}`;
+    for (let i = 0; i < 4; i += 1) path += wobblySeg(rand, c[i], c[(i + 1) % 4]);
+    path += ` L ${f1(c[0].x + 3)} ${f1(c[0].y + 0.5)}`;
+    return { d: path, w: w + P * 2, h: h + P * 2 };
+  }
+  if (kind === 'ellipse' || kind === 'circle') {
+    const rx = w / 2; const ry = (kind === 'circle' ? w : h) / 2;
+    const cx = P + rx; const cy = P + ry;
+    const n = Math.max(16, Math.min(48, Math.round((rx + ry) / 6)));
+    const amp = Math.min(1.6, 0.5 + (rx + ry) / 300);
+    let path = '';
+    // 多画 1/8 圈让起止重叠，像手画的圈
+    for (let i = 0; i <= n + n / 8; i += 1) {
+      const t = (i / n) * Math.PI * 2 - Math.PI / 3;
+      const jitter = 1 + (rand() * 2 - 1) * amp / Math.max(rx, ry);
+      const x = cx + Math.cos(t) * rx * jitter; const y = cy + Math.sin(t) * ry * jitter;
+      path += (i === 0 ? 'M ' : ' L ') + `${f1(x)} ${f1(y)}`;
+    }
+    return { d: path, w: rx * 2 + P * 2, h: ry * 2 + P * 2 };
+  }
+  return null;
+}
+
+/**
+ * 模板排布。nodes: [{ key, w, h, at?: {x,y}(网格) }] → Map key → {x,y}（局部像素）
+ * - free：有 at 的按网格落，没 at 的排在 free 区域下面一列
+ * - column / row / grid(cols) / mindmap（第一个是中心，其余环绕）
+ */
+export function layoutNodes(nodes, { template = 'auto', cols = null } = {}) {
+  const pos = new Map();
+  if (!nodes.length) return pos;
+  let tpl = template;
+  if (tpl === 'auto') tpl = nodes.some(n => n.at) ? 'free' : (nodes.length <= 4 ? 'column' : 'grid');
+
+  if (tpl === 'free') {
+    let bottom = 0;
+    const rest = [];
+    for (const n of nodes) {
+      if (n.at && Number.isFinite(n.at.x) && Number.isFinite(n.at.y)) {
+        const p = { x: Math.round(n.at.x * UNIT), y: Math.round(n.at.y * UNIT) };
+        pos.set(n.key, p); bottom = Math.max(bottom, p.y + n.h);
+      } else rest.push(n);
+    }
+    let y = bottom ? bottom + GAP : 0;
+    for (const n of rest) { pos.set(n.key, { x: 0, y }); y += n.h + GAP; }
+    return pos;
+  }
+  if (tpl === 'column') {
+    let y = 0;
+    for (const n of nodes) { pos.set(n.key, { x: 0, y }); y += n.h + GAP; }
+    return pos;
+  }
+  if (tpl === 'row') {
+    let x = 0;
+    for (const n of nodes) { pos.set(n.key, { x, y: 0 }); x += n.w + GAP + 4; }
+    return pos;
+  }
+  if (tpl === 'mindmap') {
+    const [center, ...rest] = nodes;
+    const cx = 0; const cy = 0;
+    pos.set(center.key, { x: cx - center.w / 2, y: cy - center.h / 2 });
+    if (!rest.length) return pos;
+    // 半径：中心节点（含可能套在外面的圈）之外留 70，且环的周长要摆得下所有节点
+    const need = rest.reduce((sum, n) => sum + Math.max(n.w, 120) + GAP * 2, 0);
+    const r = Math.max(center.w / 2 + 70, center.h / 2 + 70, need / (Math.PI * 2) + 40);
+    rest.forEach((n, i) => {
+      const t = (i / rest.length) * Math.PI * 2 - Math.PI / 2;
+      const c = Math.cos(t); const sn = Math.sin(t);
+      // 节点**靠内的那条边**落在环上（不是节点中心）：宽节点才不会压进中心
+      pos.set(n.key, {
+        x: Math.round(cx + c * r - n.w * (1 - c) / 2),
+        y: Math.round(cy + sn * r * 0.72 - n.h * (1 - sn) / 2),
+      });
+    });
+    return pos;
+  }
+  // grid
+  const c = Math.max(1, cols || Math.ceil(Math.sqrt(nodes.length)));
+  const colW = Array(c).fill(0);
+  nodes.forEach((n, i) => { colW[i % c] = Math.max(colW[i % c], n.w); });
+  let y = 0; let rowH = 0;
+  nodes.forEach((n, i) => {
+    const col = i % c;
+    if (col === 0 && i > 0) { y += rowH + GAP; rowH = 0; }
+    let x = 0; for (let k = 0; k < col; k += 1) x += colW[k] + GAP + 4;
+    pos.set(n.key, { x, y }); rowH = Math.max(rowH, n.h);
+  });
+  return pos;
+}
+
+/** 一组矩形的包围盒 */
+export function bboxOf(rects) {
+  let x0 = Infinity; let y0 = Infinity; let x1 = -Infinity; let y1 = -Infinity;
+  for (const r of rects) {
+    x0 = Math.min(x0, r.x); y0 = Math.min(y0, r.y); x1 = Math.max(x1, r.x + r.w); y1 = Math.max(y1, r.y + r.h);
+  }
+  return Number.isFinite(x0) ? { x: x0, y: y0, w: x1 - x0, h: y1 - y0 } : { x: 0, y: 0, w: 0, h: 0 };
+}
+
+/**
+ * 宏观落位：在 obstacles（同层已摆的矩形）中给一块 w×h 找地方。
+ * - near：锚右侧（撞了往下让），让不开就锚下方
+ * - 否则：内容最低边下面（与入座"新东西排底下"同一条起排线精神）
+ */
+export function findSpot({ w, h, near = null, obstacles = [], contentBottom = 0, viewport = null }) {
+  const hits = (x, y) => obstacles.some(o => !(x + w <= o.x || o.x + o.w <= x || y + h <= o.y || o.y + o.h <= y));
+  // 用户视口里有空地就落在视口里（黑板是主窗口时，画在他眼前而不是让他去找）。
+  // 阅读顺序纪律（08-23 真踩：第二张图落到第一张的**左边**）：先挑不在已有内容左侧/
+  // 上方的位置（顺着先左后右、先上后下长），实在没有才退而求其次。
+  if (!near && viewport && viewport.w >= w + 24 && viewport.h >= h + 24) {
+    const content = obstacles.length ? {
+      x: Math.min(...obstacles.map(o => o.x)), y: Math.min(...obstacles.map(o => o.y)),
+    } : null;
+    const sx = Math.max(24, Math.round(viewport.w / 8)); const sy = Math.max(24, Math.round(viewport.h / 8));
+    for (const strict of [true, false]) {
+      for (let y = viewport.y + 12; y + h <= viewport.y + viewport.h - 12; y += sy) {
+        for (let x = viewport.x + 12; x + w <= viewport.x + viewport.w - 12; x += sx) {
+          if (strict && content && (x < content.x - 24 || y < content.y - 24)) continue;
+          if (!hits(x, y)) return { x: Math.round(x), y: Math.round(y), side: 'viewport' };
+        }
+      }
+    }
+  }
+  if (near) {
+    let x = near.x + near.w + 32; let y = near.y;
+    for (let g = 0; g < 30; g += 1) {
+      if (!hits(x, y)) return { x: Math.round(x), y: Math.round(y), side: 'right' };
+      const blocker = obstacles.find(o => !(x + w <= o.x || o.x + o.w <= x || y + h <= o.y || o.y + o.h <= y));
+      y = blocker.y + blocker.h + GAP;
+    }
+    x = near.x; y = near.y + near.h + 32;
+    for (let g = 0; g < 30; g += 1) {
+      if (!hits(x, y)) return { x: Math.round(x), y: Math.round(y), side: 'below' };
+      const blocker = obstacles.find(o => !(x + w <= o.x || o.x + o.w <= x || y + h <= o.y || o.y + o.h <= y));
+      y = blocker.y + blocker.h + GAP;
+    }
+  }
+  // 排在内容底下：左边缘对齐已有内容（不是写死的 10），读起来像续在同一栏
+  const left = obstacles.length ? Math.min(...obstacles.map(o => o.x)) : 10;
+  return { x: Math.round(left), y: Math.round(contentBottom) + 40, side: 'bottom' };
+}
+
+/**
+ * 按用户屏幕算「一屏」：视点里有相机矩形和缩放 → 屏幕像素 = 世界 × 缩放；
+ * 0.8 倍可读 → 一屏世界像素 = 屏幕 / 0.8。没视点就用 SKETCH_FIT 的缺省。
+ */
+export function fitFor(vp) {
+  if (vp?.camera?.w && vp?.zoom) {
+    const sw = vp.camera.w * vp.zoom; const sh = vp.camera.h * vp.zoom;
+    return { w: Math.round(sw / 0.8), h: Math.round(sh / 0.8), screen: { w: Math.round(sw), h: Math.round(sh) } };
+  }
+  return { ...SKETCH_FIT, screen: null };
+}

package/server/projects/board-limits.js

@@ -0,0 +1,12 @@
+/**
+ * server/projects/board-limits.js — board.json 的容量常数（2026-08-23 拆出）
+ * board-store（写盘前查字节数）和 board-sanitize（逐类计数）都要，单独一份免循环依赖。
+ */
+export const DEFAULT_BOARD_SIZE = { w: 4000, h: 2600 };
+export const MAX_BOARD_BYTES = 512 * 1024;
+export const MAX_OBJECTS = 2000;
+export const MAX_ZONES = 200;
+// 关系线上限。取值理由：一块板上人能看懂的线远少于这个数，1000 是防脱缰
+// （agent 循环里连画）的闸门，不是设计目标。超了直接不收，不做淘汰 ——
+// 静默丢最旧的会让"我明明画了"变成玄学。
+export const MAX_BINDINGS = 1000;

package/server/projects/board-sanitize.js

@@ -0,0 +1,252 @@
+/**
+ * server/projects/board-sanitize.js — board.json 的校验/清洗（2026-08-23 从 board-store 拆出）
+ *
+ * 纯函数，不碰磁盘不碰锁。board-store 是唯一读写方，读进来先过这里、写出去前
+ * 也过这里；字段的白名单与上限全在这一份。拆出来只是因为 board-store 胖过了
+ * 行数棘轮，语义一个字没改。
+ *
+ * schema 见 board-store 头注释。黑板字段（2026-08-23）：
+ *   object.tag / object.staging / text.data.format
+ *   binding.material / binding.tag / binding.staging
+ */
+
+import { isBindingType, isBindingMaterial } from '../lib/binding-types.js';
+import { DEFAULT_BOARD_SIZE, MAX_OBJECTS, MAX_ZONES, MAX_BINDINGS } from './board-limits.js';
+
+export function clampNum(v, min, max, fallback) {
+  const n = Number(v);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(max, Math.max(min, Math.round(n)));
+}
+
+export function sanitizeSize(raw) {
+  return {
+    w: clampNum(raw?.w, 1000, 20000, DEFAULT_BOARD_SIZE.w),
+    h: clampNum(raw?.h, 800, 20000, DEFAULT_BOARD_SIZE.h),
+  };
+}
+
+/**
+ * **画布原生**物件的形态白名单。
+ *
+ * 绝大多数画布物件是磁盘产物的影子：board.json 只存它摆在哪，本体是文件
+ * （所以 agent 读得到、能进上下文、删文件即消失）。涂鸦不一样 —— 它没有
+ * 有意义的文件形态，board.json 就是它的**本体**。这类物件必须显式登记，
+ * 否则任何人往 objects 里塞一个 kind 就能造出一个不受形态表管的东西。
+ *
+ * 2026-08-08 加进 `text`。在那之前画布上打的字一律落成 `.md` 便签，理由是
+ * "agent 读得到"。但用户要的是**白板**：在工程文件旁边随手写一句、画一笔，
+ * 那是给自己的记号，不是给 agent 的输入。想让 agent 看见的写便利贴 ——
+ * 那条路还在，挪到了右键菜单里。
+ */
+const CANVAS_NATIVE_KINDS = new Set(['scribble', 'text']);
+
+/**
+ * 坐标夹持上限。画布 2026-08-13 起全向无限，坐标不再由 board.size 夹住 ——
+ * 这个数只挡非有限值和纯属事故的数字（±100 万世界像素之外没有正常操作能到）。
+ */
+const COORD_LIMIT = 1e6;
+
+/** 涂鸦路径串上限。一条随手画的线约 300~800 字符，8000 够长且撑不爆 board.json */
+const MAX_SCRIBBLE_PATH = 8000;
+/**
+ * 画布文字的字数上限。
+ *
+ * 它是"写在白板上的一句话"，不是文档 —— 长东西该写成 .md（那是便利贴，
+ * agent 读得到）。2000 字够写一段说明，也撑不爆 board.json。
+ */
+const MAX_TEXT_LEN = 2000;
+/**
+ * md 档文字的上限（2026-08-23 黑板）。画布上的 markdown/KaTeX/mermaid 节点比手写
+ * 一句话长，但它仍是"黑板上的一块"不是文档 —— 想写长的走 .md。
+ */
+const MAX_MD_TEXT_LEN = 4000;
+/** 文字的排版格式：plain = 原样手写；md = Markdown（含 KaTeX 与 mermaid 围栏） */
+const TEXT_FORMATS = ['plain', 'md'];
+/**
+ * 分组标签（2026-08-23 黑板）：物件和线都可以带。它**不是几何容器**，只是一个
+ * 字段 —— 读侧按它过滤、渲染侧按它画包络、staging 落定按它成批。字符集收紧
+ * 是因为它会进 DOM 属性和 URL 查询串。
+ */
+const TAG_RE = /^[\w\u4e00-\u9fff\u3040-\u30ff-]{1,40}$/;
+/**
+ * 画布 id 的路径安全（2026-08-23 fable 审出 P0）：id 大多是工作区相对路径，下游有人拿它拼
+ * 文件路径（removeByTag 删板书、chalkExcerpts 读板书）。拒掉 `..` 段、绝对路径、反斜杠、NUL；
+ * 带形态前缀（deck:/site:/…）的先剥前缀再查。
+ */
+export function isSafeCanvasId(id) {
+  if (typeof id !== 'string' || !id || id.length > 300) return false;
+  if (id.includes('\0') || id.includes('\\')) return false;
+  const c = id.indexOf(':');
+  const p = (c > 0 && /^[a-z]+$/.test(id.slice(0, c))) ? id.slice(c + 1) : id;
+  if (p.startsWith('/')) return false;
+  return !p.split('/').some(seg => seg === '..');
+}
+
+export function sanitizeTag(v) {
+  return typeof v === 'string' && TAG_RE.test(v) ? v : null;
+}
+
+/** 画布文字可选的字体。**白名单而不是自由字符串** —— 这个值会进 CSS */
+export const TEXT_FONTS = ['pen', 'kai', 'sans', 'serif', 'mono'];
+const TEXT_SIZES = ['sm', 'md', 'lg', 'xl'];
+
+/**
+ * 变换字段（2026-08-13，选中态控制器）。缺省不落字段 —— 没转过没缩过的物件
+ * 别背两个恒等值，board.json 的 diff 要能一眼看出"谁被动过"。
+ */
+function sanitizeTransform(data) {
+  const out = {};
+  const rot = Number(data?.rotation);
+  if (Number.isFinite(rot) && rot !== 0) out.rotation = clampNum(rot, -360, 360, 0);
+  const sc = Number(data?.scale);
+  if (Number.isFinite(sc) && sc !== 1) out.scale = clampNum(sc, 0.2, 10, 1);
+  return out;
+}
+
+function sanitizeCanvasData(kind, data) {
+  if (kind === 'text') {
+    const format = TEXT_FORMATS.includes(data?.format) ? data.format : 'plain';
+    const max = format === 'md' ? MAX_MD_TEXT_LEN : MAX_TEXT_LEN;
+    const t = typeof data?.t === 'string' ? data.t.slice(0, max) : '';
+    if (!t.trim()) return null;
+    return {
+      t,
+      // plain 不落字段：存量条目全是 plain，别让 diff 里凭空多一行
+      ...(format === 'md' ? { format } : {}),
+      font: TEXT_FONTS.includes(data?.font) ? data.font : 'kai',
+      size: TEXT_SIZES.includes(data?.size) ? data.size : 'md',
+      color: ['ink', 'red', 'pencil', 'brass'].includes(data?.color) ? data.color : 'ink',
+      ...sanitizeTransform(data),
+    };
+  }
+  if (kind !== 'scribble') return null;
+  const d = typeof data?.d === 'string' ? data.d.slice(0, MAX_SCRIBBLE_PATH) : '';
+  // 只收 SVG path 里合法的那几个字符，挡住任何往 DOM 里塞东西的尝试
+  if (!d || !/^[\dMLQCZ ,.\-eE]+$/.test(d)) return null;
+  return {
+    d,
+    color: ['ink', 'red', 'pencil', 'brass'].includes(data.color) ? data.color : 'ink',
+    width: clampNum(data.width, 1, 24, 2),
+    ...sanitizeTransform(data),
+  };
+}
+
+export function sanitizeObject(o, size) {
+  if (!o || typeof o !== 'object') return null;
+  const kind = typeof o.kind === 'string' && CANVAS_NATIVE_KINDS.has(o.kind) ? o.kind : null;
+  const data = kind ? sanitizeCanvasData(kind, o.data) : null;
+  // 登记了 kind 却给不出合法内容 → 整条丢弃。留一个空壳会在画布上变成
+  // 一个看不见也删不掉的幽灵物件。
+  if (kind && !data) return null;
+  return {
+    // 画布 2026-08-13 起全向无限：坐标不再被桌面尺寸夹持（原来非 native 只许
+    // 正区间、native 也出不了 ±size）。这里只挡非有限值和纯属事故的数字 ——
+    // 夹得再紧一点都意味着"用户摆在那儿的东西刷新后跳走"，那是静默数据损坏。
+    x: clampNum(o.x, -COORD_LIMIT, COORD_LIMIT, 0),
+    y: clampNum(o.y, -COORD_LIMIT, COORD_LIMIT, 0),
+    z: clampNum(o.z, 0, 1e6, 0),
+    ...(Number.isFinite(Number(o.w)) ? { w: clampNum(o.w, 4, COORD_LIMIT, 200) } : {}),
+    ...(Number.isFinite(Number(o.h)) ? { h: clampNum(o.h, 4, COORD_LIMIT, 200) } : {}),
+    ...(o.expanded ? { expanded: true } : {}),
+    // 显式归属：'' = 明确无归属（覆盖 sid 派生），非空 = 所属工作区 id
+    ...(typeof o.zone === 'string' && o.zone.length <= 300 ? { zone: o.zone } : {}),
+    // 出处（2026-08-14 agent 摆位/建元素）：agent 落的座/写的字标出来，
+    // 用户的是默认不标 —— 跟关系线的 by 同一条纪律
+    ...(o.by === 'agent' ? { by: 'agent' } : {}),
+    // 分组标签 + 草稿位（2026-08-23 黑板）。staging = agent 这一轮还在打草稿：
+    // 入座不看它、read_board 默认不列它、画面上半透明；落定（commitStaging）清位。
+    ...(sanitizeTag(o.tag) ? { tag: sanitizeTag(o.tag) } : {}),
+    ...(o.staging === true ? { staging: true } : {}),
+    ...(kind ? { kind, data } : {}),
+  };
+}
+
+/**
+ * 关系线。**不存坐标** —— 端点是 object id 或 zone id，线跟着端点走。
+ *
+ * 词汇表在 `server/lib/binding-types.js`（前端画线那份视觉映射要跟它对齐，
+ * 有 parity 断言看着）。不认识的 type 一律丢弃：宁可少画一条线，也不要在
+ * 画布上留一条没人知道什么意思的连线。
+ *
+ * 自环（from === to）也丢：它画不出来，且多半是 agent 传错了 id。
+ */
+export function sanitizeBinding(b) {
+  if (!b || typeof b !== 'object') return null;
+  if (!isBindingType(b.type)) return null;
+  const from = typeof b.from === 'string' ? b.from.slice(0, 300) : '';
+  const to = typeof b.to === 'string' ? b.to.slice(0, 300) : '';
+  if (!from || !to || from === to) return null;
+  return {
+    type: b.type,
+    from,
+    to,
+    // 线上的字。没写就渲染时回落到词汇表的默认词，不在这里补 —— 存了默认词
+    // 之后改词汇表就改不动存量了。
+    ...(typeof b.label === 'string' && b.label.trim()
+      ? { label: b.label.trim().slice(0, 60) }
+      : {}),
+    // 谁画的。用户画的线 agent 不该擅自删，反过来也一样；auto = 机器可证的
+    // 引用关系（auto-relations.js 对账层专属，只有它增删自家 b:auto:* 条目）。
+    ...(b.by === 'agent' || b.by === 'user' || b.by === 'auto' ? { by: b.by } : {}),
+    // 材质（2026-08-23 黑板）：语义之外的第二个轴 —— 墨线/手绘/丝线。不落默认值，
+    // 渲染侧按语义给缺省材质；存了默认值以后改缺省就改不动存量。
+    ...(isBindingMaterial(b.material) && b.material !== 'ink' ? { material: b.material } : {}),
+    ...(sanitizeTag(b.tag) ? { tag: sanitizeTag(b.tag) } : {}),
+    ...(b.staging === true ? { staging: true } : {}),
+  };
+}
+
+/**
+ * zones 一行只剩坐标（2026-08-13 瘦身，#14）。
+ *
+ * 逐字段的下场：
+ * - `w`/`h` —— 文件夹变方卡后前端视图**强制** FOLDER_CARD 尺寸，存的数字
+ *   没人读，还会成为"画布上 288 宽、存档里 1340"那种自相矛盾的证据。
+ * - `title` —— 名字从路径读（id 就是路径），存一份就是第二个真相源，
+ *   改名后立刻过期（实测过）。
+ * - `collapsed` —— 收起/展开两态 2026-08-13 随"当前目录"模型退役。
+ * - `pinned` —— 纵向堆叠 2026-08-08 退役，字段没有了对立面。
+ * 存量数据里这些字段读进来直接丢，下次写盘自然消失。
+ */
+export function sanitizeZone(z) {
+  if (!z || typeof z !== 'object') return null;
+  return {
+    // 同 sanitizeObject：无限画布，文件夹卡也能摆在任何地方（含负坐标）
+    x: clampNum(z.x, -COORD_LIMIT, COORD_LIMIT, 0),
+    y: clampNum(z.y, -COORD_LIMIT, COORD_LIMIT, 0),
+  };
+}
+
+export function sanitizeBoard(raw) {
+  const size = sanitizeSize(raw?.size);
+  const objects = {};
+  const zones = {};
+  const bindings = {};
+  let count = 0;
+  for (const [id, o] of Object.entries(raw?.objects && typeof raw.objects === 'object' ? raw.objects : {})) {
+    if (count >= MAX_OBJECTS) break;
+    if (!isSafeCanvasId(id)) continue;
+    const s = sanitizeObject(o, size);
+    if (s) { objects[id] = s; count += 1; }
+  }
+  let zCount = 0;
+  for (const [id, z] of Object.entries(raw?.zones && typeof raw.zones === 'object' ? raw.zones : {})) {
+    if (zCount >= MAX_ZONES) break;
+    if (!isSafeCanvasId(id)) continue;
+    const s = sanitizeZone(z);
+    if (s) { zones[id] = s; zCount += 1; }
+  }
+  let bCount = 0;
+  for (const [id, b] of Object.entries(raw?.bindings && typeof raw.bindings === 'object' ? raw.bindings : {})) {
+    if (bCount >= MAX_BINDINGS) break;
+    if (typeof id !== 'string' || id.length > 300) continue;
+    const s = sanitizeBinding(b);
+    if (s) { bindings[id] = s; bCount += 1; }
+  }
+  // 主角覆盖（2026-08-14 agent 摆位）：显式立的主角压过前端 pickHero 的推断。
+  // 存 id 不存理由 —— 理由在会话里，画布只要知道谁站 C 位
+  const hero = typeof raw?.hero === 'string' && raw.hero.length <= 300 ? raw.hero : null;
+  return { size, zones, objects, bindings, ...(hero ? { hero } : {}) };
+}
+