@xiaobuyu/nodesign 0.0.6 → 0.0.8

package/server/engine/mcp/tools/browse.js

@@ -121,7 +121,7 @@ and reopens on the next call — the profile survives, so you stay logged in.
 The user has a browser card on their desktop and can watch, or take over.`,
     {
       url: z.string().min(4).describe('Absolute http(s) URL.'),
-      waitUntil: z.enum(['domcontentloaded', 'load', 'networkidle']).optional()
+      waitUntil: z.enum(['commit', 'domcontentloaded', 'load', 'networkidle']).optional()
         .describe("How long to wait. Default 'domcontentloaded' — fastest and enough to read; measured on this machine, 'networkidle' costs an extra 1.6-4s per page, so do not reach for it by reflex. Use it only when a JS-built page comes back empty."),
       digest: z.boolean().optional()
         .describe('Include the page digest (default true). Set false only when you are navigating purely to screenshot and do not want the text.'),
@@ -175,9 +175,31 @@ The user has a browser card on their desktop and can watch, or take over.`,
             ].filter(Boolean).join('\n'), true);
           }
           if (navErr) {
+            // 超时 ≠ 全失败：commit 之后页面往往已有内容。半张页面也交回去 ——
+            // agent 拿到骨架就能决定继续还是换站（08-19 上报：原建议「试
+            // waitUntil:"load"」是往错方向推 —— load 比 domcontentloaded 严，
+            // 连 DOMContentLoaded 都没到换 load 只会更慢地再失败一次）
+            const timedOut = /Timeout/i.test(navErr);
+            let landedUrl = null;
+            try { const u = page.url(); if (timedOut && u !== before && /^https?:/.test(u)) landedUrl = u; } catch { /* */ }
+            if (landedUrl) {
+              let lines = [];
+              try {
+                const data = await collectPage(page);
+                if (!data.missing) lines = formatPage(data, { compact: true });
+              } catch { /* 半张页面读不出摘要也照样交回 */ }
+              try { ctx?.emit?.({ type: 'run.browser_opened', url: landedUrl, ts: new Date().toISOString() }); } catch { /* */ }
+              return asText([
+                `⚠️ 等待超时（${navErr}），但页面已部分加载 —— 当前状态如下，够用就继续（read/screenshot 都可），不够就换站：`,
+                ...lines,
+                gate,
+              ].filter(Boolean).join('\n'));
+            }
             return asText([
               `导航失败：${navErr}`,
-              '如果是超时：站点可能慢或者在挡自动化访问；试 waitUntil:"load"，或者换一个参考站。',
+              timedOut
+                ? '超时多半是广告/追踪脚本卡死或站点反自动化，不是"等得不够久"。别换 waitUntil:"load"（更严只会更慢地失败）；可试 waitUntil:"commit"（一有响应就接手，配 read/screenshot 看拿到多少），或者直接换一个参考站。'
+                : '站点可能在挡自动化访问；换一个参考站。',
               gate,
             ].filter(Boolean).join('\n'), true);
           }
@@ -436,7 +458,7 @@ about why they were taken is landfill.`,
             normalize: normalizeShot,
           });
           for (const f of r.files) {
-            try { ctx?.emit?.({ type: 'run.file_changed', path: f.rel, change: 'add' }); } catch { /* */ }
+            try { ctx?.emit?.({ type: 'run.file_changed', filePath: f.rel, event: 'add' }); } catch { /* */ }
           }
           const lines = [`从 ${r.data.title || r.data.url} 采下来了：`];
           for (const f of r.files) lines.push(`  ${f.rel}（${(f.bytes / 1024).toFixed(0)} KB，${f.kind}）`);

package/server/engine/mcp/tools/cast-role.js

@@ -0,0 +1,167 @@
+/**
+ * mcp/tools/cast-role.js — cast_role MCP tool（2026-08-26 建；2026-08-28 演员位重构重写）
+ *
+ * ## 重写前后
+ *
+ * 旧语义：写 `.claude/agents/rp-<id>.md`（一角色一个子代理定义），派发要等 CLI 重扫。
+ * ⛔ 那条路 08-28 勘定为生产不可靠：会话中途写入的定义文件只有**写入时活着的那个
+ * CLI 进程**认得（chokidar 事件），resume 换进程后永久 `not found`（三场真会话：
+ * 12 连败 / 恰好成功 / 永久失明）。等待、轮询、公告续接五版都救不了，全史见 git
+ * 里本文件的旧版头注。
+ *
+ * 新语义：角色卡是**数据**，子代理是**预注册的演员位**（rp-actor / rp-narrator，
+ * 建项目时就落盘，见 cast.js slotAgentFile）。cast_role 只做两件事：
+ *   1. 把人设写成 `角色/<名>/角色卡.md`（用户在画布上看得见、随时能改的文件夹范式）
+ *   2. 在 `.nd/cast.json` 登记 slug → 展示名/笔权/卡路径（板书署名与名册 API 的展示源）
+ * 写完**当回合就能派**：Agent(subagent_type: 演员位, name: "rp-<id>", prompt: 卡)。
+ *
+ * 登记不是上场的前置（不登记直接派也行），它换来的是：板上署名是「程晚」不是
+ * slug、重启后按卡重新开演有据可查、用户能在角色文件夹里改人设。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { ROLE_PREFIX, ROLE_SLOT, isSlotType, isValidRoleSlug } from '../../agent/cast.js';
+import { readCastRegistry } from '../../agent/role-card.js';
+
+/** 角色 id（不含 rp- 前缀）：ASCII、能当文件名、能当 SendMessage 收件人名。
+ *  ⚠️ 这是 cast.js `ROLE_SLUG_RE` 的**收紧子集**（这边只许小写、≥2 字符）——
+ *  两个判据的蕴含关系（ID_RE 过的 id 拼上前缀必被 ROLE_SLUG_RE 认）由
+ *  cast-role.test.js 钉着；改任何一边先看那条测试。导出仅供测试。 */
+export const ID_RE = /^[a-z0-9][a-z0-9_-]{1,40}$/;
+
+const ROLES_DIR = '角色';
+const REGISTRY_REL = '.nd/cast.json';
+const PERSONA_MAX = 20000;
+
+/** 自由文本压一行：控制字符/行终止符全清（进 JSON 与返回话术都安全） */
+function oneLine(v, max) {
+  return String(v ?? '')
+    .replace(/[\r\n\u2028\u2029]+/g, ' ')
+    .replace(/[\u0000-\u001f\u007f]/g, '')
+    .trim().slice(0, max);
+}
+
+/** 展示名 → 文件夹名：剥路径分隔与点前缀，空了退回 slug（文件夹名坏不了路径） */
+function folderNameFor(displayName, slug) {
+  const cleaned = oneLine(displayName, 40).replace(/[\/\\]/g, '').replace(/^\.+/, '').trim();
+  return cleaned || slug;
+}
+
+export function makeCastRoleTool({ workspaceRoot, sessionId = null, ctx, roster = null }) {
+  void sessionId; void roster;   // 旧签名的调用方兼容位（公告续接与回合闸已随重构退役）
+  return tool(
+    'cast_role',
+    `Register a character card so this person has a fixed identity to act from.
+
+Writes the card to ${ROLES_DIR}/<name>/角色卡.md (user-visible, user-editable) and records
+the display name. The card is DATA, and in this build it is a reference for YOU:
+character subagents are disabled, so you write everyone on stage yourself.
+
+Use it for anyone who has a name, will show up again, and whom the user may want to talk
+to. Re-read the card right before you write that person's lines — that is the thing that
+keeps several characters from all sounding like you. A walk-on with one line needs no card.
+
+⛔ Do NOT dispatch a role subagent after this: no Agent(subagent_type: "${ROLE_SLOT}"),
+no SendMessage to a character. That path is being debugged; the cards you write now will
+plug straight back in once it returns.
+When the user hands you a ready-made character card, prefer copying it in verbatim over
+rewriting it.`,
+    {
+      id: z.string().describe('ASCII slug, no prefix: lowercase letters/digits/_/- , 2-41 chars. Becomes the address (rp-<id>).'),
+      name: z.string().min(1).max(40).describe('Display name, any language — what this character is actually called. Board signatures use it.'),
+      duty: z.string().min(1).max(400).describe('One line: who this is and when you would talk to them.'),
+      persona: z.string().min(1).describe("The card itself: who this person is, how they speak, what they would never do, plus two or three short samples of their voice. You read this back before writing their lines, so write it for that use — no meta rules about who writes what."),
+    },
+    async (args) => {
+      const fail = (msg) => ({ content: [{ type: 'text', text: msg }], isError: true });
+      if (!workspaceRoot) return fail('没有工作区，cast_role 不可用。');
+
+      const id = String(args.id || '').trim();
+      if (!ID_RE.test(id)) {
+        return fail(`角色 id「${id}」不合法：只能用小写字母、数字、下划线、连字符，2-41 个字符，首字符是字母或数字。`
+          + `（这个 id 要当 SendMessage 的收件人名，收件人名不收中文和空格 —— 中文名字放 name 参数。）`);
+      }
+      const slug = `${ROLE_PREFIX}${id}`;
+      if (!isValidRoleSlug(slug) || isSlotType(slug)) return fail(`角色名「${slug}」过不了名册校验（演员位的名字不能当角色名）。`);
+
+      const displayName = oneLine(args.name, 40);
+      if (!displayName) return fail('name 清洗后是空的 —— 换个展示名。');
+      const persona = String(args.persona || '').trim();
+      if (!persona) return fail('persona 是空的 —— 角色卡就是这个角色的全部身份，不能空。');
+      if (persona.length > PERSONA_MAX) {
+        return fail(`persona 有 ${persona.length} 字符，超过 ${PERSONA_MAX} 上限。`
+          + `把大部头设定挪进世界书/设定文件让角色自己 grep，卡上留人设主干。`);
+      }
+
+      // 卡落盘：角色/<名>/角色卡.md（文件夹范式：这个文件夹就是该角色的家，
+      // 之后的记忆/日记等件都住这里；用户随时可改，改动对"下次派发/唤醒后重读卡"生效）
+      const folder = folderNameFor(displayName, slug);
+      const dir = path.join(workspaceRoot, ROLES_DIR, folder);
+      const file = path.join(dir, '角色卡.md');
+      if (!path.resolve(file).startsWith(path.resolve(workspaceRoot, ROLES_DIR) + path.sep)) {
+        return fail('角色卡路径异常，拒绝写入。');
+      }
+      // 一个家只住一个角色（2026-08-28 对账发现）：文件夹按展示名取，两个不同的
+      // slug 用同一个展示名就会共用 角色/<名>/ —— 卡被后来者覆盖，**记忆.md 也共用**，
+      // 于是 A 的 jot_memory 写进 B 的记忆里，谁都不会发现。堵在写口，不是在
+      // roleHomeDir 那头兜（判据别建在模型可写的登记表上）。
+      // 同一个 slug 重登（改卡）不受影响 —— 那本来就是同一个人。
+      const claimedBy = Object.entries((await readCastRegistry(workspaceRoot)).roles || {})
+        .find(([s2, e2]) => s2 !== slug && typeof e2?.card === 'string'
+          && e2.card.split('/').slice(0, 2).join('/') === `${ROLES_DIR}/${folder}`);
+      if (claimedBy) {
+        return fail(`「${displayName}」这个家已经是 ${claimedBy[0]} 的了（角色/${folder}/）。`
+          + `同名两个角色会共用角色卡和记忆件 —— 换个展示名，`
+          + `或者你要的其实是同一个人的话，用 ${claimedBy[0]} 这个名字重登（改卡就是重登同一个 slug）。`);
+      }
+      let existed = false;
+      try { await fs.access(file); existed = true; } catch { /* 新角色 */ }
+      await fs.mkdir(dir, { recursive: true });
+      // 记忆件骨架（只在不存在时铺）：角色 jot_memory 追加，用户/GM 可整理
+      const memFile = path.join(dir, '记忆.md');
+      try { await fs.access(memFile); } catch {
+        await fs.writeFile(memFile, `# 记忆\n\n<!-- ${slug} 的记忆：角色自己 jot_memory 追加，用户和 GM 可整理改写。还是空的。 -->\n`, 'utf8');
+      }
+      await fs.writeFile(file, [
+        `# ${displayName}`,
+        '',
+        `<!-- ${slug} · cast_role 登记。`,
+        '     正文就是角色的人设，派发时全文随 prompt 进入角色 —— 想改人设直接改这里，',
+        '     对已在场的角色用 SendMessage 告知，对下次开演自动生效。 -->',
+        '',
+        persona,
+        '',
+      ].join('\n'), 'utf8');
+
+      // 登记表：板书署名与名册 API 的展示名来源（fail-soft：登记坏了不拦上场）
+      const cardRel = path.join(ROLES_DIR, folder, '角色卡.md');
+      try {
+        const reg = await readCastRegistry(workspaceRoot);
+        reg.roles[slug] = { name: displayName, duty: oneLine(args.duty, 400), card: cardRel };
+        await fs.mkdir(path.join(workspaceRoot, '.nd'), { recursive: true });
+        await fs.writeFile(path.join(workspaceRoot, REGISTRY_REL), JSON.stringify(reg, null, 2), 'utf8');
+      } catch { /* 展示层，坏了角色照样能上场（署名退回 slug） */ }
+
+      try { ctx?.emit?.({ type: 'run.role_cast', slug, name: displayName }); } catch { /* 事件失败不挡正事 */ }
+
+      // ⚠️ 这段话和工具 description 是**同一条教义的两个读者**，改一头必须改另一头 ——
+      // 08-30 停用子代理那一刀只改了 description，这里还留着「现在就可以派它上场」，
+      // 而返回文案离模型的下一个动作更近，等于白改（fable 评审当场抓到）。
+      const lines = [
+        `${existed ? '改写' : '写好'}了角色卡「${displayName}」→ ${cardRel}（登记为 ${slug}）`,
+        '',
+        `⛔ **不要派子代理**：这一版角色由你自己演，`
+        + `Agent(subagent_type: "${ROLE_SLOT}") 和 SendMessage 给角色这两条路正在调试。`,
+        `轮到「${displayName}」说话时，**先 Read 一遍 ${cardRel}** 把腔调找回来，再由你写他这一段。`,
+        `几个人同场就一个个来，每人开口前各读各的卡 —— 这是防止全场一个腔的正事。`,
+      ];
+      if (existed) {
+        lines.push('', '⚠️ 卡改了，下次写他的话之前重新 Read 一遍 —— 你上下文里那份是旧的。');
+      }
+      return { content: [{ type: 'text', text: lines.join('\n') }] };
+    },
+  );
+}

package/server/engine/mcp/tools/crystallize-skill.js

@@ -9,7 +9,7 @@
  * （~/.nodesign/plugins/<userId>/<name>/），下次开新会话在**这个用户的所有项目**里
  * 都能用（plugin 发现是 startup-time，当前会话不生效）。
  *
- * 跟 record_decision 的分工：决策贴是**这一件作品**的过程档案，随任务走；
+ * 跟长期记忆（记忆/ + 根 CLAUDE.md）的分工：记忆记的是**这个项目/这位用户**的持续状态，随项目走；
  * 这里是跨项目复用的方法论，随用户走。一个是日志，一个是沉淀。
  *
  * 归属：写到**项目 owner** 的目录，不是"当前请求者"——同一个项目谁跑都该产出同一

package/server/engine/mcp/tools/draw-trend.js

@@ -0,0 +1,104 @@
+/**
+ * mcp/tools/draw-trend.js —— `draw_trend`：状态表历史 → 手绘趋势线
+ * （2026-08-30 画图能力线·「活图」第一块）
+ *
+ * 数据不用记：状态表住在板书文件里、文件进 git、**每回合落一个 commit** ——
+ * 「好感度随拍数怎么走」的序列是现成的，git 就是时间轴（lib/state-trend.js）。
+ *
+ * 重画语义：同 key 再调一次 = 原地重画（旧的擦掉、**位置保留** —— 用户拖过它
+ * 摆在哪就还在哪）。所以每拍 set_vars 之后想让曲线长一格，再调一次就行。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { readBoard, patchBoard, removeByTag } from '../../../projects/board-store.js';
+import { trendSeries, trendGeometry } from '../../../lib/state-trend.js';
+import { roughFreePath, textBox } from '../../../lib/sketch-layout.js';
+import { KEY_MAX } from '../../../lib/state-table.js';
+import { currentSheet, toWorld } from '../../../lib/board-sheets.js';
+import { currentSheetIdOf } from '../../../lib/sheet-state.js';
+import { estimateSizeOn } from '../../../lib/board-kind-sizes.js';
+import { Events } from '../../agent/events.js';
+
+let seq = 0;
+const stamp = () => `${Date.now().toString(36)}${(seq++ % 1000).toString(36)}`;
+
+export function makeDrawTrendTool({ projectId, sharedRoot, sessionId, ctx }) {
+  return tool(
+    'draw_trend',
+    `Draw a hand-inked trend line of one state-table key over the story so far — 好感度
+climbing across eight beats, HP bleeding down. The series comes from the workspace's
+git history (one commit per turn), so there is nothing to record: if the number lived
+in the state table, its past is already there. Call it again after set_vars and the
+chart redraws IN PLACE (position kept, even if the user dragged it). Needs ≥2 numeric
+points — early beats will refuse loudly, that is normal.`,
+    {
+      key: z.string().min(1).max(KEY_MAX).describe('Which state-table key to chart (must hold numbers — 8/10 counts as 8)'),
+      at: z.object({ x: z.number().min(0).max(12000), y: z.number().min(0).max(12000) }).optional()
+        .describe('Sheet-local pixels for first placement. Omit it: lands under the state-table card (or where the previous chart of this key sits)'),
+    },
+    async (args) => {
+      const err = (t) => ({ content: [{ type: 'text', text: t }], isError: true });
+      if (!projectId) return err('No project bound.');
+      const s = await trendSeries(sharedRoot, args.key);
+      if (!s.ok) return err(`⛔ ${s.why}`);
+
+      const g = trendGeometry(s.points);
+      const tag = `trend-${args.key}`.slice(0, 40);
+      const board = await readBoard(projectId);
+
+      // 落点：旧图原位 > at（纸内像素） > 状态表卡正下方
+      let origin = null;
+      const prev = Object.entries(board.objects || {}).filter(([, e]) => e?.tag === tag && Number.isFinite(e?.x));
+      if (prev.length) {
+        origin = { x: Math.min(...prev.map(([, e]) => e.x)), y: Math.min(...prev.map(([, e]) => e.y)) };
+        await removeByTag(projectId, tag);
+      } else if (args.at) {
+        const sheet = currentSheet(board, currentSheetIdOf(sessionId));
+        if (!sheet) return err('还没有纸 —— 先 open_sheet，或者省掉 at 让它落在状态表卡下面。');
+        origin = toWorld(sheet, args.at);
+      } else {
+        const e = board.objects?.[s.rel];
+        if (!e || !Number.isFinite(e.x)) {
+          return err(`状态表那条板书（${s.rel}）不在板上（没有座位）—— 传 at:{x,y}（纸内像素）指个位置。`);
+        }
+        const sz = estimateSizeOn(board, s.rel, e);
+        origin = { x: e.x, y: e.y + sz.h + 16 };
+      }
+
+      // 标签在图上方一行；曲线 ink、基线 pencil、现值小圈 red —— 全过同一支抖动笔
+      const label = `${args.key}  ${s.points[0]} → ${s.points[s.points.length - 1]}（${s.points.length} 拍，${g.min}~${g.max}）`;
+      const lb = textBox(label, 'sm');
+      const seed = `trend:${args.key}`;
+      const objects = {
+        [`text:a${stamp()}`]: {
+          x: Math.round(origin.x), y: Math.round(origin.y), w: lb.w, h: lb.h, z: 1, kind: 'text',
+          data: { t: label, font: 'kai', size: 'sm' }, zone: '', by: 'agent', seat: 'agent', tag,
+        },
+        [`scribble:a${stamp()}`]: {
+          x: Math.round(origin.x), y: Math.round(origin.y + lb.h + 4), w: g.w, h: g.h, z: 1, kind: 'scribble',
+          data: { d: roughFreePath(g.baselineD, `${seed}:base`), color: 'pencil', width: 1 }, zone: '', by: 'agent', seat: 'agent', tag,
+        },
+        [`scribble:b${stamp()}`]: {
+          x: Math.round(origin.x), y: Math.round(origin.y + lb.h + 4), w: g.w, h: g.h, z: 1, kind: 'scribble',
+          data: { d: roughFreePath(g.lineD, `${seed}:line`), color: 'ink', width: 2 }, zone: '', by: 'agent', seat: 'agent', tag,
+        },
+        [`scribble:c${stamp()}`]: {
+          x: Math.round(origin.x), y: Math.round(origin.y + lb.h + 4), w: g.w, h: g.h, z: 1, kind: 'scribble',
+          data: { d: g.dotD, color: 'red', width: 2 }, zone: '', by: 'agent', seat: 'agent', tag,
+        },
+      };
+      await patchBoard(projectId, { objects });
+      const rect = { x: Math.round(origin.x), y: Math.round(origin.y), w: g.w, h: g.h + lb.h + 4 };
+      try {
+        ctx?.emit?.({ type: 'board.updated', sessionId: null, summary: `画了 ${args.key} 的趋势线` });
+        ctx?.emit?.(Events.boardFocus(rect, { tag, layer: '', soft: true }));
+      } catch { /* fail-soft */ }
+      return { content: [{ type: 'text', text:
+        `Trend #${tag}: ${s.points.length} points (${s.points.join(' → ')}), range ${g.min}~${g.max}, `
+        + `at (${rect.x},${rect.y}) ${rect.w}x${rect.h}${prev.length ? ' — redrawn in place' : ''}.\n`
+        + `Call draw_trend again after set_vars to grow it; move/group it like any sketch (tag #${tag} — `
+        + `edit_board follow can pin it to the 状态板 group).` }] };
+    },
+  );
+}

package/server/engine/mcp/tools/edit-board-schema.js

@@ -0,0 +1,56 @@
+/**
+ * edit_board 的 ops schema（2026-08-30 从 edit-board.js 拆出 —— 行数棘轮）。
+ * 纯数据；弱模型方言垫片（$text 剥壳）与坐标钳制都住在这里。
+ */
+
+import { z } from 'zod';
+import { BINDING_TYPE_IDS, BINDING_MATERIALS } from '../../../lib/binding-types.js';
+import { SLOT } from './open-sheet.js';
+
+const clampTo = (lo, hi) => (v) => (typeof v === 'number' && Number.isFinite(v) ? Math.max(lo, Math.min(hi, v)) : v);
+const GAP = z.preprocess(clampTo(0, 400), z.number().min(0).max(400));
+const PX_DELTA = z.preprocess(clampTo(-20000, 20000), z.number().min(-20000).max(20000));
+/** 弱模型方言垫片：免费档模型给字符串字段裹 {$text:"…"} 壳（27/61 条真实错误，
+ *  且读不懂 zod 报文会原样重试到死）。单键 $text 自动剥壳，合法对象碰不到。 */
+const unwrapText = (v) => (v && typeof v === 'object' && !Array.isArray(v)
+  && typeof v.$text === 'string' && Object.keys(v).length === 1) ? v.$text : v;
+const ENDPOINT = z.preprocess(unwrapText, z.string().min(1).max(300));
+
+const REL = z.object({
+  ref: z.string().min(1).max(300).describe('canvas id to place relative to'),
+  side: z.enum(['right', 'left', 'above', 'below']),
+  gap: GAP.optional().describe('PIXELS of breathing room between the two (default 24, max 400) — same unit as every position you read back'),
+});
+const DELTA = z.object({ dx: PX_DELTA, dy: PX_DELTA }).describe('PIXELS to shift by (+x right, +y down) — the same pixels read_board reports');
+// 纸内绝对坐标（2026-08-29 纸范式）：以某张纸版心左上为原点的像素。sheet 缺省 = 当前纸
+const ABS = z.object({
+  x: z.preprocess((v) => (typeof v === 'number' && Number.isFinite(v) ? Math.max(0, Math.min(12000, v)) : v), z.number().min(0).max(12000)),
+  y: z.preprocess((v) => (typeof v === 'number' && Number.isFinite(v) ? Math.max(0, Math.min(12000, v)) : v), z.number().min(0).max(12000)),
+  sheet: z.string().max(40).optional().describe('which sheet these pixels are on (default the current one)'),
+}).describe("PIXELS from a sheet's top-left writable corner — exact placement, you own the layout");
+const TO = z.union([REL, ABS, DELTA]);
+
+export const OP = z.discriminatedUnion('op', [
+  z.object({ op: z.literal('set_text'), id: z.string().min(1).max(300), text: z.string().min(1).max(8000).optional(), format: z.enum(['plain', 'md']).optional(), size: z.enum(['sm', 'md', 'lg', 'xl']).optional(), color: z.enum(['ink', 'red', 'pencil', 'brass']).optional(), font: z.enum(['pen', 'kai', 'sans', 'serif', 'mono']).optional() }),
+  z.object({ op: z.literal('move'), id: z.string().min(1).max(300), to: TO }),
+  z.object({ op: z.literal('move_group'), tag: z.string().min(1).max(40), to: TO }),
+  z.object({ op: z.literal('remove'), id: z.string().min(1).max(300) }),
+  z.object({ op: z.literal('add_node'), id: z.string().regex(/^[A-Za-z0-9_-]{1,24}$/).optional().describe('local handle for later ops of this call'), text: z.string().min(1).max(8000), format: z.enum(['plain', 'md']).optional(), size: z.enum(['sm', 'md', 'lg', 'xl']).optional(), font: z.enum(['pen', 'kai', 'sans', 'serif', 'mono']).optional(), color: z.enum(['ink', 'red', 'pencil', 'brass']).optional(), at: REL, tag: z.string().max(40).optional() }),
+  z.object({ op: z.literal('add_shape'), kind: z.enum(['rect', 'ellipse', 'circle', 'underline']), around: z.string().min(1).max(300).describe('canvas id to wrap/underline — the mark HUGS it and follows when it moves'), color: z.enum(['ink', 'red', 'pencil', 'brass']).optional(), width: z.number().min(1).max(12).optional(), tag: z.string().max(40).optional() }),
+  z.object({ op: z.literal('set_shape'), id: z.string().min(1).max(300), color: z.enum(['ink', 'red', 'pencil', 'brass']).optional(), width: z.number().min(1).max(12).optional() }),
+  z.object({ op: z.literal('add_edge'), from: ENDPOINT, to: ENDPOINT, type: z.enum(BINDING_TYPE_IDS).optional(), material: z.enum(BINDING_MATERIALS).optional(), label: z.string().max(60).optional(), tag: z.string().max(40).optional() }),
+  z.object({ op: z.literal('set_edge'), id: z.string().min(1).max(300), label: z.string().max(60).optional(), type: z.enum(BINDING_TYPE_IDS).optional(), material: z.enum(BINDING_MATERIALS).optional(), from: ENDPOINT.optional().describe('re-point the line: new source end'), to: ENDPOINT.optional().describe('re-point the line: new target end') }),
+  z.object({ op: z.literal('remove_edge'), id: z.string().min(1).max(300) }),
+  z.object({ op: z.literal('reflow'), tag: z.string().min(1).max(40), layout: z.enum(['column', 'row']).optional().describe('default column: restack the group in reading order with real sizes (use after set_text changes heights)') }),
+  z.object({ op: z.literal('follow'), group_tag: z.string().min(1).max(40).describe('the group that should follow (e.g. a status panel)'), target_tag: z.string().min(1).max(40).describe('whenever a new item with this tag lands, the group auto-moves beside it and the anchor line re-points'), side: z.enum(['right', 'left', 'above', 'below']).optional(), label: z.string().max(60).optional() }),
+  z.object({ op: z.literal('unfollow'), group_tag: z.string().min(1).max(40) }),
+  z.object({ op: z.literal('commit'), tag: z.string().max(40).optional().describe('make staging solid; omit tag = everything staging') }),
+  z.object({ op: z.literal('erase_group'), tag: z.string().min(1).max(40).describe('delete the whole tagged group (notes/shapes/lines; artifact cards only lose the tag)') }),
+  z.object({ op: z.literal('roll'), tag: z.string().min(1).max(40).describe('STOW a finished group: hides it behind a compact scroll card, everything kept in place (seats reserved, files intact, one click to unroll). For a scene/act/chapter that is DONE — use erase_group only to destroy'), label: z.string().max(60).optional().describe('scroll card title (default: the tag)') }),
+  z.object({ op: z.literal('unroll'), tag: z.string().min(1).max(40).describe('expand a rolled group back — everything returns to its original seat') }),
+  z.object({ op: z.literal('feature'), id: z.string().min(1).max(300).describe('make this the hero of the desktop') }),
+  z.object({ op: z.literal('unfeature') }),
+  z.object({ op: z.literal('transform_group'), tag: z.string().min(1).max(40), scale: z.number().min(0.3).max(3).optional(), rotate: z.number().min(-180).max(180).optional().describe('degrees clockwise') }),
+  z.object({ op: z.literal('replan'), sheet: z.string().max(40).optional().describe('which sheet (default: the current one)'), plan: z.array(SLOT).min(1).max(24).describe('slots to ADD or RESIZE on an existing sheet (merged by name; slots you do not mention stay). Same local-pixel coordinates as open_sheet{plan}') }),
+  z.object({ op: z.literal('chalk_edit'), on: z.boolean().describe('true = turn ON the user-side 改板书 toggle (notes become freely draggable/editable for the user); false = back to guarded mode') }),
+]);