cortico-world-canvas 0.1.0

package/src/drawing.ts

@@ -0,0 +1,238 @@
+import { createCanvas, type Canvas, type CanvasRenderingContext2D, type Image } from 'canvas';
+import { paintContours, parsePaint, type PaintSpec } from './paint.ts';
+
+export type Point = { x: number; y: number };
+type DrawKind = 'brush' | 'line' | 'rect' | 'ellipse' | 'polygon' | 'bezier' | 'curve' | 'fill' | 'spray' | 'paint';
+export interface DrawAction {
+  kind: DrawKind;
+  points: Point[];
+  color: string;
+  size: number;
+  opacity: number;
+  brush: 'pen' | 'marker' | 'soft' | 'eraser';
+  filled: boolean;
+  closed?: boolean;
+  stroke?: string;
+  tolerance: number;
+  density: number;
+  label: string;
+  paint?: PaintSpec;
+}
+export interface DrawStep { id: string; action: DrawAction; seed: number; raster?: string }
+export interface Board {
+  id: string;
+  title: string;
+  width: number;
+  height: number;
+  background: string;
+  revision: number;
+  steps: DrawStep[];
+}
+
+export function object(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('参数必须是对象');
+  return value as Record<string, unknown>;
+}
+
+export function number(value: unknown, name: string, min: number, max: number, integer = false): number {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max || (integer && !Number.isInteger(value))) {
+    throw new Error(`${name} 必须是 ${min}–${max} 的${integer ? '整数' : '数值'}`);
+  }
+  return value;
+}
+
+export function label(value: unknown, name = '名称'): string {
+  if (typeof value !== 'string' || !value.trim() || value.trim().length > 120) throw new Error(`${name} 必须是 1–120 字的文本`);
+  return value.trim();
+}
+
+export function color(value: unknown): string {
+  if (typeof value !== 'string' || !/^#[\da-f]{6}$/i.test(value)) throw new Error('颜色须为 #RRGGBB');
+  return value.toLowerCase();
+}
+
+export function parseActions(input: unknown, board: Board): DrawAction[] {
+  if (!Array.isArray(input) || input.length < 1 || input.length > 64) throw new Error('每批需要 1–64 个绘图动作');
+  let totalPoints = 0;
+  let pathCharacters = 0;
+  let instances = 0;
+  return input.map((raw, index) => {
+    const a = object(raw);
+    if (a.path !== undefined) {
+      const parsed = parsePaint(a);
+      pathCharacters += parsed.paint!.path.length;
+      if (pathCharacters > 64000) throw new Error('每批 path 总长度最多 64000 字符');
+      instances += parsed.paint!.instances?.length ?? 1;
+      if (instances > 256) throw new Error('每批 p5.brush 实例总数最多 256');
+      return parsed;
+    }
+    const kind = a.kind as DrawKind;
+    const ranges: Record<Exclude<DrawKind, 'paint'>, [number, number]> = {
+      brush: [1, 1024], line: [2, 2], rect: [2, 2], ellipse: [2, 2], polygon: [3, 1024],
+      bezier: [4, 1024], curve: [2, 1024], fill: [1, 1], spray: [1, 1024],
+    };
+    if (!Object.hasOwn(ranges, kind)) throw new Error(`动作 ${index + 1}: 未知 kind`);
+    const [min, max] = ranges[kind as Exclude<DrawKind, 'paint'>];
+    if (!Array.isArray(a.points) || a.points.length < min || a.points.length > max) throw new Error(`${kind} 需要 ${min}–${max} 个 points`);
+    if (kind === 'bezier' && (a.points.length - 1) % 3 !== 0) throw new Error('bezier 需要一个起点，再接每段的控制点1、控制点2、终点（共 4、7、10… 个点）');
+    if (kind === 'curve' && (a.closed || a.filled) && a.points.length < 3) throw new Error('闭合 curve 至少需要三个点');
+    totalPoints += a.points.length;
+    if (totalPoints > 8192) throw new Error('每批最多 8192 个点');
+    const points = a.points.map((rawPoint) => {
+      const p = object(rawPoint);
+      return { x: number(p.x, 'x', 0, board.width - 1), y: number(p.y, 'y', 0, board.height - 1) };
+    });
+    const brush = a.brush ?? 'pen';
+    if (!['pen', 'marker', 'soft', 'eraser'].includes(brush as string)) throw new Error('未知笔刷');
+    if (a.filled !== undefined && typeof a.filled !== 'boolean') throw new Error('filled 必须是布尔值');
+    if (a.closed !== undefined && typeof a.closed !== 'boolean') throw new Error('closed 必须是布尔值');
+    return {
+      kind, points, color: color(a.color ?? '#242333'), size: number(a.size ?? 8, 'size', 1, 512),
+      opacity: number(a.opacity ?? 1, 'opacity', 0.01, 1), brush: brush as DrawAction['brush'],
+      filled: a.filled === true, tolerance: number(a.tolerance ?? 16, 'tolerance', 0, 255, true),
+      ...(a.closed === undefined ? {} : { closed: a.closed }),
+      ...(a.stroke === undefined ? {} : { stroke: color(a.stroke) }),
+      density: number(a.density ?? 32, 'density', 1, 128, true),
+      label: a.label === undefined ? kind : label(a.label, '步骤说明'),
+    };
+  });
+}
+
+/** Rendering and cursor sampling share the same cubic control points. */
+export function cubicSegments(a: DrawAction): [Point, Point, Point, Point][] {
+  const points = a.points;
+  const segments: [Point, Point, Point, Point][] = [];
+  if (a.kind === 'bezier') {
+    for (let i = 1; i < points.length; i += 3) segments.push([points[i - 1], points[i], points[i + 1], points[i + 2]]);
+  } else if (a.kind === 'curve') {
+    const closed = a.closed || a.filled;
+    const at = (i: number) => closed ? points[(i + points.length) % points.length] : points[Math.max(0, Math.min(i, points.length - 1))];
+    for (let i = 0; i < points.length - (closed ? 0 : 1); i++) {
+      const p0 = at(i - 1), p1 = at(i), p2 = at(i + 1), p3 = at(i + 2);
+      segments.push([p1,
+        { x: p1.x + (p2.x - p0.x) / 6, y: p1.y + (p2.y - p0.y) / 6 },
+        { x: p2.x - (p3.x - p1.x) / 6, y: p2.y - (p3.y - p1.y) / 6 }, p2]);
+    }
+  }
+  return segments;
+}
+
+export function blank(board: Board): Canvas {
+  const canvas = createCanvas(board.width, board.height);
+  const ctx = canvas.getContext('2d');
+  ctx.fillStyle = board.background;
+  ctx.fillRect(0, 0, board.width, board.height);
+  return canvas;
+}
+
+export function replay(board: Board, raster?: (step: DrawStep) => Image): Canvas {
+  const canvas = blank(board);
+  for (const step of board.steps) draw(canvas, board, step, raster);
+  return canvas;
+}
+
+/** Each step starts with a fresh context; spray randomness belongs to the persisted step. */
+export function draw(canvas: Canvas, board: Board, step: DrawStep, raster?: (step: DrawStep) => Image): void {
+  const a = step.action;
+  const ctx = canvas.getContext('2d');
+  ctx.save();
+  try {
+    if (a.kind === 'paint') {
+      if (!raster) throw new Error('p5.brush 步骤需要已渲染的图层');
+      if (a.paint!.clip_to) {
+        const target = board.steps.find((candidate) => candidate.id === a.paint!.clip_to)!;
+        ctx.beginPath();
+        for (const part of paintContours(target.action.paint!)) {
+          const points = part.points;
+          // Each p5 subpath fills independently; use matching winding for the union clip.
+          const area = points.reduce((sum, p, i) => { const q = points[(i + 1) % points.length]; return sum + p.x * q.y - q.x * p.y; }, 0);
+          if (area < 0) points.reverse();
+          ctx.moveTo(points[0].x, points[0].y);
+          for (const p of points.slice(1)) ctx.lineTo(p.x, p.y);
+          ctx.closePath();
+        }
+        ctx.clip();
+      }
+      ctx.drawImage(raster(step), 0, 0);
+      return;
+    }
+    ctx.globalAlpha = a.opacity;
+    ctx.strokeStyle = ctx.fillStyle = a.color;
+    ctx.lineWidth = a.size;
+    ctx.lineCap = ctx.lineJoin = 'round';
+    if (a.kind === 'fill') { flood(ctx, board, a); return; }
+    if (a.kind === 'spray') {
+      let seed = step.seed;
+      const random = () => { seed = (Math.imul(seed, 1664525) + 1013904223) >>> 0; return seed / 0x100000000; };
+      for (const p of a.points) for (let n = 0; n < a.density; n++) {
+        const angle = random() * Math.PI * 2;
+        const radius = Math.sqrt(random()) * a.size / 2;
+        ctx.fillRect(Math.round(p.x + Math.cos(angle) * radius), Math.round(p.y + Math.sin(angle) * radius), 1, 1);
+      }
+      return;
+    }
+    if (a.kind === 'brush' && a.brush === 'soft') {
+      const stamp = (x: number, y: number) => {
+        const gradient = ctx.createRadialGradient(x, y, 0, x, y, a.size / 2);
+        gradient.addColorStop(0, a.color + '50');
+        gradient.addColorStop(1, a.color + '00');
+        ctx.fillStyle = gradient;
+        ctx.fillRect(x - a.size / 2, y - a.size / 2, a.size, a.size);
+      };
+      stamp(a.points[0].x, a.points[0].y);
+      for (let i = 1; i < a.points.length; i++) {
+        const p = a.points[i - 1], q = a.points[i];
+        const count = Math.ceil(Math.hypot(q.x - p.x, q.y - p.y) / Math.max(1, a.size / 6));
+        for (let n = 1; n <= count; n++) stamp(p.x + (q.x - p.x) * n / count, p.y + (q.y - p.y) * n / count);
+      }
+      return;
+    }
+    if (a.kind === 'brush' && a.brush === 'marker') { ctx.globalAlpha *= 0.35; ctx.lineCap = 'square'; }
+    if (a.kind === 'brush' && a.brush === 'eraser') ctx.strokeStyle = ctx.fillStyle = board.background;
+    ctx.beginPath();
+    const [p, q] = a.points;
+    if (a.kind === 'rect') ctx.rect(Math.min(p.x, q.x), Math.min(p.y, q.y), Math.abs(q.x - p.x), Math.abs(q.y - p.y));
+    else if (a.kind === 'ellipse') ctx.ellipse((p.x + q.x) / 2, (p.y + q.y) / 2, Math.abs(q.x - p.x) / 2, Math.abs(q.y - p.y) / 2, 0, 0, Math.PI * 2);
+    else if (a.kind === 'bezier' || a.kind === 'curve') {
+      ctx.moveTo(p.x, p.y);
+      for (const [, c1, c2, end] of cubicSegments(a)) ctx.bezierCurveTo(c1.x, c1.y, c2.x, c2.y, end.x, end.y);
+      if (a.closed || a.filled) ctx.closePath();
+    } else if (a.points.length === 1) {
+      ctx.arc(p.x, p.y, a.size / 2, 0, Math.PI * 2);
+      ctx.fill();
+      return;
+    } else {
+      ctx.moveTo(p.x, p.y);
+      for (const point of a.points.slice(1)) ctx.lineTo(point.x, point.y);
+      if (a.kind === 'polygon') ctx.closePath();
+    }
+    if (a.filled && ['rect', 'ellipse', 'polygon', 'bezier', 'curve'].includes(a.kind)) {
+      ctx.fill();
+      if (a.stroke) { ctx.strokeStyle = a.stroke; ctx.stroke(); }
+    } else ctx.stroke();
+  } finally { ctx.restore(); }
+}
+
+function flood(ctx: CanvasRenderingContext2D, board: Board, a: DrawAction): void {
+  const { width, height } = board;
+  const image = ctx.getImageData(0, 0, width, height);
+  const pixels = image.data;
+  const start = Math.floor(a.points[0].y) * width + Math.floor(a.points[0].x);
+  const original = Array.from(pixels.slice(start * 4, start * 4 + 4));
+  const replacement = [1, 3, 5].map((offset) => parseInt(a.color.slice(offset, offset + 2), 16));
+  const seen = new Uint8Array(width * height);
+  const stack = new Int32Array(width * height);
+  let count = 0;
+  const enqueue = (pixel: number) => { if (!seen[pixel]) { seen[pixel] = 1; stack[count++] = pixel; } };
+  enqueue(start);
+  while (count) {
+    const pixel = stack[--count], offset = pixel * 4;
+    if (original.some((value, channel) => Math.abs(pixels[offset + channel] - value) > a.tolerance)) continue;
+    for (let channel = 0; channel < 3; channel++) pixels[offset + channel] = Math.round(pixels[offset + channel] * (1 - a.opacity) + replacement[channel] * a.opacity);
+    if (pixel % width > 0) enqueue(pixel - 1);
+    if (pixel % width < width - 1) enqueue(pixel + 1);
+    if (pixel >= width) enqueue(pixel - width);
+    if (pixel < width * (height - 1)) enqueue(pixel + width);
+  }
+  ctx.putImageData(image, 0, 0);
+}

package/src/engine-child.ts

@@ -0,0 +1,23 @@
+import { CanvasServer } from './server.ts';
+
+let server: CanvasServer | null = null;
+process.on('message', (message: { id: number; name: string; args: Record<string, unknown> }) => {
+  void (async () => {
+    if (message.name === 'init') {
+      server = new CanvasServer({
+        directory: message.args.directory as string, port: message.args.port as number,
+        browserPath: message.args.browserPath as string,
+        onReferences: (references) => process.send?.({ event: 'references', references }),
+        onGameEvent: (text) => process.send?.({ event: 'game', text }),
+      });
+      await server.start();
+      return { url: server.url };
+    }
+    if (!server) throw new Error('画布尚未初始化');
+    if (message.name === 'stop') { await server.stop(); return null; }
+    return server.command(message.name, message.args);
+  })().then((value) => {
+    if (process.connected) process.send?.({ id: message.id, value });
+  }).catch((error) => { if (process.connected) process.send?.({ id: message.id, error: String(error.message ?? error) }); });
+});
+process.on('disconnect', () => { void server?.abort().finally(() => process.exit(0)); });

package/src/game.ts

@@ -0,0 +1,207 @@
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { number, object } from './drawing.ts';
+
+/**
+ * 你画我猜的运行态:界面模式、当前一局、上一局揭示与计分板。
+ * 游戏规则不在这里执行——谁答对、记几分由主持人按说明书判断后写入;
+ * 存储只保证题目在揭示前不出现在网页状态里,以及倒计时到点有一次回调。
+ */
+type GameMode = 'free' | 'guess';
+interface ScoreEntry { name: string; score: number }
+interface RankedEntry extends ScoreEntry { rank: number }
+interface GameRound { id: number; answer: string; hint: string | null; startedAt: number; endsAt: number; expired: boolean }
+interface GameReveal { roundId: number; answer: string; hint: string | null; winners: string[]; at: number }
+/** 网页看到的投影:进行中一局只给字数与提示,题目留在文件里。 */
+interface GameView {
+  mode: GameMode;
+  now: number;
+  rounds: number;
+  round: { id: number; hint: string | null; length: number; startedAt: number; endsAt: number; expired: boolean } | null;
+  reveal: GameReveal | null;
+  scoreboard: RankedEntry[];
+}
+/** 主持人看到的读数:与 GameView 的区别是带题目和剩余秒数。 */
+export interface GameStatus {
+  mode: GameMode;
+  round: { id: number; answer: string; hint: string | null; remainingSeconds: number; expired: boolean } | null;
+  lastReveal: { roundId: number; answer: string; winners: string[] } | null;
+  scoreboard: RankedEntry[];
+}
+interface GameFile { mode: GameMode; rounds: number; round: GameRound | null; reveal: GameReveal | null; scoreboard: ScoreEntry[] }
+
+export const GAME_GUIDE_PATH = fileURLToPath(new URL('./GAME_GUIDE.md', import.meta.url));
+const SCOREBOARD_LIMIT = 500;
+const BATCH_LIMIT = 64;
+
+function text(value: unknown, name: string, max: number): string {
+  if (typeof value !== 'string' || !value.trim() || Array.from(value.trim()).length > max) throw new Error(`${name} 必须是 1–${max} 字的文本`);
+  return value.trim();
+}
+
+function names(value: unknown, name: string): string[] {
+  if (!Array.isArray(value) || value.length > BATCH_LIMIT) throw new Error(`${name} 须为最多 ${BATCH_LIMIT} 个名字`);
+  return value.map((item) => text(item, name, 40));
+}
+
+export class GameStore {
+  private data: GameFile;
+  private countdown: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(private readonly options: { directory: string; onChange?: () => void; onExpire?: (round: GameRound) => void }) {
+    const path = this.path();
+    this.data = existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) as GameFile : { mode: 'free', rounds: 0, round: null, reveal: null, scoreboard: [] };
+    if (this.data.round && !this.data.round.expired) this.arm();
+  }
+
+  private path(): string { return join(this.options.directory, 'game.json'); }
+
+  private persist(): void {
+    const path = this.path();
+    writeFileSync(`${path}.tmp`, JSON.stringify(this.data));
+    renameSync(`${path}.tmp`, path);
+    this.options.onChange?.();
+  }
+
+  guide(): string { return readFileSync(GAME_GUIDE_PATH, 'utf8').trim(); }
+
+  ranked(): RankedEntry[] {
+    const sorted = [...this.data.scoreboard].sort((a, b) => b.score - a.score);
+    const ranked: RankedEntry[] = [];
+    sorted.forEach((entry, index) => {
+      const previous = ranked[index - 1];
+      ranked.push({ ...entry, rank: previous && previous.score === entry.score ? previous.rank : index + 1 });
+    });
+    return ranked;
+  }
+
+  view(): GameView {
+    const { round } = this.data;
+    return {
+      mode: this.data.mode, now: Date.now(), rounds: this.data.rounds,
+      round: round ? { id: round.id, hint: round.hint, length: Array.from(round.answer).length, startedAt: round.startedAt, endsAt: round.endsAt, expired: round.expired } : null,
+      reveal: this.data.reveal, scoreboard: this.ranked(),
+    };
+  }
+
+  status(): GameStatus {
+    const { round, reveal } = this.data;
+    return {
+      mode: this.data.mode,
+      round: round ? { id: round.id, answer: round.answer, hint: round.hint, remainingSeconds: Math.max(0, Math.ceil((round.endsAt - Date.now()) / 1000)), expired: round.expired } : null,
+      lastReveal: reveal ? { roundId: reveal.roundId, answer: reveal.answer, winners: reveal.winners } : null,
+      scoreboard: this.ranked(),
+    };
+  }
+
+  enter(): GameStatus {
+    if (this.data.mode !== 'guess') { this.data.mode = 'guess'; this.persist(); }
+    return this.status();
+  }
+
+  /** 回到自由画板:未揭示的一局作废,计分板保留。 */
+  exit(): GameStatus {
+    this.clearTimer();
+    this.data = { ...this.data, mode: 'free', round: null, reveal: null };
+    this.persist();
+    return this.status();
+  }
+
+  startRound(args: Record<string, unknown>): GameStatus {
+    const current = this.data.round;
+    if (current) throw new Error(`第 ${current.id} 局尚未结束:先用 canvas_game_reveal 揭示答案,或 canvas_game_timer 的 stop 取消这一局`);
+    const answer = text(args.answer, 'answer', 40);
+    const seconds = number(args.seconds ?? 300, 'seconds', 1, 3600);
+    const hint = args.hint === undefined || args.hint === null ? null : text(args.hint, 'hint', 40);
+    const now = Date.now();
+    this.data = { ...this.data, mode: 'guess', rounds: this.data.rounds + 1, reveal: null,
+      round: { id: this.data.rounds + 1, answer, hint, startedAt: now, endsAt: now + seconds * 1000, expired: false } };
+    this.persist();
+    this.arm();
+    return this.status();
+  }
+
+  timer(args: Record<string, unknown>): GameStatus {
+    const round = this.data.round;
+    if (!round) throw new Error('没有进行中的一局,请先 canvas_game_round 开局');
+    if (args.stop === true) {
+      this.clearTimer();
+      this.data = { ...this.data, round: null };
+      this.persist();
+      return this.status();
+    }
+    const seconds = number(args.seconds, 'seconds', 1, 3600);
+    this.data = { ...this.data, round: { ...round, startedAt: Date.now(), endsAt: Date.now() + seconds * 1000, expired: false } };
+    this.persist();
+    this.arm();
+    return this.status();
+  }
+
+  reveal(args: Record<string, unknown>): GameStatus {
+    const round = this.data.round;
+    if (!round) throw new Error('没有可揭示的一局,请先 canvas_game_round 开局');
+    const winners = args.winners === undefined ? [] : names(args.winners, 'winners').slice(0, 20);
+    this.clearTimer();
+    this.data = { ...this.data, round: null, reveal: { roundId: round.id, answer: round.answer, hint: round.hint, winners, at: Date.now() } };
+    this.persist();
+    return this.status();
+  }
+
+  score(args: Record<string, unknown>): { scoreboard: RankedEntry[]; changes: { name: string; before: number | null; after: number | null }[] } {
+    const entries = args.entries === undefined ? [] : args.entries;
+    if (!Array.isArray(entries) || entries.length > BATCH_LIMIT) throw new Error(`entries 须为最多 ${BATCH_LIMIT} 项`);
+    const remove = args.remove === undefined ? [] : names(args.remove, 'remove');
+    if (!entries.length && !remove.length && args.reset !== true) throw new Error('entries、remove、reset 至少提供一项');
+    const board: ScoreEntry[] = args.reset === true ? [] : [...this.data.scoreboard];
+    const changes: { name: string; before: number | null; after: number | null }[] = [];
+    for (const raw of entries) {
+      const entry = object(raw);
+      const name = text(entry.name, 'name', 40);
+      const hasAdd = entry.add !== undefined, hasSet = entry.set !== undefined;
+      if (hasAdd === hasSet) throw new Error(`${name}:add 与 set 二选一`);
+      const value = number(hasAdd ? entry.add : entry.set, hasAdd ? 'add' : 'set', -100000, 100000, true);
+      const index = board.findIndex((item) => item.name === name);
+      const before = index >= 0 ? board[index].score : null;
+      const after = hasAdd ? (before ?? 0) + value : value;
+      if (index >= 0) board[index] = { name, score: after };
+      else {
+        if (board.length >= SCOREBOARD_LIMIT) throw new Error(`计分板最多 ${SCOREBOARD_LIMIT} 人,请用 remove 或 reset 清理`);
+        board.push({ name, score: after });
+      }
+      changes.push({ name, before, after });
+    }
+    for (const name of remove) {
+      const index = board.findIndex((item) => item.name === name);
+      if (index < 0) continue;
+      changes.push({ name, before: board[index].score, after: null });
+      board.splice(index, 1);
+    }
+    this.data = { ...this.data, scoreboard: board };
+    this.persist();
+    return { scoreboard: this.ranked(), changes };
+  }
+
+  close(): void { this.clearTimer(); }
+
+  private clearTimer(): void {
+    if (this.countdown) clearTimeout(this.countdown);
+    this.countdown = null;
+  }
+
+  private arm(): void {
+    this.clearTimer();
+    const round = this.data.round!;
+    this.countdown = setTimeout(() => this.expire(round.id), Math.max(0, round.endsAt - Date.now()));
+    this.countdown.unref();
+  }
+
+  private expire(id: number): void {
+    const round = this.data.round;
+    if (!round || round.id !== id || round.expired) return;
+    this.countdown = null;
+    this.data = { ...this.data, round: { ...round, expired: true } };
+    this.persist();
+    this.options.onExpire?.(this.data.round!);
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * 包入口:默认导出 `WorldDefinition`,加载器按 `cortico.kind === 'world'` 认它。
+ *
+ * 配置段类型一并导出,给 bot 侧在 `declares` 覆盖里写 `worlds.canvas` 的字面量时用。
+ */
+
+import { CANVAS } from './definition.ts';
+
+export default CANVAS;
+
+export { CANVAS };
+export { CANVAS_DEFAULTS, CANVAS_CONFIG_GROUP } from './config.ts';
+export type { CanvasConfigSection } from './config.ts';

package/src/inspect.ts

@@ -0,0 +1,47 @@
+import { createCanvas, type Canvas, type Image } from 'canvas';
+import { number, object } from './drawing.ts';
+
+/** Inspection coordinates refer to source pixels; the grid never enters the artwork. */
+export function inspectImage(source: Canvas | Image, args: Record<string, unknown>) {
+  if (args.grid !== undefined && typeof args.grid !== 'boolean') throw new Error('grid 必须是布尔值');
+  const raw = args.region === undefined ? { x: 0, y: 0, width: source.width, height: source.height } : object(args.region);
+  const x = number(raw.x, 'region.x', 0, source.width - 1, true);
+  const y = number(raw.y, 'region.y', 0, source.height - 1, true);
+  const width = number(raw.width, 'region.width', 1, source.width - x, true);
+  const height = number(raw.height, 'region.height', 1, source.height - y, true);
+  const scale = Math.min(args.region === undefined ? 1 : 4, 1024 / Math.max(width, height));
+  const offset = args.grid ? 32 : 0;
+  const canvas = createCanvas(Math.ceil(width * scale) + offset, Math.ceil(height * scale) + offset);
+  const ctx = canvas.getContext('2d');
+  ctx.fillStyle = '#ffffff';
+  ctx.fillRect(0, 0, canvas.width, canvas.height);
+  ctx.drawImage(source, x, y, width, height, offset, offset, width * scale, height * scale);
+  let gridStep: number | undefined;
+  if (args.grid) {
+    const desired = Math.max(width, height) / 8;
+    const unit = 10 ** Math.floor(Math.log10(desired));
+    gridStep = [1, 2, 5, 10].map((n) => n * unit).find((n) => n >= desired)!;
+    gridStep = Math.max(1, gridStep);
+    ctx.font = '12px sans-serif';
+    ctx.fillStyle = '#263047';
+    ctx.strokeStyle = '#26304740';
+    ctx.lineWidth = 1;
+    ctx.setLineDash([3, 4]);
+    ctx.textAlign = 'center';
+    for (let column = Math.ceil(x / gridStep) * gridStep; column < x + width; column += gridStep) {
+      const px = offset + (column - x) * scale;
+      ctx.beginPath(); ctx.moveTo(px, offset); ctx.lineTo(px, canvas.height); ctx.stroke();
+      ctx.fillText(String(column), Math.max(offset + 12, Math.min(canvas.width - 15, px)), 20);
+    }
+    ctx.textAlign = 'right';
+    for (let row = Math.ceil(y / gridStep) * gridStep; row < y + height; row += gridStep) {
+      const py = offset + (row - y) * scale;
+      ctx.beginPath(); ctx.moveTo(offset, py); ctx.lineTo(canvas.width, py); ctx.stroke();
+      ctx.fillText(String(row), offset - 4, Math.max(offset + 12, Math.min(canvas.height - 3, py + 4)));
+    }
+  }
+  return { png: canvas.toBuffer('image/png'), view: {
+    region: { x, y, width, height }, scale, offset: { x: offset, y: offset },
+    width: canvas.width, height: canvas.height, ...(gridStep === undefined ? {} : { gridStep }),
+  } };
+}

package/src/motion.ts

@@ -0,0 +1,132 @@
+import { createCanvas, type Canvas } from 'canvas';
+import { setTimeout as delay } from 'node:timers/promises';
+import { cubicSegments, draw, type Board, type DrawAction, type DrawStep, type Point } from './drawing.ts';
+import { paintContours } from './paint.ts';
+
+export interface Cursor extends Point { mode: 'idle' | 'moving' | 'pressed' | 'released' }
+
+export function strokePath(a: DrawAction): Point[] {
+  if (a.kind === 'paint') return paintContours(a.paint!).flatMap((part) => {
+    const points = part.points;
+    return part.closed ? [...points, points[0]] : points;
+  });
+  const [p, q] = a.points;
+  if (a.kind === 'rect') return [p, { x: q.x, y: p.y }, q, { x: p.x, y: q.y }, p];
+  if (a.kind === 'polygon') return [...a.points, p];
+  if (a.kind === 'ellipse') return Array.from({ length: 65 }, (_, i) => {
+    const angle = i / 64 * Math.PI * 2;
+    return { x: (p.x + q.x) / 2 + Math.abs(q.x - p.x) / 2 * Math.cos(angle), y: (p.y + q.y) / 2 + Math.abs(q.y - p.y) / 2 * Math.sin(angle) };
+  });
+  if (a.kind === 'bezier' || a.kind === 'curve') {
+    const path = [p];
+    for (const [start, c1, c2, end] of cubicSegments(a)) {
+      const length = Math.hypot(c1.x - start.x, c1.y - start.y) + Math.hypot(c2.x - c1.x, c2.y - c1.y) + Math.hypot(end.x - c2.x, end.y - c2.y);
+      const count = Math.max(4, Math.min(64, Math.ceil(length / 4)));
+      for (let i = 1; i <= count; i++) {
+        const t = i / count, u = 1 - t;
+        path.push({ x: u ** 3 * start.x + 3 * u ** 2 * t * c1.x + 3 * u * t ** 2 * c2.x + t ** 3 * end.x,
+          y: u ** 3 * start.y + 3 * u ** 2 * t * c1.y + 3 * u * t ** 2 * c2.y + t ** 3 * end.y });
+      }
+    }
+    if (a.closed || a.filled) path.push(p);
+    return path;
+  }
+  return a.points;
+}
+
+export function pathPrefix(points: Point[], fraction: number): Point[] {
+  const distances = points.slice(1).map((p, i) => Math.hypot(p.x - points[i].x, p.y - points[i].y));
+  let remaining = distances.reduce((sum, value) => sum + value, 0) * fraction;
+  const result = [points[0]];
+  for (let i = 0; i < distances.length; i++) {
+    if (remaining >= distances[i]) { result.push(points[i + 1]); remaining -= distances[i]; }
+    else {
+      const t = remaining / distances[i];
+      result.push({ x: points[i].x + (points[i + 1].x - points[i].x) * t, y: points[i].y + (points[i + 1].y - points[i].y) * t });
+      break;
+    }
+  }
+  return result;
+}
+
+/** Preview pixels are temporary. The final frame uses the exact persisted action. */
+export async function animateStep(
+  canvas: Canvas, board: Board, step: DrawStep, cursor: Cursor, duration: number,
+  emit: (cursor: Cursor) => void,
+  finish: (target: Canvas) => void = (target) => draw(target, board, step),
+): Promise<Cursor> {
+  if (step.action.kind === 'paint') return animatePaint(canvas, board, step, cursor, duration, emit, finish);
+  const ctx = canvas.getContext('2d');
+  const base = ctx.getImageData(0, 0, board.width, board.height);
+  const path = strokePath(step.action), start = path[0];
+  const travelFrames = duration ? Math.max(2, Math.ceil(duration * 0.22 / 50)) : 0;
+  for (let frame = 1; frame <= travelFrames; frame++) {
+    const t = frame / travelFrames, eased = t * t * (3 - 2 * t);
+    const arc = Math.sin(t * Math.PI) * Math.min(16, Math.hypot(start.x - cursor.x, start.y - cursor.y) * 0.08);
+    emit({ x: cursor.x + (start.x - cursor.x) * eased, y: Math.max(0, Math.min(board.height - 1, cursor.y + (start.y - cursor.y) * eased - arc)), mode: 'moving' });
+    await delay(duration * 0.22 / travelFrames);
+  }
+  const frames = duration ? Math.max(2, Math.ceil(duration * 0.78 / 50)) : 0;
+  for (let frame = 1; frame <= frames; frame++) {
+    const t = frame / frames, prefix = pathPrefix(path, t * t * (3 - 2 * t));
+    ctx.putImageData(base, 0, 0);
+    const a = step.action;
+    if (a.kind !== 'fill') draw(canvas, board, { ...step, action: {
+      ...a, kind: a.kind === 'spray' ? 'spray' : 'brush', brush: a.kind === 'brush' ? a.brush : 'pen', points: prefix, filled: false,
+      color: a.filled ? a.stroke ?? a.color : a.color,
+    } });
+    emit({ ...prefix[prefix.length - 1], mode: 'pressed' });
+    await delay(duration * 0.78 / frames);
+  }
+  ctx.putImageData(base, 0, 0);
+  finish(canvas);
+  const result: Cursor = { ...path[path.length - 1], mode: 'released' };
+  emit(result);
+  return result;
+}
+
+/** Reveal the rendered pixels along each stroke, including its clip, and lift between subpaths. */
+async function animatePaint(canvas: Canvas, board: Board, step: DrawStep, cursor: Cursor, duration: number,
+  emit: (cursor: Cursor) => void, finish: (target: Canvas) => void): Promise<Cursor> {
+  const paint = step.action.paint!;
+  const paths = paintContours(paint).map((part) => {
+    const points = part.points;
+    return part.closed ? [...points, points[0]] : points;
+  });
+  const ctx = canvas.getContext('2d'), base = ctx.getImageData(0, 0, board.width, board.height);
+  const layer = createCanvas(board.width, board.height); finish(layer);
+  const mask = createCanvas(board.width, board.height), maskCtx = mask.getContext('2d');
+  const revealed = createCanvas(board.width, board.height), revealCtx = revealed.getContext('2d');
+  const lengths = paths.map((path) => path.slice(1).reduce((sum, p, i) => sum + Math.hypot(p.x - path[i].x, p.y - path[i].y), 0));
+  const total = lengths.reduce((sum, value) => sum + value, 0);
+  maskCtx.lineCap = 'round'; maskCtx.lineJoin = 'round';
+  maskCtx.lineWidth = paint.stroke ? paint.stroke.width * Math.max(...paint.stroke.pressure) * (paint.stroke.brush === 'spray' ? 4 : 2) + 2 : 4;
+  for (let index = 0; index < paths.length; index++) {
+    const path = paths[index], start = path[0], time = duration * lengths[index] / total;
+    const travelFrames = duration ? Math.max(1, Math.ceil(time * 0.22 / 50)) : 0;
+    for (let frame = 1; frame <= travelFrames; frame++) {
+      const t = frame / travelFrames, eased = t * t * (3 - 2 * t);
+      const arc = Math.sin(t * Math.PI) * Math.min(16, Math.hypot(start.x - cursor.x, start.y - cursor.y) * 0.08);
+      emit({ x: cursor.x + (start.x - cursor.x) * eased, y: cursor.y + (start.y - cursor.y) * eased - arc, mode: 'moving' });
+      await delay(time * 0.22 / travelFrames);
+    }
+    const frames = duration ? Math.max(1, Math.ceil(time * 0.78 / 50)) : 0;
+    for (let frame = 1; frame <= frames; frame++) {
+      const t = frame / frames, prefix = pathPrefix(path, t * t * (3 - 2 * t));
+      maskCtx.beginPath(); maskCtx.moveTo(prefix[0].x, prefix[0].y);
+      for (const point of prefix.slice(1)) maskCtx.lineTo(point.x, point.y);
+      maskCtx.stroke();
+      revealCtx.clearRect(0, 0, board.width, board.height);
+      revealCtx.drawImage(layer, 0, 0);
+      revealCtx.globalCompositeOperation = 'destination-in'; revealCtx.drawImage(mask, 0, 0);
+      revealCtx.globalCompositeOperation = 'source-over';
+      ctx.putImageData(base, 0, 0); ctx.drawImage(revealed, 0, 0);
+      emit({ ...prefix.at(-1)!, mode: 'pressed' });
+      await delay(time * 0.78 / frames);
+    }
+    cursor = { ...path.at(-1)!, mode: 'released' }; emit(cursor);
+  }
+  ctx.putImageData(base, 0, 0); ctx.drawImage(layer, 0, 0);
+  emit(cursor);
+  return cursor;
+}