@flightdev/fonts 0.0.2

package/dist/plugins/vite.js

@@ -0,0 +1,240 @@
+/**
+ * @flightdev/fonts - Vite Plugin for Font Optimization
+ *
+ * Build-time font optimization for Flight Framework.
+ * Features:
+ * - Automatic character extraction from source files
+ * - Unicode-range CSS generation for optimal subsetting
+ * - Self-hosting with cache busting
+ * - Development mode passthrough for fast iteration
+ *
+ * This is an OPTIONAL plugin. Developers can choose to use it or not.
+ */
+import { join } from 'node:path';
+import { extractCharsFromSource, charsToCodePoints, codePointsToUnicodeRange, getNamedSubsetRanges, detectRequiredSubsets, generateFontFaceCSS, } from '../subset';
+// ============================================================================
+// Vite Plugin
+// ============================================================================
+/**
+ * Vite plugin for font optimization.
+ *
+ * Usage:
+ * ```typescript
+ * // vite.config.ts
+ * import { fontOptimization } from '@flightdev/fonts/vite';
+ *
+ * export default defineConfig({
+ *     plugins: [
+ *         fontOptimization({
+ *             strategy: 'named-subsets',
+ *             subsets: ['latin', 'latin-ext'],
+ *             selfHost: true,
+ *         }),
+ *     ],
+ * });
+ * ```
+ */
+export function fontOptimization(options = {}) {
+    const { strategy = 'named-subsets', subsets = ['latin'], selfHost = true, outputDir = 'public/_fonts', scanDirs = ['src'], scanExtensions = ['.tsx', '.jsx', '.vue', '.svelte', '.astro', '.html'], excludePatterns = ['node_modules', 'dist', '.git'], generatePreloads = true, injectToHtml = true, verbose = true, } = options;
+    let config;
+    let isProduction = false;
+    let enabled = options.enabled;
+    let projectRoot = '';
+    let extractedChars = new Set();
+    let processedFonts = [];
+    // Track registered fonts from Flight's font loader
+    const registeredFonts = new Map();
+    return {
+        name: 'flight-font-optimization',
+        enforce: 'pre',
+        configResolved(resolvedConfig) {
+            config = resolvedConfig;
+            isProduction = resolvedConfig.command === 'build';
+            projectRoot = resolvedConfig.root;
+            // Enable by default only in production
+            if (enabled === undefined) {
+                enabled = isProduction;
+            }
+            if (verbose && enabled) {
+                console.log('[flight-fonts] Font optimization enabled');
+                console.log(`[flight-fonts] Strategy: ${strategy}`);
+            }
+        },
+        buildStart() {
+            if (!enabled)
+                return;
+            // Scan source files for used characters if using 'used-chars' strategy
+            if (strategy === 'used-chars') {
+                extractedChars = scanSourceFiles(projectRoot, scanDirs, scanExtensions, excludePatterns);
+                if (verbose) {
+                    console.log(`[flight-fonts] Extracted ${extractedChars.size} unique characters`);
+                    const detectedSubsets = detectRequiredSubsets(extractedChars);
+                    console.log(`[flight-fonts] Detected subsets: ${detectedSubsets.join(', ')}`);
+                }
+            }
+        },
+        transform(code, id) {
+            if (!enabled)
+                return null;
+            // Intercept font loader calls to track registered fonts
+            if (id.includes('@flightdev/fonts') || id.includes('fonts/src')) {
+                return null;
+            }
+            // Look for createFontLoader or fonts.load calls
+            if (code.includes('fonts.load(') || code.includes('.load(')) {
+                // This is a simple detection - in production, use AST parsing
+                const fontMatches = code.matchAll(/\.load\s*\(\s*['"]([^'"]+)['"]/g);
+                for (const match of fontMatches) {
+                    const fontFamily = match[1];
+                    if (!registeredFonts.has(fontFamily)) {
+                        registeredFonts.set(fontFamily, {
+                            family: fontFamily,
+                            weights: ['400'],
+                            styles: ['normal'],
+                            subsets: strategy === 'named-subsets' ? subsets : ['latin'],
+                            display: 'swap',
+                        });
+                    }
+                }
+            }
+            return null;
+        },
+        generateBundle() {
+            if (!enabled)
+                return;
+            // Generate optimized font CSS
+            for (const [family, fontDef] of registeredFonts) {
+                let unicodeRange;
+                switch (strategy) {
+                    case 'used-chars':
+                        const codePoints = charsToCodePoints(extractedChars);
+                        unicodeRange = codePointsToUnicodeRange(codePoints);
+                        break;
+                    case 'named-subsets':
+                        unicodeRange = getNamedSubsetRanges(fontDef.subsets);
+                        break;
+                    case 'none':
+                    default:
+                        unicodeRange = undefined;
+                }
+                // Generate CSS for each weight
+                const cssRules = [];
+                for (const weight of fontDef.weights) {
+                    for (const style of fontDef.styles) {
+                        const fontUrl = selfHost
+                            ? `/_fonts/${family.toLowerCase().replace(/\s/g, '-')}-${weight}.woff2`
+                            : `https://fonts.gstatic.com/s/${family.toLowerCase().replace(/\s/g, '')}/*/${weight}.woff2`;
+                        cssRules.push(generateFontFaceCSS(family, fontUrl, {
+                            weight,
+                            style,
+                            display: fontDef.display,
+                            unicodeRange,
+                        }));
+                    }
+                }
+                processedFonts.push({
+                    family,
+                    css: cssRules.join('\n'),
+                    unicodeRange,
+                    preloadLinks: generatePreloads ? generatePreloadLinks(family, fontDef.weights) : [],
+                });
+            }
+            if (verbose && processedFonts.length > 0) {
+                console.log(`[flight-fonts] Processed ${processedFonts.length} font families`);
+            }
+        },
+        transformIndexHtml(html) {
+            if (!enabled || !injectToHtml || processedFonts.length === 0) {
+                return html;
+            }
+            // Inject preload links and font CSS
+            const preloadTags = processedFonts
+                .flatMap(f => f.preloadLinks)
+                .join('\n');
+            const fontCSS = processedFonts
+                .map(f => f.css)
+                .join('\n');
+            // Insert before </head>
+            const headCloseIndex = html.indexOf('</head>');
+            if (headCloseIndex === -1)
+                return html;
+            const injection = `
+    <!-- Flight Font Optimization -->
+    ${preloadTags}
+    <style id="flight-fonts">
+${fontCSS}
+    </style>
+`;
+            return html.slice(0, headCloseIndex) + injection + html.slice(headCloseIndex);
+        },
+    };
+}
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Scan source files for used characters.
+ */
+function scanSourceFiles(projectRoot, scanDirs, extensions, excludePatterns) {
+    const chars = new Set();
+    // This is a simplified implementation
+    // In production, use glob or fast-glob for better performance
+    const scanDir = (dir) => {
+        try {
+            const fs = require('node:fs');
+            const path = require('node:path');
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry.name);
+                // Skip excluded patterns
+                if (excludePatterns.some(pattern => fullPath.includes(pattern))) {
+                    continue;
+                }
+                if (entry.isDirectory()) {
+                    scanDir(fullPath);
+                }
+                else if (entry.isFile()) {
+                    const ext = path.extname(entry.name);
+                    if (extensions.includes(ext)) {
+                        try {
+                            const content = fs.readFileSync(fullPath, 'utf-8');
+                            const fileType = ext.slice(1); // Remove the dot
+                            const fileChars = extractCharsFromSource(content, fileType);
+                            for (const char of fileChars) {
+                                chars.add(char);
+                            }
+                        }
+                        catch {
+                            // Skip files that can't be read
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // Directory doesn't exist or can't be read
+        }
+    };
+    for (const scanDirPath of scanDirs) {
+        const fullScanDir = join(projectRoot, scanDirPath);
+        scanDir(fullScanDir);
+    }
+    return chars;
+}
+/**
+ * Generate preload link tags for fonts.
+ */
+function generatePreloadLinks(family, weights) {
+    const links = [];
+    for (const weight of weights) {
+        const fontPath = `/_fonts/${family.toLowerCase().replace(/\s/g, '-')}-${weight}.woff2`;
+        links.push(`<link rel="preload" href="${fontPath}" as="font" type="font/woff2" crossorigin="anonymous">`);
+    }
+    return links;
+}
+// ============================================================================
+// Exports
+// ============================================================================
+// Types are exported at declaration above
+export default fontOptimization;
+//# sourceMappingURL=vite.js.map

package/dist/plugins/vite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.js","sourceRoot":"","sources":["../../src/plugins/vite.ts"],"names":[],"mappings":"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"}

package/dist/subset.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @flightdev/fonts - Font Subsetting Utilities
+ *
+ * Zero-dependency font subsetting for optimal Core Web Vitals.
+ * Extracts used characters and generates unicode-range CSS.
+ *
+ * For full font file subsetting, install fontkit as a peer dependency.
+ */
+/**
+ * Unicode range entry for CSS @font-face
+ */
+export interface UnicodeRange {
+    /** Range name for identification */
+    name: string;
+    /** CSS unicode-range value (e.g., 'U+0000-00FF') */
+    range: string;
+    /** Character set description */
+    description?: string;
+}
+/**
+ * Font subset configuration
+ */
+export interface FontSubsetConfig {
+    /** Strategy for determining which characters to include */
+    strategy: 'used-chars' | 'named-subsets' | 'custom' | 'none';
+    /** Named subsets to include (e.g., 'latin', 'latin-ext') */
+    subsets?: string[];
+    /** Custom characters to include */
+    customChars?: string;
+    /** Directories to scan for used characters */
+    scanDirs?: string[];
+    /** File extensions to scan */
+    scanExtensions?: string[];
+    /** Exclude patterns (glob) */
+    excludePatterns?: string[];
+}
+/**
+ * Result of character extraction
+ */
+export interface ExtractedChars {
+    /** Set of unique characters found */
+    chars: Set<string>;
+    /** Unicode code points */
+    codePoints: number[];
+    /** Generated unicode-range CSS value */
+    unicodeRange: string;
+    /** Files that were scanned */
+    scannedFiles: string[];
+}
+/**
+ * Standard unicode ranges matching Google Fonts subsets.
+ * These are the same ranges used by major font services.
+ */
+export declare const UNICODE_RANGES: Record<string, UnicodeRange>;
+/**
+ * Extract unique characters from text content.
+ *
+ * @param text - Text to extract characters from
+ * @returns Set of unique characters
+ */
+export declare function extractCharsFromText(text: string): Set<string>;
+/**
+ * Convert a set of characters to sorted code points.
+ */
+export declare function charsToCodePoints(chars: Set<string>): number[];
+/**
+ * Generate CSS unicode-range from code points.
+ *
+ * Groups consecutive code points into ranges for smaller CSS.
+ *
+ * @param codePoints - Sorted array of code points
+ * @returns CSS unicode-range value
+ */
+export declare function codePointsToUnicodeRange(codePoints: number[]): string;
+/**
+ * Get named unicode ranges for specified subsets.
+ *
+ * @param subsetNames - Array of subset names (e.g., ['latin', 'latin-ext'])
+ * @returns Combined unicode-range CSS value
+ */
+export declare function getNamedSubsetRanges(subsetNames: string[]): string;
+/**
+ * Detect which subsets are needed based on characters.
+ *
+ * @param chars - Set of characters to analyze
+ * @returns Array of subset names that cover the characters
+ */
+export declare function detectRequiredSubsets(chars: Set<string>): string[];
+/**
+ * Extract text content from source code.
+ * Used by the Vite plugin to find used characters.
+ *
+ * @param sourceCode - Source code content
+ * @param fileType - File extension (tsx, vue, svelte, etc.)
+ * @returns Set of unique characters
+ */
+export declare function extractCharsFromSource(sourceCode: string, fileType: string): Set<string>;
+/**
+ * Generate @font-face CSS with unicode-range.
+ *
+ * @param fontFamily - Font family name
+ * @param fontUrl - URL to font file
+ * @param options - Font face options
+ * @returns CSS @font-face rule
+ */
+export declare function generateFontFaceCSS(fontFamily: string, fontUrl: string, options?: {
+    weight?: string | number;
+    style?: string;
+    display?: string;
+    unicodeRange?: string;
+    format?: string;
+}): string;
+//# sourceMappingURL=subset.d.ts.map

package/dist/subset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subset.d.ts","sourceRoot":"","sources":["../src/subset.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B,2DAA2D;IAC3D,QAAQ,EAAE,YAAY,GAAG,eAAe,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC7D,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,mCAAmC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,8BAA8B;IAC9B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,8BAA8B;IAC9B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B,qCAAqC;IACrC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnB,0BAA0B;IAC1B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAC;IACrB,8BAA8B;IAC9B,YAAY,EAAE,MAAM,EAAE,CAAC;CAC1B;AAMD;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAuEvD,CAAC;AAMF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAa9D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAW9D;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,CAkCrE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,CAWlE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CA+BlE;AA2BD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAClC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACjB,GAAG,CAAC,MAAM,CAAC,CA+Cb;AAMD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAC/B,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IACL,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACd,GACP,MAAM,CAuBR"}

package/dist/subset.js

@@ -0,0 +1,315 @@
+/**
+ * @flightdev/fonts - Font Subsetting Utilities
+ *
+ * Zero-dependency font subsetting for optimal Core Web Vitals.
+ * Extracts used characters and generates unicode-range CSS.
+ *
+ * For full font file subsetting, install fontkit as a peer dependency.
+ */
+// ============================================================================
+// Predefined Unicode Ranges (Google Fonts subsets)
+// ============================================================================
+/**
+ * Standard unicode ranges matching Google Fonts subsets.
+ * These are the same ranges used by major font services.
+ */
+export const UNICODE_RANGES = {
+    latin: {
+        name: 'latin',
+        range: 'U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD',
+        description: 'Basic Latin characters',
+    },
+    'latin-ext': {
+        name: 'latin-ext',
+        range: 'U+0100-02AF, U+0304, U+0308, U+0329, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20CF, U+2113, U+2C60-2C7F, U+A720-A7FF',
+        description: 'Extended Latin characters',
+    },
+    cyrillic: {
+        name: 'cyrillic',
+        range: 'U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116',
+        description: 'Cyrillic characters',
+    },
+    'cyrillic-ext': {
+        name: 'cyrillic-ext',
+        range: 'U+0460-052F, U+1C80-1C88, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F',
+        description: 'Extended Cyrillic characters',
+    },
+    greek: {
+        name: 'greek',
+        range: 'U+0370-03FF',
+        description: 'Greek characters',
+    },
+    'greek-ext': {
+        name: 'greek-ext',
+        range: 'U+1F00-1FFF',
+        description: 'Extended Greek characters',
+    },
+    vietnamese: {
+        name: 'vietnamese',
+        range: 'U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301, U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB',
+        description: 'Vietnamese characters',
+    },
+    arabic: {
+        name: 'arabic',
+        range: 'U+0600-06FF, U+0750-077F, U+08A0-08FF, U+FB50-FDFF, U+FE70-FEFF',
+        description: 'Arabic characters',
+    },
+    hebrew: {
+        name: 'hebrew',
+        range: 'U+0590-05FF, U+200C-2010, U+20AA, U+25CC, U+FB1D-FB4F',
+        description: 'Hebrew characters',
+    },
+    devanagari: {
+        name: 'devanagari',
+        range: 'U+0900-097F, U+1CD0-1CF6, U+1CF8-1CF9, U+200C-200D, U+20A8, U+20B9, U+25CC, U+A830-A839, U+A8E0-A8FB',
+        description: 'Devanagari characters',
+    },
+    thai: {
+        name: 'thai',
+        range: 'U+0E01-0E5B, U+200C-200D, U+25CC',
+        description: 'Thai characters',
+    },
+    japanese: {
+        name: 'japanese',
+        range: 'U+3000-303F, U+3040-309F, U+30A0-30FF, U+FF00-FFEF, U+4E00-9FAF',
+        description: 'Japanese characters (Hiragana, Katakana, common Kanji)',
+    },
+    korean: {
+        name: 'korean',
+        range: 'U+AC00-D7AF, U+1100-11FF, U+3130-318F, U+A960-A97F, U+D7B0-D7FF',
+        description: 'Korean Hangul characters',
+    },
+    'chinese-simplified': {
+        name: 'chinese-simplified',
+        range: 'U+4E00-9FFF, U+3400-4DBF, U+20000-2A6DF',
+        description: 'Simplified Chinese characters',
+    },
+};
+// ============================================================================
+// Character Extraction
+// ============================================================================
+/**
+ * Extract unique characters from text content.
+ *
+ * @param text - Text to extract characters from
+ * @returns Set of unique characters
+ */
+export function extractCharsFromText(text) {
+    const chars = new Set();
+    // Use Array.from to properly handle Unicode surrogate pairs
+    for (const char of text) {
+        // Skip whitespace and common punctuation for more aggressive subsetting
+        const codePoint = char.codePointAt(0);
+        if (codePoint !== undefined && codePoint > 0x1F) {
+            chars.add(char);
+        }
+    }
+    return chars;
+}
+/**
+ * Convert a set of characters to sorted code points.
+ */
+export function charsToCodePoints(chars) {
+    const codePoints = [];
+    for (const char of chars) {
+        const cp = char.codePointAt(0);
+        if (cp !== undefined) {
+            codePoints.push(cp);
+        }
+    }
+    return codePoints.sort((a, b) => a - b);
+}
+/**
+ * Generate CSS unicode-range from code points.
+ *
+ * Groups consecutive code points into ranges for smaller CSS.
+ *
+ * @param codePoints - Sorted array of code points
+ * @returns CSS unicode-range value
+ */
+export function codePointsToUnicodeRange(codePoints) {
+    if (codePoints.length === 0) {
+        return '';
+    }
+    const ranges = [];
+    let rangeStart = codePoints[0];
+    let rangeEnd = codePoints[0];
+    for (let i = 1; i <= codePoints.length; i++) {
+        const current = codePoints[i];
+        // Check if current is consecutive with previous
+        if (current === rangeEnd + 1) {
+            rangeEnd = current;
+        }
+        else {
+            // Output the completed range
+            if (rangeStart === rangeEnd) {
+                ranges.push(`U+${rangeStart.toString(16).toUpperCase().padStart(4, '0')}`);
+            }
+            else {
+                ranges.push(`U+${rangeStart.toString(16).toUpperCase().padStart(4, '0')}-${rangeEnd.toString(16).toUpperCase().padStart(4, '0')}`);
+            }
+            // Start new range
+            if (current !== undefined) {
+                rangeStart = current;
+                rangeEnd = current;
+            }
+        }
+    }
+    return ranges.join(', ');
+}
+/**
+ * Get named unicode ranges for specified subsets.
+ *
+ * @param subsetNames - Array of subset names (e.g., ['latin', 'latin-ext'])
+ * @returns Combined unicode-range CSS value
+ */
+export function getNamedSubsetRanges(subsetNames) {
+    const ranges = [];
+    for (const name of subsetNames) {
+        const subset = UNICODE_RANGES[name];
+        if (subset) {
+            ranges.push(subset.range);
+        }
+    }
+    return ranges.join(', ');
+}
+/**
+ * Detect which subsets are needed based on characters.
+ *
+ * @param chars - Set of characters to analyze
+ * @returns Array of subset names that cover the characters
+ */
+export function detectRequiredSubsets(chars) {
+    const needed = new Set();
+    const codePoints = charsToCodePoints(chars);
+    // Helper to check if code point is in range
+    const inRange = (cp, rangeStr) => {
+        const ranges = rangeStr.split(',').map(r => r.trim());
+        for (const range of ranges) {
+            const match = range.match(/U\+([0-9A-F]+)(?:-([0-9A-F]+))?/i);
+            if (match) {
+                const start = parseInt(match[1], 16);
+                const end = match[2] ? parseInt(match[2], 16) : start;
+                if (cp >= start && cp <= end) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    };
+    // Check each code point against all subsets
+    for (const cp of codePoints) {
+        for (const [name, subset] of Object.entries(UNICODE_RANGES)) {
+            if (inRange(cp, subset.range)) {
+                needed.add(name);
+                break; // Found a match, move to next code point
+            }
+        }
+    }
+    return Array.from(needed);
+}
+// ============================================================================
+// File Scanning (Node.js only, used by Vite plugin)
+// ============================================================================
+/**
+ * Patterns to match text content in source files.
+ * Excludes code, imports, comments.
+ */
+const TEXT_EXTRACTION_PATTERNS = {
+    // JSX/TSX text content
+    jsxText: />\s*([^<>{]+?)\s*</g,
+    // String literals (double quotes)
+    doubleQuoteString: /"([^"\\]|\\.)*"/g,
+    // String literals (single quotes)
+    singleQuoteString: /'([^'\\]|\\.)*'/g,
+    // Template literals (backticks)
+    templateLiteral: /`([^`\\]|\\.)*`/g,
+    // HTML text content
+    htmlText: />\s*([^<>]+?)\s*</g,
+    // Vue template text
+    vueText: />\s*([^<>{]+?)\s*</g,
+    // Svelte text
+    svelteText: />\s*([^<>{]+?)\s*</g,
+};
+/**
+ * Extract text content from source code.
+ * Used by the Vite plugin to find used characters.
+ *
+ * @param sourceCode - Source code content
+ * @param fileType - File extension (tsx, vue, svelte, etc.)
+ * @returns Set of unique characters
+ */
+export function extractCharsFromSource(sourceCode, fileType) {
+    const chars = new Set();
+    const patterns = [];
+    // Select patterns based on file type
+    switch (fileType) {
+        case 'tsx':
+        case 'jsx':
+            patterns.push(TEXT_EXTRACTION_PATTERNS.jsxText);
+            patterns.push(TEXT_EXTRACTION_PATTERNS.doubleQuoteString);
+            patterns.push(TEXT_EXTRACTION_PATTERNS.singleQuoteString);
+            patterns.push(TEXT_EXTRACTION_PATTERNS.templateLiteral);
+            break;
+        case 'vue':
+            patterns.push(TEXT_EXTRACTION_PATTERNS.vueText);
+            patterns.push(TEXT_EXTRACTION_PATTERNS.doubleQuoteString);
+            patterns.push(TEXT_EXTRACTION_PATTERNS.singleQuoteString);
+            break;
+        case 'svelte':
+            patterns.push(TEXT_EXTRACTION_PATTERNS.svelteText);
+            patterns.push(TEXT_EXTRACTION_PATTERNS.doubleQuoteString);
+            patterns.push(TEXT_EXTRACTION_PATTERNS.singleQuoteString);
+            break;
+        case 'html':
+            patterns.push(TEXT_EXTRACTION_PATTERNS.htmlText);
+            break;
+        default:
+            // Generic: extract all string-like content
+            patterns.push(TEXT_EXTRACTION_PATTERNS.doubleQuoteString);
+            patterns.push(TEXT_EXTRACTION_PATTERNS.singleQuoteString);
+    }
+    // Extract text using all applicable patterns
+    for (const pattern of patterns) {
+        // Reset lastIndex for global regexes
+        pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.exec(sourceCode)) !== null) {
+            const text = match[1] || match[0];
+            for (const char of extractCharsFromText(text)) {
+                chars.add(char);
+            }
+        }
+    }
+    return chars;
+}
+// ============================================================================
+// CSS Generation
+// ============================================================================
+/**
+ * Generate @font-face CSS with unicode-range.
+ *
+ * @param fontFamily - Font family name
+ * @param fontUrl - URL to font file
+ * @param options - Font face options
+ * @returns CSS @font-face rule
+ */
+export function generateFontFaceCSS(fontFamily, fontUrl, options = {}) {
+    const { weight = '400', style = 'normal', display = 'swap', unicodeRange, format = 'woff2', } = options;
+    let css = `@font-face {\n`;
+    css += `  font-family: '${fontFamily}';\n`;
+    css += `  font-style: ${style};\n`;
+    css += `  font-weight: ${weight};\n`;
+    css += `  font-display: ${display};\n`;
+    css += `  src: url('${fontUrl}') format('${format}');\n`;
+    if (unicodeRange) {
+        css += `  unicode-range: ${unicodeRange};\n`;
+    }
+    css += `}\n`;
+    return css;
+}
+// ============================================================================
+// Exports
+// ============================================================================
+// Types are exported at declaration above
+//# sourceMappingURL=subset.js.map