@pixerate/editor 0.242.0 → 0.244.0

package/dist/paint/wet/world.d.ts

@@ -17,6 +17,10 @@
  * - **Display.** Each lane has a `base` surface: the layer's pixels under the wet paint. `display`
  *   gives the base with every live tile shaded (`filmPixel`), as an ordinary RGBA surface for the
  *   compositor. Tiles that dry are baked into the base and their slots freed.
+ * - **Light paint.** Light is a fifth mass channel (suspended and settled), moving exactly as
+ *   pigment does. A lane's `light` surface (one channel, see `paint-editor/light.ts`) is the
+ *   light under the wet paint; `lightDisplay` shades the live light over it and drying bakes it
+ *   in, as the colour is.
  * - **Engine B (WebGPU).** With a GPU engine attached (`attachGpu`) and at least `gpuMinTiles` live
  *   tiles, the GPU keeps a mirror of the slots: each edit uploads the rows it changed, each batch
  *   runs on the GPU too, and `displayGpu` shades every stale tile there at once. In lead mode
@@ -30,8 +34,8 @@ import { type WetWorkerLayout } from './wasm.js';
 import type { WetGpuEngine } from './gpu.js';
 /** Wet layers a world can hold at once. */
 export declare const MAX_WET_LANES = 8;
-/** Tile slots at most (about 3.8 GB, inside wasm32's 4 GB). Water reaching a tile past this is lost. */
-export declare const MAX_WET_SLOTS = 352;
+/** Tile slots at most (about 3.75 GB, inside wasm32's 4 GB). Water reaching a tile past this is lost. */
+export declare const MAX_WET_SLOTS = 328;
 /** A flow map: a vector per document pixel, in cells per step² at strength 1. */
 export type WetFlowField = (x: number, y: number) => readonly [number, number];
 /** The paper as the simulation reads it. */
@@ -62,6 +66,8 @@ export interface WetLaneOptions {
     flow?: WetFlowField | null;
     /** Flow map strength (default 1 when a flow map is given). */
     flowStrength?: number;
+    /** The layer's light paint under the wet paint (one channel; default none). */
+    light?: TiledSurface | null;
 }
 /** Totals for one wet layer. */
 export interface WetLaneStats {
@@ -87,6 +93,8 @@ export interface WetSnapshot {
         flow: WetFlowField | null;
         flowStrength: number;
         base: TiledSurface;
+        light?: TiledSurface;
+        lit?: boolean;
     }>;
     /** Per active key: the current set and the deposit planes; and its last flags. */
     readonly slots: ReadonlyMap<number, {
@@ -177,6 +185,12 @@ export declare class WetWorld {
     getBase(id: string): TiledSurface;
     /** Replaces the pixels under a layer's wet paint. */
     setBase(id: string, base: TiledSurface): void;
+    /** The light paint under a layer's wet paint (one channel). */
+    getLight(id: string): TiledSurface;
+    /** Whether a layer has light paint, under its wet paint or in it. */
+    isLit(id: string): boolean;
+    /** Replaces the light paint under a layer's wet paint. */
+    setLight(id: string, light: TiledSurface): void;
     private pack;
     private touchAll;
     private laneIndexOf;
@@ -247,10 +261,10 @@ export declare class WetWorld {
     private addWaterAt;
     /**
      * Lays paint: `water` depth and pigment mass `pigment` (K r, g, b, S) per unit of coverage, or
-     * per pixel from `field` (4 values per pixel of `rect`). Pigment without water lands straight in
-     * the paper (settled).
+     * per pixel from `field` (4 values per pixel of `rect`), and `light` (light paint mass) per unit
+     * of coverage. Pigment and light without water land straight in the paper (settled).
      */
-    paint(id: string, rect: RasterRect, cov: ArrayLike<number> | null, water: number, pigment: ArrayLike<number> | null, field?: ArrayLike<number> | null): void;
+    paint(id: string, rect: RasterRect, cov: ArrayLike<number> | null, water: number, pigment: ArrayLike<number> | null, field?: ArrayLike<number> | null, light?: number): void;
     /** Damp paper: fills the paper's water towards its capacity by `amount` (0..1) × coverage, plus a thin film of surface water. */
     wetPaper(id: string, rect: RasterRect, cov: ArrayLike<number> | null, amount: number): void;
     /**
@@ -261,16 +275,17 @@ export declare class WetWorld {
     remove(id: string, rect: RasterRect, cov: ArrayLike<number> | null, water: number, suspended: number, settled: number, paperWater?: number): void;
     /** Pushes the water: adds velocity (`ux`, `uy` cells per step, each at most 0.1) × coverage. */
     push(id: string, rect: RasterRect, cov: ArrayLike<number> | null, ux: number, uy: number): void;
-    /** Blends wet paint: each wet cell's suspended pigment moves `strength` × coverage towards the footprint's mean. */
+    /** Blends wet paint: each wet cell's suspended pigment (and light) moves `strength` × coverage towards the footprint's mean. */
     blend(id: string, rect: RasterRect, cov: ArrayLike<number> | null, strength: number): void;
     /**
      * Drags wet paint by (`dx`, `dy`) cells: each footprint cell takes `strength` × coverage of the
-     * water and suspended pigment of the cell it came from (a smudge through wet paint).
+     * water and suspended pigment (and light) of the cell it came from (a smudge through wet paint).
      */
     drag(id: string, rect: RasterRect, cov: ArrayLike<number> | null, dx: number, dy: number, strength: number): void;
     /**
      * Re-wetting: lifts `amount` × coverage of the dried paint in the layer's pixels (`base`) back into
-     * the paper as settled pigment, so water can move it again. Only where there is surface water.
+     * the paper as settled pigment, so water can move it again, and the same share of its light
+     * paint (`light`) as settled light. Only where there is surface water.
      */
     rewet(id: string, rect: RasterRect, cov: ArrayLike<number> | null, amount: number, paper: readonly [number, number, number]): void;
     /**
@@ -284,6 +299,8 @@ export declare class WetWorld {
      * Returns whether any pixel changed.
      */
     private bakeKey;
+    /** `shadeSlot` for light paint: one channel over a light tile (see `shadeLightTile`); `null` when nothing would change. */
+    private shadeLightSlot;
     /**
      * Shades one slot over a base tile. `display`: the wet look (suspended + settled, wet paper a
      * little darker); `bake`: settled pigment only; `bake-all`: suspended and settled (dry now).
@@ -292,6 +309,8 @@ export declare class WetWorld {
     private shadeSlot;
     /** The layer's pixels with all its wet paint dried where it is (the bake of "dry on save"); changes nothing. */
     bakedSurface(id: string): TiledSurface;
+    /** The layer's light paint with all its wet paint dried where it is (`bakedSurface` for light); changes nothing. */
+    bakedLight(id: string): TiledSurface;
     /**
      * Sums over a footprint of a lane, weighted by coverage: `weight` (coverage), `water` (surface
      * depth), `wet` (coverage of wet cells), `pigment` (suspended, 4 channels), `settled` (4 channels).
@@ -323,6 +342,12 @@ export declare class WetWorld {
         changed: RasterRect[];
         pending: number;
     };
+    /**
+     * The layer's light paint with its live light shaded in (`null` when the layer has none): the
+     * light under the wet paint with each live tile's light over it. Like `display`, every stale
+     * tile is reshaded (light tiles are cheap: one channel, no colour maths).
+     */
+    lightDisplay(id: string): TiledSurface | null;
     /**
      * The water as an overlay tile (RGBA, blue, alpha from surface depth and damp paper) for a
      * document tile, or `null` where nothing is wet.
@@ -388,6 +413,7 @@ export declare class WetWorld {
 /** A layer's base and flow map in a moved snapshot (see `moveWetSnapshot`). */
 export interface WetSnapshotLaneMove {
     base?: TiledSurface;
+    light?: TiledSurface;
     flow?: WetFlowField | null;
 }
 /**

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

@@ -0,0 +1,77 @@
+/**
+ * Backlit paper: the paper as a light source behind the paint (a lightbox, stained glass). The
+ * light that makes it through the paint is drawn as one Linear Dodge (Add) layer, "Backlight", at
+ * the top of the stack (opaque pixels whose colour is the light added, so the sRGB blend adds
+ * exactly that; the linear light value is added as is, an approximation of adding light) (it shines through everything, so nothing composited above it may cover
+ * it), with a soft spill where it comes through paint, so a lit glaze lights its surroundings.
+ *
+ * Per pixel, the light starts as `backlight × backlightColor` (linear), a little stronger in the
+ * paper's valleys (thinner paper, by its grain depth), and passes through each visible pixel layer
+ * from the bottom up:
+ *
+ * - **Paint as a film over the paper.** A layer pixel (colour `c`, alpha `a`) over the paper `p`
+ *   shows `e = a·c + (1 − a)·p`. Its transmission is `T = min(1, e / p)` per channel (linear):
+ *   exact for a transparent glaze, whose film over the paper is `T·p` (the wet bake writes
+ *   watercolour that way). Alpha above the least the colour needs over the paper
+ *   (`aMin`, as `film.ts` computes it) is hiding: `hide = (a − aMin) / (1 − aMin)`, and the light
+ *   through is `(1 − hide)·T`. The wet bake writes gouache and oil with their hiding in alpha, and
+ *   opaque dry paint (alpha 1) hides by this rule too, so glazes glow in their own colour and
+ *   opaque paint blocks the light.
+ * - **Thick paint** blocks the light by its height; impasto clarity (material A) lets some through.
+ * - **Layer opacity** mixes towards no change. Blend modes are not modelled (every layer is read
+ *   as a film); over other layers rather than the paper the film rule is an approximation.
+ *
+ * Exact for watercolour straight over the paper; approximate for stacks of layers and for blend
+ * modes. Changing the backlight never repaints: it is a few numbers on the paper.
+ */
+import { TiledSurface } from '../raster/surface.cjs';
+import { type LightSpill } from './light.cjs';
+import { type PaperGrain, type PaperSettings } from './paper.cjs';
+import type { ThickChannels } from './thick.cjs';
+/** Default backlight colour: warm white, like a lightbox. */
+export declare const DEFAULT_BACKLIGHT_COLOR = "#fff1d6";
+/** Spill of the light that comes through paint (px, strength), at backlight 1. */
+export declare const BACKLIGHT_SPILL: Readonly<LightSpill>;
+/** One visible pixel layer as the backlight reads it, bottom first. */
+export interface BacklitLayer {
+    surface: TiledSurface;
+    offset: {
+        x: number;
+        y: number;
+    };
+    /** Effective opacity (its groups' opacities multiplied in). */
+    opacity: number;
+    thick?: ThickChannels;
+}
+/** The paper's backlight (0 when it has none). */
+export declare function backlightOf(paper: PaperSettings): number;
+/**
+ * Computes and caches the backlight per 256 px document tile: a tile is recomputed only when one of
+ * the layer tiles over it (or the paper, or the layer list) changed.
+ */
+export declare class BacklightCache {
+    private tiles;
+    private key;
+    private spillOf;
+    private out;
+    /**
+     * 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: PaperSettings, grain: PaperGrain, width: number, height: number, layers: readonly BacklitLayer[], spillFrom: BacklightCache | null): {
+        light: TiledSurface;
+        color: TiledSurface;
+        painted: TiledSurface;
+    } | null;
+    /**
+     * 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: {
+        light: TiledSurface;
+    }, committed: {
+        color: TiledSurface;
+        painted: TiledSurface;
+    } | null, amount: number): TiledSurface;
+}

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

@@ -0,0 +1,77 @@
+/**
+ * Backlit paper: the paper as a light source behind the paint (a lightbox, stained glass). The
+ * light that makes it through the paint is drawn as one Linear Dodge (Add) layer, "Backlight", at
+ * the top of the stack (opaque pixels whose colour is the light added, so the sRGB blend adds
+ * exactly that; the linear light value is added as is, an approximation of adding light) (it shines through everything, so nothing composited above it may cover
+ * it), with a soft spill where it comes through paint, so a lit glaze lights its surroundings.
+ *
+ * Per pixel, the light starts as `backlight × backlightColor` (linear), a little stronger in the
+ * paper's valleys (thinner paper, by its grain depth), and passes through each visible pixel layer
+ * from the bottom up:
+ *
+ * - **Paint as a film over the paper.** A layer pixel (colour `c`, alpha `a`) over the paper `p`
+ *   shows `e = a·c + (1 − a)·p`. Its transmission is `T = min(1, e / p)` per channel (linear):
+ *   exact for a transparent glaze, whose film over the paper is `T·p` (the wet bake writes
+ *   watercolour that way). Alpha above the least the colour needs over the paper
+ *   (`aMin`, as `film.ts` computes it) is hiding: `hide = (a − aMin) / (1 − aMin)`, and the light
+ *   through is `(1 − hide)·T`. The wet bake writes gouache and oil with their hiding in alpha, and
+ *   opaque dry paint (alpha 1) hides by this rule too, so glazes glow in their own colour and
+ *   opaque paint blocks the light.
+ * - **Thick paint** blocks the light by its height; impasto clarity (material A) lets some through.
+ * - **Layer opacity** mixes towards no change. Blend modes are not modelled (every layer is read
+ *   as a film); over other layers rather than the paper the film rule is an approximation.
+ *
+ * Exact for watercolour straight over the paper; approximate for stacks of layers and for blend
+ * modes. Changing the backlight never repaints: it is a few numbers on the paper.
+ */
+import { TiledSurface } from '../raster/surface.js';
+import { type LightSpill } from './light.js';
+import { type PaperGrain, type PaperSettings } from './paper.js';
+import type { ThickChannels } from './thick.js';
+/** Default backlight colour: warm white, like a lightbox. */
+export declare const DEFAULT_BACKLIGHT_COLOR = "#fff1d6";
+/** Spill of the light that comes through paint (px, strength), at backlight 1. */
+export declare const BACKLIGHT_SPILL: Readonly<LightSpill>;
+/** One visible pixel layer as the backlight reads it, bottom first. */
+export interface BacklitLayer {
+    surface: TiledSurface;
+    offset: {
+        x: number;
+        y: number;
+    };
+    /** Effective opacity (its groups' opacities multiplied in). */
+    opacity: number;
+    thick?: ThickChannels;
+}
+/** The paper's backlight (0 when it has none). */
+export declare function backlightOf(paper: PaperSettings): number;
+/**
+ * Computes and caches the backlight per 256 px document tile: a tile is recomputed only when one of
+ * the layer tiles over it (or the paper, or the layer list) changed.
+ */
+export declare class BacklightCache {
+    private tiles;
+    private key;
+    private spillOf;
+    private out;
+    /**
+     * 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: PaperSettings, grain: PaperGrain, width: number, height: number, layers: readonly BacklitLayer[], spillFrom: BacklightCache | null): {
+        light: TiledSurface;
+        color: TiledSurface;
+        painted: TiledSurface;
+    } | null;
+    /**
+     * 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: {
+        light: TiledSurface;
+    }, committed: {
+        color: TiledSurface;
+        painted: TiledSurface;
+    } | null, amount: number): TiledSurface;
+}

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

@@ -18,7 +18,7 @@ import { type BristleSettings, type ParticleSettings } from './procedural.cjs';
  */
 export type PaintBrushEngine = 'dab' | 'eraser' | 'mixer' | 'blender' | 'smudge' | 'wet' | 'impasto' | 'particle' | 'bristle' | 'sticker';
 export declare const PAINT_BRUSH_ENGINES: readonly PaintBrushEngine[];
-export type PaintBrushCategory = 'pencil' | 'pastel' | 'charcoal' | 'airbrush' | 'marker' | 'ink' | 'paint' | 'eraser' | 'blender' | 'smudge' | 'mixer' | 'watercolor' | 'wet-tool' | 'oil' | 'impasto' | 'procedural' | 'bristle' | 'sticker' | 'custom';
+export type PaintBrushCategory = 'pencil' | 'pastel' | 'charcoal' | 'airbrush' | 'marker' | 'ink' | 'paint' | 'eraser' | 'blender' | 'smudge' | 'mixer' | 'watercolor' | 'wet-tool' | 'oil' | 'impasto' | 'procedural' | 'bristle' | 'sticker' | 'light' | 'custom';
 export declare const PAINT_BRUSH_CATEGORIES: readonly PaintBrushCategory[];
 /**
  * What a wet brush does to the wet layer: `paint` (water and pigment), `water` (clear water;
@@ -81,8 +81,21 @@ export interface ImpastoSettings {
     thinner: number;
     /** Knife and brush: how much of the paint under the tool is dragged along (0..1). */
     drag: number;
+    /** Light paint: the bead's light is stronger where its surface turns away, as on backlit glass (0..1, default 0). */
+    rim: number;
+    /** Light paint: the middle of a bead lets the layers below show through, its edges stay solid (0..1, default 0). */
+    clarity: number;
 }
 export declare const DEFAULT_IMPASTO: Readonly<ImpastoSettings>;
+/** Light paint: how much light a brush lays with its colour (see `doc.light`). */
+export interface LightSettings {
+    /** Light each dab lays, scaled by its coverage and flow (0..1, default 0: none). */
+    amount: number;
+    /** Pressure scales the light (default false). */
+    pressure: boolean;
+}
+export declare const DEFAULT_LIGHT: Readonly<LightSettings>;
+export declare function normalizeLight(raw?: Partial<LightSettings>, base?: LightSettings): LightSettings;
 export declare function normalizeImpasto(raw?: Partial<ImpastoSettings>, base?: ImpastoSettings): ImpastoSettings;
 /** Multi-coloured brush: `tip` lays the colours across the tip, `dab` changes colour from dab to dab. */
 export type MultiColorMode = 'off' | 'tip' | 'dab';
@@ -181,6 +194,8 @@ export interface PaintBrush {
     bristle: BristleSettings;
     /** Sticker engine only: the stamps and how they are sprayed. */
     sticker: StickerSettings;
+    /** Light paint: the light it lays with its colour (amount 0: none). */
+    light: LightSettings;
     /**
      * The brush's own gradient paint (`@pixerate/editor/paint` `PaintGradientSource`), used instead
      * of the editor's paint; `null` (default): the editor's paint. Stops may be `paint` / `secondary`
@@ -199,7 +214,8 @@ export type BrushBehaviorInput = Partial<Omit<BrushBehavior, 'multicolor'>> & {
 };
 export declare function normalizeBehavior(raw?: BrushBehaviorInput, base?: BrushBehavior): BrushBehavior;
 /** Brush settings to change or read: any subset of a brush and of its blocks. */
-export type PaintBrushInput = Partial<Omit<PaintBrush, 'tip' | 'dynamics' | 'mixer' | 'behavior' | 'blender' | 'smudge' | 'wet' | 'impasto' | 'particle' | 'bristle' | 'sticker' | 'paint'>> & {
+export type PaintBrushInput = Partial<Omit<PaintBrush, 'tip' | 'dynamics' | 'mixer' | 'behavior' | 'blender' | 'smudge' | 'wet' | 'impasto' | 'particle' | 'bristle' | 'sticker' | 'paint' | 'light'>> & {
+    light?: Partial<LightSettings>;
     /** A gradient (or `null` for the editor's paint); a plain colour source clears it. */
     paint?: PaintSource | null;
     tip?: Partial<BrushSettings>;

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

@@ -18,7 +18,7 @@ import { type BristleSettings, type ParticleSettings } from './procedural.js';
  */
 export type PaintBrushEngine = 'dab' | 'eraser' | 'mixer' | 'blender' | 'smudge' | 'wet' | 'impasto' | 'particle' | 'bristle' | 'sticker';
 export declare const PAINT_BRUSH_ENGINES: readonly PaintBrushEngine[];
-export type PaintBrushCategory = 'pencil' | 'pastel' | 'charcoal' | 'airbrush' | 'marker' | 'ink' | 'paint' | 'eraser' | 'blender' | 'smudge' | 'mixer' | 'watercolor' | 'wet-tool' | 'oil' | 'impasto' | 'procedural' | 'bristle' | 'sticker' | 'custom';
+export type PaintBrushCategory = 'pencil' | 'pastel' | 'charcoal' | 'airbrush' | 'marker' | 'ink' | 'paint' | 'eraser' | 'blender' | 'smudge' | 'mixer' | 'watercolor' | 'wet-tool' | 'oil' | 'impasto' | 'procedural' | 'bristle' | 'sticker' | 'light' | 'custom';
 export declare const PAINT_BRUSH_CATEGORIES: readonly PaintBrushCategory[];
 /**
  * What a wet brush does to the wet layer: `paint` (water and pigment), `water` (clear water;
@@ -81,8 +81,21 @@ export interface ImpastoSettings {
     thinner: number;
     /** Knife and brush: how much of the paint under the tool is dragged along (0..1). */
     drag: number;
+    /** Light paint: the bead's light is stronger where its surface turns away, as on backlit glass (0..1, default 0). */
+    rim: number;
+    /** Light paint: the middle of a bead lets the layers below show through, its edges stay solid (0..1, default 0). */
+    clarity: number;
 }
 export declare const DEFAULT_IMPASTO: Readonly<ImpastoSettings>;
+/** Light paint: how much light a brush lays with its colour (see `doc.light`). */
+export interface LightSettings {
+    /** Light each dab lays, scaled by its coverage and flow (0..1, default 0: none). */
+    amount: number;
+    /** Pressure scales the light (default false). */
+    pressure: boolean;
+}
+export declare const DEFAULT_LIGHT: Readonly<LightSettings>;
+export declare function normalizeLight(raw?: Partial<LightSettings>, base?: LightSettings): LightSettings;
 export declare function normalizeImpasto(raw?: Partial<ImpastoSettings>, base?: ImpastoSettings): ImpastoSettings;
 /** Multi-coloured brush: `tip` lays the colours across the tip, `dab` changes colour from dab to dab. */
 export type MultiColorMode = 'off' | 'tip' | 'dab';
@@ -181,6 +194,8 @@ export interface PaintBrush {
     bristle: BristleSettings;
     /** Sticker engine only: the stamps and how they are sprayed. */
     sticker: StickerSettings;
+    /** Light paint: the light it lays with its colour (amount 0: none). */
+    light: LightSettings;
     /**
      * The brush's own gradient paint (`@pixerate/editor/paint` `PaintGradientSource`), used instead
      * of the editor's paint; `null` (default): the editor's paint. Stops may be `paint` / `secondary`
@@ -199,7 +214,8 @@ export type BrushBehaviorInput = Partial<Omit<BrushBehavior, 'multicolor'>> & {
 };
 export declare function normalizeBehavior(raw?: BrushBehaviorInput, base?: BrushBehavior): BrushBehavior;
 /** Brush settings to change or read: any subset of a brush and of its blocks. */
-export type PaintBrushInput = Partial<Omit<PaintBrush, 'tip' | 'dynamics' | 'mixer' | 'behavior' | 'blender' | 'smudge' | 'wet' | 'impasto' | 'particle' | 'bristle' | 'sticker' | 'paint'>> & {
+export type PaintBrushInput = Partial<Omit<PaintBrush, 'tip' | 'dynamics' | 'mixer' | 'behavior' | 'blender' | 'smudge' | 'wet' | 'impasto' | 'particle' | 'bristle' | 'sticker' | 'paint' | 'light'>> & {
+    light?: Partial<LightSettings>;
     /** A gradient (or `null` for the editor's paint); a plain colour source clears it. */
     paint?: PaintSource | null;
     tip?: Partial<BrushSettings>;

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

@@ -32,6 +32,7 @@ import { type PaintGuides, type PerspectiveGuide, type ReferenceImage, type Symm
 import { MixingPad, type MixingPadTool, type PadMixOptions } from './mixing-pad.cjs';
 import { type Stencil, type StencilInput } from './stencils.cjs';
 import { type Sticker } from './stickers.cjs';
+import { type LightSpill } from './light.cjs';
 import { type PaintView } from './view.cjs';
 import { PaintWetLayers, type PaintWetOptions, type WetEngineInfo, type WetGpuMode, type WetLayerInfo } from './wet.cjs';
 import { type WetParams, type WetTilt } from '../paint/wet/model.cjs';
@@ -314,6 +315,12 @@ export declare class PaintEditorController {
     private dirty;
     private seedCounter;
     private strokeCounter;
+    /** Light paint: each layer's spill settings (saved with the document, not undo steps; missing = the defaults). */
+    private lightSpills;
+    private readonly lightCaches;
+    /** Backlit paper: the light through the paint as drawn (live strokes too), and as committed (its spill). */
+    private readonly backlightView;
+    private readonly backlightCommitted;
     /** Live effect paint: playing and the frame rate cap (editor state), and the time the view shows. */
     private effectPlaybackState;
     private effectTime;
@@ -731,6 +738,24 @@ export declare class PaintEditorController {
         bounds: RasterRect | null;
         layerIds: string[];
     };
+    /** The document's `light` without these layers (as a spread: `{}` when unchanged). */
+    private lightWithout;
+    private lightSpillOf;
+    /** A layer's light paint: whether it has any, where (document pixels), its brightest value 0..255, and its spill. */
+    lightOf(layerId?: string): {
+        layerId: string;
+        hasLight: boolean;
+        bounds: RasterRect | null;
+        peak: number;
+        spill: LightSpill;
+    };
+    /** How far a layer's light spills (px; 0 turns it off) and how strongly (0..2). Saved with the document, not an undo step; nothing is repainted. */
+    setLightSpill(layerId: string | undefined, update: Partial<LightSpill>): LightSpill;
+    /** Takes a layer's light away; its paint keeps its colour. One undo step. Returns whether there was any. */
+    clearLight(layerId?: string): {
+        layerId: string;
+        cleared: boolean;
+    };
     /** The document's `thick` without these layers (as a spread: `{}` when unchanged). */
     private thickWithout;
     /** Where the light comes from for thick paint and metallic paper. */
@@ -889,6 +914,20 @@ export declare class PaintEditorController {
     private driedLayers;
     /** The layers with thick paint lit (each thick layer's pixels replaced by its lit tiles). */
     private litLayers;
+    /**
+     * Light paint over the (lit) layers: glow, rim and clarity in each layer's pixels, and its spill
+     * as a Linear Dodge (Add) layer directly above it (from the painting as committed, so a stroke in
+     * progress does not redraw the blur every frame).
+     */
+    private lightLayers;
+    /** Visible pixel layers bottom first, as the backlight reads them (group opacities multiplied in). */
+    private backlitLayers;
+    /**
+     * 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.
+     */
+    private backlightLayer;
     private renderLayers;
     /**
      * Composites the viewport stack (paper, view-only underlays, layers with the live stroke) tile by

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

@@ -32,6 +32,7 @@ import { type PaintGuides, type PerspectiveGuide, type ReferenceImage, type Symm
 import { MixingPad, type MixingPadTool, type PadMixOptions } from './mixing-pad.js';
 import { type Stencil, type StencilInput } from './stencils.js';
 import { type Sticker } from './stickers.js';
+import { type LightSpill } from './light.js';
 import { type PaintView } from './view.js';
 import { PaintWetLayers, type PaintWetOptions, type WetEngineInfo, type WetGpuMode, type WetLayerInfo } from './wet.js';
 import { type WetParams, type WetTilt } from '../paint/wet/model.js';
@@ -314,6 +315,12 @@ export declare class PaintEditorController {
     private dirty;
     private seedCounter;
     private strokeCounter;
+    /** Light paint: each layer's spill settings (saved with the document, not undo steps; missing = the defaults). */
+    private lightSpills;
+    private readonly lightCaches;
+    /** Backlit paper: the light through the paint as drawn (live strokes too), and as committed (its spill). */
+    private readonly backlightView;
+    private readonly backlightCommitted;
     /** Live effect paint: playing and the frame rate cap (editor state), and the time the view shows. */
     private effectPlaybackState;
     private effectTime;
@@ -731,6 +738,24 @@ export declare class PaintEditorController {
         bounds: RasterRect | null;
         layerIds: string[];
     };
+    /** The document's `light` without these layers (as a spread: `{}` when unchanged). */
+    private lightWithout;
+    private lightSpillOf;
+    /** A layer's light paint: whether it has any, where (document pixels), its brightest value 0..255, and its spill. */
+    lightOf(layerId?: string): {
+        layerId: string;
+        hasLight: boolean;
+        bounds: RasterRect | null;
+        peak: number;
+        spill: LightSpill;
+    };
+    /** How far a layer's light spills (px; 0 turns it off) and how strongly (0..2). Saved with the document, not an undo step; nothing is repainted. */
+    setLightSpill(layerId: string | undefined, update: Partial<LightSpill>): LightSpill;
+    /** Takes a layer's light away; its paint keeps its colour. One undo step. Returns whether there was any. */
+    clearLight(layerId?: string): {
+        layerId: string;
+        cleared: boolean;
+    };
     /** The document's `thick` without these layers (as a spread: `{}` when unchanged). */
     private thickWithout;
     /** Where the light comes from for thick paint and metallic paper. */
@@ -889,6 +914,20 @@ export declare class PaintEditorController {
     private driedLayers;
     /** The layers with thick paint lit (each thick layer's pixels replaced by its lit tiles). */
     private litLayers;
+    /**
+     * Light paint over the (lit) layers: glow, rim and clarity in each layer's pixels, and its spill
+     * as a Linear Dodge (Add) layer directly above it (from the painting as committed, so a stroke in
+     * progress does not redraw the blur every frame).
+     */
+    private lightLayers;
+    /** Visible pixel layers bottom first, as the backlight reads them (group opacities multiplied in). */
+    private backlitLayers;
+    /**
+     * 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.
+     */
+    private backlightLayer;
     private renderLayers;
     /**
      * Composites the viewport stack (paper, view-only underlays, layers with the live stroke) tile by

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

@@ -8,6 +8,7 @@
  * same layer tree loads in both editors), with the paper as plain settings.
  */
 import type { RasterGroupLayer, RasterLayer, RasterPixelLayer } from '../raster/layers.cjs';
+import { type TiledSurface } from '../raster/surface.cjs';
 import { type PaperSettings } from './paper.cjs';
 import type { RecordedStroke } from './strokes.cjs';
 import type { WetEvent } from './wet.cjs';
@@ -48,6 +49,8 @@ export interface PaintDocumentState {
      * stroke's brush, colour and points stay editable (`updateStroke`).
      */
     liveStrokes?: Readonly<Record<string, RecordedStroke[]>>;
+    /** Light paint: each layer's light channel, 0..255 per pixel in layer space (layers without light are missing). See `light.ts`. */
+    light?: Readonly<Record<string, TiledSurface>>;
     /** Thick paint: each layer's height and material channels (layers without relief are missing). */
     thick?: Readonly<Record<string, ThickChannels>>;
     /** Effect layers: the provider effect each one is drawn from (layers that are gone are ignored). */

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

@@ -8,6 +8,7 @@
  * same layer tree loads in both editors), with the paper as plain settings.
  */
 import type { RasterGroupLayer, RasterLayer, RasterPixelLayer } from '../raster/layers.js';
+import { type TiledSurface } from '../raster/surface.js';
 import { type PaperSettings } from './paper.js';
 import type { RecordedStroke } from './strokes.js';
 import type { WetEvent } from './wet.js';
@@ -48,6 +49,8 @@ export interface PaintDocumentState {
      * stroke's brush, colour and points stay editable (`updateStroke`).
      */
     liveStrokes?: Readonly<Record<string, RecordedStroke[]>>;
+    /** Light paint: each layer's light channel, 0..255 per pixel in layer space (layers without light are missing). See `light.ts`. */
+    light?: Readonly<Record<string, TiledSurface>>;
     /** Thick paint: each layer's height and material channels (layers without relief are missing). */
     thick?: Readonly<Record<string, ThickChannels>>;
     /** Effect layers: the provider effect each one is drawn from (layers that are gone are ignored). */