@snowcone-app/canvas 0.1.0

package/dist/services/AutoExportManager.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Configuration for auto-export behavior
+ */
+export interface AutoExportConfig {
+    /** Enable/disable auto-export */
+    enabled: boolean;
+    /** Debounce delay - wait this long after last change before exporting (ms) */
+    debounceMs: number;
+    /** Maximum wait time - force export after this duration even if changes keep coming (ms) */
+    maxWaitMs: number;
+}
+/**
+ * Default configuration values
+ */
+export declare const DEFAULT_AUTO_EXPORT_CONFIG: AutoExportConfig;
+/**
+ * Statistics about auto-export behavior
+ */
+export interface AutoExportStats {
+    /** Total number of exports triggered */
+    totalExports: number;
+    /** Number of exports skipped due to no changes */
+    skippedExports: number;
+    /** Last export timestamp */
+    lastExportTime: number | null;
+    /** Average time between exports (ms) */
+    avgExportInterval: number;
+}
+/**
+ * Manages automatic export triggered by editor state changes.
+ *
+ * Uses lodash debounce with `maxWait` to batch rapid changes (drag operations,
+ * continuous typing) into a single export while guaranteeing a maximum latency.
+ * Performs deep state comparison to skip no-op exports.
+ *
+ * Typically used via the `useAutoExport` hook rather than directly.
+ *
+ * @example
+ * ```ts
+ * const manager = new AutoExportManager({ enabled: true, debounceMs: 100, maxWaitMs: 1000 });
+ * manager.onExport(async () => { await exportAllArtboards(); });
+ * manager.scheduleExport(); // debounced
+ * manager.destroy(); // cleanup
+ * ```
+ */
+export declare class AutoExportManager {
+    private config;
+    private debouncedExport;
+    private onExportCallback;
+    private onExportScheduledCallback;
+    private revision;
+    private lastExportedRevision;
+    private stats;
+    private exportTimestamps;
+    constructor(config?: Partial<AutoExportConfig>);
+    /**
+     * Schedule an export (will be debounced)
+     * Call this whenever any change happens in the editor
+     */
+    scheduleExport(): void;
+    /**
+     * Force an immediate export (bypassing debounce)
+     */
+    forceExport(): Promise<void>;
+    /**
+     * Internal: Perform the actual export
+     *
+     * PERF: Uses a revision counter instead of JSON.stringify for change detection.
+     * scheduleExport() bumps `this.revision`; we compare it to `lastExportedRevision`.
+     * This eliminates the expensive JSON.stringify of all elements+artboards that was
+     * causing ~50-200ms of main-thread work every time the debounce fired (~1s).
+     *
+     * The export callback itself (element serialization + worker postMessage) is
+     * deferred via setTimeout(0) so it doesn't block the current animation frame.
+     */
+    private performExport;
+    /**
+     * Register callback to be called when export should happen
+     */
+    onExport(callback: () => void | Promise<void>): void;
+    /**
+     * Register callback to be notified when an export is scheduled (before debounce)
+     * This is called immediately when a change is detected, allowing consumers
+     * to show loading indicators before the actual export completes.
+     */
+    onExportScheduled(callback: () => void): void;
+    /**
+     * Update configuration (can be called while running)
+     */
+    updateConfig(newConfig: Partial<AutoExportConfig>): void;
+    /**
+     * Get current statistics
+     */
+    getStats(): AutoExportStats;
+    /**
+     * Reset statistics
+     */
+    resetStats(): void;
+    /**
+     * Reset change detection (next export will always trigger)
+     */
+    resetChangeDetection(): void;
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+}

package/dist/services/falApi.d.ts

@@ -0,0 +1,63 @@
+/**
+ * fal.ai API Service - Background Removal
+ *
+ * Uses the fal.ai/bria/background/remove API (Bria RMBG 2.0) to remove backgrounds from images.
+ * This model is trained exclusively on licensed data for commercial use.
+ *
+ * API Key: Set VITE_FAL_API_KEY in your .env file
+ * Get your API key from: https://fal.ai/dashboard/keys
+ *
+ * Documentation: https://fal.ai/models/fal-ai/bria/background/remove/api
+ */
+export interface RemoveBackgroundRequest {
+    image_url: string;
+    sync_mode?: boolean;
+}
+export interface RemoveBackgroundResponse {
+    image: {
+        url: string;
+        content_type: string;
+        file_name: string;
+        file_size: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Check if fal.ai API is configured
+ */
+export declare function isFalConfigured(): boolean;
+/**
+ * Remove background from an image using fal.ai Bria RMBG 2.0 API
+ * This model is trained on licensed data and suitable for commercial use.
+ *
+ * @param imageUrl - URL of the image to process
+ * @param options - Optional parameters (sync_mode)
+ * @returns Promise with the processed image data
+ */
+export declare function removeBackground(imageUrl: string, options?: {
+    syncMode?: boolean;
+}): Promise<RemoveBackgroundResponse>;
+/**
+ * Convert the fal.ai response image to a data URL
+ * Useful for immediate preview without external dependencies
+ *
+ * @param imageUrl - URL from fal.ai response
+ * @returns Promise with data URL
+ */
+export declare function convertToDataUrl(imageUrl: string): Promise<string>;
+/**
+ * Check if a URL or data URL points to an SVG image
+ *
+ * @param url - Image URL or data URL
+ * @returns true if the image is SVG
+ */
+export declare function isSvgImage(url: string): boolean;
+/**
+ * Convert an SVG image to PNG using canvas
+ *
+ * @param svgUrl - URL or data URL of the SVG image
+ * @param maxWidth - Maximum width for the output PNG (default: 2048)
+ * @returns Promise with PNG data URL
+ */
+export declare function convertSvgToPng(svgUrl: string, maxWidth?: number): Promise<string>;

package/dist/services/nounProjectApi.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Noun Project API Service
+ *
+ * Provides access to The Noun Project's icon/vector graphics API
+ * API Documentation: https://api.thenounproject.com/documentation.html
+ *
+ * Authentication: OAuth 1.0
+ * - API Key and Secret required (set via environment variables)
+ * - VITE_NOUN_PROJECT_API_KEY
+ * - VITE_NOUN_PROJECT_API_SECRET
+ *
+ * Note: For production, OAuth 1.0 authentication should be handled server-side
+ * to protect the API secret. This client-side implementation is for development only.
+ */
+export interface NounProjectIcon {
+    id: string;
+    term: string;
+    thumbnail_url: string;
+    permalink: string;
+    attribution: string;
+    license_description: string;
+    creator: {
+        name: string;
+        username: string;
+        permalink: string;
+    };
+    collections?: Array<{
+        id: string;
+        name: string;
+    }>;
+    tags?: string[];
+    styles?: Array<{
+        id: string;
+        name: string;
+    }>;
+    icon_url?: string;
+    preview_url?: string;
+    preview_url_42?: string;
+    preview_url_84?: string;
+    preview_url_200?: string;
+}
+export interface VectorResult {
+    id: string;
+    urls: {
+        svg?: string;
+        png: string;
+        preview: string;
+        thumbnail: string;
+    };
+    term: string;
+    attribution: string | null;
+    uploader: {
+        name: string;
+        username: string;
+    };
+    source: 'noun-project';
+}
+/**
+ * Check if API keys are configured
+ * When using proxy, we assume the proxy has the keys configured
+ */
+export declare const isNounProjectConfigured: () => boolean;
+/**
+ * Search for icons/vectors
+ */
+export declare const searchIcons: (query: string, options?: {
+    limit?: number;
+    includeSvg?: boolean;
+    limitToPublicDomain?: boolean;
+    nextPage?: string;
+}) => Promise<{
+    results: VectorResult[];
+    nextPage: string | null;
+}>;
+/**
+ * Get popular/featured icons
+ */
+export declare const getFeaturedIcons: (options: {
+    limit?: number;
+    includeSvg?: boolean;
+}) => Promise<VectorResult[]>;
+/**
+ * Get SVG download URL for a specific icon
+ * Uses the /v2/icon/{id}/download endpoint
+ *
+ * @param iconId - The icon ID (without 'noun-' prefix)
+ * @param color - Optional hex color (without #)
+ * @returns Download URL for the SVG file
+ */
+export declare const getIconSvgUrl: (iconId: string, color?: string) => string;

package/dist/services/recraftApi.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Recraft V3 API Service
+ *
+ * Provides AI-powered image generation capabilities using Recraft's API.
+ * Supports both photo-realistic and vector (SVG) digital illustration styles.
+ *
+ * API Documentation: https://www.recraft.ai/docs/api-reference/getting-started
+ *
+ * Environment Variable:
+ * - VITE_RECRAFT_API_TOKEN - Get from https://www.recraft.ai/
+ */
+interface RecraftGenerationRequest {
+    prompt: string;
+    style: string;
+    model?: 'recraftv3';
+    size?: '1024x1024' | '1365x1024' | '1024x1365' | '1536x1024' | '1024x1536' | '1820x1024' | '1024x1820' | '1024x2048' | '2048x1024' | '1434x1024' | '1024x1434' | '1024x1280' | '1280x1024' | '1024x1707' | '1707x1024';
+    n?: number;
+}
+export interface RecraftResult {
+    id: string;
+    url: string;
+    prompt: string;
+    style: string;
+    format: 'png' | 'svg';
+    created: number;
+}
+/**
+ * Recraft V3 Styles and Substyles
+ * Based on official API documentation
+ */
+export type RecraftStyleType = 'realistic_image' | 'digital_illustration' | 'vector_illustration';
+export interface RecraftStyleOption {
+    value: RecraftStyleType;
+    label: string;
+    substyles: string[];
+}
+/**
+ * Available styles with their substyles (Recraft V3 only)
+ */
+export declare const RECRAFT_STYLES: RecraftStyleOption[];
+/**
+ * Check if Recraft API is configured
+ */
+export declare function isRecraftConfigured(): boolean;
+/**
+ * Generate an image using Recraft V3 API
+ *
+ * @param prompt - Text description of the image to generate
+ * @param style - Style type ('realistic_image', 'digital_illustration', 'vector_illustration')
+ * @param substyle - Optional substyle name for the selected style
+ * @param options - Additional generation options (size, n)
+ * @returns Promise resolving to generated image result
+ */
+export declare function generateImage(prompt: string, style: RecraftStyleType, substyle?: string, options?: {
+    size?: RecraftGenerationRequest['size'];
+    n?: number;
+}): Promise<RecraftResult>;
+/**
+ * Download image data from Recraft URL
+ *
+ * @param url - Image URL from Recraft API
+ * @returns Promise resolving to data URL (for SVG) or blob URL (for PNG)
+ */
+export declare function downloadRecraftImage(url: string): Promise<string>;
+export {};

package/dist/services/runwareApi.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Runware API Service - AI Image Generation
+ *
+ * Uses the Runware AI SDK for high-performance image generation via WebSocket.
+ *
+ * API Key: Set VITE_RUNWARE_API_KEY in your .env file
+ * Get your API key from: https://runware.ai/
+ *
+ * Documentation: https://runware.ai/docs/en/libraries/javascript
+ * SDK: @runware/sdk-js
+ */
+export declare const RUNWARE_MODELS: readonly [{
+    readonly id: "runware:101@1";
+    readonly name: "Flux Dev";
+    readonly description: "High-quality generation with excellent detail and composition";
+    readonly supportsSteps: true;
+    readonly supportsCFGScale: true;
+    readonly supportsNegativePrompt: true;
+}, {
+    readonly id: "google:4@2";
+    readonly name: "Nano Banana 2 Pro";
+    readonly description: "Advanced Google model for controlled visual creation";
+    readonly supportsSteps: false;
+    readonly supportsCFGScale: false;
+    readonly supportsNegativePrompt: false;
+}];
+export type RunwareModelId = (typeof RUNWARE_MODELS)[number]['id'];
+export interface GenerateImageRequest {
+    prompt: string;
+    model: RunwareModelId;
+    width?: number;
+    height?: number;
+    steps?: number;
+    cfgScale?: number;
+    negativePrompt?: string;
+}
+export interface GeneratedImage {
+    imageURL: string;
+    imageUUID: string;
+    width: number;
+    height: number;
+}
+export interface GenerateImageResponse {
+    images: GeneratedImage[];
+    taskUUID: string;
+}
+/**
+ * Check if Runware API is configured
+ */
+export declare function isRunwareConfigured(): boolean;
+/**
+ * Generate images using Runware AI
+ *
+ * @param request - Image generation parameters
+ * @returns Promise with generated images
+ */
+export declare function generateImages(request: GenerateImageRequest): Promise<GenerateImageResponse>;
+/**
+ * Convert image URL to data URL for immediate use
+ *
+ * @param imageUrl - URL from Runware response
+ * @returns Promise with data URL
+ */
+export declare function convertImageToDataUrl(imageUrl: string): Promise<string>;
+/**
+ * Disconnect the Runware SDK instance
+ * Call this when the app is closing or you want to clean up the connection
+ */
+export declare function disconnectRunware(): Promise<void>;