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

package/dist/index.d.ts

@@ -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.js';
-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.js';
+import { b as EditorEvents, l as LayerType, k as LayerMeta, L as LayerData, U as SerializedLayer, G as PatternSourceResolver, P as PatternConfig, A as PatternLocks, _ as Unit, z as MockupPrintArea, v as MockupConfig, e as FontDefinition, m as LicenseConfig, o as LicenseStatus, Q as ProjectState, M as MaskBrushOptions, p as MaskPoint, r as MaskRefinementProvider, q as MaskRefinementPrompt, t as MaskRefinementResult, E as EditorConfig, V as ShapePlugin, X as TemplateDefinition, I as ImageAdjustments, c as EditorState, S as SemanticExportOptions, W as SvgExportOptions, K as PrintifyPositioning, N as NormalizedLayerPosition, J as PositioningAdapter, h as ImageProviderResult, i as ImageSearchOptions, j as ImageSearchResult, F as FileAdapter, g as ImageProvider, T as SerializedBackgroundImageOptions, B as BackgroundImageOptions, R as ResizeOptions, a as DpiIssue, C as CanvasSizePreset, w as MockupDisplacement } from './types-D60CfxL9.js';
+export { D as DEFAULT_PATTERN_CONFIG, d as ExportFormat, f as ImageAttribution, n as LicensePayload, s as MaskRefinementRequest, u as MockupBlendMode, x as MockupDisplacementChannel, y as MockupOverlay, H as PatternState, O as ProjectPage, Y as TemplateParameter, Z as TileMode } from './types-D60CfxL9.js';
 
 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;
 }
 
 /**
@@ -308,6 +327,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;
@@ -320,12 +393,14 @@ declare class CanvasEditor {
     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,6 +425,10 @@ 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>;
@@ -377,9 +456,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. */
@@ -437,4 +517,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, DpiIssue, EditorConfig, EditorEvents, EditorState, EventEmitter, FileAdapter, FontDefinition, FontRegistry, HistoryManager, ImageAdjustments, ImageProvider, ImageProviderResult, ImageSearchOptions, ImageSearchResult, Layer, LayerData, LayerManager, LayerMeta, LayerType, LicenseConfig, LicenseManager, LicenseStatus, MaskBrushOptions, MaskController, type MaskPerformanceSample, MaskPoint, MaskRefinementError, type MaskRefinementErrorCode, MaskRefinementPrompt, MaskRefinementProvider, MaskRefinementResult, MockupConfig, MockupDisplacement, MockupPrintArea, NormalizedLayerPosition, PatternConfig, PatternLocks, PatternManager, PatternSourceResolver, type PngExportOptions, PositioningAdapter, PrintifyPositioning, ProjectManager, ProjectState, ResizeOptions, SemanticExportOptions, SerializedBackgroundImageOptions, SerializedLayer, ShapePlugin, SnapManager, SvgExportOptions, TemplateDefinition, type TilePlacement, Unit, UnitConverter, type ViewportTransform, applyPatternLocks, buildPatternDataURL, captureLocks, clamp, clearPatternImageCache, computeCoverPlacement, computePrintAreaClip, computeTilePositions, deserializeEditor, displaceRgba, drawTiles, escapeXml, exportDataURL, exportMockup, exportPNG, exportSVG, generateId, isCssColor, loadPatternImage, restoreLocks, round2, sanitizeSvg, serializeEditor };