@pixerate/editor 0.103.0 → 0.104.0

package/dist/paint-editor/index.js

@@ -8,12 +8,15 @@ import {
 import {
   RasterCompositor,
   bytesToBase64,
+  decodePng,
   encodePng,
   findLayer,
   flattenLayers,
   insertLayer,
   isLayerLocked,
-  mapLayer
+  mapLayer,
+  parseDataUrl,
+  pngDataUrl
 } from "../chunk-67FRIOPZ.js";
 import "../chunk-GX332W2C.js";
 import {
@@ -43,6 +46,7 @@ import {
   finishTile,
   isBlendMode,
   readPixel,
+  readRegion,
   surfaceFromPixels,
   tileKey,
   tilesInRect
@@ -1010,6 +1014,8 @@ var PaintStrokeSession = class {
   /** Adds raw pen samples (document pixels). */
   push(points) {
     if (this.closed || !points.length) return;
+    const filter = this.init.inputFilter;
+    if (filter) points = points.map(filter);
     for (const p of points) this.points.push(p);
     this.lastRaw = points[points.length - 1];
     if (this.dry) this.update(this.dry.push(points));
@@ -1307,7 +1313,7 @@ function downsampleRgba(data, width, height, tw, th) {
 // src/paint-editor/serialize.ts
 var PAINT_FORMAT = "pixerate-paint";
 var PAINT_SCHEMA_VERSION = 1;
-var KNOWN = /* @__PURE__ */ new Set(["format", "version", "width", "height", "dpi", "paper", "layers", "assets", "activeLayerId", "strokes"]);
+var KNOWN = /* @__PURE__ */ new Set(["format", "version", "width", "height", "dpi", "paper", "layers", "assets", "activeLayerId", "strokes", "guides", "swatches"]);
 function documentExtensions(raw) {
   const out = {};
   for (const [k, v] of Object.entries(raw)) if (!KNOWN.has(k)) out[k] = v;
@@ -1325,6 +1331,8 @@ function header(state, options) {
     activeLayerId: state.activeLayerId
   };
   if (options.strokes !== false && state.strokes.length) out.strokes = JSON.parse(JSON.stringify(state.strokes));
+  if (options.guides !== void 0) out.guides = JSON.parse(JSON.stringify(options.guides));
+  if (options.swatches !== void 0) out.swatches = JSON.parse(JSON.stringify(options.swatches));
   return out;
 }
 function serializePaintDocument(state, options = {}) {
@@ -1372,7 +1380,7 @@ function deserializePaintDocument(raw) {
   const layers = paintLayersOnly(deserializeLayers(r.layers, { assets, problems }), problems);
   const wanted = typeof r.activeLayerId === "string" ? r.activeLayerId : null;
   const activeLayerId = wanted && findLayer(layers, wanted) ? wanted : flattenLayers(layers).filter((l) => l.type === "pixel").pop()?.id ?? null;
-  return { state: { canvas, paper, layers, activeLayerId, strokes: readStrokes(r.strokes, problems) }, extensions: documentExtensions(r), problems };
+  return { state: { canvas, paper, layers, activeLayerId, strokes: readStrokes(r.strokes, problems) }, extensions: documentExtensions(r), guides: r.guides, swatches: r.swatches, problems };
 }
 async function deserializePaintDocumentAsync(raw, store) {
   if (!raw || typeof raw !== "object") throw new Error("Not a paint document: expected a JSON object.");
@@ -1562,6 +1570,411 @@ function renderBrushThumbnail(brush, options) {
   return { width, height, data };
 }
 
+// src/paint-editor/guides.ts
+var SYMMETRY_MODES = ["off", "vertical", "horizontal", "dual", "diagonal", "kaleidoscope"];
+function defaultGuides(canvas) {
+  return {
+    symmetry: { mode: "off", center: { x: canvas.width / 2, y: canvas.height / 2 }, rotation: 0, segments: 6, mirror: true },
+    perspective: { enabled: false, points: [], snap: true },
+    tracing: null,
+    references: []
+  };
+}
+var MAX_COORDINATE = 1e6;
+var finite2 = (v) => typeof v === "number" && Number.isFinite(v);
+var coord = (v, d) => finite2(v) && Math.abs(v) <= MAX_COORDINATE ? v : d;
+function normalizeSymmetry(raw, base) {
+  const r = raw;
+  const c = r.center ?? {};
+  return {
+    mode: SYMMETRY_MODES.includes(r.mode) ? r.mode : base.mode,
+    center: { x: coord(c.x, base.center.x), y: coord(c.y, base.center.y) },
+    rotation: finite2(r.rotation) ? (r.rotation % 360 + 360) % 360 : base.rotation,
+    segments: finite2(r.segments) ? Math.min(32, Math.max(2, Math.round(r.segments))) : base.segments,
+    mirror: typeof r.mirror === "boolean" ? r.mirror : base.mirror
+  };
+}
+function reflectAbout(c, a) {
+  const dx = Math.cos(a);
+  const dy = Math.sin(a);
+  const m00 = 2 * dx * dx - 1;
+  const m01 = 2 * dx * dy;
+  const m11 = 2 * dy * dy - 1;
+  return [m00, m01, m01, m11, c.x - (m00 * c.x + m01 * c.y), c.y - (m01 * c.x + m11 * c.y)];
+}
+function rotateAbout(c, a) {
+  const cos = Math.cos(a);
+  const sin = Math.sin(a);
+  return [cos, -sin, sin, cos, c.x - (cos * c.x - sin * c.y), c.y - (sin * c.x + cos * c.y)];
+}
+var rad = (deg) => deg * Math.PI / 180;
+function symmetryAxisAngles(g) {
+  if (g.mode === "off") return [];
+  if (g.mode === "kaleidoscope") return Array.from({ length: g.segments }, (_, k) => rad(g.rotation) + k * Math.PI / g.segments);
+  const initial = g.mode === "horizontal" ? 0 : g.mode === "diagonal" ? 45 : 90;
+  const a = rad(initial + g.rotation);
+  return g.mode === "dual" ? [a, a + Math.PI / 2] : [a];
+}
+function symmetryCopies(g) {
+  const c = g.center;
+  switch (g.mode) {
+    case "off":
+      return [];
+    case "vertical":
+    case "horizontal":
+    case "diagonal":
+      return symmetryAxisAngles(g).map((a) => reflectAbout(c, a));
+    case "dual": {
+      const [a, b] = symmetryAxisAngles(g);
+      return [reflectAbout(c, a), reflectAbout(c, b), rotateAbout(c, Math.PI)];
+    }
+    case "kaleidoscope": {
+      const out = [];
+      const n = g.segments;
+      for (let k = 1; k < n; k++) out.push(rotateAbout(c, 2 * Math.PI * k / n));
+      if (g.mirror) {
+        const first = reflectAbout(c, rad(g.rotation));
+        for (let k = 0; k < n; k++) out.push(composeAffine(rotateAbout(c, 2 * Math.PI * k / n), first));
+      }
+      return out;
+    }
+  }
+}
+function symmetryAxisSegments(g, size) {
+  const out = [];
+  for (const a of symmetryAxisAngles(g)) {
+    const d = [Math.cos(a), Math.sin(a)];
+    const origin = [g.center.x, g.center.y];
+    const extent = [size.width, size.height];
+    let lo = -Infinity;
+    let hi = Infinity;
+    let ok = true;
+    for (let i = 0; i < 2; i++) {
+      if (Math.abs(d[i]) < 1e-12) {
+        if (origin[i] < 0 || origin[i] > extent[i]) ok = false;
+      } else {
+        const t0 = -origin[i] / d[i];
+        const t1 = (extent[i] - origin[i]) / d[i];
+        lo = Math.max(lo, Math.min(t0, t1));
+        hi = Math.min(hi, Math.max(t0, t1));
+      }
+    }
+    if (!ok || !Number.isFinite(lo) || !Number.isFinite(hi) || hi < lo) continue;
+    out.push([{ x: g.center.x + lo * d[0], y: g.center.y + lo * d[1] }, { x: g.center.x + hi * d[0], y: g.center.y + hi * d[1] }]);
+  }
+  return out;
+}
+function normalizePerspective(raw, base) {
+  const r = raw;
+  let points = base.points;
+  if (Array.isArray(r.points)) {
+    if (r.points.length > 3) throw new Error(`A perspective guide has one to three vanishing points; got ${r.points.length}.`);
+    points = r.points.map((p, i) => {
+      const q = p ?? {};
+      if (!finite2(q.x) || !finite2(q.y) || Math.abs(q.x) > MAX_COORDINATE || Math.abs(q.y) > MAX_COORDINATE) {
+        throw new Error(`points[${i}] needs finite x and y within \xB1${MAX_COORDINATE} document pixels.`);
+      }
+      return { x: q.x, y: q.y };
+    });
+  }
+  const enabled = typeof r.enabled === "boolean" ? r.enabled : base.enabled;
+  if (enabled && !points.length) throw new Error("An enabled perspective guide needs at least one vanishing point; pass points.");
+  return { enabled, points, snap: typeof r.snap === "boolean" ? r.snap : base.snap };
+}
+function perspectiveDirections(g, p) {
+  const out = [];
+  for (const v of g.points) {
+    const dx = v.x - p.x;
+    const dy = v.y - p.y;
+    const len = Math.hypot(dx, dy);
+    if (len > 1e-6) out.push({ x: dx / len, y: dy / len });
+  }
+  if (g.points.length <= 2) out.push({ x: 0, y: 1 });
+  if (g.points.length <= 1) out.push({ x: 1, y: 0 });
+  return out;
+}
+var SNAP_DECIDE_DISTANCE = 6;
+var PerspectiveSnapper = class {
+  constructor(guide) {
+    this.guide = guide;
+  }
+  guide;
+  start = null;
+  dir = null;
+  /** The line the stroke follows, once chosen. */
+  get line() {
+    return this.start && this.dir ? { from: this.start, direction: this.dir } : null;
+  }
+  snap(p) {
+    if (!this.guide.enabled || !this.guide.snap || !this.guide.points.length) return p;
+    if (!this.start) {
+      this.start = { x: p.x, y: p.y };
+      return p;
+    }
+    const s = this.start;
+    if (!this.dir) {
+      const dx = p.x - s.x;
+      const dy = p.y - s.y;
+      const len = Math.hypot(dx, dy);
+      if (len < SNAP_DECIDE_DISTANCE) return { ...p, x: s.x, y: s.y };
+      let best = null;
+      let bestDot = -1;
+      for (const d2 of perspectiveDirections(this.guide, s)) {
+        const dot = Math.abs((dx * d2.x + dy * d2.y) / len);
+        if (dot > bestDot) {
+          bestDot = dot;
+          best = d2;
+        }
+      }
+      this.dir = best;
+      if (!best) return p;
+    }
+    const d = this.dir;
+    const t = (p.x - s.x) * d.x + (p.y - s.y) * d.y;
+    return { ...p, x: s.x + d.x * t, y: s.y + d.y * t };
+  }
+};
+function perspectiveGuideLines(g, size, count = 12) {
+  const out = [];
+  const far = Math.hypot(size.width, size.height) * 4;
+  for (const v of g.points) {
+    const cx = size.width / 2 - v.x;
+    const cy = size.height / 2 - v.y;
+    const inside = v.x >= 0 && v.y >= 0 && v.x <= size.width && v.y <= size.height;
+    const mid = Math.atan2(cy, cx);
+    const spread = inside ? Math.PI : Math.min(Math.PI, 2 * Math.atan2(Math.hypot(size.width, size.height) / 2, Math.hypot(cx, cy)));
+    for (let i = 0; i < count; i++) {
+      const a = inside ? 2 * Math.PI * i / count : mid - spread / 2 + spread * (i + 0.5) / count;
+      out.push([{ ...v }, { x: v.x + Math.cos(a) * far, y: v.y + Math.sin(a) * far }]);
+    }
+  }
+  return out;
+}
+
+// src/paint-editor/color.ts
+var HEX2 = /^#?([0-9a-f]{6})$/i;
+function parseHexColor(value, what = "color") {
+  const m = typeof value === "string" ? HEX2.exec(value.trim()) : null;
+  if (!m) throw new Error(`${what} is ${JSON.stringify(value)}; use #rrggbb, e.g. "#2a4b8d".`);
+  const n = parseInt(m[1], 16);
+  return [n >> 16 & 255, n >> 8 & 255, n & 255];
+}
+function rgbToHexColor(r, g, b) {
+  return "#" + [r, g, b].map((v) => Math.round(Math.min(255, Math.max(0, v))).toString(16).padStart(2, "0")).join("");
+}
+function rgbToHsv(r, g, b) {
+  const R = r / 255;
+  const G = g / 255;
+  const B = b / 255;
+  const max = Math.max(R, G, B);
+  const min = Math.min(R, G, B);
+  const d = max - min;
+  let h = 0;
+  if (d > 0) {
+    if (max === R) h = 60 * ((G - B) / d % 6);
+    else if (max === G) h = 60 * ((B - R) / d + 2);
+    else h = 60 * ((R - G) / d + 4);
+  }
+  if (h < 0) h += 360;
+  return { h, s: max === 0 ? 0 : d / max, v: max };
+}
+function hsvToRgb(h, s, v) {
+  const hh = (h % 360 + 360) % 360 / 60;
+  const c = v * s;
+  const x = c * (1 - Math.abs(hh % 2 - 1));
+  const m = v - c;
+  const [r, g, b] = hh < 1 ? [c, x, 0] : hh < 2 ? [x, c, 0] : hh < 3 ? [0, c, x] : hh < 4 ? [0, x, c] : hh < 5 ? [x, 0, c] : [c, 0, x];
+  return [Math.round((r + m) * 255), Math.round((g + m) * 255), Math.round((b + m) * 255)];
+}
+function rgbToHsl(r, g, b) {
+  const { h } = rgbToHsv(r, g, b);
+  const max = Math.max(r, g, b) / 255;
+  const min = Math.min(r, g, b) / 255;
+  const l = (max + min) / 2;
+  const d = max - min;
+  return { h, s: d === 0 ? 0 : d / (1 - Math.abs(2 * l - 1)), l };
+}
+function hslToRgb(h, s, l) {
+  const c = (1 - Math.abs(2 * l - 1)) * s;
+  const v = l + c / 2;
+  return hsvToRgb(h, v === 0 ? 0 : c / v, v);
+}
+var RYB_STOPS = [
+  [0, 0],
+  [60, 30],
+  [120, 60],
+  [180, 120],
+  [240, 240],
+  [300, 280],
+  [360, 360]
+];
+function piecewise(v, from) {
+  const x = (v % 360 + 360) % 360;
+  const to = from === 0 ? 1 : 0;
+  for (let i = 1; i < RYB_STOPS.length; i++) {
+    const a = RYB_STOPS[i - 1];
+    const b = RYB_STOPS[i];
+    if (x <= b[from]) return a[to] + (x - a[from]) / (b[from] - a[from]) * (b[to] - a[to]);
+  }
+  return x;
+}
+function wheelToHue(angle, wheel) {
+  return wheel === "rgb" ? (angle % 360 + 360) % 360 : piecewise(angle, 0);
+}
+function hueToWheel(hue, wheel) {
+  return wheel === "rgb" ? (hue % 360 + 360) % 360 : piecewise(hue, 1);
+}
+var HARMONY_KINDS = ["complementary", "split-complementary", "analogous", "triadic", "tetradic", "square", "monochromatic"];
+function colorHarmony(base, kind, options = {}) {
+  const wheel = options.wheel ?? "ryb";
+  const [r, g, b] = parseHexColor(base, "base");
+  const hsv = rgbToHsv(r, g, b);
+  const start = hueToWheel(hsv.h, wheel);
+  const at = (angle) => {
+    const a = (angle % 360 + 360) % 360;
+    const [rr, gg, bb] = hsvToRgb(wheelToHue(a, wheel), hsv.s, hsv.v);
+    return { color: rgbToHexColor(rr, gg, bb), angle: Math.round(a * 10) / 10 };
+  };
+  const spread = options.spread ?? 30;
+  const offsets = {
+    complementary: [0, 180],
+    "split-complementary": [0, 180 - spread, 180 + spread],
+    analogous: [0, -spread, spread],
+    triadic: [0, 120, 240],
+    tetradic: [0, 60, 180, 240],
+    square: [0, 90, 180, 270]
+  };
+  if (kind === "monochromatic") {
+    const hsl = rgbToHsl(r, g, b);
+    const steps = [0, -0.3, -0.15, 0.15, 0.3];
+    return steps.map((d) => {
+      const [rr, gg, bb] = d === 0 ? [r, g, b] : hslToRgb(hsl.h, hsl.s, Math.min(0.97, Math.max(0.03, hsl.l + d)));
+      return { color: rgbToHexColor(rr, gg, bb), angle: Math.round(start * 10) / 10 };
+    });
+  }
+  return offsets[kind].map((o, i) => i === 0 ? { color: rgbToHexColor(r, g, b), angle: Math.round(start * 10) / 10 } : at(start + o));
+}
+var DEFAULT_SWATCHES = [
+  { color: "#f7f5ee", name: "Warm white" },
+  { color: "#f3d23a", name: "Lemon yellow" },
+  { color: "#c8912f", name: "Yellow ochre" },
+  { color: "#d23a2a", name: "Warm red" },
+  { color: "#9e1f3d", name: "Crimson" },
+  { color: "#8a4a2b", name: "Burnt earth" },
+  { color: "#2f3f9e", name: "Deep blue" },
+  { color: "#1d6f8f", name: "Cool blue" },
+  { color: "#4f6e2c", name: "Leaf green" },
+  { color: "#25221f", name: "Warm black" }
+];
+
+// src/paint-editor/mixing-pad.ts
+var MIXING_PAD_WIDTH = 360;
+var MIXING_PAD_HEIGHT = 220;
+var PAD_PAINT = normalizePaintBrush({
+  id: "pad-paint",
+  name: "Pad paint",
+  category: "mixer",
+  engine: "mixer",
+  tip: { size: 28, hardness: 0.75, spacing: 0.1, opacity: 1, flow: 0.7, pressureSize: false, pressureOpacity: false },
+  mixer: { wet: 0.45, load: 1, mix: 0.4, loadEachStroke: true, cleanEachStroke: true, mixing: "pigment" }
+});
+var PAD_KNIFE = normalizePaintBrush({
+  id: "pad-knife",
+  name: "Palette knife",
+  category: "smudge",
+  engine: "mixer",
+  loadsColor: false,
+  tip: { size: 34, hardness: 0.9, spacing: 0.08, roundness: 0.35, angle: 90, opacity: 1, flow: 0.85, pressureSize: false, pressureOpacity: false },
+  mixer: { wet: 1, load: 0, mix: 1, loadEachStroke: false, cleanEachStroke: true, mixing: "pigment" }
+});
+var MixingPad = class {
+  width = MIXING_PAD_WIDTH;
+  height = MIXING_PAD_HEIGHT;
+  surface = emptySurface(4);
+  /** Increments on every change (for redrawing). */
+  version = 0;
+  /** Paints (`paint`, with `color`) or smears (`knife`) through `points` in pad pixels. */
+  stroke(points, options) {
+    if (!points.length) throw new Error("points is empty; give at least one {x, y} in pad pixels.");
+    for (const [i, p] of points.entries()) {
+      if (!Number.isFinite(p.x) || !Number.isFinite(p.y) || p.x < 0 || p.y < 0 || p.x > this.width || p.y > this.height) {
+        throw new Error(`points[${i}] (${p.x}, ${p.y}) is off the ${this.width}\xD7${this.height} mixing pad.`);
+      }
+    }
+    let brush = options.tool === "knife" ? PAD_KNIFE : PAD_PAINT;
+    if (options.size !== void 0) brush = normalizePaintBrush({ tip: { ...brush.tip, size: options.size } }, brush);
+    const [r, g, b] = hexToRgb8(options.color);
+    let result = null;
+    const session = new PaintStrokeSession(
+      { update: () => {
+      }, commit: (_s, s) => result = s },
+      {
+        layerId: "mixing-pad",
+        surface: this.surface,
+        offset: { x: 0, y: 0 },
+        lockTransparency: false,
+        brush,
+        color: [r, g, b, 255],
+        background: [255, 255, 255, 255],
+        grain: null,
+        paperDepth: 0,
+        seed: 1,
+        colorHex: options.color,
+        affineCopies: [],
+        copies: [IDENTITY_COPY],
+        mixerLoad: mixerLoadForStroke(brush, EMPTY_MIXER_LOAD, [r / 255, g / 255, b / 255])
+      }
+    );
+    session.push(points);
+    const res = session.end();
+    if (result) {
+      this.surface = result;
+      this.version++;
+    }
+    return { bounds: res.bounds };
+  }
+  /** The average colour within `radius` pixels of (x, y), or `null` where the pad is bare. */
+  pick(x, y, radius = 3) {
+    if (!(x >= 0 && y >= 0 && x < this.width && y < this.height)) throw new Error(`(${x}, ${y}) is off the ${this.width}\xD7${this.height} mixing pad.`);
+    const r = Math.max(0, Math.round(radius));
+    const x0 = Math.max(0, Math.floor(x) - r);
+    const y0 = Math.max(0, Math.floor(y) - r);
+    const x1 = Math.min(this.width, Math.floor(x) + r + 1);
+    const y1 = Math.min(this.height, Math.floor(y) + r + 1);
+    const px = readRegion(this.surface, { x: x0, y: y0, width: x1 - x0, height: y1 - y0 });
+    let R = 0;
+    let G = 0;
+    let B = 0;
+    let A = 0;
+    for (let i = 0; i < px.length; i += 4) {
+      const a = px[i + 3];
+      R += px[i] * a;
+      G += px[i + 1] * a;
+      B += px[i + 2] * a;
+      A += a;
+    }
+    if (A === 0) return null;
+    const hex = (v) => Math.round(v / A).toString(16).padStart(2, "0");
+    return `#${hex(R)}${hex(G)}${hex(B)}`;
+  }
+  clear() {
+    this.surface = emptySurface(4);
+    this.version++;
+  }
+  /** The pad over white, `width × height` RGBA. */
+  pixels() {
+    const px = readRegion(this.surface, { x: 0, y: 0, width: this.width, height: this.height });
+    for (let i = 0; i < px.length; i += 4) {
+      const a = px[i + 3] / 255;
+      px[i] = Math.round(px[i] * a + 255 * (1 - a));
+      px[i + 1] = Math.round(px[i + 1] * a + 255 * (1 - a));
+      px[i + 2] = Math.round(px[i + 2] * a + 255 * (1 - a));
+      px[i + 3] = 255;
+    }
+    return px;
+  }
+};
+
 // src/paint-editor/controller.ts
 var PaintEditorError = class extends Error {
   constructor(message) {
@@ -1569,9 +1982,9 @@ var PaintEditorError = class extends Error {
     this.name = "PaintEditorError";
   }
 };
-var HEX2 = /^#[0-9a-f]{6}$/i;
+var HEX3 = /^#[0-9a-f]{6}$/i;
 function parseColor(value, what = "color") {
-  if (typeof value !== "string" || !HEX2.test(value.trim())) throw new PaintEditorError(`${what} is ${JSON.stringify(value)}; use #rrggbb, e.g. "#2a4b8d".`);
+  if (typeof value !== "string" || !HEX3.test(value.trim())) throw new PaintEditorError(`${what} is ${JSON.stringify(value)}; use #rrggbb, e.g. "#2a4b8d".`);
   return value.trim().toLowerCase();
 }
 function rgbaOf(hex) {
@@ -1612,6 +2025,13 @@ var PaintEditorController = class {
   dirty = "all";
   seedCounter = 1;
   strokeCounter = 1;
+  guides;
+  swatches = DEFAULT_SWATCHES.map((s) => ({ ...s }));
+  pad = new MixingPad();
+  tracingVersion = 1;
+  tracingCache = null;
+  imagePixels = /* @__PURE__ */ new Map();
+  nextReferenceId = 1;
   viewCompositor = createPaintCompositor();
   exportCompositor = createPaintCompositor();
   constructor(options = {}) {
@@ -1623,6 +2043,7 @@ var PaintEditorController = class {
     this.color = options.color ? parseColor(options.color) : "#1f2937";
     this.hand = options.hand === "left" ? "left" : "right";
     this.encodeImage = options.encodeImage;
+    this.guides = defaultGuides(this.doc.canvas);
   }
   // --- State and events ----------------------------------------------------------
   subscribe(listener) {
@@ -1654,6 +2075,9 @@ var PaintEditorController = class {
       canRedo: this.redoStack.length > 0 && !this.session,
       undoLabel: last?.label ?? null,
       redoLabel: next?.label ?? null,
+      guides: this.guides,
+      swatches: this.swatches,
+      mixingPadVersion: this.pad.version,
       stroking: Boolean(this.session),
       version: this.version
     };
@@ -1723,6 +2147,8 @@ var PaintEditorController = class {
       paper: options.paper === void 0 ? this.doc.paper : this.resolvePaper(options.paper)
     });
     this.extensions = {};
+    this.guides = { ...this.guides, symmetry: { ...this.guides.symmetry, center: { x: next.canvas.width / 2, y: next.canvas.height / 2 } }, tracing: null };
+    this.tracingVersion++;
     this.commit("New canvas", next);
     return next;
   }
@@ -2145,7 +2571,7 @@ var PaintEditorController = class {
   }
   /** Extra copies every new stroke paints (the painting guides add mirror and kaleidoscope copies). */
   strokeCopies() {
-    return [];
+    return symmetryCopies(this.guides.symmetry);
   }
   sessionFor(doc, init, host) {
     const layer = (() => {
@@ -2160,7 +2586,11 @@ var PaintEditorController = class {
       return l;
     })();
     const brush = this.strokeBrush(init);
-    const color = init.color === void 0 ? this.color : parseColor(init.color);
+    let color = init.color === void 0 ? this.color : parseColor(init.color);
+    const tracing = this.guides.tracing;
+    if (init.color === void 0 && init.start && tracing?.visible && tracing.sampleColors) color = this.sampleTracingColor(init.start.x, init.start.y) ?? color;
+    const perspective = this.guides.perspective;
+    const snapper = init.snapToPerspective && perspective.enabled && perspective.snap ? new PerspectiveSnapper(perspective) : null;
     const rgba = rgbaOf(color);
     const seed = init.seed ?? mix32(this.seedCounter++ * 2654435761 >>> 0) & 2147483647;
     const copies = (init.copies ?? this.strokeCopies()).filter((m) => m.some((v, i) => v !== IDENTITY_AFFINE[i]));
@@ -2178,6 +2608,7 @@ var PaintEditorController = class {
       colorHex: color,
       affineCopies: copies,
       copies: [IDENTITY_AFFINE, ...copies].map(affineCopy),
+      inputFilter: snapper ? (p) => snapper.snap(p) : void 0,
       mixerLoad: brush.engine === "mixer" ? mixerLoadForStroke(brush, this.mixerLoad, [rgba[0] / 255, rgba[1] / 255, rgba[2] / 255]) : EMPTY_MIXER_LOAD
     });
     return session;
@@ -2222,7 +2653,7 @@ var PaintEditorController = class {
         this.commit(`${brush.name} stroke`, { ...this.doc, layers: mapLayer(this.doc.layers, l.id, () => ({ ...l, surface })), strokes: [...this.doc.strokes, stroke] });
       }
     };
-    const session = this.sessionFor(this.doc, init, host);
+    const session = this.sessionFor(this.doc, { snapToPerspective: true, ...init }, host);
     this.session = session;
     this.emit([]);
     return session;
@@ -2254,7 +2685,7 @@ var PaintEditorController = class {
   paintStroke(init) {
     this.requireIdle("painting");
     const points = this.checkPoints(init.points);
-    const { doc, result, brush } = this.runStroke(this.doc, init, points);
+    const { doc, result, brush } = this.runStroke(this.doc, { ...init, start: init.start ?? points[0] }, points);
     if (result.mixerLoad && brush.loadsColor) this.mixerLoad = result.mixerLoad;
     if (doc !== this.doc) this.commit(`${brush.name} stroke`, doc);
     else this.emit([]);
@@ -2339,7 +2770,20 @@ var PaintEditorController = class {
   }
   /** View-only layers between the paper and the paint (the painting guides add the tracing image). */
   underlayLayers() {
-    return [];
+    const t = this.guides.tracing;
+    if (!t || !t.visible) return [];
+    return [this.tracingNode(t)];
+  }
+  /** The tracing image resampled onto the canvas (cached until it or the canvas changes). */
+  tracingNode(t) {
+    const { width, height } = this.doc.canvas;
+    const key = this.tracingVersion * 100003 + width * 7 + height;
+    if (this.tracingCache?.key === key && this.tracingCache.node.opacity === t.opacity) return this.tracingCache.node;
+    const src = this.imagePixels.get(t.src) ?? this.decodeImage(t.src);
+    const image = resampleInto(src, t.rect, width, height);
+    const node = { type: "image", id: TRACING_NODE_ID, name: "Tracing", visible: true, opacity: t.opacity, blend: "normal", image, version: key + Math.round(t.opacity * 1e3) / 1e4 };
+    this.tracingCache = { key, node };
+    return node;
   }
   renderLayers(options, view = false) {
     let layers = this.currentLayers();
@@ -2380,14 +2824,18 @@ var PaintEditorController = class {
   // --- Save, load and export -------------------------------------------------------
   /** The document as JSON with inline PNG assets. */
   toJSON(options = {}) {
-    return serializePaintDocument(this.doc, { strokes: options.strokes, extensions: this.extensions });
+    return serializePaintDocument(this.doc, { strokes: options.strokes, extensions: this.extensions, guides: this.guides, swatches: this.swatches });
   }
   /** The document as JSON with each PNG stored in `store`. */
   toJSONExternal(store, options = {}) {
-    return serializePaintDocumentExternal(this.doc, store, { strokes: options.strokes, extensions: this.extensions });
+    return serializePaintDocumentExternal(this.doc, store, { strokes: options.strokes, extensions: this.extensions, guides: this.guides, swatches: this.swatches });
   }
   adopt(loaded) {
     this.extensions = loaded.extensions;
+    this.readGuides(loaded.guides, loaded.state, loaded.problems);
+    if (Array.isArray(loaded.swatches)) {
+      this.swatches = loaded.swatches.filter((x) => Boolean(x) && typeof x.color === "string" && /^#[0-9a-f]{6}$/i.test(x.color)).map((x) => typeof x.name === "string" ? { color: x.color.toLowerCase(), name: x.name } : { color: x.color.toLowerCase() });
+    }
     for (const s of loaded.state.strokes) {
       const n = Number(/^s(\d+)$/.exec(s.id)?.[1] ?? 0);
       if (n >= this.strokeCounter) this.strokeCounter = n + 1;
@@ -2476,20 +2924,630 @@ var PaintEditorController = class {
     const img = this.renderPreview(options);
     return { data: bytesToBase64(encodePng(img.width, img.height, img.data)), width: img.width, height: img.height };
   }
+  // --- Guides --------------------------------------------------------------------
+  setGuides(next) {
+    this.guides = next;
+    this.emit("all");
+    return next;
+  }
+  /** Mirror and kaleidoscope painting: every new stroke paints its copies too (one stroke, one undo step). */
+  setSymmetry(update) {
+    const symmetry = normalizeSymmetry(update, this.guides.symmetry);
+    this.setGuides({ ...this.guides, symmetry });
+    return symmetry;
+  }
+  /** Perspective guides with one to three vanishing points that pointer strokes snap to. */
+  setPerspective(update) {
+    let perspective;
+    try {
+      perspective = normalizePerspective(update, this.guides.perspective);
+    } catch (e) {
+      throw new PaintEditorError(e.message);
+    }
+    this.setGuides({ ...this.guides, perspective });
+    return perspective;
+  }
+  /** An image from a PNG (base64 or data URL) or from RGBA pixels, stored as a PNG data URL. */
+  importImage(input, what) {
+    let pixels;
+    if (input.pixels) {
+      const { width, height, data } = input.pixels;
+      if (!(width > 0 && height > 0 && Number.isInteger(width) && Number.isInteger(height)) || data.length !== width * height * 4) {
+        throw new PaintEditorError(`${what}: pixels must be width \xD7 height \xD7 4 bytes of RGBA.`);
+      }
+      pixels = { width, height, data: new Uint8ClampedArray(data) };
+    } else if (typeof input.png === "string" && input.png.trim()) {
+      pixels = this.decodeImage(input.png.trim().startsWith("data:") ? input.png.trim() : `data:image/png;base64,${input.png.trim()}`, what);
+    } else throw new PaintEditorError(`${what}: pass png (a PNG as base64 or a data URL) or pixels.`);
+    if (pixels.width > MAX_IMAGE_SIDE || pixels.height > MAX_IMAGE_SIDE) throw new PaintEditorError(`${what} is ${pixels.width}\xD7${pixels.height}; the limit is ${MAX_IMAGE_SIDE} px per side.`);
+    const src = pngDataUrl(pixels.width, pixels.height, pixels.data);
+    this.imagePixels.set(src, pixels);
+    return { src, pixels };
+  }
+  decodeImage(src, what = "Image") {
+    const cached = this.imagePixels.get(src);
+    if (cached) return cached;
+    const parsed = parseDataUrl(src);
+    if (!parsed) throw new PaintEditorError(`${what} is not a data URL or base64 PNG.`);
+    try {
+      const png = decodePng(parsed.bytes);
+      const px = { width: png.width, height: png.height, data: png.data };
+      this.imagePixels.set(src, px);
+      return px;
+    } catch (e) {
+      throw new PaintEditorError(`${what} could not be decoded as a PNG (${e.message}); decode other formats in the browser and pass pixels.`);
+    }
+  }
+  /**
+   * Puts an image under the paint to trace over: view only, never in exports. Placed to fit the
+   * canvas unless `rect` is given; `sampleColors` makes strokes take their colour from it.
+   */
+  setTracingImage(options) {
+    const { src, pixels } = this.importImage(options, "The tracing image");
+    const { width, height } = this.doc.canvas;
+    const k = Math.min(width / pixels.width, height / pixels.height);
+    const fit = { x: (width - pixels.width * k) / 2, y: (height - pixels.height * k) / 2, width: pixels.width * k, height: pixels.height * k };
+    const tracing = { src, width: pixels.width, height: pixels.height, rect: fit, opacity: 0.35, visible: true, sampleColors: false };
+    return this.updateTracing({ ...options, rect: options.rect ?? fit }, tracing);
+  }
+  /** Changes the tracing image's opacity, visibility, placement or colour sampling. */
+  updateTracing(update, base = this.guides.tracing) {
+    if (!base) throw new PaintEditorError("There is no tracing image; set one with set_tracing_image first.");
+    if (update.opacity !== void 0 && !(update.opacity >= 0 && update.opacity <= 1)) throw new PaintEditorError(`opacity ${update.opacity} is out of range; use 0..1.`);
+    if (update.rect && !(update.rect.width > 0 && update.rect.height > 0)) throw new PaintEditorError("rect needs a width and height above 0.");
+    const tracing = {
+      ...base,
+      ...update.opacity !== void 0 ? { opacity: update.opacity } : {},
+      ...update.visible !== void 0 ? { visible: update.visible } : {},
+      ...update.sampleColors !== void 0 ? { sampleColors: update.sampleColors } : {},
+      ...update.rect ? { rect: { ...update.rect } } : {}
+    };
+    if (tracing.src !== base.src || update.rect) this.tracingVersion++;
+    if (base !== this.guides.tracing) this.tracingVersion++;
+    this.setGuides({ ...this.guides, tracing });
+    return tracing;
+  }
+  clearTracingImage() {
+    this.tracingVersion++;
+    this.setGuides({ ...this.guides, tracing: null });
+  }
+  /** The tracing image's colour at a document pixel, or `null` outside it or where it is clear. */
+  sampleTracingColor(x, y) {
+    const t = this.guides.tracing;
+    if (!t) return null;
+    const src = this.decodeImage(t.src);
+    const u = Math.floor((x - t.rect.x) / t.rect.width * src.width);
+    const v = Math.floor((y - t.rect.y) / t.rect.height * src.height);
+    if (u < 0 || v < 0 || u >= src.width || v >= src.height) return null;
+    const i = (v * src.width + u) * 4;
+    if (src.data[i + 3] === 0) return null;
+    return rgbToHex(src.data[i], src.data[i + 1], src.data[i + 2]);
+  }
+  /** Adds a floating reference image to look at and pick colours from. */
+  addReferenceImage(options) {
+    const { src, pixels } = this.importImage(options, "The reference image");
+    const ref = {
+      id: `ref${this.nextReferenceId++}`,
+      name: options.name?.trim() || `Reference ${this.guides.references.length + 1}`,
+      src,
+      width: pixels.width,
+      height: pixels.height,
+      x: options.x ?? 16 + this.guides.references.length * 24,
+      y: options.y ?? 16 + this.guides.references.length * 24,
+      displayWidth: options.displayWidth ?? Math.min(240, pixels.width),
+      visible: true
+    };
+    this.setGuides({ ...this.guides, references: [...this.guides.references, ref] });
+    return ref;
+  }
+  requireReference(id) {
+    const r = this.guides.references.find((x) => x.id === id);
+    if (!r) throw new PaintEditorError(`Unknown reference image "${id}". Call list_reference_images for the ids.`);
+    return r;
+  }
+  /** Moves, resizes, renames, shows or hides a reference image. */
+  updateReferenceImage(id, update) {
+    const r = this.requireReference(id);
+    if (update.displayWidth !== void 0 && !(update.displayWidth >= 16 && update.displayWidth <= 4096)) throw new PaintEditorError(`displayWidth ${update.displayWidth} is out of range; use 16..4096.`);
+    const next = { ...r, ...Object.fromEntries(Object.entries(update).filter(([, v]) => v !== void 0)) };
+    this.setGuides({ ...this.guides, references: this.guides.references.map((x) => x.id === id ? next : x) });
+    return next;
+  }
+  removeReferenceImage(id) {
+    this.requireReference(id);
+    this.setGuides({ ...this.guides, references: this.guides.references.filter((x) => x.id !== id) });
+  }
+  /** A reference image's pixels (decoded once). */
+  referencePixels(id) {
+    return this.decodeImage(this.requireReference(id).src);
+  }
+  /** The colour of a reference image at its pixel (x, y). */
+  pickReferenceColor(id, x, y) {
+    const r = this.requireReference(id);
+    const px = this.decodeImage(r.src);
+    const u = Math.floor(x);
+    const v = Math.floor(y);
+    if (!(u >= 0 && v >= 0 && u < px.width && v < px.height)) throw new PaintEditorError(`(${x}, ${y}) is outside reference "${r.name}" (${px.width}\xD7${px.height}); use its own pixel coordinates.`);
+    const i = (v * px.width + u) * 4;
+    return rgbToHex(px.data[i], px.data[i + 1], px.data[i + 2]);
+  }
+  readGuides(raw, state, problems) {
+    const base = defaultGuides(state.canvas);
+    this.guides = base;
+    this.tracingVersion++;
+    if (!raw || typeof raw !== "object") return;
+    const r = raw;
+    const guides = { ...base };
+    guides.symmetry = normalizeSymmetry(r.symmetry ?? {}, base.symmetry);
+    try {
+      guides.perspective = normalizePerspective(r.perspective ?? {}, base.perspective);
+    } catch (e) {
+      problems.push(`Perspective guide: ${e.message}`);
+    }
+    const t = r.tracing;
+    if (t && typeof t.src === "string") {
+      try {
+        const px = this.decodeImage(t.src, "The tracing image");
+        guides.tracing = {
+          src: t.src,
+          width: px.width,
+          height: px.height,
+          rect: t.rect && t.rect.width > 0 && t.rect.height > 0 ? { ...t.rect } : { x: 0, y: 0, width: state.canvas.width, height: state.canvas.height },
+          opacity: typeof t.opacity === "number" ? Math.min(1, Math.max(0, t.opacity)) : 0.35,
+          visible: t.visible !== false,
+          sampleColors: t.sampleColors === true
+        };
+      } catch (e) {
+        problems.push(e.message);
+      }
+    }
+    if (Array.isArray(r.references)) {
+      for (const ref of r.references) {
+        if (!ref || typeof ref.src !== "string" || typeof ref.id !== "string") continue;
+        try {
+          const px = this.decodeImage(ref.src, `Reference "${ref.name}"`);
+          guides.references.push({ id: ref.id, name: String(ref.name ?? ref.id), src: ref.src, width: px.width, height: px.height, x: Number(ref.x) || 0, y: Number(ref.y) || 0, displayWidth: Number(ref.displayWidth) || 240, visible: ref.visible !== false });
+          const n = Number(/^ref(\d+)$/.exec(ref.id)?.[1] ?? 0);
+          if (n >= this.nextReferenceId) this.nextReferenceId = n + 1;
+        } catch (e) {
+          problems.push(e.message);
+        }
+      }
+    }
+    this.guides = guides;
+  }
+  // --- Swatches and harmonies ------------------------------------------------------
+  /** Colour harmonies around a colour (default the paint colour) on the painter's RYB wheel or the RGB wheel. */
+  harmony(kind, options = {}) {
+    try {
+      return colorHarmony(options.color === void 0 ? this.color : parseColor(options.color), kind, options);
+    } catch (e) {
+      throw new PaintEditorError(e.message);
+    }
+  }
+  addSwatch(color, name) {
+    const c = parseColor(color);
+    this.swatches = [...this.swatches, name?.trim() ? { color: c, name: name.trim() } : { color: c }];
+    this.emit([]);
+    return this.swatches;
+  }
+  removeSwatch(index) {
+    if (!Number.isInteger(index) || index < 0 || index >= this.swatches.length) throw new PaintEditorError(`index ${index} is out of range; there are ${this.swatches.length} swatches (0-based).`);
+    this.swatches = this.swatches.filter((_, i) => i !== index);
+    this.emit([]);
+    return this.swatches;
+  }
+  setSwatches(swatches) {
+    this.swatches = swatches.map((x) => x.name ? { color: parseColor(x.color), name: x.name } : { color: parseColor(x.color) });
+    this.emit([]);
+    return this.swatches;
+  }
+  // --- Mixing pad ------------------------------------------------------------------
+  get mixingPad() {
+    return this.pad;
+  }
+  /** Paints (`paint`) or smears with the palette knife (`knife`) on the mixing pad, in pad pixels. */
+  mixingPadStroke(points, options = {}) {
+    const color = options.color === void 0 ? this.color : parseColor(options.color);
+    if (options.size !== void 0 && !(options.size >= 1 && options.size <= 200)) throw new PaintEditorError(`size ${options.size} is out of range; use 1..200 px.`);
+    try {
+      const r = this.pad.stroke(points, { tool: options.tool ?? "paint", color, size: options.size });
+      this.emit([]);
+      return r;
+    } catch (e) {
+      throw new PaintEditorError(e.message);
+    }
+  }
+  /** Picks the mixed colour on the pad (averaged over `radius` px); with `setColor` it becomes the paint colour. */
+  mixingPadPick(x, y, options = {}) {
+    let c;
+    try {
+      c = this.pad.pick(x, y, options.radius);
+    } catch (e) {
+      throw new PaintEditorError(e.message);
+    }
+    if (c && options.setColor) this.setColor(c);
+    return c;
+  }
+  clearMixingPad() {
+    this.pad.clear();
+    this.emit([]);
+  }
   /** A layer's tile surface (live while stroking), for thumbnails. */
   layerSurface(id) {
     const l = findLayer(this.currentLayers(), id)?.layer;
     return isPixelLayer(l) ? l.surface : null;
   }
 };
+var MAX_IMAGE_SIDE = 8192;
+function resampleInto(src, rect, width, height) {
+  const out = new Uint8ClampedArray(width * height * 4);
+  const x0 = Math.max(0, Math.floor(rect.x));
+  const y0 = Math.max(0, Math.floor(rect.y));
+  const x1 = Math.min(width, Math.ceil(rect.x + rect.width));
+  const y1 = Math.min(height, Math.ceil(rect.y + rect.height));
+  const sx = src.width / rect.width;
+  const sy = src.height / rect.height;
+  const d = src.data;
+  for (let y = y0; y < y1; y++) {
+    const v = Math.min(src.height - 1, Math.max(0, (y + 0.5 - rect.y) * sy - 0.5));
+    const j0 = Math.floor(v);
+    const j1 = Math.min(src.height - 1, j0 + 1);
+    const fy = v - j0;
+    for (let x = x0; x < x1; x++) {
+      const u = (x + 0.5 - rect.x) * sx - 0.5;
+      if (u < -0.5 || u > src.width - 0.5 || (y + 0.5 - rect.y) * sy < 0 || (y + 0.5 - rect.y) * sy > src.height) continue;
+      const uc = Math.min(src.width - 1, Math.max(0, u));
+      const i0 = Math.floor(uc);
+      const i1 = Math.min(src.width - 1, i0 + 1);
+      const fx = uc - i0;
+      const o = (y * width + x) * 4;
+      for (let c = 0; c < 4; c++) {
+        const a = d[(j0 * src.width + i0) * 4 + c] + (d[(j0 * src.width + i1) * 4 + c] - d[(j0 * src.width + i0) * 4 + c]) * fx;
+        const b = d[(j1 * src.width + i0) * 4 + c] + (d[(j1 * src.width + i1) * 4 + c] - d[(j1 * src.width + i0) * 4 + c]) * fx;
+        out[o + c] = a + (b - a) * fy;
+      }
+    }
+  }
+  return { width, height, data: out };
+}
 
-// src/paint-editor/tools.ts
+// src/paint-editor/guide-tools.ts
 var READ = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 var WRITE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
 var SET = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 var DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false };
 var EMPTY = { type: "object", properties: {}, additionalProperties: false };
-var COLOR = { type: "string", pattern: "^#[0-9a-fA-F]{6}$", description: 'Colour #rrggbb, e.g. "#2a4b8d".' };
+var COLOR = { type: "string", pattern: "^#[0-9a-fA-F]{6}$", description: "Colour #rrggbb." };
+var POINT = {
+  type: "object",
+  properties: { x: { type: "number", description: "x in document pixels." }, y: { type: "number", description: "y in document pixels." } },
+  required: ["x", "y"],
+  additionalProperties: false
+};
+var RECT = {
+  type: "object",
+  description: "Placement in document pixels.",
+  properties: {
+    x: { type: "number", description: "Left edge." },
+    y: { type: "number", description: "Top edge." },
+    width: { type: "number", exclusiveMinimum: 0, description: "Width." },
+    height: { type: "number", exclusiveMinimum: 0, description: "Height." }
+  },
+  required: ["x", "y", "width", "height"],
+  additionalProperties: false
+};
+var PNG = { type: "string", minLength: 1, description: "The image as a PNG, base64 or a data:image/png URL." };
+var tracingInfo = (t) => t ? { width: t.width, height: t.height, rect: t.rect, opacity: t.opacity, visible: t.visible, sampleColors: t.sampleColors } : null;
+var refInfo = ({ src: _s, ...r }) => r;
+function createPaintGuideTools(c) {
+  const guides = () => c.getState().guides;
+  return [
+    {
+      name: "get_guides",
+      title: "Get the painting guides",
+      description: "Reads the painting guides: symmetry (mode, centre, rotation, segments, mirror, and how many copies each stroke paints), the perspective guide (vanishing points, snap), the tracing image (size, placement, opacity, visibility, colour sampling) and the reference images.",
+      inputSchema: EMPTY,
+      annotations: { title: "Get the painting guides", ...READ },
+      handler: () => {
+        const g = guides();
+        return { symmetry: { ...g.symmetry, copies: symmetryCopies(g.symmetry).length }, perspective: g.perspective, tracing: tracingInfo(g.tracing), references: g.references.map(refInfo) };
+      }
+    },
+    {
+      name: "set_symmetry",
+      title: "Set mirror or kaleidoscope painting",
+      description: "Turns symmetry on or off. Every stroke after it also paints its copies, as one stroke and one undo step: vertical, horizontal or diagonal mirror (one copy), dual (four-way), or kaleidoscope with n segments (rotated copies, and with mirror the reflections between them). Editor state, saved with the document. Returns the guide and the number of copies.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          mode: { type: "string", enum: [...SYMMETRY_MODES], description: "off, vertical (mirror left / right), horizontal (top / bottom), dual, diagonal or kaleidoscope." },
+          center: { ...POINT, description: "Centre of the axes in document pixels (default the canvas centre)." },
+          rotation: { type: "number", minimum: -360, maximum: 360, description: "Turn the axes, degrees clockwise." },
+          segments: { type: "integer", minimum: 2, maximum: 32, description: "Kaleidoscope segments (default 6)." },
+          mirror: { type: "boolean", description: "Kaleidoscope: also reflect alternate segments (default true)." }
+        },
+        additionalProperties: false
+      },
+      annotations: { title: "Set mirror or kaleidoscope painting", ...SET },
+      handler: (a) => {
+        const s = c.setSymmetry(a);
+        return { ...s, copies: symmetryCopies(s).length };
+      }
+    },
+    {
+      name: "set_perspective_guide",
+      title: "Set the perspective guide",
+      description: "Sets one to three vanishing points (document pixels, may be off the canvas). With snap on, pen strokes snap to the line through their start towards a vanishing point (one-point also keeps horizontals and verticals, two-point verticals); for paint_stroke pass snapToPerspective. Editor state, saved with the document. Returns the guide.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          enabled: { type: "boolean", description: "Show and use the guide." },
+          points: { type: "array", minItems: 1, maxItems: 3, items: { ...POINT, description: "A vanishing point." }, description: "The vanishing points." },
+          snap: { type: "boolean", description: "Snap strokes to the guide lines (default true)." }
+        },
+        additionalProperties: false
+      },
+      annotations: { title: "Set the perspective guide", ...SET },
+      handler: (a) => c.setPerspective(a)
+    },
+    {
+      name: "set_tracing_image",
+      title: "Set a tracing image",
+      description: "Puts an image under the paint to trace over (view only: never exported), fitted to the canvas unless rect is given, at opacity (default 0.35). With sampleColors, strokes without a colour take the image colour where they start, so painting over it copies its colours. Replaces any tracing image. Returns its size and placement.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          png: PNG,
+          rect: RECT,
+          opacity: { type: "number", minimum: 0, maximum: 1, description: "Opacity 0..1 (default 0.35)." },
+          sampleColors: { type: "boolean", description: "Strokes take their colour from the image (default false)." }
+        },
+        required: ["png"],
+        additionalProperties: false
+      },
+      annotations: { title: "Set a tracing image", ...WRITE },
+      handler: (a) => tracingInfo(c.setTracingImage(a))
+    },
+    {
+      name: "update_tracing_image",
+      title: "Change the tracing image",
+      description: "Changes the tracing image opacity, visibility, placement or colour sampling. Returns it.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          opacity: { type: "number", minimum: 0, maximum: 1, description: "Opacity 0..1." },
+          visible: { type: "boolean", description: "Show or hide it." },
+          sampleColors: { type: "boolean", description: "Strokes take their colour from it." },
+          rect: RECT
+        },
+        additionalProperties: false
+      },
+      annotations: { title: "Change the tracing image", ...SET },
+      handler: (a) => tracingInfo(c.updateTracing(a))
+    },
+    {
+      name: "clear_tracing_image",
+      title: "Remove the tracing image",
+      description: "Removes the tracing image. Returns null.",
+      inputSchema: EMPTY,
+      annotations: { title: "Remove the tracing image", ...DESTRUCTIVE },
+      handler: () => {
+        c.clearTracingImage();
+        return { tracing: null };
+      }
+    },
+    {
+      name: "add_reference_image",
+      title: "Add a reference image",
+      description: "Adds a floating reference image (shown beside the canvas, never painted) to look at and pick colours from with pick_reference_color. Returns its id, size and placement.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          png: PNG,
+          name: { type: "string", minLength: 1, description: "Display name." },
+          x: { type: "number", description: "Panel left in viewport pixels." },
+          y: { type: "number", description: "Panel top in viewport pixels." },
+          displayWidth: { type: "number", minimum: 16, maximum: 4096, description: "Panel width in screen pixels (default up to 240)." }
+        },
+        required: ["png"],
+        additionalProperties: false
+      },
+      annotations: { title: "Add a reference image", ...WRITE },
+      handler: (a) => refInfo(c.addReferenceImage(a))
+    },
+    {
+      name: "list_reference_images",
+      title: "List reference images",
+      description: "Lists the reference images: id, name, size in pixels, panel placement and visibility.",
+      inputSchema: EMPTY,
+      annotations: { title: "List reference images", ...READ },
+      handler: () => ({ references: guides().references.map(refInfo) })
+    },
+    {
+      name: "update_reference_image",
+      title: "Change a reference image",
+      description: "Moves, resizes, renames, shows or hides a reference image panel. Returns it.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "Reference id from list_reference_images." },
+          name: { type: "string", minLength: 1, description: "Display name." },
+          x: { type: "number", description: "Panel left in viewport pixels." },
+          y: { type: "number", description: "Panel top in viewport pixels." },
+          displayWidth: { type: "number", minimum: 16, maximum: 4096, description: "Panel width in screen pixels." },
+          visible: { type: "boolean", description: "Show or hide it." }
+        },
+        required: ["id"],
+        additionalProperties: false
+      },
+      annotations: { title: "Change a reference image", ...SET },
+      handler: ({ id, ...u }) => refInfo(c.updateReferenceImage(id, u))
+    },
+    {
+      name: "remove_reference_image",
+      title: "Remove a reference image",
+      description: "Removes a reference image. Returns the removed id.",
+      inputSchema: { type: "object", properties: { id: { type: "string", description: "Reference id from list_reference_images." } }, required: ["id"], additionalProperties: false },
+      annotations: { title: "Remove a reference image", ...DESTRUCTIVE },
+      handler: ({ id }) => {
+        c.removeReferenceImage(id);
+        return { removed: id };
+      }
+    },
+    {
+      name: "pick_reference_color",
+      title: "Pick a colour from a reference",
+      description: "Reads the colour of a reference image at its own pixel (x, y). With setColor it becomes the paint colour. Returns #rrggbb.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "Reference id from list_reference_images." },
+          x: { type: "number", minimum: 0, description: "x in the image\u2019s pixels." },
+          y: { type: "number", minimum: 0, description: "y in the image\u2019s pixels." },
+          setColor: { type: "boolean", description: "Also make it the paint colour (default false)." }
+        },
+        required: ["id", "x", "y"],
+        additionalProperties: false
+      },
+      annotations: { title: "Pick a colour from a reference", ...SET },
+      handler: ({ id, x, y, setColor }) => {
+        const color = c.pickReferenceColor(id, x, y);
+        if (setColor) c.setColor(color);
+        return { color };
+      }
+    },
+    {
+      name: "color_harmony",
+      title: "Colour harmonies",
+      description: "Returns the colours of a harmony around a colour (default the paint colour): complementary, split-complementary, analogous, triadic, tetradic, square or monochromatic, on the painter\u2019s red-yellow-blue wheel (default: red\u2019s complement is green) or the RGB wheel. Changes nothing. Returns the colours with their wheel angles, the base first.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          kind: { type: "string", enum: [...HARMONY_KINDS], description: "The harmony." },
+          color: { ...COLOR, description: "Base colour #rrggbb (default the paint colour)." },
+          wheel: { type: "string", enum: ["ryb", "rgb"], description: "ryb (painter\u2019s wheel, default) or rgb." },
+          spread: { type: "number", minimum: 5, maximum: 90, description: "Analogous and split-complementary spread in degrees (default 30)." }
+        },
+        required: ["kind"],
+        additionalProperties: false
+      },
+      annotations: { title: "Colour harmonies", ...READ },
+      handler: ({ kind, color, wheel, spread }) => ({ kind, wheel: wheel ?? "ryb", colors: c.harmony(kind, { color, wheel, spread }) })
+    },
+    {
+      name: "list_swatches",
+      title: "List swatches",
+      description: "Lists the colour swatches (index, colour, name).",
+      inputSchema: EMPTY,
+      annotations: { title: "List swatches", ...READ },
+      handler: () => ({ swatches: c.getState().swatches.map((s, index) => ({ index, ...s })) })
+    },
+    {
+      name: "add_swatch",
+      title: "Add a swatch",
+      description: "Adds a colour to the swatches (saved with the document). Returns the swatches.",
+      inputSchema: {
+        type: "object",
+        properties: { color: COLOR, name: { type: "string", minLength: 1, description: "Optional name." } },
+        required: ["color"],
+        additionalProperties: false
+      },
+      annotations: { title: "Add a swatch", ...WRITE },
+      handler: ({ color, name }) => ({ swatches: c.addSwatch(color, name).map((s, index) => ({ index, ...s })) })
+    },
+    {
+      name: "remove_swatch",
+      title: "Remove a swatch",
+      description: "Removes a swatch by index (from list_swatches). Returns the swatches.",
+      inputSchema: { type: "object", properties: { index: { type: "integer", minimum: 0, description: "0-based index." } }, required: ["index"], additionalProperties: false },
+      annotations: { title: "Remove a swatch", ...DESTRUCTIVE },
+      handler: ({ index }) => ({ swatches: c.removeSwatch(index).map((s, i) => ({ index: i, ...s })) })
+    },
+    {
+      name: "mixing_pad_stroke",
+      title: "Paint on the mixing pad",
+      description: "Paints on the mixing pad (a 360 \xD7 220 scratch canvas, not the painting): tool paint lays down a colour with a pigment Mixer Brush; tool knife smears what is there like a palette knife, mixing it as paint. Points are pad pixels. Not an undo step. Returns the changed bounds; then pick_mixing_pad_color.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          points: {
+            type: "array",
+            minItems: 1,
+            maxItems: 2e3,
+            description: "The path in pad pixels (0..360, 0..220).",
+            items: {
+              type: "object",
+              properties: { x: { type: "number", description: "Pad x." }, y: { type: "number", description: "Pad y." }, pressure: { type: "number", minimum: 0, maximum: 1, description: "Pressure (default 1)." } },
+              required: ["x", "y"],
+              additionalProperties: false
+            }
+          },
+          tool: { type: "string", enum: ["paint", "knife"], description: "paint (default) or knife." },
+          color: { ...COLOR, description: "Paint colour (default the paint colour; ignored by the knife)." },
+          size: { type: "number", minimum: 1, maximum: 200, description: "Tool size in pad pixels (default 28 paint, 34 knife)." }
+        },
+        required: ["points"],
+        additionalProperties: false
+      },
+      annotations: { title: "Paint on the mixing pad", ...WRITE },
+      handler: ({ points, tool, color, size }) => c.mixingPadStroke(points, { tool, color, size })
+    },
+    {
+      name: "pick_mixing_pad_color",
+      title: "Pick from the mixing pad",
+      description: "Reads the mixed colour on the pad at (x, y), averaged over radius pixels (default 3); with setColor it becomes the paint colour. Returns #rrggbb, or null where the pad is bare.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          x: { type: "number", minimum: 0, maximum: 360, description: "Pad x." },
+          y: { type: "number", minimum: 0, maximum: 220, description: "Pad y." },
+          radius: { type: "integer", minimum: 0, maximum: 20, description: "Averaging radius in pixels (default 3)." },
+          setColor: { type: "boolean", description: "Also make it the paint colour (default false)." }
+        },
+        required: ["x", "y"],
+        additionalProperties: false
+      },
+      annotations: { title: "Pick from the mixing pad", ...SET },
+      handler: ({ x, y, radius, setColor }) => ({ color: c.mixingPadPick(x, y, { radius, setColor }) })
+    },
+    {
+      name: "clear_mixing_pad",
+      title: "Clear the mixing pad",
+      description: "Wipes the mixing pad clean.",
+      inputSchema: EMPTY,
+      annotations: { title: "Clear the mixing pad", ...DESTRUCTIVE },
+      handler: () => {
+        c.clearMixingPad();
+        return { cleared: true };
+      }
+    },
+    {
+      name: "render_mixing_pad",
+      title: "Render the mixing pad",
+      description: "Renders the mixing pad as a PNG (360 \xD7 220, over white). Changes nothing.",
+      inputSchema: EMPTY,
+      annotations: { title: "Render the mixing pad", ...READ },
+      handler: () => {
+        const pad = c.mixingPad;
+        return {
+          content: [
+            { type: "image", data: bytesToBase64(encodePng(pad.width, pad.height, pad.pixels())), mimeType: "image/png" },
+            { type: "text", text: `Mixing pad ${pad.width}\xD7${pad.height}` }
+          ]
+        };
+      }
+    }
+  ];
+}
+
+// src/paint-editor/tools.ts
+var READ2 = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+var WRITE2 = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
+var SET2 = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+var DESTRUCTIVE2 = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false };
+var EMPTY2 = { type: "object", properties: {}, additionalProperties: false };
+var COLOR2 = { type: "string", pattern: "^#[0-9a-fA-F]{6}$", description: 'Colour #rrggbb, e.g. "#2a4b8d".' };
 var LAYER_ID = { type: "string", description: "Layer id from list_layers (default the active layer)." };
 var TIP = {
   type: "object",
@@ -2589,8 +3647,8 @@ function createPaintEditorToolProvider(controller, options = {}) {
     name: "get_canvas_info",
     title: "Get the canvas",
     description: "Reads the canvas: size in pixels and dpi, the paper (preset, colour, grain depth), the active layer, the active brush id, the paint colour, the view (zoom, rotation, mirror), the hand, how many strokes are recorded, the undo / redo labels, and the blend modes. Call it first.",
-    inputSchema: EMPTY,
-    annotations: { title: "Get the canvas", ...READ },
+    inputSchema: EMPTY2,
+    annotations: { title: "Get the canvas", ...READ2 },
     handler: () => {
       const s = c.getState();
       const d = s.document;
@@ -2627,7 +3685,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       },
       additionalProperties: false
     },
-    annotations: { title: "Start a new canvas", ...DESTRUCTIVE },
+    annotations: { title: "Start a new canvas", ...DESTRUCTIVE2 },
     handler: (a) => {
       const d = c.newCanvas({ width: a.width, height: a.height, dpi: a.dpi, paper: a.paper });
       return { width: d.canvas.width, height: d.canvas.height, dpi: d.canvas.dpi, paper: d.paper.preset, layerId: d.activeLayerId };
@@ -2646,15 +3704,15 @@ function createPaintEditorToolProvider(controller, options = {}) {
       },
       additionalProperties: false
     },
-    annotations: { title: "Resize the canvas", ...SET },
+    annotations: { title: "Resize the canvas", ...SET2 },
     handler: (a) => c.setCanvas({ width: a.width, height: a.height, dpi: a.dpi })
   });
   add({
     name: "list_papers",
     title: "List papers",
     description: "Lists the built-in paper library (generated grain, no textures): id, name, family, grain pattern, colour, grain depth and the wet-media properties (absorption, permeability, roughness). Use an id with set_paper or new_canvas.",
-    inputSchema: EMPTY,
-    annotations: { title: "List papers", ...READ },
+    inputSchema: EMPTY2,
+    annotations: { title: "List papers", ...READ2 },
     handler: () => ({
       papers: PAPER_LIBRARY.map((p) => ({ id: p.preset, name: p.name, family: p.family, pattern: p.pattern, color: p.color, depth: p.depth, absorption: p.absorption, permeability: p.permeability, roughness: p.roughness })),
       families: [...PAPER_FAMILIES],
@@ -2665,8 +3723,8 @@ function createPaintEditorToolProvider(controller, options = {}) {
     name: "get_paper",
     title: "Get the paper",
     description: "Reads every setting of the current paper (preset, pattern, seed, colour, scale, tiling, depth, shading, dry and wet tuning, absorption, permeability, roughness).",
-    inputSchema: EMPTY,
-    annotations: { title: "Get the paper", ...READ },
+    inputSchema: EMPTY2,
+    annotations: { title: "Get the paper", ...READ2 },
     handler: () => JSON.parse(JSON.stringify(c.document.paper))
   });
   const tuning2 = {
@@ -2685,7 +3743,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       type: "object",
       properties: {
         preset: { type: "string", description: "Paper id from list_papers (its settings, then the other fields here on top)." },
-        color: { ...COLOR, description: "Paper colour #rrggbb." },
+        color: { ...COLOR2, description: "Paper colour #rrggbb." },
         depth: { type: "number", minimum: 0, maximum: 1, description: "Grain depth 0..1 (0: brushes ignore the grain)." },
         scale: { type: "number", minimum: 0.25, maximum: 8, description: "Grain scale: 1 natural, 2 twice as coarse." },
         seed: { type: "integer", minimum: 0, description: "Grain seed: another sheet of the same paper." },
@@ -2701,15 +3759,15 @@ function createPaintEditorToolProvider(controller, options = {}) {
       },
       additionalProperties: false
     },
-    annotations: { title: "Set the paper", ...SET },
+    annotations: { title: "Set the paper", ...SET2 },
     handler: (a) => c.setPaper(a)
   });
   add({
     name: "list_layers",
     title: "List layers",
     description: "Lists the layers top first: id, name, type (pixel or group), visibility, opacity, blend, clipping, locks, whether it is active, the painted bounds in document pixels (null when empty), parent and depth.",
-    inputSchema: EMPTY,
-    annotations: { title: "List layers", ...READ },
+    inputSchema: EMPTY2,
+    annotations: { title: "List layers", ...READ2 },
     handler: () => ({ layers: c.listLayers(), activeLayerId: c.document.activeLayerId })
   });
   add({
@@ -2726,7 +3784,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       },
       additionalProperties: false
     },
-    annotations: { title: "Add a layer", ...WRITE },
+    annotations: { title: "Add a layer", ...WRITE2 },
     handler: (a) => c.addLayer({ name: a.name, type: a.type, aboveId: a.aboveId, parentId: a.parentId })
   });
   add({
@@ -2757,7 +3815,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       required: ["layerId"],
       additionalProperties: false
     },
-    annotations: { title: "Change a layer", ...SET },
+    annotations: { title: "Change a layer", ...SET2 },
     handler: ({ layerId, ...u }) => c.updateLayer(layerId, u)
   });
   add({
@@ -2765,7 +3823,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     title: "Choose the active layer",
     description: "Makes a layer active: strokes, fills and clears without a layerId go to it. Editor state, not an undo step. Returns the layer.",
     inputSchema: { type: "object", properties: { layerId: { type: "string", description: "Layer id from list_layers." } }, required: ["layerId"], additionalProperties: false },
-    annotations: { title: "Choose the active layer", ...SET },
+    annotations: { title: "Choose the active layer", ...SET2 },
     handler: ({ layerId }) => {
       c.setActiveLayer(layerId);
       return c.describeLayer(c.getLayer(layerId));
@@ -2776,7 +3834,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     title: "Remove a layer",
     description: "Removes a layer (a group with its children). One undo step. Returns the removed id and the new active layer.",
     inputSchema: { type: "object", properties: { layerId: { type: "string", description: "Layer id from list_layers." } }, required: ["layerId"], additionalProperties: false },
-    annotations: { title: "Remove a layer", ...DESTRUCTIVE },
+    annotations: { title: "Remove a layer", ...DESTRUCTIVE2 },
     handler: ({ layerId }) => c.removeLayer(layerId)
   });
   add({
@@ -2784,7 +3842,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     title: "Duplicate a layer",
     description: "Copies a layer (a group with its children) directly above it; the copy becomes active. One undo step. Returns the copy.",
     inputSchema: { type: "object", properties: { layerId: { type: "string", description: "Layer id from list_layers." } }, required: ["layerId"], additionalProperties: false },
-    annotations: { title: "Duplicate a layer", ...WRITE },
+    annotations: { title: "Duplicate a layer", ...WRITE2 },
     handler: ({ layerId }) => c.duplicateLayer(layerId)
   });
   add({
@@ -2801,7 +3859,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       required: ["layerId", "index"],
       additionalProperties: false
     },
-    annotations: { title: "Reorder a layer", ...WRITE },
+    annotations: { title: "Reorder a layer", ...WRITE2 },
     handler: ({ layerId, index, parentId }) => c.moveLayer(layerId, index, parentId)
   });
   add({
@@ -2809,7 +3867,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     title: "Merge a layer down",
     description: "Merges a pixel layer into the pixel layer directly below it, which keeps its name, opacity and blend. One undo step. Returns the merged layer.",
     inputSchema: { type: "object", properties: { layerId: { type: "string", description: "The upper layer, from list_layers." } }, required: ["layerId"], additionalProperties: false },
-    annotations: { title: "Merge a layer down", ...DESTRUCTIVE },
+    annotations: { title: "Merge a layer down", ...DESTRUCTIVE2 },
     handler: ({ layerId }) => c.mergeDown(layerId)
   });
   add({
@@ -2820,7 +3878,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       type: "object",
       properties: {
         layerId: LAYER_ID,
-        color: { ...COLOR, description: "Fill colour #rrggbb (default the paint colour)." },
+        color: { ...COLOR2, description: "Fill colour #rrggbb (default the paint colour)." },
         opacity: { type: "number", minimum: 0, maximum: 1, description: "Opacity 0..1 (default 1)." },
         grain: { type: "number", minimum: 0, maximum: 1, description: "Paper grain response 0..1 (default 0: flat)." },
         pressure: { type: "number", minimum: 0, maximum: 1, description: "With grain: how far into the valleys, 0..1 (default 0.5)." },
@@ -2828,7 +3886,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       },
       additionalProperties: false
     },
-    annotations: { title: "Fill a layer", ...WRITE },
+    annotations: { title: "Fill a layer", ...WRITE2 },
     handler: (a) => c.fillLayer(a)
   });
   add({
@@ -2836,15 +3894,15 @@ function createPaintEditorToolProvider(controller, options = {}) {
     title: "Clear a layer",
     description: "Removes every pixel of a pixel layer. One undo step. Returns the layer id and the bounds that were cleared (null if it was empty).",
     inputSchema: { type: "object", properties: { layerId: LAYER_ID }, additionalProperties: false },
-    annotations: { title: "Clear a layer", ...DESTRUCTIVE },
+    annotations: { title: "Clear a layer", ...DESTRUCTIVE2 },
     handler: ({ layerId }) => c.clearLayer(layerId)
   });
   add({
     name: "list_brushes",
     title: "List brushes",
     description: "Lists the brush library: built-in dry media (pencils, pastels, charcoal, airbrush, marker, ink, erasers, blender, smudge, Mixer Brush) and saved user brushes, with id, name, category, engine, size, grain response and rotation mode, plus the active brush id.",
-    inputSchema: EMPTY,
-    annotations: { title: "List brushes", ...READ },
+    inputSchema: EMPTY2,
+    annotations: { title: "List brushes", ...READ2 },
     handler: () => {
       const s = c.getState();
       return { activeBrushId: s.brush.id, activeEdited: !s.brush.builtin && Boolean(c.getBrush(s.brush.id)?.builtin), brushes: s.brushes.map(brushSummary) };
@@ -2855,7 +3913,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     title: "Get a brush",
     description: "Reads every setting of a brush (tip, grain, pressure smoothing, rotation, dynamics, mixer). Without id, the active brush as edited.",
     inputSchema: { type: "object", properties: { id: { type: "string", description: "Brush id from list_brushes (default the active brush)." } }, additionalProperties: false },
-    annotations: { title: "Get a brush", ...READ },
+    annotations: { title: "Get a brush", ...READ2 },
     handler: ({ id }) => {
       if (id === void 0) return brushToJSON(c.getState().brush);
       const b = c.getBrush(id);
@@ -2868,7 +3926,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     title: "Set the brush",
     description: "Chooses the active brush (id) and / or changes its settings; strokes without a brush use it. Editor state, not an undo step. Changes stay on the active brush until save_brush stores them. Returns the active brush.",
     inputSchema: { type: "object", properties: { id: { type: "string", description: "Brush id from list_brushes to start from." }, ...BRUSH_FIELDS }, additionalProperties: false },
-    annotations: { title: "Set the brush", ...SET },
+    annotations: { title: "Set the brush", ...SET2 },
     handler: (a) => brushToJSON(c.setBrush(a))
   });
   add({
@@ -2884,7 +3942,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       required: ["id"],
       additionalProperties: false
     },
-    annotations: { title: "Save a brush", ...SET },
+    annotations: { title: "Save a brush", ...SET2 },
     handler: ({ id, name }) => brushToJSON(c.saveBrush({ id, name }))
   });
   add({
@@ -2892,7 +3950,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     title: "Remove a saved brush",
     description: "Removes a user brush from the library (built-in brushes cannot be removed). Library state, not an undo step. Returns the removed id.",
     inputSchema: { type: "object", properties: { id: { type: "string", description: "User brush id from list_brushes." } }, required: ["id"], additionalProperties: false },
-    annotations: { title: "Remove a saved brush", ...DESTRUCTIVE },
+    annotations: { title: "Remove a saved brush", ...DESTRUCTIVE2 },
     handler: ({ id }) => {
       c.removeBrush(id);
       return { removed: id };
@@ -2907,7 +3965,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       properties: { ids: { type: "array", items: { type: "string", description: "Brush id." }, description: "Brush ids from list_brushes (default every user brush)." } },
       additionalProperties: false
     },
-    annotations: { title: "Export brushes", ...READ },
+    annotations: { title: "Export brushes", ...READ2 },
     handler: ({ ids }) => c.exportBrushes(ids)
   });
   add({
@@ -2923,7 +3981,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       required: ["library"],
       additionalProperties: false
     },
-    annotations: { title: "Import brushes", ...WRITE },
+    annotations: { title: "Import brushes", ...WRITE2 },
     handler: ({ library, replace }) => c.importBrushes(library, { replace })
   });
   add({
@@ -2936,11 +3994,11 @@ function createPaintEditorToolProvider(controller, options = {}) {
         id: { type: "string", description: "Brush id from list_brushes (default the active brush)." },
         width: { type: "integer", minimum: 16, maximum: 512, description: "Width in pixels (default 160)." },
         height: { type: "integer", minimum: 16, maximum: 512, description: "Height in pixels (default 48)." },
-        color: { ...COLOR, description: "Stroke colour (default the paint colour)." }
+        color: { ...COLOR2, description: "Stroke colour (default the paint colour)." }
       },
       additionalProperties: false
     },
-    annotations: { title: "Render a brush thumbnail", ...READ },
+    annotations: { title: "Render a brush thumbnail", ...READ2 },
     handler: ({ id, width, height, color }) => {
       const t = c.brushThumbnail(id ?? c.getState().brush.id, { width, height, color });
       return {
@@ -2957,10 +4015,10 @@ function createPaintEditorToolProvider(controller, options = {}) {
     description: "Sets the paint colour (and optionally the second colour) that strokes and fills use by default. Editor state, not an undo step. Returns both colours.",
     inputSchema: {
       type: "object",
-      properties: { color: { ...COLOR, description: "Paint colour #rrggbb." }, secondaryColor: { ...COLOR, description: "Second colour #rrggbb." } },
+      properties: { color: { ...COLOR2, description: "Paint colour #rrggbb." }, secondaryColor: { ...COLOR2, description: "Second colour #rrggbb." } },
       additionalProperties: false
     },
-    annotations: { title: "Set the paint colour", ...SET },
+    annotations: { title: "Set the paint colour", ...SET2 },
     handler: ({ color, secondaryColor }) => {
       if (color !== void 0) c.setColor(color);
       if (secondaryColor !== void 0) c.setSecondaryColor(secondaryColor);
@@ -2982,23 +4040,23 @@ function createPaintEditorToolProvider(controller, options = {}) {
       required: ["x", "y"],
       additionalProperties: false
     },
-    annotations: { title: "Pick a colour", ...READ },
+    annotations: { title: "Pick a colour", ...READ2 },
     handler: ({ x, y, layerId }) => c.pickColor(x, y, { layerId })
   });
   add({
     name: "get_mixer_brush",
     title: "Get the Mixer Brush load",
     description: "Reads what the Mixer Brush carries between strokes: reservoir #rrggbb or null, amount 0..1 left, pickup #rrggbb or null. Call before painting with mixer-brush when its loadEachStroke is false.",
-    inputSchema: EMPTY,
-    annotations: { title: "Get the Mixer Brush load", ...READ },
+    inputSchema: EMPTY2,
+    annotations: { title: "Get the Mixer Brush load", ...READ2 },
     handler: () => loadResult(c.getState().mixerLoad)
   });
   add({
     name: "load_mixer_brush",
     title: "Load the Mixer Brush",
     description: "Fills the Mixer Brush reservoir with a colour (amount 1), keeping what it picked up. Editor state, not an undo step. Returns the load.",
-    inputSchema: { type: "object", properties: { color: { ...COLOR, description: "Colour #rrggbb (default the paint colour)." } }, additionalProperties: false },
-    annotations: { title: "Load the Mixer Brush", ...SET },
+    inputSchema: { type: "object", properties: { color: { ...COLOR2, description: "Colour #rrggbb (default the paint colour)." } }, additionalProperties: false },
+    annotations: { title: "Load the Mixer Brush", ...SET2 },
     handler: ({ color }) => loadResult(c.loadMixerBrush(color))
   });
   add({
@@ -3006,13 +4064,13 @@ function createPaintEditorToolProvider(controller, options = {}) {
     title: "Clean the Mixer Brush",
     description: "Empties the Mixer Brush pickup well (and with emptyReservoir its paint too). Editor state, not an undo step. Returns the load.",
     inputSchema: { type: "object", properties: { emptyReservoir: { type: "boolean", description: "Also drop the loaded paint (default false)." } }, additionalProperties: false },
-    annotations: { title: "Clean the Mixer Brush", ...SET },
+    annotations: { title: "Clean the Mixer Brush", ...SET2 },
     handler: ({ emptyReservoir }) => loadResult(c.cleanMixerBrush(emptyReservoir === true))
   });
   add({
     name: "paint_stroke",
     title: "Paint a brush stroke",
-    description: "Paints one stroke through points (document pixels, with optional pressure, time, tilt and barrel rotation) on a pixel layer with a library brush or the active one, optionally changed for this stroke. Grain-responsive brushes follow the paper; the mixer engine (mixer-brush, blender, smudge) picks up and moves paint already on the layer. The painting guides add their mirror copies. One undo step. Returns the layer id, changed bounds, dab count, the recorded strokeId (for replay_strokes) and, for the mixer, its load after the stroke.",
+    description: "Paints one stroke through points (document pixels, with optional pressure, time, tilt and barrel rotation) on a pixel layer with a library brush or the active one, optionally changed for this stroke. Grain-responsive brushes follow the paper; the mixer engine (mixer-brush, blender, smudge) picks up and moves paint already on the layer. The symmetry guide adds its mirror copies; with a tracing image that samples colours, a stroke without color takes the image colour at its first point. One undo step. Returns the layer id, changed bounds, dab count, the recorded strokeId (for replay_strokes) and, for the mixer, its load after the stroke.",
     inputSchema: {
       type: "object",
       properties: {
@@ -3020,15 +4078,16 @@ function createPaintEditorToolProvider(controller, options = {}) {
         layerId: LAYER_ID,
         brushId: { type: "string", description: "Brush id from list_brushes (default the active brush)." },
         brush: { type: "object", description: "Brush changes for this stroke only.", properties: BRUSH_FIELDS, additionalProperties: false },
-        color: { ...COLOR, description: "Paint colour #rrggbb (default the paint colour)." },
-        seed: { type: "integer", minimum: 0, description: "Jitter seed (default a new one); the same seed and points give the same marks." }
+        color: { ...COLOR2, description: "Paint colour #rrggbb (default the paint colour)." },
+        seed: { type: "integer", minimum: 0, description: "Jitter seed (default a new one); the same seed and points give the same marks." },
+        snapToPerspective: { type: "boolean", description: "Snap the points to the perspective guide, as a pen stroke would (default false)." }
       },
       required: ["points"],
       additionalProperties: false
     },
-    annotations: { title: "Paint a brush stroke", ...WRITE },
+    annotations: { title: "Paint a brush stroke", ...WRITE2 },
     handler: (a) => {
-      const r = c.paintStroke({ points: a.points, layerId: a.layerId, brushId: a.brushId, brush: a.brush, color: a.color, seed: a.seed });
+      const r = c.paintStroke({ points: a.points, layerId: a.layerId, brushId: a.brushId, brush: a.brush, color: a.color, seed: a.seed, snapToPerspective: a.snapToPerspective });
       return r.mixerLoad ? { ...r, mixerLoad: loadResult(r.mixerLoad) } : r;
     }
   });
@@ -3044,7 +4103,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       },
       additionalProperties: false
     },
-    annotations: { title: "List recorded strokes", ...READ },
+    annotations: { title: "List recorded strokes", ...READ2 },
     handler: ({ ids, last }) => {
       const all = c.getStrokes();
       const picked = ids ? all.filter((s) => ids.includes(s.id)) : all.slice(-(last ?? 100));
@@ -3093,7 +4152,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
           additionalProperties: false
         },
         pressureScale: { type: "number", minimum: 0, maximum: 4, description: "Multiply every pressure (default 1)." },
-        color: { ...COLOR, description: "Recolour (default each stroke\u2019s colour)." },
+        color: { ...COLOR2, description: "Recolour (default each stroke\u2019s colour)." },
         brushId: { type: "string", description: "Replay with this brush from list_brushes (default each stroke\u2019s brush)." },
         layerId: { type: "string", description: "Paint on this layer (default each stroke\u2019s layer)." },
         repeat: { type: "integer", minimum: 1, maximum: 100, description: "How many copies (default 1)." }
@@ -3101,7 +4160,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       required: ["strokeIds"],
       additionalProperties: false
     },
-    annotations: { title: "Replay strokes, varied", ...WRITE },
+    annotations: { title: "Replay strokes, varied", ...WRITE2 },
     handler: (a) => c.replayStrokes(a)
   });
   add({
@@ -3118,7 +4177,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       },
       additionalProperties: false
     },
-    annotations: { title: "Rotate, mirror or zoom the view", ...SET },
+    annotations: { title: "Rotate, mirror or zoom the view", ...SET2 },
     handler: ({ reset, ...v }) => {
       if (reset) c.resetView();
       return c.setView(v);
@@ -3129,15 +4188,15 @@ function createPaintEditorToolProvider(controller, options = {}) {
     title: "Set the drawing hand",
     description: "Says which hand holds the pen; palm rejection ignores touches on that side of the pen. Editor state, not an undo step. Returns the hand.",
     inputSchema: { type: "object", properties: { hand: { type: "string", enum: ["right", "left"], description: "right or left." } }, required: ["hand"], additionalProperties: false },
-    annotations: { title: "Set the drawing hand", ...SET },
+    annotations: { title: "Set the drawing hand", ...SET2 },
     handler: ({ hand }) => ({ hand: c.setHand(hand) })
   });
   add({
     name: "undo_paint",
     title: "Undo",
     description: "Undoes the last step (a stroke, a fill, a layer or paper change). Returns the label undone (null when there was nothing) and what can be undone and redone next.",
-    inputSchema: EMPTY,
-    annotations: { title: "Undo", ...WRITE },
+    inputSchema: EMPTY2,
+    annotations: { title: "Undo", ...WRITE2 },
     handler: () => {
       const undone = c.undo();
       const s = c.getState();
@@ -3148,8 +4207,8 @@ function createPaintEditorToolProvider(controller, options = {}) {
     name: "redo_paint",
     title: "Redo",
     description: "Redoes the last undone step. Returns the label redone (null when there was nothing) and what can be undone and redone next.",
-    inputSchema: EMPTY,
-    annotations: { title: "Redo", ...WRITE },
+    inputSchema: EMPTY2,
+    annotations: { title: "Redo", ...WRITE2 },
     handler: () => {
       const redone = c.redo();
       const s = c.getState();
@@ -3169,7 +4228,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       },
       additionalProperties: false
     },
-    annotations: { title: "Render a preview", ...READ },
+    annotations: { title: "Render a preview", ...READ2 },
     handler: ({ maxSide, layerIds, paper }) => {
       if (layerIds) {
         for (const id of layerIds) if (!c.getLayer(id)) throw new Error(`Unknown layer "${id}". Call list_layers for the ids.`);
@@ -3192,7 +4251,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       },
       additionalProperties: false
     },
-    annotations: { title: "Export the painting", ...READ },
+    annotations: { title: "Export the painting", ...READ2 },
     handler: async ({ format, quality, scale, paper }) => {
       const bytes = await c.exportImage({ format, quality, scale, paper });
       return { mimeType: format ?? "image/png", bytes: bytes.length, data: bytesToBase64(bytes) };
@@ -3202,8 +4261,8 @@ function createPaintEditorToolProvider(controller, options = {}) {
     name: "export_psd",
     title: "Export as PSD",
     description: 'Writes the painting as an 8-bit RGB PSD (PSB above 30000 px) through the shared PSD writer: every layer and group with its opacity, blend, mask and locks, the paper as a locked "Paper" pixel layer at the bottom, and the composite as the merged image. Changes nothing. Returns the file as base64, its size, whether it is a PSB, and warnings (pigment blending has no PSD equivalent).',
-    inputSchema: EMPTY,
-    annotations: { title: "Export as PSD", ...READ },
+    inputSchema: EMPTY2,
+    annotations: { title: "Export as PSD", ...READ2 },
     handler: () => {
       const r = c.exportPsd();
       return { data: bytesToBase64(r.bytes), bytes: r.bytes.length, psb: r.psb, warnings: r.warnings };
@@ -3214,7 +4273,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     title: "Save the document",
     description: "Returns the document as JSON (format pixerate-paint, version 1): canvas, paper, layers with PNG data URLs, and the recorded strokes unless strokes is false. Changes nothing.",
     inputSchema: { type: "object", properties: { strokes: { type: "boolean", description: "Include the recorded strokes (default true)." } }, additionalProperties: false },
-    annotations: { title: "Save the document", ...READ },
+    annotations: { title: "Save the document", ...READ2 },
     handler: ({ strokes }) => c.toJSON({ strokes })
   });
   add({
@@ -3222,13 +4281,14 @@ function createPaintEditorToolProvider(controller, options = {}) {
     title: "Open a document",
     description: "Opens a saved paint document (as save_document returns), replacing the painting and clearing the undo history. Returns the canvas, the layers and anything that could not be read.",
     inputSchema: { type: "object", properties: { document: { type: "object", description: "The saved document JSON." } }, required: ["document"], additionalProperties: false },
-    annotations: { title: "Open a document", ...DESTRUCTIVE },
+    annotations: { title: "Open a document", ...DESTRUCTIVE2 },
     handler: ({ document }) => {
       const problems = c.loadJSON(document);
       const d = c.document;
       return { width: d.canvas.width, height: d.canvas.height, layers: c.listLayers(), strokes: d.strokes.length, problems };
     }
   });
+  tools.push(...createPaintGuideTools(c));
   tools.push(...createPigmentTools());
   return { id: options.id ?? "paint-editor", namespace: options.namespace, tools };
 }
@@ -3240,17 +4300,24 @@ export {
   DEFAULT_DPI,
   DEFAULT_DYNAMICS,
   DEFAULT_PAPER,
+  DEFAULT_SWATCHES,
   DEFAULT_VIEW,
   DryStroke,
   GRAIN_PATTERNS,
   GRAIN_TILE,
+  HARMONY_KINDS,
   IDENTITY_AFFINE,
   IDENTITY_COPY,
   MAX_BRUSH_SIZE,
   MAX_CANVAS_SIDE,
+  MAX_COORDINATE,
+  MAX_IMAGE_SIDE,
   MAX_ZOOM,
   MIN_CANVAS_SIDE,
   MIN_ZOOM,
+  MIXING_PAD_HEIGHT,
+  MIXING_PAD_WIDTH,
+  MixingPad,
   PAINT_BRUSH_CATEGORIES,
   PAINT_BRUSH_ENGINES,
   PAINT_FORMAT,
@@ -3265,17 +4332,22 @@ export {
   PaperGrain,
   PenDabWalker,
   PenSmoother,
+  PerspectiveSnapper,
+  SNAP_DECIDE_DISTANCE,
+  SYMMETRY_MODES,
   TRACING_NODE_ID,
   TileableNoise,
   affineCopy,
   applyAffine,
   brushToJSON,
   clonePaper,
+  colorHarmony,
   composeAffine,
   createPaintCompositor,
   createPaintDocument,
   createPaintEditorToolProvider,
   createPaintLayer,
+  defaultGuides,
   defaultImageEncoder,
   deserializePaintDocument,
   deserializePaintDocumentAsync,
@@ -3287,6 +4359,9 @@ export {
   grainHeights,
   hash2,
   hexToRgb8,
+  hslToRgb,
+  hsvToRgb,
+  hueToWheel,
   invertAffine,
   isPalmTouch,
   mapPenPoint,
@@ -3299,25 +4374,36 @@ export {
   normalizeDynamics,
   normalizePaintBrush,
   normalizePaper,
+  normalizePerspective,
   normalizeRotation,
+  normalizeSymmetry,
   normalizeView,
   paperGrain,
   paperKey,
   paperNode,
   paperPreset,
   parseBrushLibrary,
+  parseHexColor,
   penOrientation,
+  perspectiveDirections,
+  perspectiveGuideLines,
   pointerToPenPoint,
   rand01,
   randSigned,
   renderBrushThumbnail,
   renderPaper,
+  rgbToHexColor,
+  rgbToHsl,
+  rgbToHsv,
   samplePressure,
   screenToDocument,
   seedFromString,
   serializePaintDocument,
   serializePaintDocumentExternal,
   strokeBounds,
+  symmetryAxisAngles,
+  symmetryAxisSegments,
+  symmetryCopies,
   thumbnailStroke,
   tiltToOrientation,
   toStrokePoint,
@@ -3325,6 +4411,7 @@ export {
   varyStroke,
   viewCssTransform,
   viewMatrix,
-  viewPenToDocument
+  viewPenToDocument,
+  wheelToHue
 };
 //# sourceMappingURL=index.js.map