@pixerate/editor 0.272.1 → 0.274.0

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