cortico-world-canvas 0.1.0

package/src/server.ts

@@ -0,0 +1,306 @@
+import { createServer, type Server, type ServerResponse } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import express from 'express';
+import { createCanvas, loadImage } from 'canvas';
+import { object } from './drawing.ts';
+import { BrushRenderer } from './brush-renderer.ts';
+import { toolAction } from './paint.ts';
+import { inspectImage } from './inspect.ts';
+import { animateStep, type Cursor } from './motion.ts';
+import { CanvasStore, type Reference } from './store.ts';
+import { GameStore, type GameStatus } from './game.ts';
+
+export interface CanvasReply { text: string; images?: { png: string; fallback: string }[] }
+interface CanvasServerOptions {
+  directory: string;
+  port: number;
+  animationMs?: number;
+  browserPath?: string;
+  onReferences?: (references: Reference[]) => void;
+  /** 倒计时到点的通知正文,由 World 作为内部事件投递。 */
+  onGameEvent?: (text: string) => void;
+}
+
+const GAME_COMMANDS = ['canvas_game_enter', 'canvas_game_round', 'canvas_game_timer', 'canvas_game_reveal', 'canvas_game_scoreboard', 'canvas_game_score', 'canvas_game_exit'];
+
+export class CanvasServer {
+  readonly store: CanvasStore;
+  readonly game: GameStore;
+  private server: Server | null = null;
+  private subscribers = new Set<ServerResponse>();
+  private heartbeat: ReturnType<typeof setInterval> | null = null;
+  private tail: Promise<unknown> = Promise.resolve();
+  private queued = 0;
+  private painting: { step: number; total: number; label: string } | null = null;
+  private cursor: Cursor = { x: 0, y: 0, mode: 'idle' };
+  private preview: string | null = null;
+  private stopping = false;
+  private readonly brush: BrushRenderer;
+  url = '';
+
+  constructor(private readonly options: CanvasServerOptions) {
+    this.store = new CanvasStore(options.directory);
+    this.brush = new BrushRenderer(options.browserPath);
+    this.game = new GameStore({
+      directory: this.store.directory,
+      onChange: () => this.publish(),
+      onExpire: (round) => options.onGameEvent?.(`[你画我猜] 第 ${round.id} 局倒计时结束，题目「${round.answer}」${round.hint ? `（提示：${round.hint}）` : ''}。之后的回答不计分；请先用 canvas_game_score 给倒计时内答对的观众记分，再用 canvas_game_reveal 揭示答案。`),
+    });
+  }
+
+  state() {
+    return { board: this.store.board, references: this.store.references, queued: this.queued,
+      painting: this.painting, cursor: this.cursor, preview: this.preview, game: this.game.view() };
+  }
+
+  private gameCommand(name: string, args: Record<string, unknown>): CanvasReply {
+    const reply = (message: string, status: GameStatus): CanvasReply => ({ text: JSON.stringify({ message, ...status }) });
+    switch (name) {
+      case 'canvas_game_enter': {
+        const status = this.game.enter();
+        return { text: `${this.game.guide()}\n\n${JSON.stringify({ message: '画室网页已切换到你画我猜界面', ...status })}` };
+      }
+      case 'canvas_game_round': {
+        const status = this.game.startRound(args);
+        return reply(`第 ${status.round!.id} 局已开始，倒计时 ${status.round!.remainingSeconds} 秒；题目只有你知道`, status);
+      }
+      case 'canvas_game_timer': {
+        const status = this.game.timer(args);
+        return reply(status.round ? `倒计时已重设为 ${status.round.remainingSeconds} 秒` : '本局已取消，未揭示答案', status);
+      }
+      case 'canvas_game_reveal': {
+        const status = this.game.reveal(args);
+        return reply(`第 ${status.lastReveal!.roundId} 局已揭示答案「${status.lastReveal!.answer}」`, status);
+      }
+      case 'canvas_game_scoreboard': return reply('当前游戏状态', this.game.status());
+      case 'canvas_game_score': {
+        const result = this.game.score(args);
+        return { text: JSON.stringify({ message: `已更新 ${result.changes.length} 项`, ...result }) };
+      }
+      default: return reply('已回到自由画板', this.game.exit());
+    }
+  }
+
+  private emit(type: string, data: unknown): void {
+    const packet = `data: ${JSON.stringify({ type, data })}\n\n`;
+    for (const response of this.subscribers) {
+      if (response.writableLength > 4 * 1024 * 1024) { response.destroy(); this.subscribers.delete(response); }
+      else response.write(packet);
+    }
+  }
+
+  private publish(): void { this.emit('state', this.state()); }
+
+  private enqueue<T>(action: () => Promise<T> | T): Promise<T> {
+    if (this.stopping) return Promise.reject(new Error('画布服务已停止'));
+    if (this.queued >= 16) return Promise.reject(new Error('画布队列已满，请稍后重试'));
+    this.queued++;
+    this.publish();
+    const result = this.tail.then(() => { if (this.stopping) throw new Error('画布调用已取消'); return action(); });
+    this.tail = result.catch(() => undefined).finally(() => { this.queued--; this.publish(); });
+    return result;
+  }
+
+  command(name: string, args: Record<string, unknown>): Promise<CanvasReply> {
+    // Game commands touch no pixels and answer immediately instead of waiting behind a playing batch.
+    if (GAME_COMMANDS.includes(name)) {
+      if (this.stopping) return Promise.reject(new Error('画布服务已停止'));
+      try { return Promise.resolve(this.gameCommand(name, args)); } catch (error) { return Promise.reject(error); }
+    }
+    return this.enqueue(async () => {
+      if (name === 'canvas_new') {
+        this.store.newBoard(args);
+        this.cursor = { x: 0, y: 0, mode: 'idle' };
+        return this.snapshot('已新建画布');
+      }
+      if (name === 'canvas_snapshot') return this.snapshot('当前画布', undefined, true, args);
+      if (name === 'canvas_save') {
+        const saved = this.store.save(args.filename);
+        return { text: JSON.stringify({ ...saved, url: `${this.url}${saved.url}` }) };
+      }
+      if (name === 'canvas_undo') {
+        const id = this.store.undo(args.step_id);
+        return this.snapshot(`已撤销步骤 ${id}`);
+      }
+      if (name === 'canvas_references') {
+        const selected = this.store.referenceImages(args.ids);
+        if (args.region !== undefined && selected.length !== 1) throw new Error('查看局部参考图时，ids 须选择一张图片');
+        const views = await Promise.all(selected.map(async ({ ref, png }) => {
+          const inspected = args.region !== undefined || args.grid !== undefined ? inspectImage(await loadImage(png), args) : { png, view: undefined };
+          return { ref, ...inspected };
+        }));
+        return {
+          text: JSON.stringify({ references: this.store.references, shown: selected.map(({ ref }) => ref.id),
+            views: views.filter(({ view }) => view).map(({ ref, view }) => ({ id: ref.id, ...view })) }),
+          images: views.map(({ ref, png, view }) => ({ png: png.toString('base64'), fallback: `[参考图：${ref.name}，ID=${ref.id}，${ref.width}×${ref.height}${view ? '，观察区域见 views' : ''}]` })),
+        };
+      }
+      if (!['canvas_draw', 'canvas_edit', 'canvas_transform'].includes(name)) throw new Error('未知画布工具');
+      const editing = name !== 'canvas_draw';
+      const board = this.store.current();
+      const steps = name === 'canvas_transform' ? this.store.prepareTransform(args) : editing ? this.store.prepareEdits(args.updates) : this.store.prepare(args.actions);
+      const previous = board.steps.filter((old) => steps.some((step) => step.id === old.id)).map((step) => ({ step_id: step.id, action: toolAction(step.action) }));
+      const planned = editing ? board.steps.map((old) => steps.find((step) => step.id === old.id) ?? old) : [...board.steps, ...steps];
+      this.store.validateLayers(planned);
+      let working = [...board.steps];
+      let canvas = this.store.copyCanvas();
+      const duration = Math.min(this.options.animationMs ?? 850, 12000 / steps.length);
+      try {
+        for (let index = 0; index < steps.length; index++) {
+          if (this.stopping) throw new Error('画布调用已取消');
+          this.painting = { step: index + 1, total: steps.length, label: steps[index].action.label };
+          if (steps[index].action.kind === 'paint') this.store.cacheRaster(steps[index], await this.brush.render(board, steps[index]));
+        }
+        for (let index = 0; index < steps.length; index++) {
+          if (this.stopping) throw new Error('画布调用已取消');
+          this.painting = { step: index + 1, total: steps.length, label: steps[index].action.label };
+          const position = editing ? planned.findIndex((step) => step.id === steps[index].id) : working.length;
+          const later = editing ? planned.slice(position + 1) : [];
+          // Edits preview the final dependency graph, including clips changed in the same batch.
+          if (editing) canvas = this.store.replay(planned.slice(0, position));
+          const frameBoard = { ...board, steps: editing ? planned : [...working, steps[index]] };
+          const preview = editing ? createCanvas(board.width, board.height) : canvas;
+          // Flood fills depend on lower pixels; other layers can be flattened once per edited step.
+          const upper = editing && !later.some((step) => step.action.kind === 'fill') ? createCanvas(board.width, board.height) : null;
+          if (upper) for (const step of later) this.store.draw(upper, frameBoard, step);
+          this.cursor = await animateStep(canvas, board, steps[index], this.cursor, duration, (cursor) => {
+            if (this.stopping) throw new Error('画布调用已取消');
+            this.cursor = cursor;
+            if (editing) {
+              preview.getContext('2d').drawImage(canvas, 0, 0);
+              if (upper) preview.getContext('2d').drawImage(upper, 0, 0);
+              else for (const step of later) this.store.draw(preview, frameBoard, step);
+            }
+            this.preview = preview.toBuffer('image/png').toString('base64');
+            this.emit('frame', { ...this.painting, cursor, png: this.preview });
+          }, (target) => this.store.draw(target, frameBoard, steps[index]));
+          working = editing ? planned : [...working, steps[index]];
+        }
+        if (this.stopping) throw new Error('画布调用已取消');
+        this.store.commit(working, editing ? this.store.replay(working) : canvas);
+        const reply = this.snapshot(`已${editing ? '修改' : '完成'} ${steps.length} 个步骤`, steps.map((step) => step.id));
+        if (editing) reply.text = JSON.stringify({ ...JSON.parse(reply.text), previous });
+        return reply;
+      } finally {
+        this.preview = null;
+        this.painting = null;
+        this.cursor = { ...this.cursor, mode: 'idle' };
+        this.publish();
+      }
+    });
+  }
+
+  private snapshot(message: string, completed?: string[], includeSteps = false, args: Record<string, unknown> = {}): CanvasReply {
+    const board = this.store.current();
+    const { steps, ...description } = board;
+    const inspected = args.region !== undefined || args.grid !== undefined ? inspectImage(this.store.canvas!, args) : undefined;
+    return {
+      text: JSON.stringify({ message, board: { ...description, stepCount: steps.length, ...(includeSteps ? { steps: steps.map((step) => ({ id: step.id, action: toolAction(step.action) })) } : {}) },
+        ...(inspected ? { view: inspected.view } : {}),
+        ...(completed ? { completed: steps.filter((step) => completed.includes(step.id)).map((step) => ({ id: step.id, label: step.action.label })) } : {}) }),
+      images: [{ png: (inspected?.png ?? this.store.png()).toString('base64'), fallback: `[画布截图：${board.title}，${board.width}×${board.height}，${board.steps.length} 步${inspected ? '，观察区域见 view' : ''}]` }],
+    };
+  }
+
+  async start(): Promise<void> {
+    const app = express();
+    app.disable('x-powered-by');
+    app.use((req, res, next) => {
+      res.setHeader('X-Content-Type-Options', 'nosniff');
+      res.setHeader('Cache-Control', 'no-store');
+      res.setHeader('Content-Security-Policy', "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data: blob:; connect-src 'self'; object-src 'none'; base-uri 'none'");
+      if (!['GET', 'HEAD'].includes(req.method) && req.headers.origin && req.headers.origin !== this.url) {
+        res.status(403).json({ error: '写入只接受本机同源请求' }); return;
+      }
+      next();
+    });
+    app.use(express.json({ limit: '14mb' }));
+    app.get('/api/state', (_req, res) => res.json(this.state()));
+    app.get('/api/canvas.png', (_req, res) => {
+      if (!this.store.board) { res.status(404).end(); return; }
+      res.type('png').send(this.store.png());
+    });
+    app.get('/events', (_req, res) => {
+      res.set({ 'Content-Type': 'text/event-stream', Connection: 'keep-alive', 'X-Accel-Buffering': 'no' });
+      res.flushHeaders();
+      res.write(`data: ${JSON.stringify({ type: 'state', data: this.state() })}\n\n`);
+      this.subscribers.add(res);
+      res.on('close', () => this.subscribers.delete(res));
+    });
+    app.post('/api/command', (req, res) => {
+      void (async () => {
+        const body = object(req.body);
+        const reply = await this.command(String(body.name), object(body.args ?? {}));
+        // canvas_game_enter answers with the guide text ahead of its JSON line; other replies are JSON throughout.
+        const json = reply.text.slice(reply.text.lastIndexOf('\n') + 1);
+        res.json({ result: JSON.parse(json), state: this.state() });
+      })().catch((error) => res.status(400).json({ error: String(error.message ?? error) }));
+    });
+    app.post('/api/references', (req, res) => {
+      void this.enqueue(async () => {
+        const body = object(req.body);
+        const ref = await this.store.upload(body.name, body.base64);
+        this.options.onReferences?.([ref]);
+        return ref;
+      }).then((reference) => res.json({ reference, references: this.store.references }))
+        .catch((error) => res.status(400).json({ error: String(error.message ?? error) }));
+    });
+    app.patch('/api/references/:id', (req, res) => {
+      void this.enqueue(() => {
+        this.store.renameReference(String(req.params.id), object(req.body).name);
+        this.options.onReferences?.(this.store.references.filter((ref) => ref.id === req.params.id));
+      }).then(() => res.json({ references: this.store.references }))
+        .catch((error) => res.status(400).json({ error: String(error.message ?? error) }));
+    });
+    app.delete('/api/references/:id', (req, res) => {
+      void this.enqueue(() => this.store.removeReference(String(req.params.id)))
+        .then(() => res.json({ references: this.store.references }))
+        .catch((error) => res.status(400).json({ error: String(error.message ?? error) }));
+    });
+    app.use('/references', express.static(join(this.store.directory, 'references')));
+    app.use('/exports', express.static(join(this.store.directory, 'exports'), { setHeaders: (res) => res.setHeader('Content-Disposition', 'attachment') }));
+    const publicDir = fileURLToPath(new URL('./public/', import.meta.url));
+    app.get('/overlay', (_req, res) => res.sendFile(join(publicDir, 'index.html')));
+    app.use(express.static(publicDir));
+    app.use((error: { status?: number; message?: string }, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
+      res.status(error.status ?? 400).json({ error: error.message ?? '请求失败' });
+    });
+    for (let offset = 0; offset < (this.options.port === 0 ? 1 : 50); offset++) {
+      const candidate = createServer(app);
+      try {
+        await new Promise<void>((resolve, reject) => {
+          candidate.once('error', reject);
+          candidate.listen(this.options.port + offset, '127.0.0.1', () => { candidate.removeListener('error', reject); resolve(); });
+        });
+        this.server = candidate;
+        this.url = `http://127.0.0.1:${(candidate.address() as AddressInfo).port}`;
+        this.heartbeat = setInterval(() => { for (const response of this.subscribers) response.write(': heartbeat\n\n'); }, 15000);
+        this.heartbeat.unref();
+        return;
+      } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'EADDRINUSE') throw error; }
+    }
+    throw new Error('画布服务没有可用端口');
+  }
+
+  async stop(): Promise<void> {
+    this.stopping = true;
+    this.game.close();
+    if (this.heartbeat) clearInterval(this.heartbeat);
+    await this.tail;
+    await this.brush.close();
+    for (const response of this.subscribers) response.end();
+    this.subscribers.clear();
+    if (this.server) {
+      const server = this.server;
+      this.server = null;
+      await new Promise<void>((resolve) => { server.close(() => resolve()); server.closeIdleConnections(); });
+    }
+  }
+
+  async abort(): Promise<void> {
+    this.stopping = true;
+    await this.brush.close();
+  }
+}

package/src/store.ts

@@ -0,0 +1,286 @@
+import { createHash, randomUUID, randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createCanvas, Image, loadImage, type Canvas } from 'canvas';
+import { blank, color, draw, label, number, object, parseActions, replay, type Board, type DrawStep } from './drawing.ts';
+import { contours, multiply, validateTransform, type Matrix } from './paint.ts';
+
+export interface Reference { id: string; name: string; width: number; height: number; url: string }
+interface SavedCanvas { filename: string; path: string; url: string }
+
+function atomicJson(path: string, value: unknown): void {
+  const temp = `${path}.tmp`;
+  writeFileSync(temp, JSON.stringify(value));
+  renameSync(temp, path);
+}
+
+function patchAction(step: DrawStep, input: unknown): Record<string, unknown> {
+  if (!step.action.paint) throw new Error('patch 需要 p5.brush 步骤；旧动作请使用 action 完整替换');
+  const patch = object(input);
+  const styles: Record<string, readonly string[]> = {
+    fill: ['color', 'mode', 'opacity', 'bleed', 'texture'],
+    stroke: ['brush', 'color', 'width', 'pressure'],
+    hatch: ['brush', 'color', 'width', 'spacing', 'angle'],
+  };
+  const merged: Record<string, unknown> = { ...step.action.paint, label: step.action.label };
+  for (const [key, value] of Object.entries(patch)) {
+    if (!['label', 'path', 'matrix', 'instances', 'clip_to', ...Object.keys(styles)].includes(key)) throw new Error(`未知 patch 字段: ${key}`);
+    if (Object.hasOwn(styles, key)) {
+      if (value === null) { delete merged[key]; continue; }
+      const nested = { ...(merged[key] as Record<string, unknown> | undefined) };
+      for (const [field, change] of Object.entries(object(value))) {
+        if (!styles[key].includes(field)) throw new Error(`未知 patch.${key} 字段: ${field}`);
+        if (change === null) delete nested[field];
+        else nested[field] = change;
+      }
+      merged[key] = nested;
+    } else if ((key === 'clip_to' || key === 'instances') && value === null) delete merged[key];
+    else merged[key] = value;
+  }
+  return merged;
+}
+
+export class CanvasStore {
+  board: Board | null = null;
+  canvas: Canvas | null = null;
+  references: Reference[] = [];
+  readonly directory: string;
+  private rasters = new Map<string, Image>();
+  private rasterBytes = 0;
+
+  constructor(directory: string) {
+    this.directory = resolve(directory);
+    for (const subdir of ['boards', 'references', 'exports', 'layers']) mkdirSync(join(this.directory, subdir), { recursive: true });
+    const indexPath = join(this.directory, 'index.json');
+    if (existsSync(indexPath)) {
+      const index = JSON.parse(readFileSync(indexPath, 'utf8')) as { boardId: string | null; references: Reference[] };
+      this.references = index.references;
+      if (index.boardId) {
+        this.board = JSON.parse(readFileSync(join(this.directory, 'boards', `${index.boardId}.json`), 'utf8')) as Board;
+        this.canvas = this.replay(this.board.steps);
+      }
+    }
+  }
+
+  private persistIndex(board: Board | null, references = this.references): void {
+    atomicJson(join(this.directory, 'index.json'), { boardId: board?.id ?? null, references });
+  }
+
+  current(): Board {
+    if (!this.board) throw new Error('尚未新建画布，请先调用 canvas_new');
+    return this.board;
+  }
+
+  newBoard(args: Record<string, unknown>): Board {
+    const board: Board = {
+      id: randomUUID(), title: label(args.title, '标题'),
+      width: number(args.width ?? 1024, 'width', 64, 2048, true),
+      height: number(args.height ?? 1024, 'height', 64, 2048, true),
+      background: color(args.background ?? '#ffffff'), revision: 0, steps: [],
+    };
+    const canvas = blank(board);
+    atomicJson(join(this.directory, 'boards', `${board.id}.json`), board);
+    this.persistIndex(board);
+    this.board = board;
+    this.canvas = canvas;
+    return board;
+  }
+
+  prepare(input: unknown): DrawStep[] {
+    const board = this.current();
+    const actions = parseActions(input, board);
+    if (board.steps.length + actions.length > 5000) throw new Error('单张画布最多 5000 步，请保存后新建画布');
+    return actions.map((action) => ({ id: randomUUID(), action, seed: randomBytes(4).readUInt32LE() }));
+  }
+
+  prepareEdits(input: unknown): DrawStep[] {
+    const board = this.current();
+    if (!Array.isArray(input) || input.length < 1 || input.length > 64) throw new Error('每批需要 1–64 个修改');
+    const updates = input.map(object);
+    const ids = new Set<unknown>();
+    const originals = updates.map((update) => {
+      const step = board.steps.find((step) => step.id === update.step_id);
+      if (!step) throw new Error('找不到当前画布中的 step_id');
+      if (ids.has(step.id)) throw new Error('同一批不能重复修改同一个 step_id');
+      ids.add(step.id);
+      if (Object.hasOwn(update, 'action') === Object.hasOwn(update, 'patch')) throw new Error('每个修改须指定 action 或 patch，且只能指定一项');
+      return step;
+    });
+    const actions = parseActions(updates.map((update, index) => Object.hasOwn(update, 'patch') ? patchAction(originals[index], update.patch) : update.action), board);
+    const edits = originals.map((step, index) => {
+      return { id: step.id, seed: step.seed, action: actions[index] };
+    });
+    const byId = new Map(edits.map((step) => [step.id, step]));
+    this.validateLayers(board.steps.map((step) => byId.get(step.id) ?? step));
+    return edits;
+  }
+
+  prepareTransform(args: Record<string, unknown>): DrawStep[] {
+    if (!Array.isArray(args.step_ids) || !args.step_ids.length || args.step_ids.length > 64 || new Set(args.step_ids).size !== args.step_ids.length) throw new Error('step_ids 须为 1–64 个不重复的步骤 ID');
+    const ids = args.step_ids;
+    const dx = number(args.dx ?? 0, 'dx', -4096, 4096), dy = number(args.dy ?? 0, 'dy', -4096, 4096);
+    const sx = number(args.scale_x ?? 1, 'scale_x', 0.05, 20), sy = number(args.scale_y ?? sx, 'scale_y', 0.05, 20);
+    const angle = number(args.rotate ?? 0, 'rotate', -360, 360) * Math.PI / 180;
+    const origin = args.origin === undefined ? { x: 0, y: 0 } : object(args.origin);
+    const x = number(origin.x, 'origin.x', -4096, 4096), y = number(origin.y, 'origin.y', -4096, 4096);
+    const c = Math.cos(angle), s = Math.sin(angle);
+    const matrix: Matrix = [c * sx, s * sx, -s * sy, c * sy, x + dx - c * sx * x + s * sy * y, y + dy - s * sx * x - c * sy * y];
+    let instances = 0;
+    return ids.map((id) => {
+      const step = this.current().steps.find((step) => step.id === id);
+      if (!step || step.action.kind !== 'paint') throw new Error('canvas_transform 需要当前画布中的 p5.brush 步骤 ID');
+      const paint = { ...step.action.paint!, matrix: multiply(matrix, step.action.paint!.matrix) };
+      instances += paint.instances?.length ?? 1;
+      if (instances > 256) throw new Error('每批 p5.brush 实例总数最多 256');
+      paint.matrix.forEach((value) => number(value, 'matrix', -8192, 8192));
+      validateTransform(contours(paint.path), paint.matrix, paint.instances);
+      return { id: step.id, seed: step.seed, action: { ...step.action, paint } };
+    });
+  }
+
+  validateLayers(steps: DrawStep[]): void {
+    const earlier = new Map<string, DrawStep>();
+    for (const step of steps) {
+      const clip = step.action.paint?.clip_to;
+      if (clip) {
+        const target = earlier.get(clip);
+        if (!target?.action.paint || contours(target.action.paint.path).some((part) => !part.closed)) throw new Error(`clip_to ${clip} 必须引用更早的闭合 p5.brush 部件；请先修改或撤销依赖它的步骤`);
+      }
+      earlier.set(step.id, step);
+    }
+  }
+
+  cacheRaster(step: DrawStep, png: Buffer): void {
+    const hash = createHash('sha256').update(png).digest('hex');
+    const path = join(this.directory, 'layers', `${hash}.png`);
+    if (!existsSync(path)) writeFileSync(path, png, { flag: 'wx' });
+    step.raster = hash;
+  }
+
+  private raster(step: DrawStep): Image {
+    const key = step.raster!;
+    if (!/^[a-f0-9]{64}$/.test(key)) throw new Error('p5.brush 图层缓存缺失或损坏');
+    let image = this.rasters.get(key);
+    if (image) this.rasters.delete(key);
+    else {
+      image = new Image(); image.src = readFileSync(join(this.directory, 'layers', `${key}.png`));
+      this.rasterBytes += image.width * image.height * 4;
+    }
+    this.rasters.set(key, image);
+    while (this.rasterBytes > 128 * 1024 * 1024 && this.rasters.size > 1) {
+      const [oldKey, old] = this.rasters.entries().next().value!;
+      this.rasters.delete(oldKey); this.rasterBytes -= old.width * old.height * 4;
+    }
+    return image;
+  }
+
+  draw(canvas: Canvas, board: Board, step: DrawStep): void { draw(canvas, board, step, (step) => this.raster(step)); }
+  replay(steps: DrawStep[]): Canvas {
+    this.validateLayers(steps);
+    return replay({ ...this.current(), steps }, (step) => this.raster(step));
+  }
+
+  copyCanvas(): Canvas {
+    const board = this.current();
+    const canvas = createCanvas(board.width, board.height);
+    canvas.getContext('2d').drawImage(this.canvas!, 0, 0);
+    return canvas;
+  }
+
+  commit(steps: DrawStep[], canvas: Canvas): void {
+    const board = { ...this.current(), revision: this.current().revision + 1, steps };
+    atomicJson(join(this.directory, 'boards', `${board.id}.json`), board);
+    this.board = board;
+    this.canvas = canvas;
+  }
+
+  undo(id: unknown): string {
+    const board = this.current();
+    if (typeof id !== 'string' || !board.steps.some((step) => step.id === id)) throw new Error('找不到当前画布中的 step_id');
+    const steps = board.steps.filter((step) => step.id !== id);
+    this.commit(steps, this.replay(steps));
+    return id;
+  }
+
+  png(): Buffer { this.current(); return this.canvas!.toBuffer('image/png'); }
+
+  save(filename?: unknown): SavedCanvas {
+    const board = this.current();
+    let stem: string;
+    if (filename !== undefined) {
+      stem = label(filename, '文件名').replace(/\.png$/i, '');
+      if (/[<>:"/\\|?*\x00-\x1f]/.test(stem) || /^\.+$/.test(stem)) throw new Error('文件名不能包含目录或特殊字符');
+    } else stem = board.title.replace(/[<>:"/\\|?*\x00-\x1f]/g, '_');
+    const name = `${stem}-${randomUUID().slice(0, 8)}.png`;
+    const path = join(this.directory, 'exports', name);
+    writeFileSync(path, this.png(), { flag: 'wx' });
+    return { filename: name, path, url: `/exports/${encodeURIComponent(name)}` };
+  }
+
+  async upload(name: unknown, data: unknown): Promise<Reference> {
+    if (this.references.length >= 64) throw new Error('参考图队列最多 64 张，请先移除不需要的图片');
+    const displayName = label(name, '参考图名称');
+    if (typeof data !== 'string' || data.length > 14_000_000 || !/^[A-Za-z0-9+/]+={0,2}$/.test(data)) throw new Error('参考图必须是最多 10 MiB 的 PNG/JPEG');
+    const bytes = Buffer.from(data, 'base64');
+    if (bytes.length > 10 * 1024 * 1024) throw new Error('参考图不能超过 10 MiB');
+    const size = imageDimensions(bytes);
+    if (size.width < 1 || size.height < 1 || size.width > 4096 || size.height > 4096) throw new Error('参考图尺寸必须在 1–4096 像素之间');
+    const image = await loadImage(bytes);
+    const normalized = createCanvas(image.width, image.height);
+    normalized.getContext('2d').drawImage(image, 0, 0);
+    const id = randomUUID();
+    const reference: Reference = { id, name: displayName, width: image.width, height: image.height, url: `/references/${id}.png` };
+    writeFileSync(join(this.directory, 'references', `${id}.png`), normalized.toBuffer('image/png'));
+    const next = [...this.references, reference];
+    this.persistIndex(this.board, next);
+    this.references = next;
+    return reference;
+  }
+
+  renameReference(id: string, name: unknown): void {
+    if (!this.references.some((ref) => ref.id === id)) throw new Error('参考图不存在');
+    const next = this.references.map((ref) => ref.id === id ? { ...ref, name: label(name, '参考图名称') } : ref);
+    this.persistIndex(this.board, next);
+    this.references = next;
+  }
+
+  removeReference(id: string): void {
+    if (!this.references.some((ref) => ref.id === id)) throw new Error('参考图不存在');
+    const next = this.references.filter((ref) => ref.id !== id);
+    this.persistIndex(this.board, next);
+    this.references = next;
+  }
+
+  referenceImages(ids: unknown): { ref: Reference; png: Buffer }[] {
+    if (ids !== undefined && (!Array.isArray(ids) || ids.length > 8 || ids.some((id) => typeof id !== 'string'))) throw new Error('ids 须为最多 8 个参考图 ID');
+    const selected = ids === undefined ? this.references.slice(0, 8).map((ref) => ref.id) : ids as string[];
+    return selected.map((id) => {
+      const ref = this.references.find((ref) => ref.id === id);
+      if (!ref) throw new Error(`参考图不存在: ${id}`);
+      return { ref, png: readFileSync(join(this.directory, 'references', `${id}.png`)) };
+    });
+  }
+}
+
+/** Read dimensions before invoking the native decoder; uploads accept PNG and JPEG only. */
+export function imageDimensions(bytes: Buffer): { width: number; height: number } {
+  if (bytes.length >= 24 && bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) {
+    return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+  }
+  if (bytes[0] === 0xff && bytes[1] === 0xd8) {
+    let offset = 2;
+    while (offset + 3 < bytes.length) {
+      if (bytes[offset++] !== 0xff) break;
+      while (bytes[offset] === 0xff) offset++;
+      const marker = bytes[offset++];
+      if (marker === 0xda || marker === 0xd9) break;
+      if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) continue;
+      if (offset + 2 > bytes.length) break;
+      const length = bytes.readUInt16BE(offset);
+      if (length < 2 || offset + length > bytes.length) break;
+      if ([0xc0, 0xc1, 0xc2].includes(marker) && length >= 7) return { width: bytes.readUInt16BE(offset + 5), height: bytes.readUInt16BE(offset + 3) };
+      offset += length;
+    }
+  }
+  throw new Error('无法读取 PNG/JPEG 参考图');
+}