@snowcone-app/canvas 0.1.0

package/dist/utils/GoogleFontsService.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Service for fetching and managing all Google Fonts
+ */
+export interface GoogleFontMetadata {
+    family: string;
+    category: string;
+    subsets?: string[];
+    variants?: string[];
+    version?: string;
+    lastModified?: string;
+    popularity?: number;
+}
+/**
+ * Fetch all Google Fonts from metadata endpoint
+ * Results are cached after first fetch
+ */
+export declare function fetchAllGoogleFonts(): Promise<GoogleFontMetadata[]>;
+/**
+ * Get all Google Fonts (uses cache if available)
+ */
+export declare function getAllGoogleFonts(): GoogleFontMetadata[];
+/**
+ * Check if fonts have been loaded
+ */
+export declare function isFontsLoaded(): boolean;
+/**
+ * Search Google Fonts by name
+ */
+export declare function searchGoogleFonts(query: string): GoogleFontMetadata[];
+/**
+ * Filter Google Fonts by category
+ */
+export declare function filterGoogleFontsByCategory(category: string): GoogleFontMetadata[];
+/**
+ * Map Google Fonts category to our internal categories
+ */
+export declare function mapGoogleCategory(googleCategory: string): string;

package/dist/utils/ImageLoader.d.ts

@@ -0,0 +1,124 @@
+import { ImageElement } from '../core/ImageElement.js';
+import { ImageElementConfig } from '../types/index.js';
+import { Alignment, ScaleMode } from './ArtworkPlacement.js';
+export interface ImageLoadResult {
+    success: boolean;
+    element?: HTMLImageElement;
+    error?: Error;
+    width?: number;
+    height?: number;
+    aspectRatio?: number;
+}
+export interface ImageLoaderOptions {
+    /** Timeout in milliseconds (default: 30000 - 30 seconds) */
+    timeout?: number;
+    /** Number of retry attempts on failure (default: 1) */
+    retries?: number;
+    /** Retry delay in milliseconds (default: 1000) */
+    retryDelay?: number;
+    /** Whether to validate URL before loading (default: true) */
+    validateUrl?: boolean;
+}
+export type ImageLoadingState = 'idle' | 'loading' | 'success' | 'error';
+/**
+ * Validate if a string is a valid URL
+ */
+export declare function isValidImageUrl(url: string): boolean;
+/**
+ * Load an image from a URL
+ * Returns a promise that resolves with the loaded HTMLImageElement
+ */
+export declare function loadImageFromURL(url: string, options?: ImageLoaderOptions): Promise<ImageLoadResult>;
+/**
+ * Preload multiple images in parallel
+ * Returns results for all images (some may fail)
+ */
+export declare function preloadImages(urls: string[], options?: ImageLoaderOptions): Promise<Map<string, ImageLoadResult>>;
+/**
+ * Create an ImageElement from a URL with loading state handling
+ */
+export declare function createImageElement(url: string, config?: Partial<ImageElementConfig>, options?: ImageLoaderOptions): Promise<{
+    success: boolean;
+    element?: ImageElement;
+    error?: Error;
+}>;
+/**
+ * Configuration for artwork placement on artboard
+ */
+export interface ArtworkPlacementOptions {
+    /** Artboard dimensions */
+    artboard: {
+        width: number;
+        height: number;
+        /** Artboard position on canvas (for proper element positioning) */
+        x: number;
+        y: number;
+    };
+    /** Alignment string (e.g., 'center', 'top', 'bottom-left') */
+    alignment?: string | Alignment;
+    /** User scale multiplier (default: 1) */
+    scale?: number;
+    /** X offset in range -1 to 1 */
+    offsetX?: number;
+    /** Y offset in range -1 to 1 */
+    offsetY?: number;
+    /** Scale mode: "cover" fills area (may crop), "contain" fits inside (may have space). Default: "cover" */
+    scaleMode?: ScaleMode;
+    /** Top margin in pixels (reduces available area in contain mode) */
+    marginTop?: number;
+    /** Right margin in pixels (reduces available area in contain mode) */
+    marginRight?: number;
+    /** Bottom margin in pixels (reduces available area in contain mode) */
+    marginBottom?: number;
+    /** Left margin in pixels (reduces available area in contain mode) */
+    marginLeft?: number;
+}
+/**
+ * Create an ImageElement with proper "cover" sizing and placement on artboard
+ *
+ * This uses CSS-like object-fit: cover logic to ensure the artwork completely
+ * fills the artboard while maintaining aspect ratio, with 9-point alignment support.
+ *
+ * @example
+ * const result = await createImageElementWithPlacement(
+ *   'https://example.com/art.png',
+ *   {
+ *     artboard: { width: 1200, height: 1500, x: 250, y: 250 },
+ *     alignment: 'center',
+ *     scale: 1
+ *   }
+ * );
+ */
+export declare function createImageElementWithPlacement(url: string, placementOptions: ArtworkPlacementOptions, config?: Partial<ImageElementConfig>, loaderOptions?: ImageLoaderOptions): Promise<{
+    success: boolean;
+    element?: ImageElement;
+    error?: Error;
+    placement?: {
+        artworkSize: {
+            width: number;
+            height: number;
+        };
+        finalSize: {
+            width: number;
+            height: number;
+        };
+        position: {
+            x: number;
+            y: number;
+        };
+        scale: number;
+    };
+}>;
+/**
+ * Check if an image URL is accessible (HEAD request)
+ * More efficient than fully loading the image
+ */
+export declare function checkImageUrl(url: string): Promise<boolean>;
+/**
+ * Get image dimensions without fully loading it (when possible)
+ * Falls back to full load if necessary
+ */
+export declare function getImageDimensions(url: string): Promise<{
+    width: number;
+    height: number;
+} | null>;

package/dist/utils/ImportManager.d.ts

@@ -0,0 +1,72 @@
+import { ArtboardElement } from '../core/ArtboardElement.js';
+import { TextElement } from '../core/TextElement.js';
+import { ImageElement } from '../core/ImageElement.js';
+import { GroupElement } from '../core/GroupElement.js';
+export interface ImportResult {
+    success: boolean;
+    artboards?: ArtboardElement[];
+    elements?: (TextElement | ImageElement | GroupElement)[];
+    activeArtboardId?: string | null;
+    error?: string;
+}
+export interface ImageImportResult {
+    success: boolean;
+    dataUrl?: string;
+    filename?: string;
+    width?: number;
+    height?: number;
+    error?: string;
+}
+export declare class ImportManager {
+    private static readonly SUPPORTED_VERSIONS;
+    /**
+     * Import workspace from JSON file
+     */
+    static importFromJSON(file: File): Promise<ImportResult>;
+    /**
+     * Migrate v1 document (no artboards) to v2 (with artboards)
+     */
+    private static migrateV1Document;
+    /**
+     * Import image file
+     */
+    static importImage(file: File): Promise<ImageImportResult>;
+    /**
+     * Validate document structure
+     */
+    private static validateDocument;
+    /**
+     * Read file as text
+     */
+    private static readFileAsText;
+    /**
+     * Read file as data URL
+     */
+    private static readFileAsDataURL;
+    /**
+     * Get image dimensions from data URL
+     */
+    private static getImageDimensions;
+    /**
+     * Validate imported data before applying to state
+     */
+    static validateImportedData(artboards: ArtboardElement[], elements: (TextElement | ImageElement | GroupElement)[]): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Get import summary (for UI display before confirming)
+     */
+    static getImportSummary(artboards: ArtboardElement[], elements: (TextElement | ImageElement | GroupElement)[]): {
+        artboardCount: number;
+        elementCount: number;
+        artboardNames: string[];
+        warnings: string[];
+    };
+    /**
+     * Preload all images in parallel for fast artboard switching
+     * Recursively finds all ImageElements (including those in groups)
+     */
+    private static preloadAllImages;
+}
+export default ImportManager;

package/dist/utils/MonotypeCategoryMapping.d.ts

@@ -0,0 +1,36 @@
+import { FontCategory } from '../fonts/google-fonts.js';
+export interface CategoryRule {
+    canonical: FontCategory;
+    monotypeClassifications: string[];
+    googleCategory?: string;
+    displayName: string;
+    description: string;
+    icon?: string;
+}
+/**
+ * Category mapping rules with priority order
+ * Most specific categories first, general categories last
+ */
+export declare const CATEGORY_MAPPINGS: CategoryRule[];
+/**
+ * Map Monotype classifications to canonical category
+ * Uses priority order (most specific first)
+ *
+ * Example:
+ * - ["SERIF", "SLAB SERIF"] → 'slab-serif' (most specific wins)
+ * - ["SERIF", "OLD STYLE SERIF", "DISPLAY"] → 'display' (priority order)
+ * - ["SANS SERIF", "GEOMETRIC SANS"] → 'sans-serif'
+ *
+ * @param classifications - Array of Monotype classifications
+ * @returns Canonical category
+ */
+export declare function mapMonotypeClassifications(classifications: string[]): FontCategory;
+/**
+ * Get category mapping by canonical name
+ */
+export declare function getCategoryMapping(category: FontCategory): CategoryRule | undefined;
+/**
+ * Get all Monotype classifications for a canonical category
+ * Useful for API searches
+ */
+export declare function getMonotypeClassifications(category: FontCategory): string[];

package/dist/utils/MonotypeService.d.ts

@@ -0,0 +1,148 @@
+import { FontCategory, FontDefinition } from '../fonts/google-fonts.js';
+export interface MonotypeFont {
+    fontId: string;
+    name: string;
+    friendlyName: string;
+    family: string;
+    familyId: string;
+    foundry: string;
+    classification: string[];
+    tag: string[];
+    publicTags: string[];
+    weightCSS: number;
+    sample: string;
+    format?: string;
+}
+export interface MonotypeSearchParams {
+    name?: string;
+    family?: string;
+    classification?: string[];
+    foundry?: string;
+    tag?: string[];
+    searchSettings?: {
+        fuzzy?: string[];
+        partial?: string[];
+        exact?: string[];
+    };
+    pageSize?: number;
+    pageNumber?: number;
+    pageId?: string;
+}
+export interface MonotypeSearchResponse {
+    fonts: MonotypeFont[];
+    nextPageId?: string;
+    totalCount?: number;
+}
+export interface WebFontKit {
+    fontFamily: string;
+    cssUrl: string;
+    timestamp: number;
+}
+declare class MonotypeServiceClass {
+    private accessToken;
+    private tokenExpiry;
+    private fonts;
+    private fontsLoaded;
+    private webfontKits;
+    private searchCache;
+    private readonly API_BASE;
+    private readonly CACHE_TTL;
+    private monotypeEnabled;
+    constructor();
+    /**
+     * Check if Monotype credentials are configured
+     */
+    private checkMonotypeEnabled;
+    /**
+     * Check if Monotype integration is enabled
+     */
+    isMonotypeEnabled(): boolean;
+    /**
+     * Authenticate with Monotype API using OAuth 2.0
+     * Token is cached and automatically refreshed when expired
+     * Returns silently if Monotype is not enabled
+     */
+    authenticate(): Promise<void>;
+    /**
+     * Check if service is authenticated
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Fetch all Monotype fonts with pagination and caching
+     * Strategy: Fetch fonts by category to get classification data
+     * Returns silently if Monotype is not enabled
+     */
+    fetchAllFonts(): Promise<void>;
+    /**
+     * Get all Monotype fonts (uses cache if available)
+     */
+    getAllFonts(): MonotypeFont[];
+    /**
+     * Check if fonts have been loaded
+     */
+    isFontsLoaded(): boolean;
+    /**
+     * Search Monotype fonts (returns raw API response)
+     * For internal use - external callers should use searchFonts()
+     */
+    private searchFontsRaw;
+    /**
+     * Search Monotype fonts and return FontDefinitions
+     * Supports text search, fuzzy matching, and category filtering
+     */
+    searchFonts(params: MonotypeSearchParams): Promise<FontDefinition[]>;
+    /**
+     * Search fonts by name with fuzzy matching
+     */
+    searchFontsByName(query: string): Promise<FontDefinition[]>;
+    /**
+     * Filter fonts by category
+     */
+    filterFontsByCategory(category: FontCategory): Promise<FontDefinition[]>;
+    /**
+     * Group Monotype fonts by family
+     * Reduces 492 font variants to ~120 font families
+     */
+    groupMonotypeFontsByFamily(fonts: MonotypeFont[]): FontDefinition[];
+    /**
+     * Extract font weights from variants
+     */
+    private extractWeights;
+    /**
+     * Get or generate WebFont kit for a Monotype font
+     * Kit URLs are persistent and cached forever
+     */
+    getWebFontKit(fontId: string, fontFamily: string): Promise<WebFontKit>;
+    /**
+     * Load Monotype font by injecting CSS link
+     */
+    loadMonotypeFont(fontId: string, fontFamily: string): Promise<void>;
+    /**
+     * Load caches from localStorage
+     */
+    private loadCachesFromStorage;
+    /**
+     * Save caches to localStorage
+     */
+    private saveCachesToStorage;
+    /**
+     * Clear all caches (including auth state)
+     */
+    clearCaches(): void;
+    /**
+     * Get service stats for debugging
+     */
+    getStats(): {
+        monotypeEnabled: boolean;
+        authenticated: boolean;
+        hasAccessToken: boolean;
+        tokenExpiry: string | null;
+        fontsLoaded: boolean;
+        fontCount: number;
+        familyCount: number;
+        webfontKitCount: number;
+        searchCacheSize: number;
+    };
+}
+export declare const MonotypeService: MonotypeServiceClass;
+export {};

package/dist/utils/PerformanceMonitor.d.ts

@@ -0,0 +1,54 @@
+/**
+ * PerformanceMonitor - Dev-mode performance metrics for the canvas render loop.
+ *
+ * Singleton class that tracks frame times, element counts, cache hit rates,
+ * and export durations. Exposed on `window.__CANVAS_PERF__` in dev mode
+ * so developers can inspect real-time metrics from the browser console.
+ *
+ * @example
+ * ```ts
+ * // Record a frame render time
+ * const start = performance.now();
+ * renderFrame();
+ * PerformanceMonitor.getInstance().recordFrameTime(performance.now() - start);
+ *
+ * // Read metrics from console in dev mode
+ * window.__CANVAS_PERF__.getMetrics();
+ * ```
+ */
+export interface CanvasPerformanceMetrics {
+    /** Average frame render time in ms (rolling window of last 60 frames) */
+    frameTime: number;
+    /** Total frames rendered since last reset */
+    frameCount: number;
+    /** Current element count on the active artboard */
+    elementCount: number;
+    /** Bitmap cache hit rate as a ratio 0-1 */
+    cacheHitRate: number;
+    /** Duration of the last export operation in ms */
+    lastExportDuration: number;
+}
+export declare class PerformanceMonitor {
+    private static instance;
+    private metrics;
+    /** Rolling window of the last N frame times (ms) */
+    private frameTimes;
+    private constructor();
+    static getInstance(): PerformanceMonitor;
+    /**
+     * Record a single frame's render duration. Maintains a rolling window
+     * of the last 60 values and recomputes the average.
+     */
+    recordFrameTime(ms: number): void;
+    /** Record the duration of an export operation. */
+    recordExportDuration(ms: number): void;
+    /** Update the current element count (call once per frame or on change). */
+    setElementCount(count: number): void;
+    /** Update the bitmap cache hit rate (0-1). */
+    setCacheHitRate(rate: number): void;
+    /** Return a readonly snapshot of the current metrics. */
+    getMetrics(): Readonly<CanvasPerformanceMetrics>;
+    /** Reset all metrics and the rolling window. */
+    reset(): void;
+    private _average;
+}

package/dist/utils/TextureManager.d.ts

@@ -0,0 +1,60 @@
+/**
+ * TextureManager - Loads and caches background textures
+ * Provides texture loading for artboard backgrounds
+ */
+export interface TextureInfo {
+    id: string;
+    name: string;
+    url: string;
+    category?: string;
+    presetColor: string;
+}
+export declare class TextureManager {
+    private static cache;
+    private static loading;
+    /**
+     * Available built-in textures
+     */
+    static readonly TEXTURES: TextureInfo[];
+    /**
+     * Load a texture by ID or URL
+     */
+    static loadTexture(idOrUrl: string): Promise<HTMLImageElement>;
+    /**
+     * Get a texture synchronously (returns null if not loaded)
+     */
+    static getTexture(idOrUrl: string): HTMLImageElement | null;
+    /**
+     * Preload multiple textures
+     */
+    static preloadTextures(idsOrUrls: string[]): Promise<void>;
+    /**
+     * Preload all built-in textures
+     */
+    static preloadAllTextures(): Promise<void>;
+    /**
+     * Clear cache
+     */
+    static clearCache(): void;
+    /**
+     * Resolve texture URL from ID
+     */
+    private static resolveTextureUrl;
+    /**
+     * Get texture info by ID
+     */
+    static getTextureInfo(id: string): TextureInfo | undefined;
+    /**
+     * Get all available textures
+     */
+    static getAllTextures(): TextureInfo[];
+    /**
+     * Get textures by category
+     */
+    static getTexturesByCategory(category: string): TextureInfo[];
+    /**
+     * Get preset color for a texture
+     * Each texture has a fixed color that's part of its preset
+     */
+    static getTexturePresetColor(textureId: string): string;
+}

package/dist/utils/UnifiedFontService.d.ts

@@ -0,0 +1,117 @@
+import { FontCategory, FontDefinition } from '../fonts/google-fonts.js';
+declare class UnifiedFontServiceClass {
+    private searchCache;
+    private previewFontLinks;
+    /**
+     * Initialize both Google Fonts and Monotype
+     * Monotype is optional - app works with Google Fonts only if credentials not configured
+     */
+    initialize(): Promise<void>;
+    /**
+     * Check if fonts are loaded
+     */
+    isFontsLoaded(): boolean;
+    /**
+     * Check if Monotype integration is enabled
+     */
+    isMonotypeEnabled(): boolean;
+    /**
+     * Get all fonts from both sources
+     * Returns system fonts + Google Fonts + Monotype Fonts (deduplicated)
+     */
+    getAllFonts(): FontDefinition[];
+    /**
+     * Get recommended fonts (TSHIRT_FONTS curated list)
+     */
+    getRecommendedFonts(): FontDefinition[];
+    /**
+     * Search fonts by name (text search with fuzzy matching)
+     * Combines results from both Google Fonts and Monotype
+     */
+    searchFontsByName(query: string): Promise<FontDefinition[]>;
+    /**
+     * Filter fonts by category
+     * Combines results from both Google Fonts and Monotype
+     */
+    filterFontsByCategory(category: FontCategory): Promise<FontDefinition[]>;
+    /**
+     * Combined search: text search + category filter
+     * Option A: Search overrides category (simpler UX)
+     */
+    searchAndFilterFonts(query: string, category: FontCategory | 'all'): Promise<FontDefinition[]>;
+    /**
+     * Load a font (Google or Monotype). All exposed fonts are one or
+     * the other; the picker no longer offers true "system" fonts that
+     * aren't on Google Fonts because Android lacks them and we'd render
+     * inconsistently across platforms.
+     */
+    loadFont(font: FontDefinition): Promise<void>;
+    /**
+     * Load Google Font via CSS link injection (full font)
+     */
+    private loadGoogleFont;
+    /**
+     * Load Google Font with only specific characters (for previews)
+     * Uses the text= parameter to load minimal glyphs (~99.9% smaller than full font)
+     * See: https://developers.google.com/fonts/docs/getting_started#optimizing_your_font_requests
+     *
+     * @param fontName - Font family name
+     * @param text - Text to render (only these characters will be loaded)
+     */
+    loadGoogleFontForPreview(fontName: string, text: string): void;
+    /**
+     * Clear all preview font links from DOM
+     * Call this when closing the font browser to free memory
+     */
+    clearPreviewFonts(): void;
+    /**
+     * Get count of loaded preview fonts
+     */
+    getPreviewFontCount(): number;
+    /**
+     * Map Google Font metadata to FontDefinition
+     */
+    private mapGoogleFont;
+    /**
+     * Map Google Fonts array to FontDefinitions
+     */
+    private mapGoogleFonts;
+    /**
+     * Merge fonts from multiple sources and deduplicate by family name
+     * Priority: Monotype > Google (Monotype fonts are premium)
+     */
+    private mergeFonts;
+    /**
+     * Clear search cache
+     */
+    clearSearchCache(): void;
+    /**
+     * Clear all caches (including Monotype service caches)
+     */
+    clearAllCaches(): void;
+    /**
+     * Get service stats for debugging
+     */
+    getStats(): {
+        initialized: boolean;
+        monotypeEnabled: boolean;
+        totalFonts: number;
+        googleFontsCount: number;
+        monotopeFontsCount: number;
+        systemFontsCount: number;
+        searchCacheSize: number;
+        monotypeStats: {
+            monotypeEnabled: boolean;
+            authenticated: boolean;
+            hasAccessToken: boolean;
+            tokenExpiry: string | null;
+            fontsLoaded: boolean;
+            fontCount: number;
+            familyCount: number;
+            webfontKitCount: number;
+            searchCacheSize: number;
+        };
+    };
+}
+export declare const UnifiedFontService: UnifiedFontServiceClass;
+export {};