@xiaobuyu/nodesign 0.0.7 → 0.0.8

package/server/lib/board-sheets.js

@@ -0,0 +1,467 @@
+/**
+ * server/lib/board-sheets.js —— 纸（sheet）的分配与符号地图（2026-08-29 纸范式刀 1）
+ *
+ * ## 范式总纲（站主拍板）
+ *
+ * 落位的旧回路是「模糊锚点 + 机器启发式找洞」，㉚ 五刀证明那一层的坑修不完。
+ * 新回路：**开工先铺一张纸（0.75 倍缩放下等于用户一屏的矩形），agent 在纸内用
+ * 局部绝对坐标精确摆放，写满翻下一张**。机器只剩两件事：
+ *   1. **纸的分配**（下一张纸放哪 —— 缺省当前纸正下方，铺第一张对准用户视口）
+ *   2. **局部 → 世界的平移**（纸的原点加上去就完了）
+ *
+ * 纸是**分配纪律不是本体容器**（08-23 否 frame 的判决不翻案）：成员按几何派生
+ * （物件中心落在纸内），组照旧由 tag/线派生。用户的手不受纸约束 —— 拖出纸边界
+ * 完全合法。
+ *
+ * 纸名一律 ASCII（p1/p2/…）：它是模型要写进工具参数的值（中文参数值会让部分
+ * 模型静默结束回合 —— feedback-ascii-tool-params）。
+ */
+
+import { UNIT, overlaps, bboxOf, pointIn } from './rect.js';
+import { ONE_SCREEN, ZOOM_BASIS } from './screen.js';
+import { estimateSizeOn, zoneRects } from './board-kind-sizes.js';
+import { DEFAULT_CHALK_W } from './sketch-layout.js';
+import { ROLE_SLUG_RE } from '../engine/agent/cast.js';
+import { layerOf } from './canvas-id.js';
+
+/**
+ * 根层物件（纸只存在于根层桌面，纸面账目只许数根层的东西）。
+ *
+ * ⛔ 2026-08-30 跨层幻影案（proj_mtfpehm3 首拍连败 4 发）：文件夹里的文件卡
+ * 存的是**文件夹层内坐标**，数值恰好落在根层第一张纸的范围里；这儿原来不分层
+ * 直接扫全部 objects，前端根本不渲染的卡在服务端把纸「占满」了 —— 版位报
+ * 剩 0 行、整张纸报 full，全是假账。判据只有一条：layerOf 说它在根层才算。
+ */
+function rootObjects(board) {
+  const objs = board?.objects || {};
+  const known = new Set(Object.keys(board?.zones || {}));
+  const out = [];
+  for (const [id, e] of Object.entries(objs)) {
+    if (!Number.isFinite(e?.x) || !Number.isFinite(e?.y)) continue;
+    if (layerOf(id, e, known) !== '') continue;
+    out.push([id, e]);
+  }
+  return out;
+}
+
+/** 纸与纸之间的沟（格子感放在纸与纸之间 —— 登录墙定格动画同一条经验） */
+export const SHEET_GAP = 2 * UNIT;   // 48
+/** 纸的版心边距：纸内可用区四周留白 */
+export const SHEET_MARGIN = UNIT;    // 24
+
+const snap = (v) => Math.round(v / UNIT) * UNIT;
+
+/** 纸尺寸：铺纸那一刻按设备档算（fitFor 的产出直接喂进来），没有就兜底一屏 */
+export function sheetSizeFor(fit) {
+  if (fit && Number.isFinite(fit.w) && Number.isFinite(fit.h)) {
+    return { w: Math.round(fit.w), h: Math.round(fit.h) };
+  }
+  return { ...ONE_SCREEN };
+}
+
+/** 注册表 → 阅读序矩形列表（先上后下、同带先左后右） */
+export function sheetRects(board) {
+  return Object.entries(board?.sheets || {})
+    .map(([id, s]) => ({ id, x: s.x, y: s.y, w: s.w, h: s.h, at: s.at || '', by: s.by || null, title: s.title || null }))
+    .sort((a, b) => (a.y - b.y) || (a.x - b.x));
+}
+
+/** 下一个纸名：p1/p2/…（取最大序号 +1，撕掉的号不复用 —— 名字要能当历史讲） */
+export function nextSheetName(board) {
+  let max = 0;
+  for (const id of Object.keys(board?.sheets || {})) {
+    const m = /^p(\d{1,5})$/.exec(id);
+    if (m) max = Math.max(max, Number(m[1]));
+  }
+  return `p${max + 1}`;
+}
+
+/** 点落在哪张纸上（重叠时取登记时间最新的 —— 正常分配不产生重叠，这是兜底） */
+export function sheetOfPoint(board, pt) {
+  let hit = null;
+  for (const s of sheetRects(board)) {
+    if (!pointIn(pt, s)) continue;
+    if (!hit || String(s.at) >= String(hit.at)) hit = s;
+  }
+  return hit;
+}
+
+/**
+ * 一张纸的成员（几何派生：物件中心在纸内；staging 也算 —— 草稿也占纸面）。
+ * 文件夹卡（zones）也是成员：它实打实占着那块地，往下接排必须从它底下起
+ * （2026-08-29 占位契约刀 A —— 在这之前它对落位系统整个是隐形的）。
+ */
+export function sheetMembers(board, sheetId) {
+  const s = board?.sheets?.[sheetId];
+  if (!s) return [];
+  const out = [];
+  for (const [id, e] of rootObjects(board)) {
+    const sz = estimateSizeOn(board, id, e);
+    const c = { x: e.x + sz.w / 2, y: e.y + sz.h / 2 };
+    if (pointIn(c, s)) out.push({ id, x: e.x, y: e.y, w: sz.w, h: sz.h, entry: e });
+  }
+  for (const z of zoneRects(board)) {
+    const c = { x: z.x + z.w / 2, y: z.y + z.h / 2 };
+    if (pointIn(c, s)) out.push({ id: z.id, x: z.x, y: z.y, w: z.w, h: z.h, entry: null, folder: true });
+  }
+  return out.sort((a, b) => (a.y - b.y) || (a.x - b.x));
+}
+
+/** 纸内可用区（世界坐标） */
+export function innerRect(s, margin = SHEET_MARGIN) {
+  return { x: s.x + margin, y: s.y + margin, w: s.w - margin * 2, h: s.h - margin * 2 };
+}
+
+/** 局部坐标（纸内像素，原点=版心左上角）→ 世界坐标 */
+export function toWorld(s, local, margin = SHEET_MARGIN) {
+  return { x: s.x + margin + local.x, y: s.y + margin + local.y };
+}
+
+/** 世界坐标 → 纸内局部坐标 */
+export function toLocal(s, world, margin = SHEET_MARGIN) {
+  return { x: world.x - s.x - margin, y: world.y - s.y - margin };
+}
+
+/**
+ * 最新那张纸的名字 = 登记时间（at）最大的那张。**「最新」只有这一份算法**。
+ *
+ * ⚠️ 2026-08-30：这之前有两份。落位走 currentSheet（按 at），而每回合状态块和
+ * read_board 取的是 `sheetRects(board)` 的**最后一项** —— 那个数组按 y 排序，
+ * 拿到的是「最下面那张」。平时新纸往下叠、两者恰好重合，`open_sheet{where:
+ * 'viewport'}` 把纸铺在上方时就分叉：免费账本会去报一张 agent 根本没在写的纸。
+ * 「同一件事各执一词」先想收成一份。
+ */
+export function latestSheetId(board) {
+  let best = null; let bestAt = '';
+  for (const [id, s] of Object.entries(board?.sheets || {})) {
+    if (!best || String(s.at || '') > bestAt) { best = id; bestAt = String(s.at || ''); }
+  }
+  return best;
+}
+
+/**
+ * 当前纸：会话指过的那张（还在就认），否则登记时间最新的一张。
+ * @param {string|null} preferred  会话层记着的纸名
+ */
+export function currentSheet(board, preferred = null) {
+  const sheets = board?.sheets || {};
+  if (preferred && sheets[preferred]) {
+    return { id: preferred, ...sheets[preferred] };
+  }
+  const id = latestSheetId(board);
+  return id ? { id, ...sheets[id] } : null;
+}
+
+/**
+ * 给新纸找落点。纪律：
+ *   - 铺第一张（或显式要求）对准**用户视口**（agent 在用户眼皮底下开工）
+ *   - 续铺缺省落在锚定纸（通常是当前纸）**正下方**（竖着长 = 阅读序，跟章节竖列同构）
+ *   - 纸与纸绝不重叠（硬约束，沿轴滑开）；散落的旧物件尽量避开，避不开就压上
+ *     （纸画在物件层之下，旧东西看起来就是「摆在这张纸上」—— 如实报，不硬拒）
+ *
+ * 契约与 resolvePlacement 同款：**没有失败分支**，永远返回一个矩形。
+ *
+ * @returns {{x,y,w,h, basis:'viewport'|'below-sheet'|'below-content', overlapsLoose:boolean}}
+ */
+export function allocateSheetRect({ board, size, viewport = null, nearSheet = null, obstacles = [] }) {
+  const sz = { w: Math.max(240, Math.round(size?.w || ONE_SCREEN.w)), h: Math.max(240, Math.round(size?.h || ONE_SCREEN.h)) };
+  const sheets = sheetRects(board);
+  const anchor = nearSheet ? sheets.find((s) => s.id === nearSheet) || null : null;
+
+  let ideal; let basis;
+  if (anchor) {
+    ideal = { x: anchor.x, y: anchor.y + anchor.h + SHEET_GAP };
+    basis = 'below-sheet';
+  } else if (viewport && Number.isFinite(viewport.x)) {
+    // 对准视口：纸的左上贴视口左上（snap 到格）。纸比视口大（0.75 基准 vs 用户
+    // 此刻缩放）没关系 —— 铺纸之后镜头会去框纸。
+    ideal = { x: snap(viewport.x), y: snap(viewport.y) };
+    basis = 'viewport';
+  } else {
+    const content = bboxOf([...sheets, ...obstacles]);
+    ideal = content
+      ? { x: snap(content.x), y: snap(content.y + content.h) + SHEET_GAP }
+      : { x: 0, y: 0 };
+    basis = 'below-content';
+  }
+
+  const hitsSheet = (r) => sheets.some((s) => overlaps(r, s, SHEET_GAP / 2));
+  const hitsLoose = (r) => obstacles.some((o) => overlaps(r, o));
+
+  // 先找「纸不撞纸、也不压散件」的位置；往下滑最多 4 屏，找不到就接受压散件，
+  // 只保硬约束（纸不撞纸）。滑动只沿 y 轴 —— 纸的阅读序是竖着长的。
+  const MAX_SLIDE = sz.h * 4;
+  let clean = null; let sheetClear = null;
+  for (let dy = 0; dy <= MAX_SLIDE; dy += UNIT * 2) {
+    const r = { x: ideal.x, y: ideal.y + dy, w: sz.w, h: sz.h };
+    if (hitsSheet(r)) continue;
+    if (sheetClear === null) sheetClear = r;
+    if (!hitsLoose(r)) { clean = r; break; }
+  }
+  if (clean) return { ...clean, basis, overlapsLoose: false };
+  if (sheetClear) return { ...sheetClear, basis, overlapsLoose: true };
+  // 连纸不撞纸的位置都没有（理想列被纸占满 4 屏）：落到全部纸的最底下
+  const all = bboxOf(sheets) || { x: ideal.x, y: ideal.y, w: 0, h: 0 };
+  const r = { x: ideal.x, y: snap(all.y + all.h) + SHEET_GAP, w: sz.w, h: sz.h };
+  return { ...r, basis, overlapsLoose: hitsLoose(r) };
+}
+
+/**
+ * 纸内自动落位（给没带坐标的写入用：产物入座、步骤清单、agent 偷懒不给 at）。
+ *
+ * **跟着设备的形状走**（2026-08-29 站主拍板）：
+ *   - 横纸（电脑：2048×973 那种）→ **报纸分栏**：竖着填满一栏，再到右边下一栏顶上，
+ *     整页填满才翻页。原来只会往下排一列 —— 一张两个屏幕宽的纸，四分之三是空的。
+ *   - 竖纸（手机：屏宽 × 1.6 屏高）→ 只往下。竖屏上分栏等于把每栏挤成一指宽。
+ *
+ * 栏宽固定 DEFAULT_CHALK_W（不随内容变），否则每写一件栏边界就漂一次，读起来
+ * 是锯齿。比一栏宽的东西（产物卡 640）自然占掉它压住的所有栏 —— 算某栏的底部时
+ * 认**水平重叠**而不是中心点，宽物件才挡得住它真正盖住的那几栏。
+ *
+ * 装不下返回 null（调用方翻新纸）。仍然不是启发式引擎：规则只有"竖着填、填满换栏"。
+ *
+ * @returns {{x,y,col?}|null}  世界坐标；null = 这张纸满了
+ */
+export function nextSpotInSheet(board, sheetId, box, { gap = UNIT } = {}) {
+  const s = board?.sheets?.[sheetId];
+  if (!s) return null;
+  const inner = innerRect(s);
+  if (box.w > inner.w) return null;   // 比纸还宽的东西没资格进这张纸
+  const members = sheetMembers(board, sheetId);
+  const floor = inner.y + inner.h;
+
+  // 竖纸：只往下（原规则）
+  if (inner.w <= inner.h) {
+    const bottom = members.length ? Math.max(...members.map((m) => m.y + m.h)) : inner.y - gap;
+    const y = Math.round(bottom + gap);
+    if (y + box.h > floor) return null;
+    return { x: Math.round(inner.x), y };
+  }
+
+  // 横纸：先往下接；这一列到底了，就在纸上往右找第一块放得下的地方。
+  // 步长跟这件东西的宽度走，不是切死的栏 —— 机器只是帮忙找地方，版面怎么切
+  // 是 agent 自己的事（站主：有限制有规划的自由）。
+  const step = Math.max(UNIT * 4, Math.round(box.w) + gap);
+  for (let x = inner.x; x + box.w <= inner.x + inner.w + 1; x += step) {
+    const hit = members.filter((m) => m.x < x + box.w && m.x + m.w > x);
+    const bottom = hit.length ? Math.max(...hit.map((m) => m.y + m.h)) : inner.y - gap;
+    const y = Math.round(bottom + gap);
+    if (y + box.h <= floor) return { x: Math.round(x), y, moved: x > inner.x };
+  }
+  return null;   // 纸上哪儿都放不下了 —— 这才叫满
+}
+
+/**
+ * 这张纸还剩哪些空地（2026-08-29 刀 F，站主要的"有规划的自由"的依据）。
+ *
+ * agent 要自己判断"还放不放得下、要不要开新一页"，就得知道纸上哪里还空着 ——
+ * 只报"最后一件下面还剩多少"是不够的：那一列到底了不等于这张纸满了，右边可能
+ * 整片空着。按内容列宽扫一遍，报每一列的剩余高度。
+ *
+ * @returns {Array<{x:number, freeH:number}>}  x = 纸内局部像素
+ */
+export function freeColumnsInSheet(board, sheetId, colW = DEFAULT_CHALK_W, gap = UNIT) {
+  const s = board?.sheets?.[sheetId];
+  if (!s) return [];
+  const inner = innerRect(s);
+  const members = sheetMembers(board, sheetId);
+  const out = [];
+  for (let x = inner.x; x + colW <= inner.x + inner.w + 1; x += colW + gap) {
+    const hit = members.filter((m) => m.x < x + colW && m.x + m.w > x);
+    const bottom = hit.length ? Math.max(...hit.map((m) => m.y + m.h)) : inner.y - gap;
+    out.push({ x: Math.round(x - inner.x), freeH: Math.max(0, Math.round(inner.y + inner.h - (bottom + gap))) });
+  }
+  return out;
+}
+
+/* ── 版位（slot，2026-08-29 占位契约刀 E）────────────────────────────────
+ *
+ * 站主拍板：**agent 应当提前规划所有落位，然后再开始生成**。所以开工那一步不是
+ * 「写第一条」而是「把这一屏切成几块地」（open_sheet 的 plan），之后每条内容
+ * 点名往哪块地里放。
+ *
+ * 为什么这比「一条一条自己给 at」强：一张纸是横的（约 2.1:1），一条一条往下写
+ * 只会用掉最左边一栏、剩下大半空着；而且写到第五条才发现装不下时，前四条已经
+ * 落盘了。先规划＝**版面在内容之前就定死**，装不下当场就知道。
+ *
+ * 装不下的处理是**拒收**不是挤进去（站主原话：提示 agent 让她分块内容、重新
+ * 布置）—— 折叠、裁切、自动缩排都是替它把问题藏起来。
+ */
+
+/** 版位矩形（世界坐标）。名字不存在返回 null */
+export function slotRectOf(sheet, name, margin = SHEET_MARGIN) {
+  const sl = sheet?.slots?.[name];
+  if (!sl) return null;
+  return {
+    x: sheet.x + margin + sl.x, y: sheet.y + margin + sl.y,
+    w: sl.w, h: sl.h, about: sl.about || null,
+  };
+}
+
+/** 落在某块地里的物件（中心点判据，同 sheetMembers；只数根层 —— 版位在纸上，
+ *  纸在根层。顶层文件夹卡真占着地也算成员：它就摆在那儿）。 */
+export function membersInRect(board, rect) {
+  const out = [];
+  for (const [id, e] of rootObjects(board)) {
+    const sz = estimateSizeOn(board, id, e);
+    const c = { x: e.x + sz.w / 2, y: e.y + sz.h / 2 };
+    if (pointIn(c, rect)) out.push({ id, x: e.x, y: e.y, w: sz.w, h: sz.h });
+  }
+  for (const z of zoneRects(board)) {
+    const c = { x: z.x + z.w / 2, y: z.y + z.h / 2 };
+    if (pointIn(c, rect)) out.push({ id: z.id, x: z.x, y: z.y, w: z.w, h: z.h, folder: true });
+  }
+  return out.sort((a, b) => (a.y - b.y) || (a.x - b.x));
+}
+
+/**
+ * 版位内往下接排。装不下**不返回兜底位置** —— 返回 full + 还剩多少，
+ * 调用方据此拒收并把这个数报给 agent。
+ *
+ * @returns {{x,y}|{full:true, freeH:number, needH:number}}
+ */
+export function nextSpotInSlot(board, rect, box, { gap = UNIT } = {}) {
+  const members = membersInRect(board, rect);
+  const bottom = members.length ? Math.max(...members.map((m) => m.y + m.h)) : rect.y - gap;
+  const y = Math.round(bottom + gap);
+  const freeH = Math.max(0, Math.round(rect.y + rect.h - y));
+  if (box.h > freeH) return { full: true, freeH, needH: box.h, taken: members.length };
+  return { x: Math.round(rect.x), y };
+}
+
+/**
+ * 符号地图：板上现在有哪些纸（read_board / 注入 用）。
+ * 每张：名字、矩形、件数、剩余高度（版心内从成员最低边到纸底）。
+ */
+export function sheetSummaries(board) {
+  return sheetRects(board).map((s) => {
+    const members = sheetMembers(board, s.id);
+    const inner = innerRect(s);
+    const bottom = members.length ? Math.max(...members.map((m) => m.y + m.h)) : inner.y;
+    const full = board?.sheets?.[s.id] || {};
+    // 版位余量（2026-08-30）：agent 每回合免费拿到的空间账本此前只有整张纸的
+    // freeH —— 而它写的时候是往**块**里写。报纸不报块，等于让它对着错的数做判断。
+    const slots = Object.entries(full.slots || {}).map(([name, sl]) => {
+      const rect = slotRectOf({ ...full, id: s.id }, name);
+      const spot = rect ? nextSpotInSlot(board, rect, { w: 1, h: 1 }) : { full: true };
+      const freeH = (rect && !spot.full) ? Math.max(0, Math.round(rect.y + rect.h - spot.y)) : 0;
+      return { name, about: sl.about || null, freeH, freeLines: Math.max(0, Math.floor((freeH - 8) / 26)) };
+    });
+    return {
+      id: s.id, x: s.x, y: s.y, w: s.w, h: s.h,
+      title: s.title, by: s.by, at: s.at,
+      count: members.length,
+      lastId: members.length ? members[members.length - 1].id : null,
+      freeH: Math.max(0, Math.round(inner.y + inner.h - bottom)),
+      innerW: inner.w,
+      slots,
+    };
+  });
+}
+
+/* ── 落位三动词（2026-08-29 刀 2：启发式引擎退役后仅存的三条几何规则）──
+ *
+ * 旧引擎（环搜/挑侧/半平面/走廊/兜底左缘）整层退役 —— ㉚ 五刀证明那一层的坑
+ * 修不完，且 agent 对「纸内绝对坐标」的适应性远好于「模糊锚点」。留下的规则
+ * 每条都短到不需要启发式：
+ *   placeAtOnSheet  agent 说了算（钳进版心，钳了如实报）
+ *   placeThread     接楼只有一个方向：正下方，压住就跳到那件底下
+ *   placeBeside     贴放是精确几何不是搜索（压上如实报，不代找洞）
+ */
+
+/**
+ * 纸内定点：局部坐标 → 世界坐标，钳进版心。钳过要如实报（越界钳住但要说）。
+ *
+ * `overflowY` = 从 agent 要的那个 y 往下**真的不够高**还差多少（2026-08-29 刀 C）。
+ * 站主定的换纸判据第一条就是"当前这块地放不下剩下一整块内容"—— 光说"钳住了"
+ * 不够，钳住的结果是那条被压到贴着纸底、跟上一条挤在一起，而 agent 完全不知道
+ * 该翻页了。
+ */
+export function placeAtOnSheet(s, at, box) {
+  const inner = innerRect(s);
+  const ideal = toWorld(s, { x: Math.round(at.x), y: Math.round(at.y) });
+  const x = Math.min(Math.max(ideal.x, inner.x), Math.max(inner.x, inner.x + inner.w - box.w));
+  const y = Math.min(Math.max(ideal.y, inner.y), Math.max(inner.y, inner.y + inner.h - box.h));
+  return {
+    x: Math.round(x), y: Math.round(y),
+    clamped: x !== ideal.x || y !== ideal.y,
+    overflowY: Math.max(0, Math.round(ideal.y + box.h - (inner.y + inner.h))),
+  };
+}
+
+/**
+ * 接楼（线程）：被回应那条的正下方；位置被占就跳到占位者底下接着试。
+ * 只往下 —— 读序即方向。落点出了所在纸的版心底 → 报 sheetFull（调用方翻纸）。
+ * 纸外（文件夹层/散地）没有纸界，滑到空为止。
+ */
+export function placeThread(board, replyRect, box, { obstacles = [], gap = UNIT } = {}) {
+  const sheet = sheetOfPoint(board, { x: replyRect.x + replyRect.w / 2, y: replyRect.y + replyRect.h / 2 });
+  const floor = sheet ? innerRect(sheet).y + innerRect(sheet).h : Infinity;
+  const x = Math.round(replyRect.x);
+  let y = replyRect.y + replyRect.h + gap;
+  for (let i = 0; i < 500; i += 1) {
+    if (y + box.h > floor) return { sheetFull: sheet.id };
+    const r = { x, y, w: box.w, h: box.h };
+    const hit = obstacles.find((o) => overlaps(r, o));
+    if (!hit) return { x, y: Math.round(y), sheetId: sheet?.id || null };
+    y = hit.y + hit.h + gap;
+  }
+  return { x, y: Math.round(y), sheetId: sheet?.id || null };
+}
+
+/** 贴放：锚点某一侧的精确位置（gap 像素）。不搜索 —— 压上由调用方如实报。 */
+export function placeBeside(anchor, box, side = 'right', gap = UNIT) {
+  const p = side === 'right' ? { x: anchor.x + anchor.w + gap, y: anchor.y }
+    : side === 'left' ? { x: anchor.x - gap - box.w, y: anchor.y }
+      : side === 'below' ? { x: anchor.x, y: anchor.y + anchor.h + gap }
+        : { x: anchor.x, y: anchor.y - gap - box.h };
+  return { x: Math.round(p.x), y: Math.round(p.y) };
+}
+
+/** 压上了谁（如实报的判据；调用方拿去写返回文案，不据此挪位置） */
+export function overlapIds(rect, obstacles, { pad = 0, limit = 6 } = {}) {
+  const out = [];
+  for (const o of obstacles) {
+    if (!overlaps(rect, o, pad)) continue;
+    if (o.id) out.push(o.id);
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+
+/**
+ * 精灵身位（从 board-place.js 搬来，2026-08-27 建）。角色精灵在客户端贴着该角色
+ * 最新一条板书摆，服务端只能把那条当带身位的障碍 —— 四周外扩 pad，新东西的
+ * 压上判定就不会压在精灵脸上。「最新」按 objects 插入序。
+ */
+export function inflateSpriteSeats(obstacles, objects, pad = 60) {
+  const last = new Map();
+  for (const [id, e] of Object.entries(objects || {})) {
+    if (typeof e?.by === 'string' && ROLE_SLUG_RE.test(e.by)) last.set(e.by, id);
+  }
+  if (!last.size) return obstacles;
+  const ids = new Set(last.values());
+  return obstacles.map((o) => (ids.has(o.id)
+    ? { ...o, x: o.x - pad, y: o.y - pad, w: o.w + pad * 2, h: o.h + pad * 2 }
+    : o));
+}
+
+/**
+ * 卷卡（RollLayer）占位估算（2026-08-29 刀 3）：卷卡是前端合成物不进 objects，
+ * 但它真占桌面一角 —— agent 要知道那儿有张卡。位置 = 成员左上角（前端同款），
+ * 尺寸按标签字数估（chip：padding + 文字）。成员座位本来就保留当障碍，这只是
+ * 让 read_board 能把「那张卷卡」点出来。
+ */
+export function rollCardRect(board, tag) {
+  const roll = board?.rolls?.[tag];
+  if (!roll) return null;
+  const members = Object.entries(board?.objects || {}).filter(([, e]) => e?.tag === tag && Number.isFinite(e?.x));
+  if (!members.length) return null;
+  const x = Math.min(...members.map(([, e]) => e.x));
+  const y = Math.min(...members.map(([, e]) => e.y));
+  const label = String(roll.label || tag);
+  const em = [...label].reduce((n, c) => n + (/[　-鿿＀-￯]/.test(c) ? 1 : 0.62), 0);
+  return { x: Math.round(x), y: Math.round(y), w: Math.round(48 + em * 15), h: 40 };
+}
+
+export { ZOOM_BASIS };

package/server/lib/board-shelf.js

@@ -0,0 +1,86 @@
+/**
+ * server/lib/board-shelf.js —— 暂存架（2026-08-30）
+ *
+ * 机器的手从此只够得到这条架：入座器/步骤镜像找不到 agent 规划的地
+ * （for:'artifacts' 版位、chalk 显式锚点）时，一律把东西码在这条竖带上 ——
+ * **绝不再铺纸，也绝不再往 agent 的纸面上顺排**。真案 proj_mtfz7n8p：web_search
+ * 采回的参考图撞进入座器的「开工例外」，第一张纸成了机器铺的，agent 从头到尾
+ * 不知道那张纸存在，自己的板书只能在缝里流。
+ *
+ * 架上的东西 seat:'shelf'。离架不靠第二份成员表：pin_to_board 写 seat:'agent'、
+ * edit_board move 写 seat:'agent'、用户拖拽写 seat:'user' —— 任何一只手一挪，
+ * seat 被改写，它就自然不在架上了（单一真相 = 座位出处字段本身）。
+ *
+ * 架的原点存 board.shelf {x,y}，立了就不挪；唯一的例外是**架带跟后来铺的纸
+ * 横向撞上**（agent 有权把纸开在任何地方），这时搬去纸群左侧重立 —— 判据是
+ * 整条竖带不是原点那一个点，见 bandHitsSheet。
+ */
+
+export const SHELF_W = 360;
+export const SHELF_GAP = 24;
+// 文件夹卡在架上的占地（数字对齐 web/src/lib/board-geometry.js 的 FOLDER_CARD ——
+// zones 存档只有坐标，尺寸恒为前端那份；这里只用来算架上的避让）
+export const FOLDER_BOX = { w: 288, h: 240 };
+
+/**
+ * 架带跟这张纸撞不撞。**架不是原点那一个点，是从原点往下的一条竖带**
+ * （宽 SHELF_W，向下不封口）。
+ *
+ * 原来这儿测的是「原点这个点落没落进纸里」，于是架立在纸群**正上方**时
+ * 永远判不出冲突，然后顺着这条带一路往下长穿每一张纸。真案 proj_mtg61or1：
+ * 架原点 (24,24) 在 p1 上方 1464px，四张纸一张都没"压住"它，但架带 x[24,384)
+ * 跟四张纸的横向重叠率是 100% —— agent 写的板书全从 x=24 起排，42 个根层
+ * 对象里 38 个压在架带上，架被自己码的货一路顶到 y=8322（板子才高 2600）；
+ * 反过来铺新纸又要躲开架上的散件，纸也被顶着往下走（p3 底 3805 → p4 顶 4621）。
+ * 两边互相顶，板子只会单向长高。
+ */
+const bandHitsSheet = (s, x, y) => s.x < x + SHELF_W && s.x + s.w > x && s.y + s.h > y;
+
+/**
+ * 架的原点。已立的沿用（除非架带跟纸撞上）；没立过的：有纸靠纸群左上侧，
+ * 没纸落在用户视口左上（到货要让用户看得见）。
+ * @param {object} board
+ * @param {{x,y,w,h}|null} viewport 用户相机（根层才传）
+ * @returns {{x:number,y:number,changed:boolean}}
+ */
+export function resolveShelfOrigin(board, viewport = null) {
+  const sheets = Object.values(board.sheets || {})
+    .filter(s => Number.isFinite(s?.x) && Number.isFinite(s?.y) && Number.isFinite(s?.w) && Number.isFinite(s?.h));
+  const cur = board.shelf;
+  if (cur && Number.isFinite(cur.x) && Number.isFinite(cur.y) && !sheets.some(s => bandHitsSheet(s, cur.x, cur.y))) {
+    return { x: cur.x, y: cur.y, changed: false };
+  }
+  if (sheets.length) {
+    const minX = Math.min(...sheets.map(s => s.x));
+    const minY = Math.min(...sheets.map(s => s.y));
+    return { x: Math.round(minX - SHELF_W - SHELF_GAP), y: Math.round(minY), changed: true };
+  }
+  if (viewport && Number.isFinite(viewport.x) && Number.isFinite(viewport.y)) {
+    return { x: Math.round(viewport.x + SHELF_GAP), y: Math.round(viewport.y + SHELF_GAP), changed: true };
+  }
+  return { x: SHELF_GAP, y: SHELF_GAP, changed: true };
+}
+
+/**
+ * 架上下一个空位：从原点往下码。占位判据是「矩形横向压进架带」，不看 seat ——
+ * 用户拖了张卡堵在架上，新到的也得往下让，压上去才是数据损坏。
+ * @param {{x,y}} origin
+ * @param {Array<{x,y,w,h}>} obstacles 同层全部已摆矩形
+ */
+export function nextShelfSpot(origin, obstacles) {
+  let bottom = origin.y;
+  for (const o of obstacles || []) {
+    if (!Number.isFinite(o?.x) || !Number.isFinite(o?.y)) continue;
+    if (o.x + (o.w || 0) <= origin.x || o.x >= origin.x + SHELF_W) continue;
+    if (o.y + (o.h || 0) <= origin.y) continue;
+    bottom = Math.max(bottom, o.y + (o.h || 0) + SHELF_GAP);
+  }
+  return { x: origin.x, y: Math.round(bottom) };
+}
+
+/** 架上现有的东西（根层、seat:'shelf' 的画布 id 列表，登记序） */
+export function shelfItems(board) {
+  return Object.entries(board.objects || {})
+    .filter(([, e]) => e?.seat === 'shelf' && !e.zone && Number.isFinite(e.x))
+    .map(([id]) => id);
+}

package/server/lib/board-transform.js

@@ -0,0 +1,62 @@
+/**
+ * server/lib/board-transform.js —— 整组缩放/旋转（2026-08-30 画图能力线）
+ *
+ * 画完一幅想整体缩小/转个角度，此前只能逐笔挪。以组（tag）为单位绕组心变换：
+ *   - 涂鸦（scribble）**真变形**：d 逐点过矩阵、包围盒重建 —— 线条真的转过去
+ *   - 其他成员（text/板书/产物卡）**只换座不变形**：字号和卡面没有"转 30°"的
+ *     渲染语义，硬转是把问题藏起来 —— 中心点跟着矩阵走、如实报"这几件只挪了位"
+ *
+ * 纯函数：算出 objects patch 交回，落盘归调用方（edit-board）。
+ */
+
+import { transformD } from './sketch-layout.js';
+
+/**
+ * @param members  [{id, entry, w, h}]（w/h 是估好的真尺寸）
+ * @param opts     { scale?: 0.3..3, rotate?: 度, about?: {x,y} 世界像素（缺省组心）}
+ * @returns {{ patch: Record<string, object>, inked: number, seated: number, center: {x,y} }}
+ */
+export function transformGroup(members, { scale = 1, rotate = 0, about = null } = {}) {
+  const minX = Math.min(...members.map((m) => m.entry.x));
+  const minY = Math.min(...members.map((m) => m.entry.y));
+  const maxX = Math.max(...members.map((m) => m.entry.x + m.w));
+  const maxY = Math.max(...members.map((m) => m.entry.y + m.h));
+  const C = about || { x: (minX + maxX) / 2, y: (minY + maxY) / 2 };
+  const th = (rotate * Math.PI) / 180;
+  const cos = Math.cos(th); const sin = Math.sin(th);
+  const T = (p) => ({
+    x: C.x + ((p.x - C.x) * cos - (p.y - C.y) * sin) * scale,
+    y: C.y + ((p.x - C.x) * sin + (p.y - C.y) * cos) * scale,
+  });
+
+  const patch = {};
+  let inked = 0; let seated = 0;
+  for (const m of members) {
+    const e = m.entry;
+    if (m.id.startsWith('scribble:') && typeof e?.data?.d === 'string') {
+      let mnX = Infinity; let mnY = Infinity; let mxX = -Infinity; let mxY = -Infinity;
+      const dAbs = transformD(e.data.d, (p) => {
+        const q = T({ x: e.x + p.x, y: e.y + p.y });
+        if (q.x < mnX) mnX = q.x; if (q.x > mxX) mxX = q.x;
+        if (q.y < mnY) mnY = q.y; if (q.y > mxY) mxY = q.y;
+        return q;
+      });
+      if (!Number.isFinite(mnX)) { seated += 1; continue; }
+      const P = 6;
+      const d = transformD(dAbs, (p) => ({ x: p.x - mnX + P, y: p.y - mnY + P }));
+      patch[m.id] = {
+        ...e, x: Math.round(mnX - P), y: Math.round(mnY - P),
+        w: Math.max(4, Math.round(mxX - mnX + P * 2)), h: Math.max(4, Math.round(mxY - mnY + P * 2)),
+        data: { ...e.data, d },
+      };
+      inked += 1;
+    } else {
+      // 只换座：中心过矩阵，尺寸不动
+      const c0 = { x: e.x + m.w / 2, y: e.y + m.h / 2 };
+      const c1 = T(c0);
+      patch[m.id] = { ...e, x: Math.round(c1.x - m.w / 2), y: Math.round(c1.y - m.h / 2) };
+      seated += 1;
+    }
+  }
+  return { patch, inked, seated, center: { x: Math.round(C.x), y: Math.round(C.y) } };
+}

package/server/lib/canvas-id.js

@@ -22,7 +22,24 @@ export function normalizeCanvasId(raw) {
  * 返回 { x, y, w, h, anchorId, ids } 或 null；anchorId = 最右那个（贴右侧摆用）。
  * sizeOf(id, entry) 由调用方给（estimateSizeOn 绑着 board，不在这层 import）。
  */
-export function tagEnvelope(board, tag, sizeOf) {
+/**
+ * 查 tag 时的归一：剥掉前导 `#`（2026-08-30）。
+ *
+ * ⛔ 我们在 write_on_board 的 `near`、read_board 的 `tag` 等好几处描述里明写
+ * 「Canvas id or **#tag**」，而查询侧一直是 `e.tag === raw` 精确比对，从来没剥过
+ * 这个井号 —— 全库统计：带 # 的写法 5 处，5 处全废；不带 # 的 2773 处全通。
+ * 「注释/描述声称做了、代码没做」的第三例。
+ *
+ * 只用在**查**的一侧。写的一侧（write_on_board 的 tag 参数）走 TAG_RE，本来就
+ * 收不下 # —— 那是 schema 报错，是响的，不用管。
+ */
+export function bareTag(raw) {
+  return String(raw ?? '').trim().replace(/^#+/, '');
+}
+
+export function tagEnvelope(board, rawTag, sizeOf) {
+  const tag = bareTag(rawTag);
+  if (!tag) return null;
   const hits = Object.entries(board?.objects || {})
     .filter(([, e]) => e?.tag === tag && Number.isFinite(e?.x));
   if (!hits.length) return null;