@overtone-art/canvas-editor-core 0.2.7 → 0.3.0

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { Canvas, FabricObject, ImageFormat } from 'fabric';
-import { b as EditorEvents, l as LayerType, k as LayerMeta, L as LayerData, S as SerializedLayer, t as PatternSourceResolver, P as PatternConfig, s as PatternLocks, U as Unit, r as MockupPrintArea, p as MockupConfig, e as FontDefinition, m as LicenseConfig, o as LicenseStatus, y as ProjectState, E as EditorConfig, z as ShapePlugin, T as TemplateDefinition, I as ImageAdjustments, c as EditorState, A as SvgExportOptions, w as PrintifyPositioning, N as NormalizedLayerPosition, v as PositioningAdapter, h as ImageProviderResult, i as ImageSearchOptions, j as ImageSearchResult, F as FileAdapter, g as ImageProvider, B as BackgroundImageOptions, R as ResizeOptions, a as DpiIssue, C as CanvasSizePreset } from './types-bOY7oYVq.mjs';
-export { D as DEFAULT_PATTERN_CONFIG, d as ExportFormat, f as ImageAttribution, n as LicensePayload, M as MockupBlendMode, q as MockupOverlay, u as PatternState, x as ProjectPage, G as TemplateParameter, H as TileMode } from './types-bOY7oYVq.mjs';
+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';
 
 type EventHandler<T> = (data: T) => void;
 declare class EventEmitter<TEvents extends {} = Record<string, unknown>> {
@@ -53,8 +53,12 @@ declare class LayerManager {
 }
 
 declare class HistoryManager {
+    private static readonly ASSET_KEY;
     private undoStack;
     private redoStack;
+    private assets;
+    private assetIds;
+    private nextAssetId;
     private maxSize;
     private maxBytes;
     private paused;
@@ -94,6 +98,21 @@ declare class HistoryManager {
     private emitChanged;
     private snapshotBytes;
     private trimToBudget;
+    /**
+     * History is internal and can content-address large raster strings without
+     * changing the public EditorState wire format. Unchanged images are retained
+     * once even when dozens of snapshots reference them.
+     */
+    private compactState;
+    private expandState;
+    /**
+     * Runs on every commit, so it scans for the serialized reference marker
+     * instead of re-parsing every snapshot — parsing multi-megabyte raster states
+     * per save would cost more than the retention it reclaims. `JSON.stringify`
+     * emits the marker verbatim; the same text inside user data is escaped and
+     * therefore cannot match.
+     */
+    private pruneAssets;
 }
 
 /**
@@ -227,6 +246,107 @@ interface CanvasRenderingProtocol {
     drawImage(image: CanvasImageSource, dx: number, dy: number, dw: number, dh: number): void;
 }
 
+/** Straight text — the state every text layer starts in. */
+declare const DEFAULT_TEXT_CURVE: TextCurveConfig;
+interface CurvePath {
+    /** SVG path data the text is laid out along. */
+    data: string;
+    /** Length of that path, used to centre the run on it. */
+    length: number;
+}
+/** Path the given curve traces for a text run of `width` px, or null when straight. */
+declare function buildCurvePathData(config: TextCurveConfig, width: number, fontSize: number): CurvePath | null;
+/**
+ * Bends a text layer's baseline along a generated path.
+ *
+ * The curve lives on the fabric object as a real text path, so it survives
+ * export and serialization with no extra machinery. The parameters that
+ * produced it are kept in `layer.meta.curve` so the UI can show them and so the
+ * path can be rebuilt when the text, font or size changes.
+ */
+declare class TextCurveManager {
+    private canvas;
+    private layers;
+    private history;
+    private events;
+    constructor(canvas: Canvas, layers: LayerManager, history: HistoryManager, events: EventEmitter<EditorEvents>);
+    /** Curve parameters for a layer, or null when it is not curved text. */
+    get(layerId: string): TextCurveConfig | null;
+    isCurved(layerId: string): boolean;
+    /** Apply (or update) the curve on a text layer. Zeroed config clears it. */
+    apply(layerId: string, config: Partial<TextCurveConfig>, save?: boolean): boolean;
+    /** Remove the curve, restoring the authored text box width. */
+    clear(layerId: string, save?: boolean): boolean;
+    /**
+     * Rebuild the path from the stored parameters. Text content, font family and
+     * font size all change the run's width, and the path is sized to that width —
+     * without this the curve keeps the geometry of the text it was created from.
+     */
+    refresh(layerId: string, save?: boolean): boolean;
+    /** Rebuild every curved layer — used after a state restore. */
+    refreshAll(): void;
+    private detach;
+}
+
+declare function isMaskPresetId(value: unknown): value is MaskPresetId;
+/**
+ * Clips a layer to a preset silhouette or soft texture.
+ *
+ * The preset is installed as the fabric object's `clipPath`, so it renders,
+ * exports and serializes through the same path fabric already uses. The chosen
+ * id is kept in `layer.meta.maskPreset` so the UI can show the active preset
+ * and so the clip can be rebuilt when the layer is resized.
+ *
+ * A pattern strips and restores the layer's clip while it is enabled (see
+ * `PatternManager`), so a mask preset is suspended for the duration of one.
+ */
+declare class MaskPresetManager {
+    private canvas;
+    private layers;
+    private history;
+    private events;
+    constructor(canvas: Canvas, layers: LayerManager, history: HistoryManager, events: EventEmitter<EditorEvents>);
+    get(layerId: string): MaskPresetId | null;
+    /** Clip the layer to `id`. Passing null (or an unknown id) clears the clip. */
+    apply(layerId: string, id: MaskPresetId | null, save?: boolean): boolean;
+    clear(layerId: string, save?: boolean): boolean;
+    /**
+     * Re-fit the clip to the layer's current size. The clip is built for the
+     * object's dimensions at the time it was applied; editing text or replacing an
+     * image changes them, and a stale clip would crop the wrong region.
+     */
+    refresh(layerId: string, save?: boolean): boolean;
+    /** Re-fit every masked layer — used after a state restore. */
+    refreshAll(): void;
+    private buildClip;
+}
+
+/** Silhouette masks, authored on a 0–100 square so they scale to any layer. */
+declare const SHAPE_MASK_IDS: readonly ["circle", "square", "triangle", "star", "heart", "octagram", "arch", "zigzag"];
+type ShapeMaskId = ShapeMaskPresetId;
+declare function isShapeMaskId(value: unknown): value is ShapeMaskId;
+/** SVG path data for a shape mask, on a 100×100 box. */
+declare function shapeMaskPathData(id: ShapeMaskId): string;
+/** Nominal authoring box every shape mask path is drawn in. */
+declare const SHAPE_MASK_BOX = 100;
+
+/**
+ * Procedural alpha textures used as soft layer masks.
+ *
+ * Each renders white-on-transparent at a fixed resolution; the opaque parts are
+ * what survives masking. They are deterministic (seeded PRNG, no `Math.random`)
+ * so a design renders identically on every load and in every export.
+ */
+declare const TEXTURE_MASK_IDS: readonly ["vignette", "halftone", "spray", "grunge", "torn", "band"];
+type TextureMaskId = TextureMaskPresetId;
+declare function isTextureMaskId(value: unknown): value is TextureMaskId;
+/** Square resolution every texture is rendered at before being scaled to fit. */
+declare const TEXTURE_MASK_SIZE = 320;
+/** Render (and memoize) a texture mask. Browser-only: needs a 2D canvas. */
+declare function renderTextureMask(id: TextureMaskId): HTMLCanvasElement;
+/** Drop memoized textures — used by tests and by long-lived editors on dispose. */
+declare function clearTextureMaskCache(): void;
+
 declare class UnitConverter {
     private unit;
     private dpi;
@@ -254,6 +374,14 @@ declare function computePrintAreaClip(area: MockupPrintArea, scaleX: number, sca
 /** Object-fit: cover geometry, exported for deterministic preview/composite tests. */
 declare function computeCoverPlacement(sourceWidth: number, sourceHeight: number, targetWidth: number, targetHeight: number): CoverPlacement;
 declare function exportPNG(canvas: Canvas, options?: PngExportOptions): Promise<Blob>;
+/**
+ * Render just the print-area rectangle, on transparency.
+ *
+ * This is the file a print provider receives: the design alone, cropped to the
+ * printable rectangle, with no garment behind it and no canvas background baked
+ * in — so it is rendered from cloned objects rather than off the live canvas.
+ */
+declare function exportPrintArea(source: Canvas, area: MockupPrintArea, options?: PngExportOptions): Promise<Blob>;
 /** Rasterize the browser mockup preview together with the transparent design. */
 declare function exportMockup(canvas: Canvas, mockup: MockupConfig, options?: PngExportOptions): Promise<Blob>;
 declare function exportSVG(canvas: Canvas): string;
@@ -308,6 +436,60 @@ declare class ProjectManager {
     private emitChanged;
 }
 
+type MaskRefinementErrorCode = 'not-found' | 'cancelled' | 'provider' | 'invalid-result';
+declare class MaskRefinementError extends Error {
+    readonly code: MaskRefinementErrorCode;
+    readonly cause?: unknown | undefined;
+    constructor(code: MaskRefinementErrorCode, message: string, cause?: unknown | undefined);
+}
+interface MaskPerformanceSample {
+    width: number;
+    height: number;
+    backingBytes: number;
+    strokeBackupBytes: number;
+    estimatedPeakBytes: number;
+    historyBytes: number;
+    interactionLatencyMs: number;
+    usedJsHeapBytes?: number;
+    elapsedMs: number;
+}
+/** Raster-mask editing without exposing Fabric brush classes in the public contract. */
+declare class MaskController {
+    private readonly editor;
+    private backing;
+    private context;
+    private layerId;
+    private brush;
+    private previousPoint;
+    private strokeBackup;
+    private strokeStartedAt;
+    private lastInteractionLatencyMs;
+    private refinement;
+    private disposed;
+    constructor(editor: CanvasEditor);
+    create(width?: number, height?: number): Promise<Layer>;
+    attach(layerId: string): void;
+    beginStroke(options: MaskBrushOptions): void;
+    addPoint(point: MaskPoint): void;
+    endStroke(): Promise<void>;
+    cancelStroke(): void;
+    isStrokeActive(): boolean;
+    activeLayerId(): string | null;
+    detach(layerId?: string): void;
+    refine(layerId: string, provider: MaskRefinementProvider, prompts: MaskRefinementPrompt[], options?: {
+        signal?: AbortSignal;
+        onProgress?: (progress: number) => void;
+    }): Promise<MaskRefinementResult>;
+    cancelRefinement(): void;
+    measure(): MaskPerformanceSample | null;
+    dispose(): void;
+    private drawDot;
+    private makeCanvas;
+    private attachBacking;
+    private requireMask;
+    private assertActive;
+}
+
 declare class CanvasEditor {
     readonly canvas: Canvas;
     readonly layers: LayerManager;
@@ -317,15 +499,19 @@ declare class CanvasEditor {
     readonly snapping: SnapManager;
     readonly crop: CropController;
     readonly patterns: PatternManager;
+    readonly curves: TextCurveManager;
+    readonly maskPresets: MaskPresetManager;
     readonly fonts: FontRegistry;
     readonly licensing: LicenseManager;
     readonly pages: ProjectManager;
+    readonly masks: MaskController;
     private fileAdapter?;
     private imageProvider?;
     private zoomLevel;
     private mockup;
     private designBackground;
     private designBackgroundImage;
+    private backgroundImageOptions;
     constructor(canvasElement: HTMLCanvasElement, config: EditorConfig);
     addImage(url: string, options?: Partial<Record<string, unknown>>): Promise<Layer>;
     /** Replace an image source without changing its layer identity or visual transform. */
@@ -350,10 +536,20 @@ declare class CanvasEditor {
     toPNG(options?: PngExportOptions): Promise<Blob>;
     toJPEG(options?: Omit<PngExportOptions, 'format'>): Promise<Blob>;
     toWebP(options?: Omit<PngExportOptions, 'format'>): Promise<Blob>;
+    /** Export one layer in document coordinates or at its native image resolution. */
+    exportLayer(id: string, options?: SemanticExportOptions): Promise<Blob>;
+    /** Export only the configured document background, excluding design layers. */
+    exportBackground(options?: SemanticExportOptions): Promise<Blob>;
     private toRaster;
     toSVG(): string;
     toSVGAsync(options?: SvgExportOptions): Promise<string>;
     toDataURL(format?: ImageFormat, multiplier?: number): string;
+    /**
+     * Export the print file: the design cropped to the mockup's print area, on
+     * transparency. Without a print area this is the whole canvas, still
+     * transparent — a print file never carries the design background.
+     */
+    toPrintFile(options?: PngExportOptions): Promise<Blob>;
     /** Export the current product-preview composite. Advanced warping is host-defined. */
     toMockupImage(options?: PngExportOptions): Promise<Blob>;
     /**
@@ -377,9 +573,10 @@ declare class CanvasEditor {
     setBackground(color: string): void;
     getDesignBackground(): string;
     getDesignBackgroundImage(): FabricObject | null;
+    getBackgroundImageOptions(): SerializedBackgroundImageOptions | null;
     setBackgroundImage(url: string | null, options?: BackgroundImageOptions): Promise<void>;
     /** Used by state restoration and advanced integrations with an existing Fabric object. */
-    setBackgroundImageObject(image: FabricObject | null, save?: boolean): void;
+    setBackgroundImageObject(image: FabricObject | null, save?: boolean, options?: SerializedBackgroundImageOptions | null): void;
     setTransparentBackground(): void;
     resize(width: number, height: number, options?: ResizeOptions): void;
     /** Effective source resolution for an image at its current physical size. */
@@ -404,13 +601,64 @@ declare class CanvasEditor {
     zoomToSelection(padding?: number): void;
     applyPattern(layerId: string, config: PatternConfig): Promise<void>;
     clearPattern(layerId: string): Promise<void>;
-    setMockup(mockup: MockupConfig | null): void;
+    applyTextCurve(layerId: string, config: Partial<TextCurveConfig>): boolean;
+    clearTextCurve(layerId: string): boolean;
+    getTextCurve(layerId: string): TextCurveConfig | null;
+    applyMaskPreset(layerId: string, id: MaskPresetId | null): boolean;
+    clearMaskPreset(layerId: string): boolean;
+    getMaskPreset(layerId: string): MaskPresetId | null;
+    /**
+     * Constrain a layer to its current proportions. Persisted on the layer so a
+     * reopened design still resizes the way it was set up to.
+     */
+    setLayerAspectLock(layerId: string, locked: boolean): boolean;
+    getLayerAspectLock(layerId: string): boolean;
+    /** Re-apply every stored aspect lock — control visibility is not serialized. */
+    restoreAspectLocks(): void;
+    /** Drop scale, rotation, skew and flips; the layer stays where it is. */
+    resetLayerTransform(layerId: string): boolean;
+    setLayerShadow(layerId: string, config: Partial<LayerShadowConfig>): boolean;
+    getLayerShadow(layerId: string): LayerShadowConfig | null;
+    /**
+     * Show (or clear) the product preview. Pass `history: false` for preview-only
+     * changes such as swapping a colourway — those are not design edits and
+     * should not fill the undo stack.
+     */
+    setMockup(mockup: MockupConfig | null, options?: {
+        history?: boolean;
+    }): void;
     clearMockup(): void;
     getMockup(): MockupConfig | null;
     dispose(): void;
     private setupCanvasEvents;
 }
 
+declare const DEFAULT_LAYER_SHADOW: LayerShadowConfig;
+/**
+ * Read a layer's drop shadow back off its fabric object.
+ *
+ * Fabric serializes `shadow` with the object, so the object — not layer meta —
+ * is the source of truth; nothing extra has to round-trip through the editor
+ * state for a shadow to survive save/load.
+ */
+declare function readLayerShadow(object: FabricObject): LayerShadowConfig;
+/** Install (or remove) a drop shadow on a fabric object. */
+declare function applyLayerShadow(object: FabricObject, config: Partial<LayerShadowConfig>): void;
+
+/**
+ * Constrain (or release) a layer's proportions.
+ *
+ * Fabric already scales uniformly from the corners (`canvas.uniformScaling`),
+ * so the lock is enforced by taking away the single-axis handles — every
+ * remaining control keeps the ratio.
+ */
+declare function applyAspectLock(object: FabricObject, locked: boolean): void;
+/**
+ * Undo scaling, rotation, skew and flips, leaving the layer where it sits.
+ * Position is deliberately kept: this is "reset the shape", not "move it back".
+ */
+declare function resetTransform(object: FabricObject): void;
+
 declare const generateId: () => string;
 
 declare function clamp(v: number, min: number, max: number): number;
@@ -437,4 +685,77 @@ declare function deserializeEditor(editor: CanvasEditor, state: EditorState): Pr
 /** Common print and digital canvas sizes. */
 declare const CANVAS_SIZE_PRESETS: readonly CanvasSizePreset[];
 
-export { BackgroundImageOptions, CANVAS_SIZE_PRESETS, CanvasEditor, CanvasSizePreset, type CoverPlacement, CropController, DpiIssue, EditorConfig, EditorEvents, EditorState, EventEmitter, FileAdapter, FontDefinition, FontRegistry, HistoryManager, ImageAdjustments, ImageProvider, ImageProviderResult, ImageSearchOptions, ImageSearchResult, Layer, LayerData, LayerManager, LayerMeta, LayerType, LicenseConfig, LicenseManager, LicenseStatus, MockupConfig, MockupPrintArea, NormalizedLayerPosition, PatternConfig, PatternLocks, PatternManager, PatternSourceResolver, type PngExportOptions, PositioningAdapter, PrintifyPositioning, ProjectManager, ProjectState, ResizeOptions, SerializedLayer, ShapePlugin, SnapManager, SvgExportOptions, TemplateDefinition, type TilePlacement, Unit, UnitConverter, applyPatternLocks, buildPatternDataURL, captureLocks, clamp, clearPatternImageCache, computeCoverPlacement, computePrintAreaClip, computeTilePositions, deserializeEditor, drawTiles, escapeXml, exportDataURL, exportMockup, exportPNG, exportSVG, generateId, isCssColor, loadPatternImage, restoreLocks, round2, sanitizeSvg, serializeEditor };
+type AnnotationPrimitive = {
+    id: string;
+    type: 'point';
+    x: number;
+    y: number;
+    label?: string;
+} | {
+    id: string;
+    type: 'rectangle';
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    label?: string;
+} | {
+    id: string;
+    type: 'label';
+    x: number;
+    y: number;
+    text: string;
+} | {
+    id: string;
+    type: 'path';
+    points: Array<{
+        x: number;
+        y: number;
+    }>;
+    label?: string;
+};
+interface ViewportTransform {
+    zoom: number;
+    panX: number;
+    panY: number;
+    devicePixelRatio?: number;
+}
+/** Host-owned annotations that never enter editor layers, history, serialization, or exports. */
+declare class AnnotationOverlay {
+    private items;
+    private transform;
+    set(annotation: AnnotationPrimitive): void;
+    remove(id: string): boolean;
+    clear(): void;
+    getAll(): AnnotationPrimitive[];
+    setTransform(transform: ViewportTransform): void;
+    documentToViewport(point: {
+        x: number;
+        y: number;
+    }): {
+        x: number;
+        y: number;
+    };
+    viewportToDocument(point: {
+        x: number;
+        y: number;
+    }): {
+        x: number;
+        y: number;
+    };
+    documentToDevice(point: {
+        x: number;
+        y: number;
+    }): {
+        x: number;
+        y: number;
+    };
+}
+
+/**
+ * Warp RGBA pixels with an equally sized channel map. A channel value of 128
+ * is neutral; 0 and 255 move by the configured negative/positive maximum.
+ */
+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_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, 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, applyPatternLocks, 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 };