@pixerate/editor 0.273.0 → 0.275.0

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

@@ -20,6 +20,7 @@ import type { PaintBrush } from './brushes.cjs';
 import { type EffectPaintPixels } from './effect-paint.cjs';
 import type { StickerArtLookup } from './sticker-art.cjs';
 import { type PaperGrain } from './paper.cjs';
+import type { FilmBuffer } from './thick.cjs';
 /** One pen sample in document pixels. Every channel but x and y is optional. */
 export interface PenPoint {
     x: number;
@@ -136,6 +137,8 @@ export interface DryStrokeOptions {
      * tip grain (`brush.tipGrain.source`); without it such a tip paints round, and the grain is left out.
      */
     stampArt?: StickerArtLookup;
+    /** Thin-film iridescence channel for dry brushes with `iridescence` (or eraser). */
+    film?: FilmBuffer | null;
 }
 /**
  * One dab-engine stroke (dab and eraser brushes): smoothing, the dab walk of every copy, grain and

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

@@ -20,6 +20,7 @@ import type { PaintBrush } from './brushes.js';
 import { type EffectPaintPixels } from './effect-paint.js';
 import type { StickerArtLookup } from './sticker-art.js';
 import { type PaperGrain } from './paper.js';
+import type { FilmBuffer } from './thick.js';
 /** One pen sample in document pixels. Every channel but x and y is optional. */
 export interface PenPoint {
     x: number;
@@ -136,6 +137,8 @@ export interface DryStrokeOptions {
      * tip grain (`brush.tipGrain.source`); without it such a tip paints round, and the grain is left out.
      */
     stampArt?: StickerArtLookup;
+    /** Thin-film iridescence channel for dry brushes with `iridescence` (or eraser). */
+    film?: FilmBuffer | null;
 }
 /**
  * One dab-engine stroke (dab and eraser brushes): smoothing, the dab walk of every copy, grain and

package/dist/paint-editor/evolution-tools.d.cts

@@ -0,0 +1,48 @@
+/**
+ * Agent tools for evolutionary strokes (`breed_strokes`, `breed_proposal`, `get_proposal_genome`).
+ * Accepting or dismissing bred variants reuses `accept_paint_proposal` and `reject_paint_proposal`.
+ */
+import type { AgentToolProvider } from '../tools/registry.cjs';
+import type { PaintEditorController } from './controller.cjs';
+import type { PaintAgentTool } from './hosted.cjs';
+export declare const EVOLUTION_MUTATION_SCHEMA: {
+    readonly type: "object";
+    readonly description: "How strongly each part of a stroke genome mutates (each 0..1; 0 keeps that part unchanged).";
+    readonly properties: {
+        readonly geometry: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 1;
+            readonly description: string;
+        };
+        readonly color: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 1;
+            readonly description: string;
+        };
+        readonly brush: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 1;
+            readonly description: string;
+        };
+        readonly seed: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 1;
+            readonly description: string;
+        };
+    };
+    readonly additionalProperties: false;
+};
+export declare function createPaintEvolutionTools(c: PaintEditorController): PaintAgentTool[];
+export declare const createEvolutionTools: typeof createPaintEvolutionTools;
+export interface PaintEvolutionToolProviderOptions {
+    /** Provider id (unique per registry). Default `paint-evolution`. */
+    id?: string;
+    /** Tool-name prefix (`<namespace>__<name>`); defaults to the provider id, `''` for bare names. */
+    namespace?: string;
+}
+/** Standalone tool provider for evolutionary strokes (also included in `createPaintEditorToolProvider`). */
+export declare function createPaintEvolutionToolProvider(controller: PaintEditorController, options?: PaintEvolutionToolProviderOptions): AgentToolProvider;

package/dist/paint-editor/evolution-tools.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Agent tools for evolutionary strokes (`breed_strokes`, `breed_proposal`, `get_proposal_genome`).
+ * Accepting or dismissing bred variants reuses `accept_paint_proposal` and `reject_paint_proposal`.
+ */
+import type { AgentToolProvider } from '../tools/registry.js';
+import type { PaintEditorController } from './controller.js';
+import type { PaintAgentTool } from './hosted.js';
+export declare const EVOLUTION_MUTATION_SCHEMA: {
+    readonly type: "object";
+    readonly description: "How strongly each part of a stroke genome mutates (each 0..1; 0 keeps that part unchanged).";
+    readonly properties: {
+        readonly geometry: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 1;
+            readonly description: string;
+        };
+        readonly color: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 1;
+            readonly description: string;
+        };
+        readonly brush: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 1;
+            readonly description: string;
+        };
+        readonly seed: {
+            readonly type: "number";
+            readonly minimum: 0;
+            readonly maximum: 1;
+            readonly description: string;
+        };
+    };
+    readonly additionalProperties: false;
+};
+export declare function createPaintEvolutionTools(c: PaintEditorController): PaintAgentTool[];
+export declare const createEvolutionTools: typeof createPaintEvolutionTools;
+export interface PaintEvolutionToolProviderOptions {
+    /** Provider id (unique per registry). Default `paint-evolution`. */
+    id?: string;
+    /** Tool-name prefix (`<namespace>__<name>`); defaults to the provider id, `''` for bare names. */
+    namespace?: string;
+}
+/** Standalone tool provider for evolutionary strokes (also included in `createPaintEditorToolProvider`). */
+export declare function createPaintEvolutionToolProvider(controller: PaintEditorController, options?: PaintEvolutionToolProviderOptions): AgentToolProvider;

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

@@ -0,0 +1,175 @@
+/**
+ * Evolutionary strokes: breed and mutate stroke variants (`RecordedStroke` genomes).
+ *
+ * - **Geometry mutation**: reuses `StrokeVariation` / `varyStroke` for whole-stroke affine drift
+ *   (move, scale, rotate, pressure scale) plus seeded, smoothed point jitter along the path.
+ * - **Colour drift**: perceptual drift in OKLCH lightness, chroma and hue, gamut-mapped to sRGB.
+ * - **Brush facet drift**: drifts numeric brush facets within their schema ranges (`BRUSH_JSON_SCHEMA`)
+ *   and resolves back to an engine `PaintBrush`.
+ * - **Seed reroll**: deterministic reroll of the stroke's dab/particle/bristle seed.
+ * - **Crossover**: resamples two parent stroke paths to a common point count, blends their points
+ *   and colours in OKLab/OKLCH, and mixes their brush facets.
+ */
+import type { RasterRect } from '../raster/surface.cjs';
+import type { PaintBrush } from './brushes.cjs';
+import type { PaintProposal } from './collaboration.cjs';
+import type { PaintEditorController, PixelImage } from './controller.cjs';
+import type { PenPoint } from './engine.cjs';
+import { strokeToJSON, type RecordedStroke, type StrokeVariation } from './strokes.cjs';
+export type RecordedStrokeJSON = ReturnType<typeof strokeToJSON>;
+/** How strongly each part of a stroke genome mutates (`0..1`; `0` keeps that part unchanged). */
+export interface StrokeMutationRates {
+    /** Path variation and smoothed point jitter, 0..1 (default 0.35). */
+    geometry?: number;
+    /** Colour drift in OKLCH lightness, chroma and hue, 0..1 (default 0.35). */
+    color?: number;
+    /** Brush facet drift within schema bounds, 0..1 (default 0.35). */
+    brush?: number;
+    /** Seed reroll rate, 0..1 (default 0.5; 0 keeps the stroke seed). */
+    seed?: number;
+}
+export type EvolutionMutationRates = StrokeMutationRates;
+export interface ResolvedMutationRates {
+    geometry: number;
+    color: number;
+    brush: number;
+    seed: number;
+}
+export declare const DEFAULT_MUTATION_RATES: ResolvedMutationRates;
+/** Validates and fills defaults for mutation rates (`0..1`). */
+export declare function normalizeMutationRates(rates?: StrokeMutationRates): ResolvedMutationRates;
+/** Numeric brush facet descriptor with its schema range and drift span. */
+export interface EvolutionBrushFacet {
+    /** Dot-path in the facet `Brush`. */
+    facet: string;
+    /** Dot-path in the resolved `PaintBrush`. */
+    engine: string;
+    /** Engines that read this facet. */
+    engines: readonly PaintBrush['engine'][];
+    /** Minimum schema value. */
+    min: number;
+    /** Maximum schema value. */
+    max: number;
+    /** Maximum drift at `mutation.brush = 1` (relative fraction when `relative` is true, else additive). */
+    span: number;
+    /** Inverse of rounding step (`1`, `10`, `100`). */
+    scale: number;
+    /** True when `span` scales the current value multiplicatively. */
+    relative?: boolean;
+    /** Optional `tip.shape` filter. */
+    shapes?: readonly string[];
+    /** Optional `marks.kind` filter. */
+    marks?: readonly string[];
+}
+/** Ordered table of numeric brush facets drifted and crossed over within their schema ranges. */
+export declare const EVOLUTION_BRUSH_FACETS: readonly EvolutionBrushFacet[];
+/**
+ * Seeded, smoothed point jitter along a stroke path: combines two harmonic waves with a 3-point
+ * smoothed random displacement so mutated paths stay fluid rather than jagged.
+ */
+export declare function jitterStrokePoints(points: readonly PenPoint[], amount: number, seed: number): PenPoint[];
+/** Whole-stroke `StrokeVariation` derived from a seed and geometry mutation rate (`0..1`). */
+export declare function seededStrokeVariation(amount: number, seed: number, index?: number): StrokeVariation;
+/**
+ * Drifts a `#rrggbb` colour in OKLCH lightness (±0.22), chroma (±0.10) and hue (±90°) scaled by
+ * `amount` (`0..1`), reducing chroma when needed to stay inside the sRGB gamut.
+ */
+export declare function driftColorOklch(hex: string, amount: number, seed: number, index?: number): string;
+/** Mixes two `#rrggbb` colours perceptually in OKLab/OKLCH at weight `t` (`0..1`). */
+export declare function mixColorOklch(hexA: string, hexB: string, t: number): string;
+/**
+ * Drifts a brush's numeric facets within their schema ranges (`EVOLUTION_BRUSH_FACETS`), keeping
+ * the brush compatible with live strokes (`liveStrokeRefusal`).
+ */
+export declare function driftBrushFacets(brush: PaintBrush, amount: number, seed: number, index?: number): PaintBrush;
+/** Rerolls a stroke seed deterministically when `amount > 0`; keeps `strokeSeed` when `amount <= 0`. */
+export declare function rerollStrokeSeed(strokeSeed: number, amount: number, seed: number, index?: number): number;
+/** Resamples a stroke's points by arc length to `count` evenly spaced samples. */
+export declare function resampleStrokePoints(points: readonly PenPoint[], count: number): PenPoint[];
+/** Mixes two brushes by blending their applicable numeric facets onto a dominant parent's skeleton. */
+export declare function crossoverBrushes(brushA: PaintBrush, brushB: PaintBrush, seed: number, index?: number): PaintBrush;
+/**
+ * Crosses two parent strokes over: resamples their points to a common count, blends positions and
+ * pressures, mixes their colours in OKLab/OKLCH, mixes their brush facets and combines their seeds.
+ */
+export declare function crossoverStrokes(a: RecordedStroke, b: RecordedStroke, seed: number, index?: number): RecordedStroke;
+/**
+ * Mutates one stroke genome with `rates` (`geometry`, `color`, `brush`, `seed`). When `origin` and
+ * `variation` are given (for multi-stroke motifs), whole-stroke affine drift uses them so strokes
+ * in the same genome move and turn together while each stroke's path jitters on its own.
+ */
+export declare function mutateStroke(stroke: RecordedStroke, rates: strokeMutationInput, seed: number, index?: number, group?: {
+    origin: {
+        x: number;
+        y: number;
+    };
+    variation: StrokeVariation;
+}): RecordedStroke;
+type strokeMutationInput = StrokeMutationRates | undefined;
+export interface StrokeEvolutionChanges {
+    geometry: boolean;
+    colors: Array<{
+        from: string;
+        to: string;
+    }>;
+    facets: Record<string, {
+        from: number;
+        to: number;
+    }>;
+    seedChanged: boolean;
+    crossover: boolean;
+}
+/** Summarises what changed between a parent stroke genome and a bred child genome. */
+export declare function describeGenomeDiff(parents: readonly RecordedStroke[], children: readonly RecordedStroke[], options?: {
+    crossover?: boolean;
+}): {
+    diff: string;
+    changes: StrokeEvolutionChanges;
+};
+/** Mutates a multi-stroke genome at `variantSeed`. */
+export declare function mutateGenome(strokes: readonly RecordedStroke[], rates: StrokeMutationRates | undefined, variantSeed: number): RecordedStroke[];
+/** Crosses two stroke genomes over and mutates the offspring at `variantSeed`. */
+export declare function crossoverGenomes(genomeA: readonly RecordedStroke[], genomeB: readonly RecordedStroke[], rates: StrokeMutationRates | undefined, variantSeed: number): RecordedStroke[];
+/** Checks that every stroke in a genome can be bred and previewed (refuses brushes `liveStrokeRefusal` rejects). */
+export declare function checkEvolutionStrokes(strokes: readonly RecordedStroke[]): void;
+export interface BredProposalSummary {
+    proposalId: string;
+    title: string;
+    seed: number;
+    bounds: RasterRect | null;
+    diff: string;
+    changes: StrokeEvolutionChanges;
+}
+export interface BreedStrokesResult {
+    proposalIds: string[];
+    proposals: BredProposalSummary[];
+}
+export interface ProposalGenomeResult {
+    proposalId: string;
+    title: string;
+    bounds: RasterRect | null;
+    strokes: RecordedStrokeJSON[];
+}
+/** Extracts the stroke genome of a pending `PaintProposal`, or returns `[]` when it has none. */
+export declare function proposalGenomeStrokes(first: PaintEditorController | PaintProposal, second?: PaintProposal): RecordedStroke[];
+/**
+ * Renders a contact sheet (`replay.ts:contactSheet`) of pending proposals' ghosts composited over
+ * the current canvas, for grid export.
+ */
+export declare function renderProposalContactSheet(controller: PaintEditorController, proposals: readonly PaintProposal[], options?: {
+    columns?: number;
+    cell?: number;
+    paper?: boolean;
+}): PixelImage;
+/** Encodes `renderProposalContactSheet` as a PNG byte array and base64 string. */
+export declare function exportProposalContactSheetPng(controller: PaintEditorController, proposals: readonly PaintProposal[], options?: {
+    columns?: number;
+    cell?: number;
+    paper?: boolean;
+}): {
+    width: number;
+    height: number;
+    bytes: Uint8Array;
+    base64: string;
+};
+export { strokeToJSON };

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

@@ -0,0 +1,175 @@
+/**
+ * Evolutionary strokes: breed and mutate stroke variants (`RecordedStroke` genomes).
+ *
+ * - **Geometry mutation**: reuses `StrokeVariation` / `varyStroke` for whole-stroke affine drift
+ *   (move, scale, rotate, pressure scale) plus seeded, smoothed point jitter along the path.
+ * - **Colour drift**: perceptual drift in OKLCH lightness, chroma and hue, gamut-mapped to sRGB.
+ * - **Brush facet drift**: drifts numeric brush facets within their schema ranges (`BRUSH_JSON_SCHEMA`)
+ *   and resolves back to an engine `PaintBrush`.
+ * - **Seed reroll**: deterministic reroll of the stroke's dab/particle/bristle seed.
+ * - **Crossover**: resamples two parent stroke paths to a common point count, blends their points
+ *   and colours in OKLab/OKLCH, and mixes their brush facets.
+ */
+import type { RasterRect } from '../raster/surface.js';
+import type { PaintBrush } from './brushes.js';
+import type { PaintProposal } from './collaboration.js';
+import type { PaintEditorController, PixelImage } from './controller.js';
+import type { PenPoint } from './engine.js';
+import { strokeToJSON, type RecordedStroke, type StrokeVariation } from './strokes.js';
+export type RecordedStrokeJSON = ReturnType<typeof strokeToJSON>;
+/** How strongly each part of a stroke genome mutates (`0..1`; `0` keeps that part unchanged). */
+export interface StrokeMutationRates {
+    /** Path variation and smoothed point jitter, 0..1 (default 0.35). */
+    geometry?: number;
+    /** Colour drift in OKLCH lightness, chroma and hue, 0..1 (default 0.35). */
+    color?: number;
+    /** Brush facet drift within schema bounds, 0..1 (default 0.35). */
+    brush?: number;
+    /** Seed reroll rate, 0..1 (default 0.5; 0 keeps the stroke seed). */
+    seed?: number;
+}
+export type EvolutionMutationRates = StrokeMutationRates;
+export interface ResolvedMutationRates {
+    geometry: number;
+    color: number;
+    brush: number;
+    seed: number;
+}
+export declare const DEFAULT_MUTATION_RATES: ResolvedMutationRates;
+/** Validates and fills defaults for mutation rates (`0..1`). */
+export declare function normalizeMutationRates(rates?: StrokeMutationRates): ResolvedMutationRates;
+/** Numeric brush facet descriptor with its schema range and drift span. */
+export interface EvolutionBrushFacet {
+    /** Dot-path in the facet `Brush`. */
+    facet: string;
+    /** Dot-path in the resolved `PaintBrush`. */
+    engine: string;
+    /** Engines that read this facet. */
+    engines: readonly PaintBrush['engine'][];
+    /** Minimum schema value. */
+    min: number;
+    /** Maximum schema value. */
+    max: number;
+    /** Maximum drift at `mutation.brush = 1` (relative fraction when `relative` is true, else additive). */
+    span: number;
+    /** Inverse of rounding step (`1`, `10`, `100`). */
+    scale: number;
+    /** True when `span` scales the current value multiplicatively. */
+    relative?: boolean;
+    /** Optional `tip.shape` filter. */
+    shapes?: readonly string[];
+    /** Optional `marks.kind` filter. */
+    marks?: readonly string[];
+}
+/** Ordered table of numeric brush facets drifted and crossed over within their schema ranges. */
+export declare const EVOLUTION_BRUSH_FACETS: readonly EvolutionBrushFacet[];
+/**
+ * Seeded, smoothed point jitter along a stroke path: combines two harmonic waves with a 3-point
+ * smoothed random displacement so mutated paths stay fluid rather than jagged.
+ */
+export declare function jitterStrokePoints(points: readonly PenPoint[], amount: number, seed: number): PenPoint[];
+/** Whole-stroke `StrokeVariation` derived from a seed and geometry mutation rate (`0..1`). */
+export declare function seededStrokeVariation(amount: number, seed: number, index?: number): StrokeVariation;
+/**
+ * Drifts a `#rrggbb` colour in OKLCH lightness (±0.22), chroma (±0.10) and hue (±90°) scaled by
+ * `amount` (`0..1`), reducing chroma when needed to stay inside the sRGB gamut.
+ */
+export declare function driftColorOklch(hex: string, amount: number, seed: number, index?: number): string;
+/** Mixes two `#rrggbb` colours perceptually in OKLab/OKLCH at weight `t` (`0..1`). */
+export declare function mixColorOklch(hexA: string, hexB: string, t: number): string;
+/**
+ * Drifts a brush's numeric facets within their schema ranges (`EVOLUTION_BRUSH_FACETS`), keeping
+ * the brush compatible with live strokes (`liveStrokeRefusal`).
+ */
+export declare function driftBrushFacets(brush: PaintBrush, amount: number, seed: number, index?: number): PaintBrush;
+/** Rerolls a stroke seed deterministically when `amount > 0`; keeps `strokeSeed` when `amount <= 0`. */
+export declare function rerollStrokeSeed(strokeSeed: number, amount: number, seed: number, index?: number): number;
+/** Resamples a stroke's points by arc length to `count` evenly spaced samples. */
+export declare function resampleStrokePoints(points: readonly PenPoint[], count: number): PenPoint[];
+/** Mixes two brushes by blending their applicable numeric facets onto a dominant parent's skeleton. */
+export declare function crossoverBrushes(brushA: PaintBrush, brushB: PaintBrush, seed: number, index?: number): PaintBrush;
+/**
+ * Crosses two parent strokes over: resamples their points to a common count, blends positions and
+ * pressures, mixes their colours in OKLab/OKLCH, mixes their brush facets and combines their seeds.
+ */
+export declare function crossoverStrokes(a: RecordedStroke, b: RecordedStroke, seed: number, index?: number): RecordedStroke;
+/**
+ * Mutates one stroke genome with `rates` (`geometry`, `color`, `brush`, `seed`). When `origin` and
+ * `variation` are given (for multi-stroke motifs), whole-stroke affine drift uses them so strokes
+ * in the same genome move and turn together while each stroke's path jitters on its own.
+ */
+export declare function mutateStroke(stroke: RecordedStroke, rates: strokeMutationInput, seed: number, index?: number, group?: {
+    origin: {
+        x: number;
+        y: number;
+    };
+    variation: StrokeVariation;
+}): RecordedStroke;
+type strokeMutationInput = StrokeMutationRates | undefined;
+export interface StrokeEvolutionChanges {
+    geometry: boolean;
+    colors: Array<{
+        from: string;
+        to: string;
+    }>;
+    facets: Record<string, {
+        from: number;
+        to: number;
+    }>;
+    seedChanged: boolean;
+    crossover: boolean;
+}
+/** Summarises what changed between a parent stroke genome and a bred child genome. */
+export declare function describeGenomeDiff(parents: readonly RecordedStroke[], children: readonly RecordedStroke[], options?: {
+    crossover?: boolean;
+}): {
+    diff: string;
+    changes: StrokeEvolutionChanges;
+};
+/** Mutates a multi-stroke genome at `variantSeed`. */
+export declare function mutateGenome(strokes: readonly RecordedStroke[], rates: StrokeMutationRates | undefined, variantSeed: number): RecordedStroke[];
+/** Crosses two stroke genomes over and mutates the offspring at `variantSeed`. */
+export declare function crossoverGenomes(genomeA: readonly RecordedStroke[], genomeB: readonly RecordedStroke[], rates: StrokeMutationRates | undefined, variantSeed: number): RecordedStroke[];
+/** Checks that every stroke in a genome can be bred and previewed (refuses brushes `liveStrokeRefusal` rejects). */
+export declare function checkEvolutionStrokes(strokes: readonly RecordedStroke[]): void;
+export interface BredProposalSummary {
+    proposalId: string;
+    title: string;
+    seed: number;
+    bounds: RasterRect | null;
+    diff: string;
+    changes: StrokeEvolutionChanges;
+}
+export interface BreedStrokesResult {
+    proposalIds: string[];
+    proposals: BredProposalSummary[];
+}
+export interface ProposalGenomeResult {
+    proposalId: string;
+    title: string;
+    bounds: RasterRect | null;
+    strokes: RecordedStrokeJSON[];
+}
+/** Extracts the stroke genome of a pending `PaintProposal`, or returns `[]` when it has none. */
+export declare function proposalGenomeStrokes(first: PaintEditorController | PaintProposal, second?: PaintProposal): RecordedStroke[];
+/**
+ * Renders a contact sheet (`replay.ts:contactSheet`) of pending proposals' ghosts composited over
+ * the current canvas, for grid export.
+ */
+export declare function renderProposalContactSheet(controller: PaintEditorController, proposals: readonly PaintProposal[], options?: {
+    columns?: number;
+    cell?: number;
+    paper?: boolean;
+}): PixelImage;
+/** Encodes `renderProposalContactSheet` as a PNG byte array and base64 string. */
+export declare function exportProposalContactSheetPng(controller: PaintEditorController, proposals: readonly PaintProposal[], options?: {
+    columns?: number;
+    cell?: number;
+    paper?: boolean;
+}): {
+    width: number;
+    height: number;
+    bytes: Uint8Array;
+    base64: string;
+};
+export { strokeToJSON };

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

@@ -0,0 +1,156 @@
+/**
+ * Smart inks: UV-fluorescent ink (`doc.fluor[layerId]` + `uvLight`) and thermochromic ink
+ * (`doc.thermo[layerId]` + `doc.heat`).
+ *
+ * - **Fluorescent ink**: a per-layer 4-channel RGBA surface (`[R, G, B, intensity]`) in layer
+ *   space, painted alongside strokes when `brush.fluorescence.amount > 0`. With
+ *   `brush.fluorescence.invisible: true`, no daylight pigment is laid onto the layer's normal
+ *   surface, so the mark stays invisible under normal light. When the virtual UV blacklight
+ *   (`uvLight.on`) is switched on, normal layers dim to `uvLight.ambient` and fluorescent pixels
+ *   emit their colour and cast a Linear Dodge spill halo (reusing `computeSpill` from `./light`).
+ * - **Thermochromic ink**: a per-layer 4-channel RGBA surface (`[hotR, hotG, hotB, thresholdByte]`)
+ *   in layer space, painted when `brush.thermochromic.hotColor` is set. A document-level coarse
+ *   heat field (`HEAT_SCALE = 4`, 1/4 canvas resolution) stores local temperature in `0..1`,
+ *   painted by `paintHeatField` and stepped with 5-point Laplacian diffusion + Newtonian cooling
+ *   by `advanceHeatField`. At render time, thermochromic pixels blend smoothly from their cold
+ *   paint colour to `hotColor` around `threshold` based on bilinearly sampled temperature, and
+ *   tiles heated past `HEAT_DRY_THRESHOLD` dry any wet paint on them.
+ */
+import { TiledSurface, type RasterRect } from '../raster/surface.cjs';
+import { type PaintBrush } from './brushes.cjs';
+import { type PaperSettings } from './paper.cjs';
+/** View / document UV blacklight setting. */
+export interface UvLightSettings {
+    /** Whether the UV blacklight is switched on (default false). */
+    on: boolean;
+    /** Emission and halo strength under UV, 0..2 (default 1). */
+    strength: number;
+    /** How much normal daylight colour remains visible when UV is on, 0 (pitch dark) .. 1 (default 0.15). */
+    ambient: number;
+}
+export declare const DEFAULT_UV_LIGHT: Readonly<UvLightSettings>;
+export declare function normalizeUvLight(raw?: Partial<UvLightSettings>, base?: UvLightSettings): UvLightSettings;
+export declare function uvLightKey(uv: UvLightSettings): string;
+/** The paper dimmed to `uv.ambient` while the UV blacklight is on (cached by paper reference). */
+export declare function uvPaper(paper: PaperSettings, uv: UvLightSettings): PaperSettings;
+export declare function emptyFluor(): TiledSurface;
+export declare function emptyThermo(): TiledSurface;
+/**
+ * Twin brush that writes or moves the per-layer 4-channel fluorescence surface (`doc.fluor[id]`).
+ * When `brush.fluorescence.amount > 0`, it lays the stroke's colour scaled by `fluorescence.amount`;
+ * erasers, smudges and blenders act on the existing fluorescence; plain opaque paint dims it.
+ */
+export declare function fluorTwinBrush(brush: PaintBrush): PaintBrush;
+/**
+ * Twin brush that writes or moves the per-layer 4-channel thermochromic surface (`doc.thermo[id]`).
+ */
+export declare function thermoTwinBrush(brush: PaintBrush): PaintBrush;
+/**
+ * Encodes `threshold` (`0.05..0.95`) into channel 3 (`1..255`) of a thermochromic surface after a
+ * twin stroke painted `hotColor` with coverage in channel 3. Existing thermochromic pixels blend
+ * smoothly with the new `hotColor` and `threshold` by the twin's coverage.
+ */
+export declare function finalizeThermoStroke(twinOut: TiledSurface, before: TiledSurface, hotRgb: readonly [number, number, number], threshold: number): TiledSurface;
+/** Scales the alpha channel of a 4-channel RGBA surface (`fluor`) by `k` (0..1). */
+export declare function scaleFluor(surface: TiledSurface, k: number): TiledSurface;
+/** Merges two 4-channel surfaces (`above` over `below`) when merging layers down. */
+export declare function mergeFourChannel(below: TiledSurface | undefined, above: TiledSurface | undefined): TiledSurface | null;
+/** Computes the UV spill halo for a layer's `fluor` surface, reusing `computeSpill` from `./light`. */
+export declare function computeUvSpill(fluor: TiledSurface, strength: number): TiledSurface | null;
+/**
+ * Tile cache for UV blacklight rendering on one layer: dims daylight pixels to `uvLight.ambient`
+ * and adds fluorescent emission from `doc.fluor[id]` (even where daylight alpha is 0 for invisible ink).
+ */
+export declare class UvCache {
+    private readonly tiles;
+    private spillCache;
+    render(color: TiledSurface, fluor: TiledSurface | undefined, uv: UvLightSettings): TiledSurface;
+    spill(fluor: TiledSurface, uv: UvLightSettings): TiledSurface | null;
+}
+/** Coarse grid scale: 1 heat cell per 4×4 canvas pixels. */
+export declare const HEAT_SCALE = 4;
+/** Explicit 2D diffusion rate per step (≤ 0.25 for stability). */
+export declare const HEAT_DIFFUSION = 0.18;
+/** Newtonian cooling fraction per step. */
+export declare const HEAT_COOLING = 0.03;
+/** Temperature above which a heated cell dries wet paint. */
+export declare const HEAT_DRY_THRESHOLD = 0.5;
+export interface HeatField {
+    width: number;
+    height: number;
+    gridWidth: number;
+    gridHeight: number;
+    /** Row-major temperatures in 0..1 (`gridWidth * gridHeight`). */
+    cells: Float64Array;
+    max: number;
+    revision: number;
+}
+export interface HeatSample {
+    x: number;
+    y: number;
+    temperature: number;
+}
+export declare function createHeatField(width: number, height: number): HeatField;
+export declare function cloneHeatField(field: HeatField): HeatField;
+export interface HeatStats {
+    max: number;
+    mean: number;
+    hotCells: number;
+    bounds: RasterRect | null;
+}
+export declare function heatStats(field: HeatField | undefined): HeatStats;
+/** Bounding document-space rectangle of all coarse cells with temperature ≥ `threshold`, or `null`. */
+export declare function hotCellsBounds(field: HeatField, threshold?: number): RasterRect | null;
+/**
+ * Paints heat (or cools when `temperature` is below current cell heat) along `points` with `radius`
+ * in document pixels. Returns the affected document-space bounding box and updated field statistics.
+ */
+export declare function paintHeatField(field: HeatField, points: ReadonlyArray<{
+    x: number;
+    y: number;
+}>, radius?: number, temperature?: number): {
+    bounds: RasterRect;
+    stats: HeatStats;
+};
+/**
+ * Advances the heat field by `steps` iterations of 5-point Laplacian diffusion and Newtonian cooling.
+ */
+export declare function advanceHeatField(field: HeatField, steps?: number): HeatStats;
+/** Clears the heat field to 0 everywhere. */
+export declare function clearHeatField(field: HeatField): boolean;
+/** Bilinearly samples temperature (0..1) at document coordinates `(x, y)`. */
+export declare function sampleHeatAt(field: HeatField, x: number, y: number): number;
+/** Shifts and resizes a heat field when `extendCanvas` shifts the document by `(dx, dy)`. */
+export declare function shiftHeatField(field: HeatField, dx: number, dy: number, newWidth: number, newHeight: number): HeatField;
+/**
+ * Tile cache for thermochromic colour shifting on one layer: blends cold pixels toward `hotColor`
+ * around `threshold` where the coarse heat field is warm.
+ */
+export declare class ThermoCache {
+    private readonly tiles;
+    render(color: TiledSurface, thermo: TiledSurface | undefined, offset: {
+        x: number;
+        y: number;
+    }, heat: HeatField): TiledSurface;
+}
+export interface SavedLayerFluor {
+    rect: RasterRect;
+    /** 4-channel RGBA PNG data URL of the layer's fluorescence. */
+    fluor: string;
+}
+export interface SavedLayerThermo {
+    rect: RasterRect;
+    /** 4-channel RGBA PNG data URL of the layer's thermochromic `[hotR, hotG, hotB, thresholdByte]`. */
+    thermo: string;
+}
+export interface SavedHeatField {
+    gridWidth: number;
+    gridHeight: number;
+    cells: number[];
+}
+export declare function fluorToJSON(fluor: TiledSurface | undefined): SavedLayerFluor | null;
+export declare function fluorFromJSON(raw: unknown): TiledSurface;
+export declare function thermoToJSON(thermo: TiledSurface | undefined): SavedLayerThermo | null;
+export declare function thermoFromJSON(raw: unknown): TiledSurface;
+export declare function heatToJSON(field: HeatField | undefined): SavedHeatField | null;
+export declare function heatFromJSON(raw: unknown, width: number, height: number): HeatField | null;