@pixerate/editor 0.243.0 → 0.244.0

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

@@ -32,6 +32,7 @@ export { BLEND_MODES, PAINTERLY_BLEND_MODES, isBlendMode, isPainterlyBlendMode,
 export * from './wet.cjs';
 export * from './wet-tools.cjs';
 export * from './thick.cjs';
+export { BACKLIGHT_SPILL, DEFAULT_BACKLIGHT_COLOR, backlightOf } from './backlight.cjs';
 export * from './thick-tools.cjs';
 export * from './replay.cjs';
 export * from './replay-tools.cjs';

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

@@ -32,6 +32,7 @@ export { BLEND_MODES, PAINTERLY_BLEND_MODES, isBlendMode, isPainterlyBlendMode,
 export * from './wet.js';
 export * from './wet-tools.js';
 export * from './thick.js';
+export { BACKLIGHT_SPILL, DEFAULT_BACKLIGHT_COLOR, backlightOf } from './backlight.js';
 export * from './thick-tools.js';
 export * from './replay.js';
 export * from './replay-tools.js';

package/dist/paint-editor/index.js

@@ -7,7 +7,7 @@ import {
   resolveExternalAssets,
   serializeLayers,
   serializeLayersExternal
-} from "../chunk-SRXWDOUI.js";
+} from "../chunk-7YQNKSQ7.js";
 import "../chunk-3CI7FRMK.js";
 import "../chunk-ZNA3IQZF.js";
 import {
@@ -44,7 +44,7 @@ import {
   pigmentOf,
   pointerPressure,
   wetSupport
-} from "../chunk-HLBTRSQJ.js";
+} from "../chunk-P3NIPIKS.js";
 import "../chunk-HVQVHUTV.js";
 import {
   writeZip
@@ -55,7 +55,7 @@ import {
   realPresenceClock,
   tweenPresenceCursor
 } from "../chunk-IVSWRVB4.js";
-import "../chunk-6L3WWIDW.js";
+import "../chunk-4EQY4TZJ.js";
 import {
   BRUSH_ID,
   BRUSH_ROTATIONS,
@@ -133,7 +133,7 @@ import {
   tiltToOrientation,
   toStrokePoint,
   usesPaintExchange
-} from "../chunk-HQZHOPNE.js";
+} from "../chunk-TBJEMELS.js";
 import "../chunk-M6DNZNVY.js";
 import "../chunk-WEIK3UYB.js";
 import "../chunk-PWBZH3FK.js";
@@ -2214,6 +2214,7 @@ function downloadBytes(bytes, fileName, mimeType) {
 // src/paint-editor/wet.ts
 var STROKE_WATER = 0.9;
 var STROKE_MASS = PIGMENT_UNIT * 2.5;
+var STROKE_LIGHT = 1.5;
 var COVERAGE_STEPS = 4096;
 function union2(a, b) {
   if (!a) return { ...b };
@@ -2245,8 +2246,10 @@ var WetStrokeDriver = class {
     this.medium = new WetMedium(init.world, init.laneId, {
       water: STROKE_WATER * Math.min(1, wet.water * (1 + thin)) * perDab,
       mass: STROKE_MASS * wet.pigment * (1 - 0.6 * thin) * perDab,
-      body: wet.body * (1 - thin)
+      body: wet.body * (1 - thin),
+      light: 0
     });
+    this.lightBase = wet.tool === "paint" ? STROKE_LIGHT * brush.light.amount * (1 - 0.6 * thin) * perDab : 0;
     const rates = exchangeRates(brush.behavior.pickup, brush.behavior.mix, wet.load, brush.behavior.mixing);
     this.states = copies.map((c, i) => ({
       walker: new PenDabWalker(brush, init.seed + i * 7919 | 0, c.linear),
@@ -2276,6 +2279,7 @@ var WetStrokeDriver = class {
   paint = [0, 0, 0];
   centre = [0, 0, 0];
   depth;
+  lightBase;
   sampler;
   sample = { rgb: [0, 0, 0], alpha: 1 };
   copies;
@@ -2374,6 +2378,7 @@ var WetStrokeDriver = class {
     switch (wet.tool) {
       case "paint": {
         const ex = st.exchange;
+        this.medium.options.light = this.lightBase * (brush.light.pressure ? d.pressure : 1);
         let flow = 1;
         const effect = this.init.effect;
         if (effect) {
@@ -2562,6 +2567,7 @@ var PaintWetLayers = class {
       const flow = this.settings.get(l.id)?.flow;
       return {
         base: translateSurface(l.base, left, top),
+        ...l.light ? { light: translateSurface(l.light, left, top) } : {},
         flow: l.flow && flow && flow.kind !== "none" ? flowField(flow, width, height) : l.flow
       };
     });
@@ -2601,7 +2607,7 @@ var PaintWetLayers = class {
     if (!w.hasLane(layerId)) {
       const base = this.host.layerSurface(layerId) ?? new TiledSurface(4, /* @__PURE__ */ new Map(), 0);
       const s = this.settingsOf(layerId, medium);
-      w.ensureLane(layerId, { params: s.params, base });
+      w.ensureLane(layerId, { params: s.params, base, light: this.host.layerLight(layerId) });
       const { width, height } = this.host.canvas();
       if (s.flow.kind !== "none") w.setFlow(layerId, flowField(s.flow, width, height), s.flow.strength);
     }
@@ -2659,6 +2665,7 @@ var PaintWetLayers = class {
       if (this.host.layerSurface(id) !== d.surface) surfaces.set(id, d.surface);
       rects.push(...d.changed);
     }
+    this.syncLights();
     if (surfaces.size) this.host.updateSurfaces(surfaces, rects);
     return rects;
   }
@@ -2674,9 +2681,21 @@ var PaintWetLayers = class {
       if (this.host.layerSurface(id) !== d.surface) surfaces.set(id, d.surface);
       rects.push(...d.changed);
     }
+    this.syncLights();
     if (surfaces.size) this.host.updateSurfaces(surfaces, rects);
     return rects;
   }
+  /** Shows each wet layer's live light paint (the light under it with the wet light shaded in). */
+  syncLights() {
+    const w = this.world;
+    if (!w) return;
+    const lights = /* @__PURE__ */ new Map();
+    for (const id of w.laneIds()) {
+      const l = w.lightDisplay(id);
+      if (l && this.host.layerLight(id) !== l) lights.set(id, l);
+    }
+    if (lights.size) this.host.updateLights(lights);
+  }
   /** Drops the wet layers whose paint has all dried (they become ordinary pixel layers). */
   retireDry() {
     const w = this.world;
@@ -2684,7 +2703,9 @@ var PaintWetLayers = class {
     for (const id of w.laneIds()) {
       if (w.isActive(id) || this.driver?.init.laneId === id) continue;
       const base = w.getBase(id);
+      const light = w.isLit(id) ? w.getLight(id) : null;
       w.removeLane(id);
+      if (light && this.host.layerLight(id) !== light) this.host.updateLights(/* @__PURE__ */ new Map([[id, light]]));
       this.host.updateSurfaces(/* @__PURE__ */ new Map([[id, base]]), []);
     }
   }
@@ -2803,6 +2824,12 @@ var PaintWetLayers = class {
     this.retireDry();
     return out;
   }
+  /** The layer's light paint with all its wet paint dried (`null` without a wet layer or light), without changing anything. */
+  bakedLight(layerId) {
+    const w = this.world;
+    if (!w?.hasLane(layerId) || !w.isLit(layerId)) return null;
+    return w.bakedLight(layerId);
+  }
   /** The layer's pixels with all its wet paint dried (deterministic), without changing anything. */
   bakedSurface(layerId) {
     const w = this.world;
@@ -3477,6 +3504,212 @@ function liveStrokeBounds(stroke) {
   return { x: Math.floor(x0 - pad), y: Math.floor(y0 - pad), width: Math.ceil(x1 - x0 + 2 * pad), height: Math.ceil(y1 - y0 + 2 * pad) };
 }
 
+// src/paint-editor/backlight.ts
+var DEFAULT_BACKLIGHT_COLOR = "#fff1d6";
+var BACKLIGHT_SPILL = { radius: 24, strength: 1.5 };
+var BLOCK_HEIGHT = 96;
+var VALLEY_GAIN = 0.35;
+function backlightOf(paper) {
+  return paper.backlight ?? 0;
+}
+var LIN = new Float64Array(256);
+for (let i = 0; i < 256; i++) LIN[i] = srgbToLinear(i / 255);
+function needAlpha(e, p) {
+  if (e < p) return 1 - e / p;
+  if (e > p) return (e - p) / (255 - p);
+  return 0;
+}
+function tilesUnder(surface, rect, offset, out) {
+  if (!surface) {
+    out.push(null);
+    return;
+  }
+  const x0 = Math.floor((rect.x - offset.x) / TILE);
+  const y0 = Math.floor((rect.y - offset.y) / TILE);
+  const x1 = Math.floor((rect.x - offset.x + rect.width - 1) / TILE);
+  const y1 = Math.floor((rect.y - offset.y + rect.height - 1) / TILE);
+  for (let ty = y0; ty <= y1; ty++) for (let tx = x0; tx <= x1; tx++) out.push(surface.tiles.get(tileKey(tx, ty)) ?? null);
+}
+var sameRefs = (a, b) => a.length === b.length && a.every((v, i) => v === b[i]);
+var BacklightCache = class {
+  tiles = /* @__PURE__ */ new Map();
+  key = "";
+  spillOf = null;
+  out = null;
+  /**
+   * The backlight layer's pixels for `layers` (bottom first) on `paper` over a `width` × `height`
+   * canvas, or `null` when the paper has no backlight. `spillFrom` is the committed painting (the
+   * spill is drawn from it, so a stroke in progress does not redo the blur every frame).
+   */
+  surface(paper, grain, width, height, layers, spillFrom) {
+    const amount = backlightOf(paper);
+    if (!(amount > 0)) return null;
+    const key = JSON.stringify([amount, paper.backlightColor ?? DEFAULT_BACKLIGHT_COLOR, paper.color, paper.depth, grain.flat, width, height, layers.length, layers.map((l) => [l.opacity, l.offset.x, l.offset.y, l.surface.channels])]);
+    if (key !== this.key) {
+      this.tiles.clear();
+      this.key = key;
+    }
+    const light = /* @__PURE__ */ new Map();
+    const color = /* @__PURE__ */ new Map();
+    const painted = /* @__PURE__ */ new Map();
+    const tilesX = Math.ceil(width / TILE);
+    const tilesY = Math.ceil(height / TILE);
+    const refs = [];
+    for (let ty = 0; ty < tilesY; ty++) {
+      for (let tx = 0; tx < tilesX; tx++) {
+        const rect = { x: tx * TILE, y: ty * TILE, width: Math.min(TILE, width - tx * TILE), height: Math.min(TILE, height - ty * TILE) };
+        refs.length = 0;
+        for (const l of layers) {
+          tilesUnder(l.surface, rect, l.offset, refs);
+          tilesUnder(l.thick?.height, rect, l.offset, refs);
+          tilesUnder(l.thick?.material, rect, l.offset, refs);
+        }
+        const k = tileKey(tx, ty);
+        let r = this.tiles.get(k);
+        if (!r || !sameRefs(r.refs, refs)) {
+          r = { refs: [...refs], ...computeTile(paper, grain, amount, rect, layers) };
+          this.tiles.set(k, r);
+        }
+        if (r.light) light.set(k, r.light);
+        if (r.color) color.set(k, r.color);
+        if (r.painted) painted.set(k, r.painted);
+      }
+    }
+    return { light: new TiledSurface(4, light, 0), color: new TiledSurface(4, color, 0), painted: new TiledSurface(1, painted, 0) };
+  }
+  /**
+   * The full Backlight layer: the light through the paint (`current`) plus the spill of the light
+   * through the committed paint (`committed`), both Linear Dodge. Cached on their tiles.
+   */
+  layer(current, committed, amount) {
+    let spill = null;
+    if (committed) {
+      const s = this.spillOf;
+      if (s && s.color.id === committed.color.id && s.painted.id === committed.painted.id) spill = s.out;
+      else {
+        spill = computeSpill(committed.color, committed.painted, { radius: BACKLIGHT_SPILL.radius, strength: BACKLIGHT_SPILL.strength * amount });
+        this.spillOf = { color: committed.color, painted: committed.painted, out: spill };
+      }
+    }
+    if (!spill) return current.light;
+    const parts = [...current.light.tiles.values(), ...spill.tiles.values()];
+    if (this.out && sameRefs(this.out.parts, parts)) return this.out.surface;
+    const keys = /* @__PURE__ */ new Set([...current.light.tiles.keys(), ...spill.tiles.keys()]);
+    const tiles = /* @__PURE__ */ new Map();
+    for (const key of keys) {
+      const a = current.light.tiles.get(key);
+      const b = spill.tiles.get(key);
+      const t = !a ? b : !b ? a : addTiles(a, b);
+      if (t) tiles.set(key, t);
+    }
+    const surface = new TiledSurface(4, tiles, 0);
+    this.out = { parts, surface };
+    return surface;
+  }
+};
+var full4 = (t) => {
+  if (t.data.length === TILE * TILE * 4) return t.data;
+  const out = new Uint8ClampedArray(TILE * TILE * 4);
+  const u = t.uniform ?? 0;
+  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 addTiles(a, b) {
+  const x = full4(a);
+  const y = full4(b);
+  const out = new Uint8ClampedArray(TILE * TILE * 4);
+  for (let i = 0; i < out.length; i += 4) {
+    const ay = y[i + 3] / 255;
+    const r = x[i] + y[i] * ay;
+    const g = x[i + 1] + y[i + 1] * ay;
+    const bl = x[i + 2] + y[i + 2] * ay;
+    if (r < 0.5 && g < 0.5 && bl < 0.5) continue;
+    out[i] = Math.round(r);
+    out[i + 1] = Math.round(g);
+    out[i + 2] = Math.round(bl);
+    out[i + 3] = 255;
+  }
+  return finishTile(out, 4, 0);
+}
+function computeTile(paper, grain, amount, rect, layers) {
+  const n = rect.width * rect.height;
+  const [p0, p1, p2] = hexToRgb8(paper.color);
+  const pb = [p0, p1, p2];
+  const pl = [Math.max(1e-4, LIN[p0]), Math.max(1e-4, LIN[p1]), Math.max(1e-4, LIN[p2])];
+  const [c0, c1, c2] = hexToRgb8(paper.backlightColor ?? DEFAULT_BACKLIGHT_COLOR);
+  const t0 = new Float32Array(n).fill(amount * LIN[c0]);
+  const t1 = new Float32Array(n).fill(amount * LIN[c1]);
+  const t2 = new Float32Array(n).fill(amount * LIN[c2]);
+  const depth = grain.flat ? 0 : paper.depth;
+  if (depth > 0) {
+    for (let y = 0, i = 0; y < rect.height; y++)
+      for (let x = 0; x < rect.width; x++, i++) {
+        const g = 1 + VALLEY_GAIN * depth * (0.5 - grain.at(rect.x + x + 0.5, rect.y + y + 0.5));
+        t0[i] *= g;
+        t1[i] *= g;
+        t2[i] *= g;
+      }
+  }
+  const clear = new Float32Array(n).fill(1);
+  for (const l of layers) {
+    const lr = { x: rect.x - l.offset.x, y: rect.y - l.offset.y, width: rect.width, height: rect.height };
+    if (!l.surface.tiles.size) continue;
+    const px = readRegion(l.surface, lr);
+    const h = l.thick?.height.tiles.size ? readRegion(l.thick.height, lr) : null;
+    const m = h && l.thick?.material.tiles.size ? readRegion(l.thick.material, lr) : null;
+    const op = l.opacity;
+    for (let i = 0; i < n; i++) {
+      const a8 = px[i * 4 + 3];
+      if (!a8 && !(h && h[i])) continue;
+      const a = a8 / 255;
+      let aMin = 0;
+      const tr = [1, 1, 1];
+      for (let c = 0; c < 3; c++) {
+        const e = a * px[i * 4 + c] + (1 - a) * pb[c];
+        aMin = Math.max(aMin, needAlpha(e, pb[c]));
+        tr[c] = Math.min(1, LIN[Math.round(e)] / pl[c]);
+      }
+      const hide = aMin < 1 && a > aMin ? (a - aMin) / (1 - aMin) : 0;
+      let k = 1 - hide;
+      if (h && h[i]) {
+        const ma = m ? m[i * 4 + 3] : 0;
+        const clarity = ma ? (255 - ma) / 254 : 0;
+        k *= 1 - Math.min(1, h[i] / BLOCK_HEIGHT) * (1 - clarity);
+      }
+      t0[i] *= 1 - op + op * tr[0] * k;
+      t1[i] *= 1 - op + op * tr[1] * k;
+      t2[i] *= 1 - op + op * tr[2] * k;
+      clear[i] *= 1 - op * Math.max(a, h && h[i] ? 1 : 0);
+    }
+  }
+  const light = new Uint8ClampedArray(TILE * TILE * 4);
+  const color = new Uint8ClampedArray(TILE * TILE * 4);
+  const painted = new Uint8ClampedArray(TILE * TILE);
+  for (let y = 0, i = 0; y < rect.height; y++) {
+    for (let x = 0; x < rect.width; x++, i++) {
+      const o = (y * TILE + x) * 4;
+      const add = [Math.min(1, t0[i]), Math.min(1, t1[i]), Math.min(1, t2[i])];
+      const mx = Math.max(add[0], add[1], add[2]);
+      if (mx > 0.5 / 255) {
+        light[o] = Math.round(add[0] * 255);
+        light[o + 1] = Math.round(add[1] * 255);
+        light[o + 2] = Math.round(add[2] * 255);
+        light[o + 3] = 255;
+      }
+      const pv = Math.round((1 - clear[i]) * 255);
+      if (pv && mx > 0.5 / 255) {
+        painted[y * TILE + x] = pv;
+        color[o] = Math.round(linearToSrgb(add[0]) * 255);
+        color[o + 1] = Math.round(linearToSrgb(add[1]) * 255);
+        color[o + 2] = Math.round(linearToSrgb(add[2]) * 255);
+        color[o + 3] = 255;
+      }
+    }
+  }
+  return { light: finishTile(light, 4, 0), color: finishTile(color, 4, 0), painted: finishTile(painted, 1, 0) };
+}
+
 // src/paint-editor/replay.ts
 function replayItems(doc) {
   const items = [];
@@ -3867,6 +4100,9 @@ var PaintEditorController = class _PaintEditorController {
   /** Light paint: each layer's spill settings (saved with the document, not undo steps; missing = the defaults). */
   lightSpills = {};
   lightCaches = /* @__PURE__ */ new Map();
+  /** Backlit paper: the light through the paint as drawn (live strokes too), and as committed (its spill). */
+  backlightView = new BacklightCache();
+  backlightCommitted = new BacklightCache();
   /** Live effect paint: playing and the frame rate cap (editor state), and the time the view shows. */
   effectPlaybackState = { playing: true, fps: 30 };
   effectTime = 0;
@@ -3928,6 +4164,12 @@ var PaintEditorController = class _PaintEditorController {
           this.doc = { ...this.doc, layers };
           this.emit(rects.length ? rects : "all");
         },
+        layerLight: (id) => this.doc.light?.[id] ?? null,
+        updateLights: (lights) => {
+          let light = this.doc.light;
+          for (const [id, surface] of lights) if (findLayer(this.doc.layers, id)) light = withLayerLight(light, id, surface);
+          this.doc = { ...this.doc, ...light ? { light } : {} };
+        },
         changed: () => {
         }
       },
@@ -5193,7 +5435,6 @@ var PaintEditorController = class _PaintEditorController {
     const brush = this.strokeBrush(init);
     const effect = this.strokeEffect(init, brush);
     if (brush.light.amount > 0) {
-      if (brush.engine === "wet") throw new PaintEditorError(`The ${brush.name} brush paints wet media, which doesn't take light yet (glowing watercolour is planned in #494); paint light with a dab or impasto light brush (list_brushes category light), or set light.amount to 0 (set_brush).`);
       if (brush.engine === "sticker") throw new PaintEditorError(`The ${brush.name} brush sprays stickers, which don't take light yet; paint light with a dab or particle light brush (list_brushes category light), or set light.amount to 0 (set_brush).`);
     }
     if (doc.liveStrokes?.[layer.id]) {
@@ -5376,7 +5617,8 @@ var PaintEditorController = class _PaintEditorController {
         const thick = ch ? { ...this.doc.thick ?? {}, [l.id]: ch } : this.doc.thick;
         const sprayed = s.stickers();
         const stickers = sprayed ? { ...this.doc.stickers ?? {}, [l.id]: [...this.doc.stickers?.[l.id] ?? [], ...sprayed] } : this.doc.stickers;
-        const light = withLayerLight(this.doc.light, l.id, s.lightChannel());
+        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);
         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 } : {} }, stroke)), wetStroke ? before : this.doc);
       }
     };
@@ -5410,13 +5652,14 @@ var PaintEditorController = class _PaintEditorController {
         const offset = s.init.wet ? { x: 0, y: 0 } : l.offset;
         const ch = s.thickChannels();
         const sprayed = s.stickers();
+        const lit = s.lightChannel() ?? (s.init.wet && this.wet.world?.hasLane(l.id) ? this.wet.world.lightDisplay(l.id) : null);
         out = withLiveStroke({
           ...out,
           layers: mapLayer(out.layers, l.id, () => ({ ...l, surface, offset })),
           strokes: [...out.strokes, stroke],
           ...ch ? { thick: { ...out.thick ?? {}, [l.id]: ch } } : {},
           ...sprayed ? { stickers: { ...out.stickers ?? {}, [l.id]: [...out.stickers?.[l.id] ?? [], ...sprayed] } } : {},
-          ...s.lightChannel() ? { light: withLayerLight(out.light, l.id, s.lightChannel()) } : {}
+          ...lit ? { light: withLayerLight(out.light, l.id, lit) } : {}
         }, stroke);
       }
     };
@@ -5565,6 +5808,7 @@ var PaintEditorController = class _PaintEditorController {
   clearLight(layerId) {
     this.requireIdle("clearing light");
     const l = this.paintTarget(layerId, "clear the light of");
+    if (this.wet.bakedLight(l.id)) this.dryLayersFirst([l.id]);
     const t = this.lightWithout([l.id]);
     if (!t.light) return { layerId: l.id, cleared: false };
     this.commit("Clear light", { ...this.doc, light: t.light });
@@ -5941,8 +6185,39 @@ var PaintEditorController = class _PaintEditorController {
     }
     return out;
   }
+  /** Visible pixel layers bottom first, as the backlight reads them (group opacities multiplied in). */
+  backlitLayers(layers, committed, opacity = 1, out = []) {
+    for (const l of layers) {
+      if (!l.visible) continue;
+      if (l.type === "group") this.backlitLayers(l.children, committed, opacity * l.opacity, out);
+      else if (isPixelLayer(l)) {
+        const thick = !committed && this.liveThick?.layerId === l.id ? this.liveThick.channels : this.doc.thick?.[l.id];
+        out.push({ surface: l.surface, offset: l.offset, opacity: opacity * l.opacity, ...thick ? { thick } : {} });
+      }
+    }
+    return out;
+  }
+  /**
+   * Backlit paper: the light that makes it through `base` (the layers as drawn), with the spill of
+   * the light through the committed painting, as a Linear Dodge (Add) layer for the top of the
+   * stack; `null` when the paper has no backlight.
+   */
+  backlightLayer(base) {
+    const paper = this.doc.paper;
+    const amount = backlightOf(paper);
+    if (!(amount > 0)) return null;
+    const { width, height } = this.doc.canvas;
+    const grain = paperGrain(paper);
+    const current = this.backlightView.surface(paper, grain, width, height, this.backlitLayers(base, false), null);
+    const committed = base === this.doc.layers ? current : this.backlightCommitted.surface(paper, grain, width, height, this.backlitLayers(this.doc.layers, true), null);
+    const surface = this.backlightView.layer(current, committed, amount);
+    return { type: "pixel", id: BACKLIGHT_LAYER_ID, name: "Backlight", visible: true, opacity: 1, blend: "linear-dodge", surface, offset: { x: 0, y: 0 } };
+  }
   renderLayers(options, view = false) {
-    let layers = this.lightLayers(this.litLayers((options.wet ?? "display") === "dried" ? this.driedLayers() : this.currentLayers()));
+    const base = (options.wet ?? "display") === "dried" ? this.driedLayers() : this.currentLayers();
+    let layers = this.lightLayers(this.litLayers(base));
+    const backlight = options.paper !== false && !options.layerIds ? this.backlightLayer(base) : null;
+    if (backlight) layers = [...layers, backlight];
     if (options.layerIds) {
       const picked = [];
       for (const id of options.layerIds) picked.push(findLayer(layers, id)?.layer ?? this.requireLayer(id));
@@ -6032,7 +6307,7 @@ var PaintEditorController = class _PaintEditorController {
     const light = {};
     for (const [id, t] of Object.entries(this.doc.light ?? {})) {
       if (!findLayer(this.doc.layers, id)) continue;
-      const saved = lightToJSON(t);
+      const saved = lightToJSON(this.wet.bakedLight(id) ?? t);
       if (saved) light[id] = saved;
     }
     if (Object.keys(light).length) ext.light = light;
@@ -6218,7 +6493,9 @@ var PaintEditorController = class _PaintEditorController {
    * pixels), and the composite as the merged image.
    */
   exportPsd() {
-    const dried = this.lightLayers(this.litLayers(this.driedLayers(this.doc.layers)));
+    const driedBase = this.driedLayers(this.doc.layers);
+    const backlight = this.backlightLayer(driedBase);
+    const dried = [...this.lightLayers(this.litLayers(driedBase)), ...backlight ? [backlight] : []];
     const { width, height, dpi } = this.doc.canvas;
     const paperPixels = this.compositePixels({ layerIds: [], paper: true });
     const paperLayer = {
@@ -6249,6 +6526,9 @@ var PaintEditorController = class _PaintEditorController {
       const one = names.length === 1;
       result.warnings.push(`${label} blending has no PSD equivalent; ${list} ${one ? "was" : "were"} written as ${std}, the nearest Photoshop mode, so ${one ? "it looks" : "they look"} different in Photoshop (the merged image is exact).`);
     }
+    if (backlight) {
+      result.warnings.push('Backlit paper is written as pixels: the light that comes through the paint is a "Backlight" Linear Dodge (Add) layer at the top. Opening the PSD again gives a plain pixel layer, not a backlight.');
+    }
     if (Object.values(this.doc.light ?? {}).some((l) => l.tiles.size)) {
       result.warnings.push('Light paint is written as pixels: each layer with its glow, and its spill as a "\u2039layer\u203A light" Linear Dodge (Add) layer above it. Opening the PSD again gives plain pixel layers, not editable light.');
     }
@@ -7265,6 +7545,7 @@ function withLayerLight(light, layerId, next) {
   else delete out[layerId];
   return out;
 }
+var BACKLIGHT_LAYER_ID = "__backlight";
 function insertAfter(layers, id, node) {
   const i = layers.findIndex((l) => l.id === id);
   if (i >= 0) return [...layers.slice(0, i + 1), node, ...layers.slice(i + 1)];
@@ -8259,7 +8540,7 @@ function createPaintWetTools(c) {
     {
       name: "advance_wet_paint",
       title: "Let the wet paint flow",
-      description: "Lets time pass for wet paint: the water spreads, runs downhill on a tilted canvas, granulates, blooms and evaporates, and pigment settles. Give steps (simulation steps; at the default 120 per second, 120 steps is one second) or seconds (default 1). Not an undo step, as time passing never is. Returns the steps run, the clock, stillWet and each wet layer\u2019s state. Paint dries by itself after a few thousand steps; dry_paint dries it at once.",
+      description: "Lets time pass for wet paint: the water spreads, runs downhill on a tilted canvas, granulates, blooms and evaporates, and pigment settles. Give steps (simulation steps; at the default 120 per second, 120 steps is one second) or seconds (default 1). Not an undo step, as time passing never is. Returns the steps run, the clock, stillWet and each wet layer\u2019s state. Paint dries by itself after a few thousand steps; dry_paint dries it at once. Wet light paint (wet brushes with light.amount) flows with the pigment and settles where it dries into the layer\u2019s light (get_light).",
       inputSchema: {
         type: "object",
         properties: {
@@ -8709,7 +8990,7 @@ var IMPASTO_BRUSH = {
 };
 var LIGHT_BRUSH = {
   type: "object",
-  description: "Light paint: the light the brush lays with its colour, glowing in the paint's own colour and spilling onto its surroundings (set_light_spill). Dab, particle, bristle, Mixer Brush and impasto brushes take it; wet and sticker brushes refuse light above 0. Missing fields keep their current values.",
+  description: "Light paint: the light the brush lays with its colour, glowing in the paint's own colour and spilling onto its surroundings (set_light_spill). Dab, particle, bristle, Mixer Brush, impasto and wet paint brushes take it (wet light flows, pools, granulates and blooms with the pigment until the paint dries, then is ordinary light paint); wet tools other than paint lay none, and sticker brushes refuse light above 0. Missing fields keep their current values.",
   properties: {
     amount: { type: "number", minimum: 0, maximum: 1, description: "Light each dab lays, scaled by its coverage and flow (0 none, default; 1 full)." },
     pressure: { type: "boolean", description: "Pressure scales the light (default false)." }
@@ -8940,7 +9221,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
   add({
     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).",
+    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", ...READ6 },
     handler: () => JSON.parse(JSON.stringify(c.document.paper))
@@ -8956,7 +9237,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
   add({
     name: "set_paper",
     title: "Set the paper",
-    description: "Changes the paper under the whole painting: a preset from list_papers and / or its settings. Grain depth decides how much grain-responsive brushes (pencil, pastel, charcoal) skip the valleys; changing it re-renders the paper but not strokes already painted. One undo step. Returns the paper.",
+    description: "Changes the paper under the whole painting: a preset from list_papers and / or its settings. Grain depth decides how much grain-responsive brushes (pencil, pastel, charcoal) skip the valleys; changing it re-renders the paper but not strokes already painted. backlight lights the paper from behind (the stained-glass preset has it on). One undo step. Returns the paper.",
     inputSchema: {
       type: "object",
       properties: {
@@ -8974,6 +9255,8 @@ function createPaintEditorToolProvider(controller, options = {}) {
         permeability: { type: "number", minimum: 0, maximum: 1, description: "Wet media: how freely water flows over the fibres (low: more ragged, slower spreading)." },
         roughness: { type: "number", minimum: 0, maximum: 1, description: "Wet media: how much the grain pins wet edges and catches granulating pigment." },
         metallic: { type: "number", minimum: 0, maximum: 1, description: "Metallic paper (gold or silver leaf, pearlescent card): the grain catches the light (see set_lighting). 0 by default." },
+        backlight: { type: "number", minimum: 0, maximum: 1, description: "Backlit paper (a lightbox, stained glass): light from behind the paper, 0 (none, the default) .. 1. Transparent glazes (watercolour, airbrush, thin marker) glow in their own colour; opaque paint (gouache, oil, solid ink) and thick paint block it; the light through paint spills softly around it. Nothing is repainted." },
+        backlightColor: { ...COLOR3, description: "The backlight\u2019s colour #rrggbb (default #fff1d6, warm white)." },
         name: { type: "string", minLength: 1, description: "Display name." }
       },
       additionalProperties: false
@@ -9148,7 +9431,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
   add({
     name: "list_brushes",
     title: "List brushes",
-    description: "Lists the brush library: built-in dry media (pencils, pastels, charcoal, airbrush, marker, ink, erasers), paint brushes (dirty round, multi-colour flat, palette dabber), blending tools (blender, smudge, pigment smudge, Mixer Brush), light paint (category light: glow gel, neon marker, light airbrush, spark trail; light is the amount they lay) and saved user brushes, with id, name, category, engine, size, grain response, rotation mode, whether it can pick up paint (wetCapable), its pick-up ratio, dirty and multi-colour mode, plus the active brush id.",
+    description: "Lists the brush library: built-in dry media (pencils, pastels, charcoal, airbrush, marker, ink, erasers), paint brushes (dirty round, multi-colour flat, palette dabber), blending tools (blender, smudge, pigment smudge, Mixer Brush), light paint (category light: glow gel, neon marker, light airbrush, spark trail, glow wash; light is the amount they lay) and saved user brushes, with id, name, category, engine, size, grain response, rotation mode, whether it can pick up paint (wetCapable), its pick-up ratio, dirty and multi-colour mode, plus the active brush id.",
     inputSchema: EMPTY3,
     annotations: { title: "List brushes", ...READ6 },
     handler: () => {
@@ -9332,7 +9615,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
   add({
     name: "paint_stroke",
     title: "Paint a brush stroke",
-    description: "Paints one stroke through points (document pixels, with optional pressure, time, tilt and barrel rotation) on a pixel layer with a library brush or the active one, optionally changed for this stroke. Grain-responsive brushes follow the paper; the mixer engine (mixer-brush) picks up and mixes paint already on the layer, the blender mixes nearby colours, the smudge drags paint, and dab brushes with behavior.pickup lift and carry paint, and wet brushes (engine wet: watercolour, gouache, add water, dry, blow, wet blend, wet smudge, blot) paint on the layer\u2019s wet layer, where the paint keeps moving until it dries (the result says wet: true while it is; see advance_wet_paint and dry_paint; a dry brush on wet paint dries it first; wet oil brushes blend into the wet oil they meet), impasto brushes (engine impasto: impasto brush, paint tube, palette knife, roller, gloop pen, metallic paint) lay thick paint whose relief is lit by set_lighting, particle and bristle brushes draw procedural marks, and sticker brushes spray editable stickers onto an empty or sticker layer (list_stickers). Guide stencils make strokes that start near them follow them; mask stencils keep paint inside them. The symmetry guide adds its mirror copies; with a tracing image that samples colours, a stroke without color takes the image colour at its first point. With an agent cursor (a director), the stroke is painted live along the points at the pace of their times. One undo step. Returns the layer id, changed bounds, dab count, the recorded strokeId (for replay_strokes), for wet brushes wet (paint still wet) and, for brushes that pick up paint, mixerLoad: what the brush carries after the stroke.",
+    description: "Paints one stroke through points (document pixels, with optional pressure, time, tilt and barrel rotation) on a pixel layer with a library brush or the active one, optionally changed for this stroke. Grain-responsive brushes follow the paper; the mixer engine (mixer-brush) picks up and mixes paint already on the layer, the blender mixes nearby colours, the smudge drags paint, and dab brushes with behavior.pickup lift and carry paint, and wet brushes (engine wet: watercolour, gouache, add water, dry, blow, wet blend, wet smudge, blot) paint on the layer\u2019s wet layer, where the paint keeps moving until it dries (the result says wet: true while it is; see advance_wet_paint and dry_paint; a dry brush on wet paint dries it first; wet oil brushes blend into the wet oil they meet; with light.amount, as glow-wash has, their light flows with the paint), impasto brushes (engine impasto: impasto brush, paint tube, palette knife, roller, gloop pen, metallic paint) lay thick paint whose relief is lit by set_lighting, particle and bristle brushes draw procedural marks, and sticker brushes spray editable stickers onto an empty or sticker layer (list_stickers). Guide stencils make strokes that start near them follow them; mask stencils keep paint inside them. The symmetry guide adds its mirror copies; with a tracing image that samples colours, a stroke without color takes the image colour at its first point. With an agent cursor (a director), the stroke is painted live along the points at the pace of their times. One undo step. Returns the layer id, changed bounds, dab count, the recorded strokeId (for replay_strokes), for wet brushes wet (paint still wet) and, for brushes that pick up paint, mixerLoad: what the brush carries after the stroke.",
     inputSchema: {
       type: "object",
       properties: {
@@ -10054,7 +10337,8 @@ var PAPER_SLIDERS = [
   { path: "absorption", label: "Absorption", min: 0, max: 1, step: 0.01 },
   { path: "permeability", label: "Permeability", min: 0, max: 1, step: 0.01 },
   { path: "roughness", label: "Roughness", min: 0, max: 1, step: 0.01 },
-  { path: "metallic", label: "Metallic", min: 0, max: 1, step: 0.01 }
+  { path: "metallic", label: "Metallic", min: 0, max: 1, step: 0.01 },
+  { path: "backlight", label: "Backlight", min: 0, max: 1, step: 0.01 }
 ];
 function readPath(obj, path) {
   let v = obj;
@@ -10110,7 +10394,8 @@ var PICKUP_SLIDERS = [
 ];
 function brushEngineControls(brush) {
   const c = engineControls(brush);
-  if (!c || !["dab", "mixer", "particle", "bristle", "impasto"].includes(brush.engine)) return c;
+  const wetPaint = brush.engine === "wet" && brush.wet?.tool === "paint";
+  if (!c || !(wetPaint || ["dab", "mixer", "particle", "bristle", "impasto"].includes(brush.engine))) return c;
   const extra = brush.engine === "impasto" ? [{ path: "impasto.rim", label: "Rim", min: 0, max: 1, step: 0.01 }, { path: "impasto.clarity", label: "Clarity", min: 0, max: 1, step: 0.01 }] : [];
   return { ...c, sliders: [...c.sliders, LIGHT_SLIDER, ...extra], light: true };
 }
@@ -10644,6 +10929,7 @@ function createPaintEditorDocument(controller, options = {}) {
   });
 }
 export {
+  BACKLIGHT_SPILL,
   BLEND_MENU_GROUPS,
   BLEND_MODES,
   BRUSH_ID,
@@ -10651,6 +10937,7 @@ export {
   BRUSH_SLIDERS,
   BUILTIN_BRUSHES,
   BristleStroke,
+  DEFAULT_BACKLIGHT_COLOR,
   DEFAULT_BEHAVIOR,
   DEFAULT_BRISTLE,
   DEFAULT_BRUSH_ID,
@@ -10776,6 +11063,7 @@ export {
   addPaintGradientStop,
   affineCopy,
   applyAffine,
+  backlightOf,
   brushEngineControls,
   brushLoadColor,
   brushLoadForStroke,

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

@@ -40,6 +40,13 @@ export interface PaperSettings {
     roughness: number;
     /** Metallic paper (gold or silver leaf, pearlescent card): the grain catches the light, 0..1 (default 0). */
     metallic?: number;
+    /**
+     * Backlit paper (a lightbox, stained glass): light from behind the paper, 0..1 (default 0: none).
+     * Transparent glazes glow in their own colour; opaque and thick paint block it (`backlight.ts`).
+     */
+    backlight?: number;
+    /** The backlight's colour #rrggbb (default warm white, `#fff1d6`). */
+    backlightColor?: string;
     /**
      * Where the grain's (0, 0) sits in document pixels (missing = the top-left). `extendCanvas` moves
      * it with the paint, so the texture stays under what was painted on it.

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

@@ -40,6 +40,13 @@ export interface PaperSettings {
     roughness: number;
     /** Metallic paper (gold or silver leaf, pearlescent card): the grain catches the light, 0..1 (default 0). */
     metallic?: number;
+    /**
+     * Backlit paper (a lightbox, stained glass): light from behind the paper, 0..1 (default 0: none).
+     * Transparent glazes glow in their own colour; opaque and thick paint block it (`backlight.ts`).
+     */
+    backlight?: number;
+    /** The backlight's colour #rrggbb (default warm white, `#fff1d6`). */
+    backlightColor?: string;
     /**
      * Where the grain's (0, 0) sits in document pixels (missing = the top-left). `extendCanvas` moves
      * it with the paint, so the texture stays under what was painted on it.