@overtone-art/canvas-editor-core 0.3.2 → 0.5.0

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { Canvas, FabricObject, ImageFormat } from 'fabric';
-import { b as EditorEvents, m as LayerType, k as LayerMeta, L as LayerData, W as SerializedLayer, J as PatternSourceResolver, P as PatternConfig, H as PatternLocks, a0 as TextCurveConfig, r as MaskPresetId, X as ShapeMaskPresetId, a1 as TextureMaskPresetId, a3 as Unit, G as MockupPrintArea, x as MockupConfig, e as FontDefinition, n as LicenseConfig, p as LicenseStatus, S as ProjectState, M as MaskBrushOptions, q as MaskPoint, t as MaskRefinementProvider, s as MaskRefinementPrompt, v as MaskRefinementResult, E as EditorConfig, Y as ShapePlugin, _ as TemplateDefinition, I as ImageAdjustments, c as EditorState, U as SemanticExportOptions, Z as SvgExportOptions, Q as PrintifyPositioning, N as NormalizedLayerPosition, O as PositioningAdapter, h as ImageProviderResult, i as ImageSearchOptions, j as ImageSearchResult, F as FileAdapter, g as ImageProvider, V as SerializedBackgroundImageOptions, B as BackgroundImageOptions, T as ResizeOptions, a as DpiIssue, l as LayerShadowConfig, C as CanvasSizePreset, y as MockupDisplacement } from './types-Dh1unrzT.mjs';
-export { D as DEFAULT_PATTERN_CONFIG, d as ExportFormat, f as ImageAttribution, o as LicensePayload, u as MaskRefinementRequest, w as MockupBlendMode, z as MockupDisplacementChannel, A as MockupOverlay, K as PatternState, R as ProjectPage, $ as TemplateParameter, a2 as TileMode } from './types-Dh1unrzT.mjs';
+import { Canvas, FabricObject, Point, ImageFormat, Group } from 'fabric';
+import { b as EditorEvents, o as LayerType, m as LayerMeta, L as LayerData, X as SerializedLayer, P as PatternConfig, K as PatternLocks, a1 as TextCurveConfig, t as MaskPresetId, Y as ShapeMaskPresetId, a2 as TextureMaskPresetId, a4 as Unit, J as MockupPrintArea, z as MockupConfig, e as FontDefinition, p as LicenseConfig, r as LicenseStatus, T as ProjectState, M as MaskBrushOptions, s as MaskPoint, v as MaskRefinementProvider, u as MaskRefinementPrompt, x as MaskRefinementResult, k as LayerMaskEntry, l as LayerMaskMode, E as EditorConfig, Z as ShapePlugin, $ as TemplateDefinition, I as ImageAdjustments, c as EditorState, V as SemanticExportOptions, _ as SvgExportOptions, R as PrintifyPositioning, N as NormalizedLayerPosition, Q as PositioningAdapter, h as ImageProviderResult, i as ImageSearchOptions, j as ImageSearchResult, F as FileAdapter, g as ImageProvider, W as SerializedBackgroundImageOptions, B as BackgroundImageOptions, U as ResizeOptions, a as DpiIssue, n as LayerShadowConfig, C as CanvasSizePreset, A as MockupDisplacement } from './types-JP8MZsIs.mjs';
+export { D as DEFAULT_PATTERN_CONFIG, d as ExportFormat, f as ImageAttribution, q as LicensePayload, w as MaskRefinementRequest, y as MockupBlendMode, G as MockupDisplacementChannel, H as MockupOverlay, O as PatternState, S as ProjectPage, a0 as TemplateParameter, a3 as TileMode } from './types-JP8MZsIs.mjs';
 
 type EventHandler<T> = (data: T) => void;
 declare class EventEmitter<TEvents extends {} = Record<string, unknown>> {
@@ -22,6 +22,12 @@ declare class Layer {
     /** Non-fabric data (e.g. pattern config) that must persist with the layer. */
     meta: LayerMeta;
     fabricObject: FabricObject;
+    /**
+     * Stand-in object drawn in place of `fabricObject` (the tiled pattern). It is
+     * part of the canvas but never part of the document: it is not serialized, and
+     * the layer's real object stays the one every editor API talks to.
+     */
+    renderProxy: FabricObject | null;
     constructor(type: LayerType, fabricObject: FabricObject, name?: string, id?: string);
     private hasMeta;
     toData(): LayerData;
@@ -38,6 +44,19 @@ declare class LayerManager {
     remove(id: string): boolean;
     /** Replace a layer's render object while preserving its immutable ID and panel state. */
     replaceObject(id: string, fabricObject: FabricObject): boolean;
+    /**
+     * Attach (or clear) the object drawn in place of a layer's own object. The
+     * proxy tracks the layer's stacking position, visibility and opacity, and is
+     * removed with the layer — it must never outlive or drift from its source.
+     */
+    setRenderProxy(id: string, proxy: FabricObject | null): void;
+    /**
+     * Re-stack every canvas object to match layer order, keeping each proxy
+     * directly above the source it stands in for. Canvas indices can't be derived
+     * from layer indices once proxies are in the array, so the order is rebuilt
+     * front-to-back instead of computed.
+     */
+    private syncZOrder;
     reorder(id: string, newIndex: number): boolean;
     select(id: string | null): void;
     get(id: string): Layer | undefined;
@@ -176,79 +195,182 @@ declare class CropController {
 }
 
 /**
- * Renders a single image layer as a repeating pattern that fills the canvas.
+ * Repeats a layer's own object across the print area.
  *
- * The tiled result is rasterised onto an offscreen canvas and swapped in as the
- * layer's image source, so it survives export, serialization and undo/redo with
- * no extra machinery. The original source + transform are kept in `layer.meta`
- * so the pattern can be turned back off.
+ * The layer keeps its real fabric object as the tile *source*: it stays in the
+ * document, stays selectable and stays editable, and is simply parked at
+ * `opacity: 0` while a {@link TiledPatternObject} render proxy draws the tiling
+ * over the print area. Nothing is baked into the layer, so a source edit (text,
+ * font, colour, drag, scale) shows up on the very next render, and the saved
+ * state stores a `Textbox` rather than a screenshot of one.
  */
 declare class PatternManager {
     private canvas;
     private layers;
     private history;
     private events;
-    private sourceResolver?;
-    private chains;
-    constructor(canvas: Canvas, layers: LayerManager, history: HistoryManager, events: EventEmitter<EditorEvents>, sourceResolver?: PatternSourceResolver | undefined);
+    private proxies;
+    private readonly onObjectModified;
+    private readonly onSourceModified;
+    private readonly onLayerRemoved;
+    constructor(canvas: Canvas, layers: LayerManager, history: HistoryManager, events: EventEmitter<EditorEvents>);
     isPattern(layerId: string): boolean;
     getConfig(layerId: string): PatternConfig | null;
-    /** Turn a plain image layer into a pattern, or update an existing one. */
+    /** Turn a layer into a repeating pattern, or update an existing one. */
     apply(layerId: string, config: PatternConfig): Promise<void>;
+    /** Drop the tiling and show the source again. */
+    disable(layerId: string): Promise<void>;
     /**
-     * Stretch every restored pattern layer back over the full print area and
-     * re-freeze it, without re-rasterising: the baked bitmap keeps whatever size
-     * it was saved at, so it is scaled (not re-tiled) to the current canvas. Used
-     * after a state restore, where the canvas may be a different display size
-     * than when the pattern was baked — and to repair states saved while a
-     * pattern could still be dragged out of the print area.
+     * Rebuild every proxy after a state restore, migrating any layer that was
+     * saved by the old bake-into-the-layer engine.
      */
-    repinAll(): void;
-    /** Restore the original image and drop the pattern. */
-    disable(layerId: string): Promise<void>;
-    /** Run `task` after any in-flight work for this layer, regardless of outcome. */
-    private enqueue;
-    private renderLayer;
-}
-/** Interaction flags to restore when a pattern is turned off. */
-declare function captureLocks(obj: FabricObject): PatternLocks;
-/** Pin a pattern object: no move, scale or rotate while the pattern is on. */
-declare function applyPatternLocks(obj: FabricObject): void;
+    rehydrateAll(): Promise<void>;
+    /** Re-fit every proxy to the print area (canvas resize). */
+    syncArea(): void;
+    /** Drop a layer's cached source snapshot (its content changed). */
+    invalidate(layerId: string): void;
+    /** Give a freshly cloned layer its own proxy (duplicating a pattern layer). */
+    attachTo(layer: Layer): void;
+    dispose(): void;
+    /** Release every proxy and the offscreen snapshot it holds. */
+    private clearProxies;
+    private attach;
+    /**
+     * Fold a finished drag / scale / rotate on the proxy back into the pattern:
+     * position becomes the grid origin (carried by the source), scale becomes the
+     * tile scale, rotation becomes the pattern angle. Read the live transform
+     * first — writing the config re-fits the box and destroys it.
+     */
+    private commitGesture;
+    private area;
+    private detach;
+    private invalidateFor;
+}
 /**
- * Restore pre-pattern interaction flags. States saved before locking existed
- * carry no snapshot — fall back to a fully interactive object rather than
- * leaving it frozen forever.
+ * Restore pre-pattern interaction flags. Only legacy states carry a snapshot —
+ * the live-source engine never freezes anything — so a missing snapshot means
+ * "fully interactive", not "leave it frozen".
  */
 declare function restoreLocks(obj: FabricObject, locks: PatternLocks | undefined): void;
-declare function loadPatternImage(src: string, resolver?: PatternSourceResolver): Promise<HTMLImageElement>;
-/** Clear the decoded-image cache (e.g. on teardown). Exported for completeness. */
-declare function clearPatternImageCache(): void;
+
+interface PatternArea {
+    width: number;
+    height: number;
+}
 /**
- * Draw the source image repeatedly across a `targetW × targetH` offscreen
- * canvas and return the result as a PNG data URL.
+ * Renders a layer's source object repeated across the print area.
+ *
+ * This is a *render proxy*, not a layer: it is attached to the layer that owns
+ * the source (see `LayerManager.setRenderProxy`) and never serialized. The
+ * document keeps the real object — a `Textbox` stays a `Textbox` — so tiling is
+ * non-destructive and every source edit shows up on the next render.
  *
- * Exported for unit testing of the tile geometry.
+ * **Its box is one tile, its drawing is the whole area.** The object's own
+ * width/height/angle/position track the tile drawn at the grid origin (the
+ * "anchor" tile), so the selection frame the user grabs sits exactly on a tile
+ * they can see, while `_render` paints the full print area outside those bounds.
+ * That also makes the transform handles meaningful: dragging moves the grid,
+ * scaling is the tile scale, rotating is the pattern angle. The live transform
+ * is the truth during a gesture; `PatternManager` folds it back into the config
+ * when the gesture ends.
  */
-declare function buildPatternDataURL(src: string, config: PatternConfig, targetW: number, targetH: number, baseW: number, baseH: number, sourceResolver?: PatternSourceResolver): Promise<string>;
-/** Placement of one tile, relative to the (already rotated) pattern centre. */
+declare class TiledPatternObject extends FabricObject {
+    static type: string;
+    /** The layer's real object. Never rendered directly (it is kept at opacity 0). */
+    source: FabricObject;
+    config: PatternConfig;
+    /** The print area this pattern fills, in canvas units. */
+    area: PatternArea;
+    private snapshotEl;
+    private snapshotScale;
+    constructor(source: FabricObject, config: PatternConfig, area: PatternArea);
+    /** Swap in a new config and re-fit the box to the tile it now describes. */
+    setConfig(config: PatternConfig): void;
+    /** Re-fit to a new print area (canvas resize). */
+    setArea(area: PatternArea): void;
+    /** Drop the cached source snapshot (the source was edited). */
+    invalidate(): void;
+    /** Free the offscreen snapshot. */
+    dispose(): void;
+    /**
+     * Put the box back on the anchor tile: the tile's size, the pattern angle, and
+     * the grid origin displaced by the configured phase shift. Resets any live
+     * gesture scale, so it must run only once that gesture has been folded in.
+     */
+    syncBox(): void;
+    /** Grid rotation in play right now — the live handle during a rotate gesture. */
+    liveAngle(): number;
+    /** Tile scale in play right now, as a config percentage. */
+    liveScale(): number;
+    /**
+     * Where the source's centre would have to sit for the box to stay put — i.e.
+     * the grid origin implied by a drag. `PatternManager` moves the source there.
+     */
+    liveOrigin(): Point;
+    _render(ctx: CanvasRenderingContext2D): void;
+    /** Raster fallback for SVG export — one `<image>` covering the print area. */
+    _toSVG(): string[];
+    /**
+     * The proxy holds a live reference to its source, which would make a
+     * serialized canvas circular. Nothing persists this object (only layers are
+     * serialized) — this keeps an accidental `canvas.toObject()` from throwing.
+     */
+    toObject(): Record<string, unknown>;
+    /**
+     * Fabric's generic clone round-trips through `toObject()` + the class
+     * registry, which cannot carry a live source reference. Export paths clone
+     * every canvas object, so without this a print export would silently lose the
+     * tiling. The copy shares the source (it only ever reads from it).
+     */
+    clone(): Promise<this>;
+    /** The source's on-canvas width, before the tile scale. */
+    private baseW;
+    /** Tile size from the config alone, ignoring any in-flight gesture. */
+    private baseTile;
+    /** Tile size as drawn right now, including a live scale gesture. */
+    private liveTile;
+    /** Smallest tile the draw loop may use, so a tiny tile can't flood the area. */
+    private tileFloor;
+    /** Phase shift (`offsetX`/`offsetY`) as a canvas-space vector. */
+    private shiftVector;
+    private anchorFromOrigin;
+    /**
+     * Snapshot the source at (at least) `scale`, reusing the cached one while it
+     * is still sharp enough and the source has not changed.
+     */
+    private ensureSnapshot;
+    /** Bound the snapshot by both a linear scale and a total pixel budget. */
+    private clampScale;
+}
+
+/** Placement of one tile, relative to the (already rotated) pattern origin. */
 interface TilePlacement {
-    /** Tile-centre offset from the pattern centre, in px. */
+    /** Tile-centre offset from the pattern origin, in px. */
     x: number;
     y: number;
     /** Per-tile rotation, in radians. */
     rotation: number;
 }
+/** Where the tile grid is anchored inside the target, in target px. */
+interface PatternOrigin {
+    x: number;
+    y: number;
+}
 /**
  * Pure tile geometry: where each tile centre lands and how much it is rotated,
- * for a config + target/base size. Covers the rotated bounding diagonal so
- * corners stay filled at any pattern angle. Extracted for unit testing.
+ * for a config + target/base size. Covers every corner of the target from the
+ * grid origin, so no rotation or origin can uncover an edge. Extracted for unit
+ * testing.
+ *
+ * `origin` defaults to the centre of the target.
  */
-declare function computeTilePositions(config: PatternConfig, targetW: number, targetH: number, baseW: number, baseH: number): TilePlacement[];
+declare function computeTilePositions(config: PatternConfig, targetW: number, targetH: number, baseW: number, baseH: number, origin?: PatternOrigin): TilePlacement[];
 /**
- * Draw the tiled pattern onto a 2D context. The geometry lives in
- * {@link computeTilePositions}; this just plays it out as canvas calls.
+ * Draw the tiled pattern onto a 2D context, in target coordinates (0,0 = the
+ * target's top-left corner). The geometry lives in {@link computeTilePositions};
+ * this just plays it out as canvas calls.
  */
-declare function drawTiles(ctx: CanvasRenderingProtocol, img: CanvasImageSource, config: PatternConfig, targetW: number, targetH: number, baseW: number, baseH: number): void;
+declare function drawTiles(ctx: CanvasRenderingProtocol, img: CanvasImageSource, config: PatternConfig, targetW: number, targetH: number, baseW: number, baseH: number, origin?: PatternOrigin): void;
 /** Minimal 2D-context surface used by {@link drawTiles}; lets tests inject a spy. */
 interface CanvasRenderingProtocol {
     save(): void;
@@ -543,6 +665,237 @@ declare class MaskController {
     private assertActive;
 }
 
+interface MaskEditTarget {
+    target: string;
+    maskId: string;
+}
+
+interface MaskBox {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+
+/** Target id for the mask stack that clips the whole design rather than a layer. */
+declare const CANVAS_MASK_TARGET = "canvas";
+/**
+ * Storage half of the mask stacks: where a stack lives, how it is read back out
+ * of the composed clip, and how a new one is installed. `LayerMaskManager` adds
+ * the editing operations on top.
+ *
+ * Two things are persisted, and each has a job:
+ *
+ *  - the composed `clipPath` on the host's fabric object, which is what actually
+ *    renders — in the browser, in an export, and in a server-side replay that
+ *    knows nothing about this class;
+ *  - `layer.meta.maskStack`, the per-entry list (name, mode, link, visibility)
+ *    that the UI edits.
+ *
+ * Geometry is NOT duplicated into the meta: the group's children are the single
+ * source of truth for it, unwrapped and recomposed on every mutation, so the two
+ * can never drift into disagreeing about where a mask sits. The order of
+ * `entries` matches the order of the group's children, minus the implicit base
+ * rect a stack that opens with subtract/intersect needs.
+ */
+declare abstract class MaskStackStore {
+    protected canvas: Canvas;
+    protected layers: LayerManager;
+    protected history: HistoryManager;
+    protected events: EventEmitter<EditorEvents>;
+    protected selected: {
+        target: string;
+        maskId: string;
+    } | null;
+    private pinning;
+    constructor(canvas: Canvas, layers: LayerManager, history: HistoryManager, events: EventEmitter<EditorEvents>);
+    list(target: string): LayerMaskEntry[];
+    get(target: string, maskId: string): LayerMaskEntry | undefined;
+    /** Every target that currently carries at least one mask. */
+    targets(): string[];
+    /** The box a mask is fitted to, in the space the stack is composed in. */
+    hostBox(target: string, absolute?: boolean): MaskBox;
+    /** The host layer of a target, optionally creating the design overlay. */
+    protected hostLayer(target: string, create?: boolean): Layer | undefined;
+    protected host(target: string, create?: boolean): FabricObject | null;
+    /** Re-pin the design overlay, guarding the reorder that re-triggers this. */
+    protected pin(): void;
+    /**
+     * Take the current geometry back out of the composed clip, entry-aligned.
+     *
+     * The entry list is the authority on how to read the clip: with no entries the
+     * clip predates the stack (a mask preset, or a single `clipPath` an older host
+     * installed) and is one mask whole — including when it happens to be a group,
+     * which is why this cannot just unwrap anything group-shaped.
+     */
+    protected unwrap(target: string, host: FabricObject): FabricObject[];
+    /**
+     * Entries for a stack, adopting a pre-stack clip as the first one. Without
+     * this, the first `add()` on an already-masked layer would compose a clip it
+     * has no entry for and silently throw that mask away.
+     */
+    protected entriesFor(target: string, sources: FabricObject[]): LayerMaskEntry[];
+    /**
+     * Install a stack: convert geometry into the space the stack needs, compose the
+     * clip, store the entries, and commit one history checkpoint for the lot.
+     */
+    protected commit(target: string, host: FabricObject, entries: LayerMaskEntry[], sources: FabricObject[], save?: boolean, 
+    /** Compose in canvas space regardless of the entries — see `beginEdit`. */
+    forceAbsolute?: boolean): void;
+}
+
+interface AddMaskOptions {
+    name?: string;
+    mode?: LayerMaskMode;
+    linked?: boolean;
+    /** Host data describing where the geometry came from (preset id, generator…). */
+    meta?: Record<string, unknown>;
+    /** Scale the geometry to the host's box (a number zooms it); default 1. */
+    fit?: number | false;
+    /**
+     * Fit to this box instead of the host's own, in the stack's coordinate space.
+     * The whole-design overlay spans the canvas, but a mask on it usually wants to
+     * frame the artwork, which occupies part of it.
+     */
+    box?: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Stacked, boolean-composed masks — one ordered list per host, where a host is
+ * either a layer or the design as a whole (`CANVAS_MASK_TARGET`). Storage and
+ * clip composition live in `MaskStackStore`; this class is what a UI drives.
+ */
+declare class LayerMaskManager extends MaskStackStore {
+    private readonly edits;
+    private readonly onLayersChanged;
+    private readonly onLayerSelected;
+    private readonly onObjectModified;
+    constructor(canvas: Canvas, layers: LayerManager, history: HistoryManager, events: EventEmitter<EditorEvents>);
+    dispose(): void;
+    /** The mask currently being dragged on the canvas, if any. */
+    editing(): MaskEditTarget | null;
+    /**
+     * Put drag handles on one mask. The stack is composed in canvas space for the
+     * duration — a linked mask would otherwise sit in the host's space, where the
+     * handle's own canvas coordinates mean something else entirely. `endEdit`
+     * returns it to whichever space its entries call for.
+     */
+    beginEdit(target: string, maskId: string): Promise<boolean>;
+    /** Take the handles down and settle the stack back into its own space. */
+    endEdit(save?: boolean): void;
+    getSelected(): {
+        target: string;
+        maskId: string;
+    } | null;
+    select(target: string | null, maskId: string | null): void;
+    add(target: string, object: FabricObject, options?: AddMaskOptions): LayerMaskEntry | null;
+    /** Swap one mask's geometry, keeping its identity, mode and position in the stack. */
+    replaceGeometry(target: string, maskId: string, object: FabricObject, options?: AddMaskOptions): boolean;
+    /**
+     * Re-fit one mask to its host's box (or `box`) at `fit` scale, keeping the
+     * geometry it already has. This is what a zoom control drives: re-picking the
+     * mask would cost another render of a generated alpha map just to resize it.
+     */
+    refit(target: string, maskId: string, options?: {
+        fit?: number;
+        box?: MaskBox;
+        save?: boolean;
+    }): boolean;
+    remove(target: string, maskId: string): boolean;
+    clear(target: string): boolean;
+    reorder(target: string, maskId: string, index: number): boolean;
+    /** Replace a mask's host metadata (which preset or generator produced it). */
+    setMeta(target: string, maskId: string, meta: Record<string, unknown>): boolean;
+    setMode(target: string, maskId: string, mode: LayerMaskMode): boolean;
+    setVisible(target: string, maskId: string, visible: boolean): boolean;
+    setOpacity(target: string, maskId: string, opacity: number): boolean;
+    setName(target: string, maskId: string, name: string): boolean;
+    /**
+     * Link or unlink one mask. Unlinking pins it where it currently appears;
+     * re-linking records its position relative to the host so later host moves
+     * carry it along.
+     */
+    setLinked(target: string, maskId: string, linked: boolean): boolean;
+    /**
+     * Consume a layer, turning its artwork into a mask. Without an explicit target
+     * it masks the layer directly beneath it, and the bottom layer masks the whole
+     * design — there is nothing under it to clip.
+     */
+    convertLayer(layerId: string, target?: string): {
+        target: string;
+        entry: LayerMaskEntry;
+    } | null;
+    /** Recompose one stack's clip from the geometry it already holds. */
+    rebuild(target: string, save?: boolean): void;
+    /** Re-derive linked masks after the host moved (canvas-space stacks only). */
+    private reflow;
+    /**
+     * Adopt a clip this manager did not install — a host's own single `clipPath` —
+     * as a one-entry stack, so it shows up in the UI as a mask row before anything
+     * is added to it. A mask preset is left alone unless asked for by name: it is
+     * still owned by `MaskPresetManager` until a stack operation takes it over.
+     */
+    adopt(target: string, name?: string): LayerMaskEntry | null;
+    /** After a state restore: re-pin the design overlay and recompose every stack. */
+    refreshAll(): void;
+    private patch;
+}
+
+interface ComposeOptions {
+    /** Host box in the coordinate space the children use, for the implicit base. */
+    box: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * Canvas-space children (an unlinked mask is pinned to the canvas, so the
+     * whole group has to leave the host's local space with it).
+     */
+    absolute: boolean;
+}
+/**
+ * Build the `clipPath` for one mask stack: one child per entry, in order, each
+ * carrying its mode's compositing operation.
+ *
+ * `children` are consumed — a Group takes ownership of what it is given and
+ * rewrites the coordinates, so callers pass clones of their sources rather than
+ * the sources themselves.
+ */
+declare function composeMaskGroup(children: FabricObject[], entries: LayerMaskEntry[], options: ComposeOptions): Group | undefined;
+/** True when the stack has to be composed in canvas space rather than host space. */
+declare function needsAbsoluteSpace(entries: LayerMaskEntry[]): boolean;
+
+/** Host-space geometry → canvas-space, for the same on-screen result. */
+declare function toCanvasSpace(object: FabricObject, host: FabricObject): void;
+/** Canvas-space geometry → host-space, for the same on-screen result. */
+declare function toHostSpace(object: FabricObject, host: FabricObject): void;
+/** Scale an object so its unrotated box covers `box`, centred on it. */
+declare function fitToBox(object: FabricObject, box: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, zoom?: number): void;
+/**
+ * Pull a composed clip group back apart into standalone objects in the space the
+ * group itself was in.
+ *
+ * `removeAll` already restores each child's own transform on the way out — the
+ * group rebases children when it takes them in, and reverses that when it lets
+ * them go. Folding the group's matrix back in on top (as one would with a v5-era
+ * group) double-counts it, which stays invisible while a mask sits at the origin
+ * and moves it twice as far as it should the moment one does not.
+ *
+ * The group passed in is emptied.
+ */
+declare function unwrapGroup(group: Group): FabricObject[];
+
 declare class CanvasEditor {
     readonly canvas: Canvas;
     readonly layers: LayerManager;
@@ -554,6 +907,8 @@ declare class CanvasEditor {
     readonly patterns: PatternManager;
     readonly curves: TextCurveManager;
     readonly maskPresets: MaskPresetManager;
+    /** Stacked boolean masks, per layer and for the design as a whole. */
+    readonly layerMasks: LayerMaskManager;
     readonly fonts: FontRegistry;
     readonly licensing: LicenseManager;
     readonly pages: ProjectManager;
@@ -820,4 +1175,4 @@ declare class AnnotationOverlay {
  */
 declare function displaceRgba(source: Uint8ClampedArray, map: Uint8ClampedArray, width: number, height: number, options: Omit<MockupDisplacement, 'image'>): Uint8ClampedArray;
 
-export { AnnotationOverlay, type AnnotationPrimitive, BackgroundImageOptions, CANVAS_SIZE_PRESETS, CanvasEditor, CanvasSizePreset, type CoverPlacement, CropController, DEFAULT_LAYER_SHADOW, DEFAULT_SELECTION_STYLE, DEFAULT_TEXT_CURVE, DpiIssue, EditorConfig, EditorEvents, EditorState, EventEmitter, FileAdapter, FontDefinition, FontRegistry, HistoryManager, ImageAdjustments, ImageProvider, ImageProviderResult, ImageSearchOptions, ImageSearchResult, Layer, LayerData, LayerManager, LayerMeta, LayerShadowConfig, LayerType, LicenseConfig, LicenseManager, LicenseStatus, MaskBrushOptions, MaskController, type MaskPerformanceSample, MaskPoint, MaskPresetId, MaskPresetManager, MaskRefinementError, type MaskRefinementErrorCode, MaskRefinementPrompt, MaskRefinementProvider, MaskRefinementResult, MockupConfig, MockupDisplacement, MockupPrintArea, NormalizedLayerPosition, PatternConfig, PatternLocks, PatternManager, PatternSourceResolver, type PngExportOptions, PositioningAdapter, PrintifyPositioning, ProjectManager, ProjectState, ResizeOptions, SHAPE_MASK_BOX, SHAPE_MASK_IDS, type SelectionStyle, SemanticExportOptions, SerializedBackgroundImageOptions, SerializedLayer, ShapeMaskPresetId, ShapePlugin, SnapManager, SvgExportOptions, TEXTURE_MASK_IDS, TEXTURE_MASK_SIZE, TemplateDefinition, TextCurveConfig, TextCurveManager, TextureMaskPresetId, type TilePlacement, Unit, UnitConverter, type ViewportTransform, applyAspectLock, applyLayerShadow, applyObjectSelectionStyle, applyPatternLocks, applySelectionStyle, buildCurvePathData, buildPatternDataURL, captureLocks, clamp, clearPatternImageCache, clearTextureMaskCache, computeCoverPlacement, computePrintAreaClip, computeTilePositions, deserializeEditor, displaceRgba, drawTiles, escapeXml, exportDataURL, exportMockup, exportPNG, exportPrintArea, exportSVG, generateId, isCssColor, isMaskPresetId, isShapeMaskId, isTextureMaskId, loadPatternImage, readLayerShadow, renderTextureMask, resetTransform, restoreLocks, round2, sanitizeSvg, serializeEditor, shapeMaskPathData };
+export { type AddMaskOptions, AnnotationOverlay, type AnnotationPrimitive, BackgroundImageOptions, CANVAS_MASK_TARGET, CANVAS_SIZE_PRESETS, CanvasEditor, type CanvasRenderingProtocol, CanvasSizePreset, type CoverPlacement, CropController, DEFAULT_LAYER_SHADOW, DEFAULT_SELECTION_STYLE, DEFAULT_TEXT_CURVE, DpiIssue, EditorConfig, EditorEvents, EditorState, EventEmitter, FileAdapter, FontDefinition, FontRegistry, HistoryManager, ImageAdjustments, ImageProvider, ImageProviderResult, ImageSearchOptions, ImageSearchResult, Layer, LayerData, LayerManager, LayerMaskEntry, LayerMaskManager, LayerMaskMode, LayerMeta, LayerShadowConfig, LayerType, LicenseConfig, LicenseManager, LicenseStatus, MaskBrushOptions, MaskController, type MaskPerformanceSample, MaskPoint, MaskPresetId, MaskPresetManager, MaskRefinementError, type MaskRefinementErrorCode, MaskRefinementPrompt, MaskRefinementProvider, MaskRefinementResult, MockupConfig, MockupDisplacement, MockupPrintArea, NormalizedLayerPosition, PatternConfig, PatternLocks, PatternManager, type PatternOrigin, type PngExportOptions, PositioningAdapter, PrintifyPositioning, ProjectManager, ProjectState, ResizeOptions, SHAPE_MASK_BOX, SHAPE_MASK_IDS, type SelectionStyle, SemanticExportOptions, SerializedBackgroundImageOptions, SerializedLayer, ShapeMaskPresetId, ShapePlugin, SnapManager, SvgExportOptions, TEXTURE_MASK_IDS, TEXTURE_MASK_SIZE, TemplateDefinition, TextCurveConfig, TextCurveManager, TextureMaskPresetId, type TilePlacement, TiledPatternObject, Unit, UnitConverter, type ViewportTransform, applyAspectLock, applyLayerShadow, applyObjectSelectionStyle, applySelectionStyle, buildCurvePathData, clamp, clearTextureMaskCache, composeMaskGroup, computeCoverPlacement, computePrintAreaClip, computeTilePositions, deserializeEditor, displaceRgba, drawTiles, escapeXml, exportDataURL, exportMockup, exportPNG, exportPrintArea, exportSVG, fitToBox, generateId, isCssColor, isMaskPresetId, isShapeMaskId, isTextureMaskId, needsAbsoluteSpace, readLayerShadow, renderTextureMask, resetTransform, restoreLocks, round2, sanitizeSvg, serializeEditor, shapeMaskPathData, toCanvasSpace, toHostSpace, unwrapGroup };