@snowcone-app/canvas 0.1.0

package/dist/rendering/canvas-renderer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Canvas Renderer - Orchestrator module that re-exports from focused sub-modules.
+ *
+ * Pure rendering functions that work in both main thread and worker.
+ * These functions can render to both CanvasRenderingContext2D and OffscreenCanvasRenderingContext2D.
+ *
+ * Sub-modules:
+ * - renderer-types.ts   — Shared type definitions (RenderContext, SerializedTextElement, etc.)
+ * - text-renderer.ts    — Text measurement, plain text rendering, CustomTransform
+ * - rich-text-renderer.ts — Rich text / multi-line / span rendering
+ * - image-renderer.ts   — Image element rendering with crop, flip, border radius
+ * - shape-renderer.ts   — Shape element rendering (rectangle, circle, star, etc.)
+ */
+export type { SerializedTextElement, SerializedImageElement, SerializedShapeElement, } from './renderer-types.js';
+export { buildFontString, measureTextWidth, getFontMetrics, applySpaceLayoutRules, renderTextFillOnly, wrapText, renderMultilineText, renderCustomTransform, renderTextElement, } from './text-renderer.js';
+export { wrapRichTextSpans, splitRichTextIntoLines, renderRichTextFillOnly, } from './rich-text-renderer.js';
+export { renderImageElement } from './image-renderer.js';
+export { renderShapeElement } from './shape-renderer.js';

package/dist/rendering/element-serializer.d.ts

@@ -0,0 +1,143 @@
+import { ArtboardElement } from '../core/ArtboardElement.js';
+import { BaseElement } from '../core/BaseElement.js';
+import { AnyElementConfig, ArtboardDistressTexture, ArtboardImageMask } from '../types/index.js';
+/**
+ * Default maximum dimension for image capping (in pixels)
+ * Images larger than this on any dimension will be scaled down while preserving aspect ratio.
+ * This prevents memory issues with very large images (e.g., 6000x6000 = 144MB per bitmap).
+ */
+export declare const DEFAULT_MAX_BITMAP_DIMENSION = 4000;
+/**
+ * Get cache key for an image element
+ * Uses element ID and image src to create a unique key
+ * Format: "{elementId}:{srcHash}"
+ */
+export declare function getImageCacheKey(elementId: string, imageSrc: string | undefined): string;
+/**
+ * Clear all registered bitmap keys.
+ * Call this when the worker cache is cleared (e.g., on editor exit).
+ * The actual bitmap cleanup happens in the worker via 'clear-all-bitmaps' message.
+ */
+export declare function clearRegisteredBitmapKeys(): void;
+/**
+ * Remove a specific element's registration tracking.
+ * Call this when an element is removed or its image source changes.
+ * The actual bitmap cleanup happens in the worker via 'clear-bitmap' message.
+ */
+export declare function unregisterElementBitmaps(elementId: string): void;
+/**
+ * Mark a bitmap as registered with the worker
+ */
+export declare function markBitmapRegistered(cacheKey: string): void;
+/**
+ * Check if a bitmap is already registered with the worker
+ */
+export declare function isBitmapRegistered(cacheKey: string): boolean;
+/**
+ * Create an ImageBitmap with dimension capping.
+ * If the source image exceeds maxDimension on any side, it will be scaled down
+ * while preserving aspect ratio.
+ *
+ * @param source - HTMLImageElement to create bitmap from
+ * @param maxDimension - Maximum allowed dimension (default: 4000px)
+ * @returns Promise<ImageBitmap> - The (potentially scaled) ImageBitmap
+ */
+export declare function createCappedImageBitmap(source: HTMLImageElement, maxDimension?: number): Promise<ImageBitmap>;
+/**
+ * Register callbacks for worker cache clearing.
+ * Called by WorkerExportManager to enable legacy API to clear worker cache.
+ * @internal
+ */
+export declare function registerWorkerCacheCallbacks(clearAll: () => void, clearElement: (elementId: string) => void): void;
+/**
+ * Unregister callbacks (e.g., when worker terminates).
+ * @internal
+ */
+export declare function unregisterWorkerCacheCallbacks(): void;
+/**
+ * Clear all ImageBitmap caches.
+ * This clears both the main thread tracking AND the worker cache (if available).
+ * Call this when exiting editor mode to free memory.
+ */
+export declare function clearImageBitmapCache(): void;
+/**
+ * Remove a specific element's cached bitmaps.
+ * This clears both the main thread tracking AND the worker cache (if available).
+ * Call this when an element is removed or its image source changes.
+ */
+export declare function removeFromImageBitmapCache(elementId: string): void;
+/**
+ * Serialized artboard data for export
+ */
+export interface SerializedArtboardData {
+    id: string;
+    name: string;
+    width: number;
+    height: number;
+    backgroundColor: string;
+    exportBackground: boolean;
+    x: number;
+    y: number;
+    distressTexture?: ArtboardDistressTexture;
+    imageMask?: ArtboardImageMask;
+}
+/**
+ * Serialized export data sent to worker
+ * Note: Images reference worker cache via bitmapCacheKey, not transferred inline
+ */
+export interface SerializedExportData {
+    version: string;
+    artboard: SerializedArtboardData;
+    elements: AnyElementConfig[];
+    fonts: string[];
+}
+/**
+ * A new bitmap that needs to be registered with the worker
+ */
+export interface NewBitmapRegistration {
+    cacheKey: string;
+    bitmap: ImageBitmap;
+}
+/**
+ * Result from serializeForWorkerExport
+ */
+export interface SerializationResult {
+    /** Serialized data to send to worker for export */
+    data: SerializedExportData;
+    /** New bitmaps that need to be registered with worker before export */
+    newBitmaps: NewBitmapRegistration[];
+}
+export interface SerializedImageElement {
+    id: string;
+    type: 'image';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation: number;
+    /** Cache key for worker bitmap lookup in format "{elementId}:{srcHash}" */
+    bitmapCacheKey: string;
+    cropX?: number;
+    cropY?: number;
+    cropWidth?: number;
+    cropHeight?: number;
+    flipHorizontal?: boolean;
+    flipVertical?: boolean;
+    borderRadius?: number;
+    opacity?: number;
+}
+/**
+ * Serialize artboard and elements for worker export.
+ *
+ * ARCHITECTURE:
+ * - Images are identified by bitmapCacheKey (format: "{elementId}:{srcHash}")
+ * - If a bitmap is not yet registered with the worker, it's included in newBitmaps
+ * - Caller should register newBitmaps with worker before sending export request
+ * - Worker looks up bitmaps from its cache by bitmapCacheKey
+ *
+ * @param artboard - The artboard to export
+ * @param elements - All elements in the canvas
+ * @param maxBitmapDimension - Optional max dimension for image capping (default: 4000px)
+ * @returns SerializationResult with serialized data and any new bitmaps to register
+ */
+export declare function serializeForWorkerExport(artboard: ArtboardElement, elements: BaseElement[], maxBitmapDimension?: number): Promise<SerializationResult>;

package/dist/rendering/image-renderer.d.ts

@@ -0,0 +1,6 @@
+import { RenderContext, SerializedImageElement } from './renderer-types.js';
+/**
+ * Render an image element using ImageBitmap
+ * Works in both main thread and worker
+ */
+export declare function renderImageElement(ctx: RenderContext, elementData: SerializedImageElement, imageBitmap: ImageBitmap): void;

package/dist/rendering/knockout-utils.d.ts

@@ -0,0 +1,48 @@
+import { BlendMode, CompositingConfig, CompositingScope, KnockoutConfig, KnockoutScope } from '../types/index.js';
+/**
+ * Create default knockout configuration
+ */
+export declare function createKnockoutConfig(fill?: boolean, stroke?: boolean, scope?: CompositingScope): CompositingConfig;
+/**
+ * Create stroke knockout configuration (common for t-shirt design)
+ */
+export declare function createStrokeKnockout(scope?: CompositingScope): CompositingConfig;
+/**
+ * Create fill knockout configuration
+ */
+export declare function createFillKnockout(scope?: CompositingScope): CompositingConfig;
+/**
+ * Check if element has any compositing parts enabled (knockout or clip)
+ */
+export declare function hasCompositing(config: CompositingConfig | undefined): boolean;
+/** @deprecated Use hasCompositing instead */
+export declare function hasKnockout(config: KnockoutConfig | undefined): boolean;
+/**
+ * Get compositing parts as array of strings
+ */
+export declare function getCompositingParts(config: CompositingConfig | undefined): string[];
+/** @deprecated Use getCompositingParts instead */
+export declare function getKnockoutParts(config: KnockoutConfig | undefined): string[];
+/**
+ * Get human-readable description of compositing configuration
+ */
+export declare function describeCompositing(config: CompositingConfig | undefined, mode?: BlendMode): string;
+/** @deprecated Use describeCompositing instead */
+export declare function describeKnockout(config: KnockoutConfig | undefined): string;
+/**
+ * Validate knockout configuration
+ */
+export declare function isValidKnockoutConfig(config: KnockoutConfig): boolean;
+/**
+ * Merge knockout configurations
+ * Combines two configs, with priority given to the second one
+ */
+export declare function mergeKnockoutConfigs(config1: KnockoutConfig | undefined, config2: KnockoutConfig | undefined): KnockoutConfig | undefined;
+/**
+ * Clone knockout configuration
+ */
+export declare function cloneKnockoutConfig(config: KnockoutConfig): KnockoutConfig;
+/**
+ * Get recommended scope for use case
+ */
+export declare function getRecommendedScope(useCase: 'tshirt' | 'pillow' | 'pattern' | 'general'): KnockoutScope;

package/dist/rendering/mask-utils.d.ts

@@ -0,0 +1,65 @@
+import { MaskDefinition, MaskType, AnyElementConfig } from '../types/index.js';
+/**
+ * Create a new mask definition
+ */
+export declare function createMask(type: MaskType, maskElement: AnyElementConfig, options?: Partial<Omit<MaskDefinition, 'id' | 'type' | 'maskElement'>>): MaskDefinition;
+/**
+ * Create a clip mask from text
+ */
+export declare function createTextClipMask(text: string, fontSize?: number, fontFamily?: string, options?: Partial<Omit<MaskDefinition, 'id' | 'type' | 'maskElement'>>): MaskDefinition;
+/**
+ * Create a clip mask from an image.
+ * Opaque pixels in the image define the visible area; transparent pixels clip.
+ */
+export declare function createImageClipMask(imageUrl: string, width?: number, height?: number, options?: Partial<Omit<MaskDefinition, 'id' | 'type' | 'maskElement'>>): MaskDefinition;
+/**
+ * Create an alpha mask from an image.
+ * The image's alpha channel controls element visibility.
+ */
+export declare function createImageAlphaMask(imageUrl: string, width?: number, height?: number, options?: Partial<Omit<MaskDefinition, 'id' | 'type' | 'maskElement'>>): MaskDefinition;
+/**
+ * Create a luma mask from an image.
+ * Bright pixels = visible, dark pixels = hidden.
+ */
+export declare function createImageLumaMask(imageUrl: string, width?: number, height?: number, options?: Partial<Omit<MaskDefinition, 'id' | 'type' | 'maskElement'>>): MaskDefinition;
+/**
+ * Create a distress mask from image/texture
+ */
+export declare function createDistressMask(textureUrl: string, opacity?: number, options?: Partial<Omit<MaskDefinition, 'id' | 'type' | 'maskElement'>>): MaskDefinition;
+/**
+ * Calculate relative position for mask element
+ * Converts world coordinates to relative coordinates
+ */
+export declare function calculateRelativePosition(parentX: number, parentY: number, maskWorldX: number, maskWorldY: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Calculate world position for mask element
+ * Converts relative coordinates to world coordinates
+ */
+export declare function calculateWorldPosition(parentX: number, parentY: number, maskRelativeX: number, maskRelativeY: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Validate mask definition
+ */
+export declare function isValidMask(mask: MaskDefinition): boolean;
+/**
+ * Compute mask dimensions using object-contain scaling.
+ *
+ * The mask maintains its natural aspect ratio and scales to fit entirely
+ * within the parent element's bounding box, plus an optional oversize bleed.
+ * This prevents shape masks (star, heart, etc.) from stretching when
+ * applied to non-square images, and ensures the full mask shape is visible
+ * (no clipping of star points, heart bumps, etc.).
+ */
+export declare function computeMaskCoverDimensions(parentW: number, parentH: number, maskNaturalW: number, maskNaturalH: number, oversize?: number): {
+    width: number;
+    height: number;
+};
+/**
+ * Clone a mask definition
+ */
+export declare function cloneMask(mask: MaskDefinition): MaskDefinition;

package/dist/rendering/renderer-types.d.ts

@@ -0,0 +1,79 @@
+import { AnyTransformData, TextAlign, StrokeConfig, OpenTypeFeatures, TextSpan, GlyphOverride } from '../types/index.js';
+export type RenderContext = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+export interface SerializedTextElement {
+    id: string;
+    type: string;
+    richText?: {
+        spans: TextSpan[];
+    };
+    text: string;
+    x: number;
+    y: number;
+    rotation: number;
+    opacity?: number;
+    fontSize: number;
+    fontFamily: string;
+    color: string;
+    textAlign: TextAlign;
+    bold: boolean;
+    italic: boolean;
+    underline: boolean;
+    strikethrough: boolean;
+    transformData: AnyTransformData;
+    stroke?: StrokeConfig;
+    openTypeFeatures?: OpenTypeFeatures;
+    glyphOverrides?: GlyphOverride[];
+    /** Temporary property used during corner resize to lock text wrapping line count */
+    _lockedLineCount?: number;
+}
+export interface SerializedImageElement {
+    id: string;
+    type: 'image';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation: number;
+    /** Cache key for worker bitmap lookup in format "{elementId}:{srcHash}" */
+    bitmapCacheKey: string;
+    cropX?: number;
+    cropY?: number;
+    cropWidth?: number;
+    cropHeight?: number;
+    flipHorizontal?: boolean;
+    flipVertical?: boolean;
+    borderRadius?: number;
+    opacity?: number;
+    stroke?: StrokeConfig;
+    knockoutParts?: {
+        fill?: boolean;
+        stroke?: boolean;
+        scope?: 'group' | 'artboard';
+    };
+}
+export interface SerializedShapeElement {
+    id: string;
+    type: 'shape';
+    x: number;
+    y: number;
+    rotation: number;
+    opacity?: number;
+    transformData: {
+        type: 'shape';
+        shapeType: 'rectangle' | 'circle' | 'ellipse' | 'triangle' | 'polygon' | 'star' | 'line';
+        width: number;
+        height: number;
+        borderRadius?: number;
+        sides?: number;
+        points?: number;
+        innerRadius?: number;
+        fillColor?: string;
+        fillOpacity?: number;
+    };
+    stroke?: StrokeConfig;
+    knockoutParts?: {
+        fill?: boolean;
+        stroke?: boolean;
+        scope?: 'group' | 'artboard';
+    };
+}

package/dist/rendering/rich-text-renderer.d.ts

@@ -0,0 +1,43 @@
+import { TextAlign, CharacterStyle, RichText } from '../types/index.js';
+import { RenderContext } from './renderer-types.js';
+/**
+ * Wrap rich text spans to fit within a given width, preserving character-level formatting
+ *
+ * This function handles character-level formatting correctly by:
+ * 1. First merging consecutive spans with the same style
+ * 2. Finding word boundaries (spaces) across spans
+ * 3. Wrapping at word boundaries, not at span boundaries
+ */
+export declare function wrapRichTextSpans(spans: Array<{
+    text: string;
+    style: CharacterStyle;
+}>, maxWidth: number, element: {
+    fontSize: number;
+    fontFamily: string;
+    bold?: boolean;
+    italic?: boolean;
+}): Array<{
+    text: string;
+    style: CharacterStyle;
+}[]>;
+/**
+ * Split rich text into lines by explicit newlines, preserving span formatting
+ */
+export declare function splitRichTextIntoLines(richText: RichText): Array<{
+    text: string;
+    style: CharacterStyle;
+}[]>;
+/**
+ * Render rich text with per-span styling (fill only, no effects)
+ * Supports multi-line text with line breaks and word wrapping
+ */
+export declare function renderRichTextFillOnly(ctx: RenderContext, richText: RichText, element: {
+    fontSize: number;
+    fontFamily: string;
+    color: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    textAlign?: TextAlign;
+}, maxWidth?: number, lockedLineCount?: number): void;

package/dist/rendering/serialize-for-server.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Serialize canvas state (from onChange/toJSON) to the format the export worker expects.
+ *
+ * This bridges the gap between SnowconeCanvas.onChange() output (element configs with
+ * transformType and nested transformData) and the export worker's expected format
+ * (elements with 'type' field and flattened image properties).
+ *
+ * Use this when sending canvas state to a server-side renderer that runs the export
+ * worker bundle. The client-side serializeForWorkerExport() requires live element
+ * instances; this function works on plain JSON from onChange/toJSON.
+ */
+export interface ServerRenderRequest {
+    artboards: Array<{
+        id: string;
+        name: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        backgroundColor: string;
+        exportBackground: boolean;
+        elements: any[];
+        distressTexture?: any;
+        imageMask?: any;
+    }>;
+}
+/**
+ * Convert onChange canvas state to the server render format.
+ *
+ * @param state - The state from SnowconeCanvas onChange callback
+ * @returns ServerRenderRequest ready to send via sendCanvasState()
+ */
+export declare function serializeStateForServer(state: {
+    elements?: any[];
+    artboards?: Array<{
+        name?: string;
+        width?: number;
+        height?: number;
+        backgroundColor?: string;
+        clipShape?: any;
+        distressTexture?: any;
+        imageMask?: any;
+    }>;
+    activeArtboard?: string;
+}): ServerRenderRequest;

package/dist/rendering/shape-renderer.d.ts

@@ -0,0 +1,6 @@
+import { RenderContext, SerializedShapeElement } from './renderer-types.js';
+/**
+ * Render a shape element
+ * Works in both main thread and worker
+ */
+export declare function renderShapeElement(ctx: RenderContext, elementData: SerializedShapeElement): void;

package/dist/rendering/stroke-utils.d.ts

@@ -0,0 +1,18 @@
+import { AnyElementConfig, ImageElementConfig, RenderingContext } from '../types/index.js';
+/**
+ * Create text path for stroking
+ * Handles all text transform types
+ */
+export declare function createTextPath(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, element: AnyElementConfig, _renderingContext?: RenderingContext): void;
+/**
+ * Create image boundary path for stroking
+ */
+export declare function createImagePath(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, element: ImageElementConfig): void;
+/**
+ * Create circular path (for circle transform or shapes)
+ */
+export declare function createCirclePath(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, x: number, y: number, radius: number): void;
+/**
+ * Create rectangular path
+ */
+export declare function createRectPath(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, x: number, y: number, width: number, height: number): void;

package/dist/rendering/text-renderer.d.ts

@@ -0,0 +1,71 @@
+import { TextAlign, OpenTypeFeatures } from '../types/index.js';
+import { RenderContext, SerializedTextElement } from './renderer-types.js';
+/**
+ * Build font string with optional bold and italic
+ */
+export declare function buildFontString(fontSize: number, fontFamily: string, bold?: boolean, italic?: boolean): string;
+/**
+ * Measure text width
+ */
+export declare function measureTextWidth(text: string, fontSize: number, fontFamily: string, bold?: boolean, italic?: boolean): number;
+/**
+ * Get font metrics for accurate text positioning
+ */
+export declare function getFontMetrics(fontSize: number, fontFamily: string, bold?: boolean, italic?: boolean): {
+    ascent: number;
+    descent: number;
+    height: number;
+};
+/**
+ * Apply space layout rules to text lines for rendering
+ * Hides leading/trailing spaces based on paragraph boundaries to match HTML/CSS text rendering
+ *
+ * Rules (matching browser text rendering behavior):
+ * - Leading spaces are hidden when NOT at paragraph start
+ * - Trailing spaces are hidden when NOT at paragraph end
+ * - Paragraph = text separated by explicit \n characters
+ *
+ * Example:
+ *   Input: ["Foo   ", "Bar"] (from wrapping "Foo   Bar", no explicit \n)
+ *   Output: ["Foo", "Bar"] (trailing space on line 1 hidden)
+ *
+ * @param lines - Array of text lines (from wrapText or split by \n)
+ * @param hasExplicitNewlines - Whether original text contained \n characters
+ * @returns Lines with space collapsing applied for rendering
+ */
+export declare function applySpaceLayoutRules(lines: string[], hasExplicitNewlines: boolean): string[];
+/**
+ * Render text fill only (without transforms or effects)
+ * Shared utility used by main rendering and knockout compositing
+ *
+ * IMPORTANT: This renders ONLY the fill, positioned and transformed correctly
+ * It does NOT render strokes, masks, or other effects
+ */
+export declare function renderTextFillOnly(ctx: RenderContext, element: {
+    text: string;
+    fontSize: number;
+    fontFamily: string;
+    bold?: boolean;
+    italic?: boolean;
+    textAlign?: TextAlign;
+    color: string;
+}): void;
+/**
+ * Word wrap text to fit within a given width
+ */
+export declare function wrapText(text: string, maxWidth: number, fontSize: number, fontFamily: string, bold?: boolean, italic?: boolean, lockedLineCount?: number): string[];
+/**
+ * Render multi-line text with alignment and text decorations
+ * Works with both CanvasRenderingContext2D and OffscreenCanvasRenderingContext2D
+ */
+export declare function renderMultilineText(ctx: RenderContext, lines: string[], x: number, y: number, fontSize: number, fontFamily: string, alignment?: CanvasTextAlign, containerWidth?: number, horizontalPadding?: number, lineHeight?: number, bold?: boolean, italic?: boolean, underline?: boolean, strikethrough?: boolean, openTypeFeatures?: OpenTypeFeatures, glyphOverrides?: import('../types/index.js').GlyphOverride[]): void;
+/**
+ * Render a CustomTransform (straight text) element
+ * Pure function that works in both main thread and worker
+ */
+export declare function renderCustomTransform(ctx: RenderContext, elementData: SerializedTextElement): void;
+/**
+ * Render a text element based on its type
+ * This is the main entry point for rendering text elements in the worker
+ */
+export declare function renderTextElement(ctx: RenderContext, elementData: SerializedTextElement): void;

package/dist/rendering/transform-renderer.d.ts

@@ -0,0 +1,33 @@
+import { AnyTransformData } from '../types/index.js';
+type RenderContext = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+export interface SerializedTextTransformElement {
+    id: string;
+    type: string;
+    text: string;
+    x: number;
+    y: number;
+    rotation: number;
+    fontSize: number;
+    fontFamily: string;
+    color: string;
+    bold: boolean;
+    italic: boolean;
+    transformData: AnyTransformData;
+    stroke?: {
+        enabled: boolean;
+        color: string;
+        width: number;
+        opacity?: number;
+        lineCap?: CanvasLineCap;
+        lineJoin?: CanvasLineJoin;
+        miterLimit?: number;
+        feather?: number;
+    };
+}
+export declare function renderCircleTransform(ctx: RenderContext, elementData: SerializedTextTransformElement): void;
+export declare function renderWaveTransform(ctx: RenderContext, elementData: SerializedTextTransformElement): void;
+export declare function renderArchTransform(ctx: RenderContext, elementData: SerializedTextTransformElement): void;
+export declare function renderAscendTransform(ctx: RenderContext, elementData: SerializedTextTransformElement): void;
+export declare function renderLeanTransform(ctx: RenderContext, elementData: SerializedTextTransformElement): void;
+export declare function renderFlagTransform(ctx: RenderContext, elementData: SerializedTextTransformElement): void;
+export {};