pagyra-js 0.0.1

package/src/fonts/extractors/metrics-extractor.ts

@@ -0,0 +1,362 @@
+import type { TtfMetrics, GlyphMetrics, CmapData, GlyphOutlineCmd } from '../../types/fonts.js';
+import type { FontTableData } from '../parsers/base-parser.js';
+
+/**
+ * Font Metrics Extractor - Single Responsibility: Extract font metrics from table data
+ * 
+ * This extractor is responsible ONLY for:
+ * - Reading font metrics from table data
+ * - Extracting character-to-glyph mappings
+ * - Computing font-wide measurements
+ * 
+ * It does NOT handle:
+ * - Font format parsing
+ * - PDF embedding
+ * - Font file I/O
+ */
+export interface FontMetrics {
+  readonly metrics: TtfMetrics;
+  readonly glyphMetrics: ReadonlyMap<number, GlyphMetrics>;
+  readonly cmap: CmapData;
+  readonly headBBox?: readonly [number, number, number, number];
+}
+
+/**
+ * Interface for extracting metrics from any font table data
+ */
+export interface MetricsExtractor<T extends FontTableData = FontTableData> {
+  extractMetrics(tableData: T): FontMetrics;
+  getSupportedFormats(): string[];
+}
+
+/**
+ * WOFF2 Metrics Extractor - Extract metrics directly from WOFF2 table data
+ * 
+ * This allows us to avoid TTF conversion and work directly with WOFF2 data,
+ * maintaining performance and compression benefits.
+ */
+export class Woff2MetricsExtractor implements MetricsExtractor {
+  
+  getSupportedFormats(): string[] {
+    return ['woff2'];
+  }
+
+  extractMetrics(tableData: any): FontMetrics {
+    // Validate we have the required WOFF2 table data
+    if (!tableData.tables || typeof tableData.tables !== 'object') {
+      throw new Error('Invalid WOFF2 table data: missing tables');
+    }
+
+    const tables = tableData.tables;
+    
+    // Extract basic metrics from required tables
+    const headTable = tables['head'];
+    const hheaTable = tables['hhea'];
+    const maxpTable = tables['maxp'];
+    const nameTable = tables['name'];
+    const os2Table = tables['OS/2'];
+
+    if (!headTable || !hheaTable || !maxpTable) {
+      throw new Error('WOFF2 font missing required tables (head, hhea, maxp)');
+    }
+
+    // Parse metrics from tables
+    const metrics = this.parseMetrics(headTable, hheaTable, maxpTable, os2Table);
+    const glyphMetrics = this.parseGlyphMetrics(tableData);
+    const cmap = this.parseCharacterMap(tables['cmap']);
+    const headBBox = this.parseHeadBBox(headTable);
+
+    return {
+      metrics,
+      glyphMetrics,
+      cmap,
+      headBBox
+    };
+  }
+
+  private parseMetrics(headTable: Uint8Array, hheaTable: Uint8Array, maxpTable: Uint8Array, os2Table?: Uint8Array): TtfMetrics {
+    const head = new DataView(headTable.buffer, headTable.byteOffset, headTable.length);
+    const hhea = new DataView(hheaTable.buffer, hheaTable.byteOffset, hheaTable.length);
+    
+    // Read unitsPerEm from head table (offset 18, length 2, big-endian)
+    const unitsPerEm = head.getUint16(18, false);
+    
+    // Read ascender/descender from hhea table
+    const ascender = hhea.getInt16(4, false); // offset 4, length 2, signed
+    const descender = hhea.getInt16(6, false); // offset 6, length 2, signed
+    
+    // Read line gap from hhea table
+    const lineGap = hhea.getInt16(8, false); // offset 8, length 2, signed
+
+    // Extract additional metrics from OS/2 table if available
+    let capHeight = 700; // Default fallback
+    let xHeight = 500; // Default fallback
+    
+    if (os2Table) {
+      const os2 = new DataView(os2Table.buffer, os2Table.byteOffset, os2Table.length);
+      
+      // OS/2 version 2+ has sCapHeight at offset 88
+      if (os2Table.length >= 90) {
+        try {
+          capHeight = os2.getInt16(88, false);
+        } catch {
+          // Use default if reading fails
+        }
+      }
+      
+      // OS/2 has sxHeight at offset 86 (version 2+)
+      if (os2Table.length >= 88) {
+        try {
+          xHeight = os2.getInt16(86, false);
+        } catch {
+          // Use default if reading fails
+        }
+      }
+    }
+
+    return {
+      unitsPerEm,
+      ascender,
+      descender,
+      lineGap,
+      capHeight,
+      xHeight
+    };
+  }
+
+  private parseGlyphMetrics(tableData: any): ReadonlyMap<number, GlyphMetrics> {
+    const tables = tableData.tables;
+    const hmtxTable = tables['hmtx'];
+    const maxpTable = tables['maxp'];
+    
+    if (!hmtxTable || !maxpTable) {
+      throw new Error('WOFF2 font missing required tables for glyph metrics (hmtx, maxp)');
+    }
+
+    const maxp = new DataView(maxpTable.buffer, maxpTable.byteOffset, maxpTable.length);
+    const numGlyphs = maxp.getUint16(4, false); // offset 4, length 2
+    
+    const hmtx = new DataView(hmtxTable.buffer, hmtxTable.byteOffset, hmtxTable.length);
+    const glyphMetrics = new Map<number, GlyphMetrics>();
+    
+    // hmtx format: longHorMetric[] followed by leftSideBearing[]
+    // Number of longHorMetric entries = number of advance widths in hhea
+    const hheaTable = tables['hhea'];
+    const numLongHorMetrics = new DataView(hheaTable.buffer, hheaTable.byteOffset, hheaTable.length).getUint16(34, false);
+    
+    let hmtxOffset = 0;
+    let lastAdvanceWidth = 0;
+    
+    // Process longHorMetric entries (advanceWidth + leftSideBearing)
+    for (let i = 0; i < numLongHorMetrics && i < numGlyphs; i++) {
+      const advanceWidth = hmtx.getUint16(hmtxOffset, false);
+      const leftSideBearing = hmtx.getInt16(hmtxOffset + 2, false);
+      
+      glyphMetrics.set(i, {
+        advanceWidth,
+        leftSideBearing
+      });
+      
+      lastAdvanceWidth = advanceWidth;
+      hmtxOffset += 4; // 2 bytes advanceWidth + 2 bytes leftSideBearing
+    }
+    
+    // Process remaining glyphs with just leftSideBearing
+    // Per OpenType spec: these glyphs reuse the last advanceWidth value
+    for (let i = numLongHorMetrics; i < numGlyphs; i++) {
+      const leftSideBearing = hmtx.getInt16(hmtxOffset, false);
+      
+      glyphMetrics.set(i, {
+        advanceWidth: lastAdvanceWidth,
+        leftSideBearing
+      });
+      
+      hmtxOffset += 2;
+    }
+
+    return glyphMetrics;
+  }
+
+  private parseCharacterMap(cmapTable?: Uint8Array): CmapData {
+    if (!cmapTable) {
+      // Return basic fallback cmap
+      return {
+        getGlyphId: () => 0,
+        hasCodePoint: () => false,
+        unicodeMap: new Map()
+      };
+    }
+
+    const cmap = new DataView(cmapTable.buffer, cmapTable.byteOffset, cmapTable.length);
+    
+    // Parse cmap table structure
+    const version = cmap.getUint16(0, false);
+    const numTables = cmap.getUint16(2, false);
+    
+    let bestSubtable: { offset: number; length: number; format: number } | null = null;
+    
+    // Find the best encoding subtable (prefer format 4, then format 12)
+    for (let i = 0; i < numTables; i++) {
+      const tableOffset = 4 + i * 8; // Each table entry is 8 bytes
+      const platformID = cmap.getUint16(tableOffset, false);
+      const encodingID = cmap.getUint16(tableOffset + 2, false);
+      const subtableOffset = cmap.getUint32(tableOffset + 4, false);
+      
+      // Read subtable format
+      const subtableFormat = cmap.getUint16(subtableOffset, false);
+      
+      // Prefer Unicode (platformID = 0 or 3) with format 4 or 12
+      const isUnicode = platformID === 0 || (platformID === 3 && encodingID === 1);
+      const isPreferredFormat = subtableFormat === 4 || subtableFormat === 12;
+      
+      if (isUnicode && isPreferredFormat && (!bestSubtable || subtableFormat === 4)) {
+        bestSubtable = {
+          offset: subtableOffset,
+          length: 0, // Will be computed
+          format: subtableFormat
+        };
+        
+        if (subtableFormat === 4) {
+          break; // Format 4 is preferred
+        }
+      }
+    }
+    
+    if (!bestSubtable) {
+      // Fallback to first available subtable
+      const tableOffset = 4; // First table
+      const subtableOffset = cmap.getUint32(tableOffset + 4, false);
+      bestSubtable = {
+        offset: subtableOffset,
+        length: 0,
+        format: cmap.getUint16(subtableOffset, false)
+      };
+    }
+    
+    // Parse the chosen subtable
+    if (bestSubtable.format === 4) {
+      return this.parseCmapFormat4(cmap, bestSubtable.offset);
+    } else if (bestSubtable.format === 12) {
+      return this.parseCmapFormat12(cmap, bestSubtable.offset);
+    } else {
+      // Unsupported format - return fallback
+      return {
+        getGlyphId: () => 0,
+        hasCodePoint: () => false,
+        unicodeMap: new Map()
+      };
+    }
+  }
+
+  private parseCmapFormat4(cmap: DataView, offset: number): CmapData {
+    const format = cmap.getUint16(offset, false);
+    if (format !== 4) {
+      throw new Error(`Expected format 4, got ${format}`);
+    }
+    
+    const length = cmap.getUint16(offset + 2, false);
+    const language = cmap.getUint16(offset + 4, false); // Should be 0 for Unicode
+    const segCountX2 = cmap.getUint16(offset + 6, false);
+    const segCount = segCountX2 / 2;
+    
+    const searchRange = cmap.getUint16(offset + 8, false);
+    const entrySelector = cmap.getUint16(offset + 10, false);
+    const rangeShift = cmap.getUint16(offset + 12, false);
+    
+    // Find the offset to endCodes array
+    const endCodesOffset = offset + 14;
+    const startCodesOffset = endCodesOffset + segCount * 2 + 2; // +2 for reservedPad
+    const idDeltaOffset = startCodesOffset + segCount * 2;
+    const idRangeOffsetOffset = idDeltaOffset + segCount * 2;
+    
+    const glyphIdArrayOffset = idRangeOffsetOffset + segCount * 2;
+    
+    const unicodeMap = new Map<number, number>();
+    
+    // Parse segments
+    for (let i = 0; i < segCount; i++) {
+      const endCode = cmap.getUint16(endCodesOffset + i * 2, false);
+      const startCode = cmap.getUint16(startCodesOffset + i * 2, false);
+      const idDelta = cmap.getUint16(idDeltaOffset + i * 2, false);
+      const idRangeOffset = cmap.getUint16(idRangeOffsetOffset + i * 2, false);
+      
+      if (endCode === 0xFFFF) {
+        break; // Last segment marker
+      }
+      
+      if (idRangeOffset === 0) {
+        // Simple case: glyphId = (unicode + idDelta) mod 65536
+        for (let unicode = startCode; unicode <= endCode; unicode++) {
+          const glyphId = (unicode + idDelta) & 0xFFFF;
+          unicodeMap.set(unicode, glyphId);
+        }
+      } else {
+        // Complex case: use idRangeOffset
+        const glyphIdOffset = idRangeOffsetOffset + i * 2 + idRangeOffset;
+        
+        for (let unicode = startCode; unicode <= endCode; unicode++) {
+          const offsetInRange = glyphIdOffset + (unicode - startCode) * 2;
+          const glyphId = cmap.getUint16(offsetInRange, false);
+          
+          if (glyphId !== 0) {
+            const finalGlyphId = (glyphId + idDelta) & 0xFFFF;
+            unicodeMap.set(unicode, finalGlyphId);
+          }
+        }
+      }
+    }
+    
+    return {
+      getGlyphId: (unicode: number) => unicodeMap.get(unicode) || 0,
+      hasCodePoint: (unicode: number) => unicodeMap.has(unicode),
+      unicodeMap
+    };
+  }
+
+  private parseCmapFormat12(cmap: DataView, offset: number): CmapData {
+    const format = cmap.getUint16(offset, false);
+    if (format !== 12) {
+      throw new Error(`Expected format 12, got ${format}`);
+    }
+    
+    const reserved = cmap.getUint16(offset + 2, false);
+    const length = cmap.getUint32(offset + 4, false);
+    const language = cmap.getUint32(offset + 8, false);
+    const nGroups = cmap.getUint32(offset + 12, false);
+    
+    const unicodeMap = new Map<number, number>();
+    
+    let groupOffset = offset + 16;
+    
+    for (let i = 0; i < nGroups; i++) {
+      const startCharCode = cmap.getUint32(groupOffset, false);
+      const endCharCode = cmap.getUint32(groupOffset + 4, false);
+      const startGlyphID = cmap.getUint32(groupOffset + 8, false);
+      
+      for (let unicode = startCharCode; unicode <= endCharCode; unicode++) {
+        const glyphId = startGlyphID + (unicode - startCharCode);
+        unicodeMap.set(unicode, glyphId);
+      }
+      
+      groupOffset += 12; // Each group is 12 bytes
+    }
+    
+    return {
+      getGlyphId: (unicode: number) => unicodeMap.get(unicode) || 0,
+      hasCodePoint: (unicode: number) => unicodeMap.has(unicode),
+      unicodeMap
+    };
+  }
+
+  private parseHeadBBox(headTable: Uint8Array): readonly [number, number, number, number] {
+    const head = new DataView(headTable.buffer, headTable.byteOffset, headTable.length);
+    
+    // head table format: xMin, yMin, xMax, yMax at offsets 36, 38, 40, 42
+    const xMin = head.getInt16(36, false);
+    const yMin = head.getInt16(38, false);
+    const xMax = head.getInt16(40, false);
+    const yMax = head.getInt16(42, false);
+    
+    return [xMin, yMin, xMax, yMax];
+  }
+}

package/src/fonts/font-registry-resolver.ts

@@ -0,0 +1,132 @@
+import type { FontResolver, UnifiedFont } from "../fonts/types.js";
+import type { FontRegistry, FontResource } from "../pdf/font/font-registry.js";
+
+/**
+ * Adapter that implements FontResolver using FontRegistry.
+ * Allows the layout system to resolve fonts during render tree building.
+ */
+export class FontRegistryResolver implements FontResolver {
+    private readonly rawTableAccessors = new WeakMap<FontResource, (tag: string) => Uint8Array | null>();
+
+    constructor(private readonly fontRegistry: FontRegistry) { }
+
+    async resolve(family: string, weight?: number, style?: string): Promise<UnifiedFont> {
+        const fontResource = await this.fontRegistry.ensureFontResource(family, weight, style);
+
+        return this.toUnifiedFont(fontResource, family, weight, style) ?? this.createFallbackFont(family, weight, style);
+    }
+
+    resolveSync(family: string, weight?: number, style?: string): UnifiedFont | undefined {
+        const fontResource = this.fontRegistry.ensureFontResourceSync(family, weight, style);
+
+        return this.toUnifiedFont(fontResource, family, weight, style);
+    }
+
+    private createFallbackFont(family: string, weight?: number, style?: string): UnifiedFont {
+        return {
+            metrics: {
+                metrics: {
+                    unitsPerEm: 1000,
+                    ascender: 800,
+                    descender: -200,
+                    lineGap: 0,
+                    capHeight: 700,
+                    xHeight: 500,
+                },
+                glyphMetrics: new Map([
+                    [0, { advanceWidth: 500, leftSideBearing: 0 }],
+                ]),
+                cmap: {
+                    getGlyphId: () => 0,
+                    hasCodePoint: () => false,
+                    unicodeMap: new Map(),
+                },
+            },
+            program: {
+                sourceFormat: "ttf",
+                unitsPerEm: 1000,
+                glyphCount: 1,
+            },
+            css: {
+                family,
+                weight: weight ?? 400,
+                style: (style as 'normal' | 'italic') ?? 'normal',
+            },
+        };
+    }
+
+    private toUnifiedFont(fontResource: FontResource, family: string, weight?: number, style?: string): UnifiedFont | undefined {
+        const metrics = fontResource.metrics;
+        if (!metrics) return undefined;
+
+        const getRawTableData = this.lookupRawTableAccessor(fontResource);
+        return {
+            metrics: {
+                metrics: metrics.metrics,
+                glyphMetrics: metrics.glyphMetrics,
+                cmap: metrics.cmap,
+                headBBox: metrics.headBBox,
+                kerning: metrics.kerning,
+            },
+            program: {
+                sourceFormat: "ttf",
+                unitsPerEm: metrics.metrics.unitsPerEm,
+                glyphCount: metrics.glyphMetrics.size,
+                getGlyphOutline: metrics.getGlyphOutline,
+                getRawTableData,
+            },
+            css: {
+                family,
+                weight: weight ?? 400,
+                style: (style as 'normal' | 'italic') ?? 'normal',
+            },
+        };
+    }
+
+    private lookupRawTableAccessor(fontResource: FontResource): ((tag: string) => Uint8Array | null) | undefined {
+        const rawBytes: Uint8Array | undefined = fontResource.embedded?.subset;
+        if (!rawBytes || rawBytes.byteLength < 12) {
+            return undefined;
+        }
+
+        const cached = this.rawTableAccessors.get(fontResource);
+        if (cached) return cached;
+
+        const accessor = createRawTableAccessor(rawBytes);
+        this.rawTableAccessors.set(fontResource, accessor);
+        return accessor;
+    }
+}
+
+function createRawTableAccessor(ttfBytes: Uint8Array): (tag: string) => Uint8Array | null {
+    const directory = parseTtfTableDirectory(ttfBytes);
+    return (tag: string) => directory.get(tag) ?? null;
+}
+
+function parseTtfTableDirectory(ttfBytes: Uint8Array): Map<string, Uint8Array> {
+    const tables = new Map<string, Uint8Array>();
+    if (ttfBytes.byteLength < 12) return tables;
+
+    const view = new DataView(ttfBytes.buffer, ttfBytes.byteOffset, ttfBytes.byteLength);
+    const numTables = view.getUint16(4, false);
+
+    for (let i = 0; i < numTables; i++) {
+        const entryOffset = 12 + i * 16;
+        if (entryOffset + 16 > ttfBytes.byteLength) break;
+
+        const tag = String.fromCharCode(
+            ttfBytes[entryOffset],
+            ttfBytes[entryOffset + 1],
+            ttfBytes[entryOffset + 2],
+            ttfBytes[entryOffset + 3]
+        );
+
+        const offset = view.getUint32(entryOffset + 8, false);
+        const length = view.getUint32(entryOffset + 12, false);
+
+        if (offset + length > ttfBytes.byteLength) continue;
+        tables.set(tag, ttfBytes.subarray(offset, offset + length));
+    }
+
+    return tables;
+}

package/src/fonts/index.ts

@@ -0,0 +1,3 @@
+export type { ParsedFont, UnifiedFont, FontFormat } from './types.js';
+export { FontOrchestrator } from './orchestrator.js';
+export { detectFontFormat, isSupportedFontFormat } from './detector.js';

package/src/fonts/orchestrator.ts

@@ -0,0 +1,92 @@
+import { detectFontFormat } from './detector.js';
+import { TtfEngine } from './engines/ttf-engine.js';
+import { WoffEngine } from './engines/woff-engine.js';
+import { Woff2Engine } from './engines/woff2-engine.js';
+import type { FontFormat, UnifiedFont } from './types.js';
+
+export class FontOrchestrator {
+  private engines = new Map<FontFormat, any>();
+
+  constructor() {
+    this.engines.set('ttf', new TtfEngine());
+    this.engines.set('woff', new WoffEngine());
+    this.engines.set('woff2', new Woff2Engine());
+    this.engines.set('otf', new TtfEngine()); // OTF uses the same engine as TTF for now
+  }
+
+  async parseFont(fontData: Uint8Array): Promise<UnifiedFont> {
+    const format = detectFontFormat(fontData);
+    if (!format) {
+      throw new Error('Unsupported font format');
+    }
+
+    const engine = this.engines.get(format);
+    if (!engine) {
+      throw new Error(`No engine available for font format: ${format}`);
+    }
+
+    try {
+      console.log(`FONT-ORCH: Parsing ${format} font with ${engine.constructor.name}`);
+
+      let parsed;
+      if (format === 'ttf' || format === 'otf') {
+        // TTF engine works with TtfFontMetrics directly
+        parsed = engine.parse(fontData);
+      } else {
+        // WOFF/WOFF2 engines work with ParsedFont
+        parsed = await engine.parse(fontData);
+      }
+
+      let unifiedFont: UnifiedFont;
+      if (format === 'ttf' || format === 'otf') {
+        unifiedFont = engine.convertToUnified(parsed);
+      } else {
+        unifiedFont = await engine.convertToUnified(parsed);
+      }
+
+      console.log(`FONT-ORCH: Successfully parsed ${format} font`);
+      return unifiedFont;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      console.warn(`FONT-ORCH: Failed to parse ${format} font:`, errorMessage);
+      throw error instanceof Error ? error : new Error(errorMessage);
+    }
+  }
+
+  getSupportedFormats(): FontFormat[] {
+    return Array.from(this.engines.keys());
+  }
+
+  private getFallbackFont(format: FontFormat): UnifiedFont {
+    console.log(`FONT-ORCH: Creating fallback font for ${format} format`);
+
+    return {
+      metrics: {
+        metrics: {
+          unitsPerEm: 1000,
+          ascender: 800,
+          descender: -200,
+          lineGap: 0,
+          capHeight: 700,
+          xHeight: 500,
+        },
+        glyphMetrics: new Map([
+          [0, { advanceWidth: 500, leftSideBearing: 0 }],
+          [1, { advanceWidth: 250, leftSideBearing: 0 }],
+          [2, { advanceWidth: 500, leftSideBearing: 0 }],
+        ]),
+        cmap: {
+          getGlyphId: () => 1,
+          hasCodePoint: () => true,
+          unicodeMap: new Map([[65, 1]]),
+        },
+        headBBox: [0, -200, 1000, 800]
+      },
+      program: {
+        sourceFormat: format,
+        getRawTableData: () => null,
+        getGlyphOutline: () => null,
+      },
+    };
+  }
+}

package/src/fonts/parsers/base-parser.ts

@@ -0,0 +1,23 @@
+// Base parser interface for all font formats
+export interface FontTableData {
+  flavor: number;
+  tables: Record<string, Uint8Array>;
+  compressionInfo?: CompressionInfo;
+}
+
+export interface CompressionInfo {
+  type: 'none' | 'woff' | 'woff2';
+  tables: Map<string, TableCompressionInfo>;
+}
+
+export interface TableCompressionInfo {
+  compressed: boolean;
+  originalLength?: number;
+  compressedLength?: number;
+}
+
+// Generic font parser interface
+export interface FontParser<T extends FontTableData = FontTableData> {
+  parseTables(fontData: Uint8Array): Promise<T>;
+  getFormat(): string;
+}

package/src/fonts/types.ts

@@ -0,0 +1,85 @@
+import type { TtfMetrics, GlyphMetrics, CmapData, GlyphOutlineCmd, KerningMap } from '../types/fonts.js';
+
+// Raw parsed font (low-level table data)
+export interface ParsedFont {
+  flavor: number;
+  numTables: number;
+  tables: Record<string, Uint8Array>;
+}
+
+/**
+ * Processed font metrics for layout and text shaping/rendering.
+ * Pure data, no raw binary access.
+ */
+export interface FontMetrics {
+  readonly metrics: TtfMetrics;
+  readonly glyphMetrics: ReadonlyMap<number, GlyphMetrics>;
+  readonly cmap: CmapData;
+  readonly headBBox?: readonly [number, number, number, number];
+  readonly kerning?: KerningMap;
+}
+
+/**
+ * Low-level font program data for PDF embedding, subsetting, and glyph paths.
+ * Corresponds to "font program" in PDF/TTF/OTF terminology.
+ */
+export interface FontProgram {
+  readonly sourceFormat: FontFormat;
+  readonly unitsPerEm?: number;
+  readonly glyphCount?: number;
+  readonly getRawTableData?: (tag: string) => Uint8Array | null;
+  readonly getGlyphOutline?: (gid: number) => GlyphOutlineCmd[] | null;
+}
+
+/**
+ * CSS font-face resolution info.
+ */
+export interface CssFontInfo {
+  family: string;
+  weight: number;
+  style: 'normal' | 'italic';
+}
+
+/**
+ * Loaded and unified font: ready for layout/PDF use.
+ * Combines metrics + program + CSS resolution metadata.
+ */
+export interface LoadedFont {
+  readonly metrics: FontMetrics;
+  readonly program: FontProgram;
+  readonly css?: CssFontInfo;
+}
+
+// Backward-compatible alias for gradual migration
+export type UnifiedFont = LoadedFont;
+
+export type FontFormat = 'ttf' | 'woff' | 'woff2' | 'otf';
+
+export interface FontEngine<T = ParsedFont> {
+  parse(fontData: Uint8Array): Promise<T> | T;
+  convertToUnified(parsedFont: T): Promise<UnifiedFont> | UnifiedFont;
+}
+
+/**
+ * WOFF2-specific types for enhanced separation
+ */
+export interface Woff2FontProgram extends FontProgram {
+  readonly sourceFormat: 'woff2';
+  readonly compressionInfo?: {
+    type: 'woff2';
+    tables: Map<string, any>;
+  };
+  readonly transformInfo?: {
+    glyphTransformed: boolean;
+    locaTransformed: boolean;
+  };
+}
+
+export interface Woff2Font extends LoadedFont {
+  readonly program: Woff2FontProgram;
+}
+
+export interface FontResolver {
+  resolve(family: string, weight?: number, style?: string): UnifiedFont | Promise<UnifiedFont>;
+  resolveSync?(family: string, weight?: number, style?: string): UnifiedFont | undefined;
+}