@xiaobuyu/nodesign 0.0.7 → 0.0.8

package/server/lib/sketch-layout.js

@@ -14,19 +14,24 @@
  * 全是纯函数；尺寸估算与 create-on-board 同一套公式。
  */
 
-export const UNIT = 24;            // 1 网格 = 24 世界像素
+import { UNIT, overlaps, bboxOf as rectBbox } from './rect.js';
+import { ZOOM_BASIS, ONE_SCREEN } from './screen.js';
+export { UNIT };                   // 兼容出口（真身在 rect.js）
 /**
- * 可读性规范（2026-08-23，用户定）：黑板上的字要在 80%~100% 缩放下清晰可读。
- * 手写/md 正文 16px 世界像素在 0.8 倍下是 12.8 屏幕像素 —— 这是底线，所以节点
- * 字号不低于 md；一张图的尺寸要能在 0.8 倍下整张进一个普通视口（1400×900 屏
- * ≈ 1750×1125 世界像素）。超过 SKETCH_MAX 直接拒：一张图说一件事，大了就拆。
+ * 可读性规范（2026-08-23，用户定；2026-08-29 纸范式改 0.75 基准）：黑板上的字要在
+ * 75%~100% 缩放下清晰可读。手写/md 正文 16px 世界像素在 0.75 倍下是 12 屏幕像素 ——
+ * 这是底线，所以节点字号不低于 md；一张图的尺寸要能在 0.75 倍下整张进一个普通视口。
+ * 超过 SKETCH_MAX 直接拒：一张图说一件事，大了就拆。
  */
-export const SKETCH_FIT = { w: 1700, h: 1100 };   // 推荐上限（0.8 倍一屏）
+export const SKETCH_FIT = ONE_SCREEN;   // 推荐上限 = 一屏（唯一基准在 lib/screen.js）
 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 同款） */
+/** 字宽 em 估（CJK/全角 1em，其余 0.62em）—— plain/md 两分支共用 */
+const em2 = (l) => [...l].reduce((n, c) => n + (/[　-鿿＀-￯]/.test(c) ? 1 : 0.62), 0);
+
+/** 手写字身位估算（与前端 text-fonts.js estimateTextBox 同公式，parity 测试钉着） */
 export function textBox(t, sizeKey, { md = false, wUnits = null } = {}) {
   const px = SIZE_PX[sizeKey] || 16;
   if (md) {
@@ -52,11 +57,42 @@ export function textBox(t, sizeKey, { md = false, wUnits = null } = {}) {
     }
     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);
+  // plain 也按 em 估（2026-08-29 刀 3：原来按 t.length，CJK 全错 —— 与前端
+  // text-fonts.js estimateTextBox 同公式，parity 测试钉着，改一边看另一边）
+  const rows = String(t).split('\n');
+  const longest0 = Math.min(26, Math.max(4, ...rows.map(em2)));
+  const cols = wUnits ? Math.max(4, (wUnits * UNIT) / (px * 1.05)) : longest0;
+  const lines = rows.reduce((n, l) => n + Math.max(1, Math.ceil(em2(l) / cols)), 0);
   return { w: wUnits ? wUnits * UNIT : Math.round(cols * px * 1.05) + 12, h: Math.round(lines * px * 1.6) + 10 };
 }
 
+/**
+ * 一块地方大概能写多少字（2026-08-29 占位契约刀 D，站主点名「给 agent 一个
+ * 每个中英文字符占多大的参考」）。
+ *
+ * 公式就是 textBox 那一套的逆用，不是另立一把尺：CJK 记 1em、拉丁记 0.62em，
+ * 行高 = 字号×1.6。板书渲染字号恒定 16px（BoardObject 写死，不读 size 参数），
+ * 所以这里也钉 16。
+ *
+ * 为什么要有它：在这之前给 agent 的护栏**全是像素**（"硬上限 2600×1700"、
+ * "剩 ~412px 高"），而 agent 手里的东西是字。让它自己把字数换算成像素，等于
+ * 每次落笔前做一道它做不准的算术 —— 结果就是写完才发现装不下。
+ *
+ * @param {number} w 可写宽度（像素）
+ * @param {number} h 可写高度（像素）
+ * @returns {{lines:number, cjk:number, latin:number, perLine:number}}
+ *   lines=能排几行，perLine=一行几个汉字，cjk/latin=总字数（纯中文 / 纯拉丁）
+ */
+/** 一条板书的默认版心宽（18 格）—— 自动宽度那三档的上档，也是 prelude 教的列宽 */
+export const DEFAULT_CHALK_W = 18 * UNIT;
+
+export function capacityOf(w, h) {
+  const px = 16;
+  const perLine = Math.max(1, Math.floor((w - 12) / px));
+  const lines = Math.max(0, Math.floor((h - 8) / (px * 1.6)));
+  return { lines, perLine, cjk: lines * perLine, latin: Math.round(lines * perLine / 0.62) };
+}
+
 /* ── 确定性随机（与前端 board-bindings 同款 FNV + mulberry32）── */
 function hashSeed(s) {
   let h = 0x811c9dc5;
@@ -145,16 +181,146 @@ export function shapePath(kind, { w = 0, h = 0, to = null, d = null } = {}, seed
   return null;
 }
 
+
+/**
+ * 自由 path 的手绘化（2026-08-30 画图探针案）：别的图元都过 wobblySeg，唯独
+ * path 原文直通 —— 同一幅画里一半抖一半死直，风格劈叉。这里把 **L 段**换成
+ * 微抖折线（M/Q/C 原样保留：曲线本身已经"活"，再抖是画蛇添足；Z 换成抖回
+ * 起点的显式线段，SVG 的 Z 是死直线）。端点一个不动 —— agent 的几何意图神圣。
+ *
+ * @param {string} dIn  已换算成像素的绝对坐标 path（大写 M/L/Q/C/Z）
+ */
+export function roughFreePath(dIn, seed = 'freepath') {
+  const rand = rng(hashSeed(seed));
+  const tokens = String(dIn).match(/[MLQCZ]|-?\d*\.?\d+(?:[eE][-+]?\d+)?/g) || [];
+  let out = ''; let i = 0;
+  let cur = null; let start = null;
+  const num = () => Number(tokens[i++]);
+  while (i < tokens.length) {
+    const t = tokens[i++];
+    if (t === 'M') { cur = { x: num(), y: num() }; start = { ...cur }; out += `M ${f1(cur.x)} ${f1(cur.y)}`; continue; }
+    if (t === 'L') {
+      const p = { x: num(), y: num() };
+      out += cur ? wobblySeg(rand, cur, p) : ` L ${f1(p.x)} ${f1(p.y)}`;
+      cur = p; continue;
+    }
+    if (t === 'Q') { const c = { x: num(), y: num() }; const p = { x: num(), y: num() }; out += ` Q ${f1(c.x)} ${f1(c.y)} ${f1(p.x)} ${f1(p.y)}`; cur = p; continue; }
+    if (t === 'C') { const a = { x: num(), y: num() }; const b = { x: num(), y: num() }; const p = { x: num(), y: num() }; out += ` C ${f1(a.x)} ${f1(a.y)} ${f1(b.x)} ${f1(b.y)} ${f1(p.x)} ${f1(p.y)}`; cur = p; continue; }
+    if (t === 'Z') { if (cur && start) { out += wobblySeg(rand, cur, start); cur = { ...start }; } continue; }
+  }
+  return out.trim();
+}
+
+/**
+ * 逐坐标对变换一条 path（大写绝对 M/L/Q/C/Z）。旋转/镜像/缩放全走它 ——
+ * 数字成对喂给 fn，命令字原样保留。
+ */
+export function transformD(d, fn) {
+  const tokens = String(d).match(/[MLQCZ]|-?\d*\.?\d+(?:[eE][-+]?\d+)?/g) || [];
+  const out = [];
+  let i = 0;
+  while (i < tokens.length) {
+    const t = tokens[i];
+    if (/^[MLQCZ]$/.test(t)) { out.push(t); i += 1; continue; }
+    const p = fn({ x: Number(tokens[i]), y: Number(tokens[i + 1]) });
+    i += 2;
+    out.push(f1(p.x), f1(p.y));
+  }
+  return out.join(' ');
+}
+
 /**
  * 模板排布。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 } = {}) {
+/**
+ * 模板解析（08-27 抽出，write-on-board 与 layoutNodes 共用一份 auto 规则）。
+ * ⭐ auto 现在**认线**：图内边 ≥1 且节点 ≥3 → flow（按结构分层）。在这之前
+ * 布局引擎对 edges 全盲 —— 给了线也按 column/grid 堆，「摊一堆字」的机器根源。
+ */
+export function resolveTemplate(nodes, { template = 'auto', edges = [], column = false } = {}) {
+  /**
+   * 车道约束（2026-08-28 移动端第二轮）：手机/平板一律竖排一列，**连模型点名的
+   * 模板也盖掉**。
+   *
+   * ⭐ 这条是真会话逼出来的。模型收到「一件 ≤342 宽」之后**试了三次**：第一版
+   * flow 排成 549 宽被警告 → 它改传 `w:14` 想收窄节点，结果整体变成 **576，更宽**
+   * （节点是窄了，但 flow 把它们横着摊成一排）→ 只好 erase_group 重来、再手工
+   * 一件件 move 成一列。擦两次、多花七八个工具调用，才得到本该一次给它的东西。
+   *
+   * ⛔ 病根不是「模型不配合」，是**它够着的那根杠杆是坏的**：唯一能改宽度的入参
+   * 改的是单节点，而决定整体宽度的是布局模板，那个它没法按屏幕挑。所以约束下沉
+   * 到这儿 —— 布局引擎知道屏幕多宽，模型不需要知道。
+   */
+  if (column) return 'column';
+  if (template !== 'auto') return template;
+  if (nodes.some(n => n.at)) return 'free';
+  const keys = new Set(nodes.map(n => n.key));
+  const inner = edges.filter(e => keys.has(e.from) && keys.has(e.to) && e.from !== e.to);
+  if (inner.length && nodes.length >= 3) return 'flow';
+  return nodes.length <= 4 ? 'column' : 'grid';
+}
+
+/** 分层流式（Sugiyama 简版）：层号=最长入路径（模型画的图可能带环，深度截断兜住），
+ *  层内按父级平均横位排（减少交叉），每层居中。线因此顺着重力方向读。 */
+function layoutFlow(nodes, edges, pull = new Map()) {
+  const pos = new Map();
+  const idx = new Map(nodes.map((n, i) => [n.key, i]));
+  const level = new Map();
+  const depth = (k, seen) => {
+    if (level.has(k)) return level.get(k);
+    if (seen.has(k)) return 0;                       // 环：断在回边上
+    seen.add(k);
+    let best = 0;
+    for (const e of edges) if (e.to === k) best = Math.max(best, depth(e.from, seen) + 1);
+    seen.delete(k);
+    level.set(k, best);
+    return best;
+  };
+  for (const n of nodes) depth(n.key, new Set());
+  const layers = [];
+  for (const n of nodes) { const l = level.get(n.key) || 0; (layers[l] ||= []).push(n); }
+  const centerX = new Map();
+  let y = 0;
+  for (const layer of layers) {
+    if (!layer) continue;
+    const parentAvg = (k) => {
+      const ps = edges.filter(e => e.to === k && centerX.has(e.from)).map(e => centerX.get(e.from));
+      return ps.length ? ps.reduce((a, b) => a + b, 0) / ps.length : idx.get(k) * 10;
+    };
+    // 节点级拉力（08-27 产物锚 v2）：连着外部产物的节点排向产物那一侧。
+    // 外部锚是世界坐标、parentAvg 是局部坐标，不同尺度 —— 各自归一到 [0,1] 再比。
+    const norm = (vals) => {
+      const lo = Math.min(...vals); const hi = Math.max(...vals);
+      return (v) => (hi > lo ? (v - lo) / (hi - lo) : 0.5);
+    };
+    const pulled = layer.filter((n) => pull.has(n.key));
+    const nExt = pulled.length ? norm(pulled.map((n) => pull.get(n.key).x)) : null;
+    const paVals = layer.filter((n) => !pull.has(n.key)).map((n) => parentAvg(n.key));
+    const nPa = paVals.length ? norm(paVals) : null;
+    const score = (n) => (pull.has(n.key) ? nExt(pull.get(n.key).x) : (nPa ? nPa(parentAvg(n.key)) : 0.5));
+    layer.sort((a, b) => (score(a) - score(b)) || (idx.get(a.key) - idx.get(b.key)));
+    const totalW = layer.reduce((s, n) => s + n.w, 0) + (layer.length - 1) * (GAP * 2 + 8);
+    let x = Math.round(-totalW / 2);
+    let rowH = 0;
+    for (const n of layer) {
+      pos.set(n.key, { x, y });
+      centerX.set(n.key, x + n.w / 2);
+      x += n.w + GAP * 2 + 8; rowH = Math.max(rowH, n.h);
+    }
+    y += rowH + GAP * 3;                              // 层间留出画箭头的呼吸
+  }
+  return pos;
+}
+
+export function layoutNodes(nodes, { template = 'auto', cols = null, edges = [], pull = new Map(), pullOrigin = 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');
+  const keys = new Set(nodes.map(n => n.key));
+  const inner = edges.filter(e => keys.has(e.from) && keys.has(e.to) && e.from !== e.to);
+  const tpl = resolveTemplate(nodes, { template, edges });
+  if (tpl === 'flow') return layoutFlow(nodes, inner, pull);
 
   if (tpl === 'free') {
     let bottom = 0;
@@ -180,7 +346,58 @@ export function layoutNodes(nodes, { template = 'auto', cols = null } = {}) {
     return pos;
   }
   if (tpl === 'mindmap') {
-    const [center, ...rest] = nodes;
+    // 枢纽按度数选、环序按 BFS 排（08-27）：在这之前中心=第一个节点、环上按入参
+    // 顺序 —— 结构全被扔掉，同父的孩子散在环两端，线横穿整张图
+    let order = nodes;
+    if (inner.length) {
+      const deg = new Map(nodes.map(n => [n.key, 0]));
+      const adj = new Map(nodes.map(n => [n.key, []]));
+      for (const e of inner) {
+        deg.set(e.from, deg.get(e.from) + 1); deg.set(e.to, deg.get(e.to) + 1);
+        adj.get(e.from).push(e.to); adj.get(e.to).push(e.from);
+      }
+      const hub = [...nodes].sort((a, b) => deg.get(b.key) - deg.get(a.key))[0];
+      const seen = new Set([hub.key]); const q = [hub.key]; const bfs = [];
+      while (q.length) {
+        const k = q.shift();
+        for (const nk of adj.get(k) || []) if (!seen.has(nk)) { seen.add(nk); bfs.push(nk); q.push(nk); }
+      }
+      const byKey = new Map(nodes.map(n => [n.key, n]));
+      order = [hub, ...bfs.map(k => byKey.get(k)), ...nodes.filter(n => !seen.has(n.key))];
+    }
+    let [center, ...rest] = order;
+    // 节点级拉力（08-27 产物锚 v2）：连着外部产物的叶子占朝着那个产物的环位 ——
+    // 立绘在上方，评它的节点就在环的上侧，线不再绕半圈。质心=全部外部锚的平均
+    // （图会落在它们旁边，质心是图心的够用近似）。
+    // 方位原点：pullOrigin = 图心的世界坐标（落位后由调用方二次布局传入 ——
+    // 环形 bbox 不随槽位变，二次布局不动落位）。没有它就退回锚质心；
+    // 锚全挤在一点时质心=锚本身、方向向量退化 → 放弃重排（bfs 序保底）。
+    let origin = pullOrigin;
+    if (!origin) {
+      const pts = [...pull.values()];
+      const cx0 = pts.reduce((s, p) => s + p.x, 0) / pts.length;
+      const cy0 = pts.reduce((s, p) => s + p.y, 0) / pts.length;
+      const spread = Math.max(...pts.map((p) => Math.hypot(p.x - cx0, p.y - cy0)));
+      origin = spread > 1 ? { x: cx0, y: cy0 } : null;
+    }
+    if (origin && pull.size && rest.some((n) => pull.has(n.key))) {
+      const slotAng = (i) => (i / rest.length) * Math.PI * 2 - Math.PI / 2;
+      const free = new Set(rest.map((_, i) => i));
+      const assigned = new Array(rest.length).fill(null);
+      const angDist = (a, b) => { const d = Math.abs(a - b) % (Math.PI * 2); return Math.min(d, Math.PI * 2 - d); };
+      for (const n of rest) {
+        if (!pull.has(n.key)) continue;
+        const p = pull.get(n.key);
+        const want = Math.atan2(p.y - origin.y, p.x - origin.x);
+        let best = null;
+        for (const i of free) if (best === null || angDist(slotAng(i), want) < angDist(slotAng(best), want)) best = i;
+        assigned[best] = n; free.delete(best);
+      }
+      const others = rest.filter((n) => !pull.has(n.key));
+      let j = 0;
+      for (const i of [...free].sort((a, b) => a - b)) { assigned[i] = others[j++]; }
+      rest = assigned;
+    }
     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;
@@ -212,66 +429,49 @@ export function layoutNodes(nodes, { template = 'auto', cols = null } = {}) {
   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 };
+/** 一组矩形的包围盒，空集回**零框**（写方直接解构 .x/.w）。真身在 rect.js（那边
+ *  空集 null）。08-28 从 bboxOf 改名 —— 同名两种空集语义在同一个调用文件里混用，
+ *  读代码必看错；名字把契约说出来，谁也不用再翻两处注释对齐。 */
+export function bboxOrZero(rects) {
+  return rectBbox(rects) || { 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 的缺省。
+ * 按用户屏幕算「一屏」，并说清这台机器该拿哪一套版式（2026-08-28 移动端第二轮）。
+ *
+ * 屏幕像素：优先读上报的 `device.w/h`（浏览器直接量的），没有就退回
+ * 「相机矩形 × 缩放」（08-23 起就在这么算，缩放怎么变都得同一个数）。
+ *
+ * ## 两套版式
+ *
+ *   桌面   一屏世界像素 = 屏幕 / 0.75（纸范式基准，见 lib/screen.js —— 用户在
+ *          0.75 倍上读得动，所以内容可以比屏幕大一点）
+ *   触屏   **一件 = 一屏**：宽 = 屏宽 − 48（两边各留 24 呼吸），纵向单列
+ *
+ * ⭐ 触屏这条不是"把桌面的数按比例缩小"。桌面那 1.25 倍富余的前提是**用户会缩小
+ * 了看全貌再放大读细节**，而手机上缩小到 0.19 倍就什么都读不了（真板量的：1766x2018
+ * 的内容在 390 宽的屏上全内容 fit = 19%）。手机上唯一可用的姿势是一件占满一屏、
+ * 竖着翻，所以内容必须**按屏幕生产**，而不是生产完再想办法塞进去。
+ *
+ * ⚠️ 高度给到 1.6 屏而不是 1 屏：竖着滚是手机上读长内容的天然姿势，硬压到一屏
+ * 会逼出一堆"为了短而短"的碎块。宽度才是硬约束（横向滑动没人受得了）。
  */
 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) } };
+  const cls = vp?.device?.class;
+  const lane = (cls === 'phone' || cls === 'tablet') ? cls : 'desktop';
+  let sw = Number(vp?.device?.w) || 0;
+  let sh = Number(vp?.device?.h) || 0;
+  if (!(sw > 0) && vp?.camera?.w && vp?.zoom) {
+    sw = vp.camera.w * vp.zoom; sh = vp.camera.h * vp.zoom;
+  }
+  if (!(sw > 0)) return { ...SKETCH_FIT, screen: null, lane, column: lane !== 'desktop' };
+  const screen = { w: Math.round(sw), h: Math.round(sh) };
+  if (lane === 'desktop') {
+    return { w: Math.round(sw / ZOOM_BASIS), h: Math.round(sh / ZOOM_BASIS), screen, lane, column: false };
   }
-  return { ...SKETCH_FIT, screen: null };
+  return {
+    w: Math.max(240, Math.round(sw - 48)),
+    h: Math.max(320, Math.round(sh * 1.6)),
+    screen, lane, column: true,
+  };
 }

package/server/lib/sketch-shapes.js

@@ -0,0 +1,152 @@
+/**
+ * server/lib/sketch-shapes.js —— sketch 形状构建（2026-08-27 行数棘轮拆件）
+ *
+ * 从 mcp/tools/write-on-board.js **原样**搬出：入参形状声明 → 局部像素矩形 +
+ * 手绘 path + hug 标记。纯计算、不碰磁盘；语义一字未动，搬家原因只有一个 ——
+ * write-on-board 顶到 600 行棘轮（642），拆最独立的这一块。
+ *
+ * 返回 { shapes } 或 { error }（原来的 err() 出口改成 error 字符串，调用方
+ * 自己包成工具错误 —— 这层不该知道 MCP 的返回形状）。
+ */
+
+import { UNIT, shapePath, roughFreePath } from './sketch-layout.js';
+import { stencilStrokes, STENCIL_NAMES } from './sketch-stencils.js';
+import { expandModifiers } from './sketch-array.js';
+import { flattenClosed, hatchD } from './sketch-hatch.js';
+
+/** 板书墨色表（zod 不硬拒，认不出落 ink —— 风格不用 -32602 管） */
+export const SKETCH_COLORS = ['ink', 'red', 'pencil', 'brass'];
+
+/**
+ * @param {Array} shapesIn  工具入参的 shapes
+ * @param {object} deps
+ *   rectOfNode(key) → {x,y,w,h}|null   已落位节点的局部矩形
+ *   isTaken(id) → boolean              id 是否已被节点/形状占用
+ *   tag                                本张图的 tag（手绘抖动的种子）
+ * @returns {{shapes: Array<{key,rect,d,color,width,hug}>}|{error: string}}
+ */
+export function buildSketchShapes(shapesIn, { rectOfNode, isTaken, tag }) {
+  const shapes = [];
+  for (let i = 0; i < shapesIn.length; i += 1) {
+    const s = shapesIn[i];
+    const sid = s.id || `s${i + 1}`;
+    if (isTaken(sid) || shapes.some(x => x.key === sid)) return { error: `形状 id「${sid}」跟节点/别的形状重名（形状缺省叫 s1,s2…，节点别用这类名）` };
+    const seed = `${tag || 'solo'}:${sid}`;
+    // 缺省一律 ink。曾有个 'ink2'（箭头用更深墨色）的死分支：色板里没这个色，
+    // 落盘前的白名单每次都把它打回 'ink'，意图从未生效 —— 08-28 勘查后铲平。
+    const color = SKETCH_COLORS.includes(s.color) ? s.color : 'ink';
+    const width = s.width || 2;
+    // makeOne：按种子重新生成一份本尊 —— 算子展开的每一份各自的抖（看起来是
+    // 手画了 n 遍，不是图章盖了 n 下）。返回 {rect, d}，d 局部于 rect。
+    let makeOne;
+    if (s.kind === 'path') {
+      // 单位单义（2026-08-30 画图探针案）：d 的坐标与 at/w/h **同一套格**（1 格 =
+      // 24px，小数随意）。此前 schema 写着"d 是像素"而 at 是格 —— 同一个形状两套
+      // 单位，真会话里整幅画的 path 墨迹只有别的图元 1/24 大，agent 误诊成
+      // 「path 不渲染」，从此只敢用 rect/circle 拼图，曲线全灭。
+      if (!s.d || !/^[\dMLQCZ ,.\-eE]+$/.test(s.d)) return { error: `形状 ${sid}：path 只收大写 M/L/Q/C/Z 与数字（绝对坐标，单位=格）` };
+      const nums = s.d.match(/-?\d*\.?\d+(?:[eE][-+]?\d+)?/g)?.map(Number) || [];
+      if (!nums.length) return { error: `形状 ${sid}：path 里没有坐标` };
+      const xs = nums.filter((_, k) => k % 2 === 0); const ys = nums.filter((_, k) => k % 2 === 1);
+      const P = 6;
+      const minX = Math.min(...xs) * UNIT; const minY = Math.min(...ys) * UNIT;
+      const w = Math.max(4, (Math.max(...xs) - Math.min(...xs)) * UNIT);
+      const h = Math.max(4, (Math.max(...ys) - Math.min(...ys)) * UNIT);
+      // ×UNIT 并平移到墨迹包围盒（pad 6）—— rect 跟墨走，选中框不再套住一片空气
+      let k = 0;
+      const local = s.d.replace(/-?\d*\.?\d+(?:[eE][-+]?\d+)?/g, (n) => {
+        const v = Number(n) * UNIT - ((k++ % 2 === 0) ? minX : minY) + P;
+        return String(Math.round(v * 10) / 10);
+      });
+      const rect0 = { x: (s.at?.x || 0) * UNIT + minX - P, y: (s.at?.y || 0) * UNIT + minY - P, w: w + P * 2, h: h + P * 2 };
+      let fillPolys = null;
+      if (s.fill) {
+        const fc = flattenClosed(local);
+        if (!fc.closedAny) return { error: `形状 ${sid}：fill 只对闭合轮廓生效（Z 收尾）—— 这条 path 没有闭合的子路径` };
+        fillPolys = fc.polys;
+      }
+      makeOne = (sx) => ({ rect: { ...rect0 }, d: roughFreePath(local, seed + sx) + (fillPolys ? ' ' + hatchD(fillPolys, seed + sx) : '') });
+    } else if (s.kind === 'stencil') {
+      // 词汇表（刀①）：参数化简笔画 —— 名字 + 位置 + 尺寸，一笔一画归机器
+      if (!STENCIL_NAMES.includes(s.name)) return { error: `形状 ${sid}：stencil 认识这些名字 —— ${STENCIL_NAMES.join(', ')}` };
+      if (!s.at || !s.w) return { error: `形状 ${sid}：stencil 要 at + w（格；h 可省 = 按图形比例）` };
+      const st = stencilStrokes(s.name, s.w * UNIT, s.h ? s.h * UNIT : null);
+      const flipped = s.flip
+        ? st.strokes.map((d) => { let k2 = 0; return d.replace(/-?\d*\.?\d+/g, (n) => ((k2++ % 2 === 0) ? String(Math.round((st.w - Number(n)) * 10) / 10) : n)); })
+        : st.strokes;
+      const rect0 = { x: s.at.x * UNIT - 6, y: s.at.y * UNIT - 6, w: st.w + 12, h: st.h + 12 };
+      let stFill = null;
+      if (s.fill) {
+        const fc = flattenClosed(flipped.join(' '));
+        if (!fc.closedAny) return { error: `形状 ${sid}：这个 stencil 没有闭合轮廓，fill 排不了线` };
+        stFill = fc.polys;
+      }
+      makeOne = (sx) => ({
+        rect: { ...rect0 },
+        d: flipped.map((d2, j) => roughFreePath(d2, `${seed}${sx}:${j}`)).join(' ')
+          + (stFill ? ' ' + hatchD(stFill, seed + sx) : ''),
+      });
+    } else if (s.kind === 'line' || s.kind === 'arrow' || s.kind === 'underline') {
+      if (s.fill) return { error: `形状 ${sid}：${s.kind} 是一笔线，没有内部可填 —— fill 只给闭合形状` };
+      let a; let b;
+      if (s.kind === 'underline' && s.around) {
+        const r = rectOfNode(s.around); if (!r) return { error: `形状 ${sid}：around 指向不存在的节点 ${s.around}` };
+        a = { x: r.x + 2, y: r.y + r.h - 2 }; b = { x: r.x + r.w - 2, y: r.y + r.h - 2 };
+      } else {
+        if (!s.at) return { error: `形状 ${sid}：${s.kind} 要 at 起点` };
+        a = { x: s.at.x * UNIT, y: s.at.y * UNIT };
+        if (s.toNode) {
+          const r = rectOfNode(s.toNode); if (!r) return { error: `形状 ${sid}：toNode 指向不存在的节点 ${s.toNode}` };
+          b = { x: r.x + r.w / 2, y: r.y + r.h / 2 };
+        } else if (s.to) b = { x: s.to.x * UNIT, y: s.to.y * UNIT };
+        else if (s.kind === 'underline') b = { x: a.x + (s.w || 4) * UNIT, y: a.y };
+        else return { error: `形状 ${sid}：${s.kind} 要 to 或 toNode` };
+      }
+      makeOne = (sx) => {
+        const sp = shapePath(s.kind, { to: { x: b.x - a.x, y: b.y - a.y } }, seed + sx);
+        return { rect: { x: Math.min(a.x, b.x) - 6, y: Math.min(a.y, b.y) - 6, w: sp.w, h: sp.h }, d: sp.d };
+      };
+    } else {
+      let box;
+      if (s.around) {
+        const r = rectOfNode(s.around); if (!r) return { error: `形状 ${sid}：around 指向不存在的节点 ${s.around}` };
+        const pad = s.kind === 'rect' ? 8 : 14;
+        box = { x: r.x - pad, y: r.y - pad, w: r.w + pad * 2, h: r.h + pad * 2 };
+        if (s.kind === 'circle') { const dmax = Math.max(box.w, box.h); box = { x: box.x + (box.w - dmax) / 2, y: box.y + (box.h - dmax) / 2, w: dmax, h: dmax }; }
+      } else {
+        if (!s.at || !s.w) return { error: `形状 ${sid}：${s.kind} 要 at + w（+h）或 around` };
+        box = { x: s.at.x * UNIT, y: s.at.y * UNIT, w: s.w * UNIT, h: (s.h || s.w) * UNIT };
+      }
+      let boxFill = null;
+      if (s.fill) {
+        const P2 = 6;
+        if (s.kind === 'rect') {
+          boxFill = [[{ x: P2, y: P2 }, { x: P2 + box.w, y: P2 }, { x: P2 + box.w, y: P2 + box.h }, { x: P2, y: P2 + box.h }]];
+        } else {
+          const rx = box.w / 2; const ry = (s.kind === 'circle' ? box.w : box.h) / 2;
+          const pts = [];
+          for (let a2 = 0; a2 < 24; a2 += 1) {
+            const t2 = (a2 / 24) * Math.PI * 2;
+            pts.push({ x: P2 + rx + Math.cos(t2) * rx, y: P2 + ry + Math.sin(t2) * ry });
+          }
+          boxFill = [pts];
+        }
+      }
+      makeOne = (sx) => {
+        const sp = shapePath(s.kind, { w: box.w, h: box.h }, seed + sx);
+        return { rect: { x: box.x - 6, y: box.y - 6, w: sp.w, h: sp.h }, d: sp.d + (boxFill ? ' ' + hatchD(boxFill, seed + sx) : '') };
+      };
+    }
+    // 算子展开（刀④）：repeat/ring/mirror/scatter —— 等距和对称归机器
+    const pieces = expandModifiers(s, makeOne, sid);
+    if (pieces.error) return { error: pieces.error };
+    // 包着节点的记号记 hug：落盘后编辑侧挪节点它跟着走（散架病的另一半在 edit-board）
+    const hugKey = (s.around && ['rect', 'ellipse', 'circle', 'underline'].includes(s.kind)) ? s.around : null;
+    for (const pc of pieces) {
+      if (isTaken(pc.key) || shapes.some((x) => x.key === pc.key)) return { error: `形状 id「${pc.key}」撞名（算子副本叫 <id>-2, <id>-3…，别的形状别占这些名）` };
+      shapes.push({ key: pc.key, rect: pc.rect, d: pc.d, color, width, hug: hugKey });
+    }
+    if (shapes.length > 120) return { error: `形状展开后超过 120 件（第 ${i + 1} 个展开完是 ${shapes.length}）—— 阵列收敛一点，或拆成几张图` };
+  }
+  return { shapes };
+}