@widgetic/editor 3.11.4 → 4.0.2

package/dist/utils/FontManager.js

@@ -0,0 +1,1302 @@
+import { fontUtils, fontCategories } from "./fontUtils";
+import FontFaceObserver from 'fontfaceobserver';
+import { shouldSkipFont } from './skipFonts';
+import fontsJson from '../assets/fonts.json';
+import { deleteKvValue, readKvValue, writeKvValue } from '@widgetic/cache-layer';
+const fontWeightOrder = {
+    Thin: 1,
+    ExtraLight: 2,
+    Light: 3,
+    Regular: 4,
+    Medium: 5,
+    SemiBold: 6,
+    Bold: 7,
+    ExtraBold: 8,
+    Black: 9,
+};
+/** Maps Google Fonts API variant ids to display weight labels. */
+export function mapGoogleVariantIdsToWeightNames(variants) {
+    return variants
+        .filter((v) => !v.includes('italic'))
+        .map((v) => {
+        switch (v) {
+            case '100':
+                return 'Thin';
+            case '200':
+                return 'ExtraLight';
+            case '300':
+                return 'Light';
+            case '400':
+            case 'regular':
+                return 'Regular';
+            case '500':
+                return 'Medium';
+            case '600':
+                return 'SemiBold';
+            case '700':
+            case 'bold':
+                return 'Bold';
+            case '800':
+                return 'ExtraBold';
+            case '900':
+                return 'Black';
+            default:
+                return v;
+        }
+    })
+        .sort((a, b) => (fontWeightOrder[a] || 99) - (fontWeightOrder[b] || 99));
+}
+class FontManager {
+    // Debug configuration
+    static DEBUG_MODE = false;
+    static WAIT_TIME = FontManager.DEBUG_MODE ? 2500 : 250;
+    // Singleton instance
+    static instance = null;
+    // Track loaded and pending fonts to prevent duplicates
+    loadedFonts = new Set();
+    // Map of intersection observers keyed by container ID
+    observers = new Map();
+    // Debounce timer for scroll events
+    scrollTimeout = null;
+    // Google Fonts API key
+    apiKey;
+    // Cache promise to prevent multiple simultaneous API calls
+    fontListPromise = null;
+    /**
+     * Catalog lifecycle as an explicit union. Replaces the former
+     * `initialFontsLoaded`/`allFontsLoaded` boolean pair whose ordering
+     * ('initial' must precede 'complete') was only convention. Only the
+     * 'complete' stage is ever persisted to the durable cache, preventing
+     * partial catalogs from being written.
+     */
+    catalog = { stage: 'empty' };
+    /** Current catalog contents regardless of stage (empty until loaded). */
+    get catalogFonts() {
+        return this.catalog.stage === 'empty' ? [] : this.catalog.fonts;
+    }
+    // Cache configuration — the font catalog is global (not user-owned), so it
+    // lives in the L1 kv table without an owner prefix.
+    static CACHE_KEY = 'fonts.catalog';
+    // Controls how long we keep the font list in the durable L1 store
+    static CACHE_DURATION = 24 * 60 * 60 * 1000; // 24 hours
+    static LOADED_FONTS_KEY = 'fonts.loaded';
+    // Legacy localStorage keys read once for migration
+    static LEGACY_CACHE_KEY = 'google_fonts_cache';
+    static LEGACY_LOADED_FONTS_KEY = 'loaded_fonts_cache';
+    // Controls how long browsers should cache the actual font files and stylesheets
+    static CACHE_CONTROL = 'public, max-age=31536000'; // 1 year
+    // Add new property to store visible fonts
+    visibleFonts = new Set();
+    static initialPreloadComplete = false;
+    static preloadPromise = null;
+    completeFontList = [];
+    // Add new property to track initialization
+    static isInitialized = false;
+    static initialFontNumber = 8; // 8 - how many fonts to load initially
+    // Add a static property to track initialization state
+    static initializationPromise = null;
+    // Add this property
+    remainingTime = 0;
+    // Add a Map to store pre-initialized observers
+    preInitializedObservers = new Map();
+    // Add batch size constant
+    static BATCH_SIZE = 100;
+    currentBatchIndex = FontManager.initialFontNumber; // Start after initial fonts
+    // Add a map to track batch indices per controller
+    batchIndices = new Map();
+    // Add a map to store preloaded fonts per category
+    categoryFonts = new Map();
+    // Add to existing properties
+    customFonts = new Map();
+    static missingApiKeyWarned = false;
+    static forbiddenApiKeyWarned = false;
+    static badRequestApiKeyWarned = false;
+    catalogFetchPromise = null;
+    /** Popular Google families shown when the Web Fonts API key is missing or blocked. */
+    static getFallbackCatalog() {
+        const sans = ['Inter', 'Roboto', 'Open Sans', 'Poppins', 'Lato', 'Montserrat', 'Nunito', 'Source Sans 3', 'Work Sans', 'DM Sans'];
+        const serif = ['Playfair Display', 'Merriweather', 'Libre Baskerville', 'Lora', 'Cormorant Garamond'];
+        const script = ['Dancing Script', 'Pacifico', 'Great Vibes'];
+        const other = ['Oswald', 'Raleway', 'Space Grotesk'];
+        const pack = (families, category) => families.map((family) => ({
+            family,
+            category,
+            isCustom: false,
+            variants: ['regular', '500', '600', '700'],
+        }));
+        return [
+            ...pack(sans, 'Sans Serif'),
+            ...pack(serif, 'Serif'),
+            ...pack(script, 'Script'),
+            ...pack(other, 'Other'),
+        ];
+    }
+    hasGoogleFontsApiKey() {
+        return Boolean(this.apiKey?.trim());
+    }
+    warnMissingApiKey() {
+        if (FontManager.missingApiKeyWarned)
+            return;
+        FontManager.missingApiKeyWarned = true;
+        console.warn('[FontManager] Google Fonts API key is missing. Set PUBLIC_GOOGLE_FONTS_API_KEY in Frontend/props-editor/.env ' +
+            '(or VITE_GOOGLE_FONTS_API_KEY in widget-creator/.env when using the embedded editor), then restart the dev server.');
+    }
+    warnForbiddenApiKey() {
+        if (FontManager.forbiddenApiKeyWarned)
+            return;
+        FontManager.forbiddenApiKeyWarned = true;
+        console.warn('[FontManager] Google Fonts API returned 403 Forbidden. Fix in Google Cloud Console: ' +
+            '(1) Enable "Web Fonts Developer API" on the project, ' +
+            '(2) API key → Application restrictions → HTTP referrers: http://localhost:5180/*, http://localhost:5174/*, http://127.0.0.1:5180/*, https://*.widgetic.com/*, ' +
+            '(3) use a key created for Web Fonts (not Gemini/other APIs). Font picker falls back to cached/custom fonts.');
+    }
+    warnBadRequestApiKey() {
+        if (FontManager.badRequestApiKeyWarned)
+            return;
+        FontManager.badRequestApiKeyWarned = true;
+        console.warn('[FontManager] Google Fonts API returned 400 Bad Request. Usually: invalid API key, Web Fonts Developer API not enabled, or wrong key type. ' +
+            'Use the "Widgetic-Fonts" key from Google Cloud (Web Fonts API only), set VITE_GOOGLE_FONTS_API_KEY in widget-creator/.env, restart dev server. ' +
+            'Font picker falls back to cached/custom fonts.');
+    }
+    /**
+     * Fetches the full Google Fonts catalog (Web Fonts Developer API).
+     * Returns null when key is missing or the request fails — callers use cache/custom fonts.
+     */
+    async fetchGoogleFontsCatalog() {
+        if (!this.catalogFetchPromise) {
+            this.catalogFetchPromise = this.fetchGoogleFontsCatalogOnce();
+        }
+        return this.catalogFetchPromise;
+    }
+    async fetchGoogleFontsCatalogOnce() {
+        if (!this.hasGoogleFontsApiKey()) {
+            this.warnMissingApiKey();
+            return null;
+        }
+        try {
+            const response = await fetch(`https://www.googleapis.com/webfonts/v1/webfonts?key=${this.apiKey}&sort=popularity&fields=items(family,category,variants)&prettyPrint=false`);
+            if (!response.ok) {
+                if (response.status === 403) {
+                    this.warnForbiddenApiKey();
+                }
+                else if (response.status === 400) {
+                    this.warnBadRequestApiKey();
+                }
+                else {
+                    console.warn('[FontManager] Google Fonts API request failed:', response.status, response.statusText);
+                }
+                return null;
+            }
+            const data = await response.json();
+            const filteredItems = (data.items || []).filter((font) => !shouldSkipFont(font.family));
+            return filteredItems.map((font) => ({
+                family: font.family,
+                category: fontCategories.normalize(font.category) || this.categorizeFont(font.family),
+                isCustom: false,
+                variants: font.variants,
+            }));
+        }
+        catch (error) {
+            console.warn('[FontManager] Google Fonts API fetch error:', error);
+            return null;
+        }
+    }
+    /** Variant ids from cached catalog (avoids per-font API calls). */
+    getGoogleFontVariantIds(family) {
+        const normalized = family.trim().toLowerCase();
+        const match = this.catalogFonts.find((f) => f.family.toLowerCase() === normalized) ||
+            this.completeFontList.find((f) => f.family.toLowerCase() === normalized);
+        return match?.variants?.length ? match.variants : null;
+    }
+    /**
+     * Private constructor to enforce singleton pattern
+     * @param apiKey - Google Fonts API key
+     */
+    constructor(apiKey) {
+        this.apiKey = apiKey; // Initialize apiKey in constructor
+        // console.log('🏗️ [FontManager] Creating FontManager instance...');
+    }
+    /**
+     * Gets or creates the singleton instance and initializes it
+     */
+    static async getInstance(apiKey) {
+        if (!FontManager.instance) {
+            FontManager.instance = new FontManager(apiKey);
+            // Initialize only once
+            if (!FontManager.initializationPromise) {
+                FontManager.initializationPromise = FontManager.instance.initialize();
+            }
+            // Wait for initialization to complete
+            await FontManager.initializationPromise;
+        }
+        return FontManager.instance;
+    }
+    /**
+     * Initializes the FontManager with initial fonts and setup
+     */
+    async initialize() {
+        if (FontManager.isInitialized) {
+            console.log('✅ [FontManager] Already initialized');
+            return;
+        }
+        try {
+            // console.log('🚀 [FontManager] Starting initialization...');
+            // Load custom fonts first, before any other font operations
+            const customFonts = await this.loadCustomFonts();
+            // console.log('✅ [FontManager] Loaded custom fonts:', customFonts.length);
+            // First check browser's cached fonts
+            const cachedFonts = await this.getBrowserCachedFonts();
+            // console.log('📦 [FontManager] Browser cached fonts:', {
+            //   total: cachedFonts.length,
+            //   fonts: cachedFonts
+            // });
+            // Add cached fonts to loadedFonts set
+            cachedFonts.forEach(font => this.loadedFonts.add(font));
+            // Save to localStorage for persistence
+            this.saveLoadedFonts();
+            // Get recent fonts first
+            const recentFonts = fontUtils.getRecentFonts()
+                .filter(font => !shouldSkipFont(font.family))
+                .map(font => ({
+                family: font.family,
+                category: fontCategories.normalize(font.category) || this.categorizeFont(font.family)
+            }));
+            // Get initial font list and cache it
+            const initialFontList = await this.getInitialFontList();
+            // console.log('📋 [FontManager] Initial font list loaded:', initialFontList.length);
+            // Cache the complete font list (skip duplicate fetch if getInitialFontList already loaded catalog)
+            try {
+                const catalog = this.catalogFonts.length > 0 && this.catalog.stage !== 'empty'
+                    ? this.catalogFonts
+                    : await this.fetchGoogleFontsCatalog();
+                if (catalog?.length) {
+                    this.catalog = { stage: 'complete', fonts: catalog };
+                    // Preload initial fonts for each category
+                    const categories = ['Serif', 'Sans Serif', 'Script', 'Other'];
+                    // Preload fonts for each category
+                    await Promise.all(categories.map(async (category) => {
+                        const categoryFonts = this.catalogFonts
+                            .filter(font => fontCategories.normalize(font.category) === category)
+                            .slice(0, FontManager.initialFontNumber);
+                        this.categoryFonts.set(category, categoryFonts);
+                        // Preload the fonts by inserting their stylesheets
+                        await Promise.all(categoryFonts.map(async (font) => {
+                            try {
+                                await this.insertFontStylesheet(font.family);
+                                await this.loadFont(font.family, ['400', '500', '600', '700']);
+                            }
+                            catch (error) {
+                                console.warn(`⚠️ [FontManager] Failed to preload font: ${font.family}`, error);
+                            }
+                        }));
+                        // console.log(`📚 [FontManager] Preloaded fonts for ${category}:`, {
+                        //   total: categoryFonts.length,
+                        //   sample: categoryFonts.slice(0, 3).map(f => f.family)
+                        // });
+                    }));
+                    // Save filtered list to localStorage cache
+                    this.saveFontListToCache(this.catalogFonts);
+                    // console.log('📚 [FontManager] Complete font list cached:', {
+                    //   total: this.cachedFontList.length,
+                    //   categoriesPreloaded: Array.from(this.categoryFonts.keys())
+                    // });
+                }
+            }
+            catch (error) {
+                // console.error('❌ [FontManager] Error caching complete font list:', error);
+            }
+            // Define initial fonts that must be loaded (excluding skipped fonts)
+            const initialFonts = [
+                'Roboto', 'Open Sans', 'Montserrat', 'Poppins',
+                'Lato', 'Inter'
+            ].filter(font => !shouldSkipFont(font));
+            // Add popular fonts from the initial list
+            const popularFonts = initialFontList
+                .slice(0, FontManager.initialFontNumber)
+                .map(font => font.family)
+                .filter(family => !initialFonts.includes(family));
+            // Combine all fonts to preload: initial fonts + recent fonts + popular fonts
+            const fontsToLoad = [...new Set([
+                    ...initialFonts,
+                    ...recentFonts.map(font => font.family),
+                    ...popularFonts
+                ])].filter(font => !this.loadedFonts.has(font));
+            if (fontsToLoad.length > 0) {
+                // console.log('🔄 [FontManager] Preloading fonts:', fontsToLoad);
+                // Load all fonts in parallel with all weights
+                const loadPromises = fontsToLoad.map(async (family) => {
+                    try {
+                        await this.insertFontStylesheet(family);
+                        await this.loadFont(family, ['400', '500', '600', '700']);
+                    }
+                    catch (error) {
+                        console.warn(`⚠️ [FontManager] Failed to load font: ${family}`, error);
+                    }
+                });
+                await Promise.all(loadPromises);
+            }
+            else {
+                console.log('✨ [FontManager] All initial fonts already cached');
+            }
+            // Only set initialized after everything is complete
+            FontManager.isInitialized = true;
+            // console.log('✅ [FontManager] Initialization complete. Font status:', {
+            //   totalLoaded: this.loadedFonts.size,
+            //   loadedFonts: Array.from(this.loadedFonts),
+            //   cachedFonts: this.cachedFontList.length
+            // });
+            // Pre-initialize observers for font controllers
+            this.preInitializeObservers();
+        }
+        catch (error) {
+            console.error('❌ [FontManager] Initialization failed:', error);
+            throw error;
+        }
+    }
+    /**
+     * Pre-initializes observers during FontManager initialization
+     */
+    preInitializeObservers() {
+        // Create a default observer configuration
+        const observerConfig = {
+            root: null,
+            rootMargin: '50px',
+            threshold: 0
+        };
+        // Create and store the observer
+        const observer = new IntersectionObserver((entries) => {
+            entries.forEach(entry => {
+                const fontFamily = entry.target.getAttribute('data-font');
+                if (fontFamily) {
+                    if (entry.isIntersecting) {
+                        this.addVisibleFont(fontFamily);
+                        if (!this.isScrolling()) {
+                            this.loadInitialVisibleFonts();
+                        }
+                    }
+                    else {
+                        this.removeVisibleFont(fontFamily);
+                    }
+                }
+            });
+        }, observerConfig);
+        // Store it with a default key
+        this.preInitializedObservers.set('default', observer);
+    }
+    /**
+     * Gets a pre-initialized observer
+     */
+    getPreInitializedObserver() {
+        return this.preInitializedObservers.get('default') || null;
+    }
+    /**
+     * Loads previously cached fonts from the durable L1 store (legacy localStorage fallback)
+     */
+    async loadCachedFonts() {
+        try {
+            let cachedLoadedFonts = await readKvValue(FontManager.LOADED_FONTS_KEY);
+            if (!cachedLoadedFonts) {
+                const legacyRaw = localStorage.getItem(FontManager.LEGACY_LOADED_FONTS_KEY);
+                if (legacyRaw) {
+                    try {
+                        cachedLoadedFonts = JSON.parse(legacyRaw);
+                        await writeKvValue(FontManager.LOADED_FONTS_KEY, cachedLoadedFonts);
+                    }
+                    catch {
+                        /* ignore malformed legacy data */
+                    }
+                    localStorage.removeItem(FontManager.LEGACY_LOADED_FONTS_KEY);
+                }
+            }
+            if (cachedLoadedFonts && Array.isArray(cachedLoadedFonts)) {
+                // Only load the first fonts initially
+                const initialFonts = cachedLoadedFonts.slice(0, FontManager.initialFontNumber);
+                const loadPromises = initialFonts.map(async (font) => {
+                    const family = typeof font === 'string' ? font : font.family;
+                    if (family) {
+                        try {
+                            await this.loadFont(family, ['400', '500', '600', '700']);
+                        }
+                        catch (error) {
+                            console.warn(`⚠️ [FontManager] Failed to load cached font: ${family}`, error);
+                        }
+                    }
+                });
+                await Promise.all(loadPromises);
+            }
+            // console.log('📊 [FontManager] Initial cache initialization complete:', {
+            //   loadedFontsSize: this.loadedFonts.size,
+            //   loadedFontsList: Array.from(this.loadedFonts)
+            // });
+        }
+        catch (error) {
+            console.error('❌ [FontManager] Error loading cached fonts:', error);
+        }
+    }
+    /**
+     * Saves the current state of loaded fonts to the durable L1 store
+     */
+    saveLoadedFonts() {
+        try {
+            const fontsToCache = Array.from(this.loadedFonts);
+            void writeKvValue(FontManager.LOADED_FONTS_KEY, fontsToCache);
+            // Add cache control headers for font files
+            const styleSheets = document.querySelectorAll('link[href*="fonts.googleapis.com"]');
+            styleSheets.forEach(sheet => {
+                if (sheet instanceof HTMLLinkElement) {
+                    sheet.setAttribute('crossorigin', 'anonymous');
+                    // Add cache control header through meta tag since we can't directly set headers
+                    const meta = document.createElement('meta');
+                    meta.setAttribute('http-equiv', 'Cache-Control');
+                    meta.setAttribute('content', FontManager.CACHE_CONTROL);
+                    document.head.appendChild(meta);
+                }
+            });
+        }
+        catch (error) {
+            console.error('❌ [FontManager] Error saving loaded fonts:', error);
+        }
+    }
+    /**
+     * Gets the stylesheet href for a font family with optimized parameters
+     */
+    getFontStylesheetHref(family) {
+        try {
+            const encodedFamily = encodeURIComponent(String(family).trim());
+            // Use text parameter to only load needed characters
+            const text = encodeURIComponent('ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789.,!?@#$%^&*()');
+            return `https://fonts.googleapis.com/css2?family=${encodedFamily}:wght@400;500;600;700&display=swap&text=${text}`;
+        }
+        catch (error) {
+            console.error('Error creating font stylesheet href:', error);
+            return '';
+        }
+    }
+    /**
+     * Checks if a font is available in Google Fonts
+     */
+    async isGoogleFont(family) {
+        // Ensure we have the complete font list
+        if (this.completeFontList.length === 0) {
+            const catalog = await this.fetchGoogleFontsCatalog();
+            if (catalog?.length) {
+                this.completeFontList = catalog;
+            }
+        }
+        return this.completeFontList.some(font => font.family.toLowerCase() === family.toLowerCase());
+    }
+    /**
+     * Inserts a font stylesheet into the document
+     * @param family - Font family name
+     * @param subset - Whether to use text subsetting (for preview)
+     */
+    async insertFontStylesheet(family, subset = true) {
+        try {
+            // Skip if already loaded with full character set
+            const fullFontLink = document.querySelector(`link[href*="${encodeURIComponent(family)}"][data-full-font="true"]`);
+            if (fullFontLink) {
+                return;
+            }
+            // Skip Google Fonts API for custom fonts
+            if (this.isCustomFont(family)) {
+                return;
+            }
+            // Add preconnect for Google Fonts
+            if (!document.querySelector('link[href="https://fonts.gstatic.com"][rel="preconnect"]')) {
+                const preconnect = document.createElement('link');
+                preconnect.rel = 'preconnect';
+                preconnect.href = 'https://fonts.gstatic.com';
+                preconnect.crossOrigin = 'anonymous';
+                document.head.appendChild(preconnect);
+            }
+            // Build URL based on whether we want subset or full font
+            const baseUrl = `https://fonts.googleapis.com/css2?family=${encodeURIComponent(family)}:wght@400&display=swap`;
+            const url = subset
+                ? `${baseUrl}&text=${encodeURIComponent('ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789')}`
+                : baseUrl;
+            const finalUrl = `${url}&capability=WOFF2`;
+            // Create and append stylesheet link first
+            const link = document.createElement('link');
+            link.rel = 'stylesheet';
+            link.href = finalUrl;
+            link.crossOrigin = 'anonymous';
+            if (!subset) {
+                link.setAttribute('data-full-font', 'true');
+            }
+            // Add to document
+            document.head.appendChild(link);
+            // Add preload hint with correct attributes after stylesheet
+            const preloadLink = document.createElement('link');
+            preloadLink.rel = 'preload';
+            preloadLink.as = 'style'; // Changed from 'font' to 'style'
+            preloadLink.href = finalUrl;
+            preloadLink.crossOrigin = 'anonymous';
+            preloadLink.setAttribute('onload', "this.onload=null;this.rel='stylesheet'");
+            document.head.appendChild(preloadLink);
+            // Wait for stylesheet to load
+            await new Promise((resolve, reject) => {
+                link.onload = () => resolve();
+                link.onerror = () => reject(new Error(`Failed to load stylesheet for ${family}`));
+                // Add a timeout to prevent hanging
+                setTimeout(resolve, 3000);
+            });
+        }
+        catch (error) {
+            console.warn(`⚠️ [FontManager] Error inserting stylesheet for ${family}, continuing anyway:`, error);
+        }
+    }
+    /**
+     * Loads a font with full character set
+     */
+    async loadFullFont(family) {
+        try {
+            // Skip if it's a custom font
+            if (this.isCustomFont(family)) {
+                return;
+            }
+            // console.log(`📥 [FontManager] Loading full font: ${family}`);
+            await this.insertFontStylesheet(family, false);
+            // Remove any subset version
+            const subsetLink = document.querySelector(`link[href*="${encodeURIComponent(family)}"][data-full-font="false"]`);
+            if (subsetLink) {
+                subsetLink.remove();
+            }
+        }
+        catch (error) {
+            console.error(`❌ [FontManager] Error loading full font: ${family}`, error);
+        }
+    }
+    /**
+     * Checks if a font is in the initial fonts list
+     */
+    isInitialFont(family) {
+        const initialFonts = ['Roboto', 'Open Sans', 'Montserrat', 'Poppins', 'Lato', 'Inter', 'Material Icons'];
+        return initialFonts.includes(family);
+    }
+    /**
+     * Checks if a font is in the browser cache
+     */
+    async checkFontInBrowserCache(family) {
+        try {
+            const href = this.getFontStylesheetHref(family);
+            const response = await fetch(href, {
+                method: 'HEAD',
+                cache: 'force-cache'
+            });
+            // Check if response came from browser cache
+            const fromCache = response.headers.get('cf-cache-status') === 'HIT' ||
+                response.headers.get('x-cache') === 'HIT' ||
+                response.headers.get('age') !== null;
+            return fromCache;
+        }
+        catch (error) {
+            console.warn('⚠️ [FontManager] Error checking browser cache:', error);
+            return false;
+        }
+    }
+    /**
+     * Maps Google Fonts categories to our simplified category system
+     * @param category - The category from Google Fonts API
+     * @returns Simplified category name
+     */
+    mapCategory(category) {
+        switch (category?.toLowerCase()) {
+            case 'serif':
+                return 'Serif';
+            case 'sans-serif':
+                return 'Sans Serif';
+            case 'handwriting':
+            case 'display':
+                return 'Script';
+            case 'monospace':
+            default:
+                return 'Other';
+        }
+    }
+    /**
+     * Ensures fonts are sorted by popularity
+     */
+    ensureFontSorting(fonts) {
+        // Keep original order from Google Fonts API as it's already sorted by popularity
+        return fonts;
+    }
+    /**
+     * Gets initial font list (initial number of fonts + recent fonts)
+     * @returns Promise resolving to initial font list
+     */
+    async getInitialFontList() {
+        try {
+            if (this.catalog.stage !== 'empty') {
+                return this.catalogFonts;
+            }
+            // Load recent fonts first (keep existing code)
+            const recentFonts = fontUtils.getRecentFonts()
+                .filter(font => !shouldSkipFont(font.family))
+                .map(font => ({
+                family: font.family,
+                category: fontCategories.normalize(font.category),
+                isCustom: font.isCustom
+            }));
+            // Add custom fonts from fonts.json
+            const customFonts = await this.loadCustomFonts();
+            const catalog = await this.fetchGoogleFontsCatalog();
+            const googleFonts = (catalog && catalog.length > 0) ? catalog : FontManager.getFallbackCatalog();
+            // Combine all fonts. A full Google catalog means the list is already
+            // complete; otherwise keep the 'initial' stage so a later fetch can
+            // still upgrade it.
+            const fonts = [
+                ...recentFonts,
+                ...customFonts,
+                ...googleFonts.filter((font) => !recentFonts.some((recent) => recent.family === font.family) &&
+                    !customFonts.some((custom) => custom.family === font.family))
+            ];
+            this.catalog = catalog?.length
+                ? { stage: 'complete', fonts }
+                : { stage: 'initial', fonts };
+            return this.catalogFonts;
+        }
+        catch (error) {
+            console.error('Error getting initial fonts:', error);
+            return FontManager.getFallbackCatalog();
+        }
+    }
+    /**
+     * Saves font list to the durable L1 cache.
+     * Only 'complete' catalogs are persisted — a partial ('initial') catalog
+     * written here used to be served for the full 24h cache duration.
+     */
+    saveFontListToCache(fonts) {
+        try {
+            if (this.catalog.stage !== 'complete') {
+                console.warn('⚠️ [FontManager] Skipping cache write: catalog is not complete yet');
+                return;
+            }
+            const cacheData = {
+                timestamp: Date.now(),
+                fonts: fonts
+            };
+            void writeKvValue(FontManager.CACHE_KEY, cacheData);
+        }
+        catch (error) {
+            console.error('❌ [FontManager] Error caching font list:', error);
+        }
+    }
+    /**
+     * Gets font list from the durable L1 cache (legacy localStorage fallback)
+     */
+    async getFontListFromCache() {
+        try {
+            let cache = await readKvValue(FontManager.CACHE_KEY, FontManager.CACHE_DURATION);
+            if (!cache) {
+                const legacyRaw = localStorage.getItem(FontManager.LEGACY_CACHE_KEY);
+                if (legacyRaw) {
+                    try {
+                        cache = JSON.parse(legacyRaw);
+                    }
+                    catch {
+                        /* ignore malformed legacy data */
+                    }
+                    localStorage.removeItem(FontManager.LEGACY_CACHE_KEY);
+                }
+            }
+            if (!cache)
+                return null;
+            // Check if cache is expired
+            if (Date.now() - cache.timestamp > FontManager.CACHE_DURATION) {
+                console.log('⚠️ [FontManager] Cache expired, removing');
+                void deleteKvValue(FontManager.CACHE_KEY);
+                return null;
+            }
+            // console.log('📦 [FontManager] Using cached font list:', {
+            //   fonts: cache.fonts.length,
+            //   age: Math.round((now - cache.timestamp) / 1000 / 60) + ' minutes'
+            // });
+            return cache.fonts;
+        }
+        catch (error) {
+            console.error('❌ [FontManager] Error reading font cache:', error);
+            return null;
+        }
+    }
+    /**
+     * Gets complete font list (called when dropdown opens)
+     */
+    async getCompleteFontList(force = false) {
+        try {
+            if (this.catalog.stage === 'complete' && !force) {
+                return this.catalogFonts;
+            }
+            if (!force) {
+                const cachedFonts = await this.getFontListFromCache();
+                if (cachedFonts) {
+                    this.catalog = { stage: 'complete', fonts: cachedFonts };
+                    return cachedFonts;
+                }
+            }
+            this.fontListPromise = (async () => {
+                const catalog = await this.fetchGoogleFontsCatalog();
+                if (!catalog?.length) {
+                    return this.catalogFonts.length ? this.catalogFonts : [];
+                }
+                const allFonts = catalog;
+                this.catalog = { stage: 'complete', fonts: allFonts };
+                this.saveFontListToCache(allFonts);
+                // console.log('✅ [FontManager] Complete font list loaded:', {
+                //   total: allFonts.length,
+                //   filtered: data.items.length - allFonts.length,
+                //   format: 'WOFF2'
+                // });
+                return allFonts;
+            })();
+            return this.fontListPromise;
+        }
+        catch (error) {
+            console.error('❌ [FontManager] Error getting complete font list:', error);
+            return this.catalogFonts;
+        }
+    }
+    /**
+     * Preloads initial fonts with optimized loading strategy
+     * Returns existing promise if preload is in progress
+     */
+    async preloadInitialFonts() {
+        // Return existing promise if preload is in progress
+        if (FontManager.preloadPromise) {
+            return FontManager.preloadPromise;
+        }
+        // Return immediately if preload is already complete
+        if (FontManager.initialPreloadComplete) {
+            console.log('✅ [FontManager] Initial fonts already preloaded');
+            return;
+        }
+        // Create new preload promise
+        FontManager.preloadPromise = (async () => {
+            try {
+                console.log('🚀 [FontManager] Preloading initial fonts...');
+                const initialFonts = await this.getInitialFontList();
+                const loadPromises = initialFonts.map(font => {
+                    this.insertFontStylesheet(font.family);
+                    return this.loadFont(font.family);
+                });
+                await Promise.all(loadPromises);
+                FontManager.initialPreloadComplete = true;
+                console.log('✅ [FontManager] Initial fonts preloaded');
+            }
+            catch (error) {
+                console.error('❌ [FontManager] Error preloading initial fonts:', error);
+            }
+            finally {
+                FontManager.preloadPromise = null;
+            }
+        })();
+        return FontManager.preloadPromise;
+    }
+    /**
+     * Loads initial visible fonts
+     */
+    async loadInitialVisibleFonts() {
+        const visibleFonts = Array.from(this.visibleFonts);
+        // Get initial fonts list
+        const initialFonts = this.catalogFonts.slice(0, FontManager.initialFontNumber);
+        const initialFontFamilies = new Set(initialFonts.map(font => font.family));
+        // Filter visible fonts to only include those in the initial batch
+        const fontsToLoad = visibleFonts.filter(font => initialFontFamilies.has(font));
+        if (fontsToLoad.length > 0) {
+            // console.log('🔄 [FontManager] Loading initial visible fonts:', {
+            //   visible: visibleFonts.length,
+            //   toLoad: fontsToLoad.length,
+            //   initialBatchSize: initialFonts.length
+            // });
+            const loadPromises = fontsToLoad.map(async (family) => {
+                try {
+                    await this.loadFont(family, ['400', '500', '600', '700']);
+                }
+                catch (error) {
+                    console.warn(`⚠️ [FontManager] Failed to load font: ${family}`, error);
+                }
+            });
+            await Promise.all(loadPromises);
+        }
+    }
+    /**
+     * Creates or retrieves an intersection observer for a container
+     * @param container - The HTML element to observe
+     * @returns IntersectionObserver instance or null if container is invalid
+     */
+    getObserver(container) {
+        if (!container) {
+            console.warn('❌ [FontManager] No container provided for observer');
+            return null;
+        }
+        // Generate or retrieve unique ID for container
+        const key = container.dataset.observerId || `font-observer-${Math.random().toString(36).slice(2)}`;
+        container.dataset.observerId = key;
+        // Return existing observer if one exists
+        if (this.observers.has(key)) {
+            return this.observers.get(key) || null;
+        }
+        // Create new observer
+        // console.log('🔧 [FontManager] Creating new observer for container:', key);
+        const observer = new IntersectionObserver((entries) => {
+            entries.forEach(entry => {
+                const fontFamily = entry.target.getAttribute('data-font');
+                if (fontFamily) {
+                    if (entry.isIntersecting) {
+                        this.addVisibleFont(fontFamily);
+                        // Load initial fonts immediately when they become visible
+                        if (!this.isScrolling()) {
+                            this.loadInitialVisibleFonts();
+                        }
+                    }
+                    else {
+                        this.removeVisibleFont(fontFamily);
+                    }
+                }
+            });
+        }, {
+            root: container,
+            rootMargin: '50px' // Pre-load fonts slightly before they come into view
+        });
+        this.observers.set(key, observer);
+        return observer;
+    }
+    /**
+     * Gets the font sources for a given family, including fallbacks
+     * @param fontFamily - Font family name
+     * @returns CSS src string with font sources
+     */
+    getFontSources(fontFamily) {
+        try {
+            const encodedFamily = encodeURIComponent(fontFamily);
+            // Use Google Fonts CSS API instead of direct file access
+            return `url(https://fonts.googleapis.com/css2?family=${encodedFamily}&display=swap)`;
+        }
+        catch (error) {
+            console.error('Error generating font sources:', error);
+            return '';
+        }
+    }
+    /**
+     * Generates a complete @font-face declaration
+     * @param fontFamily - Font family name
+     * @param options - Font face configuration options
+     * @returns Complete @font-face CSS rule
+     */
+    generateFontFaceRule(fontFamily, options = {}) {
+        const weight = options.weight || 'normal';
+        const style = options.style || 'normal';
+        return `
+      @font-face {
+        font-family: '${fontFamily}';
+        src: ${this.getFontSources(fontFamily)};
+        font-weight: ${weight};
+        font-style: ${style};
+        font-display: swap;
+      }
+    `;
+    }
+    /**
+     * Loads a font with specified weights using FontFaceObserver
+     * Simplified version with better error handling
+     */
+    async loadFont(family, weights = ['400']) {
+        if (this.loadedFonts.has(family)) {
+            return;
+        }
+        try {
+            // First ensure the stylesheet is loaded
+            await this.insertFontStylesheet(family);
+            // Wait a bit for stylesheet to be properly processed
+            await new Promise(resolve => setTimeout(resolve, 100));
+            // Load only 400 weight initially for faster loading
+            const observer = new FontFaceObserver(family);
+            await observer.load(null, 3000); // Reduced timeout
+            // Mark as loaded after basic weight is loaded
+            this.loadedFonts.add(family);
+            this.saveLoadedFonts();
+            // Load additional weights in the background
+            if (weights.length > 1) {
+                Promise.all(weights
+                    .filter(weight => weight !== '400')
+                    .map(weight => {
+                    const observer = new FontFaceObserver(family, { weight });
+                    return observer.load(null, 3000).catch(err => {
+                        console.warn(`⚠️ [FontManager] Non-critical weight ${weight} failed for ${family}:`, err);
+                        return false;
+                    });
+                })).then(results => {
+                    const loadedCount = results.filter(Boolean).length;
+                    // console.log(`📦 [FontManager] Additional weights loaded for ${family}:`, loadedCount);
+                });
+            }
+            // console.log('✅ [FontManager] Font loaded successfully:', family);
+        }
+        catch (error) {
+            console.warn(`⚠️ [FontManager] Error loading font ${family}, falling back to system fonts:`, error);
+            // Still mark as loaded to prevent retries
+            this.loadedFonts.add(family);
+            this.saveLoadedFonts();
+        }
+    }
+    /**
+     * Handles scroll optimization for font loading
+     * Implements debouncing to prevent excessive font loading
+     * @param callback - Optional callback after fonts are loaded
+     */
+    handleScroll(callback) {
+        if (this.scrollTimeout) {
+            window.clearTimeout(this.scrollTimeout);
+            this.scrollTimeout = null;
+        }
+        this.remainingTime = FontManager.WAIT_TIME;
+        this.scrollTimeout = window.setTimeout(async () => {
+            const visibleFonts = Array.from(this.visibleFonts);
+            // console.log('🔄 [FontManager] Loading visible fonts:', {
+            //   total: visibleFonts.length,
+            //   fonts: visibleFonts
+            // });
+            try {
+                // Load all visible fonts in parallel
+                const loadPromises = visibleFonts.map(async (family) => {
+                    if (this.loadedFonts.has(family)) {
+                        const status = await this.verifyFontCache(family);
+                        if (!status.cached) {
+                            // console.log('⚠️ [FontManager] Reloading uncached font:', family);
+                            await this.insertFontStylesheet(family);
+                            return this.loadFont(family);
+                        }
+                        return Promise.resolve();
+                    }
+                    // console.log('📥 [FontManager] Loading new font:', family);
+                    await this.insertFontStylesheet(family);
+                    return this.loadFont(family);
+                });
+                await Promise.all(loadPromises);
+                // Log final cache status
+                const finalStatus = await Promise.all(visibleFonts.map(async (family) => ({
+                    font: family,
+                    status: await this.verifyFontCache(family)
+                })));
+                // console.log('✅ [FontManager] Font loading complete:', {
+                //   total: finalStatus.length,
+                //   fonts: finalStatus.map(({ font, status }) => ({
+                //     font,
+                //     cached: status.cached,
+                //     stylesheet: status.stylesheet,
+                //     fontFace: status.fontFace
+                //   }))
+                // });
+            }
+            catch (error) {
+                console.error('❌ [FontManager] Error loading fonts:', error);
+            }
+            this.visibleFonts.clear();
+            this.scrollTimeout = null;
+            if (callback)
+                callback();
+        }, FontManager.WAIT_TIME);
+    }
+    /**
+     * Checks if a font is already loaded
+     */
+    isFontLoaded(family) {
+        return this.loadedFonts.has(family);
+    }
+    /**
+     * Gets stats about loaded fonts
+     */
+    getLoadedFontsStats() {
+        return {
+            total: this.loadedFonts.size,
+            fonts: Array.from(this.loadedFonts)
+        };
+    }
+    /**
+     * Cleans up resources when a font container is removed
+     * Prevents memory leaks from orphaned observers
+     * @param containerId - ID of the container being cleaned up
+     */
+    cleanup(containerId) {
+        const observer = this.observers.get(containerId);
+        if (observer) {
+            observer.disconnect();
+            this.observers.delete(containerId);
+        }
+    }
+    /**
+     * Categorizes a font based on its family name
+     * Delegates to fontUtils for consistent categorization
+     * @param family - Font family name to categorize
+     */
+    categorizeFont(family) {
+        return fontUtils.categorizeFont(family);
+    }
+    // Add public method to check scroll state
+    isScrolling() {
+        return this.scrollTimeout !== null;
+    }
+    // Method to track fonts that become visible
+    addVisibleFont(fontFamily) {
+        if (!this.visibleFonts.has(fontFamily)) {
+            this.visibleFonts.add(fontFamily);
+            //   console.log(`👁️ [FontManager] Font visible: ${fontFamily}`);
+        }
+    }
+    removeVisibleFont(family) {
+        if (this.visibleFonts.has(family)) {
+            this.visibleFonts.delete(family);
+            // console.log('👋 [FontManager] Font hidden:', family);
+        }
+    }
+    /**
+     * Verifies if a font is actually cached in the browser
+     */
+    async verifyFontCache(family) {
+        const status = {
+            family,
+            cached: false,
+            headers: {},
+            stylesheet: false,
+            fontFace: false
+        };
+        try {
+            // Check the durable loaded-fonts registry (legacy localStorage fallback)
+            let cachedFonts = await readKvValue(FontManager.LOADED_FONTS_KEY);
+            if (!cachedFonts) {
+                const legacyRaw = localStorage.getItem(FontManager.LEGACY_LOADED_FONTS_KEY);
+                cachedFonts = legacyRaw ? JSON.parse(legacyRaw) : [];
+            }
+            const loadedFonts = Array.isArray(cachedFonts) ? cachedFonts : [];
+            const isCached = loadedFonts.includes(family);
+            // Check if stylesheet exists in DOM
+            status.stylesheet = !!document.querySelector(`link[href*="${encodeURIComponent(family)}"]`);
+            // Consider font loaded if it's both in localStorage and has a stylesheet
+            status.fontFace = isCached;
+            status.cached = status.stylesheet && status.fontFace;
+            // Set standard cache headers
+            status.headers = {
+                cacheControl: 'max-age=31536000', // 1 year
+                age: '0',
+                cfCache: null,
+                xCache: null
+            };
+            return status;
+        }
+        catch (error) {
+            console.warn('⚠️ [FontManager] Error verifying font cache:', family, error);
+            return status;
+        }
+    }
+    /**
+     * Gets list of fonts cached in browser with detailed status
+     */
+    async getBrowserCachedFonts() {
+        try {
+            // Get fonts from the durable loaded-fonts registry (legacy fallback)
+            let cachedFonts = await readKvValue(FontManager.LOADED_FONTS_KEY);
+            if (!cachedFonts) {
+                const legacyRaw = localStorage.getItem(FontManager.LEGACY_LOADED_FONTS_KEY);
+                cachedFonts = legacyRaw ? JSON.parse(legacyRaw) : [];
+            }
+            cachedFonts = Array.isArray(cachedFonts) ? cachedFonts : [];
+            // console.log('📦 [FontManager] Fonts in durable registry:', cachedFonts);
+            // Verify each font has its stylesheet in the DOM
+            const verifiedFonts = await Promise.all(cachedFonts.map(async (font) => {
+                const status = await this.verifyFontCache(font);
+                return { font, status };
+            }));
+            // Filter to only include fonts that are properly cached
+            const validCachedFonts = verifiedFonts
+                .filter(({ status }) => status.cached)
+                .map(({ font }) => font);
+            // console.log('✅ [FontManager] Valid cached fonts:', {
+            //   total: validCachedFonts.length,
+            //   fonts: validCachedFonts
+            // });
+            return validCachedFonts;
+        }
+        catch (error) {
+            console.error('❌ [FontManager] Error getting browser cached fonts:', error);
+            return [];
+        }
+    }
+    /**
+     * Gets the cached font list without making an API call
+     */
+    getCachedFontList() {
+        return this.catalogFonts;
+    }
+    /**
+     * Gets the next batch of fonts
+     */
+    getNextBatch(controllerId, category) {
+        // Get or initialize batch index for this controller
+        let currentIndex = this.batchIndices.get(controllerId) || FontManager.initialFontNumber;
+        // Filter fonts by category first
+        const categoryFonts = category === 'All'
+            ? this.catalogFonts
+            : category === 'Mine'
+                ? Array.from(this.customFonts.values())
+                : this.catalogFonts.filter(font => fontCategories.normalize(font.category) === category);
+        const start = currentIndex;
+        const end = start + FontManager.BATCH_SIZE;
+        // Get next batch from category-filtered list
+        const batch = categoryFonts.slice(start, end);
+        // Only update index if we actually got more fonts
+        if (batch.length > 0) {
+            this.batchIndices.set(controllerId, end);
+        }
+        // console.log('📦 [FontManager] Loading next batch:', {
+        //   controllerId,
+        //   category,
+        //   start,
+        //   end,
+        //   batchSize: batch.length,
+        //   totalInCategory: categoryFonts.length,
+        //   remainingFonts: categoryFonts.length - end
+        // });
+        return batch;
+    }
+    /**
+     * Checks if there are more fonts to load
+     */
+    hasMoreFonts(controllerId, category) {
+        const currentIndex = this.batchIndices.get(controllerId) || FontManager.initialFontNumber;
+        // Filter fonts by category first
+        const categoryFonts = category === 'All'
+            ? this.catalogFonts
+            : category === 'Mine'
+                ? Array.from(this.customFonts.values())
+                : this.catalogFonts.filter(font => fontCategories.normalize(font.category) === category);
+        const remainingItems = categoryFonts.length - currentIndex;
+        console.log('🔍 [FontManager] Checking remaining fonts:', {
+            category,
+            currentIndex,
+            totalInCategory: categoryFonts.length,
+            remainingItems
+        });
+        // Only return true if we have more items in this category
+        return remainingItems > 0;
+    }
+    /**
+     * Resets the batch index to initial number
+     * This allows each font input controller to start from the beginning
+     */
+    resetBatchIndex(controllerId) {
+        this.batchIndices.set(controllerId, FontManager.initialFontNumber);
+        // console.log('🔄 [FontManager] Reset batch index for:', controllerId);
+    }
+    // Add method to get preloaded fonts for a category
+    getPreloadedFonts(category) {
+        if (category === 'Mine') {
+            return Array.from(this.customFonts.values());
+        }
+        const preloadedFonts = this.categoryFonts.get(category) || [];
+        // Ensure fonts are loaded
+        preloadedFonts.forEach(font => {
+            if (!this.loadedFonts.has(font.family)) {
+                this.insertFontStylesheet(font.family)
+                    .then(() => this.loadFont(font.family, ['400']))
+                    .catch(error => console.warn(`⚠️ [FontManager] Failed to load font: ${font.family}`, error));
+            }
+        });
+        return preloadedFonts;
+    }
+    /**
+     * Gets the complete list of Google Fonts
+     * @returns Promise resolving to FontData array
+     */
+    async getGoogleFontsList() {
+        const catalog = await this.fetchGoogleFontsCatalog();
+        return catalog || [];
+    }
+    // Add new method to handle custom font removal
+    async removeCustomFont(family) {
+        try {
+            if (this.customFonts.has(family)) {
+                this.customFonts.delete(family);
+                this.loadedFonts.delete(family);
+                // Update cached font list
+                if (this.catalog.stage !== 'empty') {
+                    this.catalog = {
+                        ...this.catalog,
+                        fonts: this.catalog.fonts.filter(font => font.family !== family || font.category !== 'Mine'),
+                    };
+                }
+                console.log('✅ [FontManager] Custom font removed:', family);
+            }
+        }
+        catch (error) {
+            console.error('❌ [FontManager] Error removing custom font:', error);
+        }
+    }
+    async loadCustomFonts() {
+        try {
+            const fontsData = fontsJson;
+            const families = Array.isArray(fontsData.fontFamilies) ? fontsData.fontFamilies : [];
+            const customFonts = [];
+            for (const familyData of families) {
+                try {
+                    const fontData = {
+                        family: familyData.family,
+                        category: 'Mine',
+                        isCustom: true
+                    };
+                    this.customFonts.set(familyData.family, fontData);
+                    customFonts.push(fontData);
+                    // Process each variant
+                    for (const variant of familyData.variants || []) {
+                        try {
+                            const isItalic = variant.weight.includes('Italic');
+                            // Skip local/relative font files — they only exist in standalone mode
+                            const fontUrl = variant.url;
+                            if (fontUrl.startsWith('/') && !fontUrl.startsWith('//')) {
+                                continue;
+                            }
+                            const fontFace = new FontFace(familyData.family, `url(${fontUrl})`, {
+                                style: isItalic ? 'italic' : 'normal',
+                                display: 'swap'
+                            });
+                            await document.fonts.add(fontFace);
+                            await fontFace.load();
+                            this.loadedFonts.add(familyData.family);
+                            // console.log(`✅ [FontManager] Added font face with swap:`, {
+                            //   family: familyData.family,
+                            //   weight: variant.weight,
+                            //   style: isItalic ? 'italic' : 'normal'
+                            // });
+                        }
+                        catch (error) {
+                            console.warn(`⚠️ [FontManager] Failed to add font face:`, {
+                                family: familyData.family,
+                                weight: variant.weight,
+                                error: error instanceof Error ? error.message : String(error)
+                            });
+                        }
+                    }
+                }
+                catch (error) {
+                    console.warn(`⚠️ [FontManager] Failed to load font family: ${familyData.family}`, error);
+                }
+            }
+            return customFonts;
+        }
+        catch (error) {
+            console.error('❌ [FontManager] Error loading custom fonts:', error);
+            return [];
+        }
+    }
+    /**
+     * Checks if a font is a custom font
+     */
+    isCustomFont(family) {
+        return this.customFonts.has(family);
+    }
+    /**
+     * Gets custom font data if available
+     */
+    getCustomFont(family) {
+        return this.customFonts.get(family);
+    }
+}
+export default FontManager;