@pixerate/editor 0.275.1 → 0.277.0

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

@@ -50,6 +50,7 @@ import { PaintWetLayers, type PaintWetOptions, type WetEngineInfo, type WetGpuMo
 import { type WetParams, type WetTilt } from '../paint/wet/model.js';
 import { type WetFlowSpec } from '../paint/wet/flow.js';
 import { type WetBackendInfo } from '../paint/wet/world.js';
+import { type LivePatternKind, type LivePatternStats, type LivePatternsInput } from '../paint/live-patterns.js';
 import { type TimeLapse, type TimeLapseOptions } from './replay.js';
 import { EffectsSlot } from '../effects/helpers.js';
 import type { EffectDescription, EffectProvider, EffectValue } from '../effects/types.js';
@@ -62,6 +63,7 @@ import type { PaintDirector } from './presence.js';
 import type { PresenceActorInfo } from '../animation/presence.js';
 import { type PaintProposals } from './collaboration.js';
 import { type BreedStrokesResult, type ProposalGenomeResult, type StrokeMutationRates } from './evolution.js';
+import { type PaintMagnet } from './ferro.js';
 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

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

@@ -13,6 +13,7 @@ import { type PaperSettings } from './paper.cjs';
 import type { RecordedStroke } from './strokes.cjs';
 import type { WetEvent } from './wet.cjs';
 import type { ThickChannels } from './thick.cjs';
+import type { FerroSettings, PaintMagnet } from './ferro.cjs';
 import type { Sticker } from './stickers.cjs';
 import type { PaintEffectSource, PaintPaperEffect } from './effects.cjs';
 import type { HeatField } from './heat.cjs';
@@ -61,6 +62,12 @@ export interface PaintDocumentState {
     thermo?: Readonly<Record<string, TiledSurface>>;
     /** Coarse document-level heat field (1/4 resolution) for thermochromic ink and wet-paint drying. See `heat.ts`. */
     heat?: HeatField;
+    /** Ferrofluid paint: each layer's liquid ferrofluid channel, 0..255 per pixel in layer space (layers without ferrofluid are missing). See `ferro.ts`. */
+    ferro?: Readonly<Record<string, TiledSurface>>;
+    /** Per-layer Rosensweig spike settings (`wavelength`, `threshold`) from the last ferrofluid stroke on that layer. */
+    ferroSettings?: Readonly<Record<string, FerroSettings>>;
+    /** Dipole magnets placed on the canvas (document pixel coordinates). */
+    magnets?: PaintMagnet[];
     /** Thick paint: each layer's height and material channels (layers without relief are missing). */
     thick?: Readonly<Record<string, ThickChannels>>;
     /** Effect layers: the provider effect each one is drawn from (layers that are gone are ignored). */
@@ -79,7 +86,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' | 'fill-region' | 'clear' | 'flatten' | 'stickers' | 'live-strokes';
+    kind: 'fill' | 'fill-region' | 'clear' | 'flatten' | 'stickers' | 'live-strokes' | 'magnets' | 'cure-ferrofluid';
     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

@@ -13,6 +13,7 @@ import { type PaperSettings } from './paper.js';
 import type { RecordedStroke } from './strokes.js';
 import type { WetEvent } from './wet.js';
 import type { ThickChannels } from './thick.js';
+import type { FerroSettings, PaintMagnet } from './ferro.js';
 import type { Sticker } from './stickers.js';
 import type { PaintEffectSource, PaintPaperEffect } from './effects.js';
 import type { HeatField } from './heat.js';
@@ -61,6 +62,12 @@ export interface PaintDocumentState {
     thermo?: Readonly<Record<string, TiledSurface>>;
     /** Coarse document-level heat field (1/4 resolution) for thermochromic ink and wet-paint drying. See `heat.ts`. */
     heat?: HeatField;
+    /** Ferrofluid paint: each layer's liquid ferrofluid channel, 0..255 per pixel in layer space (layers without ferrofluid are missing). See `ferro.ts`. */
+    ferro?: Readonly<Record<string, TiledSurface>>;
+    /** Per-layer Rosensweig spike settings (`wavelength`, `threshold`) from the last ferrofluid stroke on that layer. */
+    ferroSettings?: Readonly<Record<string, FerroSettings>>;
+    /** Dipole magnets placed on the canvas (document pixel coordinates). */
+    magnets?: PaintMagnet[];
     /** Thick paint: each layer's height and material channels (layers without relief are missing). */
     thick?: Readonly<Record<string, ThickChannels>>;
     /** Effect layers: the provider effect each one is drawn from (layers that are gone are ignored). */
@@ -79,7 +86,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' | 'fill-region' | 'clear' | 'flatten' | 'stickers' | 'live-strokes';
+    kind: 'fill' | 'fill-region' | 'clear' | 'flatten' | 'stickers' | 'live-strokes' | 'magnets' | 'cure-ferrofluid';
     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/ferro-tools.d.cts

@@ -0,0 +1,10 @@
+/**
+ * Agent tools for ferrofluid paint and magnets: ferrofluid strokes are painted with `paint_stroke`
+ * and a brush whose `ferro.amount` is above 0 (`ferrofluid`, `ferro-ink`); these tools place,
+ * move and remove magnets (`add_magnet`, `update_magnet`, `remove_magnets`, `list_magnets`), read
+ * a layer's liquid ferrofluid and live Rosensweig spike stats (`get_ferrofluid`), and cure the
+ * liquid spikes into solid impasto relief (`cure_ferrofluid`).
+ */
+import type { PaintAgentTool } from './hosted.cjs';
+import type { PaintEditorController } from './controller.cjs';
+export declare function createFerroTools(c: PaintEditorController): PaintAgentTool[];

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

@@ -0,0 +1,10 @@
+/**
+ * Agent tools for ferrofluid paint and magnets: ferrofluid strokes are painted with `paint_stroke`
+ * and a brush whose `ferro.amount` is above 0 (`ferrofluid`, `ferro-ink`); these tools place,
+ * move and remove magnets (`add_magnet`, `update_magnet`, `remove_magnets`, `list_magnets`), read
+ * a layer's liquid ferrofluid and live Rosensweig spike stats (`get_ferrofluid`), and cure the
+ * liquid spikes into solid impasto relief (`cure_ferrofluid`).
+ */
+import type { PaintAgentTool } from './hosted.js';
+import type { PaintEditorController } from './controller.js';
+export declare function createFerroTools(c: PaintEditorController): PaintAgentTool[];

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

@@ -0,0 +1,134 @@
+/**
+ * Ferrofluid paint: a per-layer liquid ferrofluid channel (`doc.ferro`, one byte 0..255 per pixel
+ * in layer space, like `doc.light`) and document-space magnets (`doc.magnets`).
+ *
+ * Where the analytical dipole magnetic field `|B|` exceeds the critical threshold `Bc` and
+ * `ferro > 0`, the liquid rises into a hexagonal Rosensweig spike relief field whose spacing
+ * follows the capillary wavelength, whose amplitude scales as `sqrt(1 - Bc / |B|) * ferro`, and
+ * whose peaks tilt along `B`. Adding or moving a magnet runs deterministic advection steps on
+ * `doc.ferro` so the liquid gathers toward the magnets.
+ *
+ * At render time, the spike height combines with `doc.thick` height and defaults to a dark,
+ * glossy metallic material where `ferro > 0`, so `lightTile` shades the spikes with the canvas
+ * lighting. `cure_ferrofluid` bakes the current spikes into `doc.thick` and clears `doc.ferro`.
+ */
+import { TiledSurface, type RasterRect } from '../raster/surface.cjs';
+import { DEFAULT_FERRO, normalizeFerro as normalizeFerroSettings, type FerroSettings, type PaintBrush } from './brushes.cjs';
+import { type ThickChannels } from './thick.cjs';
+export { DEFAULT_FERRO, normalizeFerroSettings, type FerroSettings };
+/** A dipole magnet on the canvas (document pixel coordinates). */
+export interface PaintMagnet {
+    id: string;
+    x: number;
+    y: number;
+    /** Dipole strength and polarity (-1 .. 1). */
+    strength: number;
+    /** Characteristic dipole falloff radius in canvas pixels (8 .. 2000). */
+    radius: number;
+}
+export declare const DEFAULT_MAGNET_STRENGTH = 0.75;
+export declare const DEFAULT_MAGNET_RADIUS = 72;
+/** Dark carrier fluid sRGB colour (`#111827`) for advected ferrofluid outside existing pigment. */
+export declare const FERRO_CARRIER_RGB: readonly [number, number, number];
+/** Default glossy metallic material for ferrofluid (`gloss ≈ 0.88`, `metallic ≈ 0.65`, `rim ≈ 0.25`). */
+export declare const FERRO_DEFAULT_GLOSS = 224;
+export declare const FERRO_DEFAULT_METALLIC = 166;
+export declare const FERRO_DEFAULT_RIM = 64;
+/** Validates and normalizes a magnet; throws a descriptive Error when a field is out of range. */
+export declare function normalizeMagnet(raw: Partial<PaintMagnet> & {
+    id: string;
+    x: number;
+    y: number;
+}, base?: PaintMagnet): PaintMagnet;
+export declare function emptyFerro(): TiledSurface;
+/** The ferrofluid channel as grey paint for a stroke's twin: white, with alpha = ferro. */
+export declare function ferroToShadow(ferro: TiledSurface): TiledSurface;
+/** A twin's grey paint back as ferrofluid: grey × alpha. */
+export declare function shadowToFerro(shadow: TiledSurface): TiledSurface;
+/** The brush a stroke's ferrofluid twin paints with: same geometry, normal blend, RGB mixing. */
+export declare function ferroTwinBrush(brush: PaintBrush): PaintBrush;
+/** Ferrofluid scaled by `k` (0..1), e.g. under a fill that covers it. */
+export declare function scaleFerro(ferro: TiledSurface, k: number): TiledSurface;
+/** Ferrofluid of an upper layer merged down onto the one below (both in lower layer's space). */
+export declare function mergeFerro(lower: TiledSurface | undefined, upper: TiledSurface | undefined, upperColor: TiledSurface): TiledSurface | undefined;
+export interface FerroFieldSample {
+    bx: number;
+    by: number;
+    bz: number;
+    magnitude: number;
+}
+/**
+ * Analytical 3D magnetic dipole field `B = (bx, by, bz)` at canvas point `(x, y)` from a set of
+ * dipole magnets placed on the canvas plane (`z = -radius`).
+ */
+export declare function ferroFieldAt(x: number, y: number, magnets: readonly PaintMagnet[]): FerroFieldSample;
+/**
+ * Hexagonal Rosensweig instability spike height (0..255) at canvas coordinate `(x, y)` for a pixel
+ * with liquid ferrofluid byte `ferroByte` (0..255).
+ *
+ * Where `|B| > threshold` and `ferroByte > 0`, spikes rise with amplitude `∝ sqrt(1 - Bc / |B|) * ferro`
+ * at the capillary `wavelength` and tilt along the tangential field `(bx, by)`.
+ */
+export declare function ferroSpikeHeightAt(x: number, y: number, ferroByte: number, magnets: readonly PaintMagnet[], settings?: FerroSettings): number;
+/**
+ * Runs deterministic mass-gathering advection steps on a layer's `ferro` surface toward `magnets`.
+ * Each step transports liquid ferrofluid along the dipole attraction field via bilinear splatting.
+ */
+export declare function advectFerro(ferro: TiledSurface, magnets: readonly PaintMagnet[], offset?: {
+    x: number;
+    y: number;
+}, steps?: number): TiledSurface;
+export interface FerroStats {
+    bounds: RasterRect | null;
+    peak: number;
+    liquidPixels: number;
+    maxSpikeHeight: number;
+    spikePixels: number;
+    magnetCount: number;
+}
+/**
+ * Inspects a layer's liquid ferrofluid channel and active Rosensweig spike relief under `magnets`.
+ */
+export declare function ferroInfo(ferro: TiledSurface | undefined, magnets?: readonly PaintMagnet[], settings?: FerroSettings, offset?: {
+    x: number;
+    y: number;
+}): FerroStats;
+export interface FerroLayerInput {
+    surface: TiledSurface;
+    magnets: readonly PaintMagnet[];
+    settings: FerroSettings;
+    offset: {
+        x: number;
+        y: number;
+    };
+}
+export declare function ferroCacheKey(ferro: FerroLayerInput | null | undefined): string;
+/**
+ * Bakes a layer's liquid ferrofluid and active Rosensweig spikes into permanent `ThickChannels`
+ * (and ensures carrier colour covers advected ferrofluid pixels) for `cure_ferrofluid`.
+ */
+export declare function bakeFerroIntoThick(color: TiledSurface, ferro: TiledSurface, thick: ThickChannels | undefined, magnets: readonly PaintMagnet[], settings?: FerroSettings, offset?: {
+    x: number;
+    y: number;
+}): {
+    color: TiledSurface;
+    thick: ThickChannels;
+    maxSpikeHeight: number;
+    spikePixels: number;
+    curedPixels: number;
+};
+/** A layer's liquid ferrofluid as saved: its rect (layer space), grey PNG, and spike settings. */
+export interface SavedFerro {
+    rect: RasterRect;
+    ferro: string;
+    wavelength?: number;
+    threshold?: number;
+}
+export declare function ferroToJSON(ferro: TiledSurface, settings?: FerroSettings): SavedFerro | null;
+/** Saved form → ferrofluid surface and settings; throws a sentence when it cannot be read. */
+export declare function ferroFromJSON(raw: unknown): {
+    surface: TiledSurface;
+    settings: FerroSettings;
+};
+/** Saved magnets array → validated `PaintMagnet[]`. */
+export declare function magnetsFromJSON(raw: unknown): PaintMagnet[];

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

@@ -0,0 +1,134 @@
+/**
+ * Ferrofluid paint: a per-layer liquid ferrofluid channel (`doc.ferro`, one byte 0..255 per pixel
+ * in layer space, like `doc.light`) and document-space magnets (`doc.magnets`).
+ *
+ * Where the analytical dipole magnetic field `|B|` exceeds the critical threshold `Bc` and
+ * `ferro > 0`, the liquid rises into a hexagonal Rosensweig spike relief field whose spacing
+ * follows the capillary wavelength, whose amplitude scales as `sqrt(1 - Bc / |B|) * ferro`, and
+ * whose peaks tilt along `B`. Adding or moving a magnet runs deterministic advection steps on
+ * `doc.ferro` so the liquid gathers toward the magnets.
+ *
+ * At render time, the spike height combines with `doc.thick` height and defaults to a dark,
+ * glossy metallic material where `ferro > 0`, so `lightTile` shades the spikes with the canvas
+ * lighting. `cure_ferrofluid` bakes the current spikes into `doc.thick` and clears `doc.ferro`.
+ */
+import { TiledSurface, type RasterRect } from '../raster/surface.js';
+import { DEFAULT_FERRO, normalizeFerro as normalizeFerroSettings, type FerroSettings, type PaintBrush } from './brushes.js';
+import { type ThickChannels } from './thick.js';
+export { DEFAULT_FERRO, normalizeFerroSettings, type FerroSettings };
+/** A dipole magnet on the canvas (document pixel coordinates). */
+export interface PaintMagnet {
+    id: string;
+    x: number;
+    y: number;
+    /** Dipole strength and polarity (-1 .. 1). */
+    strength: number;
+    /** Characteristic dipole falloff radius in canvas pixels (8 .. 2000). */
+    radius: number;
+}
+export declare const DEFAULT_MAGNET_STRENGTH = 0.75;
+export declare const DEFAULT_MAGNET_RADIUS = 72;
+/** Dark carrier fluid sRGB colour (`#111827`) for advected ferrofluid outside existing pigment. */
+export declare const FERRO_CARRIER_RGB: readonly [number, number, number];
+/** Default glossy metallic material for ferrofluid (`gloss ≈ 0.88`, `metallic ≈ 0.65`, `rim ≈ 0.25`). */
+export declare const FERRO_DEFAULT_GLOSS = 224;
+export declare const FERRO_DEFAULT_METALLIC = 166;
+export declare const FERRO_DEFAULT_RIM = 64;
+/** Validates and normalizes a magnet; throws a descriptive Error when a field is out of range. */
+export declare function normalizeMagnet(raw: Partial<PaintMagnet> & {
+    id: string;
+    x: number;
+    y: number;
+}, base?: PaintMagnet): PaintMagnet;
+export declare function emptyFerro(): TiledSurface;
+/** The ferrofluid channel as grey paint for a stroke's twin: white, with alpha = ferro. */
+export declare function ferroToShadow(ferro: TiledSurface): TiledSurface;
+/** A twin's grey paint back as ferrofluid: grey × alpha. */
+export declare function shadowToFerro(shadow: TiledSurface): TiledSurface;
+/** The brush a stroke's ferrofluid twin paints with: same geometry, normal blend, RGB mixing. */
+export declare function ferroTwinBrush(brush: PaintBrush): PaintBrush;
+/** Ferrofluid scaled by `k` (0..1), e.g. under a fill that covers it. */
+export declare function scaleFerro(ferro: TiledSurface, k: number): TiledSurface;
+/** Ferrofluid of an upper layer merged down onto the one below (both in lower layer's space). */
+export declare function mergeFerro(lower: TiledSurface | undefined, upper: TiledSurface | undefined, upperColor: TiledSurface): TiledSurface | undefined;
+export interface FerroFieldSample {
+    bx: number;
+    by: number;
+    bz: number;
+    magnitude: number;
+}
+/**
+ * Analytical 3D magnetic dipole field `B = (bx, by, bz)` at canvas point `(x, y)` from a set of
+ * dipole magnets placed on the canvas plane (`z = -radius`).
+ */
+export declare function ferroFieldAt(x: number, y: number, magnets: readonly PaintMagnet[]): FerroFieldSample;
+/**
+ * Hexagonal Rosensweig instability spike height (0..255) at canvas coordinate `(x, y)` for a pixel
+ * with liquid ferrofluid byte `ferroByte` (0..255).
+ *
+ * Where `|B| > threshold` and `ferroByte > 0`, spikes rise with amplitude `∝ sqrt(1 - Bc / |B|) * ferro`
+ * at the capillary `wavelength` and tilt along the tangential field `(bx, by)`.
+ */
+export declare function ferroSpikeHeightAt(x: number, y: number, ferroByte: number, magnets: readonly PaintMagnet[], settings?: FerroSettings): number;
+/**
+ * Runs deterministic mass-gathering advection steps on a layer's `ferro` surface toward `magnets`.
+ * Each step transports liquid ferrofluid along the dipole attraction field via bilinear splatting.
+ */
+export declare function advectFerro(ferro: TiledSurface, magnets: readonly PaintMagnet[], offset?: {
+    x: number;
+    y: number;
+}, steps?: number): TiledSurface;
+export interface FerroStats {
+    bounds: RasterRect | null;
+    peak: number;
+    liquidPixels: number;
+    maxSpikeHeight: number;
+    spikePixels: number;
+    magnetCount: number;
+}
+/**
+ * Inspects a layer's liquid ferrofluid channel and active Rosensweig spike relief under `magnets`.
+ */
+export declare function ferroInfo(ferro: TiledSurface | undefined, magnets?: readonly PaintMagnet[], settings?: FerroSettings, offset?: {
+    x: number;
+    y: number;
+}): FerroStats;
+export interface FerroLayerInput {
+    surface: TiledSurface;
+    magnets: readonly PaintMagnet[];
+    settings: FerroSettings;
+    offset: {
+        x: number;
+        y: number;
+    };
+}
+export declare function ferroCacheKey(ferro: FerroLayerInput | null | undefined): string;
+/**
+ * Bakes a layer's liquid ferrofluid and active Rosensweig spikes into permanent `ThickChannels`
+ * (and ensures carrier colour covers advected ferrofluid pixels) for `cure_ferrofluid`.
+ */
+export declare function bakeFerroIntoThick(color: TiledSurface, ferro: TiledSurface, thick: ThickChannels | undefined, magnets: readonly PaintMagnet[], settings?: FerroSettings, offset?: {
+    x: number;
+    y: number;
+}): {
+    color: TiledSurface;
+    thick: ThickChannels;
+    maxSpikeHeight: number;
+    spikePixels: number;
+    curedPixels: number;
+};
+/** A layer's liquid ferrofluid as saved: its rect (layer space), grey PNG, and spike settings. */
+export interface SavedFerro {
+    rect: RasterRect;
+    ferro: string;
+    wavelength?: number;
+    threshold?: number;
+}
+export declare function ferroToJSON(ferro: TiledSurface, settings?: FerroSettings): SavedFerro | null;
+/** Saved form → ferrofluid surface and settings; throws a sentence when it cannot be read. */
+export declare function ferroFromJSON(raw: unknown): {
+    surface: TiledSurface;
+    settings: FerroSettings;
+};
+/** Saved magnets array → validated `PaintMagnet[]`. */
+export declare function magnetsFromJSON(raw: unknown): PaintMagnet[];