@manifold-studio/typeface/dist/font-resolver.d.ts

Font loading and text-to-3D conversion for Manifold Studio

/**
 * FontResolver - Universal font loading for browser and Node.js environments
 *
 * This module provides a robust font loading system with the following features:
 * - CDN-based font loading with fallback URLs
 * - Cross-platform support (browser and Node.js)
 * - Timeout handling and error recovery
 * - Font caching to avoid redundant downloads
 * - Comprehensive error reporting with custom error types
 *
 * @example
 * ```typescript
 * import { fontResolver } from './font-resolver';
 *
 * // Load a font
 * const loadedFont = await fontResolver.loadFont('Inter Variable Font');
 *
 * // Use the font with OpenType.js
 * const path = loadedFont.font.getPath('Hello', 0, 0, 72);
 * ```
 */
import opentype from 'opentype.js';
/**
 * Font metadata and loading configuration
 */
export interface FontInfo {
    /** Display name for the font */
    name: string;
    /** Primary URL to load the font from */
    url: string;
    /** Font family name */
    family: string;
    /** Font weight (e.g., '400', 'bold') */
    weight?: string;
    /** Font style (e.g., 'normal', 'italic') */
    style?: string;
    /** Fallback URLs to try if primary URL fails */
    fallbackUrls?: string[];
}
/**
 * Successfully loaded font with metadata
 */
export interface LoadedFont {
    /** Original font information */
    info: FontInfo;
    /** Parsed OpenType.js font object */
    font: opentype.Font;
    /** Timestamp when font was loaded */
    loadedAt: number;
}
/**
 * Error thrown when font loading fails from all available URLs
 */
export declare class FontLoadError extends Error {
    /** Name of the font that failed to load */
    fontName: string;
    /** All URLs that were attempted */
    attemptedUrls: string[];
    /** The last error encountered */
    lastError?: Error | undefined;
    constructor(message: string, 
    /** Name of the font that failed to load */
    fontName: string, 
    /** All URLs that were attempted */
    attemptedUrls: string[], 
    /** The last error encountered */
    lastError?: Error | undefined);
}
/**
 * Error thrown when font loading exceeds the timeout limit
 */
export declare class FontTimeoutError extends Error {
    constructor(fontName: string, timeoutMs: number);
}
/**
 * FontResolver handles loading fonts from CDNs with caching and fallback support
 */
export declare class FontResolver {
    private fontCache;
    private loadingPromises;
    static readonly AVAILABLE_FONTS: FontInfo[];
    constructor();
    /**
     * Get list of available font names
     * @returns Array of font names that can be loaded
     */
    getAvailableFonts(): string[];
    /**
     * Load a font by name with caching and fallback support
     *
     * @param fontName - Name of the font to load (must be in registry)
     * @returns Promise that resolves to the loaded font
     * @throws {FontLoadError} When font loading fails from all URLs
     * @throws {FontTimeoutError} When font loading exceeds timeout
     * @throws {Error} When font is not found in registry
     */
    loadFont(fontName: string): Promise<LoadedFont>;
    /**
     * Load a font from a URL with fallback support
     */
    private loadFontFromUrl;
    /**
     * Load a font from a single URL with timeout handling
     */
    private loadSingleUrl;
    /**
     * Load font in browser environment using fetch
     */
    private loadFontInBrowser;
    /**
     * Load font in Node.js environment
     */
    private loadFontInNode;
    /**
     * Detect if we're running in a browser environment
     */
    private isBrowser;
    /**
     * Clear font cache
     */
    clearCache(): void;
    /**
     * Get cache status
     */
    getCacheStatus(): {
        fontName: string;
        loadedAt: Date;
        family: string;
    }[];
}
export declare const fontResolver: FontResolver;
//# sourceMappingURL=font-resolver.d.ts.map