@pixerate/editor 0.276.0 → 0.277.0

package/dist/image-editor/index.js

@@ -8,7 +8,7 @@ import {
   parseOpenTypeFont,
   removeAnchorsKeepingShape,
   traceField
-} from "../chunk-OS6OG7DN.js";
+} from "../chunk-N4MCWQZ7.js";
 import {
   ADJUSTMENT_KEYS,
   ADJUSTMENT_KINDS,
@@ -409,7 +409,7 @@ import {
   writePsd,
   xyToTempTint,
   xyToUv
-} from "../chunk-XMSH66VU.js";
+} from "../chunk-FNIWHSLI.js";
 import {
   flattenPath,
   rasterizeCoverage
@@ -683,14 +683,14 @@ import {
   warpMeshParamAt,
   warpMeshRows,
   warpPresetMesh
-} from "../chunk-4EM5NGCL.js";
+} from "../chunk-HHX7ST6Z.js";
 import {
   IMAGE_PROFILE,
   checkBrush,
   closest,
   createBrushLibrary,
   resolveBrush
-} from "../chunk-XVPQNX7O.js";
+} from "../chunk-PPDUCZZV.js";
 import "../chunk-JL6YH5WD.js";
 import "../chunk-RWDSSK2I.js";
 import {

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

@@ -149,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';
@@ -283,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;
@@ -321,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' | 'livePatterns'>> & {
+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;
@@ -336,6 +349,7 @@ export type PaintBrushInput = Partial<Omit<PaintBrush, 'tip' | 'dynamics' | 'mix
     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

@@ -149,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';
@@ -283,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;
@@ -321,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' | 'livePatterns'>> & {
+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;
@@ -336,6 +349,7 @@ export type PaintBrushInput = Partial<Omit<PaintBrush, 'tip' | 'dynamics' | 'mix
     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

@@ -63,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);
 }
@@ -548,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;
@@ -1286,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
@@ -1477,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/controller.d.ts

@@ -63,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);
 }
@@ -548,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;
@@ -1286,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
@@ -1477,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[];