@vyaz/core 0.0.1

package/src/layout/PositioningEngine.ts

@@ -0,0 +1,391 @@
+/**
+ * PositioningEngine.ts — pure X/Y positioning math.
+ *
+ * Takes pretext output (lines with fragments) + font metrics +
+ * paragraph style → returns LineBox[] with absolute coordinates.
+ *
+ * X: alignment (left/center/right/justify) + indent
+ * Y: baseline + lineHeight + spaceBefore/After
+ * Justify: fragmented approach (each space → separate FragmentBox)
+ *
+ * Specs:
+ * - CSS Text Module Level 3/4 (browser mode)
+ * - ISO/IEC 29500 (Office Open XML / DrawingML, office mode)
+ * - Parley alignment.rs (conceptually close, but here justify is simpler:
+ *   slack is divided equally among stretchable space-fragments,
+ *   without mutating ClusterData.advance)
+ */
+
+import type { ParagraphStyle } from '../types/Document.js';
+import type { FontMetrics } from '../types/FontTypes.js';
+import type { LineBox, FragmentBox, FragmentFontMetrics } from '../types/LayoutTypes.js';
+import type { PreparedRichInlineItem } from '../compile/DocumentCompiler.js';
+
+// ── Helper types for pretext ───────────────────────────────────────────
+
+interface PretextFragment {
+  itemIndex: number;
+  text: string;
+  gapBefore: number;
+  occupiedWidth: number;
+  start: { segmentIndex: number; graphemeIndex: number };
+  end: { segmentIndex: number; graphemeIndex: number };
+}
+
+interface PretextLine {
+  fragments: PretextFragment[];
+  width: number;         // natural width (without stretching)
+  end: { segmentIndex: number; graphemeIndex: number };
+}
+
+// ── PositioningEngine ─────────────────────────────────────────────────
+
+/**
+ * Build LineBox[] from pretext lines with alignment and metrics.
+ *
+ * @param pretextLines — pretext result (materializeRichInlineLineRange)
+ * @param items — original PreparedRichInlineItem[] (for metadata)
+ * @param fontMetricsFn — function to get font metrics for a fragment
+ * @param style — paragraph style
+ * @param maxWidth — available container width
+ * @param startY — initial Y position
+ * @param mode — metric mode ('browser' | 'office'), affects line height calculation
+ * @returns { lines: LineBox[], contentWidth: number }
+ */
+export function positionLineBoxes(
+  pretextLines: PretextLine[],
+  items: PreparedRichInlineItem[],
+  fontMetricsFn: (item: PreparedRichInlineItem) => FontMetrics,
+  style: ParagraphStyle,
+  maxWidth: number,
+  startY: number = 0,
+  mode: 'browser' | 'office' = 'browser',
+  paragraphId?: string,
+): { lines: LineBox[]; contentWidth: number } {
+  const lines: LineBox[] = [];
+  let currentY = startY + style.spaceBefore;
+  let charIndex = 0;
+  let isFirstLine = true;
+  let contentWidth = 0;
+
+  for (let lineIdx = 0; lineIdx < pretextLines.length; lineIdx++) {
+    const ptLine = pretextLines[lineIdx];
+
+    // ── Build FragmentBox[] ────────────────────────────
+    let maxAscent = 0;
+    let maxDescent = 0;
+    let maxLineHeightBase = 0; // max(ascent + descent) — for Office mode
+    const fragments: FragmentBox[] = [];
+
+    for (const frag of ptLine.fragments) {
+      const item = items[frag.itemIndex];
+      if (!item) continue;
+
+      const metrics = fontMetricsFn(item);
+      const effectiveAscent = metrics.ascent + (item.metadata.baselineOffset || 0);
+      const effectiveDescent = metrics.descent - (item.metadata.baselineOffset || 0);
+
+      maxAscent = Math.max(maxAscent, effectiveAscent);
+      maxDescent = Math.max(maxDescent, effectiveDescent);
+      // Office: line height base = ascent + descent (OS/2 usWinAscent + usWinDescent, scaled)
+      maxLineHeightBase = Math.max(maxLineHeightBase, metrics.ascent + metrics.descent);
+
+      // pretext: gapBefore — inter-word space BEFORE the word
+      // occupiedWidth = gapBefore + textWidth
+      // Split into two FragmentBox: space + word
+      const gapWidth = frag.gapBefore || 0;
+      const textWidth = frag.occupiedWidth;
+
+      const baseFontMetrics = {
+        ascent: metrics.ascent,
+        descent: metrics.descent,
+        fontSize: item.metadata.effectiveFontSize,
+      };
+
+      if (gapWidth > 0) {
+        fragments.push({
+          x: 0,
+          width: gapWidth,
+          text: ' ',
+          itemIndex: frag.itemIndex,
+          paragraphId,
+          fontMetrics: baseFontMetrics,
+          style: item.metadata.style,
+          inlineWidget: item.metadata.inlineWidget,
+          type: 'space',
+        });
+      }
+
+      // Split leading/trailing spaces from frag.text into separate space fragments
+      // This is needed for SVG rendering to avoid xml:space="preserve" dependency
+      const text = frag.text;
+      const leadingMatch = text.match(/^(\s+)/);
+
+      const totalChars = text.length;
+      let remainingText = text;
+      let leadingSpaceChars = 0;
+      let trailingSpaceChars = 0;
+
+      if (leadingMatch) {
+        leadingSpaceChars = leadingMatch[1].length;
+        remainingText = remainingText.slice(leadingSpaceChars);
+      }
+      if (remainingText.length > 0) {
+        const trailMatch = remainingText.match(/(\s+)$/);
+        if (trailMatch) {
+          trailingSpaceChars = trailMatch[1].length;
+          remainingText = remainingText.slice(0, -trailingSpaceChars);
+        }
+      }
+
+      const computePartialWidth = (charCount: number) => {
+        return totalChars > 0 ? (charCount / totalChars) * textWidth : 0;
+      };
+
+      // Leading space fragment
+      if (leadingSpaceChars > 0) {
+        fragments.push({
+          x: 0,
+          width: computePartialWidth(leadingSpaceChars),
+          text: text.slice(0, leadingSpaceChars),
+          itemIndex: frag.itemIndex,
+          paragraphId,
+          fontMetrics: baseFontMetrics,
+          style: item.metadata.style,
+          inlineWidget: item.metadata.inlineWidget,
+          type: 'space',
+        });
+      }
+
+      // Text fragment (trimmed)
+      if (remainingText.length > 0) {
+        const textWidth = computePartialWidth(remainingText.length);
+        // Compute per-glyph advances by distributing textWidth equally across glyphs.
+        // For monospace fonts this is exact; for proportional it's a linear approximation.
+        // The FontMetricsProvider can later supply real glyph advances when available.
+        const glyphAdvances: number[] = [];
+        if (remainingText.length > 1) {
+          const perGlyph = textWidth / remainingText.length;
+          for (let i = 0; i < remainingText.length; i++) {
+            glyphAdvances.push(perGlyph);
+          }
+        }
+        fragments.push({
+          x: 0,
+          width: textWidth,
+          text: remainingText,
+          itemIndex: frag.itemIndex,
+          paragraphId,
+          fontMetrics: baseFontMetrics,
+          style: item.metadata.style,
+          inlineWidget: item.metadata.inlineWidget,
+          type: 'text',
+          glyphAdvances: glyphAdvances.length > 0 ? glyphAdvances : undefined,
+        });
+      }
+
+      // Trailing space fragment
+      if (trailingSpaceChars > 0) {
+        const trailingStart = leadingSpaceChars + remainingText.length;
+        fragments.push({
+          x: 0,
+          width: computePartialWidth(trailingSpaceChars),
+          text: text.slice(trailingStart, trailingStart + trailingSpaceChars),
+          itemIndex: frag.itemIndex,
+          paragraphId,
+          fontMetrics: baseFontMetrics,
+          style: item.metadata.style,
+          inlineWidget: item.metadata.inlineWidget,
+          type: 'space',
+        });
+      }
+    }
+
+    // ── Mark trailing whitespace fragments ───────────────────
+    // CSS Text §4.1.3: end-of-line spaces have zero measure for line-advance calculations.
+    // Parley: LineItemData.has_trailing_whitespace → trailing whitespace is excluded from advance.
+    //
+    // Find the last space(s) at the end of the line and mark them trailing.
+    let trailingStartIndex = fragments.length;
+    for (let i = fragments.length - 1; i >= 0; i--) {
+      if (fragments[i].type === 'space') {
+        trailingStartIndex = i;
+      } else {
+        break;
+      }
+    }
+
+    const trailingWidth = fragments
+      .slice(trailingStartIndex)
+      .reduce((sum, f) => sum + f.width, 0);
+
+    for (let i = trailingStartIndex; i < fragments.length; i++) {
+      fragments[i].trailing = true;
+    }
+
+    // ── Compute effective line width (excluding trailing whitespace) ─
+    // Use sum of actual fragment widths instead of ptLine.width, because
+    // ptLine.width may not include gapBefore spaces that were split into
+    // separate FragmentBox (e.g. "AA" + " A" → [AA][ ][A]).
+    const totalFragWidth = fragments.reduce((sum, f) => sum + f.width, 0);
+    const effectiveLineWidth = totalFragWidth - trailingWidth;
+
+    // ── X positioning ───────────────────────────────
+    const indent = isFirstLine
+      ? (style.leftIndent || 0) + (style.indent || 0)
+      : (style.leftIndent || 0);
+    const rightIndent = style.rightIndent || 0;
+    const availableWidth = maxWidth - indent - rightIndent;
+
+    const slack = Math.max(0, availableWidth - effectiveLineWidth);
+
+    let xOffset = indent;
+
+    if (style.alignment === 'center') {
+      xOffset = indent + slack / 2;
+    } else if (style.alignment === 'right') {
+      xOffset = indent + slack;
+    } else if (style.alignment === 'justify') {
+      // Justify: distribute slack evenly among whitespace fragments
+      // (excluding trailing whitespace).
+      //
+      // CSS Text Module Level 3 §4.1.3: trailing spaces do not participate in justify.
+      // CSS text-align-last: last line is not justify, but start-align.
+      // OOXML (ISO 29500): last line of paragraph is not stretched.
+      // Parley alignment.rs: excludes last line (line.break_reason == None/Explicit)
+      //   and lines with num_spaces == 0.
+      //
+      // Determine if this is the last line in the paragraph.
+      const isLastLine = lineIdx === pretextLines.length - 1;
+
+      // Count only "stretchable" spaces: type === 'space' and !trailing
+      const stretchableSpaces = fragments.filter(
+        (f) => f.type === 'space' && !f.trailing,
+      );
+      const spaceCount = stretchableSpaces.length;
+
+      if (!isLastLine && spaceCount > 0 && slack > 0) {
+        const extraPerSpace = slack / spaceCount;
+        for (const sf of stretchableSpaces) {
+          sf.width += extraPerSpace;
+        }
+      }
+
+      // If this is the last line or no spaces — fallback to start-align
+      // (LTR → left, RTL → right — always left for now, Bidi in Phase 2)
+      xOffset = indent;
+    }
+
+    // Assign X positions
+    let runX = xOffset;
+    for (const frag of fragments) {
+      frag.x = Math.round(runX * 100) / 100;
+      runX += frag.width;
+    }
+
+    const lineWidth = runX - xOffset;
+    contentWidth = Math.max(contentWidth, lineWidth);
+
+    // ── Y positioning ───────────────────────────────
+    // Line height algorithm depends on mode:
+    //
+    // 'browser' (CSS-compatible, parley/Chrome matching):
+    //   1. lineHeightPx = maxFontSize * style.lineHeight
+    //
+    // 'office' (MS Office / DrawingML pixel-perfect):
+    //   PowerPoint has no line-height multiplier for single lines.
+    //   Line height strictly = ascent + descent (OS/2.usWinAscent + usWinDescent).
+    //   Baseline = Top + ascent without any half-leading additions.
+    //   See pixel-perfect-text-layout.md §1 and ECMA-376.
+    const maxFontSize = fragments.reduce((max, f) => Math.max(max, f.fontMetrics.fontSize), 0);
+
+    const ascentRounded = Math.round(maxAscent);
+    const descentRounded = Math.round(maxDescent);
+
+    let lineBoxHeight: number;
+    let baseline: number;
+
+    if (mode === 'office') {
+      // DrawingML: lineHeight = ascent + descent, no lineHeight ×1.15 and no leading.
+      // DrawingML: base line height = OS/2 (usWinAscent + usWinDescent), without
+      // sum of rounded ascent/descent — that formula caused pixel-perfect
+      // mismatch with PowerPoint, so we use maxLineHeightBase.
+      lineBoxHeight = maxLineHeightBase;
+      baseline = ascentRounded;
+    } else {
+      // Browser: CSS-compatible with leading distribution.
+      const lineHeightPx = maxFontSize * style.lineHeight;
+      const ascentDescentRounded = ascentRounded + descentRounded;
+
+      const rawLineBoxHeight = Math.round(lineHeightPx);
+      lineBoxHeight = Math.max(rawLineBoxHeight, ascentDescentRounded);
+      const leading = lineBoxHeight - ascentDescentRounded; // always integer
+
+      if (leading <= 0) {
+        // Negative or zero leading: don't shrink the line
+        baseline = ascentRounded;
+      } else {
+        // Positive leading: distribute as integers with above_leading < below_leading
+        const ascentDescent = maxAscent + maxDescent;
+        const aboveLeadingFloat = ascentDescent > 0 ? leading * maxAscent / ascentDescent : leading / 2;
+        let aboveLeading = Math.round(aboveLeadingFloat);
+        let belowLeading = leading - aboveLeading;
+
+        // Ensure above_leading < below_leading (parley/Chrome heuristic)
+        if (aboveLeading >= belowLeading) {
+          aboveLeading = Math.floor((leading - 1) / 2);
+          belowLeading = leading - aboveLeading;
+        }
+
+        baseline = ascentRounded + aboveLeading;
+      }
+    }
+
+    const startIdx = charIndex;
+
+    // Count characters in line (for INDEX_CONSIST)
+    let lineCharCount = 0;
+    for (const frag of fragments) {
+      lineCharCount += frag.text.length;
+    }
+    const endIdx = startIdx + lineCharCount;
+    charIndex = endIdx;
+
+    // ── Mark break type on the last fragment ─────────────
+    // 'soft' — line wrap due to width constraint
+    // 'hard' — explicit break (\n)
+    // 'none'/undefined — not a line end (no break)
+    if (fragments.length > 0) {
+      const lastFrag = fragments[fragments.length - 1];
+      const lastFragItem = items[lastFrag.itemIndex];
+      // If last character is \n, it's a hard break
+      if (lastFragItem && lastFrag.text.endsWith('\n')) {
+        lastFrag.breakType = 'hard';
+      } else if (lineIdx < pretextLines.length - 1) {
+        lastFrag.breakType = 'soft';
+      }
+    }
+
+    lines.push({
+      x: Math.round(xOffset * 100) / 100,
+      y: Math.round(currentY * 100) / 100,
+      width: Math.round(lineWidth * 100) / 100,
+      height: Math.round(lineBoxHeight * 100) / 100,
+      baseline: Math.round(baseline * 100) / 100,
+      ascent: Math.round(maxAscent * 100) / 100,
+      descent: Math.round(maxDescent * 100) / 100,
+      startIndex: startIdx,
+      endIndex: endIdx,
+      alignment: style.alignment,
+      fragments,
+    });
+
+    currentY += lineBoxHeight;
+    isFirstLine = false;
+  }
+
+  // Add spaceAfter to last line height
+  // (return as is — ParagraphLayoutEngine will add spaceAfter to total height)
+
+  return { lines, contentWidth };
+}

package/src/layout/TextFrameLayoutEngine.ts

@@ -0,0 +1,86 @@
+/**
+ * TextFrameLayoutEngine.ts — Layout a full TextFrame (multi-paragraph).
+ *
+ * Pipeline:
+ *   TextFrame → Paragraph[] → paragraphLayoutEngine.layout() each → merge LineBox[]
+ *
+ * Handles:
+ * - Paragraph stacking with Y offset accumulation
+ * - Padding (left reduces available width, left shifts X)
+ * - frame.width/height optional → fitHorizontal/fitVertical flags
+ */
+import type { TextFrame } from '../types/Document.js';
+import type { LineBox } from '../types/LayoutTypes.js';
+import { paragraphLayoutEngine } from './ParagraphLayoutEngine.js';
+
+/**
+ * Result of laying out a full TextFrame.
+ *
+ * `fitHorizontal` / `fitVertical` tell the renderer which dimension to use:
+ * - `'frame'`   → use `frameWidth` / `frameHeight`
+ * - `'content'` → use `contentWidth` / `contentHeight`
+ */
+export interface TextFrameLayoutResult {
+  lines: LineBox[];
+  /** Frame width (set when TextFrame.width was provided). */
+  frameWidth?: number;
+  /** Frame height (set when TextFrame.height was provided). */
+  frameHeight?: number;
+  /** Actual content width (may exceed frameWidth when wrap=false). */
+  contentWidth: number;
+  /** Actual content height (may exceed frameHeight). */
+  contentHeight: number;
+  /** Whether horizontal dimension should use frame or content size. */
+  fitHorizontal: 'frame' | 'content';
+  /** Whether vertical dimension should use frame or content size. */
+  fitVertical: 'frame' | 'content';
+}
+
+/**
+ * Layout a full TextFrame by stacking paragraphs with Y offset accumulation.
+ */
+export function layoutTextFrame(frame: TextFrame): TextFrameLayoutResult {
+  const allLines: LineBox[] = [];
+  let yOffset = 0;
+  let contentWidth = 0;
+
+  const leftPad = frame.padding?.left ?? 0;
+  const rightPad = frame.padding?.right ?? 0;
+
+  for (let i = 0; i < frame.paragraphs.length; i++) {
+    const p = frame.paragraphs[i];
+
+    // Available width: frame.width minus horizontal padding.
+    // If width is undefined → Infinite (no wrap constraint).
+    const maxWidth = frame.width !== undefined
+      ? frame.width - leftPad - rightPad
+      : Infinity;
+
+    const result = paragraphLayoutEngine.layout(p, maxWidth, yOffset);
+
+    for (const line of result.lines) {
+      // Shift lines by left padding
+      line.x += leftPad;
+      allLines.push(line);
+    }
+
+    contentWidth = Math.max(contentWidth, result.contentWidth);
+    // result.height is absolute (includes yOffset passed in).
+    // Set, don't accumulate — otherwise yOffset compounds.
+    yOffset = result.height;
+  }
+
+  const contentHeight = allLines.length > 0
+    ? allLines[allLines.length - 1].y + allLines[allLines.length - 1].height
+    : 0;
+
+  return {
+    lines: allLines,
+    frameWidth: frame.width,
+    frameHeight: frame.height,
+    contentWidth,
+    contentHeight,
+    fitHorizontal: frame.width !== undefined ? 'frame' : 'content',
+    fitVertical: frame.height !== undefined ? 'frame' : 'content',
+  };
+}

package/src/measure/FontMetricsProvider.ts

@@ -0,0 +1,190 @@
+/**
+ * FontMetricsProvider.ts — isomorphic font metrics provider.
+ *
+ * Strategy (priority):
+ *   1. fontkit (Node.js) — from registered buffer
+ *      - 'browser' mode: font.hhea.ascent / font.hhea.descent
+ *      - 'office'  mode:  font['OS/2'].usWinAscent / font['OS/2'].usWinDescent
+ *   2. Canvas TextMetrics (browser)
+ *   3. Fallback (fontSize * 0.85 / 0.15)
+ *
+ * Uses FontRegistry for font registration.
+ */
+
+import type { FontMetrics, IFontMetricsProvider } from '../types/FontTypes.js';
+import { enableOfficeTextMeasure, disableOfficeTextMeasure } from './canvas-polyfill.js';
+
+/** Cache key: "${family}_${weight}_${style}" */
+function cacheKey(family: string, weight: string, style: string): string {
+  return `${family}_${weight}_${style}`;
+}
+
+export class FontMetricsProvider implements IFontMetricsProvider {
+  private cache = new Map<string, any>();   // fontkit.Font | undefined
+  private metricsCache = new Map<string, FontMetrics>();
+  private mode: 'browser' | 'office' = 'browser';
+
+  // ── Mode ──────────────────────────────────────────────────────────
+
+  setMode(mode: 'browser' | 'office'): void {
+    if (this.mode === mode) return;
+    this.mode = mode;
+    // Invalidate metrics cache on mode change
+    this.metricsCache.clear();
+
+    // Toggle ctx.measureText for pretext (canvas-based line breaking)
+    if (mode === 'office') {
+      enableOfficeTextMeasure(this.cache); // fontkit-based hmtx advance widths
+    } else {
+      disableOfficeTextMeasure(); // original Canvas 2D measureText
+    }
+  }
+
+  getMode(): 'browser' | 'office' {
+    return this.mode;
+  }
+
+  // ── FontRegistry ──────────────────────────────────────────────────
+
+  /**
+   * Register a binary font for use with fontkit.
+   * In browser — no-op.
+   */
+  async registerFont(
+    family: string,
+    options: { weight?: string; style?: string },
+    source: string | Buffer,
+  ): Promise<void> {
+    try {
+      // Dynamic ESM import — fontkit may not be available in browser
+      const fontkit = await import('fontkit');
+      const buffer = typeof source === 'string' ? Buffer.from(source) : source;
+      // @ts-ignore fontkit CJS/ESM compatibility
+      const fk = fontkit.default || fontkit;
+      const font = fk.create(buffer);
+      const key = cacheKey(
+        family,
+        options.weight || 'normal',
+        options.style || 'normal',
+      );
+      this.cache.set(key, font);
+      // Invalidate metrics for this font
+      this.metricsCache.delete(key);
+    } catch {
+      // fontkit not available (browser) — no-op
+    }
+    return Promise.resolve();
+  }
+
+  // ── Font object access (for per-glyph advance) ────────────────────
+
+  /**
+   * Get fontkit font object for per-character calculations.
+   * Returns undefined if font is not registered or fontkit unavailable.
+   */
+  getFont(family: string, weight = 'normal', style = 'normal'): any | undefined {
+    const key = cacheKey(family, weight, style);
+    return this.cache.get(key);
+  }
+
+  // ── Metrics retrieval ─────────────────────────────────────────────
+
+  getMetrics(
+    fontFamily: string,
+    fontSize: number,
+    weight = 'normal',
+    style = 'normal',
+  ): FontMetrics {
+    const key = cacheKey(fontFamily, weight, style);
+
+    // Metrics cache (depends on fontSize, so include in key)
+    const metricsKey = `${key}_${fontSize}_${this.mode}`;
+    const cached = this.metricsCache.get(metricsKey);
+    if (cached) return cached;
+
+    let metrics: FontMetrics;
+
+    // Strategy 1: fontkit
+    const font = this.cache.get(key);
+
+    if (font) {
+      const scale = fontSize / font.unitsPerEm;
+
+      if (this.mode === 'office') {
+        // Office mode: OS/2.usWinAscent + usWinDescent
+        const os2 = font['OS/2'];
+        let ascent: number;
+        let descent: number;
+        let sourceTable: 'OS/2' | 'hhea';
+
+        if (os2 && os2.winAscent != null && os2.winDescent != null) {
+          ascent = os2.winAscent * scale  * 1.078;
+          descent = Math.abs(os2.winDescent) * scale * 1.078;
+          sourceTable = 'OS/2';
+        } else {
+          // Fallback to hhea if OS/2 is absent
+          ascent = font.ascent * scale;
+          descent = Math.abs(font.descent) * scale;
+          sourceTable = 'hhea';
+        }
+
+        metrics = {
+          ascent,
+          descent,
+          capHeight: (font.capHeight ?? ascent) * scale,
+          unitsPerEm: font.unitsPerEm,
+          sourceTable,
+        };
+      } else {
+        // Browser mode: hhea.ascender/descender
+        metrics = {
+          ascent: font.ascent * scale,
+          descent: Math.abs(font.descent) * scale,
+          capHeight: (font.capHeight ?? font.ascent) * scale,
+          unitsPerEm: font.unitsPerEm,
+          sourceTable: 'hhea',
+        };
+      }
+
+      this.metricsCache.set(metricsKey, metrics);
+      return metrics;
+    }
+
+    // Strategy 2: Canvas TextMetrics (browser)
+    if (typeof document !== 'undefined') {
+      try {
+        const canvas = document.createElement('canvas');
+        const ctx = canvas.getContext('2d')!;
+        ctx.font = `${style} ${weight} ${fontSize}px ${fontFamily}`;
+        const m = ctx.measureText('M');
+
+        metrics = {
+          ascent: m.fontBoundingBoxAscent || fontSize * 0.85,
+          descent: m.fontBoundingBoxDescent || fontSize * 0.15,
+          capHeight: m.actualBoundingBoxAscent || fontSize * 0.7,
+          unitsPerEm: 1000,
+          sourceTable: 'canvas',
+        };
+        this.metricsCache.set(metricsKey, metrics);
+        return metrics;
+      } catch {
+        // Fall through to fallback
+      }
+    }
+
+    console.error("Font not found")
+    // Strategy 3: Fallback
+    metrics = {
+      ascent: fontSize * 0.85,
+      descent: fontSize * 0.15,
+      capHeight: fontSize * 0.7,
+      unitsPerEm: 1000,
+      sourceTable: 'fallback',
+    };
+    this.metricsCache.set(metricsKey, metrics);
+    return metrics;
+  }
+}
+
+/** Singleton */
+export const fontMetricsProvider = new FontMetricsProvider();

package/src/measure/canvas-polyfill.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Type declarations for @napi-rs/canvas used by canvas-polyfill.ts.
+ */
+declare module '@napi-rs/canvas' {
+  export function createCanvas(width: number, height: number): any;
+}