@pixerate/editor 0.276.0 → 0.277.0

package/dist/paint-editor/index.js

@@ -14,7 +14,7 @@ import {
   mergeBrushPatch,
   multiColorSliders,
   patchBrushValue
-} from "../chunk-IJ6NSWKM.js";
+} from "../chunk-NJLPW4MM.js";
 import {
   createStickerTools,
   describeStickerRef
@@ -22,7 +22,7 @@ import {
 import {
   BRUSH_PREVIEW_DARK_PAPER,
   brushPreviewsOnDark
-} from "../chunk-GHYJAMMS.js";
+} from "../chunk-ROURHJYT.js";
 import {
   toVideoFfmpeg
 } from "../chunk-S2XPXA47.js";
@@ -42,7 +42,7 @@ import {
   resolveExternalAssets,
   serializeLayers,
   serializeLayersExternal
-} from "../chunk-XMSH66VU.js";
+} from "../chunk-FNIWHSLI.js";
 import "../chunk-ADMRNWR7.js";
 import "../chunk-WJ4WQJCC.js";
 import {
@@ -125,7 +125,7 @@ import {
   wetPaperInput,
   wetPigmentOf,
   withStrokePath
-} from "../chunk-4EM5NGCL.js";
+} from "../chunk-HHX7ST6Z.js";
 import {
   BRUSH_ID,
   BRUSH_PRESETS,
@@ -137,6 +137,7 @@ import {
   DEFAULT_BRISTLE,
   DEFAULT_BRUSH_ID,
   DEFAULT_DYNAMICS,
+  DEFAULT_FERRO,
   DEFAULT_FLUORESCENCE,
   DEFAULT_GHOST,
   DEFAULT_IMPASTO,
@@ -182,6 +183,7 @@ import {
   normalizeBristle,
   normalizeBrushSpec,
   normalizeDynamics,
+  normalizeFerro,
   normalizeFluorescence,
   normalizeGhost,
   normalizeImpasto,
@@ -198,7 +200,7 @@ import {
   readBrushSource,
   resolveBrush,
   usesPaintExchange
-} from "../chunk-XVPQNX7O.js";
+} from "../chunk-PPDUCZZV.js";
 import {
   STAMP_KINDS,
   StickersSlot,
@@ -412,6 +414,442 @@ function createPaintDocument(options = {}) {
   return { canvas, paper: normalizePaper(options.paper ?? {}), layers: [layer], activeLayerId: layer.id, strokes: [] };
 }
 
+// src/paint-editor/ferro.ts
+var DEFAULT_MAGNET_STRENGTH = 0.75;
+var DEFAULT_MAGNET_RADIUS = 72;
+var FERRO_CARRIER_RGB = [17, 24, 39];
+var FERRO_DEFAULT_GLOSS = 224;
+var FERRO_DEFAULT_METALLIC = 166;
+var FERRO_DEFAULT_RIM = 64;
+var SQRT3_HALF = 0.8660254037844386;
+function normalizeMagnet(raw, base) {
+  const x = raw.x ?? base?.x;
+  const y = raw.y ?? base?.y;
+  const strength = raw.strength ?? base?.strength ?? DEFAULT_MAGNET_STRENGTH;
+  const radius = raw.radius ?? base?.radius ?? DEFAULT_MAGNET_RADIUS;
+  if (typeof x !== "number" || !Number.isFinite(x)) {
+    throw new Error(`x ${String(x)} is not a finite coordinate; pass a number in canvas pixels.`);
+  }
+  if (typeof y !== "number" || !Number.isFinite(y)) {
+    throw new Error(`y ${String(y)} is not a finite coordinate; pass a number in canvas pixels.`);
+  }
+  if (typeof strength !== "number" || !Number.isFinite(strength) || strength < -1 || strength > 1) {
+    throw new Error(`strength ${String(strength)} is out of range; use -1..1.`);
+  }
+  if (typeof radius !== "number" || !Number.isFinite(radius) || radius < 8 || radius > 2e3) {
+    throw new Error(`radius ${String(radius)} is out of range; use 8..2000 px.`);
+  }
+  return { id: raw.id, x, y, strength, radius };
+}
+function emptyFerro() {
+  return new TiledSurface(1, /* @__PURE__ */ new Map(), 0);
+}
+var full = (t, channels) => {
+  if (t.data.length === TILE * TILE * channels) return t.data;
+  const out = new Uint8ClampedArray(TILE * TILE * channels);
+  const u = t.uniform ?? 0;
+  if (channels === 1) out.fill(u & 255);
+  else {
+    const bytes = [u >>> 24 & 255, u >>> 16 & 255, u >>> 8 & 255, u & 255];
+    for (let i = 0; i < out.length; i += 4) out.set(bytes, i);
+  }
+  return out;
+};
+function ferroToShadow(ferro) {
+  const tiles = /* @__PURE__ */ new Map();
+  for (const [key, tile] of ferro.tiles) {
+    const f = full(tile, 1);
+    const d = new Uint8ClampedArray(TILE * TILE * 4);
+    for (let i = 0, j = 0; i < f.length; i++, j += 4) {
+      if (!f[i]) continue;
+      d[j] = d[j + 1] = d[j + 2] = 255;
+      d[j + 3] = f[i];
+    }
+    const t = finishTile(d, 4, 0);
+    if (t) tiles.set(key, t);
+  }
+  return new TiledSurface(4, tiles, 0);
+}
+function shadowToFerro(shadow) {
+  const tiles = /* @__PURE__ */ new Map();
+  for (const [key, tile] of shadow.tiles) {
+    const s = full(tile, 4);
+    const d = new Uint8ClampedArray(TILE * TILE);
+    for (let i = 0, j = 0; i < d.length; i++, j += 4) {
+      if (s[j + 3]) d[i] = Math.round((s[j] + s[j + 1] + s[j + 2]) / 3 * s[j + 3] / 255);
+    }
+    const t = finishTile(d, 1, 0);
+    if (t) tiles.set(key, t);
+  }
+  return new TiledSurface(1, tiles, 0);
+}
+function ferroTwinBrush(brush) {
+  return normalizePaintBrush(
+    {
+      tip: { ...brush.tip, blend: "normal" },
+      behavior: { ...brush.behavior, mixing: "rgb" },
+      paint: null,
+      ...brush.engine === "mixer" ? { mixer: { ...brush.mixer, mixing: "rgb" } } : {},
+      ...brush.engine === "blender" ? { blender: { ...brush.blender, mixing: "rgb" } } : {},
+      ...brush.engine === "smudge" ? { smudge: { ...brush.smudge, mixing: "rgb" } } : {}
+    },
+    brush
+  );
+}
+function scaleFerro(ferro, k) {
+  if (k >= 1) return ferro;
+  const tiles = /* @__PURE__ */ new Map();
+  if (k > 0) {
+    for (const [key, tile] of ferro.tiles) {
+      const d = Uint8ClampedArray.from(full(tile, 1), (v) => Math.round(v * k));
+      const t = finishTile(d, 1, 0);
+      if (t) tiles.set(key, t);
+    }
+  }
+  return new TiledSurface(1, tiles, 0);
+}
+function mergeFerro(lower, upper, upperColor) {
+  if (!upper?.tiles.size) return lower;
+  const keys = /* @__PURE__ */ new Set([...lower?.tiles.keys() ?? [], ...upper.tiles.keys()]);
+  const tiles = /* @__PURE__ */ new Map();
+  for (const key of keys) {
+    const lo = lower?.tiles.get(key);
+    const up = upper.tiles.get(key);
+    const col = upperColor.tiles.get(key);
+    const l = lo ? full(lo, 1) : null;
+    const u = up ? full(up, 1) : null;
+    const c = col ? full(col, 4) : null;
+    const d = new Uint8ClampedArray(TILE * TILE);
+    for (let i = 0; i < d.length; i++) {
+      const uf = u ? u[i] : 0;
+      const ca = c ? c[i * 4 + 3] : 0;
+      const a = Math.max(ca, uf) / 255;
+      d[i] = Math.min(255, Math.round(uf + (l ? l[i] : 0) * (1 - a)));
+    }
+    const t = finishTile(d, 1, 0);
+    if (t) tiles.set(key, t);
+  }
+  return new TiledSurface(1, tiles, 0);
+}
+function ferroFieldAt(x, y, magnets) {
+  let bx = 0;
+  let by = 0;
+  let bz = 0;
+  for (let i = 0; i < magnets.length; i++) {
+    const m = magnets[i];
+    if (m.strength === 0) continue;
+    const invR = 1 / Math.max(8, m.radius);
+    const u = (x - m.x) * invR;
+    const v = (y - m.y) * invR;
+    const r2 = u * u + v * v;
+    const s = 1 + r2;
+    const d = 1 / (s * s * Math.sqrt(s));
+    bx += m.strength * 1.5 * u * d;
+    by += m.strength * 1.5 * v * d;
+    bz += m.strength * (1 - 0.5 * r2) * d;
+  }
+  const magnitude = Math.hypot(bx, by, bz);
+  return { bx, by, bz, magnitude };
+}
+function hexWave(px, py, k) {
+  const c0 = Math.cos(k * px);
+  const c1 = Math.cos(k * (-0.5 * px + SQRT3_HALF * py));
+  const c2 = Math.cos(k * (-0.5 * px - SQRT3_HALF * py));
+  return (c0 + c1 + c2 + 1.5) / 4.5;
+}
+function ferroSpikeHeightAt(x, y, ferroByte, magnets, settings = DEFAULT_FERRO) {
+  if (ferroByte <= 0 || magnets.length === 0) return 0;
+  const field = ferroFieldAt(x, y, magnets);
+  const bc = Math.max(0.01, settings.threshold);
+  if (field.magnitude <= bc) return 0;
+  const amp = Math.sqrt(1 - bc / field.magnitude) * (ferroByte / 255);
+  const wl = Math.max(4, settings.wavelength);
+  const k = 2 * Math.PI / wl;
+  const w0 = hexWave(x, y, k);
+  const sz = field.bz < 0 ? -1 : 1;
+  const tx = sz * field.bx / field.magnitude;
+  const ty = sz * field.by / field.magnitude;
+  const shift = 0.32 * wl * amp * w0;
+  const w = Math.max(0, hexWave(x - tx * shift, y - ty * shift, k));
+  const profile = 0.15 + 0.85 * w * Math.sqrt(w);
+  return Math.min(255, Math.max(1, Math.round(255 * amp * profile)));
+}
+function advectFerro(ferro, magnets, offset = { x: 0, y: 0 }, steps = 4) {
+  if (!ferro.tiles.size || !magnets.length || steps <= 0) return ferro;
+  const b = ferro.bounds;
+  if (!b) return ferro;
+  let active = false;
+  for (let i = 0; i < magnets.length; i++) {
+    if (magnets[i].strength !== 0) {
+      active = true;
+      break;
+    }
+  }
+  if (!active) return ferro;
+  const pad = Math.min(32, Math.max(8, steps * 4));
+  const rect = {
+    x: b.x - pad,
+    y: b.y - pad,
+    width: b.width + 2 * pad,
+    height: b.height + 2 * pad
+  };
+  const w = rect.width;
+  const h = rect.height;
+  const raw = readRegion(ferro, rect);
+  let cur = new Float64Array(w * h);
+  for (let i = 0; i < raw.length; i++) cur[i] = raw[i];
+  const vx = new Float64Array(w * h);
+  const vy = new Float64Array(w * h);
+  for (let gy = 0; gy < h; gy++) {
+    const docY = rect.y + gy + offset.y + 0.5;
+    for (let gx = 0; gx < w; gx++) {
+      const docX = rect.x + gx + offset.x + 0.5;
+      let fx = 0;
+      let fy = 0;
+      for (let mIdx = 0; mIdx < magnets.length; mIdx++) {
+        const m = magnets[mIdx];
+        if (m.strength === 0) continue;
+        const dx = m.x - docX;
+        const dy = m.y - docY;
+        const r = Math.hypot(dx, dy);
+        if (r <= 1e-6) continue;
+        const R = Math.max(8, m.radius);
+        const u = r / R;
+        const s = 1 + u * u;
+        const damp = Math.min(1, r * 0.5);
+        const pull = Math.abs(m.strength) * damp * 1.5 / (s * Math.sqrt(s));
+        fx += dx / r * pull;
+        fy += dy / r * pull;
+      }
+      const mag = Math.hypot(fx, fy);
+      if (mag > 2.5) {
+        const scale = 2.5 / mag;
+        fx *= scale;
+        fy *= scale;
+      }
+      const idx = gy * w + gx;
+      vx[idx] = fx;
+      vy[idx] = fy;
+    }
+  }
+  for (let step = 0; step < steps; step++) {
+    const next = new Float64Array(w * h);
+    for (let gy = 0; gy < h; gy++) {
+      for (let gx = 0; gx < w; gx++) {
+        const idx = gy * w + gx;
+        const val = cur[idx];
+        if (val <= 0) continue;
+        const nx = Math.min(w - 1, Math.max(0, gx + vx[idx]));
+        const ny = Math.min(h - 1, Math.max(0, gy + vy[idx]));
+        const x0 = Math.floor(nx);
+        const y0 = Math.floor(ny);
+        const x1 = Math.min(w - 1, x0 + 1);
+        const y1 = Math.min(h - 1, y0 + 1);
+        const tx = nx - x0;
+        const ty = ny - y0;
+        next[y0 * w + x0] += val * (1 - tx) * (1 - ty);
+        next[y0 * w + x1] += val * tx * (1 - ty);
+        next[y1 * w + x0] += val * (1 - tx) * ty;
+        next[y1 * w + x1] += val * tx * ty;
+      }
+    }
+    for (let i = 0; i < next.length; i++) {
+      cur[i] = Math.min(255, next[i]);
+    }
+  }
+  const out = new Uint8ClampedArray(w * h);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = Math.min(255, Math.max(0, Math.round(cur[i])));
+  }
+  return surfaceFromPixels({ width: w, height: h, data: out }, 1, rect.x, rect.y);
+}
+function ferroInfo(ferro, magnets = [], settings = DEFAULT_FERRO, offset = { x: 0, y: 0 }) {
+  if (!ferro || !ferro.tiles.size) {
+    return {
+      bounds: null,
+      peak: 0,
+      liquidPixels: 0,
+      maxSpikeHeight: 0,
+      spikePixels: 0,
+      magnetCount: magnets.length
+    };
+  }
+  let peak = 0;
+  let liquidPixels = 0;
+  let maxSpikeHeight = 0;
+  let spikePixels = 0;
+  for (const [key, tile] of ferro.tiles) {
+    const tx = key % 65536 - 32768;
+    const ty = Math.floor(key / 65536) - 32768;
+    const d = full(tile, 1);
+    for (let y = 0, i = 0; y < TILE; y++) {
+      const docY = ty * TILE + y + offset.y + 0.5;
+      for (let x = 0; x < TILE; x++, i++) {
+        const fb = d[i];
+        if (!fb) continue;
+        liquidPixels++;
+        if (fb > peak) peak = fb;
+        if (magnets.length > 0) {
+          const docX = tx * TILE + x + offset.x + 0.5;
+          const hs = ferroSpikeHeightAt(docX, docY, fb, magnets, settings);
+          if (hs > 0) {
+            spikePixels++;
+            if (hs > maxSpikeHeight) maxSpikeHeight = hs;
+          }
+        }
+      }
+    }
+  }
+  return {
+    bounds: peak ? ferro.bounds : null,
+    peak,
+    liquidPixels,
+    maxSpikeHeight,
+    spikePixels,
+    magnetCount: magnets.length
+  };
+}
+function ferroCacheKey(ferro) {
+  if (!ferro || !ferro.surface.tiles.size) return "";
+  const mKey = ferro.magnets.map((m) => `${m.id}:${m.x.toFixed(2)},${m.y.toFixed(2)},${m.strength.toFixed(3)},${m.radius.toFixed(1)}`).join(";");
+  const s = ferro.settings;
+  return `${ferro.offset.x},${ferro.offset.y}|${s.wavelength.toFixed(2)},${s.threshold.toFixed(3)}|${mKey}`;
+}
+function bakeFerroIntoThick(color, ferro, thick, magnets, settings = DEFAULT_FERRO, offset = { x: 0, y: 0 }) {
+  const baseThick = thick ?? emptyThickChannels();
+  if (!ferro.tiles.size) {
+    return { color, thick: baseThick, maxSpikeHeight: 0, spikePixels: 0, curedPixels: 0 };
+  }
+  const colorTiles = new Map(color.tiles);
+  const heightTiles = new Map(baseThick.height.tiles);
+  const materialTiles = new Map(baseThick.material.tiles);
+  let maxSpikeHeight = 0;
+  let spikePixels = 0;
+  let curedPixels = 0;
+  for (const [key, fTile] of ferro.tiles) {
+    const tx = key % 65536 - 32768;
+    const ty = Math.floor(key / 65536) - 32768;
+    const fd = full(fTile, 1);
+    const cTile = colorTiles.get(key);
+    const hTile = heightTiles.get(key);
+    const mTile = materialTiles.get(key);
+    const cd = cTile ? new Uint8ClampedArray(full(cTile, 4)) : new Uint8ClampedArray(TILE * TILE * 4);
+    const hd = hTile ? new Uint8ClampedArray(full(hTile, 1)) : new Uint8ClampedArray(TILE * TILE);
+    const md = mTile ? new Uint8ClampedArray(full(mTile, 4)) : new Uint8ClampedArray(TILE * TILE * 4);
+    let changedColor = false;
+    let changedHeight = false;
+    let changedMaterial = false;
+    for (let y = 0, p = 0; y < TILE; y++) {
+      const docY = ty * TILE + y + offset.y + 0.5;
+      for (let x = 0; x < TILE; x++, p++) {
+        const fb = fd[p];
+        if (!fb) continue;
+        curedPixels++;
+        const i = p * 4;
+        if (cd[i + 3] < fb) {
+          const a0 = cd[i + 3] / fb;
+          cd[i] = Math.round(cd[i] * a0 + FERRO_CARRIER_RGB[0] * (1 - a0));
+          cd[i + 1] = Math.round(cd[i + 1] * a0 + FERRO_CARRIER_RGB[1] * (1 - a0));
+          cd[i + 2] = Math.round(cd[i + 2] * a0 + FERRO_CARRIER_RGB[2] * (1 - a0));
+          cd[i + 3] = fb;
+          changedColor = true;
+        }
+        const docX = tx * TILE + x + offset.x + 0.5;
+        const hs = magnets.length > 0 ? ferroSpikeHeightAt(docX, docY, fb, magnets, settings) : 0;
+        if (hs > 0) {
+          spikePixels++;
+          if (hs > maxSpikeHeight) maxSpikeHeight = hs;
+        }
+        const bead = Math.max(hs, Math.round(fb * 28 / 255));
+        const nh = Math.min(255, hd[p] + bead);
+        if (nh !== hd[p]) {
+          hd[p] = nh;
+          changedHeight = true;
+        }
+        const w = fb / 255;
+        const ng = Math.max(md[i], Math.round(FERRO_DEFAULT_GLOSS * w));
+        const nm = Math.max(md[i + 1], Math.round(FERRO_DEFAULT_METALLIC * w));
+        const nr = Math.max(md[i + 2], Math.round(FERRO_DEFAULT_RIM * w));
+        const na = md[i + 3] || 255;
+        if (ng !== md[i] || nm !== md[i + 1] || nr !== md[i + 2] || na !== md[i + 3]) {
+          md[i] = ng;
+          md[i + 1] = nm;
+          md[i + 2] = nr;
+          md[i + 3] = na;
+          changedMaterial = true;
+        }
+      }
+    }
+    if (changedColor) {
+      const ct = finishTile(cd, 4, 0);
+      if (ct) colorTiles.set(key, ct);
+    }
+    if (changedHeight) {
+      const ht = finishTile(hd, 1, 0);
+      if (ht) heightTiles.set(key, ht);
+    }
+    if (changedMaterial) {
+      const mt = finishTile(md, 4, 0);
+      if (mt) materialTiles.set(key, mt);
+    }
+  }
+  return {
+    color: new TiledSurface(4, colorTiles, color.defaultValue),
+    thick: {
+      height: new TiledSurface(1, heightTiles, 0),
+      material: new TiledSurface(4, materialTiles, 0),
+      film: baseThick.film
+    },
+    maxSpikeHeight,
+    spikePixels,
+    curedPixels
+  };
+}
+function ferroToJSON(ferro, settings) {
+  const b = ferroInfo(ferro).bounds;
+  if (!b) return null;
+  const out = {
+    rect: { ...b },
+    ferro: pngDataUrl(b.width, b.height, readRegion(ferro, b), 1)
+  };
+  if (settings) {
+    if (settings.wavelength !== DEFAULT_FERRO.wavelength) out.wavelength = settings.wavelength;
+    if (settings.threshold !== DEFAULT_FERRO.threshold) out.threshold = settings.threshold;
+  }
+  return out;
+}
+function ferroFromJSON(raw) {
+  const r = raw;
+  if (!r || typeof r !== "object" || !r.rect || typeof r.ferro !== "string") {
+    throw new Error("not a saved ferrofluid channel");
+  }
+  const parsed = parseDataUrl(r.ferro);
+  if (!parsed) throw new Error("the ferrofluid channel is not a PNG data URL");
+  const img = decodePng(parsed.bytes, { keepGray: true });
+  const data = img.channels === 1 ? img.data : Uint8ClampedArray.from({ length: img.width * img.height }, (_, i) => img.data[i * 4]);
+  const surface = surfaceFromPixels({ width: img.width, height: img.height, data }, 1, r.rect.x, r.rect.y);
+  const settings = normalizeFerro({
+    amount: 0,
+    wavelength: r.wavelength,
+    threshold: r.threshold
+  });
+  return { surface, settings };
+}
+function magnetsFromJSON(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const item of raw) {
+    if (!item || typeof item !== "object") continue;
+    const m = item;
+    if (typeof m.id !== "string" || !m.id || typeof m.x !== "number" || typeof m.y !== "number") continue;
+    try {
+      out.push(normalizeMagnet({ id: m.id, x: m.x, y: m.y, strength: m.strength, radius: m.radius }));
+    } catch {
+    }
+  }
+  return out;
+}
+
 // src/paint-editor/thick.ts
 var DEFAULT_LIGHTING = { azimuth: 315, elevation: 40, relief: 0.7 };
 function normalizeLighting(raw = {}, base = DEFAULT_LIGHTING) {
@@ -551,8 +989,14 @@ function lightTile(color, height, heightAround, material, light, film = null, vi
 }
 var LitCache = class {
   tiles = /* @__PURE__ */ new Map();
-  /** The layer's pixels lit (tiles without relief or film nearby are the colour tiles themselves). */
-  lit(color, ch, light, viewTilt = DEFAULT_VIEW_TILT) {
+  /**
+   * The layer's pixels lit (tiles without relief, film or ferrofluid nearby are the colour tiles
+   * themselves). Without ferrofluid this is the thick-paint / thin-film pass; with it, the liquid
+   * ferrofluid adds its carrier colour, glossy metallic material and (near magnets) Rosensweig
+   * spike heights before the same lighting.
+   */
+  lit(color, ch, light, viewTilt = DEFAULT_VIEW_TILT, ferro) {
+    if (ferro && ferro.surface.tiles.size > 0) return this.litFerro(color, ch, light, viewTilt, ferro);
     const hasRelief = ch.height.tiles.size > 0 && light.relief > 0;
     const hasFilm = ch.film.tiles.size > 0;
     if (!hasRelief && !hasFilm) return color;
@@ -601,6 +1045,101 @@ var LitCache = class {
     for (const key of [...this.tiles.keys()]) if (!keys.has(key)) this.tiles.delete(key);
     return new TiledSurface(4, out, color.defaultValue);
   }
+  /**
+   * The ferrofluid lighting pass: every tile with ferrofluid or thick relief nearby is lit, with the
+   * liquid's carrier colour and gloss / metal material blended in and its spikes added to the
+   * height field. Thick relief is lit even when `light.relief` is 0 here (the spikes need it), and
+   * a thin film on the same layer still colours the lit tiles.
+   */
+  litFerro(color, ch, light, viewTilt, ferro) {
+    const hasFerroSpikes = ferro.magnets.length > 0;
+    const lk = `${lightingKey(light)}|${viewTiltKey(viewTilt)}`;
+    const fk = ferroCacheKey(ferro);
+    const out = new Map(color.tiles);
+    const keys = /* @__PURE__ */ new Set();
+    for (const key of color.tiles.keys()) keys.add(key);
+    for (const key of ferro.surface.tiles.keys()) keys.add(key);
+    for (const key of keys) {
+      const tile = color.tiles.get(key) ?? null;
+      const tx = key % 65536 - 32768;
+      const ty = Math.floor(key / 65536) - 32768;
+      const aroundH = (dx, dy) => ch.height.tiles.get(tileKey(tx + dx, ty + dy)) ?? null;
+      const aroundF = (dx, dy) => ferro.surface.tiles.get(tileKey(tx + dx, ty + dy)) ?? null;
+      const film = ch.film.tiles.get(key) ?? null;
+      let any = !!film;
+      for (let dy = -1; dy <= 1 && !any; dy++) {
+        for (let dx = -1; dx <= 1 && !any; dx++) {
+          if (aroundH(dx, dy) || aroundF(dx, dy)) any = true;
+        }
+      }
+      if (!any) continue;
+      const m = ch.material.tiles.get(key) ?? null;
+      const f = ferro.surface.tiles.get(key) ?? null;
+      if (!tile && !f) continue;
+      const inputs = [tile, lk, m, fk, film];
+      for (let dy = -1; dy <= 1; dy++) for (let dx = -1; dx <= 1; dx++) inputs.push(aroundH(dx, dy));
+      for (let dy = -1; dy <= 1; dy++) for (let dx = -1; dx <= 1; dx++) inputs.push(aroundF(dx, dy));
+      const cached = this.tiles.get(key);
+      if (cached && cached.inputs.length === inputs.length && cached.inputs.every((v, i) => v === inputs[i])) {
+        out.set(key, cached.tile);
+        continue;
+      }
+      let cd = tile ? expand(tile, 4) : new Uint8ClampedArray(TILE * TILE * 4);
+      let md = m ? expand(m, 4) : null;
+      if (f) {
+        const fd = expand(f, 1);
+        cd = new Uint8ClampedArray(cd);
+        const mBuf = md ? new Uint8ClampedArray(md) : new Uint8ClampedArray(TILE * TILE * 4);
+        for (let p = 0; p < fd.length; p++) {
+          const fb = fd[p];
+          if (!fb) continue;
+          const i = p * 4;
+          if (cd[i + 3] < fb) {
+            const a0 = cd[i + 3] / fb;
+            cd[i] = Math.round(cd[i] * a0 + FERRO_CARRIER_RGB[0] * (1 - a0));
+            cd[i + 1] = Math.round(cd[i + 1] * a0 + FERRO_CARRIER_RGB[1] * (1 - a0));
+            cd[i + 2] = Math.round(cd[i + 2] * a0 + FERRO_CARRIER_RGB[2] * (1 - a0));
+            cd[i + 3] = fb;
+          }
+          const w = fb / 255;
+          mBuf[i] = Math.max(mBuf[i], Math.round(FERRO_DEFAULT_GLOSS * w));
+          mBuf[i + 1] = Math.max(mBuf[i + 1], Math.round(FERRO_DEFAULT_METALLIC * w));
+          mBuf[i + 2] = Math.max(mBuf[i + 2], Math.round(FERRO_DEFAULT_RIM * w));
+          mBuf[i + 3] = mBuf[i + 3] || 255;
+        }
+        md = mBuf;
+      }
+      const buildHeightTile = (ntx, nty) => {
+        const nkey = tileKey(ntx, nty);
+        const ht = ch.height.tiles.get(nkey) ?? null;
+        const ft = hasFerroSpikes ? ferro.surface.tiles.get(nkey) ?? null : null;
+        if (!ht && !ft) return null;
+        if (!ft) return expand(ht, 1);
+        const hBase = ht ? expand(ht, 1) : null;
+        const fData = expand(ft, 1);
+        const outH = hBase ? new Uint8ClampedArray(hBase) : new Uint8ClampedArray(TILE * TILE);
+        const ox = ntx * TILE + ferro.offset.x + 0.5;
+        const oy = nty * TILE + ferro.offset.y + 0.5;
+        for (let py = 0, p = 0; py < TILE; py++) {
+          const docY = oy + py;
+          for (let px = 0; px < TILE; px++, p++) {
+            const fb = fData[p];
+            if (!fb) continue;
+            const hs = ferroSpikeHeightAt(ox + px, docY, fb, ferro.magnets, ferro.settings);
+            if (hs > 0) outH[p] = Math.min(255, outH[p] + hs);
+          }
+        }
+        return outH;
+      };
+      const hd = buildHeightTile(tx, ty);
+      const data = lightTile(cd, hd, (dx, dy) => buildHeightTile(tx + dx, ty + dy), md, light, film ? expand(film, 4) : null, viewTilt);
+      const lit = { data, uniform: null };
+      this.tiles.set(key, { inputs, tile: lit });
+      out.set(key, lit);
+    }
+    for (const key of [...this.tiles.keys()]) if (!keys.has(key)) this.tiles.delete(key);
+    return new TiledSurface(4, out, color.defaultValue);
+  }
 };
 function expand(t, channels) {
   if (t.data.length === TILE * TILE * channels) return t.data;
@@ -924,27 +1463,27 @@ var ThickStrokeDriver = class {
         const u = ((dx + 0.5 - d.x) * nxs + (dy + 0.5 - d.y) * nys) / r;
         const h0 = this.getH(lx, ly);
         let h = h0;
-        const full2 = 255 * thick * k;
+        const full3 = 255 * thick * k;
         switch (im.tool) {
           case "brush": {
             const ridge = 0.6 + 0.4 * Math.sin(u * 9 + hash2(Math.round(u * 6), 3, seed) * 6.28) + 0.15 * (hash2(lx, ly, seed) - 0.5);
-            const target = full2 * c * ridge;
+            const target = full3 * c * ridge;
             h = Math.max(h0 * (1 - 0.25 * c * im.drag), Math.min(255, h0 * 0.35 + target));
             break;
           }
           case "tube": {
             const dome = Math.sqrt(Math.max(0, c));
-            h = Math.max(h0, Math.min(255, full2 * dome * 1.1));
+            h = Math.max(h0, Math.min(255, full3 * dome * 1.1));
             break;
           }
           case "gloop": {
             const dome = Math.sqrt(Math.max(0, 1 - Math.min(1, Math.abs(u)) ** 2));
-            h = Math.max(h0, Math.min(255, full2 * dome * (c > 0.2 ? 1 : c * 5)));
+            h = Math.max(h0, Math.min(255, full3 * dome * (c > 0.2 ? 1 : c * 5)));
             break;
           }
           case "roller": {
             const stipple = 0.75 + 0.5 * hash2(lx >> 1, ly >> 1, seed);
-            h = h0 + (Math.min(255, full2 * 0.6 * stipple) - h0) * Math.min(1, c * 1.5);
+            h = h0 + (Math.min(255, full3 * 0.6 * stipple) - h0) * Math.min(1, c * 1.5);
             break;
           }
         }
@@ -1068,7 +1607,7 @@ function normalizeLightSpill(raw, base = DEFAULT_LIGHT_SPILL) {
 function emptyLight() {
   return new TiledSurface(1, /* @__PURE__ */ new Map(), 0);
 }
-var full = (t, channels) => {
+var full2 = (t, channels) => {
   if (t.data.length === TILE * TILE * channels) return t.data;
   const out = new Uint8ClampedArray(TILE * TILE * channels);
   const u = t.uniform ?? 0;
@@ -1082,7 +1621,7 @@ var full = (t, channels) => {
 function lightToShadow(light) {
   const tiles = /* @__PURE__ */ new Map();
   for (const [key, tile] of light.tiles) {
-    const l = full(tile, 1);
+    const l = full2(tile, 1);
     const d = new Uint8ClampedArray(TILE * TILE * 4);
     for (let i = 0, j = 0; i < l.length; i++, j += 4) {
       if (!l[i]) continue;
@@ -1097,7 +1636,7 @@ function lightToShadow(light) {
 function shadowToLight(shadow) {
   const tiles = /* @__PURE__ */ new Map();
   for (const [key, tile] of shadow.tiles) {
-    const s = full(tile, 4);
+    const s = full2(tile, 4);
     const d = new Uint8ClampedArray(TILE * TILE);
     for (let i = 0, j = 0; i < d.length; i++, j += 4) if (s[j + 3]) d[i] = Math.round((s[j] + s[j + 1] + s[j + 2]) / 3 * s[j + 3] / 255);
     const t = finishTile(d, 1, 0);
@@ -1132,7 +1671,7 @@ function scaleLight(light, k) {
   const tiles = /* @__PURE__ */ new Map();
   if (k > 0) {
     for (const [key, tile] of light.tiles) {
-      const d = Uint8ClampedArray.from(full(tile, 1), (v) => Math.round(v * k));
+      const d = Uint8ClampedArray.from(full2(tile, 1), (v) => Math.round(v * k));
       const t = finishTile(d, 1, 0);
       if (t) tiles.set(key, t);
     }
@@ -1147,9 +1686,9 @@ function mergeLight(lower, upper, upperColor) {
     const lo = lower?.tiles.get(key);
     const up = upper.tiles.get(key);
     const col = upperColor.tiles.get(key);
-    const l = lo ? full(lo, 1) : null;
-    const u = up ? full(up, 1) : null;
-    const c = col ? full(col, 4) : null;
+    const l = lo ? full2(lo, 1) : null;
+    const u = up ? full2(up, 1) : null;
+    const c = col ? full2(col, 4) : null;
     const d = new Uint8ClampedArray(TILE * TILE);
     for (let i = 0; i < d.length; i++) {
       const a = c ? c[i * 4 + 3] / 255 : 0;
@@ -1186,10 +1725,10 @@ var LightCache = class {
         out.set(key, cached.tile);
         continue;
       }
-      const c = full(tile, 4);
-      const ld = l ? full(l, 1) : null;
-      const md = m ? full(m, 4) : null;
-      const hd = h ? full(h, 1) : null;
+      const c = full2(tile, 4);
+      const ld = l ? full2(l, 1) : null;
+      const md = m ? full2(m, 4) : null;
+      const hd = h ? full2(h, 1) : null;
       const d = new Uint8ClampedArray(c);
       for (let y = 0, i = 0; y < TILE; y++) {
         for (let x = 0; x < TILE; x++, i++) {
@@ -2916,6 +3455,7 @@ var PaintStrokeSession = class _PaintStrokeSession {
     this.invisibleDaylight = brush.fluorescence.amount > 0 && brush.fluorescence.invisible && brush.engine !== "eraser" && brush.engine !== "blender" && brush.engine !== "smudge";
     if (init.wet) this.wetDriver = init.wet.driver;
     if (init.light && !init.wet && !init.sticker) this.lightTwin = this.makeLightTwin(init.light.surface);
+    if (init.ferro && !init.wet && !init.sticker) this.ferroTwin = this.makeFerroTwin(init.ferro.surface);
     if (init.fluor && !init.wet && !init.sticker) this.fluorTwin = this.makeFluorTwin(init.fluor.surface);
     if (init.thermo && !init.wet && !init.sticker) this.thermoTwin = this.makeThermoTwin(init.thermo.surface);
     this.apply = {
@@ -2948,6 +3488,9 @@ var PaintStrokeSession = class _PaintStrokeSession {
   /** Light paint: the stroke's twin over the light channel, and what it left there. */
   lightTwin = null;
   lightResult = null;
+  /** Ferrofluid paint: the stroke's twin over the ferrofluid channel, and what it left there. */
+  ferroTwin = null;
+  ferroResult = null;
   /** UV-fluorescent ink: the stroke's twin over the fluorescence channel, and what it left there. */
   fluorTwin = null;
   fluorResult = null;
@@ -3046,6 +3589,7 @@ var PaintStrokeSession = class _PaintStrokeSession {
       paint,
       effect,
       light: null,
+      ferro: null,
       fluor: null,
       thermo: null
     });
@@ -3069,7 +3613,8 @@ var PaintStrokeSession = class _PaintStrokeSession {
       inputFilter: void 0,
       light: null,
       fluor: null,
-      thermo: null
+      thermo: null,
+      ferro: null
     });
   }
   /** The stroke's twin over the 4-channel thermochromic surface (see `heat.ts`). */
@@ -3104,7 +3649,8 @@ var PaintStrokeSession = class _PaintStrokeSession {
       effect: null,
       light: null,
       fluor: null,
-      thermo: null
+      thermo: null,
+      ferro: null
     });
   }
   /** Light paint: the layer's light channel after the stroke, or `null` when the stroke has no twin or left it unchanged. */
@@ -3119,6 +3665,44 @@ var PaintStrokeSession = class _PaintStrokeSession {
   thermoChannel() {
     return this.thermoResult;
   }
+  /** The stroke's twin over the ferrofluid channel: the same marks in grey at the brush's ferro amount (see `ferro.ts`). */
+  makeFerroTwin(ferro) {
+    const init = this.init;
+    const grey = Math.round(init.brush.ferro.amount * 255);
+    const g = grey / 255;
+    const hex2 = "#" + grey.toString(16).padStart(2, "0").repeat(3);
+    const host = {
+      update: () => {
+      },
+      commit: (_s, surface) => {
+        this.ferroResult = surface ? shadowToFerro(surface) : null;
+      }
+    };
+    const effect = init.effect ? { source: init.effect.source, pixels: { ...init.effect.pixels, data: greyPixels(init.effect.pixels.data, grey) } } : null;
+    const paint = init.paint ? { ...init.paint, stops: init.paint.stops.map((st) => ({ ...st, color: hex2 })) } : null;
+    return new _PaintStrokeSession(host, {
+      ...init,
+      surface: ferroToShadow(ferro),
+      lockTransparency: false,
+      brush: ferroTwinBrush(init.brush),
+      color: [grey, grey, grey, 255],
+      colorHex: hex2,
+      secondary: [grey, grey, grey, 255],
+      inputFilter: void 0,
+      mixerLoad: { reservoir: init.mixerLoad.reservoir ? [g, g, g] : null, amount: init.mixerLoad.amount, pickup: null },
+      thick: init.thick,
+      paint,
+      effect,
+      light: null,
+      ferro: null,
+      fluor: null,
+      thermo: null
+    });
+  }
+  /** Ferrofluid paint: the layer's ferrofluid channel after the stroke, or `null` when the stroke has no twin or left it unchanged. */
+  ferroChannel() {
+    return this.ferroResult;
+  }
   tileTarget() {
     return {
       offset: this.init.offset,
@@ -3149,6 +3733,7 @@ var PaintStrokeSession = class _PaintStrokeSession {
     this.lastRaw = points[points.length - 1];
     this.host.sampled?.(this, points);
     this.lightTwin?.push(points);
+    this.ferroTwin?.push(points);
     this.fluorTwin?.push(points);
     this.thermoTwin?.push(points);
     if (this.wetDriver) {
@@ -3242,6 +3827,7 @@ var PaintStrokeSession = class _PaintStrokeSession {
     this.update(this.dry ? this.dry.finish() : this.thickDriver ? this.thickDriver.finish() : this.stickerSpray ? this.stickerSpray.finish() : this.wet.finish());
     this.closed = true;
     if (this.lightTwin?.open) this.lightTwin.end();
+    if (this.ferroTwin?.open) this.ferroTwin.end();
     if (this.fluorTwin?.open) this.fluorTwin.end();
     if (this.thermoTwin?.open) this.thermoTwin.end();
     const ch = this.base.channels;
@@ -3276,6 +3862,8 @@ var PaintStrokeSession = class _PaintStrokeSession {
     if (this.fluorTwin?.open) this.fluorTwin.cancel();
     if (this.thermoTwin?.open) this.thermoTwin.cancel();
     this.lightResult = null;
+    if (this.ferroTwin?.open) this.ferroTwin.cancel();
+    this.ferroResult = null;
     this.fluorResult = null;
     this.thermoResult = null;
     this.host.commit(this, null, true);
@@ -3392,8 +3980,8 @@ function nearestOnStencil(s, p) {
   if (s.kind === "arc") {
     const c = s.center;
     const ang = Math.atan2(p.y - c.y, p.x - c.x);
-    const full2 = Math.abs(s.endAngle - s.startAngle) >= 360;
-    if (full2) {
+    const full3 = Math.abs(s.endAngle - s.startAngle) >= 360;
+    if (full3) {
       const q = { x: c.x + Math.cos(ang) * s.radius, y: c.y + Math.sin(ang) * s.radius };
       return { point: q, distance: Math.hypot(p.x - q.x, p.y - q.y) };
     }
@@ -3836,7 +4424,7 @@ function deserializePaintDocument(raw) {
   const wetEvents = Array.isArray(r.wetEvents) ? r.wetEvents.filter((e) => e && typeof e === "object" && Number.isInteger(e.clock) && typeof e.kind === "string") : [];
   const state = { canvas, paper, layers, activeLayerId, strokes: readStrokes(r.strokes, problems) };
   if (wetEvents.length) state.wetEvents = wetEvents;
-  const paintEvents = Array.isArray(r.paintEvents) ? r.paintEvents.filter((e) => e && typeof e === "object" && Number.isInteger(e.at) && typeof e.layerId === "string" && ["fill", "fill-region", "clear", "flatten", "stickers", "live-strokes"].includes(e.kind)) : [];
+  const paintEvents = Array.isArray(r.paintEvents) ? r.paintEvents.filter((e) => e && typeof e === "object" && Number.isInteger(e.at) && typeof e.layerId === "string" && ["fill", "fill-region", "clear", "flatten", "stickers", "live-strokes", "magnets", "cure-ferrofluid"].includes(e.kind)) : [];
   if (paintEvents.length) state.paintEvents = paintEvents;
   const o = r.origin;
   if (o && typeof o === "object" && Number.isFinite(o.x) && Number.isFinite(o.y) && (o.x || o.y)) state.origin = { x: Math.round(o.x), y: Math.round(o.y) };
@@ -4768,6 +5356,7 @@ function liveStrokeRefusal(brush) {
   if (brush.light.amount > 0) return `The ${brush.name} brush lays light, which a stroke layer doesn't redraw yet; paint light on a pixel layer (add_layer), or set light.amount to 0 (set_brush).`;
   if (brush.fluorescence.amount > 0) return `The ${brush.name} brush lays UV-fluorescent ink, which a stroke layer doesn't redraw yet; paint it on a pixel layer (add_layer), or set fluorescence.amount to 0 (set_brush).`;
   if (brush.thermochromic.hotColor !== null) return `The ${brush.name} brush lays thermochromic ink, which a stroke layer doesn't redraw yet; paint it on a pixel layer (add_layer), or remove thermochromic (set_brush).`;
+  if (brush.ferro.amount > 0) return `The ${brush.name} brush lays ferrofluid, which a stroke layer doesn't redraw; paint ferrofluid on a pixel layer (add_layer), or set ferro.amount to 0 (set_brush).`;
   if (brush.behavior.pickup > 0) return `The ${brush.name} brush picks up the paint under it (pickup ${brush.behavior.pickup}), so it can't be redrawn on its own; set behavior.pickup to 0 (set_brush) or paint on a pixel layer.`;
   return null;
 }
@@ -5036,6 +5625,12 @@ async function replayPainting(source, target, options = {}) {
     if (strokes >= maxStrokes && item.kind === "stroke") break;
     if (item.kind === "paint") {
       const e = item.event;
+      if (e.kind === "magnets") {
+        const d = e.data;
+        const list = (d?.magnets ?? []).map((m) => s === 1 ? m : { ...m, x: m.x * s, y: m.y * s, radius: Math.min(2e3, Math.max(8, m.radius * s)) });
+        target.replaceMagnets(list, Boolean(d?.advect));
+        continue;
+      }
       if (!target.getLayer(e.layerId)) continue;
       if (e.kind === "fill") target.fillLayer({ layerId: e.layerId, ...e.data });
       else if (e.kind === "fill-region") {
@@ -5050,6 +5645,7 @@ async function replayPainting(source, target, options = {}) {
           ...d.expand !== void 0 ? { expand: Math.max(-16, Math.min(16, d.expand * s)) } : {}
         });
       } else if (e.kind === "clear") target.clearLayer(e.layerId);
+      else if (e.kind === "cure-ferrofluid") target.cureFerrofluid(e.layerId);
       else if (e.kind === "live-strokes") {
         const d = e.data;
         if (d?.rasterized) target.replaceLiveStrokes(e.layerId, null);
@@ -6363,6 +6959,9 @@ var PaintEditorController = class _PaintEditorController {
   litCaches = /* @__PURE__ */ new Map();
   /** The live impasto stroke's channels. */
   liveThick = null;
+  /** The live ferrofluid stroke's channel. */
+  liveFerro = null;
+  nextMagnetId = 1;
   /** The UV / blacklight setting (saved with the document, not undo steps). */
   uvLight = { ...DEFAULT_UV_LIGHT };
   uvCaches = /* @__PURE__ */ new Map();
@@ -6892,6 +7491,7 @@ var PaintEditorController = class _PaintEditorController {
       paper: options.paper === void 0 ? { ...this.doc.paper, offset: void 0 } : this.resolvePaper(options.paper)
     });
     this.extensions = {};
+    this.nextMagnetId = 1;
     this.guides = { ...this.guides, symmetry: { ...this.guides.symmetry, center: { x: next.canvas.width / 2, y: next.canvas.height / 2 } }, tracing: null };
     this.tracingVersion++;
     if (this.wet.world || this.wet.patterns.size) {
@@ -7049,7 +7649,7 @@ var PaintEditorController = class _PaintEditorController {
   describeLayer(l, parentId = findLayer(this.doc.layers, l.id)?.parent?.id ?? null, depth = findLayer(this.doc.layers, l.id)?.path.length ?? 0) {
     let bounds = null;
     if (l.type === "pixel") {
-      const b = unionRect(contentBounds(l.surface), this.doc.fluor?.[l.id] ? contentBounds(this.doc.fluor[l.id]) : null);
+      const b = unionRect(unionRect(contentBounds(l.surface), this.doc.fluor?.[l.id] ? contentBounds(this.doc.fluor[l.id]) : null), this.doc.ferro?.[l.id]?.bounds ?? null);
       bounds = b ? { ...b, x: b.x + l.offset.x, y: b.y + l.offset.y } : null;
     } else for (const c of flattenLayers(l.children)) if (c.type === "pixel") bounds = unionRect(bounds, this.describeLayer(c, l.id, depth + 1).bounds);
     return {
@@ -7250,7 +7850,8 @@ var PaintEditorController = class _PaintEditorController {
       ...this.liveStrokesWithout(removedIds),
       ...this.lightWithout(removedIds),
       ...this.fluorWithout(removedIds),
-      ...this.thermoWithout(removedIds)
+      ...this.thermoWithout(removedIds),
+      ...this.ferroWithout(removedIds)
     });
     return { removed: id, activeLayerId: active };
   }
@@ -7266,12 +7867,16 @@ var PaintEditorController = class _PaintEditorController {
     const stickers = { ...this.doc.stickers ?? {} };
     const liveStrokes = { ...this.doc.liveStrokes ?? {} };
     const light = { ...this.doc.light ?? {} };
+    const ferro = { ...this.doc.ferro ?? {} };
+    const ferroSettings = { ...this.doc.ferroSettings ?? {} };
     const fluor = { ...this.doc.fluor ?? {} };
     const thermo = { ...this.doc.thermo ?? {} };
     const copy = (l) => {
       const id2 = newPaintLayerId();
       if (light[l.id]) light[id2] = light[l.id];
       if (this.lightSpills[l.id]) this.lightSpills[id2] = { ...this.lightSpills[l.id] };
+      if (ferro[l.id]) ferro[id2] = ferro[l.id];
+      if (ferroSettings[l.id]) ferroSettings[id2] = { ...ferroSettings[l.id] };
       if (fluor[l.id]) fluor[id2] = fluor[l.id];
       if (thermo[l.id]) thermo[id2] = thermo[l.id];
       if (thick[l.id]) thick[id2] = thick[l.id];
@@ -7292,7 +7897,9 @@ var PaintEditorController = class _PaintEditorController {
         ...this.doc.liveStrokes ? { liveStrokes } : {},
         ...this.doc.light ? { light } : {},
         ...this.doc.fluor ? { fluor } : {},
-        ...this.doc.thermo ? { thermo } : {}
+        ...this.doc.thermo ? { thermo } : {},
+        ...this.doc.ferro ? { ferro } : {},
+        ...this.doc.ferroSettings ? { ferroSettings } : {}
       })
     );
     return this.describeLayer(dup);
@@ -7345,6 +7952,13 @@ var PaintEditorController = class _PaintEditorController {
     const mergedLight = this.doc.light?.[upper.id] || this.doc.light?.[below.id] ? mergeLight(toDoc(this.doc.light?.[below.id], below), upper.visible ? toDoc(this.doc.light?.[upper.id], upper) : void 0, upperDoc) : void 0;
     const lightAfter = this.lightWithout([upper.id, below.id]).light ?? (this.doc.light ? { ...this.doc.light } : void 0);
     const light = mergedLight ? { ...lightAfter ?? {}, [below.id]: mergedLight } : lightAfter;
+    const mergedFerro = this.doc.ferro?.[upper.id] || this.doc.ferro?.[below.id] ? mergeFerro(toDoc(this.doc.ferro?.[below.id], below), upper.visible ? toDoc(this.doc.ferro?.[upper.id], upper) : void 0, translateSurface(upper.surface, upper.offset.x, upper.offset.y)) : void 0;
+    const ferroRemoved = this.ferroWithout([upper.id, below.id]);
+    const ferroAfter = ferroRemoved.ferro ?? (this.doc.ferro ? { ...this.doc.ferro } : void 0);
+    const ferro = mergedFerro?.tiles.size ? { ...ferroAfter ?? {}, [below.id]: mergedFerro } : ferroAfter;
+    const ferroSettingsAfter = ferroRemoved.ferroSettings ?? (this.doc.ferroSettings ? { ...this.doc.ferroSettings } : void 0);
+    const mergedFerroSettings = upper.visible && this.doc.ferroSettings?.[upper.id] ? this.doc.ferroSettings[upper.id] : this.doc.ferroSettings?.[below.id];
+    const ferroSettings = mergedFerro?.tiles.size && mergedFerroSettings ? { ...ferroSettingsAfter ?? {}, [below.id]: mergedFerroSettings } : ferroSettingsAfter;
     const mergedFluor = this.doc.fluor?.[upper.id] || this.doc.fluor?.[below.id] ? mergeFourChannel(toDoc(this.doc.fluor?.[below.id], below), upper.visible ? toDoc(this.doc.fluor?.[upper.id], upper) : void 0) : void 0;
     const fluorAfter = this.fluorWithout([upper.id, below.id]).fluor ?? (this.doc.fluor ? { ...this.doc.fluor } : void 0);
     const fluor = mergedFluor ? { ...fluorAfter ?? {}, [below.id]: mergedFluor } : fluorAfter;
@@ -7362,7 +7976,9 @@ var PaintEditorController = class _PaintEditorController {
         ...this.liveStrokesWithout([upper.id, below.id]),
         ...light ? { light } : {},
         ...fluor ? { fluor } : {},
-        ...thermo ? { thermo } : {}
+        ...thermo ? { thermo } : {},
+        ...ferro !== void 0 ? { ferro } : {},
+        ...ferroSettings !== void 0 ? { ferroSettings } : {}
       })
     );
     return this.describeLayer(merged);
@@ -7387,7 +8003,8 @@ var PaintEditorController = class _PaintEditorController {
           ...this.doc.liveStrokes?.[l.id] ? { liveStrokes: { ...this.doc.liveStrokes, [l.id]: [] } } : {},
           ...this.lightWithout([l.id]),
           ...this.fluorWithout([l.id]),
-          ...this.thermoWithout([l.id])
+          ...this.thermoWithout([l.id]),
+          ...this.ferroWithout([l.id])
         },
         { kind: "clear", layerId: l.id }
       )
@@ -7437,6 +8054,9 @@ var PaintEditorController = class _PaintEditorController {
     const surface = this.applyCoverage(l, coverage, rect, apply);
     const lit = this.doc.light?.[l.id];
     const light = lit ? withLayerLight(this.doc.light, l.id, scaleLight(lit, 1 - opacity)) : void 0;
+    const fer = this.doc.ferro?.[l.id];
+    const ferro = fer ? withLayerFerro(this.doc.ferro, l.id, scaleFerro(fer, 1 - opacity)) : void 0;
+    const ferroSettings = fer ? withLayerFerroSettings(this.doc.ferroSettings, ferro, l.id, this.doc.ferroSettings?.[l.id] ?? null) : void 0;
     const fl = this.doc.fluor?.[l.id];
     const fluor = fl ? withLayerLight(this.doc.fluor, l.id, scaleFluor(fl, 1 - opacity)) : void 0;
     const th = this.doc.thermo?.[l.id];
@@ -7449,7 +8069,8 @@ var PaintEditorController = class _PaintEditorController {
           layers: mapLayer(this.doc.layers, l.id, () => ({ ...l, surface })),
           ...light ? { light } : {},
           ...fluor ? { fluor } : {},
-          ...thermo ? { thermo } : {}
+          ...thermo ? { thermo } : {},
+          ...fer ? { ferro, ferroSettings } : {}
         }),
         { kind: "fill", layerId: l.id, data: { color, opacity, grain: grainAmount, pressure, blend } }
       )
@@ -8625,6 +9246,10 @@ var PaintEditorController = class _PaintEditorController {
     if (brush.thermochromic.hotColor !== null && brush.engine === "sticker") {
       throw new PaintEditorError(`The ${brush.name} brush sprays stickers, which don't take thermochromic ink; paint thermochromic ink with a dab or particle brush (thermo-ink; list_brush_presets lists them), or set thermochromic.hotColor to null (set_brush).`);
     }
+    if (brush.ferro.amount > 0) {
+      if (brush.engine === "sticker") throw new PaintEditorError(`Sticker brushes spray objects and cannot lay ferrofluid (${brush.name}); paint ferrofluid with a dab or particle brush (ferrofluid, ferro-ink; list_brush_presets lists them), or set ferro.amount to 0 (set_brush).`);
+      if (brush.engine === "wet") throw new PaintEditorError(`Wet brushes cannot lay ferrofluid (${brush.name}); paint ferrofluid with a dry or impasto brush (ferrofluid, ferro-ink), or set ferro.amount to 0 (set_brush).`);
+    }
     if (doc.liveStrokes?.[layer.id]) {
       const why = liveStrokeRefusal(brush);
       if (why) throw new PaintEditorError(`Layer "${layer.name}" is a stroke layer. ${why}`);
@@ -8754,6 +9379,8 @@ var PaintEditorController = class _PaintEditorController {
       thick: needThick ? { channels: doc.thick?.[layer.id] ?? emptyThickChannels() } : void 0,
       // Light paint: a twin of the stroke paints the light channel (laying, dimming, moving light).
       light: !wet && brush.engine !== "sticker" && (brush.light.amount > 0 || doc.light?.[layer.id]) ? { surface: doc.light?.[layer.id] ?? emptyLight() } : null,
+      // Ferrofluid paint: a twin of the stroke paints the liquid ferrofluid channel.
+      ferro: !wet && brush.engine !== "sticker" && (brush.ferro.amount > 0 || doc.ferro?.[layer.id]) ? { surface: doc.ferro?.[layer.id] ?? emptyFerro() } : null,
       fluor: brush.engine !== "sticker" && (brush.fluorescence.amount > 0 || doc.fluor?.[layer.id]) ? { surface: doc.fluor?.[layer.id] ?? emptyFluor() } : null,
       thermo: brush.engine !== "sticker" && (brush.thermochromic.hotColor !== null || doc.thermo?.[layer.id]) ? { surface: doc.thermo?.[layer.id] ?? emptyThermo() } : null,
       sticker: brush.engine === "sticker" ? { nextId: this.nextStickerNumber(doc), art: this.stickerArt.get, variant: (ref2) => this.stickerArt.variantFor(ref2, this.colorScheme === "dark") } : void 0,
@@ -8804,6 +9431,9 @@ var PaintEditorController = class _PaintEditorController {
         this.live = { layerId, surface };
         const ch = this.session?.thickChannels();
         this.liveThick = ch ? { layerId, channels: ch } : null;
+        const fc = this.session?.ferroChannel();
+        const fb = this.session?.init.brush.ferro;
+        this.liveFerro = fc ? { layerId, surface: fc, settings: fb && fb.amount > 0 ? fb : this.doc.ferroSettings?.[layerId] ?? DEFAULT_FERRO } : null;
         const fl = this.session?.fluorChannel();
         this.liveFluor = fl ? { layerId, surface: fl } : null;
         const th = this.session?.thermoChannel();
@@ -8826,6 +9456,7 @@ var PaintEditorController = class _PaintEditorController {
         this.live = null;
         this.liveLayers = null;
         this.liveThick = null;
+        this.liveFerro = null;
         this.liveFluor = null;
         this.liveThermo = null;
         const wetStroke = Boolean(s.init.wet);
@@ -8874,6 +9505,9 @@ var PaintEditorController = class _PaintEditorController {
         const stickers = sprayed ? { ...this.doc.stickers ?? {}, [l.id]: [...this.doc.stickers?.[l.id] ?? [], ...sprayed] } : this.doc.stickers;
         const wetLight = wetStroke && this.wet.world?.hasLane(l.id) ? this.wet.world.lightDisplay(l.id) : null;
         const light = withLayerLight(this.doc.light, l.id, s.lightChannel() ?? wetLight);
+        const fc = s.ferroChannel();
+        const ferro = fc ? withLayerFerro(this.doc.ferro, l.id, fc) : this.doc.ferro;
+        const ferroSettings = fc ? withLayerFerroSettings(this.doc.ferroSettings, ferro, l.id, brush.ferro.amount > 0 ? brush.ferro : this.doc.ferroSettings?.[l.id] ?? DEFAULT_FERRO) : this.doc.ferroSettings;
         const fluor = withLayerLight(this.doc.fluor, l.id, s.fluorChannel());
         const thermo = withLayerLight(this.doc.thermo, l.id, s.thermoChannel());
         this.commit(
@@ -8888,7 +9522,9 @@ var PaintEditorController = class _PaintEditorController {
                 ...stickers ? { stickers } : {},
                 ...light ? { light } : {},
                 ...fluor ? { fluor } : {},
-                ...thermo ? { thermo } : {}
+                ...thermo ? { thermo } : {},
+                ...ferro ? { ferro } : { ferro: void 0 },
+                ...ferroSettings ? { ferroSettings } : { ferroSettings: void 0 }
               },
               stroke
             )
@@ -8973,6 +9609,7 @@ var PaintEditorController = class _PaintEditorController {
       this.live = null;
       this.liveLayers = null;
       this.liveThick = null;
+      this.liveFerro = null;
       this.liveFluor = null;
       this.liveThermo = null;
       const masks = s.init.selection ? (s.maskStencils ?? this.guides.stencils).filter((x) => x.enabled && x.mode === "mask") : [];
@@ -8993,6 +9630,7 @@ var PaintEditorController = class _PaintEditorController {
       this.live = null;
       this.liveLayers = null;
       this.liveThick = null;
+      this.liveFerro = null;
       this.liveFluor = null;
       this.liveThermo = null;
       this.emit();
@@ -9037,6 +9675,14 @@ var PaintEditorController = class _PaintEditorController {
         const thick = withLayerThick(out.thick, l.id, ch);
         const sprayed = s.stickers();
         const lit = s.lightChannel() ?? (s.init.wet && this.wet.world?.hasLane(l.id) ? this.wet.world.lightDisplay(l.id) : null);
+        const fc = s.ferroChannel();
+        const nextFerro = fc ? withLayerFerro(out.ferro, l.id, fc) : out.ferro;
+        const nextFerroSettings = fc ? withLayerFerroSettings(
+          out.ferroSettings,
+          nextFerro,
+          l.id,
+          s.init.brush.ferro.amount > 0 ? s.init.brush.ferro : out.ferroSettings?.[l.id] ?? DEFAULT_FERRO
+        ) : out.ferroSettings;
         const fl = s.fluorChannel();
         const th = s.thermoChannel();
         out = withLiveStroke({
@@ -9046,6 +9692,7 @@ var PaintEditorController = class _PaintEditorController {
           ...thick ? { thick } : {},
           ...sprayed ? { stickers: { ...out.stickers ?? {}, [l.id]: [...out.stickers?.[l.id] ?? [], ...sprayed] } } : {},
           ...lit ? { light: withLayerLight(out.light, l.id, lit) } : {},
+          ...fc ? { ferro: nextFerro, ferroSettings: nextFerroSettings } : {},
           ...fl ? { fluor: withLayerLight(out.fluor, l.id, fl) } : {},
           ...th ? { thermo: withLayerLight(out.thermo, l.id, th) } : {}
         }, stroke);
@@ -9440,6 +10087,178 @@ var PaintEditorController = class _PaintEditorController {
     this.commit("Flatten relief", this.withPaintEvent({ ...this.doc, ...t }, { kind: "flatten", layerId: l.id }));
     return { layerId: l.id, flattened: true };
   }
+  // --- Ferrofluid paint and magnets -----------------------------------------------
+  /** The document's `ferro` and `ferroSettings` without these layers. */
+  ferroWithout(ids) {
+    const out = {};
+    const f = this.doc.ferro;
+    if (f && ids.some((id) => f[id])) {
+      const next = { ...f };
+      for (const id of ids) delete next[id];
+      out.ferro = Object.keys(next).length ? next : void 0;
+    }
+    const fs = this.doc.ferroSettings;
+    if (fs && ids.some((id) => fs[id])) {
+      const next = { ...fs };
+      for (const id of ids) delete next[id];
+      out.ferroSettings = Object.keys(next).length ? next : void 0;
+    }
+    return out;
+  }
+  /** Runs deterministic advection on all pixel layers with liquid ferrofluid toward `magnets`. */
+  advectDocumentFerro(doc, magnets, steps = 4) {
+    const f = doc.ferro;
+    if (!f || !magnets.length) return f ? { ...f } : void 0;
+    const out = {};
+    for (const [id, surf] of Object.entries(f)) {
+      const l = findLayer(doc.layers, id)?.layer;
+      if (isPixelLayer(l) && surf.tiles.size > 0) {
+        const next = advectFerro(surf, magnets, l.offset, steps);
+        if (next.tiles.size > 0) out[id] = next;
+      } else if (surf.tiles.size > 0) {
+        out[id] = surf;
+      }
+    }
+    return Object.keys(out).length ? out : void 0;
+  }
+  /** Lists the magnets on the canvas. */
+  listMagnets() {
+    return (this.doc.magnets ?? []).map((m) => ({ ...m }));
+  }
+  /** Places a dipole magnet on the canvas and advects liquid ferrofluid toward it (one undo step). */
+  addMagnet(input) {
+    this.requireIdle("adding a magnet");
+    const existing = this.doc.magnets ?? [];
+    const usedIds = new Set(existing.map((m) => m.id));
+    while (usedIds.has(`mag${this.nextMagnetId}`)) this.nextMagnetId++;
+    const id = `mag${this.nextMagnetId++}`;
+    let magnet;
+    try {
+      magnet = normalizeMagnet({ id, x: input.x, y: input.y, strength: input.strength, radius: input.radius });
+    } catch (e) {
+      throw new PaintEditorError(e.message);
+    }
+    const magnets = [...existing, magnet];
+    const ferro = this.advectDocumentFerro(this.doc, magnets, 4);
+    const nextDoc = this.withPaintEvent(
+      { ...this.doc, magnets, ...this.doc.ferro ? { ferro } : {} },
+      { kind: "magnets", layerId: "", data: { magnets: magnets.map((m) => ({ ...m })), advect: true } }
+    );
+    this.commit("Add magnet", nextDoc);
+    return { ...magnet };
+  }
+  /** Moves or retunes a magnet and advects liquid ferrofluid toward the magnets (one undo step). */
+  updateMagnet(id, update, commitToHistory = true) {
+    this.requireIdle("updating a magnet");
+    if (update.x === void 0 && update.y === void 0 && update.strength === void 0 && update.radius === void 0) {
+      throw new PaintEditorError("Pass at least one change: x, y, strength or radius.");
+    }
+    const existing = this.doc.magnets ?? [];
+    const idx = existing.findIndex((m) => m.id === id);
+    if (idx < 0) throw new PaintEditorError(`Unknown magnet "${id}". Call list_magnets for the ids.`);
+    const current = existing[idx];
+    let magnet;
+    try {
+      magnet = normalizeMagnet(
+        {
+          id,
+          x: update.x ?? current.x,
+          y: update.y ?? current.y,
+          strength: update.strength ?? current.strength,
+          radius: update.radius ?? current.radius
+        },
+        current
+      );
+    } catch (e) {
+      throw new PaintEditorError(e.message);
+    }
+    const magnets = existing.map((m, i) => i === idx ? magnet : m);
+    const last = this.undoStack[this.undoStack.length - 1];
+    const amending = !commitToHistory && Boolean(last && last.label === "Update magnet" && !last.wet && !this.wetOp && !this.grouping);
+    const baseDoc = amending && last ? last.before : this.doc;
+    const ferro = this.advectDocumentFerro(baseDoc, magnets, 4);
+    const nextDoc = this.withPaintEvent(
+      { ...this.doc, paintEvents: baseDoc.paintEvents, magnets, ...baseDoc.ferro ? { ferro } : {} },
+      { kind: "magnets", layerId: "", data: { magnets: magnets.map((m) => ({ ...m })), advect: true } }
+    );
+    this.commitOrAmend("Update magnet", nextDoc, commitToHistory);
+    return { ...magnet };
+  }
+  /** Removes magnets by id, or all magnets when `ids` is omitted or empty (one undo step). Returns the removed ids. */
+  removeMagnets(ids) {
+    this.requireIdle("removing magnets");
+    const existing = this.doc.magnets ?? [];
+    if (ids?.length) {
+      for (const id of ids) {
+        if (!existing.some((m) => m.id === id)) throw new PaintEditorError(`Unknown magnet "${id}". Call list_magnets for the ids.`);
+      }
+    }
+    const removed = ids?.length ? [...ids] : existing.map((m) => m.id);
+    if (!removed.length) return [];
+    const next = existing.filter((m) => !removed.includes(m.id));
+    const nextDoc = this.withPaintEvent(
+      { ...this.doc, magnets: next.length ? next : void 0 },
+      { kind: "magnets", layerId: "", data: { magnets: next.map((m) => ({ ...m })), advect: false } }
+    );
+    this.commit("Remove magnets", nextDoc);
+    return removed;
+  }
+  /** Replaces the canvas magnets (used by replay). */
+  replaceMagnets(magnets, advect = false) {
+    const next = magnets.map((m) => normalizeMagnet(m));
+    const ferro = advect ? this.advectDocumentFerro(this.doc, next, 4) : this.doc.ferro;
+    this.commit("Magnets", { ...this.doc, magnets: next.length ? next : void 0, ...this.doc.ferro ? { ferro } : {} });
+  }
+  /** Reads a layer's liquid ferrofluid coverage and active Rosensweig spike relief under the canvas magnets. */
+  getFerrofluid(layerId) {
+    const l = this.wetLayer(layerId, "read the ferrofluid of");
+    const settings = this.doc.ferroSettings?.[l.id] ?? DEFAULT_FERRO;
+    const magnets = this.doc.magnets ?? [];
+    const info = ferroInfo(this.doc.ferro?.[l.id], magnets, settings, l.offset);
+    const bounds = info.bounds ? { ...info.bounds, x: info.bounds.x + l.offset.x, y: info.bounds.y + l.offset.y } : null;
+    return {
+      layerId: l.id,
+      ferro: info.peak > 0,
+      bounds,
+      peak: info.peak,
+      coverage: info.liquidPixels,
+      activeSpikeArea: info.spikePixels,
+      maxSpikeHeight: info.maxSpikeHeight,
+      magnetCount: info.magnetCount,
+      wavelength: settings.wavelength,
+      threshold: settings.threshold
+    };
+  }
+  /** Cures a layer's liquid ferrofluid: bakes the current Rosensweig spikes and glossy metallic material into `doc.thick` and clears `doc.ferro` (one undo step). */
+  cureFerrofluid(layerId) {
+    this.requireIdle("curing ferrofluid");
+    const l = this.paintTarget(layerId, "cure the ferrofluid of");
+    const fSurf = this.doc.ferro?.[l.id];
+    if (!fSurf || !fSurf.tiles.size) {
+      return { layerId: l.id, cured: false, bounds: null, maxSpikeHeight: 0, activeSpikeArea: 0 };
+    }
+    const settings = this.doc.ferroSettings?.[l.id] ?? DEFAULT_FERRO;
+    const magnets = this.doc.magnets ?? [];
+    const fb = ferroInfo(fSurf, magnets, settings, l.offset).bounds;
+    const bounds = fb ? { ...fb, x: fb.x + l.offset.x, y: fb.y + l.offset.y } : null;
+    const baked = bakeFerroIntoThick(l.surface, fSurf, this.doc.thick?.[l.id], magnets, settings, l.offset);
+    const removed = this.ferroWithout([l.id]);
+    const nextDoc = {
+      ...this.doc,
+      layers: mapLayer(this.doc.layers, l.id, () => ({ ...l, surface: baked.color })),
+      thick: { ...this.doc.thick ?? {}, [l.id]: baked.thick },
+      ferro: removed.ferro,
+      ferroSettings: removed.ferroSettings
+    };
+    this.commit("Cure ferrofluid", this.withPaintEvent(nextDoc, { kind: "cure-ferrofluid", layerId: l.id }));
+    return {
+      layerId: l.id,
+      cured: true,
+      bounds,
+      maxSpikeHeight: baked.maxSpikeHeight,
+      activeSpikeArea: baked.spikePixels
+    };
+  }
   // --- Replay: time-lapse and high-resolution export ------------------------------
   /**
    * A fresh, headless editor for replaying this painting at `scale` (canvas, dpi and paper grain
@@ -9942,20 +10761,33 @@ var PaintEditorController = class _PaintEditorController {
     };
     return visit(layers);
   }
-  /** The layers with thick paint lit (each thick layer's pixels replaced by its lit tiles). */
+  /** The layers with thick paint and ferrofluid spikes lit (each thick or ferrofluid layer's pixels replaced by its lit tiles). */
   litLayers(layers) {
     const thick = this.doc.thick;
     const live = this.liveThick;
-    if (!thick && !live) return layers;
+    const ferro = this.doc.ferro;
+    const liveFerro = this.liveFerro;
+    if (!thick && !live && !ferro && !liveFerro) return layers;
     let out = layers;
-    const ids = /* @__PURE__ */ new Set([...Object.keys(thick ?? {}), ...live ? [live.layerId] : []]);
+    const ids = /* @__PURE__ */ new Set([
+      ...Object.keys(thick ?? {}),
+      ...live ? [live.layerId] : [],
+      ...Object.keys(ferro ?? {}),
+      ...liveFerro ? [liveFerro.layerId] : []
+    ]);
+    const magnets = this.doc.magnets ?? [];
     for (const id of ids) {
-      const ch = live?.layerId === id ? live.channels : thick?.[id];
-      const l = ch && findLayer(out, id)?.layer;
-      if (!ch || !isPixelLayer(l)) continue;
+      const l = findLayer(out, id)?.layer;
+      if (!isPixelLayer(l)) continue;
+      const ch = (live?.layerId === id ? live.channels : thick?.[id]) ?? emptyThickChannels();
+      const fSurf = liveFerro?.layerId === id ? liveFerro.surface : ferro?.[id];
+      const fSet = (liveFerro?.layerId === id ? liveFerro.settings : this.doc.ferroSettings?.[id]) ?? DEFAULT_FERRO;
+      const hasThick = ch.height.tiles.size > 0 || ch.material.tiles.size > 0 || ch.film.tiles.size > 0;
+      const hasFerro = Boolean(fSurf && fSurf.tiles.size > 0);
+      if (!hasThick && !hasFerro) continue;
       let cache = this.litCaches.get(id);
       if (!cache) this.litCaches.set(id, cache = new LitCache());
-      const lit = cache.lit(l.surface, ch, this.lighting, this.viewTilt);
+      const lit = cache.lit(l.surface, ch, this.lighting, this.viewTilt, hasFerro ? { surface: fSurf, magnets, settings: fSet, offset: l.offset } : null);
       if (lit !== l.surface) out = mapLayer(out, id, () => ({ ...l, surface: lit }));
     }
     return out;
@@ -10044,13 +10876,13 @@ var PaintEditorController = class _PaintEditorController {
   }
   /** The canvas (or some layers), scaled so the longest side is at most `maxSide`. */
   renderPreview(options = {}) {
-    const full2 = this.compositePixels({ ...options, wet: options.wet ?? "display" });
+    const full3 = this.compositePixels({ ...options, wet: options.wet ?? "display" });
     const side = Math.max(1, Math.round(options.maxSide ?? 512));
-    const k = Math.min(1, side / Math.max(full2.width, full2.height));
-    if (k >= 1) return full2;
-    const w = Math.max(1, Math.round(full2.width * k));
-    const h = Math.max(1, Math.round(full2.height * k));
-    return { width: w, height: h, data: downsampleRgba(full2.data, full2.width, full2.height, w, h) };
+    const k = Math.min(1, side / Math.max(full3.width, full3.height));
+    if (k >= 1) return full3;
+    const w = Math.max(1, Math.round(full3.width * k));
+    const h = Math.max(1, Math.round(full3.height * k));
+    return { width: w, height: h, data: downsampleRgba(full3.data, full3.width, full3.height, w, h) };
   }
   // --- Save, load and export -------------------------------------------------------
   /** The document as JSON with inline PNG assets. */
@@ -10166,6 +10998,16 @@ var PaintEditorController = class _PaintEditorController {
     const spills = Object.fromEntries(Object.entries(this.lightSpills).filter(([id]) => findLayer(this.doc.layers, id)));
     if (Object.keys(spills).length) ext.lightSpill = spills;
     else delete ext.lightSpill;
+    const ferro = {};
+    for (const [id, f] of Object.entries(this.doc.ferro ?? {})) {
+      if (!findLayer(this.doc.layers, id)) continue;
+      const saved = ferroToJSON(f, this.doc.ferroSettings?.[id]);
+      if (saved) ferro[id] = saved;
+    }
+    if (Object.keys(ferro).length) ext.ferro = ferro;
+    else delete ext.ferro;
+    if (this.doc.magnets?.length) ext.magnets = this.doc.magnets.map((m) => ({ ...m }));
+    else delete ext.magnets;
     const effectLayers = effectLayersToJSON(this.doc.effectLayers ?? {}, (id) => isPixelLayer(findLayer(this.doc.layers, id)?.layer));
     if (effectLayers) ext.effectLayers = effectLayers;
     else delete ext.effectLayers;
@@ -10303,6 +11145,25 @@ var PaintEditorController = class _PaintEditorController {
       if (heat) state = { ...state, heat };
       else problems.push("The heat field could not be read; the canvas loads cool.");
     }
+    if (ext.ferro && typeof ext.ferro === "object") {
+      const ferro = {};
+      const ferroSettings = {};
+      for (const [id, v] of Object.entries(ext.ferro)) {
+        if (!isPixelLayer(findLayer(state.layers, id)?.layer)) continue;
+        try {
+          const loaded = ferroFromJSON(v);
+          ferro[id] = loaded.surface;
+          ferroSettings[id] = loaded.settings;
+        } catch (e) {
+          problems.push(`The ferrofluid of layer "${id}" could not be read (${e.message}); it loads without ferrofluid.`);
+        }
+      }
+      if (Object.keys(ferro).length) state = { ...state, ferro, ferroSettings };
+    }
+    if (ext.magnets !== void 0) {
+      const magnets = magnetsFromJSON(ext.magnets);
+      if (magnets.length) state = { ...state, magnets };
+    }
     const raw = ext.layerChannels;
     if (!raw || typeof raw !== "object") return state;
     const thick = {};
@@ -10337,6 +11198,11 @@ var PaintEditorController = class _PaintEditorController {
     this.redoStack = [];
     this.resetMutations();
     this.doc = this.readThick(loaded.state, loaded.extensions, loaded.problems);
+    this.nextMagnetId = 1;
+    for (const m of this.doc.magnets ?? []) {
+      const n = Number(/^mag(\d+)$/.exec(m.id)?.[1] ?? 0);
+      if (n >= this.nextMagnetId) this.nextMagnetId = n + 1;
+    }
     for (const list of Object.values(this.doc.liveStrokes ?? {})) {
       for (const s of list) {
         const n = Number(/^s(\d+)$/.exec(s.id)?.[1] ?? 0);
@@ -10347,6 +11213,8 @@ var PaintEditorController = class _PaintEditorController {
     delete this.extensions.layerChannels;
     delete this.extensions.light;
     delete this.extensions.lightSpill;
+    delete this.extensions.ferro;
+    delete this.extensions.magnets;
     delete this.extensions.lighting;
     delete this.extensions.stickers;
     delete this.extensions.liveStrokes;
@@ -10387,13 +11255,13 @@ var PaintEditorController = class _PaintEditorController {
     return encodePng(img.width, img.height, img.data);
   }
   scaled(options) {
-    const full2 = this.compositePixels(options);
+    const full3 = this.compositePixels(options);
     const s = options.scale ?? 1;
     if (!(s > 0 && s <= 1)) throw new PaintEditorError(`scale ${s} is out of range; use above 0 up to 1 (exports never upscale pixels).`);
-    if (s === 1) return full2;
-    const w = Math.max(1, Math.round(full2.width * s));
-    const h = Math.max(1, Math.round(full2.height * s));
-    return { width: w, height: h, data: downsampleRgba(full2.data, full2.width, full2.height, w, h) };
+    if (s === 1) return full3;
+    const w = Math.max(1, Math.round(full3.width * s));
+    const h = Math.max(1, Math.round(full3.height * s));
+    return { width: w, height: h, data: downsampleRgba(full3.data, full3.width, full3.height, w, h) };
   }
   /**
    * The canvas as PNG, JPEG or WebP bytes. JPEG has no alpha, so it always includes the paper.
@@ -11596,11 +12464,11 @@ var PaintEditorController = class _PaintEditorController {
       width,
       height
     ) ?? { x: 0, y: 0, width, height };
-    const full2 = this.compositePixels({ wet: "display" });
+    const full3 = this.compositePixels({ wet: "display" });
     const cropData = new Uint8ClampedArray(cropRect.width * cropRect.height * 4);
     for (let y = 0; y < cropRect.height; y++) {
       const srcRow = ((cropRect.y + y) * width + cropRect.x) * 4;
-      cropData.set(full2.data.subarray(srcRow, srcRow + cropRect.width * 4), y * cropRect.width * 4);
+      cropData.set(full3.data.subarray(srcRow, srcRow + cropRect.width * 4), y * cropRect.width * 4);
     }
     const cropPngBase64 = bytesToBase64(encodePng(cropRect.width, cropRect.height, cropData));
     const preview = this.renderPreview({ wet: "display", maxSide: options.maxSide ?? 512 });
@@ -12231,6 +13099,19 @@ function withLayerThick(thick, layerId, next) {
   else delete out[layerId];
   return out;
 }
+function withLayerFerro(ferro, layerId, next) {
+  if (!next) return ferro ? { ...ferro } : void 0;
+  const out = { ...ferro ?? {} };
+  if (next.tiles.size) out[layerId] = next;
+  else delete out[layerId];
+  return Object.keys(out).length ? out : void 0;
+}
+function withLayerFerroSettings(settings, ferro, layerId, next) {
+  const out = { ...settings ?? {} };
+  if (next && ferro?.[layerId]?.tiles.size) out[layerId] = { amount: next.amount, wavelength: next.wavelength, threshold: next.threshold };
+  else if (!ferro?.[layerId]?.tiles.size) delete out[layerId];
+  return Object.keys(out).length ? out : void 0;
+}
 var BACKLIGHT_LAYER_ID = "__backlight";
 function insertAfter(layers, id, node) {
   const i = layers.findIndex((l) => l.id === id);
@@ -12272,6 +13153,7 @@ function shiftDocument(doc, dx, dy) {
   for (const l of flattenLayers(doc.layers)) if (l.type === "pixel") layers = mapLayer(layers, l.id, () => ({ ...l, offset: movePoint(l.offset, dx, dy) }));
   const m = [1, 0, 0, 1, dx, dy];
   const moveStickers = (list) => list.map((s) => ({ ...s, x: Math.round((s.x + dx) * 100) / 100, y: Math.round((s.y + dy) * 100) / 100 }));
+  const moveMagnets = (list) => list.map((mag) => ({ ...mag, x: Math.round((mag.x + dx) * 100) / 100, y: Math.round((mag.y + dy) * 100) / 100 }));
   const out = {
     ...doc,
     layers,
@@ -12287,11 +13169,14 @@ function shiftDocument(doc, dx, dy) {
     return s.stencils ? { ...moved, stencils: s.stencils.map((x) => translateStencil(x, dx, dy)) } : moved;
   };
   if (doc.stickers) out.stickers = Object.fromEntries(Object.entries(doc.stickers).map(([id, list]) => [id, moveStickers(list)]));
+  if (doc.magnets) out.magnets = moveMagnets(doc.magnets);
   if (doc.liveStrokes) out.liveStrokes = Object.fromEntries(Object.entries(doc.liveStrokes).map(([id, list]) => [id, list.map(moveStroke)]));
   if (doc.paintEvents) {
     out.paintEvents = doc.paintEvents.map((e) => {
       const list = e.kind === "stickers" ? e.data?.stickers : void 0;
       if (list) return { ...e, data: { ...e.data, stickers: moveStickers(list) } };
+      const magnets = e.kind === "magnets" ? e.data?.magnets : void 0;
+      if (magnets) return { ...e, data: { ...e.data, magnets: moveMagnets(magnets) } };
       const strokes = e.kind === "live-strokes" ? e.data?.strokes : void 0;
       if (strokes) return { ...e, data: { ...e.data, strokes: strokes.map(moveStroke) } };
       if (e.kind === "fill-region" && e.data) {
@@ -12647,7 +13532,7 @@ function unionRect2(a, b) {
 
 // src/paint-editor/playback.ts
 var WET = /^(advance_wet_paint|dry_paint|wet_paper|set_wet_settings|set_flow_map|set_canvas_tilt|pause_wet_paint|set_wet_engine|set_water_overlay)$/;
-var PAPER = /^(set_paper|set_lighting|flatten_relief|set_instant_dry)$/;
+var PAPER = /^(set_paper|set_lighting|flatten_relief|set_instant_dry|add_magnet|update_magnet|remove_magnets|cure_ferrofluid)$/;
 var LAYERS = /^(add_layer|update_layer|set_active_layer|remove_layer|duplicate_layer|move_layer|merge_layer_down|clear_layer|update_sticker|arrange_stickers|remove_stickers)$/;
 var PAD = /^(mixing_pad_stroke|pick_mixing_pad_color|clear_mixing_pad|mix_on_pad|save_mixing_pad|load_mixing_pad|remove_mixing_pad|mix_colors)$/;
 var COLOR = /^(set_color|set_paint|color_harmony|add_swatch|remove_swatch|load_mixer_brush|clean_mixer_brush)$/;
@@ -13838,8 +14723,111 @@ function createPaintThickTools(c) {
   ];
 }
 
-// src/paint-editor/replay-tools.ts
+// src/paint-editor/ferro-tools.ts
 var READ5 = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+var SET4 = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+var WRITE5 = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
+var EMPTY3 = { type: "object", properties: {}, additionalProperties: false };
+var LAYER_ID4 = { type: "string", description: "Pixel layer id from list_layers (default the active layer)." };
+function createFerroTools(c) {
+  return [
+    {
+      name: "add_magnet",
+      title: "Place a magnet",
+      description: "Places a dipole magnet on the canvas at (x, y) in document pixels. Liquid ferrofluid on every layer gathers toward the magnet (deterministic advection steps) and rises into hexagonal Rosensweig relief spikes along the magnetic field lines wherever |B| exceeds the layer\u2019s threshold, shaded live by set_lighting. One undo step. Returns the magnet (id, x, y, strength, radius).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          x: { type: "number", description: "Magnet centre x in document pixels." },
+          y: { type: "number", description: "Magnet centre y in document pixels." },
+          strength: { type: "number", minimum: -1, maximum: 1, description: "Dipole strength -1..1 (default 0.8; negative flips the pole)." },
+          radius: { type: "number", minimum: 4, maximum: 2048, description: "Dipole falloff radius in pixels (default 80)." }
+        },
+        required: ["x", "y"],
+        additionalProperties: false
+      },
+      annotations: { title: "Place a magnet", ...WRITE5 },
+      coordinates: { in: [""], out: [""] },
+      handler: (a) => c.addMagnet(a)
+    },
+    {
+      name: "update_magnet",
+      title: "Move or tune a magnet",
+      description: "Moves a magnet or changes its dipole strength (-1..1) or falloff radius (4..2048 px) by id from list_magnets. Liquid ferrofluid gathers toward the updated field and the lit relief spikes update at once. One undo step. Returns the updated magnet.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "Magnet id from list_magnets." },
+          x: { type: "number", description: "Magnet centre x in document pixels." },
+          y: { type: "number", description: "Magnet centre y in document pixels." },
+          strength: { type: "number", minimum: -1, maximum: 1, description: "Dipole strength -1..1." },
+          radius: { type: "number", minimum: 4, maximum: 2048, description: "Dipole falloff radius in pixels (4..2048)." }
+        },
+        required: ["id"],
+        additionalProperties: false
+      },
+      annotations: { title: "Move or tune a magnet", ...SET4 },
+      coordinates: { in: [""], out: [""] },
+      handler: ({ id, ...u }) => c.updateMagnet(id, u)
+    },
+    {
+      name: "remove_magnets",
+      title: "Remove magnets",
+      description: "Removes magnets by id from list_magnets, or every magnet on the canvas when ids is omitted or empty. Uncured ferrofluid relaxes as the field changes; cured relief stays. One undo step. Returns the removed magnet ids.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          ids: {
+            type: "array",
+            items: { type: "string", description: "Magnet id from list_magnets." },
+            description: "Magnet ids to remove (default: remove all magnets)."
+          }
+        },
+        additionalProperties: false
+      },
+      annotations: { title: "Remove magnets", ...WRITE5 },
+      handler: ({ ids }) => ({ removed: c.removeMagnets(ids) })
+    },
+    {
+      name: "list_magnets",
+      title: "List magnets",
+      description: "Lists the magnets placed on the canvas in order: id, x, y (document pixels), strength (-1..1) and radius (px). Changes nothing.",
+      inputSchema: EMPTY3,
+      annotations: { title: "List magnets", ...READ5 },
+      coordinates: { out: ["magnets[]"] },
+      handler: () => ({ magnets: c.listMagnets() })
+    },
+    {
+      name: "get_ferrofluid",
+      title: "Read a layer\u2019s ferrofluid and spikes",
+      description: "Reads a layer\u2019s liquid ferrofluid (laid by brushes with ferro.amount above 0, such as ferrofluid and ferro-ink) and its live Rosensweig spikes under the current magnets: whether it has any (ferro), its bounds in document pixels, peak liquid level (0..255), liquid coverage in pixels, activeSpikeArea (pixels currently raised into spikes), maxSpikeHeight (0..255), magnetCount, and the layer\u2019s capillary wavelength and threshold. Changes nothing.",
+      inputSchema: {
+        type: "object",
+        properties: { layerId: LAYER_ID4 },
+        additionalProperties: false
+      },
+      annotations: { title: "Read a layer\u2019s ferrofluid and spikes", ...READ5 },
+      coordinates: { out: ["bounds"] },
+      handler: ({ layerId }) => c.getFerrofluid(layerId)
+    },
+    {
+      name: "cure_ferrofluid",
+      title: "Cure ferrofluid into solid relief",
+      description: "Cures a layer\u2019s liquid ferrofluid: bakes its current magnetic Rosensweig spikes into the layer\u2019s solid impasto height and dark glossy metallic material, and clears the liquid ferrofluid channel so moving or removing magnets no longer changes this layer. One undo step. Returns the layer id, whether anything was cured, the cured bounds, maxSpikeHeight and activeSpikeArea.",
+      inputSchema: {
+        type: "object",
+        properties: { layerId: LAYER_ID4 },
+        additionalProperties: false
+      },
+      annotations: { title: "Cure ferrofluid into solid relief", ...WRITE5 },
+      coordinates: { out: ["bounds"] },
+      handler: ({ layerId }) => c.cureFerrofluid(layerId)
+    }
+  ];
+}
+
+// src/paint-editor/replay-tools.ts
+var READ6 = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 function createPaintReplayTools(c) {
   return [
     {
@@ -13858,7 +14846,7 @@ function createPaintReplayTools(c) {
         },
         additionalProperties: false
       },
-      annotations: { title: "Export a time-lapse", ...READ5 },
+      annotations: { title: "Export a time-lapse", ...READ6 },
       handler: async (a) => {
         await c.wetIdle();
         const tl = await c.timeLapse({ frames: a.frames, fps: a.fps, maxSide: a.maxSide, wetStepsPerFrame: a.wetStepsPerFrame, holdMs: a.holdMs });
@@ -13890,7 +14878,7 @@ function createPaintReplayTools(c) {
         required: ["scale"],
         additionalProperties: false
       },
-      annotations: { title: "Export at a higher resolution", ...READ5 },
+      annotations: { title: "Export at a higher resolution", ...READ6 },
       handler: async ({ scale, paper }) => {
         await c.wetIdle();
         const img = await c.renderHighRes({ scale, paper });
@@ -13902,9 +14890,9 @@ function createPaintReplayTools(c) {
 }
 
 // src/paint-editor/mutation-tools.ts
-var READ6 = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
-var WRITE5 = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
-var SET4 = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+var READ7 = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+var WRITE6 = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
+var SET5 = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 var POINTS = {
   type: "array",
   minItems: 1,
@@ -13943,7 +14931,7 @@ function createMutationTools(c, options = {}) {
         },
         additionalProperties: false
       },
-      annotations: { title: "List pending mutations", ...READ6 },
+      annotations: { title: "List pending mutations", ...READ7 },
       coordinates: { out: ["mutations[].bounds"] },
       handler: (a) => ({ mutations: c.listMutations({ includeAll: Boolean(a.includeAll) }) })
     },
@@ -13974,7 +14962,7 @@ function createMutationTools(c, options = {}) {
         required: ["id"],
         additionalProperties: false
       },
-      annotations: { title: "Read and claim a mutation", ...WRITE5 },
+      annotations: { title: "Read and claim a mutation", ...WRITE6 },
       coordinates: { out: ["bounds", "strokes[].bounds", "strokes[].points[]", "cropPng.rect"] },
       handler: (a) => c.readMutation(a.id, {
         actor: options.actor?.id,
@@ -14051,7 +15039,7 @@ function createMutationTools(c, options = {}) {
         required: ["id", "strokes"],
         additionalProperties: false
       },
-      annotations: { title: "Answer a mutation with strokes", ...WRITE5 },
+      annotations: { title: "Answer a mutation with strokes", ...WRITE6 },
       coordinates: { in: ["strokes[].points[]"], out: ["bounds"] },
       handler: async (a) => {
         await c.wetIdle();
@@ -14105,7 +15093,7 @@ function createMutationTools(c, options = {}) {
         required: ["id"],
         additionalProperties: false
       },
-      annotations: { title: "Decline a mutation", ...SET4 },
+      annotations: { title: "Decline a mutation", ...SET5 },
       coordinates: { out: ["bounds"] },
       handler: (a) => c.declineMutation(a.id, a.reason)
     }
@@ -14113,8 +15101,8 @@ function createMutationTools(c, options = {}) {
 }
 
 // src/paint-editor/evolution-tools.ts
-var READ7 = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
-var WRITE6 = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
+var READ8 = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+var WRITE7 = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
 var UNIT2 = (description) => ({ type: "number", minimum: 0, maximum: 1, description });
 var EVOLUTION_MUTATION_SCHEMA = {
   type: "object",
@@ -14159,7 +15147,7 @@ function createPaintEvolutionTools(c) {
         required: ["strokeIds"],
         additionalProperties: false
       },
-      annotations: { title: "Breed stroke variants", ...WRITE6 },
+      annotations: { title: "Breed stroke variants", ...WRITE7 },
       coordinates: { out: ["proposals[].bounds"] },
       handler: ({ strokeIds, count, mutation, seed }, context) => {
         const actor = context?.actor?.id;
@@ -14202,7 +15190,7 @@ function createPaintEvolutionTools(c) {
         required: ["proposalIds"],
         additionalProperties: false
       },
-      annotations: { title: "Breed from paint proposals", ...WRITE6 },
+      annotations: { title: "Breed from paint proposals", ...WRITE7 },
       coordinates: { out: ["proposals[].bounds"] },
       handler: ({ proposalIds, count, mutation, seed }, context) => {
         const actor = context?.actor?.id;
@@ -14230,7 +15218,7 @@ function createPaintEvolutionTools(c) {
         required: ["proposalId"],
         additionalProperties: false
       },
-      annotations: { title: "Get a proposal\u2019s stroke genome", ...READ7 },
+      annotations: { title: "Get a proposal\u2019s stroke genome", ...READ8 },
       coordinates: { out: ["bounds", "strokes[].points[]"] },
       handler: ({ proposalId }) => c.getProposalGenome(proposalId)
     }
@@ -14249,13 +15237,13 @@ function createPaintEvolutionToolProvider(controller, options = {}) {
 }
 
 // src/paint-editor/tools.ts
-var READ8 = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
-var WRITE7 = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
-var SET5 = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+var READ9 = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+var WRITE8 = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
+var SET6 = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 var DESTRUCTIVE3 = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false };
-var EMPTY3 = { type: "object", properties: {}, additionalProperties: false };
+var EMPTY4 = { type: "object", properties: {}, additionalProperties: false };
 var COLOR3 = { type: "string", pattern: "^#[0-9a-fA-F]{6}$", description: 'Colour #rrggbb, e.g. "#2a4b8d".' };
-var LAYER_ID4 = { type: "string", description: "Layer id from list_layers (default the active layer)." };
+var LAYER_ID5 = { type: "string", description: "Layer id from list_layers (default the active layer)." };
 var TIME = { type: "number", minimum: 0, description: "Draw live effect paint (strokes on stroke layers painted with live effect paint) this many ms into its animation (default: as painted, its own time)." };
 var POINTS2 = {
   type: "array",
@@ -14298,8 +15286,8 @@ function createPaintEditorToolProvider(controller, options = {}) {
     name: "get_canvas_info",
     title: "Get the canvas",
     description: "Reads the canvas: size in pixels and dpi, its origin (where (0, 0) is relative to the canvas it was extended from), bounds (the rectangle the painting covers, in the coordinates every other tool takes), 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: EMPTY3,
-    annotations: { title: "Get the canvas", ...READ8 },
+    inputSchema: EMPTY4,
+    annotations: { title: "Get the canvas", ...READ9 },
     coordinates: { out: ["bounds"] },
     handler: () => {
       const s = c.getState();
@@ -14360,7 +15348,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       },
       additionalProperties: false
     },
-    annotations: { title: "Resize the canvas", ...SET5 },
+    annotations: { title: "Resize the canvas", ...SET6 },
     handler: (a) => c.setCanvas({ width: a.width, height: a.height, dpi: a.dpi })
   });
   const EXTEND_SIDE = (side) => ({ type: "integer", minimum: 0, maximum: MAX_CANVAS_SIDE - 1, description: `Pixels to add on the ${side} (default 0).` });
@@ -14373,15 +15361,15 @@ function createPaintEditorToolProvider(controller, options = {}) {
       properties: { left: EXTEND_SIDE("left"), top: EXTEND_SIDE("top"), right: EXTEND_SIDE("right"), bottom: EXTEND_SIDE("bottom") },
       additionalProperties: false
     },
-    annotations: { title: "Extend the canvas", ...WRITE7 },
+    annotations: { title: "Extend the canvas", ...WRITE8 },
     handler: (a) => c.extendCanvas({ left: a.left, top: a.top, right: a.right, bottom: a.bottom })
   });
   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: EMPTY3,
-    annotations: { title: "List papers", ...READ8 },
+    inputSchema: EMPTY4,
+    annotations: { title: "List papers", ...READ9 },
     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],
@@ -14392,8 +15380,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, and metallic, backlight and backlightColor when set).",
-    inputSchema: EMPTY3,
-    annotations: { title: "Get the paper", ...READ8 },
+    inputSchema: EMPTY4,
+    annotations: { title: "Get the paper", ...READ9 },
     handler: () => JSON.parse(JSON.stringify(c.document.paper))
   });
   const tuning = {
@@ -14431,15 +15419,15 @@ function createPaintEditorToolProvider(controller, options = {}) {
       },
       additionalProperties: false
     },
-    annotations: { title: "Set the paper", ...SET5 },
+    annotations: { title: "Set the paper", ...SET6 },
     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: EMPTY3,
-    annotations: { title: "List layers", ...READ8 },
+    inputSchema: EMPTY4,
+    annotations: { title: "List layers", ...READ9 },
     coordinates: { out: ["layers[].bounds"] },
     handler: () => ({ layers: c.listLayers(), activeLayerId: c.document.activeLayerId })
   });
@@ -14457,7 +15445,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       },
       additionalProperties: false
     },
-    annotations: { title: "Add a layer", ...WRITE7 },
+    annotations: { title: "Add a layer", ...WRITE8 },
     coordinates: { out: ["bounds"] },
     handler: (a) => c.addLayer({ name: a.name, type: a.type, aboveId: a.aboveId, parentId: a.parentId })
   });
@@ -14493,7 +15481,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       required: ["layerId"],
       additionalProperties: false
     },
-    annotations: { title: "Change a layer", ...SET5 },
+    annotations: { title: "Change a layer", ...SET6 },
     coordinates: { out: ["bounds"] },
     handler: ({ layerId, ...u }) => c.updateLayer(layerId, u)
   });
@@ -14501,8 +15489,8 @@ function createPaintEditorToolProvider(controller, options = {}) {
     name: "list_blend_modes",
     title: "List blend modes",
     description: "Lists every layer and brush blend mode: id, label, group (standard Photoshop modes, pigment, or painterly), what the pigment and painterly modes do, and the standard mode PSD export writes in their place. Changes nothing. Read it before choosing a painterly mode for update_layer or a brush tip.",
-    inputSchema: EMPTY3,
-    annotations: { title: "List blend modes", ...READ8 },
+    inputSchema: EMPTY4,
+    annotations: { title: "List blend modes", ...READ9 },
     handler: () => ({
       modes: BLEND_MODES.map((m) => ({
         id: m.id,
@@ -14518,7 +15506,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", ...SET5 },
+    annotations: { title: "Choose the active layer", ...SET6 },
     coordinates: { out: ["bounds"] },
     handler: ({ layerId }) => {
       c.setActiveLayer(layerId);
@@ -14538,7 +15526,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", ...WRITE7 },
+    annotations: { title: "Duplicate a layer", ...WRITE8 },
     coordinates: { out: ["bounds"] },
     handler: ({ layerId }) => c.duplicateLayer(layerId)
   });
@@ -14556,7 +15544,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       required: ["layerId", "index"],
       additionalProperties: false
     },
-    annotations: { title: "Reorder a layer", ...WRITE7 },
+    annotations: { title: "Reorder a layer", ...WRITE8 },
     coordinates: { out: ["bounds"] },
     handler: ({ layerId, index, parentId }) => c.moveLayer(layerId, index, parentId)
   });
@@ -14576,7 +15564,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     inputSchema: {
       type: "object",
       properties: {
-        layerId: LAYER_ID4,
+        layerId: LAYER_ID5,
         color: { ...COLOR3, 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)." },
@@ -14585,7 +15573,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       },
       additionalProperties: false
     },
-    annotations: { title: "Fill a layer", ...WRITE7 },
+    annotations: { title: "Fill a layer", ...WRITE8 },
     coordinates: { out: ["bounds"] },
     handler: (a) => act({ kind: "fill", fill: a }, () => c.fillLayer(a))
   });
@@ -14613,7 +15601,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
             additionalProperties: false
           }
         },
-        layerId: LAYER_ID4,
+        layerId: LAYER_ID5,
         reference: {
           type: "string",
           description: 'Which pixels stop the fill: "layer" (default, the target layer itself), "all" or "composite" (all visible layers without paper), or a layer id from list_layers (e.g. an ink line-art layer above the flats layer).'
@@ -14632,7 +15620,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       },
       additionalProperties: false
     },
-    annotations: { title: "Fill a region (bucket / flats)", ...WRITE7 },
+    annotations: { title: "Fill a region (bucket / flats)", ...WRITE8 },
     coordinates: { in: ["", "points[]"], out: ["bounds", "regions[].point", "regions[].bounds"] },
     handler: (a) => act({ kind: "fill-region", fill: a }, () => c.fillRegion(a))
   });
@@ -14656,7 +15644,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       },
       additionalProperties: false
     },
-    annotations: { title: "Find enclosed unfilled regions", ...READ8 },
+    annotations: { title: "Find enclosed unfilled regions", ...READ9 },
     coordinates: { out: ["regions[].point", "regions[].centroid", "regions[].bounds"] },
     handler: (a) => c.findUnfilledRegions(a)
   });
@@ -14664,7 +15652,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     name: "clear_layer",
     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_ID4 }, additionalProperties: false },
+    inputSchema: { type: "object", properties: { layerId: LAYER_ID5 }, additionalProperties: false },
     annotations: { title: "Clear a layer", ...DESTRUCTIVE3 },
     coordinates: { out: ["bounds"] },
     handler: ({ layerId }) => c.clearLayer(layerId)
@@ -14674,7 +15662,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     title: "Get a brush",
     description: "Reads a brush as facets (kind, medium, variety or tool, tip, marks, dynamics, behaviour, light, motion, colour: the brush library's form, as describe_brush returns it), with the engine it paints with and whether it is an unchanged built-in preset. Without id, the active brush as edited. Also returns strokePaint: what a stroke with it would paint now (its gradient colour, else the editor's paint from set_paint). Changes nothing.",
     inputSchema: { type: "object", properties: { id: { type: "string", description: "Brush id from list_brush_presets (default the active brush)." } }, additionalProperties: false },
-    annotations: { title: "Get a brush", ...READ8 },
+    annotations: { title: "Get a brush", ...READ9 },
     handler: ({ id }) => {
       const st = c.getState();
       const b = id === void 0 ? st.brush : c.getBrush(id);
@@ -14688,7 +15676,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     title: "Set the brush",
     description: "Chooses the active brush (id, from list_brush_presets) and / or changes it with facets laid over it (objects merge, lists and values replace, marks of another kind replace the marks; the brush library's create_brush fields); unset removes whole facets first (unset colour drops a brush's own gradient). Strokes without a brush use it. Editor state, not an undo step: the changes stay on the active brush until the library's create_brush or update_brush stores a brush. Returns the active brush as facets, the engine it paints with, and problems (values clamped or dropped).",
     inputSchema: { type: "object", properties: { id: { type: "string", description: "Brush id from list_brush_presets to start from (default the active brush)." }, name: { type: "string", minLength: 1, maxLength: 80, description: "Display name." }, ...BRUSH_PATCH_PROPERTIES, unset: BRUSH_UNSET_PROPERTY }, additionalProperties: false },
-    annotations: { title: "Set the brush", ...SET5 },
+    annotations: { title: "Set the brush", ...SET6 },
     handler: async ({ id, unset, ...patch }) => {
       const stamps = patch.tip?.stamps;
       if (stamps) await c.prepareStickers(stamps);
@@ -14709,7 +15697,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       },
       additionalProperties: false
     },
-    annotations: { title: "Set the paint colour", ...SET5 },
+    annotations: { title: "Set the paint colour", ...SET6 },
     handler: ({ color, secondaryColor, locked }) => {
       if (color === void 0 && secondaryColor === void 0 && locked === void 0) throw new Error("Pass color, secondaryColor or locked.");
       if (color !== void 0) c.setColor(color);
@@ -14724,7 +15712,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     title: "Set the paint (colour or gradient)",
     description: 'Sets what strokes paint with: one colour, or gradient paint that changes colour as the stroke goes. Gradient paint: 2..16 stops sorted by offset (#rrggbb, or "paint" / "secondary" for the two editor colours), space pigment (default: mixes like paint) / oklab / srgb, and map: distance (default: the colour changes as the stroke is dragged out, 300 px then mirrored back), pressure, tilt, velocity, direction, time, across-tip or random. Every stroking brush samples it per dab (dab, mixer, watercolour and gouache, oil and impasto, particle, bristle, sticker); erasers, blenders and smudges ignore it, and a brush with its own gradient (get_brush paint) paints that instead. It also ends effect paint (set_effect_paint); set_color goes back to one colour. Editor state, not an undo step. Returns paint, color and secondaryColor.',
     inputSchema: { type: "object", properties: { paint: PAINT_SOURCE_JSON_SCHEMA }, required: ["paint"], additionalProperties: false },
-    annotations: { title: "Set the paint (colour or gradient)", ...SET5 },
+    annotations: { title: "Set the paint (colour or gradient)", ...SET6 },
     handler: ({ paint }) => {
       const p = c.setPaint(paint);
       const s = c.getState();
@@ -14745,7 +15733,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       required: ["x", "y"],
       additionalProperties: false
     },
-    annotations: { title: "Pick a colour", ...READ8 },
+    annotations: { title: "Pick a colour", ...READ9 },
     coordinates: { in: [""] },
     handler: ({ x, y, layerId }) => c.pickColor(x, y, { layerId })
   });
@@ -14753,8 +15741,8 @@ function createPaintEditorToolProvider(controller, options = {}) {
     name: "get_mixer_brush",
     title: "Get the Mixer Brush load",
     description: "Reads what the brush carries between strokes: reservoir #rrggbb or null (the Mixer Brush's loaded paint), amount 0..1 left, pickup #rrggbb or null (paint picked up from the canvas, kept by dirty brushes and a Mixer Brush that does not clean each stroke). Call before painting with mixer-brush when its loadEachStroke is false, or with a dirty brush.",
-    inputSchema: EMPTY3,
-    annotations: { title: "Get the Mixer Brush load", ...READ8 },
+    inputSchema: EMPTY4,
+    annotations: { title: "Get the Mixer Brush load", ...READ9 },
     handler: () => loadResult(c.getState().mixerLoad)
   });
   add({
@@ -14762,7 +15750,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     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: { ...COLOR3, description: "Colour #rrggbb (default the paint colour)." } }, additionalProperties: false },
-    annotations: { title: "Load the Mixer Brush", ...SET5 },
+    annotations: { title: "Load the Mixer Brush", ...SET6 },
     handler: ({ color }) => loadResult(c.loadMixerBrush(color))
   });
   add({
@@ -14770,7 +15758,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     title: "Clean the Mixer Brush",
     description: "Cleans the brush: empties the picked-up paint a dirty brush or the Mixer Brush carries (and with emptyReservoir the Mixer Brush 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", ...SET5 },
+    annotations: { title: "Clean the Mixer Brush", ...SET6 },
     handler: ({ emptyReservoir }) => loadResult(c.cleanMixerBrush(emptyReservoir === true))
   });
   add({
@@ -14781,7 +15769,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       type: "object",
       properties: {
         points: POINTS2,
-        layerId: LAYER_ID4,
+        layerId: LAYER_ID5,
         brushId: { type: "string", description: "Brush id from list_brush_presets (default the active brush)." },
         brush: { type: "object", description: "Facets to change for this stroke only, laid over brushId or the active brush (as set_brush takes them).", properties: BRUSH_PATCH_PROPERTIES, additionalProperties: false },
         color: { ...COLOR3, description: "Paint colour #rrggbb (default the paint colour)." },
@@ -14792,7 +15780,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       required: ["points"],
       additionalProperties: false
     },
-    annotations: { title: "Paint a brush stroke", ...WRITE7 },
+    annotations: { title: "Paint a brush stroke", ...WRITE8 },
     coordinates: { in: ["points[]"], out: ["bounds"] },
     handler: async (a) => {
       await c.wetIdle();
@@ -14819,7 +15807,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
         spacing: { type: "number", minimum: 0.25, maximum: 100, description: "Distance between samples along the path in document pixels (default 2); the brush spaces its own dabs, so this only sets how closely curves are followed." },
         pressure: { type: "array", minItems: 1, maxItems: 64, items: { type: "number", minimum: 0, maximum: 1 }, description: "Pen pressure along each subpath, spread evenly from start to end (default full pressure); [0.2, 1, 0.2] tapers both ends." },
         speed: { type: "number", minimum: 0.01, maximum: 100, description: "Drawing speed in document pixels per millisecond (optional; gives each sample a time t so playback has a pace and speed-sensitive brushes respond)." },
-        layerId: LAYER_ID4,
+        layerId: LAYER_ID5,
         brushId: { type: "string", description: "Brush id from list_brush_presets (default the active brush)." },
         brush: { type: "object", description: "Facets to change for this stroke only, laid over brushId or the active brush (as set_brush takes them).", properties: BRUSH_PATCH_PROPERTIES, additionalProperties: false },
         color: { ...COLOR3, description: "Paint colour #rrggbb (default the paint colour)." },
@@ -14829,7 +15817,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       required: ["path"],
       additionalProperties: false
     },
-    annotations: { title: "Brush along a path", ...WRITE7 },
+    annotations: { title: "Brush along a path", ...WRITE8 },
     coordinates: { out: ["bounds"] },
     handler: async (a) => {
       await c.wetIdle();
@@ -14883,7 +15871,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       properties: { limit: { type: "integer", minimum: 1, maximum: 5e3, description: "Most recent samples to return (default 500)." } },
       additionalProperties: false
     },
-    annotations: { title: "Get the stroke being painted", ...READ8 },
+    annotations: { title: "Get the stroke being painted", ...READ9 },
     handler: (args) => {
       const live = c.getLiveStroke();
       if (!live) return { live: false };
@@ -14905,7 +15893,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       },
       additionalProperties: false
     },
-    annotations: { title: "List recorded strokes", ...READ8 },
+    annotations: { title: "List recorded strokes", ...READ9 },
     coordinates: { out: ["strokes[].bounds", "strokes[].points[]"] },
     handler: ({ ids, last, live, layerId }) => {
       if (layerId !== void 0 && !c.getLayer(layerId)) throw new Error(`Unknown layer "${layerId}". Call list_layers for the ids.`);
@@ -14934,7 +15922,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       required: ["x", "y"],
       additionalProperties: false
     },
-    annotations: { title: "Find the stroke at a point", ...READ8 },
+    annotations: { title: "Find the stroke at a point", ...READ9 },
     coordinates: { in: [""], out: ["stroke.bounds"] },
     handler: ({ layerId, x, y }) => {
       const s = c.liveStrokeAt(layerId, x, y);
@@ -14958,7 +15946,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       required: ["id"],
       additionalProperties: false
     },
-    annotations: { title: "Change a stroke", ...WRITE7 },
+    annotations: { title: "Change a stroke", ...WRITE8 },
     coordinates: { out: ["bounds", "stroke.bounds"] },
     handler: ({ id, ...update }) => {
       if (!Object.keys(update).length) throw new Error("Pass at least one change: brushId, brush, color, paint or seed.");
@@ -14997,7 +15985,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       required: ["id"],
       additionalProperties: false
     },
-    annotations: { title: "Move or reshape a stroke", ...WRITE7 },
+    annotations: { title: "Move or reshape a stroke", ...WRITE8 },
     coordinates: { in: ["points[]", "transform.origin"], out: ["bounds", "stroke.bounds", "stroke.points[]"] },
     handler: async ({ id, points, transform }) => {
       await c.prepareStrokeEdit(id, { points, transform });
@@ -15015,7 +16003,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       required: ["id", "index"],
       additionalProperties: false
     },
-    annotations: { title: "Move a stroke up or down", ...WRITE7 },
+    annotations: { title: "Move a stroke up or down", ...WRITE8 },
     handler: ({ id, index }) => ({ order: c.reorderStroke(id, index) })
   });
   add({
@@ -15037,7 +16025,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     title: "Make a layer a stroke layer",
     description: 'Makes an empty pixel layer a stroke layer, so strokes painted on it stay editable. Refuses a layer with paint (add_layer {type: "strokes"} instead). One undo step. Returns the layer.',
     inputSchema: { type: "object", properties: { layerId: { type: "string", description: "Layer id from list_layers (default the active layer)." } }, additionalProperties: false },
-    annotations: { title: "Make a layer a stroke layer", ...WRITE7 },
+    annotations: { title: "Make a layer a stroke layer", ...WRITE8 },
     coordinates: { out: ["bounds"] },
     handler: ({ layerId }) => c.convertToLiveStrokes(layerId)
   });
@@ -15079,7 +16067,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       required: ["strokeIds"],
       additionalProperties: false
     },
-    annotations: { title: "Replay strokes, varied", ...WRITE7 },
+    annotations: { title: "Replay strokes, varied", ...WRITE8 },
     coordinates: { in: ["origin"], out: ["bounds"] },
     handler: async (a) => {
       const replay = a;
@@ -15101,7 +16089,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       },
       additionalProperties: false
     },
-    annotations: { title: "Rotate, mirror or zoom the view", ...SET5 },
+    annotations: { title: "Rotate, mirror or zoom the view", ...SET6 },
     handler: ({ reset, ...v }) => {
       if (reset) c.resetView();
       return c.setView(v);
@@ -15112,15 +16100,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", ...SET5 },
+    annotations: { title: "Set the drawing hand", ...SET6 },
     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: EMPTY3,
-    annotations: { title: "Undo", ...WRITE7 },
+    inputSchema: EMPTY4,
+    annotations: { title: "Undo", ...WRITE8 },
     handler: () => {
       const undone = c.undo();
       const s = c.getState();
@@ -15131,8 +16119,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: EMPTY3,
-    annotations: { title: "Redo", ...WRITE7 },
+    inputSchema: EMPTY4,
+    annotations: { title: "Redo", ...WRITE8 },
     handler: () => {
       const redone = c.redo();
       const s = c.getState();
@@ -15152,7 +16140,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       },
       additionalProperties: false
     },
-    annotations: { title: "Render a preview", ...READ8 },
+    annotations: { title: "Render a preview", ...READ9 },
     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.`);
@@ -15176,7 +16164,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
       },
       additionalProperties: false
     },
-    annotations: { title: "Export the painting", ...READ8 },
+    annotations: { title: "Export the painting", ...READ9 },
     handler: async ({ format, quality, scale, paper, time }) => {
       const run = () => c.exportImage({ format, quality, scale, paper });
       const bytes = time === void 0 ? await run() : await c.withEffectTime(time, run);
@@ -15188,7 +16176,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     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 and painterly blend modes have no PSD equivalent: they are written as the nearest standard mode, see list_blend_modes).',
     inputSchema: { type: "object", properties: { time: TIME }, additionalProperties: false },
-    annotations: { title: "Export as PSD", ...READ8 },
+    annotations: { title: "Export as PSD", ...READ9 },
     handler: async ({ time }) => {
       const r = time === void 0 ? c.exportPsd() : await c.withEffectTime(time, () => c.exportPsd());
       return { data: bytesToBase64(r.bytes), bytes: r.bytes.length, psb: r.psb, warnings: r.warnings };
@@ -15197,6 +16185,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
   tools.push(...createPaintGuideTools(c));
   tools.push(...createPaintWetTools(c));
   tools.push(...createPaintThickTools(c));
+  tools.push(...createFerroTools(c));
   tools.push(...createPaintReplayTools(c));
   tools.push(...createPaintEvolutionTools(c));
   tools.push(...createPaintStickerTools(c));
@@ -15920,6 +16909,10 @@ var EVOLUTION_SLIDERS = [
   { path: "brush", label: "Brush", min: 0, max: 1, step: 0.05 },
   { path: "seed", label: "Seed", min: 0, max: 1, step: 0.05 }
 ];
+var MAGNET_SLIDERS = [
+  { path: "strength", label: "Strength", min: -1, max: 1, step: 0.05 },
+  { path: "radius", label: "Radius", min: 4, max: 512, step: 1 }
+];
 function quickStencil(kind, canvas) {
   const { width: w, height: h } = canvas;
   switch (kind) {
@@ -16205,8 +17198,8 @@ function createPaintEditorDocument(controller, options = {}) {
 }
 
 // src/paint-editor/collaboration-tools.ts
-var READ9 = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
-var WRITE8 = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
+var READ10 = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+var WRITE9 = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
 var proposalIdArg = {
   type: "object",
   properties: { proposalId: { type: "string", minLength: 1, description: "Id of a pending paint proposal, from propose_paint or list_paint_proposals." } },
@@ -16284,7 +17277,7 @@ function createPaintProposalToolProvider(proposals, options = {}) {
       required: ["title", "ops"],
       additionalProperties: false
     },
-    annotations: { title: "Propose paint", ...WRITE8 },
+    annotations: { title: "Propose paint", ...WRITE9 },
     handler: (args, context) => {
       const origin = context.actor?.id ? `agent:${context.actor.id}` : options.fallbackOrigin;
       const proposal = proposals.propose({ ...args, ...origin ? { origin } : {} });
@@ -16297,7 +17290,7 @@ function createPaintProposalToolProvider(proposals, options = {}) {
     title: "List paint proposals",
     description: "Lists the pending paint proposals (ghost paint not yet on the canvas): id, title, rationale, who proposed it, its op kinds, where it goes, where the ghost sits, the strokes it echoes and any of those since removed (missing: it can no longer be accepted), and whether accepting is allowed. Call before accept_paint_proposal or reject_paint_proposal.",
     inputSchema: { type: "object", properties: {}, additionalProperties: false },
-    annotations: { title: "List paint proposals", ...READ9 },
+    annotations: { title: "List paint proposals", ...READ10 },
     handler: () => ({ proposals: proposals.getState().proposals.map(describe), readOnly: readOnlyReason() })
   };
   const acceptTool = {
@@ -16305,7 +17298,7 @@ function createPaintProposalToolProvider(proposals, options = {}) {
     title: "Accept a paint proposal",
     description: "Paints a pending proposal on a new layer as one undo step, recorded as made by whoever proposed it, and drops it from the pending list; the user's active layer stays theirs. Refuses, changing nothing, when the painting is read-only or a stroke it echoes was removed. Returns the new layer id, the stroke ids painted and the undo step name.",
     inputSchema: proposalIdArg,
-    annotations: { title: "Accept a paint proposal", ...WRITE8 },
+    annotations: { title: "Accept a paint proposal", ...WRITE9 },
     handler: (args) => {
       const reason = readOnlyReason();
       if (reason) throw new Error(reason);
@@ -16317,7 +17310,7 @@ function createPaintProposalToolProvider(proposals, options = {}) {
     title: "Reject a paint proposal",
     description: "Dismisses a pending paint proposal: its ghost disappears and the painting and its history are unchanged. Use it to withdraw a suggestion that no longer fits. Returns the dismissed proposal id and title.",
     inputSchema: proposalIdArg,
-    annotations: { title: "Reject a paint proposal", ...WRITE8 },
+    annotations: { title: "Reject a paint proposal", ...WRITE9 },
     handler: (args) => {
       const p = proposals.reject(args.proposalId);
       return { proposalId: p.id, title: p.title, rejected: true };
@@ -16390,6 +17383,33 @@ var PAINT_DOCUMENT_JSON_SCHEMA = {
             required: ["id", "layerId", "points", "brush"]
           }
         },
+        ferro: { type: "object", additionalProperties: { type: "string" }, description: "Layer id \u2192 asset id of its liquid ferrofluid map." },
+        ferroSettings: {
+          type: "object",
+          additionalProperties: {
+            type: "object",
+            properties: {
+              wavelength: { type: "number", description: "Rosensweig spike spacing in pixels." },
+              threshold: { type: "number", description: "Critical magnetic field threshold." }
+            }
+          },
+          description: "Layer id \u2192 ferrofluid spike settings."
+        },
+        magnets: {
+          type: "array",
+          description: "Magnets on the canvas that pull liquid ferrofluid into spikes.",
+          items: {
+            type: "object",
+            properties: {
+              id: { type: "string", description: "Magnet id." },
+              x: { type: "number", description: "Document x in pixels." },
+              y: { type: "number", description: "Document y in pixels." },
+              strength: { type: "number", minimum: -1, maximum: 1, description: "Magnet dipole strength (-1..1)." },
+              radius: { type: "number", minimum: 4, maximum: 512, description: "Magnet field falloff radius in pixels." }
+            },
+            required: ["id", "x", "y", "strength", "radius"]
+          }
+        },
         fluor: {
           type: "object",
           description: "Per-layer UV-fluorescent ink channels (layerId \u2192 bounds + PNG data URL).",
@@ -16440,7 +17460,7 @@ function uiTables() {
     brushOptions: BRUSH_OPTION_CONTROLS,
     blendMenu: BLEND_MENU_GROUPS,
     layerEffects: LAYER_EFFECT_MENU.map(({ kind, label }) => ({ kind, label, controls: layerEffectControls(defaultLayerEffect(kind, kind)) })),
-    sliders: { paper: PAPER_SLIDERS, wet: WET_PARAM_SLIDERS, wetTilt: WET_TILT_SLIDERS, wetSpeed: WET_SPEED_SLIDER, light: LIGHT_SLIDERS, uvLight: UV_LIGHT_SLIDERS, viewTilt: VIEW_TILT_SLIDERS, ghost: GHOST_SLIDERS, mutation: MUTATION_SLIDERS, livePatterns: LIVE_PATTERN_SLIDERS, stroke: STROKE_SLIDERS, sticker: STICKER_SLIDERS },
+    sliders: { paper: PAPER_SLIDERS, wet: WET_PARAM_SLIDERS, wetTilt: WET_TILT_SLIDERS, wetSpeed: WET_SPEED_SLIDER, light: LIGHT_SLIDERS, uvLight: UV_LIGHT_SLIDERS, viewTilt: VIEW_TILT_SLIDERS, ghost: GHOST_SLIDERS, mutation: MUTATION_SLIDERS, livePatterns: LIVE_PATTERN_SLIDERS, stroke: STROKE_SLIDERS, sticker: STICKER_SLIDERS, magnet: MAGNET_SLIDERS },
     pathStrokeTapers: PATH_STROKE_TAPERS,
     padSampleSizes: PAD_SAMPLE_SIZES,
     wetGpu: WET_GPU_OPTIONS,
@@ -16517,6 +17537,7 @@ export {
   DEFAULT_BRUSH_ID,
   DEFAULT_DPI,
   DEFAULT_DYNAMICS,
+  DEFAULT_FERRO,
   DEFAULT_FLOW,
   DEFAULT_FLUORESCENCE,
   DEFAULT_GHOST,
@@ -16525,6 +17546,8 @@ export {
   DEFAULT_LIGHT,
   DEFAULT_LIGHTING,
   DEFAULT_LIVE_PATTERNS,
+  DEFAULT_MAGNET_RADIUS,
+  DEFAULT_MAGNET_STRENGTH,
   DEFAULT_MULTI_COLOR,
   DEFAULT_MUTATION,
   DEFAULT_MUTATION_RATES,
@@ -16552,6 +17575,10 @@ export {
   EVOLUTION_BRUSH_FACETS,
   EVOLUTION_MUTATION_SCHEMA,
   EVOLUTION_SLIDERS,
+  FERRO_CARRIER_RGB,
+  FERRO_DEFAULT_GLOSS,
+  FERRO_DEFAULT_METALLIC,
+  FERRO_DEFAULT_RIM,
   FilmBuffer,
   GHOST_SLIDERS,
   GHOST_TRIGGERS,
@@ -16576,6 +17603,7 @@ export {
   LIVE_PATTERN_SLIDERS,
   LIVE_STROKE_ENGINES,
   LitCache,
+  MAGNET_SLIDERS,
   MAX_BRUSH_SIZE,
   MAX_CANVAS_SIDE,
   MAX_COORDINATE,
@@ -16688,9 +17716,11 @@ export {
   addPaintGradientStop,
   addPolygonArea,
   advanceHeatField,
+  advectFerro,
   affineCopy,
   applyAffine,
   backlightOf,
+  bakeFerroIntoThick,
   brushEngineControls,
   brushLoadColor,
   brushLoadForStroke,
@@ -16707,6 +17737,7 @@ export {
   computeUvSpill,
   contactSheet,
   createEvolutionTools,
+  createFerroTools,
   createHeatField,
   createMutationTools,
   createPaintAgentStrokes,
@@ -16751,11 +17782,20 @@ export {
   effectPaintKey,
   effectPaintSize,
   emptiedLayers,
+  emptyFerro,
   emptyFluor,
   emptyThermo,
   emptyThickChannels,
   engineBrushSourceIds,
   exportProposalContactSheetPng,
+  ferroCacheKey,
+  ferroFieldAt,
+  ferroFromJSON,
+  ferroInfo,
+  ferroSpikeHeightAt,
+  ferroToJSON,
+  ferroToShadow,
+  ferroTwinBrush,
   fillRegionMask,
   finalizeThermoStroke,
   findUnfilledRegionsMask,
@@ -16792,7 +17832,9 @@ export {
   lightingKey,
   liveStrokeBounds,
   liveStrokeRefusal,
+  magnetsFromJSON,
   mapPenPoint,
+  mergeFerro,
   mergeFourChannel,
   mix32,
   mixColorOklch,
@@ -16814,6 +17856,8 @@ export {
   normalizeBrushStroke,
   normalizeCanvas,
   normalizeDynamics,
+  normalizeFerro,
+  normalizeFerro as normalizeFerroSettings,
   normalizeFlow,
   normalizeFluorescence,
   normalizeGhost,
@@ -16822,6 +17866,7 @@ export {
   normalizeLight,
   normalizeLighting,
   normalizeLivePatterns,
+  normalizeMagnet,
   normalizeMultiColor,
   normalizeMutation,
   normalizeMutationRates,
@@ -16903,6 +17948,7 @@ export {
   sampleHeatAt,
   samplePath,
   samplePressure,
+  scaleFerro,
   scaleFluor,
   scalePaintGradient,
   scaleStencil,
@@ -16911,6 +17957,7 @@ export {
   seededStrokeVariation,
   serializePaintDocument,
   serializePaintDocumentExternal,
+  shadowToFerro,
   shiftHeatField,
   solidPaint,
   squaredDistanceTransform,