@pixerate/editor 0.275.1 → 0.277.0

package/dist/paint/live-patterns.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Live patterns: Gray-Scott reaction-diffusion fields `(U, V)` that grow inside wet paint and
+ * freeze where the paint dries.
+ *
+ * Each wet layer with live patterns active holds a sparse set of half-resolution (`128 × 128`)
+ * pattern tiles paired with the `256 × 256` tiles of `WetWorld`, outside the wet-media LBM kernel.
+ * Every wet simulation step runs Gray-Scott substeps gated by the wet layer's water (`P_RHO` +
+ * `P_SW > DRY_EPS`): where water remains, `U` and `V` react and diffuse into Turing spots,
+ * stripes, coral dendrites, mazes or worms; where the paint has dried, the reaction and diffusion
+ * rates drop to zero so the pattern freezes in place.
+ */
+import { TiledSurface, type RasterRect } from '../raster/surface.js';
+/** Side length of one half-resolution pattern tile (`WET_TILE / 2`). */
+export declare const PATTERN_TILE = 128;
+/** Cells per pattern tile (`128 × 128`). */
+export declare const PATTERN_CELLS: number;
+/** Gray-Scott substeps run for each wet simulation step. */
+export declare const PATTERN_SUBSTEPS = 4;
+/** Threshold of `V` above which a cell counts as pattern-bearing in stats and relief. */
+export declare const PATTERN_V_EPS = 0.02;
+/** Named Gray-Scott Pearson pattern presets. */
+export declare const LIVE_PATTERN_KINDS: readonly ["spots", "stripes", "coral", "maze", "worms"];
+export type LivePatternKind = (typeof LIVE_PATTERN_KINDS)[number];
+export interface LivePatternPresetInfo {
+    readonly kind: LivePatternKind;
+    readonly label: string;
+    readonly description: string;
+    readonly feed: number;
+    readonly kill: number;
+}
+/** Built-in Pearson (1993) feed / kill parameter presets. */
+export declare const LIVE_PATTERN_PRESETS: Readonly<Record<LivePatternKind, LivePatternPresetInfo>>;
+/** Resolved live-pattern parameters for a brush or wet layer. */
+export interface LivePatternsSettings {
+    /** Named Gray-Scott preset (`spots`, `stripes`, `coral`, `maze`, `worms`). */
+    pattern: LivePatternKind;
+    /** Gray-Scott feed rate F (0.01..0.1). */
+    feed: number;
+    /** Gray-Scott kill rate k (0.03..0.08). */
+    kill: number;
+    /** Pattern feature scale (0.5..4, default 1). Scales the diffusion rates. */
+    scale: number;
+    /** Visual contrast of the V concentration field (0..2, default 1). */
+    contrast: number;
+    /** Optional hex colour (`#rrggbb`) that V blends the wet paint towards; `null` modulates pigment contrast. */
+    secondColor: string | null;
+    /** Impasto relief written to the layer's thick height map as patterns grow (0..1, default 0). */
+    relief: number;
+}
+export type LivePatternsInput = Partial<LivePatternsSettings>;
+export declare const DEFAULT_LIVE_PATTERNS: Readonly<LivePatternsSettings>;
+export declare function isLivePatternKind(v: unknown): v is LivePatternKind;
+/** Normalizes a hex colour string (`#rgb` or `#rrggbb`) to lowercase `#rrggbb`, or `null`. */
+export declare function normalizePatternHexColor(v: unknown, fallback?: string | null): string | null;
+/** Parses a `#rrggbb` colour to `[r, g, b]` bytes, or `null`. */
+export declare function parsePatternHexColor(hex: string | null): [number, number, number] | null;
+/** Clamps and fills a `LivePatternsSettings` object from partial input. */
+export declare function normalizeLivePatterns(raw?: LivePatternsInput | null | undefined, base?: LivePatternsSettings): LivePatternsSettings;
+/** Deterministic 32-bit integer hash in `[0, 1)` shared between TypeScript and Swift. */
+export declare function patternNoise(gx: number, gy: number, seed: number): number;
+/** Summary statistics for one wet layer's Gray-Scott field. */
+export interface LivePatternStats {
+    /** Whether live patterns are enabled on this layer. */
+    enabled: boolean;
+    /** Current Gray-Scott reaction-diffusion settings for this layer. */
+    settings: LivePatternsSettings;
+    /** Half-resolution (`128 × 128`) tiles currently holding pattern state. */
+    activeTiles: number;
+    /** Pattern cells (`2 × 2` px each) where `V >= PATTERN_V_EPS`. */
+    patternCells: number;
+    /** Pattern cells where `V >= PATTERN_V_EPS` that are still wet (actively growing). */
+    wetPatternCells: number;
+    /** Mean `V` concentration across active pattern cells (0..1). */
+    meanV: number;
+    /** Peak `V` concentration across the layer (0..1). */
+    maxV: number;
+    /** Document pixel bounding box of active pattern cells, or `null` when none. */
+    bounds: RasterRect | null;
+}
+export interface LivePatternTileState {
+    readonly u: Float64Array;
+    readonly v: Float64Array;
+    readonly bakedV: Float64Array;
+}
+export interface LivePatternFieldSnapshot {
+    readonly settings: LivePatternsSettings;
+    readonly enabled: boolean;
+    readonly tiles: ReadonlyMap<number, LivePatternTileState>;
+    readonly bytes: number;
+}
+/** Callback returning whether a half-res pattern cell `(tx, ty, lx, ly)` still holds water. */
+export type WetCellPredicate = (tx: number, ty: number, lx: number, ly: number) => boolean;
+/**
+ * Per-wet-layer Gray-Scott reaction-diffusion field `(U, V)` stored in `128 × 128` tiles.
+ */
+export declare class LivePatternField {
+    width: number;
+    height: number;
+    tilesX: number;
+    tilesY: number;
+    settings: LivePatternsSettings;
+    enabled: boolean;
+    readonly tiles: Map<number, {
+        u: Float64Array;
+        v: Float64Array;
+        bakedV: Float64Array;
+    }>;
+    constructor(width: number, height: number, settings?: LivePatternsInput);
+    resize(width: number, height: number): void;
+    configure(settings: LivePatternsInput): LivePatternsSettings;
+    clear(): void;
+    private ensureTile;
+    /**
+     * Seeds Gray-Scott reagent `V` inside a circle at document coordinates `(cx, cy)` with document
+     * `radius` (pixels). Returns the number of half-resolution cells seeded.
+     */
+    seedDisc(cx: number, cy: number, radius: number, seed?: number, strength?: number): number;
+    /**
+     * Advances the Gray-Scott reaction-diffusion field for `wetSteps` wet simulation steps.
+     * Only cells where `isWetCell(tx, ty, lx, ly)` is true update; dry cells have zero rate and freeze.
+     * Returns whether any cell updated.
+     */
+    step(wetSteps: number, isWetCell: WetCellPredicate, canWakeTile?: (tx: number, ty: number) => boolean): boolean;
+    /**
+     * Bilinearly samples unbaked `V` (`max(0, v - bakedV)`) at document-tile pixel `(x, y)` in `0..255`.
+     */
+    private sampleUnbakedV;
+    /**
+     * Blends the pattern's `V` concentration into a shaded `256 × 256` RGBA wet tile `out`.
+     * Returns whether any pixel in `out` was modified.
+     */
+    shadeTile(tx: number, ty: number, out: Uint8ClampedArray, w: number, h: number): boolean;
+    /** Marks a tile's current `V` values as baked into the layer's base surface so they are not baked twice. */
+    markBaked(tx: number, ty: number): void;
+    /**
+     * When `settings.relief > 0`, writes pattern `V` ridges into a 1-channel thick height surface.
+     * Returns the updated height `TiledSurface`, or `currentHeight` when `relief <= 0` or nothing changed.
+     */
+    applyReliefHeight(currentHeight: TiledSurface): TiledSurface;
+    /** Computes summary statistics of the layer's live pattern field. */
+    stats(isWetCell?: WetCellPredicate): LivePatternStats;
+    snapshot(): LivePatternFieldSnapshot;
+    restore(snap: LivePatternFieldSnapshot): void;
+}
+/** Shifts a `LivePatternFieldSnapshot` by `(tx0, ty0)` whole wet tiles for a resized canvas `to`. */
+export declare function moveLivePatternSnapshot(snap: LivePatternFieldSnapshot, to: {
+    width: number;
+    height: number;
+}, tx0: number, ty0: number): LivePatternFieldSnapshot;

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

@@ -29,6 +29,7 @@
  *   only feeds the display.
  */
 import { TiledSurface, type RasterRect } from '../../raster/surface.cjs';
+import { LivePatternField, type LivePatternFieldSnapshot, type LivePatternStats, type LivePatternsInput, type LivePatternsSettings } from '../live-patterns.cjs';
 import { type WetPaper, type WetParams, type WetTilt } from './model.cjs';
 import { type WetWorkerLayout } from './wasm.cjs';
 import type { WetGpuEngine } from './gpu.cjs';
@@ -81,6 +82,8 @@ export interface WetLaneOptions {
     flowStrength?: number;
     /** The layer's light paint under the wet paint (one channel; default none). */
     light?: TiledSurface | null;
+    /** Shared per-layer reaction-diffusion field outside the wet kernel. */
+    livePatterns?: LivePatternField;
     /** Active ghost paint state on the layer, if any. */
     ghost?: WetGhostState | null;
 }
@@ -111,12 +114,15 @@ export interface WetSnapshot {
         light?: TiledSurface;
         lit?: boolean;
         ghost?: WetGhostState | null;
+        livePatterns?: LivePatternFieldSnapshot;
     }>;
     /** Per active key: the current set and the deposit planes; and its last flags. */
     readonly slots: ReadonlyMap<number, {
         planes: Float32Array;
         last: number;
     }>;
+    /** Per-layer live-pattern snapshots (including layers whose water has already dried). */
+    readonly patterns?: ReadonlyMap<string, LivePatternFieldSnapshot>;
     /** Bytes held. */
     readonly bytes: number;
 }
@@ -190,6 +196,13 @@ export declare class WetWorld {
     removeLane(id: string): void;
     getParams(id: string): WetParams;
     setParams(id: string, params: Partial<WetParams>): WetParams;
+    getLivePatterns(id: string): LivePatternsSettings;
+    hasLivePatterns(id: string): boolean;
+    livePatternField(id: string): LivePatternField;
+    setLivePatterns(id: string, settings: LivePatternsInput): LivePatternsSettings;
+    seedLivePatterns(id: string, cx: number, cy: number, radius: number, seed?: number, strength?: number, settings?: LivePatternsInput): number;
+    livePatternStats(id: string): LivePatternStats;
+    private isPatternCellWet;
     getTilt(): WetTilt;
     setTilt(tilt: Partial<WetTilt>): WetTilt;
     /** Changes the paper: heights of live tiles are refilled, rates repacked. */

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

@@ -29,6 +29,7 @@
  *   only feeds the display.
  */
 import { TiledSurface, type RasterRect } from '../../raster/surface.js';
+import { LivePatternField, type LivePatternFieldSnapshot, type LivePatternStats, type LivePatternsInput, type LivePatternsSettings } from '../live-patterns.js';
 import { type WetPaper, type WetParams, type WetTilt } from './model.js';
 import { type WetWorkerLayout } from './wasm.js';
 import type { WetGpuEngine } from './gpu.js';
@@ -81,6 +82,8 @@ export interface WetLaneOptions {
     flowStrength?: number;
     /** The layer's light paint under the wet paint (one channel; default none). */
     light?: TiledSurface | null;
+    /** Shared per-layer reaction-diffusion field outside the wet kernel. */
+    livePatterns?: LivePatternField;
     /** Active ghost paint state on the layer, if any. */
     ghost?: WetGhostState | null;
 }
@@ -111,12 +114,15 @@ export interface WetSnapshot {
         light?: TiledSurface;
         lit?: boolean;
         ghost?: WetGhostState | null;
+        livePatterns?: LivePatternFieldSnapshot;
     }>;
     /** Per active key: the current set and the deposit planes; and its last flags. */
     readonly slots: ReadonlyMap<number, {
         planes: Float32Array;
         last: number;
     }>;
+    /** Per-layer live-pattern snapshots (including layers whose water has already dried). */
+    readonly patterns?: ReadonlyMap<string, LivePatternFieldSnapshot>;
     /** Bytes held. */
     readonly bytes: number;
 }
@@ -190,6 +196,13 @@ export declare class WetWorld {
     removeLane(id: string): void;
     getParams(id: string): WetParams;
     setParams(id: string, params: Partial<WetParams>): WetParams;
+    getLivePatterns(id: string): LivePatternsSettings;
+    hasLivePatterns(id: string): boolean;
+    livePatternField(id: string): LivePatternField;
+    setLivePatterns(id: string, settings: LivePatternsInput): LivePatternsSettings;
+    seedLivePatterns(id: string, cx: number, cy: number, radius: number, seed?: number, strength?: number, settings?: LivePatternsInput): number;
+    livePatternStats(id: string): LivePatternStats;
+    private isPatternCellWet;
     getTilt(): WetTilt;
     setTilt(tilt: Partial<WetTilt>): WetTilt;
     /** Changes the paper: heights of live tiles are refilled, rates repacked. */

package/dist/paint-editor/brush-model.d.cts

@@ -8,7 +8,9 @@ import { type BlenderSettings, type SmudgeSettings } from '../paint/blending.cjs
 import type { MixingModel } from '../paint/exchange.cjs';
 import { type PaintGradientSource, type PaintSource } from '../paint/gradient-paint.cjs';
 import { type MixerSettings } from '../paint/mixer.cjs';
+import { DEFAULT_LIVE_PATTERNS, LIVE_PATTERN_KINDS, LIVE_PATTERN_PRESETS, normalizeLivePatterns, type LivePatternKind, type LivePatternsInput, type LivePatternsSettings } from '../paint/live-patterns.cjs';
 import { type BristleSettings, type ParticleSettings, type StickerSettings } from './mark-settings.cjs';
+export { DEFAULT_LIVE_PATTERNS, LIVE_PATTERN_KINDS, LIVE_PATTERN_PRESETS, normalizeLivePatterns, type LivePatternKind, type LivePatternsInput, type LivePatternsSettings };
 /**
  * How a brush makes marks: `dab` (dabs into a stroke buffer, or dab by dab through the pick-up /
  * mix exchange when its behaviour asks for it), `eraser` (removes alpha), `mixer` (the Mixer
@@ -147,6 +149,17 @@ export interface MutationSettings {
 }
 export declare const DEFAULT_MUTATION: Readonly<MutationSettings>;
 export declare function normalizeMutation(raw?: Partial<MutationSettings>, base?: MutationSettings): MutationSettings;
+/** Ferrofluid paint: how much liquid ferrofluid a brush lays, and its Rosensweig spike settings (see `doc.ferro`). */
+export interface FerroSettings {
+    /** How much liquid ferrofluid each dab lays, scaled by coverage and flow (0..1, default 0: none). */
+    amount: number;
+    /** Capillary wavelength (spike-to-spike spacing) in pixels (4..64, default 16). */
+    wavelength: number;
+    /** Critical magnetic field |B| threshold where spikes begin to rise (0.01..0.95, default 0.12). */
+    threshold: number;
+}
+export declare const DEFAULT_FERRO: Readonly<FerroSettings>;
+export declare function normalizeFerro(raw?: number | Partial<FerroSettings> | null | undefined, base?: FerroSettings): FerroSettings;
 export declare function normalizeImpasto(raw?: Partial<ImpastoSettings>, base?: ImpastoSettings): ImpastoSettings;
 /** Multi-coloured brush: `tip` lays the colours across the tip, `dab` changes colour from dab to dab. */
 export type MultiColorMode = 'off' | 'tip' | 'dab';
@@ -281,6 +294,8 @@ export interface PaintBrush {
     ghost?: GhostSettings;
     /** Mutation paint settings (missing when not a mutation brush). */
     mutation?: MutationSettings;
+    /** Ferrofluid paint: liquid ferrofluid it lays and its Rosensweig spike settings (amount 0: none). */
+    ferro: FerroSettings;
     /**
      * Dab engine: a stamp tip. Each dab (and each spray droplet) is this sticker's shape, an editor
      * stamp (`editor:star`) or any sticker ref from the sticker library, laid in the paint colour;
@@ -291,6 +306,8 @@ export interface PaintBrush {
     spray: SpraySettings | null;
     /** Dab engines: texture inside the tip (missing: none). Recorded with the stroke, source ref included, so replays match. */
     tipGrain?: TipGrainSettings;
+    /** Wet engine: Gray-Scott reaction-diffusion pattern seeded into the wet paint (missing: none). */
+    livePatterns?: LivePatternsSettings;
     /**
      * The brush's own gradient paint (`@pixerate/editor/paint` `PaintGradientSource`), used instead
      * of the editor's paint; `null` (default): the editor's paint. Stops may be `paint` / `secondary`
@@ -317,7 +334,7 @@ export interface SpraySettings {
     size: number;
 }
 export declare const DEFAULT_SPRAY: Readonly<SpraySettings>;
-export type PaintBrushInput = Partial<Omit<PaintBrush, 'tip' | 'dynamics' | 'mixer' | 'behavior' | 'blender' | 'smudge' | 'wet' | 'impasto' | 'particle' | 'bristle' | 'sticker' | 'paint' | 'light' | 'fluorescence' | 'thermochromic' | 'iridescence' | 'ghost' | 'mutation' | 'spray' | 'tipGrain'>> & {
+export type PaintBrushInput = Partial<Omit<PaintBrush, 'tip' | 'dynamics' | 'mixer' | 'behavior' | 'blender' | 'smudge' | 'wet' | 'impasto' | 'particle' | 'bristle' | 'sticker' | 'paint' | 'light' | 'fluorescence' | 'thermochromic' | 'iridescence' | 'ghost' | 'mutation' | 'ferro' | 'spray' | 'tipGrain' | 'livePatterns'>> & {
     spray?: Partial<SpraySettings> | null;
     /** Tip grain (`null` removes it). */
     tipGrain?: Partial<TipGrainSettings> | null;
@@ -325,11 +342,14 @@ export type PaintBrushInput = Partial<Omit<PaintBrush, 'tip' | 'dynamics' | 'mix
     ghost?: Partial<GhostSettings> | null;
     /** Mutation paint (`null` removes it). */
     mutation?: Partial<MutationSettings> | null;
+    /** Live reaction-diffusion patterns (`null` removes it). */
+    livePatterns?: LivePatternsInput | null;
     light?: Partial<LightSettings>;
     fluorescence?: Partial<FluorescenceSettings> | number;
     thermochromic?: Partial<ThermochromicSettings>;
     /** Thin-film iridescence (`null` removes it). */
     iridescence?: Partial<IridescenceSettings> | null;
+    ferro?: number | Partial<FerroSettings>;
     /** A gradient (or `null` for the editor's paint); a plain colour source clears it. */
     paint?: PaintSource | null;
     tip?: Partial<BrushSettings>;

package/dist/paint-editor/brush-model.d.ts

@@ -8,7 +8,9 @@ import { type BlenderSettings, type SmudgeSettings } from '../paint/blending.js'
 import type { MixingModel } from '../paint/exchange.js';
 import { type PaintGradientSource, type PaintSource } from '../paint/gradient-paint.js';
 import { type MixerSettings } from '../paint/mixer.js';
+import { DEFAULT_LIVE_PATTERNS, LIVE_PATTERN_KINDS, LIVE_PATTERN_PRESETS, normalizeLivePatterns, type LivePatternKind, type LivePatternsInput, type LivePatternsSettings } from '../paint/live-patterns.js';
 import { type BristleSettings, type ParticleSettings, type StickerSettings } from './mark-settings.js';
+export { DEFAULT_LIVE_PATTERNS, LIVE_PATTERN_KINDS, LIVE_PATTERN_PRESETS, normalizeLivePatterns, type LivePatternKind, type LivePatternsInput, type LivePatternsSettings };
 /**
  * How a brush makes marks: `dab` (dabs into a stroke buffer, or dab by dab through the pick-up /
  * mix exchange when its behaviour asks for it), `eraser` (removes alpha), `mixer` (the Mixer
@@ -147,6 +149,17 @@ export interface MutationSettings {
 }
 export declare const DEFAULT_MUTATION: Readonly<MutationSettings>;
 export declare function normalizeMutation(raw?: Partial<MutationSettings>, base?: MutationSettings): MutationSettings;
+/** Ferrofluid paint: how much liquid ferrofluid a brush lays, and its Rosensweig spike settings (see `doc.ferro`). */
+export interface FerroSettings {
+    /** How much liquid ferrofluid each dab lays, scaled by coverage and flow (0..1, default 0: none). */
+    amount: number;
+    /** Capillary wavelength (spike-to-spike spacing) in pixels (4..64, default 16). */
+    wavelength: number;
+    /** Critical magnetic field |B| threshold where spikes begin to rise (0.01..0.95, default 0.12). */
+    threshold: number;
+}
+export declare const DEFAULT_FERRO: Readonly<FerroSettings>;
+export declare function normalizeFerro(raw?: number | Partial<FerroSettings> | null | undefined, base?: FerroSettings): FerroSettings;
 export declare function normalizeImpasto(raw?: Partial<ImpastoSettings>, base?: ImpastoSettings): ImpastoSettings;
 /** Multi-coloured brush: `tip` lays the colours across the tip, `dab` changes colour from dab to dab. */
 export type MultiColorMode = 'off' | 'tip' | 'dab';
@@ -281,6 +294,8 @@ export interface PaintBrush {
     ghost?: GhostSettings;
     /** Mutation paint settings (missing when not a mutation brush). */
     mutation?: MutationSettings;
+    /** Ferrofluid paint: liquid ferrofluid it lays and its Rosensweig spike settings (amount 0: none). */
+    ferro: FerroSettings;
     /**
      * Dab engine: a stamp tip. Each dab (and each spray droplet) is this sticker's shape, an editor
      * stamp (`editor:star`) or any sticker ref from the sticker library, laid in the paint colour;
@@ -291,6 +306,8 @@ export interface PaintBrush {
     spray: SpraySettings | null;
     /** Dab engines: texture inside the tip (missing: none). Recorded with the stroke, source ref included, so replays match. */
     tipGrain?: TipGrainSettings;
+    /** Wet engine: Gray-Scott reaction-diffusion pattern seeded into the wet paint (missing: none). */
+    livePatterns?: LivePatternsSettings;
     /**
      * The brush's own gradient paint (`@pixerate/editor/paint` `PaintGradientSource`), used instead
      * of the editor's paint; `null` (default): the editor's paint. Stops may be `paint` / `secondary`
@@ -317,7 +334,7 @@ export interface SpraySettings {
     size: number;
 }
 export declare const DEFAULT_SPRAY: Readonly<SpraySettings>;
-export type PaintBrushInput = Partial<Omit<PaintBrush, 'tip' | 'dynamics' | 'mixer' | 'behavior' | 'blender' | 'smudge' | 'wet' | 'impasto' | 'particle' | 'bristle' | 'sticker' | 'paint' | 'light' | 'fluorescence' | 'thermochromic' | 'iridescence' | 'ghost' | 'mutation' | 'spray' | 'tipGrain'>> & {
+export type PaintBrushInput = Partial<Omit<PaintBrush, 'tip' | 'dynamics' | 'mixer' | 'behavior' | 'blender' | 'smudge' | 'wet' | 'impasto' | 'particle' | 'bristle' | 'sticker' | 'paint' | 'light' | 'fluorescence' | 'thermochromic' | 'iridescence' | 'ghost' | 'mutation' | 'ferro' | 'spray' | 'tipGrain' | 'livePatterns'>> & {
     spray?: Partial<SpraySettings> | null;
     /** Tip grain (`null` removes it). */
     tipGrain?: Partial<TipGrainSettings> | null;
@@ -325,11 +342,14 @@ export type PaintBrushInput = Partial<Omit<PaintBrush, 'tip' | 'dynamics' | 'mix
     ghost?: Partial<GhostSettings> | null;
     /** Mutation paint (`null` removes it). */
     mutation?: Partial<MutationSettings> | null;
+    /** Live reaction-diffusion patterns (`null` removes it). */
+    livePatterns?: LivePatternsInput | null;
     light?: Partial<LightSettings>;
     fluorescence?: Partial<FluorescenceSettings> | number;
     thermochromic?: Partial<ThermochromicSettings>;
     /** Thin-film iridescence (`null` removes it). */
     iridescence?: Partial<IridescenceSettings> | null;
+    ferro?: number | Partial<FerroSettings>;
     /** A gradient (or `null` for the editor's paint); a plain colour source clears it. */
     paint?: PaintSource | null;
     tip?: Partial<BrushSettings>;

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

@@ -50,6 +50,7 @@ import { PaintWetLayers, type PaintWetOptions, type WetEngineInfo, type WetGpuMo
 import { type WetParams, type WetTilt } from '../paint/wet/model.cjs';
 import { type WetFlowSpec } from '../paint/wet/flow.cjs';
 import { type WetBackendInfo } from '../paint/wet/world.cjs';
+import { type LivePatternKind, type LivePatternStats, type LivePatternsInput } from '../paint/live-patterns.cjs';
 import { type TimeLapse, type TimeLapseOptions } from './replay.cjs';
 import { EffectsSlot } from '../effects/helpers.cjs';
 import type { EffectDescription, EffectProvider, EffectValue } from '../effects/types.cjs';
@@ -62,6 +63,7 @@ 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';
+import { type PaintMagnet } from './ferro.cjs';
 export declare class PaintEditorError extends Error {
     constructor(message: string);
 }
@@ -121,6 +123,13 @@ export interface PaintWetStateInfo {
     /** Engine B is shading the wet paint now. */
     gpuActive: boolean;
 }
+/** One layer's Gray-Scott live-pattern state and wet coverage. */
+export interface PaintLayerLivePatternsInfo extends LivePatternStats {
+    layerId: string;
+    wet: boolean;
+    wetCells: number;
+    wetBounds: RasterRect | null;
+}
 export interface PaintEditorState {
     document: PaintDocumentState;
     /** The active brush (possibly edited from its preset). */
@@ -540,6 +549,9 @@ export declare class PaintEditorController {
     private readonly litCaches;
     /** The live impasto stroke's channels. */
     private liveThick;
+    /** The live ferrofluid stroke's channel. */
+    private liveFerro;
+    private nextMagnetId;
     /** The UV / blacklight setting (saved with the document, not undo steps). */
     private uvLight;
     private readonly uvCaches;
@@ -1278,6 +1290,51 @@ export declare class PaintEditorController {
         layerId: string;
         flattened: boolean;
     };
+    /** The document's `ferro` and `ferroSettings` without these layers. */
+    private ferroWithout;
+    /** Runs deterministic advection on all pixel layers with liquid ferrofluid toward `magnets`. */
+    private advectDocumentFerro;
+    /** Lists the magnets on the canvas. */
+    listMagnets(): PaintMagnet[];
+    /** Places a dipole magnet on the canvas and advects liquid ferrofluid toward it (one undo step). */
+    addMagnet(input: {
+        x: number;
+        y: number;
+        strength?: number;
+        radius?: number;
+    }): PaintMagnet;
+    /** Moves or retunes a magnet and advects liquid ferrofluid toward the magnets (one undo step). */
+    updateMagnet(id: string, update: {
+        x?: number;
+        y?: number;
+        strength?: number;
+        radius?: number;
+    }, commitToHistory?: boolean): PaintMagnet;
+    /** Removes magnets by id, or all magnets when `ids` is omitted or empty (one undo step). Returns the removed ids. */
+    removeMagnets(ids?: readonly string[]): string[];
+    /** Replaces the canvas magnets (used by replay). */
+    replaceMagnets(magnets: readonly PaintMagnet[], advect?: boolean): void;
+    /** Reads a layer's liquid ferrofluid coverage and active Rosensweig spike relief under the canvas magnets. */
+    getFerrofluid(layerId?: string): {
+        layerId: string;
+        ferro: boolean;
+        bounds: RasterRect | null;
+        peak: number;
+        coverage: number;
+        activeSpikeArea: number;
+        maxSpikeHeight: number;
+        magnetCount: number;
+        wavelength: number;
+        threshold: number;
+    };
+    /** Cures a layer's liquid ferrofluid: bakes the current Rosensweig spikes and glossy metallic material into `doc.thick` and clears `doc.ferro` (one undo step). */
+    cureFerrofluid(layerId?: string): {
+        layerId: string;
+        cured: boolean;
+        bounds: RasterRect | null;
+        maxSpikeHeight: number;
+        activeSpikeArea: number;
+    };
     /**
      * A fresh, headless editor for replaying this painting at `scale` (canvas, dpi and paper grain
      * scaled; every pixel layer empty; the same brushes, lighting and wet options). Dispose of it
@@ -1406,6 +1463,50 @@ export declare class PaintEditorController {
         ty: number;
         data: Uint8ClampedArray;
     }>;
+    private layerLivePatternsInfo;
+    private checkLivePatternsInput;
+    /**
+     * Reads a layer's Gray-Scott reaction-diffusion live patterns (`layerId`, default the active
+     * layer), plus all layers with wet paint or live patterns and the built-in Pearson presets.
+     */
+    getLivePatterns(layerId?: string): PaintLayerLivePatternsInfo & {
+        layers: PaintLayerLivePatternsInfo[];
+        presets: Readonly<Record<LivePatternKind, {
+            feed: number;
+            kill: number;
+        }>>;
+        brushPresets: readonly string[];
+    };
+    /**
+     * Configures a layer's Gray-Scott reaction-diffusion live patterns (or clears them with
+     * `enabled: false`). One undo step.
+     */
+    setLivePatterns(layerId: string | undefined, update: LivePatternsInput & {
+        enabled?: boolean;
+    }): PaintLayerLivePatternsInfo;
+    /**
+     * Seeds Gray-Scott reaction-diffusion activator (`V`) discs into a layer's live-pattern field so
+     * patterns grow where the layer holds wet water and freeze where it dries. One undo step.
+     */
+    seedLivePatterns(options: {
+        layerId?: string;
+        points: ReadonlyArray<{
+            x: number;
+            y: number;
+            strength?: number;
+        }>;
+        radius?: number;
+        seed?: number;
+        pattern?: LivePatternKind;
+        feed?: number;
+        kill?: number;
+        scale?: number;
+        contrast?: number;
+        secondColor?: string | null;
+        relief?: number;
+    }): PaintLayerLivePatternsInfo & {
+        seededCells: number;
+    };
     private sources;
     /** The layers with the live stroke's surface in place. */
     private currentLayers;
@@ -1425,7 +1526,7 @@ export declare class PaintEditorController {
      * 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). */
+    /** The layers with thick paint and ferrofluid spikes lit (each thick or ferrofluid layer's pixels replaced by its lit tiles). */
     private litLayers;
     /**
      * Light paint over the (lit) layers: glow, rim and clarity in each layer's pixels, and its spill