@xiaobuyu/nodesign 0.0.1 → 0.0.3

package/server/lib/board-graph-export.js

@@ -0,0 +1,191 @@
+/**
+ * server/lib/board-graph-export.js —— 连接图导出（2026-08-23 黑板）
+ *
+ * 真相是 board.json（节点 + 线 + 位置 + 标签），由它派生三种形态：
+ *   json     结构原样（给程序 / 备份）
+ *   mermaid  flowchart 文本（给别的工具吃；位置丢掉，语义留着）
+ *   svg      一张能看的图：卡片画成带名字的方框、手写字照排、涂鸦照路径、线照语义
+ *            —— 这是**导出保真度**的渲染，不是画布本体（画布本体只有前端那一份）
+ * 可按 #tag 只导一组。带产物的 zip 另议（zip 要搬文件，是交付层的事）。
+ */
+import { BINDING_TYPES } from './binding-types.js';
+import { estimateSizeOn } from './board-kind-sizes.js';
+import { layerOf } from './canvas-id.js';
+import { describeEndpoint } from './board-relations.js';
+
+function pick(board, { tag = null, layer = '' } = {}) {
+  const known = new Set(Object.keys(board.zones || {}));
+  const nodes = [];
+  for (const [id, e] of Object.entries(board.objects || {})) {
+    if (!Number.isFinite(e?.x)) continue;
+    if (layerOf(id, e, known) !== layer) continue;
+    if (tag && e.tag !== tag) continue;
+    const sz = estimateSizeOn(board, id, e);
+    nodes.push({
+      id, kind: e.kind || kindOfId(id), x: e.x, y: e.y, w: sz.w, h: sz.h,
+      ...(e.kind === 'text' ? { text: e.data?.t || '', format: e.data?.format || 'plain', font: e.data?.font, size: e.data?.size, color: e.data?.color } : {}),
+      ...(e.kind === 'scribble' ? { d: e.data?.d || '', color: e.data?.color, width: e.data?.width } : {}),
+      ...(e.tag ? { tag: e.tag } : {}), ...(e.staging ? { staging: true } : {}), ...(e.by ? { by: e.by } : {}),
+    });
+  }
+  const ids = new Set(nodes.map(n => n.id));
+  const edges = [];
+  for (const [id, b] of Object.entries(board.bindings || {})) {
+    if (!ids.has(b.from) || !ids.has(b.to)) continue;
+    if (tag && b.tag !== tag && !(ids.has(b.from) && ids.has(b.to))) continue;
+    edges.push({ id, type: b.type, from: b.from, to: b.to, ...(b.label ? { label: b.label } : {}), material: b.material || 'ink', ...(b.by ? { by: b.by } : {}), ...(b.tag ? { tag: b.tag } : {}) });
+  }
+  return { nodes, edges };
+}
+
+function kindOfId(id) {
+  const m = /^(deck|site|docx|doc):/.exec(id);
+  if (m) return m[1];
+  if (/\.(png|jpe?g|webp|gif|svg|avif)$/i.test(id)) return 'image';
+  if (/\.(mp4|webm|mov)$/i.test(id)) return 'video';
+  if (/\.(md|txt)$/i.test(id)) return 'note';
+  return 'file';
+}
+
+export function exportGraph(board, { format = 'json', tag = null, layer = '' } = {}) {
+  const g = pick(board, { tag, layer });
+  if (format === 'json') return { mime: 'application/json', body: JSON.stringify({ version: 1, tag, layer, ...g }, null, 2) };
+  if (format === 'mermaid') return { mime: 'text/plain; charset=utf-8', body: toMermaid(g, board) };
+  if (format === 'svg') return { mime: 'image/svg+xml; charset=utf-8', body: toSvg(g, board) };
+  throw Object.assign(new Error('unknown format'), { status: 400 });
+}
+
+const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+function nodeTitle(n, board) {
+  if (n.kind === 'text') return String(n.text || '').replace(/^#+\s*/gm, '').replace(/\s+/g, ' ').trim().slice(0, 60);
+  if (n.kind === 'scribble') return '（涂鸦）';
+  return describeEndpoint(n.id, board).replace(/（[a-z]+）$/, '');
+}
+
+export function toMermaid(g, board) {
+  const key = new Map(g.nodes.map((n, i) => [n.id, `n${i}`]));
+  const lines = ['flowchart LR'];
+  for (const n of g.nodes) {
+    if (n.kind === 'scribble') continue;
+    const t = nodeTitle(n, board).replace(/["[\]{}()|]/g, ' ').trim() || n.id;
+    const shape = n.kind === 'text' ? `("${t}")` : `["${t}"]`;
+    lines.push(`  ${key.get(n.id)}${shape}`);
+  }
+  for (const e of g.edges) {
+    const t = BINDING_TYPES[e.type];
+    const word = (e.label || t?.label || e.type).replace(/["|]/g, ' ');
+    const arrow = t?.directed ? `-- ${word} -->` : `--- ${word} ---`;
+    if (!key.has(e.from) || !key.has(e.to)) continue;
+    lines.push(`  ${key.get(e.from)} ${arrow} ${key.get(e.to)}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+const PAPER = { paper: '#F0EADB', ink: '#2B2117', ink2: '#5F5142', pencil: '#A39882', red: '#A8362B', brass: '#b08c4f', card: '#FFFEF6' };
+const INK = { ink: PAPER.ink, red: PAPER.red, pencil: PAPER.pencil, brass: PAPER.brass };
+const SIZE_PX = { sm: 13, md: 16, lg: 22, xl: 30 };
+
+function edgePoint(a, b) {
+  const ac = { x: a.x + a.w / 2, y: a.y + a.h / 2 }; const bc = { x: b.x + b.w / 2, y: b.y + b.h / 2 };
+  const dx = bc.x - ac.x; const dy = bc.y - ac.y;
+  const pt = (r, c, ddx, ddy) => {
+    const tx = ddx === 0 ? Infinity : (r.w / 2) / Math.abs(ddx); const ty = ddy === 0 ? Infinity : (r.h / 2) / Math.abs(ddy);
+    const t = Math.min(tx, ty); return { x: c.x + ddx * t, y: c.y + ddy * t };
+  };
+  return { from: pt(a, ac, dx, dy), to: pt(b, bc, -dx, -dy) };
+}
+
+export function toSvg(g, board, { hrefOf = null } = {}) {
+  if (!g.nodes.length) return '<svg xmlns="http://www.w3.org/2000/svg" width="200" height="60"><text x="10" y="35" font-size="14">（空）</text></svg>';
+  const PAD = 40;
+  const x0 = Math.min(...g.nodes.map(n => n.x)) - PAD; const y0 = Math.min(...g.nodes.map(n => n.y)) - PAD;
+  const x1 = Math.max(...g.nodes.map(n => n.x + n.w)) + PAD; const y1 = Math.max(...g.nodes.map(n => n.y + n.h)) + PAD;
+  const W = Math.round(x1 - x0); const H = Math.round(y1 - y0);
+  const byId = new Map(g.nodes.map(n => [n.id, n]));
+  const out = [];
+  out.push(`<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}" viewBox="${x0} ${y0} ${W} ${H}" font-family="'Kaiti SC','KaiTi','STKaiti',serif">`);
+  out.push(`<rect x="${x0}" y="${y0}" width="${W}" height="${H}" fill="${PAPER.paper}"/>`);
+  out.push('<defs><marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="5" orient="auto" markerUnits="userSpaceOnUse"><path d="M 1 1 L 9 5 L 1 9 z" fill="context-stroke"/></marker><marker id="dot" markerWidth="8" markerHeight="8" refX="4" refY="4" markerUnits="userSpaceOnUse"><circle cx="4" cy="4" r="3" fill="context-stroke"/></marker></defs>');
+  // 线在物件下面
+  for (const e of g.edges) {
+    const a = byId.get(e.from); const b = byId.get(e.to); if (!a || !b) continue;
+    const p = edgePoint(a, b);
+    const dx = p.to.x - p.from.x; const dy = p.to.y - p.from.y; const dist = Math.hypot(dx, dy) || 1;
+    const yarn = e.material === 'yarn';
+    const lift = yarn ? 0 : Math.min(dist * 0.14, 46);
+    const cx = (p.from.x + p.to.x) / 2 + (yarn ? 0 : (-dy / dist) * lift);
+    const cy = (p.from.y + p.to.y) / 2 + (yarn ? Math.min(dist * 0.11, 56) : (dx / dist) * lift);
+    const t = BINDING_TYPES[e.type];
+    const stroke = yarn ? PAPER.red : (e.type === 'contrast' ? PAPER.brass : e.type === 'ref' ? PAPER.pencil : e.type === 'derives-from' ? PAPER.ink : PAPER.ink2);
+    const width = yarn ? 2.6 : e.type === 'derives-from' ? 2.4 : e.type === 'annotates' ? 1.4 : 2;
+    const dash = !yarn && e.type === 'annotates' ? ' stroke-dasharray="3 4"' : !yarn && e.type === 'ref' ? ' stroke-dasharray="1 5"' : '';
+    const marker = yarn ? '' : (t?.directed ? ' marker-end="url(#arrow)"' : (e.type === 'link' ? ' marker-end="url(#dot)" marker-start="url(#dot)"' : ''));
+    out.push(`<path d="M ${p.from.x} ${p.from.y} Q ${cx} ${cy} ${p.to.x} ${p.to.y}" fill="none" stroke="${stroke}" stroke-width="${width}" stroke-linecap="round"${dash}${marker}/>`);
+    if (yarn) for (const q of [p.from, p.to]) out.push(`<circle cx="${q.x}" cy="${q.y}" r="4.6" fill="${PAPER.red}" stroke="${PAPER.ink}" stroke-width="0.8"/>`);
+    const word = e.label || (e.type !== 'annotates' ? t?.label : null);
+    if (word) {
+      const mx = 0.25 * p.from.x + 0.5 * cx + 0.25 * p.to.x; const my = 0.25 * p.from.y + 0.5 * cy + 0.25 * p.to.y;
+      out.push(`<text x="${mx}" y="${my}" font-size="11" text-anchor="middle" dominant-baseline="middle" fill="${PAPER.ink2}" stroke="${PAPER.paper}" stroke-width="4" paint-order="stroke">${esc(word)}</text>`);
+    }
+  }
+  for (const n of g.nodes) {
+    const op = n.staging ? ' opacity="0.55"' : '';
+    if (n.kind === 'scribble') {
+      out.push(`<g transform="translate(${n.x} ${n.y})"${op}><path d="${esc(n.d)}" fill="none" stroke="${INK[n.color] || PAPER.ink}" stroke-width="${n.width || 2}" stroke-linecap="round" stroke-linejoin="round"/></g>`);
+      continue;
+    }
+    if (n.kind === 'text') {
+      const px = SIZE_PX[n.size] || 16; const fill = INK[n.color] || PAPER.ink;
+      const lines = String(n.text || '').split('\n').slice(0, 24);
+      out.push(`<g transform="translate(${n.x + 6} ${n.y + 4})"${op}>` + lines.map((l, i) => `<text x="0" y="${Math.round((i + 0.85) * px * 1.6)}" font-size="${px}" fill="${fill}">${esc(l.replace(/^#+\s*/, '').replace(/\*\*/g, ''))}</text>`).join('') + '</g>');
+      continue;
+    }
+    const title = nodeTitle(n, board);
+    const href = hrefOf ? hrefOf(n) : null;
+    out.push(`${href ? `<a href="${esc(href)}">` : ''}<g${op}><rect x="${n.x}" y="${n.y}" width="${n.w}" height="${n.h}" rx="10" fill="${PAPER.card}" stroke="rgba(43,33,23,0.18)"/>`
+      + `<text x="${n.x + 12}" y="${n.y + 20}" font-size="13" fill="${PAPER.ink}">${esc(title)}</text>`
+      + `<text x="${n.x + 12}" y="${n.y + n.h - 10}" font-size="10" fill="${PAPER.pencil}">${esc(n.kind)}</text></g>${href ? '</a>' : ''}`);
+  }
+  out.push('</svg>');
+  return out.join('\n');
+}
+
+/* ── 带产物的 zip（2026-08-23）────────────────────────────────────────────
+ * 真相仍是 board.json；zip 里：board/graph.json + graph.svg（卡片可点，链到 zip 里的文件）+
+ * graph.mmd + index.html（内嵌 svg 的静态重放页）+ 节点指向的产物文件（走 export-collect
+ * 同一套寻址：站点整目录、deck 的 html、图片、板书 .md…）。画布原生的手写字/涂鸦没有文件，
+ * 它们的内容都在 graph.json/svg 里。
+ */
+export async function exportGraphZip(board, { workspaceRoot, tag = null, layer = '', projectName = '画布' } = {}) {
+  const [{ default: JSZip }, { collectCards }, fsm] = await Promise.all([
+    import('jszip'), import('./export-collect.js'), import('node:fs/promises'),
+  ]);
+  const g = pick(board, { tag, layer });
+  const fileIds = g.nodes.filter(n => n.kind !== 'text' && n.kind !== 'scribble').map(n => n.id);
+  const { bundles, skipped } = await collectCards({ workspaceRoot, cardIds: fileIds });
+  const zip = new JSZip();
+  const relOfNode = new Map();
+  for (const b of bundles) {
+    for (const f of [...(b.files || []), ...(b.assets || [])]) {
+      try { zip.file(f.rel, await fsm.readFile(f.abs)); } catch { /* 读不到就跳，写进 manifest */ }
+    }
+  }
+  // collectCard 不回 cardId：按顺序对齐（collectCards 按 cardIds 顺序 push，跳过的在 skipped）
+  const skippedIds = new Set(skipped.map(s => s.cardId));
+  let bi = 0;
+  for (const id of fileIds) {
+    if (skippedIds.has(id)) continue;
+    const b = bundles[bi++]; if (!b) break;
+    relOfNode.set(id, b.files?.[0]?.rel || b.assets?.[0]?.rel || null);
+  }
+  const hrefOf = (n) => { const r = relOfNode.get(n.id); return r ? `../${r.split('/').map(encodeURIComponent).join('/')}` : null; };
+  const svg = toSvg(g, board, { hrefOf });
+  zip.file('board/graph.json', JSON.stringify({ version: 1, tag, layer, ...g, files: Object.fromEntries(relOfNode), skipped }, null, 2));
+  zip.file('board/graph.svg', svg);
+  zip.file('board/graph.mmd', toMermaid(g, board));
+  zip.file('index.html', `<!doctype html><html lang="zh"><head><meta charset="utf-8"><title>${esc(projectName)} · 画布</title>
+<style>html,body{margin:0;background:#F0EADB;font-family:'Kaiti SC','KaiTi',serif}header{padding:12px 20px;color:#2B2117;font-size:14px}main{overflow:auto;padding:0 20px 20px}svg{max-width:100%;height:auto;display:block}a:hover rect{stroke:#b08c4f;stroke-width:2}</style></head>
+<body><header>${esc(projectName)} · 画布导出${tag ? ` · #${esc(tag)}` : ''} · ${g.nodes.length} 件 ${g.edges.length} 线 · 点卡片打开文件</header><main>${svg.replace(/\.\.\//g, '')}</main></body></html>`);
+  return { zip, skipped, count: { nodes: g.nodes.length, edges: g.edges.length, files: relOfNode.size } };
+}

package/server/lib/board-groups.js

@@ -0,0 +1,167 @@
+/**
+ * server/lib/board-groups.js —— 画布的「组」与「小地图」（2026-08-23 黑板）
+ *
+ * 黑板不设几何容器（用户拍板：frame 给黑板开小灶，终局产物卡也要走同一套）。
+ * 「组」是派生的：**被线连在一起的一群东西算一组**（连通分量），再加上显式
+ * `tag` 字段把没连线的也归到一起。read_board 按组分段输出、用户按组整选、渲染
+ * 按组画包络，三处读同一个判据 —— 入座算法里「关系组独占成行」用的也是连通
+ * 分量，没有第二份真相。
+ *
+ * 小地图：把一层的物件投到一张 ≤ 48×16 的字符网格上。模型读网格的整体感远比
+ * 读三十行坐标强；从 board.json 直接算，零成本。
+ */
+
+/**
+ * 连通分量 + tag 合并。
+ * @param {string[]} ids           这一层的物件 id
+ * @param {object}  bindings       board.bindings
+ * @param {(id:string)=>string|null} tagOf
+ * @returns {Array<{ members: string[], tags: Set<string>, edges: string[] }>}  大组在前
+ */
+export function groupObjects(ids, bindings, tagOf = () => null) {
+  const parent = new Map(ids.map(id => [id, id]));
+  const find = (x) => {
+    while (parent.get(x) !== x) { parent.set(x, parent.get(parent.get(x))); x = parent.get(x); }
+    return x;
+  };
+  const union = (a, b) => {
+    if (!parent.has(a) || !parent.has(b)) return;
+    const ra = find(a); const rb = find(b);
+    if (ra !== rb) parent.set(ra, rb);
+  };
+  const edgesIn = [];
+  const cross = [];
+  for (const [bid, b] of Object.entries(bindings || {})) {
+    if (b.by === 'auto' && b.type === 'ref') continue;   // 自动取材边不成组（蜘蛛网）
+    if (!parent.has(b.from) || !parent.has(b.to)) continue;
+    // tag 优先：两端 tag 不同（或一端有一端没有）的线是"组间线"，不把两张图粘成一组
+    // （08-23 真踩：两张草图之间一条 ref 线让 read_board 把它们报成一组 6 列）
+    const ta = tagOf(b.from); const tb = tagOf(b.to);
+    if (ta !== tb) { cross.push([bid, b]); continue; }
+    union(b.from, b.to); edgesIn.push([bid, b]);
+  }
+  // 同 tag 归一组
+  const byTag = new Map();
+  for (const id of ids) {
+    const t = tagOf(id);
+    if (!t) continue;
+    if (!byTag.has(t)) byTag.set(t, id); else union(byTag.get(t), id);
+  }
+  const groups = new Map();
+  for (const id of ids) {
+    const r = find(id);
+    if (!groups.has(r)) groups.set(r, { members: [], tags: new Set(), edges: [] });
+    const g = groups.get(r);
+    g.members.push(id);
+    const t = tagOf(id); if (t) g.tags.add(t);
+  }
+  for (const [bid, b] of edgesIn) {
+    const g = groups.get(find(b.from));
+    if (g) g.edges.push(bid);
+  }
+  const out = [...groups.values()].sort((a, b) => b.members.length - a.members.length);
+  out.cross = cross.map(([bid]) => bid);   // 组间线 id（调用方愿意列就列）
+  return out;
+}
+
+const GLYPHS = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+
+/**
+ * ASCII 小地图。
+ * @param {Array<{id:string,x:number,y:number,w:number,h:number}>} rects
+ * @param {{ cols?: number, rows?: number, viewport?: {x,y,w,h}|null }} opts
+ * @returns {{ grid: string, legend: Array<[string,string]>, bbox: {x,y,w,h} }|null}
+ */
+export function asciiMinimap(rects, { cols = 48, rows = 16, viewport = null } = {}) {
+  if (!rects.length) return null;
+  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);
+  }
+  if (viewport) {
+    x0 = Math.min(x0, viewport.x); y0 = Math.min(y0, viewport.y);
+    x1 = Math.max(x1, viewport.x + viewport.w); y1 = Math.max(y1, viewport.y + viewport.h);
+  }
+  const W = Math.max(1, x1 - x0); const H = Math.max(1, y1 - y0);
+  // 等比：一个字符格近似正方（字符高宽比约 2:1，所以横向给两倍格数）
+  const scale = Math.max(W / cols, H / (rows * 2));
+  const gw = Math.max(1, Math.ceil(W / scale));
+  const gh = Math.max(1, Math.ceil(H / (scale * 2)));
+  const grid = Array.from({ length: gh }, () => Array(gw).fill('·'));
+  const legend = [];
+  if (viewport) {
+    // 视口边框用 +─│ 画在底下，物件盖在上面
+    const cx0 = Math.floor((viewport.x - x0) / scale); const cx1 = Math.min(gw - 1, Math.floor((viewport.x + viewport.w - x0) / scale));
+    const cy0 = Math.floor((viewport.y - y0) / (scale * 2)); const cy1 = Math.min(gh - 1, Math.floor((viewport.y + viewport.h - y0) / (scale * 2)));
+    for (let x = cx0; x <= cx1; x += 1) { if (grid[cy0]) grid[cy0][x] = '─'; if (grid[cy1]) grid[cy1][x] = '─'; }
+    for (let y = cy0; y <= cy1; y += 1) { if (grid[y]) { grid[y][cx0] = '│'; grid[y][cx1] = '│'; } }
+    if (grid[cy0]) { grid[cy0][cx0] = '┌'; grid[cy0][cx1] = '┐'; }
+    if (grid[cy1]) { grid[cy1][cx0] = '└'; grid[cy1][cx1] = '┘'; }
+  }
+  rects.forEach((r, i) => {
+    const g = i < GLYPHS.length ? GLYPHS[i] : '#';
+    legend.push([g, r.id]);
+    const cx0 = Math.floor((r.x - x0) / scale); const cx1 = Math.min(gw - 1, Math.max(cx0, Math.ceil((r.x + r.w - x0) / scale) - 1));
+    const cy0 = Math.floor((r.y - y0) / (scale * 2)); const cy1 = Math.min(gh - 1, Math.max(cy0, Math.ceil((r.y + r.h - y0) / (scale * 2)) - 1));
+    for (let y = cy0; y <= cy1; y += 1) for (let x = cx0; x <= cx1; x += 1) if (grid[y]) grid[y][x] = g;
+  });
+  return {
+    grid: grid.map(row => row.join('')).join('\n'),
+    legend,
+    bbox: { x: Math.round(x0), y: Math.round(y0), w: Math.round(W), h: Math.round(H) },
+    cell: Math.round(scale),
+  };
+}
+
+/* ────────────────────────────────────────────────────────────────────────
+ * 相对位置（2026-08-23 晚，用户问「我们有没有告诉 agent 各模块的相对位置」——没有，
+ * 之前只给绝对坐标和一张小地图；模型对"组 2 在组 1 左侧、同高"这种话的理解远好于
+ * 读坐标）。下面把组的包围盒之间、组与用户视口之间的关系说成人话；组内再认一下
+ * 列（x 聚类）给出阅读顺序提示。
+ * ──────────────────────────────────────────────────────────────────────── */
+
+export function bboxOfRects(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 } : null;
+}
+
+/** b 相对 a 在哪（以 a 为参照）：左/右/上/下 + 距离；重叠则说重叠 */
+export function relationOf(a, b) {
+  if (!a || !b) return null;
+  const gapX = b.x >= a.x + a.w ? b.x - (a.x + a.w) : (b.x + b.w <= a.x ? a.x - (b.x + b.w) : -1);
+  const gapY = b.y >= a.y + a.h ? b.y - (a.y + a.h) : (b.y + b.h <= a.y ? a.y - (b.y + b.h) : -1);
+  if (gapX < 0 && gapY < 0) return '重叠';
+  const horiz = gapX >= 0 && (gapY < 0 || gapX >= gapY);
+  if (horiz) {
+    const side = b.x >= a.x + a.w ? '右侧' : '左侧';
+    const vAlign = Math.abs(b.y - a.y) < 60 ? '顶齐' : (b.y > a.y ? '偏下' : '偏上');
+    return `${side} ${Math.round(gapX)}px（${vAlign}）`;
+  }
+  const side = b.y >= a.y + a.h ? '下方' : '上方';
+  const hAlign = Math.abs(b.x - a.x) < 60 ? '左齐' : (b.x > a.x ? '偏右' : '偏左');
+  return `${side} ${Math.round(gapY)}px（${hAlign}）`;
+}
+
+/** 组内的列：按左边缘聚类（容差 60px），返回每列的成员数（自左向右） */
+export function columnsOf(rects) {
+  const xs = [...rects].sort((a, b) => a.x - b.x);
+  const cols = [];
+  for (const r of xs) {
+    const c = cols.find(k => Math.abs(k.x - r.x) < 60);
+    if (c) { c.n += 1; c.x = (c.x * (c.n - 1) + r.x) / c.n; } else cols.push({ x: r.x, n: 1 });
+  }
+  return cols;
+}
+
+/** 视口与一块区域的关系 */
+export function viewportRelation(vp, box) {
+  if (!vp || !box) return null;
+  const ix = Math.max(0, Math.min(vp.x + vp.w, box.x + box.w) - Math.max(vp.x, box.x));
+  const iy = Math.max(0, Math.min(vp.y + vp.h, box.y + box.h) - Math.max(vp.y, box.y));
+  const cover = (ix * iy) / Math.max(1, box.w * box.h);
+  if (cover >= 0.95) return '整块在用户视口里';
+  if (cover > 0) return `用户视口盖住它约 ${Math.round(cover * 100)}%`;
+  return `在用户视口之外（视口${relationOf(box, vp) || '别处'}）`;
+}

package/server/lib/board-hero.js

@@ -0,0 +1,76 @@
+/**
+ * server/lib/board-hero.js —— 主角判断的服务端镜像（2026-08-23 黑板）
+ *
+ * 前端 `web/src/lib/hero.js` 的 pickHero 决定哪张产物卡放大 1.5 倍。服务端摆东西
+ * （sketch_on_board / create_on_board 的避让、read_board 的尺寸、look_at_board 的
+ * 取景）在这之前只认基础尺寸，于是"锚在主角卡右边"会落进主角卡的身体里
+ * （08-23 首跑真踩：纸本站是主角 960 宽，草图从 640 处起算，整张压进去）。
+ *
+ * **镜像不是重写**：下面 pickHero 的函数体必须与 web/src/lib/hero.js 逐字相同，
+ * board-hero.test.js 读两份源码比对。npm 包不带 web/src，所以不能 import 过来。
+ */
+import { DECK_EMBED_W, ARTIFACT_HEADER_H, ARTIFACT_PREVIEW_H } from './board-kind-sizes.js';
+import { layerOf } from './canvas-id.js';
+
+// ── 以下到 END-MIRROR 与 web/src/lib/hero.js 逐字一致 ──
+const ELIGIBLE = new Set(['deck', 'site', 'docx']);
+const FOCUS_PER_EDGE = 0.5;
+const FOCUS_CAP = 1.5;
+export function pickHero(items, bindings) {
+  const score = new Map();
+  for (const it of items || []) {
+    if (ELIGIBLE.has(it.type)) score.set(String(it.id), 3);
+  }
+  if (!score.size) return null;
+  const bump = (id, d) => { if (score.has(id)) score.set(id, score.get(id) + d); };
+  const focus = new Map();
+  for (const b of Object.values(bindings || {})) {
+    if (b.type === 'derives-from') { bump(b.from, 2); bump(b.to, -3); }
+    if (b.type === 'ref' && b.by === 'auto') bump(b.to, -3);
+    if (b.by === 'user' || b.by === 'agent') {
+      for (const end of [b.from, b.to]) {
+        if (!score.has(end)) continue;
+        const used = focus.get(end) || 0;
+        if (used >= FOCUS_CAP) continue;
+        focus.set(end, used + FOCUS_PER_EDGE);
+        bump(end, FOCUS_PER_EDGE);
+      }
+    }
+  }
+  const ranked = [...score.entries()].sort((a, z) => z[1] - a[1] || a[0].localeCompare(z[0]));
+  if (ranked.length === 1) return ranked[0][0];
+  if (ranked[0][1] === ranked[1][1]) return null;   // 并列 = 没证据
+  return ranked[0][0];
+}
+// ── END-MIRROR ──
+
+export const HERO_SCALE = 1.5;   // = web board-kinds.js HERO_SCALE
+
+const TYPE_RE = /^(deck|site|docx):/;
+
+/**
+ * 这块板此刻的主角 id（只看桌面根层，与前端入座同口径）：board.hero 显式覆盖，
+ * 否则按关系线推。前端还会把谱系收叠藏起来的旧版排除在外 —— 那些卡本来就被
+ * 改自边重罚，结果一致，这里不重复实现收叠。
+ */
+export function boardHeroId(board) {
+  const known = new Set(Object.keys(board?.zones || {}));
+  const items = [];
+  for (const [id, e] of Object.entries(board?.objects || {})) {
+    if (!Number.isFinite(e?.x) || e.kind) continue;
+    if (layerOf(id, e, known) !== '') continue;
+    const m = TYPE_RE.exec(id);
+    if (m) items.push({ id, type: m[1] });
+  }
+  if (board?.hero && items.some(it => it.id === board.hero)) return board.hero;
+  return pickHero(items, board?.bindings || {});
+}
+
+export function heroSize(id) {
+  const m = TYPE_RE.exec(String(id || ''));
+  if (!m) return null;
+  return {
+    w: Math.round(DECK_EMBED_W * HERO_SCALE),
+    h: ARTIFACT_HEADER_H + Math.round(ARTIFACT_PREVIEW_H[m[1]] * HERO_SCALE),
+  };
+}

package/server/lib/board-kind-sizes.js

@@ -1,62 +1,85 @@
-/**
- * board-kind-sizes —— 画布物件身位的服务端镜像（2026-08-14，agent 摆位批）
- *
- * read_board / arrange_on_board / create_on_board 要在服务端估算卡片矩形
- * （挨着谁摆、会不会压到谁），而身位真相住在前端 `web/src/lib/board-kinds.js`
- * （渲染方）。这里抄一份**常量**，web 侧有 parity 测试钉着两边一致 ——
- * 改那边忘了改这边，测试直接红（跟 binding-types 的双份表同一套纪律）。
- *
- * 文字/涂鸦不在表里：它们的 w/h 是逐条存在 board.json 里的（本体即数据）。
- */
-
-import { KINDS } from './kinds/index.js';
-
-export const DECK_EMBED_W = 640;
-export const ARTIFACT_HEADER_H = 28;
-export const ARTIFACT_PREVIEW_H = { deck: 360, site: 400, docx: 420, browse: 360 };
-
-// file 是 224x32 的细条卡（parity 测试上岗第一天就逮住我猜成 160x120 ——
-// 那是涂鸦的默认身位。别猜，抄表）
-export const KIND_SIZES = {
-  doc: { w: 200, h: 96 },
-  image: { w: 200, h: 176 },
-  video: { w: 240, h: 160 },
-  note: { w: 200, h: 148 },
-  file: { w: 224, h: 32 },
-};
-
-// 前缀表从注册表派生（「写死表家族」第 4 处，2026-08-18 收）：手写
-// `deck|site|docx` 的话加形态必漏，新形态的卡掉到 file 兜底（224×32 细条），
-// agent 摆位按错矩形算。⚠️ 新形态要同步给 ARTIFACT_PREVIEW_H 加一行
-//（两边都有 parity 测试钉着前端那份）。
-const KIND_PREFIX_RE = new RegExp(`^(${Object.keys(KINDS).join('|')}):`);
-
-const IMG_EXT = /\.(png|jpe?g|webp|gif|svg|avif)$/i;
-const VIDEO_EXT = /\.(mp4|webm|mov)$/i;
-
-/**
- * 按 id + board.json 条目估身位。优先条目里存的 w/h（文字/涂鸦，或将来任何
- * 显式尺寸），其次按 id 形态推：kind 前缀 → 产物卡，扩展名 → 图/视频/便签/文件。
- */
-export function estimateSize(id, entry) {
-  if (entry && Number.isFinite(entry.w) && Number.isFinite(entry.h)) {
-    return { w: entry.w, h: entry.h };
-  }
-  const s = String(id || '');
-  if (s.startsWith('doc:')) return KIND_SIZES.doc;
-  // 浏览器卡是**单例**，id 就是 'browse'（没有路径可挂 —— 它背后不是文件）。
-  // 不给这条分支的话它会掉到最后的 file 兜底（224×32 的细条），agent 摆位时
-  // 就会拿一个错的矩形去算"挨着谁摆、会不会压到谁"。
-  if (s === 'browse') {
-    return { w: DECK_EMBED_W, h: ARTIFACT_HEADER_H + ARTIFACT_PREVIEW_H.browse };
-  }
-  const m = KIND_PREFIX_RE.exec(s);
-  if (m) {
-    const t = m[1];
-    return { w: DECK_EMBED_W, h: ARTIFACT_HEADER_H + ARTIFACT_PREVIEW_H[t] };
-  }
-  if (IMG_EXT.test(s)) return KIND_SIZES.image;
-  if (VIDEO_EXT.test(s)) return KIND_SIZES.video;
-  if (/\.(md|txt)$/i.test(s)) return KIND_SIZES.note;
-  return KIND_SIZES.file;
-}
+/**
+ * board-kind-sizes —— 画布物件身位的服务端镜像（2026-08-14，agent 摆位批）
+ *
+ * read_board / arrange_on_board / create_on_board 要在服务端估算卡片矩形
+ * （挨着谁摆、会不会压到谁），而身位真相住在前端 `web/src/lib/board-kinds.js`
+ * （渲染方）。这里抄一份**常量**，web 侧有 parity 测试钉着两边一致 ——
+ * 改那边忘了改这边，测试直接红（跟 binding-types 的双份表同一套纪律）。
+ *
+ * 文字/涂鸦不在表里：它们的 w/h 是逐条存在 board.json 里的（本体即数据）。
+ */
+
+import { KINDS } from './kinds/index.js';
+import { boardHeroId, heroSize } from './board-hero.js';
+
+export const DECK_EMBED_W = 640;
+export const ARTIFACT_HEADER_H = 28;
+export const ARTIFACT_PREVIEW_H = { deck: 360, site: 400, docx: 420, browse: 360 };
+
+// file 是 224x32 的细条卡（parity 测试上岗第一天就逮住我猜成 160x120 ——
+// 那是涂鸦的默认身位。别猜，抄表）
+export const KIND_SIZES = {
+  doc: { w: 200, h: 96 },
+  image: { w: 200, h: 176 },
+  video: { w: 240, h: 160 },
+  note: { w: 200, h: 148 },
+  file: { w: 224, h: 32 },
+};
+
+// 前缀表从注册表派生（「写死表家族」第 4 处，2026-08-18 收）：手写
+// `deck|site|docx` 的话加形态必漏，新形态的卡掉到 file 兜底（224×32 细条），
+// agent 摆位按错矩形算。⚠️ 新形态要同步给 ARTIFACT_PREVIEW_H 加一行
+//（两边都有 parity 测试钉着前端那份）。
+const KIND_PREFIX_RE = new RegExp(`^(${Object.keys(KINDS).join('|')}):`);
+
+const IMG_EXT = /\.(png|jpe?g|webp|gif|svg|avif)$/i;
+const VIDEO_EXT = /\.(mp4|webm|mov)$/i;
+
+/**
+ * 按 id + board.json 条目估身位。优先条目里存的 w/h（文字/涂鸦，或将来任何
+ * 显式尺寸），其次按 id 形态推：kind 前缀 → 产物卡，扩展名 → 图/视频/便签/文件。
+ */
+export function estimateSize(id, entry) {
+  if (entry && Number.isFinite(entry.w) && Number.isFinite(entry.h)) {
+    return { w: entry.w, h: entry.h };
+  }
+  const s = String(id || '');
+  if (s.startsWith('doc:')) return KIND_SIZES.doc;
+  // 浏览器卡是**单例**，id 就是 'browse'（没有路径可挂 —— 它背后不是文件）。
+  // 不给这条分支的话它会掉到最后的 file 兜底（224×32 的细条），agent 摆位时
+  // 就会拿一个错的矩形去算"挨着谁摆、会不会压到谁"。
+  if (s === 'browse') {
+    return { w: DECK_EMBED_W, h: ARTIFACT_HEADER_H + ARTIFACT_PREVIEW_H.browse };
+  }
+  const m = KIND_PREFIX_RE.exec(s);
+  if (m) {
+    const t = m[1];
+    return { w: DECK_EMBED_W, h: ARTIFACT_HEADER_H + ARTIFACT_PREVIEW_H[t] };
+  }
+  if (IMG_EXT.test(s)) return KIND_SIZES.image;
+  if (VIDEO_EXT.test(s)) return KIND_SIZES.video;
+  if (/\.(md|txt)$/i.test(s)) return KIND_SIZES.note;
+  return KIND_SIZES.file;
+}
+
+/**
+ * 按**这块板**估尺寸：主角卡（board-hero 的判断）放大 1.5 倍，其余同 estimateSize。
+ * 凡是拿尺寸去避让/取景/列座次的地方都该用它 —— 主角不是特例，是版面常态。
+ * heroId 按 board 对象缓存一次（同一次工具调用里反复问不重算）。
+ */
+const heroCache = new WeakMap();
+export function estimateSizeOn(board, id, entry) {
+  if (entry && Number.isFinite(entry.w) && Number.isFinite(entry.h)) return { w: entry.w, h: entry.h };
+  if (board && typeof board === 'object') {
+    let hero = heroCache.get(board);
+    if (hero === undefined) {
+      hero = boardHeroId(board);
+      heroCache.set(board, hero);
+    }
+    if (hero && hero === id) {
+      const hs = heroSize(id);
+      if (hs) return hs;
+    }
+  }
+  return estimateSize(id, entry);
+}