@pixerate/editor 0.277.0 → 0.279.0

package/dist/paint-editor/index.js

@@ -368,7 +368,10 @@ import {
   wheelToHue
 } from "../chunk-2EUW2XZX.js";
 import "../chunk-E2V5DA3W.js";
-import "../chunk-VR6OGHU5.js";
+import {
+  isDualColor,
+  normalizeDualColor
+} from "../chunk-VR6OGHU5.js";
 import "../chunk-JC2SHA4A.js";
 import {
   linearToSrgb,
@@ -4172,6 +4175,8 @@ function normalizeBrushStroke(raw) {
     points,
     seed: finite2(r.seed) ? r.seed | 0 : 0
   };
+  const dual = r.dualColor === void 0 ? null : normalizeDualColor(r.dualColor);
+  if (dual && /^#[0-9a-f]{6}$/.test(dual.light) && /^#[0-9a-f]{6}$/.test(dual.dark)) out.dualColor = dual;
   const copies = Array.isArray(r.copies) ? r.copies.map(readAffine).filter((m) => m !== null) : [];
   if (copies.length) out.copies = copies;
   const load = readLoad(r.load);
@@ -4380,9 +4385,77 @@ function serializePaintDocument(state, options = {}) {
   const { layers, assets } = serializeLayers(state.layers);
   return { ...header(state, options), layers, assets };
 }
+var NO_EXTENSION_PNGS = /* @__PURE__ */ new Set(["format", "version", "width", "height", "dpi", "paper", "layers", "assets", "activeLayerId", "strokes", "wetEvents", "paintEvents", "origin"]);
+var EXTENSION_ASSET_REF = "asset:";
+var PNG_DATA_URL = "data:image/png;base64,";
+var storedPngs = /* @__PURE__ */ new WeakMap();
+function fnv1a(text) {
+  let h = 2166136261;
+  for (let i = 0; i < text.length; i++) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+async function externalizePngs(value, assets, store) {
+  if (typeof value === "string") {
+    if (!value.startsWith(PNG_DATA_URL)) return value;
+    const id = `ext-${fnv1a(value)}-${value.length.toString(36)}`;
+    if (!assets[id]) {
+      let refs = storedPngs.get(store);
+      if (!refs) storedPngs.set(store, refs = /* @__PURE__ */ new Map());
+      let ref2 = refs.get(value);
+      if (!ref2) {
+        const parsed = parseDataUrl(value);
+        if (!parsed) return value;
+        const b = parsed.bytes;
+        const u32 = (o) => (b[o] << 24 | b[o + 1] << 16 | b[o + 2] << 8 | b[o + 3]) >>> 0;
+        ref2 = await store.put(new Blob([b], { type: "image/png" }), { id, width: b.length >= 24 ? u32(16) : 0, height: b.length >= 24 ? u32(20) : 0 });
+        if (typeof ref2 !== "string" || !ref2) throw new Error(`The asset store returned no reference for "${id}".`);
+        refs.set(value, ref2);
+      }
+      assets[id] = ref2;
+    }
+    return `${EXTENSION_ASSET_REF}${id}`;
+  }
+  if (Array.isArray(value)) {
+    const out = [];
+    for (const v of value) out.push(await externalizePngs(v, assets, store));
+    return out;
+  }
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = await externalizePngs(v, assets, store);
+    return out;
+  }
+  return value;
+}
+function inlinePngs(value, assets, problems, field, used) {
+  if (typeof value === "string") {
+    if (!value.startsWith(EXTENSION_ASSET_REF)) return value;
+    const id = value.slice(EXTENSION_ASSET_REF.length);
+    const url = assets[id];
+    if (typeof url === "string" && url.startsWith("data:")) {
+      used.add(id);
+      return url;
+    }
+    const msg = `"${field}" refers to asset "${id}", which could not be read; that part loads empty.`;
+    if (!problems.includes(msg)) problems.push(msg);
+    return value;
+  }
+  if (Array.isArray(value)) return value.map((v) => inlinePngs(v, assets, problems, field, used));
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = inlinePngs(v, assets, problems, field, used);
+    return out;
+  }
+  return value;
+}
 async function serializePaintDocumentExternal(state, store, options = {}) {
   const { layers, assets } = await serializeLayersExternal(state.layers, store);
-  return { ...header(state, options), layers, assets };
+  const out = { ...header(state, options), layers, assets };
+  for (const key of Object.keys(out)) if (!NO_EXTENSION_PNGS.has(key)) out[key] = await externalizePngs(out[key], assets, store);
+  return out;
 }
 function paintLayersOnly(layers, problems) {
   const out = [];
@@ -4415,9 +4488,15 @@ function deserializePaintDocument(raw) {
     throw new Error(`Paint document version ${JSON.stringify(r.version)} is newer than this editor reads (${PAINT_SCHEMA_VERSION}); update @pixerate/editor.`);
   }
   const problems = [];
+  const rawAssets = r.assets && typeof r.assets === "object" ? r.assets : {};
+  const used = /* @__PURE__ */ new Set();
+  const inlined = { ...r };
+  for (const key of Object.keys(r)) if (!NO_EXTENSION_PNGS.has(key)) inlined[key] = inlinePngs(r[key], rawAssets, problems, key, used);
+  return readDocument(inlined, Object.fromEntries(Object.entries(rawAssets).filter(([id]) => !used.has(id))), problems);
+}
+function readDocument(r, assets, problems) {
   const canvas = normalizeCanvas({ width: r.width, height: r.height, dpi: r.dpi ?? void 0 });
   const paper = normalizePaper(r.paper ?? {});
-  const assets = r.assets && typeof r.assets === "object" ? r.assets : {};
   const layers = paintLayersOnly(deserializeLayers(r.layers, { assets, problems }), problems);
   const wanted = typeof r.activeLayerId === "string" ? r.activeLayerId : null;
   const activeLayerId = wanted && findLayer(layers, wanted) ? wanted : flattenLayers(layers).filter((l) => l.type === "pixel").pop()?.id ?? null;
@@ -9025,7 +9104,8 @@ var PaintEditorController = class _PaintEditorController {
   brushColour = null;
   /**
    * The host's colour scheme: a paint colour that came from a brush's light / dark default
-   * resolves to the new side. Editor state, not an undo step.
+   * resolves to the new side, and stroke layers show their dual-colour strokes in it. Only the
+   * view changes: the document, history and change listeners don't hear of it.
    */
   setColorScheme(scheme) {
     const next = scheme === "dark" ? "dark" : "light";
@@ -9033,9 +9113,77 @@ var PaintEditorController = class _PaintEditorController {
     this.colorScheme = next;
     const hex2 = this.brushColour ? brushColourHex(this.brushColour, next) : null;
     if (hex2) this.color = hex2;
+    this.liveLayers = null;
     const refs = brushStickerRefs(this.brush);
     if (refs.some((r) => !editorStampOf(r))) void this.prepareStickers(refs).catch(() => this.emit([]));
-    this.emit([]);
+    this.emit();
+  }
+  /**
+   * Stroke layers in the colour scheme: the document keeps every stroke layer drawn with each
+   * stroke's `color` (a dual-colour stroke's light side), so saved and shared documents never
+   * depend on who is looking. The view (display, image exports, the base a pointer stroke paints
+   * on) draws dual-colour strokes in the scheme's side instead. One cached surface per layer,
+   * brought up to date from the strokes that changed since it was drawn.
+   */
+  schemeViews = /* @__PURE__ */ new Map();
+  schemeCopies = /* @__PURE__ */ new WeakMap();
+  /** Set while a stroke is painted for the document rather than the view (`runStroke` on a stroke layer): dual colours take this side. */
+  paintScheme = null;
+  /** A stroke as the scheme shows it: itself, or (a dual-colour stroke) a copy in the scheme's side. */
+  schemeStroke(st, scheme) {
+    const want = st.dualColor?.[scheme];
+    if (!want || want === st.color) return st;
+    const had = this.schemeCopies.get(st);
+    if (had?.scheme === scheme) return had.stroke;
+    const out = { ...st, color: want };
+    if (st.load) {
+      const load = brushLoadForStroke(st.brush, EMPTY_MIXER_LOAD, hexToRgb8(want).map((v) => v / 255));
+      if (load.reservoir || load.pickup) out.load = load;
+      else delete out.load;
+    }
+    this.schemeCopies.set(st, { scheme, stroke: out });
+    return out;
+  }
+  /** A stroke layer's surface in the scheme, or `null` when the document's pixels already show it. */
+  schemeSurface(layer, list) {
+    const scheme = this.colorScheme;
+    if (!list.some((st) => st.dualColor && st.dualColor[scheme] !== st.color)) {
+      this.schemeViews.delete(layer.id);
+      return null;
+    }
+    const had = this.schemeViews.get(layer.id);
+    if (had && had.scheme === scheme && had.list === list && had.base === layer.surface) return had.surface;
+    const view = list.map((st) => this.schemeStroke(st, scheme));
+    let surface;
+    if (had && had.scheme === scheme && had.list !== list && !layer.offset.x && !layer.offset.y) {
+      const now = new Set(list);
+      const before = new Set(had.list);
+      const gone = had.list.filter((st) => !now.has(st));
+      const kept = list.filter((st) => before.has(st));
+      const sameOrder = kept.every((st, i) => st === had.list.filter((x) => now.has(x))[i]);
+      surface = sameOrder ? this.drawLiveStrokes({ ...layer, surface: had.surface }, view, this.strokeAreas(gone.map((st) => this.schemeStroke(st, scheme)))) : this.drawLiveStrokes(layer, view);
+    } else surface = this.drawLiveStrokes(layer, view);
+    this.schemeViews.set(layer.id, { scheme, list, base: layer.surface, surface });
+    return surface;
+  }
+  /** `layers` with each stroke layer that holds dual-colour strokes shown in the scheme. */
+  schemeLayers(layers) {
+    const live = this.doc.liveStrokes;
+    if (!live) return layers;
+    let out = layers;
+    for (const [id, list] of Object.entries(live)) {
+      const l = findLayer(out, id)?.layer;
+      if (!isPixelLayer(l)) continue;
+      const surface = this.schemeSurface(l, list);
+      if (surface) out = mapLayer(out, id, () => ({ ...l, surface }));
+    }
+    return out;
+  }
+  /** The paint colour's light / dark pair for a stroke with `brushId`, when the colour came from one (a brush's own or default colour, or `setColor`). */
+  dualPaint(brushId) {
+    const spec = brushId !== void 0 ? this.findEntry(brushId)?.spec : this.brushSpec;
+    if (spec?.colour?.own && spec.colour.default !== void 0) return dualHex(spec.colour.default);
+    return this.brushColour ? dualHex(this.brushColour) : null;
   }
   /** Locks the paint colour: choosing a brush with a default colour keeps it. Editor state, not an undo step. */
   setColorLocked(locked) {
@@ -9065,10 +9213,16 @@ var PaintEditorController = class _PaintEditorController {
     const d = spec?.colour?.own ? spec.colour.default : void 0;
     return d !== void 0 ? brushColourHex(d, this.colorScheme) : null;
   }
-  /** Sets the paint colour (and goes back to one colour from gradient paint). */
+  /**
+   * Sets the paint colour (and goes back to one colour from gradient paint). A light / dark pair
+   * paints the colour scheme's side, follows `setColorScheme`, and is recorded with each stroke
+   * painted in it. Returns the colour as #rrggbb.
+   */
   setColor(color) {
-    this.color = parseColor(color);
-    this.brushColour = null;
+    const dual = typeof color === "string" ? null : dualHex(color);
+    if (typeof color !== "string" && !dual) throw new PaintEditorError(`color ${JSON.stringify(color)} is not a colour; use #rrggbb, or { light, dark } with a colour each.`);
+    this.color = dual ? dual[this.colorScheme] : parseColor(color);
+    this.brushColour = dual;
     this.gradient = null;
     this.effectPaint = this.effectPaintPending = null;
     this.paintEpoch++;
@@ -9197,11 +9351,20 @@ var PaintEditorController = class _PaintEditorController {
   strokeCopies() {
     return symmetryCopies(this.guides.symmetry);
   }
-  sessionFor(doc, init, host, points) {
+  sessionFor(doc, given, host, points) {
+    let dualColor = null;
+    if (given.color !== void 0 && typeof given.color !== "string") {
+      dualColor = dualHex(given.color);
+      if (!dualColor) throw new PaintEditorError(`color ${JSON.stringify(given.color)} is not a colour; use #rrggbb, or { light, dark } with a colour each.`);
+    }
+    const scheme = this.paintScheme ?? this.colorScheme;
+    let init = dualColor ? { ...given, color: dualColor[scheme] } : given;
     if (init.paint !== void 0 && !isPaintEffectPaint(init.paint)) {
       const p = this.readStrokePaint(init.paint);
-      if (p.type === "color") init = { ...init, color: p.color, paint: void 0 };
-      else init = { ...init, paint: p };
+      if (p.type === "color") {
+        init = { ...init, color: p.color, paint: void 0 };
+        dualColor = null;
+      } else init = { ...init, paint: p };
     }
     let layer = (() => {
       const id = init.layerId ?? doc.activeLayerId;
@@ -9341,7 +9504,12 @@ var PaintEditorController = class _PaintEditorController {
     }
     let color = init.color === void 0 ? this.ownColour(init.brushId) ?? this.color : parseColor(init.color);
     const tracing = this.guides.tracing;
-    if (init.color === void 0 && init.start && tracing?.visible && tracing.sampleColors) color = this.sampleTracingColor(init.start.x, init.start.y) ?? color;
+    const traced = init.color === void 0 && init.start && tracing?.visible && tracing.sampleColors ? this.sampleTracingColor(init.start.x, init.start.y) : null;
+    if (traced) color = traced;
+    else if (init.color === void 0) {
+      dualColor = this.dualPaint(init.brushId);
+      if (dualColor) color = dualColor[scheme];
+    }
     const perspective = this.guides.perspective;
     const snapper = init.snapToPerspective && perspective.enabled && perspective.snap ? new PerspectiveSnapper(perspective) : null;
     const useStencils = init.stencils !== false;
@@ -9357,6 +9525,7 @@ var PaintEditorController = class _PaintEditorController {
     const copies = (init.copies ?? this.strokeCopies()).filter((m) => m.some((v, i) => v !== IDENTITY_AFFINE[i]));
     const hasThick = Boolean(doc.thick?.[layer.id]);
     const needThick = brush.engine === "impasto" || Boolean(brush.iridescence) || brush.engine === "eraser" && hasThick || Boolean(wet?.driver.init.film);
+    const gradient = effect ? null : this.strokeGradient(init, brush, color);
     const session = new PaintStrokeSession(host, {
       layerId: layer.id,
       surface: layer.surface,
@@ -9369,6 +9538,8 @@ var PaintEditorController = class _PaintEditorController {
       paperDepth: doc.paper.depth,
       seed,
       colorHex: color,
+      // Only a stroke that paints its one colour keeps the pair (gradient and effect paint have their own colours).
+      ...dualColor && !gradient && !effect && dualColor[scheme] === color ? { dualColor } : {},
       affineCopies: copies,
       copies: [IDENTITY_AFFINE, ...copies].map(affineCopy),
       inputFilter,
@@ -9385,7 +9556,7 @@ var PaintEditorController = class _PaintEditorController {
       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,
       stampArt: this.stampArt,
-      paint: effect ? null : this.strokeGradient(init, brush, color),
+      paint: gradient,
       effect
     });
     if (wet) this.wet.driver = wet.driver;
@@ -9402,6 +9573,10 @@ var PaintEditorController = class _PaintEditorController {
       points: session.points.map((p) => ({ ...p })),
       seed: init.seed
     };
+    if (init.dualColor) {
+      stroke.dualColor = { ...init.dualColor };
+      if (this.doc.liveStrokes?.[session.layerId]) stroke.color = init.dualColor.light;
+    }
     if (init.affineCopies.length) stroke.copies = init.affineCopies.map((m) => [...m]);
     if (init.effect) stroke.paint = JSON.parse(JSON.stringify(init.effect.source));
     else if (init.paint) stroke.paint = JSON.parse(JSON.stringify(init.paint));
@@ -9510,34 +9685,43 @@ var PaintEditorController = class _PaintEditorController {
         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(
-          `${brush.name} stroke`,
-          this.withWetEvents(
-            withLiveStroke(
-              {
-                ...this.doc,
-                layers: mapLayer(this.doc.layers, l.id, () => ({ ...l, surface })),
-                strokes: [...this.doc.strokes, stroke],
-                ...thick ? { thick } : {},
-                ...stickers ? { stickers } : {},
-                ...light ? { light } : {},
-                ...fluor ? { fluor } : {},
-                ...thermo ? { thermo } : {},
-                ...ferro ? { ferro } : { ferro: void 0 },
-                ...ferroSettings ? { ferroSettings } : { ferroSettings: void 0 }
-              },
-              stroke
-            )
-          ),
-          before
+        let next = this.withWetEvents(
+          withLiveStroke(
+            {
+              ...this.doc,
+              layers: mapLayer(this.doc.layers, l.id, () => ({ ...l, surface })),
+              strokes: [...this.doc.strokes, stroke],
+              ...thick ? { thick } : {},
+              ...stickers ? { stickers } : {},
+              ...light ? { light } : {},
+              ...fluor ? { fluor } : {},
+              ...thermo ? { thermo } : {},
+              ...ferro ? { ferro } : { ferro: void 0 },
+              ...ferroSettings ? { ferroSettings } : { ferroSettings: void 0 }
+            },
+            stroke
+          )
         );
+        const list = next.liveStrokes?.[l.id];
+        if (list && (viewBase || stroke.color !== s.init.colorHex)) {
+          const canonical = this.withLiveStrokes({ ...next, layers: mapLayer(next.layers, l.id, () => l) }, l, list, s.result?.bounds ? [s.result.bounds] : null, { record: false });
+          const drawn = findLayer(canonical.layers, l.id)?.layer;
+          this.schemeViews.set(l.id, { scheme: viewScheme, list, base: drawn.surface, surface });
+          next = canonical;
+        }
+        this.commit(`${brush.name} stroke`, next, before);
         this.recordMutationStroke(stroke, s.result?.bounds ?? null);
         this.notifySample("end", s, [], stroke.id);
       }
     };
+    const targetId = init.layerId ?? this.doc.activeLayerId;
+    const target = targetId ? findLayer(this.doc.layers, targetId)?.layer : void 0;
+    const targetStrokes = isPixelLayer(target) ? this.doc.liveStrokes?.[target.id] : void 0;
+    const viewBase = targetStrokes && isPixelLayer(target) ? this.schemeSurface(target, targetStrokes) : null;
+    const viewScheme = this.colorScheme;
     let session;
     try {
-      session = this.sessionFor(this.doc, { snapToPerspective: true, ...init }, host);
+      session = this.sessionFor(viewBase && target ? { ...this.doc, layers: mapLayer(this.doc.layers, target.id, (x) => ({ ...x, surface: viewBase })) } : this.doc, { snapToPerspective: true, ...init }, host);
     } catch (e) {
       this.wetOp = null;
       throw e;
@@ -9614,7 +9798,7 @@ var PaintEditorController = class _PaintEditorController {
       this.liveThermo = null;
       const masks = s.init.selection ? (s.maskStencils ?? this.guides.stencils).filter((x) => x.enabled && x.mode === "mask") : [];
       const load = s.init.mixerLoad;
-      const result = this.paintStroke({ layerId: s.layerId, points: s.points, color: s.init.colorHex, brush: brushToJSON(s.init.brush), seed: s.init.seed, copies: s.init.affineCopies, ...load.reservoir || load.pickup ? { load } : {}, paint, snapToPerspective: false, stencils: false, maskStencils: masks });
+      const result = this.paintStroke({ layerId: s.layerId, points: s.points, color: s.init.dualColor ?? s.init.colorHex, brush: brushToJSON(s.init.brush), seed: s.init.seed, copies: s.init.affineCopies, ...load.reservoir || load.pickup ? { load } : {}, paint, snapToPerspective: false, stencils: false, maskStencils: masks });
       Object.assign(s.result, result);
       this.notifySample("end", s, [], result.strokeId);
     };
@@ -9698,7 +9882,14 @@ var PaintEditorController = class _PaintEditorController {
         }, stroke);
       }
     };
-    const session = this.sessionFor(doc, init, host, points);
+    const target = init.layerId ?? doc.activeLayerId;
+    this.paintScheme = target && doc.liveStrokes?.[target] ? "light" : null;
+    let session;
+    try {
+      session = this.sessionFor(doc, init, host, points);
+    } finally {
+      this.paintScheme = null;
+    }
     session.push(points);
     const result = session.end();
     if (session.init.wet) {
@@ -10669,9 +10860,9 @@ var PaintEditorController = class _PaintEditorController {
     const override = this.frameOverride;
     if (override) return Array.from(override).reduce((ls, [id, surface]) => mapLayer(ls, id, (l) => ({ ...l, surface })), this.doc.layers);
     const live = this.live;
-    if (!live) return this.animatedView();
+    if (!live) return this.schemeLayers(this.animatedView());
     if (this.liveLayers?.key === live.surface) return this.liveLayers.layers;
-    const layers = mapLayer(this.doc.layers, live.layerId, (l) => ({ ...l, surface: live.surface }));
+    const layers = mapLayer(this.schemeLayers(this.doc.layers), live.layerId, (l) => ({ ...l, surface: live.surface }));
     this.liveLayers = { key: live.surface, layers };
     return layers;
   }
@@ -11226,6 +11417,7 @@ var PaintEditorController = class _PaintEditorController {
     delete this.extensions.heat;
     delete this.extensions.uvLight;
     this.viewCompositor.clear();
+    this.schemeViews.clear();
     this.emit();
     const refs = Object.values(this.doc.stickers ?? {}).flatMap((list) => list.map((x) => x.ref));
     if (refs.some((r) => !editorStampOf(r))) void this.prepareStickers(refs).catch(() => this.emit([]));
@@ -11284,7 +11476,7 @@ var PaintEditorController = class _PaintEditorController {
    * pixels), and the composite as the merged image.
    */
   exportPsd() {
-    const driedBase = this.driedLayers(this.doc.layers);
+    const driedBase = this.driedLayers(this.schemeLayers(this.doc.layers));
     const backlight = this.backlightLayer(driedBase);
     const dried = [...this.lightLayers(this.uvLayers(this.litLayers(this.thermoLayers(driedBase)))), ...backlight ? [backlight] : []];
     const { width, height, dpi } = this.doc.canvas;
@@ -11838,7 +12030,11 @@ var PaintEditorController = class _PaintEditorController {
       next.seed = update.seed;
     }
     if (update.color !== void 0) {
-      next.color = parseColor(update.color);
+      const dual = typeof update.color === "string" ? null : dualHex(update.color);
+      if (typeof update.color !== "string" && !dual) throw new PaintEditorError(`color ${JSON.stringify(update.color)} is not a colour; use #rrggbb, or { light, dark } with a colour each.`);
+      next.color = dual ? dual.light : parseColor(update.color);
+      if (dual) next.dualColor = dual;
+      else delete next.dualColor;
       delete next.paint;
     }
     if (update.paint !== void 0) {
@@ -11851,6 +12047,7 @@ var PaintEditorController = class _PaintEditorController {
         const p = this.readStrokePaint(update.paint);
         if (p.type === "color") {
           next.color = p.color;
+          delete next.dualColor;
           delete next.paint;
         } else next.paint = JSON.parse(JSON.stringify(p));
       }
@@ -11966,8 +12163,13 @@ var PaintEditorController = class _PaintEditorController {
   commitLiveStrokes(label, layer, list, dirty) {
     this.commit(label, this.withLiveStrokes(this.doc, layer, list, dirty));
   }
-  withLiveStrokes(doc, layer, list, dirty) {
-    if (isLayerLocked(layer, "pixels")) throw new PaintEditorError(`Layer "${layer.name}" has its pixels locked; unlock it (update_layer locks) first.`);
+  /**
+   * The document with a layer's strokes set and its pixels redrawn. With `record` false (the same
+   * strokes drawn for the colour scheme) the pixel lock doesn't apply and no event is recorded for replays.
+   */
+  withLiveStrokes(doc, layer, list, dirty, options = {}) {
+    const record = options.record !== false;
+    if (record && isLayerLocked(layer, "pixels")) throw new PaintEditorError(`Layer "${layer.name}" has its pixels locked; unlock it (update_layer locks) first.`);
     const current = findLayer(doc.layers, layer.id)?.layer;
     const hasFilm = list.some((s) => Boolean(s.brush.iridescence)) || Boolean(doc.thick?.[layer.id]);
     const surface = this.drawLiveStrokes(current ?? layer, list, hasFilm ? null : dirty);
@@ -11987,6 +12189,7 @@ var PaintEditorController = class _PaintEditorController {
       thick = withLayerThick(doc.thick, layer.id, ch);
     }
     const next = { ...doc, layers: mapLayer(doc.layers, layer.id, (l) => ({ ...l, surface, offset: { x: 0, y: 0 } })), liveStrokes: { ...doc.liveStrokes ?? {}, [layer.id]: [...list] }, ...thick ? { thick } : {} };
+    if (!record) return next;
     return this.withPaintEvent(next, { kind: "live-strokes", layerId: layer.id, data: { strokes: list.map((x) => JSON.parse(JSON.stringify(x))) } });
   }
   /** Where a stroke painted (document pixels): as learnt when it was painted or drawn, else an estimate from its points and brush. */
@@ -13276,6 +13479,12 @@ function readWetGhost(raw) {
   const linger = typeof g.linger === "number" && Number.isFinite(g.linger) ? Math.max(0.5, Math.min(60, g.linger)) : 4;
   return { pigment: [g.pigment[0], g.pigment[1], g.pigment[2], g.pigment[3]], remaining, total, linger };
 }
+function dualHex(value) {
+  if (!isDualColor(value)) return null;
+  const light = brushColourHex(value.light, "light");
+  const dark = brushColourHex(value.dark, "dark");
+  return light && dark ? { light, dark } : null;
+}
 
 // src/paint-editor/presence.ts
 var PaintPresence = class extends PresenceStore {
@@ -15687,24 +15896,33 @@ function createPaintEditorToolProvider(controller, options = {}) {
   add({
     name: "set_color",
     title: "Set the paint colour",
-    description: "Sets the paint colour (and optionally the second colour) that strokes and fills use by default, and whether it is locked. Choosing a brush with a default colour (set_brush id, e.g. the highlighter's yellow) makes that the paint colour unless the colour is locked; a brush with colour.own always paints its own. Setting color goes back to one colour from gradient paint (set_paint) or effect paint (set_effect_paint). Editor state, not an undo step. Returns both colours and locked.",
+    description: "Sets the paint colour (and optionally the second colour) that strokes and fills use by default, and whether it is locked. Choosing a brush with a default colour (set_brush id, e.g. the highlighter's yellow) makes that the paint colour unless the colour is locked; a brush with colour.own always paints its own. Setting color goes back to one colour from gradient paint (set_paint) or effect paint (set_effect_paint). dualColor sets a light / dark pair instead: strokes record the pair, and on a stroke layer each viewer sees them in the side of their own colour scheme (a pixel layer keeps the side painted). Editor state, not an undo step. Returns both colours and locked (and dualColor when given).",
     inputSchema: {
       type: "object",
       properties: {
         color: { ...COLOR3, description: "Paint colour #rrggbb." },
+        dualColor: {
+          type: "object",
+          description: "A light / dark pair as the paint colour, instead of color: each side a colour #rrggbb.",
+          properties: { light: { ...COLOR3, description: "The colour in the light scheme, #rrggbb." }, dark: { ...COLOR3, description: "The colour in the dark scheme, #rrggbb." } },
+          required: ["light", "dark"],
+          additionalProperties: false
+        },
         secondaryColor: { ...COLOR3, description: "Second colour #rrggbb." },
         locked: { type: "boolean", description: "Lock the paint colour: brushes chosen later keep it instead of taking their default colour (default: unchanged; the editor starts unlocked)." }
       },
       additionalProperties: false
     },
     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.");
+    handler: ({ color, dualColor, secondaryColor, locked }) => {
+      if (color === void 0 && dualColor === void 0 && secondaryColor === void 0 && locked === void 0) throw new Error("Pass color, dualColor, secondaryColor or locked.");
+      if (color !== void 0 && dualColor !== void 0) throw new Error("Pass color or dualColor, not both.");
       if (color !== void 0) c.setColor(color);
+      if (dualColor !== void 0) c.setColor(dualColor);
       if (secondaryColor !== void 0) c.setSecondaryColor(secondaryColor);
       if (locked !== void 0) c.setColorLocked(locked);
       const s = c.getState();
-      return { color: s.color, secondaryColor: s.secondaryColor, locked: s.colorLocked };
+      return { color: s.color, secondaryColor: s.secondaryColor, locked: s.colorLocked, ...dualColor !== void 0 ? { dualColor: { light: dualColor.light.toLowerCase(), dark: dualColor.dark.toLowerCase() } } : {} };
     }
   });
   add({
@@ -17575,6 +17793,7 @@ export {
   EVOLUTION_BRUSH_FACETS,
   EVOLUTION_MUTATION_SCHEMA,
   EVOLUTION_SLIDERS,
+  EXTENSION_ASSET_REF,
   FERRO_CARRIER_RGB,
   FERRO_DEFAULT_GLOSS,
   FERRO_DEFAULT_METALLIC,

package/dist/paint-editor/serialize.d.cts

@@ -59,7 +59,9 @@ export interface SerializeOptions {
 }
 /** The document as JSON with inline PNG data URLs. */
 export declare function serializePaintDocument(state: PaintDocumentState, options?: SerializeOptions): SerializedPaintDocument;
-/** The document as JSON with each PNG uploaded to `store` once (by content). */
+/** How an extension field refers to a PNG in `assets`: `asset:<asset id>`. */
+export declare const EXTENSION_ASSET_REF = "asset:";
+/** The document as JSON with each PNG (layers and extension fields alike) uploaded to `store` once (by content). */
 export declare function serializePaintDocumentExternal(state: PaintDocumentState, store: PaintAssetStore, options?: SerializeOptions): Promise<SerializedPaintDocument>;
 export interface LoadedPaintDocument {
     state: PaintDocumentState;

package/dist/paint-editor/serialize.d.ts

@@ -59,7 +59,9 @@ export interface SerializeOptions {
 }
 /** The document as JSON with inline PNG data URLs. */
 export declare function serializePaintDocument(state: PaintDocumentState, options?: SerializeOptions): SerializedPaintDocument;
-/** The document as JSON with each PNG uploaded to `store` once (by content). */
+/** How an extension field refers to a PNG in `assets`: `asset:<asset id>`. */
+export declare const EXTENSION_ASSET_REF = "asset:";
+/** The document as JSON with each PNG (layers and extension fields alike) uploaded to `store` once (by content). */
 export declare function serializePaintDocumentExternal(state: PaintDocumentState, store: PaintAssetStore, options?: SerializeOptions): Promise<SerializedPaintDocument>;
 export interface LoadedPaintDocument {
     state: PaintDocumentState;

package/dist/paint-editor/stroke.d.cts

@@ -22,6 +22,7 @@ import { type PaperGrain } from './paper.cjs';
 import { type Sticker } from './stickers.cjs';
 import type { StickerArtLookup } from './sticker-art.cjs';
 import type { StickerRef, StickerVariant } from '../stickers/types.cjs';
+import type { DualColor } from '../color/dual.cjs';
 export interface StrokeSessionHost {
     /** Shows the layer's live surface (no history); `rects` are where it changed. */
     update(layerId: string, surface: TiledSurface, rects: RasterRect[]): void;
@@ -48,6 +49,8 @@ export interface StrokeSessionInit {
     seed: number;
     /** The paint colour as #rrggbb (recorded with the stroke). */
     colorHex: string;
+    /** The light / dark pair `colorHex` is one side of, when the colour came from one (recorded with the stroke). */
+    dualColor?: DualColor;
     /** The stroke's extra copies as affine maps (recorded with the stroke); `copies` holds all of them as engine copies. */
     affineCopies: readonly Affine[];
     copies: readonly StrokeCopy[];

package/dist/paint-editor/stroke.d.ts

@@ -22,6 +22,7 @@ import { type PaperGrain } from './paper.js';
 import { type Sticker } from './stickers.js';
 import type { StickerArtLookup } from './sticker-art.js';
 import type { StickerRef, StickerVariant } from '../stickers/types.js';
+import type { DualColor } from '../color/dual.js';
 export interface StrokeSessionHost {
     /** Shows the layer's live surface (no history); `rects` are where it changed. */
     update(layerId: string, surface: TiledSurface, rects: RasterRect[]): void;
@@ -48,6 +49,8 @@ export interface StrokeSessionInit {
     seed: number;
     /** The paint colour as #rrggbb (recorded with the stroke). */
     colorHex: string;
+    /** The light / dark pair `colorHex` is one side of, when the colour came from one (recorded with the stroke). */
+    dualColor?: DualColor;
     /** The stroke's extra copies as affine maps (recorded with the stroke); `copies` holds all of them as engine copies. */
     affineCopies: readonly Affine[];
     copies: readonly StrokeCopy[];

package/dist/paint-editor/strokes.d.cts

@@ -14,6 +14,7 @@ import type { MixerLoad } from '../paint/exchange.cjs';
 import { type Stencil } from './stencils.cjs';
 import { type PaintGradientSource } from '../paint/gradient-paint.cjs';
 import { type PaintEffectPaint } from './effect-paint.cjs';
+import { type DualColor } from '../color/dual.cjs';
 /** An affine map [a, b, c, d, e, f]: (x, y) → (a·x + b·y + e, c·x + d·y + f). */
 export type Affine = readonly [number, number, number, number, number, number];
 export declare const IDENTITY_AFFINE: Affine;
@@ -21,8 +22,17 @@ export interface RecordedStroke {
     id: string;
     layerId: string;
     brush: PaintBrush;
-    /** #rrggbb */
+    /**
+     * #rrggbb: the colour the document draws the stroke with. A dual-colour stroke on a stroke layer
+     * keeps its light side here, whoever painted it; on a pixel layer, the side it was painted in.
+     */
     color: string;
+    /**
+     * The light / dark pair the colour came from (both #rrggbb), when it came from one. A stroke
+     * layer shows it in the viewer's side (`PaintEditorController.setColorScheme`) without changing
+     * the document; a pixel layer's pixels stay as painted.
+     */
+    dualColor?: DualColor;
     /** Raw pen samples in document pixels, before smoothing. */
     points: PenPoint[];
     seed: number;

package/dist/paint-editor/strokes.d.ts

@@ -14,6 +14,7 @@ import type { MixerLoad } from '../paint/exchange.js';
 import { type Stencil } from './stencils.js';
 import { type PaintGradientSource } from '../paint/gradient-paint.js';
 import { type PaintEffectPaint } from './effect-paint.js';
+import { type DualColor } from '../color/dual.js';
 /** An affine map [a, b, c, d, e, f]: (x, y) → (a·x + b·y + e, c·x + d·y + f). */
 export type Affine = readonly [number, number, number, number, number, number];
 export declare const IDENTITY_AFFINE: Affine;
@@ -21,8 +22,17 @@ export interface RecordedStroke {
     id: string;
     layerId: string;
     brush: PaintBrush;
-    /** #rrggbb */
+    /**
+     * #rrggbb: the colour the document draws the stroke with. A dual-colour stroke on a stroke layer
+     * keeps its light side here, whoever painted it; on a pixel layer, the side it was painted in.
+     */
     color: string;
+    /**
+     * The light / dark pair the colour came from (both #rrggbb), when it came from one. A stroke
+     * layer shows it in the viewer's side (`PaintEditorController.setColorScheme`) without changing
+     * the document; a pixel layer's pixels stay as painted.
+     */
+    dualColor?: DualColor;
     /** Raw pen samples in document pixels, before smoothing. */
     points: PenPoint[];
     seed: number;