@pixerate/editor 0.272.1 → 0.274.0

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

@@ -18,6 +18,7 @@ import { type LayerLocks } from '../raster/layers.cjs';
 import { type LayerEffect, type LayerEffectKind, type LayerEffects } from '../raster/effects/model.cjs';
 import type { EffectPattern } from '../raster/effects/patterns.cjs';
 import { TiledSurface, type RasterRect, type Tile } from '../raster/surface.cjs';
+import { type FillRegionPoint, type FillRegionSummary, type UnfilledRegion } from '../raster/fill.cjs';
 import { type PaintBrushInput, type PaintBrush } from './brushes.cjs';
 import { type BrushLibrary, type BrushLibraryFile } from '../brushes/library.cjs';
 import { type BrushPatch, type UnsettableBrushFacet } from '../brushes/patch.cjs';
@@ -55,6 +56,8 @@ import type { EffectDescription, EffectProvider, EffectValue } from '../effects/
 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 PaintProposals } from './collaboration.cjs';
+import { type BreedStrokesResult, type ProposalGenomeResult, type StrokeMutationRates } from './evolution.cjs';
 export declare class PaintEditorError extends Error {
     constructor(message: string);
 }
@@ -297,6 +300,75 @@ export interface FillLayerOptions {
     pressure?: number;
     blend?: BlendMode;
 }
+export type FillReference = 'layer' | 'all' | 'composite' | (string & {});
+export interface FillRegionOptions {
+    /** Seed x in document pixels (pass `x` and `y`, or `points`). */
+    x?: number;
+    /** Seed y in document pixels (pass `x` and `y`, or `points`). */
+    y?: number;
+    /** Multiple seed points in document pixels (filled together as one undo step). */
+    points?: ReadonlyArray<FillRegionPoint>;
+    /** Target layer id from `listLayers` (default the active layer). */
+    layerId?: string;
+    /**
+     * Which pixels define the region boundaries:
+     * - `'layer'` (default): the target layer itself.
+     * - `'all'` or `'composite'`: all visible layers composited (without paper).
+     * - a layer id from `listLayers`: that layer (e.g. an ink line-art layer above a flats layer).
+     */
+    reference?: FillReference;
+    /** Fill colour #rrggbb (default the editor's paint colour). */
+    color?: string;
+    /** Opacity 0..1 (default 1). */
+    opacity?: number;
+    /** Blend mode (default `'normal'`). */
+    blend?: BlendMode;
+    /** Alias for `blend`. */
+    blendMode?: BlendMode;
+    /** Colour/alpha similarity tolerance 0..255 (default 32). */
+    tolerance?: number;
+    /** Close small gaps in line art up to this width in pixels, 0..32 (default 0). */
+    closeGap?: number;
+    /** Expand (> 0, bleed under lines) or contract (< 0) the filled region in pixels, -16..16 (default 0). */
+    expand?: number;
+    /** Soften boundary edges (default true). */
+    antialias?: boolean;
+    /** Paper grain response 0..1 (default 0: flat fill). */
+    grain?: number;
+    /** With grain: pressure 0..1, how far the fill reaches into the valleys (default 0.5). */
+    pressure?: number;
+    /** Pour a wet watercolour wash into the region on the layer's wet layer (default false). */
+    wet?: boolean;
+}
+export interface FillRegionResult {
+    layerId: string;
+    bounds: RasterRect | null;
+    pixelCount: number;
+    leaked: boolean;
+    regions: FillRegionSummary[];
+    wet?: boolean;
+}
+export interface FindUnfilledRegionsOptions {
+    /** Target layer id from `listLayers` (when given, regions already painted on it are excluded). */
+    layerId?: string;
+    /**
+     * Which pixels define the line-art barriers:
+     * - `'all'` or `'composite'` (default): all visible layers composited (without paper).
+     * - `'layer'`: the target (or active) layer itself.
+     * - a layer id from `listLayers`: that layer (e.g. an ink line-art layer).
+     */
+    reference?: FillReference;
+    /** Alpha/colour threshold 0..255 above which a reference pixel is treated as line art (default 32). */
+    tolerance?: number;
+    /** Close small gaps in line art up to this width in pixels, 0..32 (default 0). */
+    closeGap?: number;
+    /** Ignore regions smaller than this many pixels (default 16). */
+    minArea?: number;
+    /** Include regions that touch the canvas border (default false: only enclosed shapes). */
+    includeEdge?: boolean;
+    /** Maximum number of regions to return, sorted largest first (default 100). */
+    maxRegions?: number;
+}
 /** Pixels to add on each side of the canvas (whole numbers, 0 or more; missing = 0). */
 export interface PaintCanvasExtension {
     left?: number;
@@ -653,6 +725,22 @@ export declare class PaintEditorController {
         layerId: string;
         bounds: RasterRect;
     };
+    /**
+     * Flood-fills one or more contiguous regions on a pixel layer (one undo step), sampling boundaries
+     * from the layer itself (`reference: 'layer'`), all visible layers (`'all'` / `'composite'`), or a
+     * specific reference layer id (e.g. an ink line-art layer above a flats layer). Closes line-art gaps
+     * up to `closeGap` px and expands (`> 0`, bleeding under lines) or contracts (`< 0`) by `expand` px.
+     * With `wet: true`, pours a watercolour wash into the region on the layer's wet layer.
+     */
+    fillRegion(options: FillRegionOptions): FillRegionResult;
+    /**
+     * Finds enclosed unfilled regions from a reference layer or the visible composite (without paper),
+     * closing line-art gaps up to `closeGap` px and returning each region's interior seed `point`,
+     * `centroid`, `bounds`, `pixelCount`, and `touchesEdge` flag.
+     */
+    findUnfilledRegions(options?: FindUnfilledRegionsOptions): {
+        regions: UnfilledRegion[];
+    };
     private applyCoverage;
     /** The registered effects provider, or `null`. */
     get effectsProvider(): EffectProvider | null;
@@ -1606,6 +1694,35 @@ export declare class PaintEditorController {
     private readMixingPad;
     /** 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

@@ -18,6 +18,7 @@ import { type LayerLocks } from '../raster/layers.js';
 import { type LayerEffect, type LayerEffectKind, type LayerEffects } from '../raster/effects/model.js';
 import type { EffectPattern } from '../raster/effects/patterns.js';
 import { TiledSurface, type RasterRect, type Tile } from '../raster/surface.js';
+import { type FillRegionPoint, type FillRegionSummary, type UnfilledRegion } from '../raster/fill.js';
 import { type PaintBrushInput, type PaintBrush } from './brushes.js';
 import { type BrushLibrary, type BrushLibraryFile } from '../brushes/library.js';
 import { type BrushPatch, type UnsettableBrushFacet } from '../brushes/patch.js';
@@ -55,6 +56,8 @@ import type { EffectDescription, EffectProvider, EffectValue } from '../effects/
 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 PaintProposals } from './collaboration.js';
+import { type BreedStrokesResult, type ProposalGenomeResult, type StrokeMutationRates } from './evolution.js';
 export declare class PaintEditorError extends Error {
     constructor(message: string);
 }
@@ -297,6 +300,75 @@ export interface FillLayerOptions {
     pressure?: number;
     blend?: BlendMode;
 }
+export type FillReference = 'layer' | 'all' | 'composite' | (string & {});
+export interface FillRegionOptions {
+    /** Seed x in document pixels (pass `x` and `y`, or `points`). */
+    x?: number;
+    /** Seed y in document pixels (pass `x` and `y`, or `points`). */
+    y?: number;
+    /** Multiple seed points in document pixels (filled together as one undo step). */
+    points?: ReadonlyArray<FillRegionPoint>;
+    /** Target layer id from `listLayers` (default the active layer). */
+    layerId?: string;
+    /**
+     * Which pixels define the region boundaries:
+     * - `'layer'` (default): the target layer itself.
+     * - `'all'` or `'composite'`: all visible layers composited (without paper).
+     * - a layer id from `listLayers`: that layer (e.g. an ink line-art layer above a flats layer).
+     */
+    reference?: FillReference;
+    /** Fill colour #rrggbb (default the editor's paint colour). */
+    color?: string;
+    /** Opacity 0..1 (default 1). */
+    opacity?: number;
+    /** Blend mode (default `'normal'`). */
+    blend?: BlendMode;
+    /** Alias for `blend`. */
+    blendMode?: BlendMode;
+    /** Colour/alpha similarity tolerance 0..255 (default 32). */
+    tolerance?: number;
+    /** Close small gaps in line art up to this width in pixels, 0..32 (default 0). */
+    closeGap?: number;
+    /** Expand (> 0, bleed under lines) or contract (< 0) the filled region in pixels, -16..16 (default 0). */
+    expand?: number;
+    /** Soften boundary edges (default true). */
+    antialias?: boolean;
+    /** Paper grain response 0..1 (default 0: flat fill). */
+    grain?: number;
+    /** With grain: pressure 0..1, how far the fill reaches into the valleys (default 0.5). */
+    pressure?: number;
+    /** Pour a wet watercolour wash into the region on the layer's wet layer (default false). */
+    wet?: boolean;
+}
+export interface FillRegionResult {
+    layerId: string;
+    bounds: RasterRect | null;
+    pixelCount: number;
+    leaked: boolean;
+    regions: FillRegionSummary[];
+    wet?: boolean;
+}
+export interface FindUnfilledRegionsOptions {
+    /** Target layer id from `listLayers` (when given, regions already painted on it are excluded). */
+    layerId?: string;
+    /**
+     * Which pixels define the line-art barriers:
+     * - `'all'` or `'composite'` (default): all visible layers composited (without paper).
+     * - `'layer'`: the target (or active) layer itself.
+     * - a layer id from `listLayers`: that layer (e.g. an ink line-art layer).
+     */
+    reference?: FillReference;
+    /** Alpha/colour threshold 0..255 above which a reference pixel is treated as line art (default 32). */
+    tolerance?: number;
+    /** Close small gaps in line art up to this width in pixels, 0..32 (default 0). */
+    closeGap?: number;
+    /** Ignore regions smaller than this many pixels (default 16). */
+    minArea?: number;
+    /** Include regions that touch the canvas border (default false: only enclosed shapes). */
+    includeEdge?: boolean;
+    /** Maximum number of regions to return, sorted largest first (default 100). */
+    maxRegions?: number;
+}
 /** Pixels to add on each side of the canvas (whole numbers, 0 or more; missing = 0). */
 export interface PaintCanvasExtension {
     left?: number;
@@ -653,6 +725,22 @@ export declare class PaintEditorController {
         layerId: string;
         bounds: RasterRect;
     };
+    /**
+     * Flood-fills one or more contiguous regions on a pixel layer (one undo step), sampling boundaries
+     * from the layer itself (`reference: 'layer'`), all visible layers (`'all'` / `'composite'`), or a
+     * specific reference layer id (e.g. an ink line-art layer above a flats layer). Closes line-art gaps
+     * up to `closeGap` px and expands (`> 0`, bleeding under lines) or contracts (`< 0`) by `expand` px.
+     * With `wet: true`, pours a watercolour wash into the region on the layer's wet layer.
+     */
+    fillRegion(options: FillRegionOptions): FillRegionResult;
+    /**
+     * Finds enclosed unfilled regions from a reference layer or the visible composite (without paper),
+     * closing line-art gaps up to `closeGap` px and returning each region's interior seed `point`,
+     * `centroid`, `bounds`, `pixelCount`, and `touchesEdge` flag.
+     */
+    findUnfilledRegions(options?: FindUnfilledRegionsOptions): {
+        regions: UnfilledRegion[];
+    };
     private applyCoverage;
     /** The registered effects provider, or `null`. */
     get effectsProvider(): EffectProvider | null;
@@ -1606,6 +1694,35 @@ export declare class PaintEditorController {
     private readMixingPad;
     /** 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/document.d.cts

@@ -69,7 +69,7 @@ export interface PaintDocumentState {
 /** A change a replay repeats besides strokes, recorded with how many strokes came before it. */
 export interface PaintEvent {
     at: number;
-    kind: 'fill' | 'clear' | 'flatten' | 'stickers' | 'live-strokes';
+    kind: 'fill' | 'fill-region' | 'clear' | 'flatten' | 'stickers' | 'live-strokes';
     layerId: string;
     /** The fill's options (colour, opacity, grain, pressure, blend), or the layer's stickers or live strokes after an edit. */
     data?: Record<string, unknown>;

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

@@ -69,7 +69,7 @@ export interface PaintDocumentState {
 /** A change a replay repeats besides strokes, recorded with how many strokes came before it. */
 export interface PaintEvent {
     at: number;
-    kind: 'fill' | 'clear' | 'flatten' | 'stickers' | 'live-strokes';
+    kind: 'fill' | 'fill-region' | 'clear' | 'flatten' | 'stickers' | 'live-strokes';
     layerId: string;
     /** The fill's options (colour, opacity, grain, pressure, blend), or the layer's stickers or live strokes after an edit. */
     data?: Record<string, unknown>;

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 };