@pixerate/editor 0.276.0 → 0.278.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

@@ -23,7 +23,7 @@ import { type PaintBrushInput, type PaintBrush } from './brushes.cjs';
 import { type BrushLibrary, type BrushLibraryFile } from '../brushes/library.cjs';
 import { type BrushPatch, type UnsettableBrushFacet } from '../brushes/patch.cjs';
 import type { Brush } from '../brushes/types.cjs';
-import type { ColorScheme } from '../color/dual.cjs';
+import { type ColorScheme, type ColorValue } from '../color/dual.cjs';
 import { type PaintCanvas, type PaintDocumentState, type PaintLayer } from './document.cjs';
 import { type ImageEncoder, type ImageFormat } from './encode.cjs';
 import type { PenPoint } from './engine.cjs';
@@ -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);
 }
@@ -205,8 +206,8 @@ export interface LiveStrokeUpdate {
     brushId?: string;
     /** Brush settings to change (as `setBrush` takes), on top of `brushId` or the stroke's brush. */
     brush?: Omit<PaintBrushInput, 'id'>;
-    /** A new colour #rrggbb (replaces gradient or effect paint). */
-    color?: string;
+    /** A new colour #rrggbb, or a light / dark pair (replaces gradient or effect paint). */
+    color?: ColorValue;
     /** Paint: a colour, gradient paint or effect paint; `null` back to the plain colour. */
     paint?: unknown;
     /** Another jitter seed (particles, scatter and texture fall differently). */
@@ -274,8 +275,12 @@ export interface PaintPreviewPlacement {
 export interface PaintStrokeInit {
     /** Default the active layer. */
     layerId?: string;
-    /** Default the editor colour. */
-    color?: string;
+    /**
+     * Default the editor colour. A light / dark pair (`DualColor`) is recorded with the stroke
+     * (`RecordedStroke.dualColor`): on a stroke layer the document draws its light side and the view
+     * the viewer's (`setColorScheme`); on a pixel layer it paints the scheme's side.
+     */
+    color?: ColorValue;
     /**
      * What this stroke paints with, instead of the editor's paint: a colour, gradient paint
      * (`@pixerate/editor/paint` `PaintSource`), or effect paint (render it first with
@@ -548,6 +553,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;
@@ -1058,9 +1066,29 @@ export declare class PaintEditorController {
     private brushColour;
     /**
      * The host's colour scheme: a paint colour that came from a brush's light / dark default
-     * resolves to the new side. Editor state, not an undo step.
+     * resolves to the new side, and stroke layers show their dual-colour strokes in it. Only the
+     * view changes: the document, history and change listeners don't hear of it.
      */
     setColorScheme(scheme: ColorScheme): void;
+    /**
+     * Stroke layers in the colour scheme: the document keeps every stroke layer drawn with each
+     * stroke's `color` (a dual-colour stroke's light side), so saved and shared documents never
+     * depend on who is looking. The view (display, image exports, the base a pointer stroke paints
+     * on) draws dual-colour strokes in the scheme's side instead. One cached surface per layer,
+     * brought up to date from the strokes that changed since it was drawn.
+     */
+    private schemeViews;
+    private schemeCopies;
+    /** Set while a stroke is painted for the document rather than the view (`runStroke` on a stroke layer): dual colours take this side. */
+    private paintScheme;
+    /** A stroke as the scheme shows it: itself, or (a dual-colour stroke) a copy in the scheme's side. */
+    private schemeStroke;
+    /** A stroke layer's surface in the scheme, or `null` when the document's pixels already show it. */
+    private schemeSurface;
+    /** `layers` with each stroke layer that holds dual-colour strokes shown in the scheme. */
+    private schemeLayers;
+    /** The paint colour's light / dark pair for a stroke with `brushId`, when the colour came from one (a brush's own or default colour, or `setColor`). */
+    private dualPaint;
     /** Locks the paint colour: choosing a brush with a default colour keeps it. Editor state, not an undo step. */
     setColorLocked(locked: boolean): void;
     /**
@@ -1071,8 +1099,12 @@ export declare class PaintEditorController {
     private takeBrushColour;
     /** A brush that always paints its own colour (`colour.own`): that colour, resolved for the scheme now; else `null`. */
     private ownColour;
-    /** Sets the paint colour (and goes back to one colour from gradient paint). */
-    setColor(color: string): string;
+    /**
+     * Sets the paint colour (and goes back to one colour from gradient paint). A light / dark pair
+     * paints the colour scheme's side, follows `setColorScheme`, and is recorded with each stroke
+     * painted in it. Returns the colour as #rrggbb.
+     */
+    setColor(color: ColorValue): string;
     /**
      * Sets what strokes paint with: one colour (`{ type: 'color', color }` or `#rrggbb`), or gradient
      * paint (`{ type: 'gradient', stops, space?, map?, softness? }`, see `@pixerate/editor/paint`),
@@ -1286,6 +1318,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 +1554,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
@@ -1726,6 +1803,10 @@ export declare class PaintEditorController {
     liveStrokeArea(id: string): RasterRect | null;
     /** Commits a layer's new stroke list with its redrawn pixels, recorded for replays (one undo step). */
     private commitLiveStrokes;
+    /**
+     * The document with a layer's strokes set and its pixels redrawn. With `record` false (the same
+     * strokes drawn for the colour scheme) the pixel lock doesn't apply and no event is recorded for replays.
+     */
     private withLiveStrokes;
     /** Where a stroke painted (document pixels): as learnt when it was painted or drawn, else an estimate from its points and brush. */
     private strokeArea;

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

@@ -23,7 +23,7 @@ import { type PaintBrushInput, type PaintBrush } from './brushes.js';
 import { type BrushLibrary, type BrushLibraryFile } from '../brushes/library.js';
 import { type BrushPatch, type UnsettableBrushFacet } from '../brushes/patch.js';
 import type { Brush } from '../brushes/types.js';
-import type { ColorScheme } from '../color/dual.js';
+import { type ColorScheme, type ColorValue } from '../color/dual.js';
 import { type PaintCanvas, type PaintDocumentState, type PaintLayer } from './document.js';
 import { type ImageEncoder, type ImageFormat } from './encode.js';
 import type { PenPoint } from './engine.js';
@@ -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);
 }
@@ -205,8 +206,8 @@ export interface LiveStrokeUpdate {
     brushId?: string;
     /** Brush settings to change (as `setBrush` takes), on top of `brushId` or the stroke's brush. */
     brush?: Omit<PaintBrushInput, 'id'>;
-    /** A new colour #rrggbb (replaces gradient or effect paint). */
-    color?: string;
+    /** A new colour #rrggbb, or a light / dark pair (replaces gradient or effect paint). */
+    color?: ColorValue;
     /** Paint: a colour, gradient paint or effect paint; `null` back to the plain colour. */
     paint?: unknown;
     /** Another jitter seed (particles, scatter and texture fall differently). */
@@ -274,8 +275,12 @@ export interface PaintPreviewPlacement {
 export interface PaintStrokeInit {
     /** Default the active layer. */
     layerId?: string;
-    /** Default the editor colour. */
-    color?: string;
+    /**
+     * Default the editor colour. A light / dark pair (`DualColor`) is recorded with the stroke
+     * (`RecordedStroke.dualColor`): on a stroke layer the document draws its light side and the view
+     * the viewer's (`setColorScheme`); on a pixel layer it paints the scheme's side.
+     */
+    color?: ColorValue;
     /**
      * What this stroke paints with, instead of the editor's paint: a colour, gradient paint
      * (`@pixerate/editor/paint` `PaintSource`), or effect paint (render it first with
@@ -548,6 +553,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;
@@ -1058,9 +1066,29 @@ export declare class PaintEditorController {
     private brushColour;
     /**
      * The host's colour scheme: a paint colour that came from a brush's light / dark default
-     * resolves to the new side. Editor state, not an undo step.
+     * resolves to the new side, and stroke layers show their dual-colour strokes in it. Only the
+     * view changes: the document, history and change listeners don't hear of it.
      */
     setColorScheme(scheme: ColorScheme): void;
+    /**
+     * Stroke layers in the colour scheme: the document keeps every stroke layer drawn with each
+     * stroke's `color` (a dual-colour stroke's light side), so saved and shared documents never
+     * depend on who is looking. The view (display, image exports, the base a pointer stroke paints
+     * on) draws dual-colour strokes in the scheme's side instead. One cached surface per layer,
+     * brought up to date from the strokes that changed since it was drawn.
+     */
+    private schemeViews;
+    private schemeCopies;
+    /** Set while a stroke is painted for the document rather than the view (`runStroke` on a stroke layer): dual colours take this side. */
+    private paintScheme;
+    /** A stroke as the scheme shows it: itself, or (a dual-colour stroke) a copy in the scheme's side. */
+    private schemeStroke;
+    /** A stroke layer's surface in the scheme, or `null` when the document's pixels already show it. */
+    private schemeSurface;
+    /** `layers` with each stroke layer that holds dual-colour strokes shown in the scheme. */
+    private schemeLayers;
+    /** The paint colour's light / dark pair for a stroke with `brushId`, when the colour came from one (a brush's own or default colour, or `setColor`). */
+    private dualPaint;
     /** Locks the paint colour: choosing a brush with a default colour keeps it. Editor state, not an undo step. */
     setColorLocked(locked: boolean): void;
     /**
@@ -1071,8 +1099,12 @@ export declare class PaintEditorController {
     private takeBrushColour;
     /** A brush that always paints its own colour (`colour.own`): that colour, resolved for the scheme now; else `null`. */
     private ownColour;
-    /** Sets the paint colour (and goes back to one colour from gradient paint). */
-    setColor(color: string): string;
+    /**
+     * Sets the paint colour (and goes back to one colour from gradient paint). A light / dark pair
+     * paints the colour scheme's side, follows `setColorScheme`, and is recorded with each stroke
+     * painted in it. Returns the colour as #rrggbb.
+     */
+    setColor(color: ColorValue): string;
     /**
      * Sets what strokes paint with: one colour (`{ type: 'color', color }` or `#rrggbb`), or gradient
      * paint (`{ type: 'gradient', stops, space?, map?, softness? }`, see `@pixerate/editor/paint`),
@@ -1286,6 +1318,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 +1554,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
@@ -1726,6 +1803,10 @@ export declare class PaintEditorController {
     liveStrokeArea(id: string): RasterRect | null;
     /** Commits a layer's new stroke list with its redrawn pixels, recorded for replays (one undo step). */
     private commitLiveStrokes;
+    /**
+     * The document with a layer's strokes set and its pixels redrawn. With `record` false (the same
+     * strokes drawn for the colour scheme) the pixel lock doesn't apply and no event is recorded for replays.
+     */
     private withLiveStrokes;
     /** Where a stroke painted (document pixels): as learnt when it was painted or drawn, else an estimate from its points and brush. */
     private strokeArea;

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[];