@pixerate/editor 0.273.0 → 0.275.0

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

@@ -55,7 +55,13 @@ import { EffectsSlot } from '../effects/helpers.cjs';
 import type { EffectDescription, EffectProvider, EffectValue } from '../effects/types.cjs';
 import { type PaintEffectPaint } from './effect-paint.cjs';
 import { type PaintEffectPlace, type PaintEffectSource, type PaintPaperEffect, type PaperEffectBlend } from './effects.cjs';
-import { type PaintLighting } from './thick.cjs';
+import { type PaintLighting, type PaintViewTilt } from './thick.cjs';
+import { type HeatSample, type HeatStats, type UvLightSettings } from './heat.cjs';
+import { type PaintMutationAnswerInput, type PaintMutationAnswerResult, type PaintMutationInfo, type PaintMutationReadResult, type PaintMutationRequestListener } from './mutation.cjs';
+import type { PaintDirector } from './presence.cjs';
+import type { PresenceActorInfo } from '../animation/presence.cjs';
+import { type PaintProposals } from './collaboration.cjs';
+import { type BreedStrokesResult, type ProposalGenomeResult, type StrokeMutationRates } from './evolution.cjs';
 export declare class PaintEditorError extends Error {
     constructor(message: string);
 }
@@ -144,6 +150,8 @@ export interface PaintEditorState {
     /** What the Mixer Brush carries between strokes. */
     mixerLoad: MixerLoad;
     view: PaintView;
+    /** View tilt for thin-film iridescence and specular highlights (-1..1, default {x: 0, y: 0}; editor state, not saved with the document). */
+    viewTilt: PaintViewTilt;
     hand: Hand;
     /** Live effect paint: whether strokes on stroke layers play their effect, the frame rate cap and the time (ms) the view shows. Editor state. */
     effectPlayback: {
@@ -171,6 +179,14 @@ export interface PaintEditorState {
     stroking: boolean;
     /** Wet media. */
     wet: PaintWetStateInfo;
+    /** The UV / blacklight view setting (saved with the document, not undo steps). */
+    uvLight: UvLightSettings;
+    /** The coarse heat field's temperature summary. */
+    heat: HeatStats;
+    /** Pending and active mutation exchanges (editor state, not saved with the document). */
+    mutations: readonly PaintMutationInfo[];
+    /** Whether an agent is listening for mutation requests (`onMutationRequest` or `setMutationAgentConnected`). */
+    hasMutationAgent: boolean;
     /** Increments on every change. */
     version: number;
 }
@@ -206,6 +222,8 @@ export interface PaintLayerInfo {
     liveStrokes?: number;
     /** How many live layer effects (glows, shadows, strokes…) it has, when any (`getLayerEffects`). */
     effects?: number;
+    /** A temporary layer created for a dry mutation stroke (fades away once claimed or merges down if unanswered). */
+    temporary?: boolean;
 }
 /** A live stroke as it is painted (`onStrokeSample`), for agents that paint along with the user. */
 export interface PaintStrokeSample {
@@ -517,9 +535,17 @@ export declare class PaintEditorController {
     private readonly wetOptions;
     /** Where the light comes from for thick paint (saved with the document, not undo steps). */
     private lighting;
+    /** Where the viewer looks from for thin-film iridescence and specular highlights (editor state, not saved with the document). */
+    private viewTilt;
     private readonly litCaches;
     /** The live impasto stroke's channels. */
     private liveThick;
+    /** The UV / blacklight setting (saved with the document, not undo steps). */
+    private uvLight;
+    private readonly uvCaches;
+    private readonly thermoCaches;
+    private liveFluor;
+    private liveThermo;
     /** Set while an operation that changes wet paint runs: the simulation before it (for undo). */
     private wetOp;
     /** The effects provider slot (see `setEffectsProvider`). */
@@ -534,6 +560,15 @@ export declare class PaintEditorController {
     private readonly rasterizeSticker;
     private readonly effectsRenderer;
     private paperEffectNodeCache;
+    private mutations;
+    private nextMutationId;
+    private readonly mutationListeners;
+    private mutationAgentConnected;
+    private mutationDirector;
+    private readonly heldEvaporation;
+    private readonly tempLayerTargets;
+    private answeringMutation;
+    private lastMutationTick;
     constructor(options?: PaintEditorOptions);
     subscribe(listener: () => void): () => void;
     /**
@@ -1157,12 +1192,81 @@ export declare class PaintEditorController {
         layerId: string;
         cleared: boolean;
     };
+    private fluorWithout;
+    private thermoWithout;
+    /** The UV / blacklight view setting. */
+    getUvLight(): UvLightSettings;
+    /** Layers that carry UV-fluorescent ink. */
+    fluorescentLayerIds(): string[];
+    /** Layers that carry thermochromic ink. */
+    thermochromicLayerIds(): string[];
+    /**
+     * Switches or tunes the virtual UV / blacklight (`on`, `strength` 0..2, `ambient` 0..1). When
+     * `on` is true, the composite dims to `ambient` and fluorescent ink (`brush.fluorescence`) glows
+     * in its stroke colour with a Linear Dodge halo. Saved with the document, not an undo step.
+     */
+    setUvLight(update: Partial<UvLightSettings>): UvLightSettings;
+    /**
+     * Reads the document's heat field: its temperature summary (`peak`, `mean`, `hotCells`) and,
+     * when `points` are given (document pixels), the bilinearly sampled temperature (0..1) at each.
+     */
+    getHeat(points?: readonly {
+        x: number;
+        y: number;
+    }[]): HeatStats & {
+        samples: HeatSample[];
+        thermochromicLayerIds: string[];
+    };
+    /**
+     * Warms (or with `temperature` 0 cools) the canvas heat field along `points` (document pixels)
+     * with a soft brush of `radius` px (default 28) towards `temperature` 0..1 (default 1). Where
+     * temperature reaches `HEAT_DRY_THRESHOLD` (0.5), any wet paint on those tiles dries at once.
+     * One undo step.
+     */
+    paintHeat(options: {
+        points: readonly {
+            x: number;
+            y: number;
+        }[];
+        radius?: number;
+        temperature?: number;
+    }): HeatStats & {
+        bounds: RasterRect | null;
+        dried: Array<{
+            layerId: string;
+            bounds: RasterRect | null;
+        }>;
+    };
+    /**
+     * Advances the heat field by `steps` simulation steps (1..200, default 10): heat diffuses into
+     * neighbouring cells and cools towards 0 by Newtonian cooling. Newly heated tiles above the dry
+     * threshold dry any wet paint on them. Not an undo step (time passing never is).
+     */
+    advanceHeat(stepsOrOptions?: number | {
+        steps?: number;
+    }): HeatStats & {
+        steps: number;
+        dried: Array<{
+            layerId: string;
+            bounds: RasterRect | null;
+        }>;
+    };
+    /** Cools the whole canvas heat field to 0 at once (one undo step when anything was warm). */
+    clearHeat(): {
+        cleared: boolean;
+    };
+    /** Dries any wet paint on tiles where `field` is at or above `HEAT_DRY_THRESHOLD`. */
+    private dryWetFromHeat;
     /** 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. */
     getLighting(): PaintLighting;
     /** Moves the light (thick paint and metallic paper are relit; nothing is repainted). Saved with the document, not an undo step. */
     setLighting(update: Partial<PaintLighting>): PaintLighting;
+    /** Where the viewer looks from for thin-film iridescence and specular highlights (-1..1; editor state, not saved with the document). */
+    getViewTilt(): PaintViewTilt;
+    /** Tilts the view vector for thin-film iridescence and specular highlights (-1..1; editor state, not saved with the document, not an undo step). */
+    setViewTilt(update: Partial<PaintViewTilt>): PaintViewTilt;
     /** A layer's relief: where it is, its highest point (0..255) and its tiles; `null` when it has none. */
     reliefOf(layerId?: string): {
         layerId: string;
@@ -1313,6 +1417,14 @@ export declare class PaintEditorController {
     private tracingNode;
     /** The layers with every wet layer dried where it is (what saving and exporting see). */
     private driedLayers;
+    /** The layers with thermochromic paint shifted toward its hot colour where the canvas is warm. */
+    private thermoLayers;
+    /**
+     * Under the UV blacklight: every pixel layer's daylight paint dims to `uvLight.ambient`, any
+     * fluorescent ink (`doc.fluor[id]`) glows in its own colour, and each fluorescent layer casts a
+     * Linear Dodge (`::uv`) spill layer directly above it.
+     */
+    private uvLayers;
     /** The layers with thick paint lit (each thick layer's pixels replaced by its lit tiles). */
     private litLayers;
     /**
@@ -1690,8 +1802,94 @@ export declare class PaintEditorController {
     removeMixingPad(id: string): SavedMixingPadInfo;
     private mixingPadJSON;
     private readMixingPad;
+    /**
+     * Hears each mutation once it has settled (`settle` seconds after the user's last mutation
+     * stroke). Registering a listener marks an agent as connected (`state.hasMutationAgent`).
+     */
+    onMutationRequest(listener: PaintMutationRequestListener): () => void;
+    /** Marks whether a mutation-answering agent is connected (for hosts that wake agents via tools). */
+    setMutationAgentConnected(connected: boolean): void;
+    /** Attaches a `PaintDirector` so `answerMutation` and `readMutation` animate the agent's cursor. */
+    setMutationDirector(director: PaintDirector | null): void;
+    /** Lists pending mutations (or all mutations when `includeAll` is true). */
+    listMutations(options?: {
+        includeAll?: boolean;
+    }): PaintMutationInfo[];
+    /** One mutation by id (`undefined` when unknown). */
+    getMutation(id: string): PaintMutationInfo | undefined;
+    /**
+     * Claims a mutation (`id`) and starts its fade. Returns the strokes (points, colour, brush), a
+     * PNG of the area around them (`cropPng`), and a preview of the whole painting (`canvasPng`) so
+     * the agent can choose where to answer. Refused if already claimed, answered or declined.
+     */
+    readMutation(id: string, options?: {
+        actor?: string;
+        padding?: number;
+        maxSide?: number;
+    }): PaintMutationReadResult;
+    /**
+     * Paints the agent's answer to a claimed mutation (`id`). When a `PaintDirector` is attached (or
+     * passed in `options`), the agent's cursor is seen painting live; all strokes commit as one undo
+     * step with origin `agent:<id>`. A second answer to the same id is refused.
+     */
+    answerMutation(id: string, input: PaintMutationAnswerInput, options?: {
+        director?: PaintDirector;
+        actor?: PresenceActorInfo;
+    }): Promise<PaintMutationAnswerResult>;
+    /**
+     * Gives up on a mutation (`id`) without answering. The user's paint stays as ordinary paint (wet
+     * strokes stay in the wet layer, and dry temporary layers merge down into their target layer).
+     */
+    declineMutation(id: string, reason?: string): PaintMutationInfo;
+    /**
+     * Advances mutation timers (`settle`, `patience`, and dry temporary-layer `fade`) by `seconds`
+     * of simulated time. Called automatically from `tickMutations` and `advanceWet`.
+     */
+    advanceMutations(seconds: number): void;
+    /** Steps mutation timers with the wall clock (`performance.now()`, in ms). */
+    tickMutations(now: number): void;
+    private toMutationInfo;
+    private recordMutationStroke;
+    private holdMutationEvaporation;
+    private releaseMutationEvaporation;
+    private finishWetMutationsOnDry;
+    private expireMutation;
+    private keepMutationPaint;
+    private mergeTempLayerIntoTarget;
+    private removeTempMutationLayer;
+    private reconcileMutationsAfterUndo;
+    private resetMutations;
     /** A layer's tile surface (live while stroking), for thumbnails. */
     layerSurface(id: string): TiledSurface | null;
+    private proposalsStore;
+    /** The pending paint proposals store attached to this editor (created on demand). */
+    get proposals(): PaintProposals;
+    /** Attaches an external `PaintProposals` store so tools and panels share it. */
+    attachProposals(store: PaintProposals): void;
+    /**
+     * Breeds `count` (`2..12`, default `4`) mutated variants from `1..16` recorded strokes as
+     * pending paint proposals, generated one after another through `previewPaint`.
+     */
+    breedStrokes(options: {
+        strokeIds: readonly string[];
+        count?: number;
+        mutation?: StrokeMutationRates;
+        seed?: number;
+        origin?: string;
+    }): BreedStrokesResult;
+    /**
+     * Breeds `count` (`2..12`, default `4`) variants from `1` pending proposal (mutation) or `2`
+     * pending proposals (crossover + mutation), generated one after another through `previewPaint`.
+     */
+    breedProposal(options: {
+        proposalIds: readonly string[];
+        count?: number;
+        mutation?: StrokeMutationRates;
+        seed?: number;
+        origin?: string;
+    }): BreedStrokesResult;
+    /** Returns the full stroke genome records (`RecordedStrokeJSON[]`) of a pending paint proposal. */
+    getProposalGenome(proposalId: string): ProposalGenomeResult;
 }
 export type { Tile };
 /** Largest tracing or reference image side, in pixels. */

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

@@ -55,7 +55,13 @@ import { EffectsSlot } from '../effects/helpers.js';
 import type { EffectDescription, EffectProvider, EffectValue } from '../effects/types.js';
 import { type PaintEffectPaint } from './effect-paint.js';
 import { type PaintEffectPlace, type PaintEffectSource, type PaintPaperEffect, type PaperEffectBlend } from './effects.js';
-import { type PaintLighting } from './thick.js';
+import { type PaintLighting, type PaintViewTilt } from './thick.js';
+import { type HeatSample, type HeatStats, type UvLightSettings } from './heat.js';
+import { type PaintMutationAnswerInput, type PaintMutationAnswerResult, type PaintMutationInfo, type PaintMutationReadResult, type PaintMutationRequestListener } from './mutation.js';
+import type { PaintDirector } from './presence.js';
+import type { PresenceActorInfo } from '../animation/presence.js';
+import { type PaintProposals } from './collaboration.js';
+import { type BreedStrokesResult, type ProposalGenomeResult, type StrokeMutationRates } from './evolution.js';
 export declare class PaintEditorError extends Error {
     constructor(message: string);
 }
@@ -144,6 +150,8 @@ export interface PaintEditorState {
     /** What the Mixer Brush carries between strokes. */
     mixerLoad: MixerLoad;
     view: PaintView;
+    /** View tilt for thin-film iridescence and specular highlights (-1..1, default {x: 0, y: 0}; editor state, not saved with the document). */
+    viewTilt: PaintViewTilt;
     hand: Hand;
     /** Live effect paint: whether strokes on stroke layers play their effect, the frame rate cap and the time (ms) the view shows. Editor state. */
     effectPlayback: {
@@ -171,6 +179,14 @@ export interface PaintEditorState {
     stroking: boolean;
     /** Wet media. */
     wet: PaintWetStateInfo;
+    /** The UV / blacklight view setting (saved with the document, not undo steps). */
+    uvLight: UvLightSettings;
+    /** The coarse heat field's temperature summary. */
+    heat: HeatStats;
+    /** Pending and active mutation exchanges (editor state, not saved with the document). */
+    mutations: readonly PaintMutationInfo[];
+    /** Whether an agent is listening for mutation requests (`onMutationRequest` or `setMutationAgentConnected`). */
+    hasMutationAgent: boolean;
     /** Increments on every change. */
     version: number;
 }
@@ -206,6 +222,8 @@ export interface PaintLayerInfo {
     liveStrokes?: number;
     /** How many live layer effects (glows, shadows, strokes…) it has, when any (`getLayerEffects`). */
     effects?: number;
+    /** A temporary layer created for a dry mutation stroke (fades away once claimed or merges down if unanswered). */
+    temporary?: boolean;
 }
 /** A live stroke as it is painted (`onStrokeSample`), for agents that paint along with the user. */
 export interface PaintStrokeSample {
@@ -517,9 +535,17 @@ export declare class PaintEditorController {
     private readonly wetOptions;
     /** Where the light comes from for thick paint (saved with the document, not undo steps). */
     private lighting;
+    /** Where the viewer looks from for thin-film iridescence and specular highlights (editor state, not saved with the document). */
+    private viewTilt;
     private readonly litCaches;
     /** The live impasto stroke's channels. */
     private liveThick;
+    /** The UV / blacklight setting (saved with the document, not undo steps). */
+    private uvLight;
+    private readonly uvCaches;
+    private readonly thermoCaches;
+    private liveFluor;
+    private liveThermo;
     /** Set while an operation that changes wet paint runs: the simulation before it (for undo). */
     private wetOp;
     /** The effects provider slot (see `setEffectsProvider`). */
@@ -534,6 +560,15 @@ export declare class PaintEditorController {
     private readonly rasterizeSticker;
     private readonly effectsRenderer;
     private paperEffectNodeCache;
+    private mutations;
+    private nextMutationId;
+    private readonly mutationListeners;
+    private mutationAgentConnected;
+    private mutationDirector;
+    private readonly heldEvaporation;
+    private readonly tempLayerTargets;
+    private answeringMutation;
+    private lastMutationTick;
     constructor(options?: PaintEditorOptions);
     subscribe(listener: () => void): () => void;
     /**
@@ -1157,12 +1192,81 @@ export declare class PaintEditorController {
         layerId: string;
         cleared: boolean;
     };
+    private fluorWithout;
+    private thermoWithout;
+    /** The UV / blacklight view setting. */
+    getUvLight(): UvLightSettings;
+    /** Layers that carry UV-fluorescent ink. */
+    fluorescentLayerIds(): string[];
+    /** Layers that carry thermochromic ink. */
+    thermochromicLayerIds(): string[];
+    /**
+     * Switches or tunes the virtual UV / blacklight (`on`, `strength` 0..2, `ambient` 0..1). When
+     * `on` is true, the composite dims to `ambient` and fluorescent ink (`brush.fluorescence`) glows
+     * in its stroke colour with a Linear Dodge halo. Saved with the document, not an undo step.
+     */
+    setUvLight(update: Partial<UvLightSettings>): UvLightSettings;
+    /**
+     * Reads the document's heat field: its temperature summary (`peak`, `mean`, `hotCells`) and,
+     * when `points` are given (document pixels), the bilinearly sampled temperature (0..1) at each.
+     */
+    getHeat(points?: readonly {
+        x: number;
+        y: number;
+    }[]): HeatStats & {
+        samples: HeatSample[];
+        thermochromicLayerIds: string[];
+    };
+    /**
+     * Warms (or with `temperature` 0 cools) the canvas heat field along `points` (document pixels)
+     * with a soft brush of `radius` px (default 28) towards `temperature` 0..1 (default 1). Where
+     * temperature reaches `HEAT_DRY_THRESHOLD` (0.5), any wet paint on those tiles dries at once.
+     * One undo step.
+     */
+    paintHeat(options: {
+        points: readonly {
+            x: number;
+            y: number;
+        }[];
+        radius?: number;
+        temperature?: number;
+    }): HeatStats & {
+        bounds: RasterRect | null;
+        dried: Array<{
+            layerId: string;
+            bounds: RasterRect | null;
+        }>;
+    };
+    /**
+     * Advances the heat field by `steps` simulation steps (1..200, default 10): heat diffuses into
+     * neighbouring cells and cools towards 0 by Newtonian cooling. Newly heated tiles above the dry
+     * threshold dry any wet paint on them. Not an undo step (time passing never is).
+     */
+    advanceHeat(stepsOrOptions?: number | {
+        steps?: number;
+    }): HeatStats & {
+        steps: number;
+        dried: Array<{
+            layerId: string;
+            bounds: RasterRect | null;
+        }>;
+    };
+    /** Cools the whole canvas heat field to 0 at once (one undo step when anything was warm). */
+    clearHeat(): {
+        cleared: boolean;
+    };
+    /** Dries any wet paint on tiles where `field` is at or above `HEAT_DRY_THRESHOLD`. */
+    private dryWetFromHeat;
     /** 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. */
     getLighting(): PaintLighting;
     /** Moves the light (thick paint and metallic paper are relit; nothing is repainted). Saved with the document, not an undo step. */
     setLighting(update: Partial<PaintLighting>): PaintLighting;
+    /** Where the viewer looks from for thin-film iridescence and specular highlights (-1..1; editor state, not saved with the document). */
+    getViewTilt(): PaintViewTilt;
+    /** Tilts the view vector for thin-film iridescence and specular highlights (-1..1; editor state, not saved with the document, not an undo step). */
+    setViewTilt(update: Partial<PaintViewTilt>): PaintViewTilt;
     /** A layer's relief: where it is, its highest point (0..255) and its tiles; `null` when it has none. */
     reliefOf(layerId?: string): {
         layerId: string;
@@ -1313,6 +1417,14 @@ export declare class PaintEditorController {
     private tracingNode;
     /** The layers with every wet layer dried where it is (what saving and exporting see). */
     private driedLayers;
+    /** The layers with thermochromic paint shifted toward its hot colour where the canvas is warm. */
+    private thermoLayers;
+    /**
+     * Under the UV blacklight: every pixel layer's daylight paint dims to `uvLight.ambient`, any
+     * fluorescent ink (`doc.fluor[id]`) glows in its own colour, and each fluorescent layer casts a
+     * Linear Dodge (`::uv`) spill layer directly above it.
+     */
+    private uvLayers;
     /** The layers with thick paint lit (each thick layer's pixels replaced by its lit tiles). */
     private litLayers;
     /**
@@ -1690,8 +1802,94 @@ export declare class PaintEditorController {
     removeMixingPad(id: string): SavedMixingPadInfo;
     private mixingPadJSON;
     private readMixingPad;
+    /**
+     * Hears each mutation once it has settled (`settle` seconds after the user's last mutation
+     * stroke). Registering a listener marks an agent as connected (`state.hasMutationAgent`).
+     */
+    onMutationRequest(listener: PaintMutationRequestListener): () => void;
+    /** Marks whether a mutation-answering agent is connected (for hosts that wake agents via tools). */
+    setMutationAgentConnected(connected: boolean): void;
+    /** Attaches a `PaintDirector` so `answerMutation` and `readMutation` animate the agent's cursor. */
+    setMutationDirector(director: PaintDirector | null): void;
+    /** Lists pending mutations (or all mutations when `includeAll` is true). */
+    listMutations(options?: {
+        includeAll?: boolean;
+    }): PaintMutationInfo[];
+    /** One mutation by id (`undefined` when unknown). */
+    getMutation(id: string): PaintMutationInfo | undefined;
+    /**
+     * Claims a mutation (`id`) and starts its fade. Returns the strokes (points, colour, brush), a
+     * PNG of the area around them (`cropPng`), and a preview of the whole painting (`canvasPng`) so
+     * the agent can choose where to answer. Refused if already claimed, answered or declined.
+     */
+    readMutation(id: string, options?: {
+        actor?: string;
+        padding?: number;
+        maxSide?: number;
+    }): PaintMutationReadResult;
+    /**
+     * Paints the agent's answer to a claimed mutation (`id`). When a `PaintDirector` is attached (or
+     * passed in `options`), the agent's cursor is seen painting live; all strokes commit as one undo
+     * step with origin `agent:<id>`. A second answer to the same id is refused.
+     */
+    answerMutation(id: string, input: PaintMutationAnswerInput, options?: {
+        director?: PaintDirector;
+        actor?: PresenceActorInfo;
+    }): Promise<PaintMutationAnswerResult>;
+    /**
+     * Gives up on a mutation (`id`) without answering. The user's paint stays as ordinary paint (wet
+     * strokes stay in the wet layer, and dry temporary layers merge down into their target layer).
+     */
+    declineMutation(id: string, reason?: string): PaintMutationInfo;
+    /**
+     * Advances mutation timers (`settle`, `patience`, and dry temporary-layer `fade`) by `seconds`
+     * of simulated time. Called automatically from `tickMutations` and `advanceWet`.
+     */
+    advanceMutations(seconds: number): void;
+    /** Steps mutation timers with the wall clock (`performance.now()`, in ms). */
+    tickMutations(now: number): void;
+    private toMutationInfo;
+    private recordMutationStroke;
+    private holdMutationEvaporation;
+    private releaseMutationEvaporation;
+    private finishWetMutationsOnDry;
+    private expireMutation;
+    private keepMutationPaint;
+    private mergeTempLayerIntoTarget;
+    private removeTempMutationLayer;
+    private reconcileMutationsAfterUndo;
+    private resetMutations;
     /** A layer's tile surface (live while stroking), for thumbnails. */
     layerSurface(id: string): TiledSurface | null;
+    private proposalsStore;
+    /** The pending paint proposals store attached to this editor (created on demand). */
+    get proposals(): PaintProposals;
+    /** Attaches an external `PaintProposals` store so tools and panels share it. */
+    attachProposals(store: PaintProposals): void;
+    /**
+     * Breeds `count` (`2..12`, default `4`) mutated variants from `1..16` recorded strokes as
+     * pending paint proposals, generated one after another through `previewPaint`.
+     */
+    breedStrokes(options: {
+        strokeIds: readonly string[];
+        count?: number;
+        mutation?: StrokeMutationRates;
+        seed?: number;
+        origin?: string;
+    }): BreedStrokesResult;
+    /**
+     * Breeds `count` (`2..12`, default `4`) variants from `1` pending proposal (mutation) or `2`
+     * pending proposals (crossover + mutation), generated one after another through `previewPaint`.
+     */
+    breedProposal(options: {
+        proposalIds: readonly string[];
+        count?: number;
+        mutation?: StrokeMutationRates;
+        seed?: number;
+        origin?: string;
+    }): BreedStrokesResult;
+    /** Returns the full stroke genome records (`RecordedStrokeJSON[]`) of a pending paint proposal. */
+    getProposalGenome(proposalId: string): ProposalGenomeResult;
 }
 export type { Tile };
 /** Largest tracing or reference image side, in pixels. */

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

@@ -22,6 +22,7 @@ import type { MultiColorSettings, PaintBrush } from './brushes.cjs';
 import { type EffectPaintPixels } from './effect-paint.cjs';
 import { type PenPoint, type StrokeCopy } from './engine.cjs';
 import { type PaperGrain } from './paper.cjs';
+import type { FilmBuffer } from './thick.cjs';
 import type { StickerArtLookup } from './sticker-art.cjs';
 export interface PaintDabStrokeOptions {
     /** Where the stroke reads and writes pixels. */
@@ -42,6 +43,8 @@ export interface PaintDabStrokeOptions {
     effect?: EffectPaintPixels | null;
     /** Loaded sticker art, for a stamp tip of a sticker from the sticker library (`brush.stamp`). */
     stampArt?: StickerArtLookup;
+    /** Thin-film iridescence channel for dab / mixer brushes with `iridescence`. */
+    film?: FilmBuffer | null;
 }
 /** Colours of a multi-colour brush, resolved against the paint and secondary colours. */
 export declare function multiColorPalette(mc: MultiColorSettings, color: RgbTriple, secondary: RgbTriple): RgbTriple[];

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

@@ -22,6 +22,7 @@ import type { MultiColorSettings, PaintBrush } from './brushes.js';
 import { type EffectPaintPixels } from './effect-paint.js';
 import { type PenPoint, type StrokeCopy } from './engine.js';
 import { type PaperGrain } from './paper.js';
+import type { FilmBuffer } from './thick.js';
 import type { StickerArtLookup } from './sticker-art.js';
 export interface PaintDabStrokeOptions {
     /** Where the stroke reads and writes pixels. */
@@ -42,6 +43,8 @@ export interface PaintDabStrokeOptions {
     effect?: EffectPaintPixels | null;
     /** Loaded sticker art, for a stamp tip of a sticker from the sticker library (`brush.stamp`). */
     stampArt?: StickerArtLookup;
+    /** Thin-film iridescence channel for dab / mixer brushes with `iridescence`. */
+    film?: FilmBuffer | null;
 }
 /** Colours of a multi-colour brush, resolved against the paint and secondary colours. */
 export declare function multiColorPalette(mc: MultiColorSettings, color: RgbTriple, secondary: RgbTriple): RgbTriple[];

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

@@ -7,7 +7,7 @@
  * Saved documents are JSON plus PNG assets, through the image editor's layer serializer (so the
  * same layer tree loads in both editors), with the paper as plain settings.
  */
-import type { RasterGroupLayer, RasterLayer, RasterPixelLayer } from '../raster/layers.cjs';
+import type { RasterGroupLayer, RasterPixelLayer } from '../raster/layers.cjs';
 import { type TiledSurface } from '../raster/surface.cjs';
 import { type PaperSettings } from './paper.cjs';
 import type { RecordedStroke } from './strokes.cjs';
@@ -15,10 +15,14 @@ import type { WetEvent } from './wet.cjs';
 import type { ThickChannels } from './thick.cjs';
 import type { Sticker } from './stickers.cjs';
 import type { PaintEffectSource, PaintPaperEffect } from './effects.cjs';
-export type PaintPixelLayer = RasterPixelLayer;
+import type { HeatField } from './heat.cjs';
+export type PaintPixelLayer = RasterPixelLayer & {
+    /** A temporary layer for a dry mutation stroke (fades on claim, merges down on timeout or save). */
+    temporary?: boolean;
+};
 export type PaintGroupLayer = RasterGroupLayer<PaintLayer>;
 /** A layer of the paint editor: the shared stack's pixel layers and groups. */
-export type PaintLayer = RasterLayer;
+export type PaintLayer = PaintPixelLayer | PaintGroupLayer;
 /** Canvas size limits (pixels per side). */
 export declare const MIN_CANVAS_SIDE = 1;
 export declare const MAX_CANVAS_SIDE = 16384;
@@ -51,6 +55,12 @@ export interface PaintDocumentState {
     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>>;
+    /** UV-fluorescent ink: each layer's 4-channel RGBA fluorescence surface in layer space (layers without fluorescence are missing). See `heat.ts`. */
+    fluor?: Readonly<Record<string, TiledSurface>>;
+    /** Thermochromic ink: each layer's 4-channel RGBA thermochromic surface (`[hotR, hotG, hotB, thresholdByte]`) in layer space. See `heat.ts`. */
+    thermo?: Readonly<Record<string, TiledSurface>>;
+    /** Coarse document-level heat field (1/4 resolution) for thermochromic ink and wet-paint drying. See `heat.ts`. */
+    heat?: HeatField;
     /** 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

@@ -7,7 +7,7 @@
  * Saved documents are JSON plus PNG assets, through the image editor's layer serializer (so the
  * same layer tree loads in both editors), with the paper as plain settings.
  */
-import type { RasterGroupLayer, RasterLayer, RasterPixelLayer } from '../raster/layers.js';
+import type { RasterGroupLayer, RasterPixelLayer } from '../raster/layers.js';
 import { type TiledSurface } from '../raster/surface.js';
 import { type PaperSettings } from './paper.js';
 import type { RecordedStroke } from './strokes.js';
@@ -15,10 +15,14 @@ import type { WetEvent } from './wet.js';
 import type { ThickChannels } from './thick.js';
 import type { Sticker } from './stickers.js';
 import type { PaintEffectSource, PaintPaperEffect } from './effects.js';
-export type PaintPixelLayer = RasterPixelLayer;
+import type { HeatField } from './heat.js';
+export type PaintPixelLayer = RasterPixelLayer & {
+    /** A temporary layer for a dry mutation stroke (fades on claim, merges down on timeout or save). */
+    temporary?: boolean;
+};
 export type PaintGroupLayer = RasterGroupLayer<PaintLayer>;
 /** A layer of the paint editor: the shared stack's pixel layers and groups. */
-export type PaintLayer = RasterLayer;
+export type PaintLayer = PaintPixelLayer | PaintGroupLayer;
 /** Canvas size limits (pixels per side). */
 export declare const MIN_CANVAS_SIDE = 1;
 export declare const MAX_CANVAS_SIDE = 16384;
@@ -51,6 +55,12 @@ export interface PaintDocumentState {
     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>>;
+    /** UV-fluorescent ink: each layer's 4-channel RGBA fluorescence surface in layer space (layers without fluorescence are missing). See `heat.ts`. */
+    fluor?: Readonly<Record<string, TiledSurface>>;
+    /** Thermochromic ink: each layer's 4-channel RGBA thermochromic surface (`[hotR, hotG, hotB, thresholdByte]`) in layer space. See `heat.ts`. */
+    thermo?: Readonly<Record<string, TiledSurface>>;
+    /** Coarse document-level heat field (1/4 resolution) for thermochromic ink and wet-paint drying. See `heat.ts`. */
+    heat?: HeatField;
     /** 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). */