@vyaz/core 0.0.14 → 0.1.0

package/dist/layout/AutoFitEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AutoFitEngine.d.ts","sourceRoot":"","sources":["../../src/layout/AutoFitEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,sBAAsB;AACtB,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBAAqB;AACrB,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,SAAS,EACd,KAAK,EAAE,MAAM,GACZ,SAAS,CAcX;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,SAAS,EACd,QAAQ,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EACrE,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EAC/C,OAAO,CAAC,EAAE,cAAc,GACvB,aAAa,CAoCf"}
+{"version":3,"file":"AutoFitEngine.d.ts","sourceRoot":"","sources":["../../src/layout/AutoFitEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,sBAAsB;AACtB,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBAAqB;AACrB,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,SAAS,EACd,KAAK,EAAE,MAAM,GACZ,SAAS,CAgBX;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,SAAS,EACd,QAAQ,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EACrE,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EAC/C,OAAO,CAAC,EAAE,cAAc,GACvB,aAAa,CAoCf"}

package/dist/layout/LineBoxValidator.d.ts

@@ -1,10 +1,11 @@
 /**
- * LineBoxValidator.ts — invariant checks and YAML serialization.
+ * LineBoxValidator.ts — Parley-inspired line-box invariant checks.
  *
- * Parley-inspired invariant checks:
- *   NO_OVERLAP, MONOTONIC_Y, INDEX_CONSIST, WIDTH_FIT, BASELINE_EQ
+ * Invariants: NO_OVERLAP, MONOTONIC_Y, INDEX_CONSIST, WIDTH_FIT, BASELINE_EQ.
  *
- * YAML snapshots: semantic data only (no metric noise).
+ * YAML snapshot serialization lives in `../debug/lines-to-yaml.ts` (pulled in
+ * only through the `@vyaz/core/debug` entry, so `js-yaml` stays out of the
+ * production bundle).
  */
 import type { Line } from '../types/LayoutTypes.js';
 export interface InvariantError {
@@ -17,10 +18,4 @@ export interface InvariantError {
  * Throws on first violation.
  */
 export declare function assertLineInvariants(lines: Line[], originalText: string, maxWidth: number): void;
-/**
- * Convert Line[] to YAML string for snapshots.
- * Only semantic data: text, x, width, style.
- * No glyphAdvances, fontMetrics (noise), inlineWidget.
- */
-export declare function linesToYAML(lines: Line[], paragraphWidth: number, paragraphHeight: number): string;
 //# sourceMappingURL=LineBoxValidator.d.ts.map

package/dist/layout/LineBoxValidator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LineBoxValidator.d.ts","sourceRoot":"","sources":["../../src/layout/LineBoxValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,IAAI,EAA2B,MAAM,yBAAyB,CAAC;AAM7E,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,GAAG,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,IAAI,EAAE,EACb,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,GACf,IAAI,CAqFN;AAYD;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,IAAI,EAAE,EACb,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,MAAM,GACtB,MAAM,CAwBR"}
+{"version":3,"file":"LineBoxValidator.d.ts","sourceRoot":"","sources":["../../src/layout/LineBoxValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAMpD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,GAAG,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,IAAI,EAAE,EACb,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,GACf,IAAI,CAqFN"}

package/dist/layout/ParagraphLayoutEngine.d.ts

@@ -3,21 +3,28 @@
  *
  * Pipeline:
  *   Paragraph
- *   → compile (DocumentCompiler)
+ *   → compile (ParagraphCompiler)
  *   → prepareRichInline (pretext)
  *   → walkRichInlineLineRanges + materializeRichInlineLineRange (pretext)
  *   → positionLines (PositioningEngine)
- *   → assertLineInvariants (LineInvariants)
+ *
+ * Line-box invariant checks live in `@vyaz/core/debug` (assertLineInvariants);
+ * they are not run on the layout hot path.
  *
  * Supports autofit via AutoFitEngine.findScale.
  * Caches PreparedRichInline per paragraph key (Parley LayoutContext pattern).
  */
-import '../measure/canvas-polyfill.js';
 import type { Paragraph, ListStyle } from '../types/Document.js';
 import type { IFontMetricsProvider } from '../types/FontTypes.js';
 import type { ParagraphLayoutResult } from '../types/LayoutTypes.js';
+import { type OnMissingFont } from './resolve-font.js';
 export declare class ParagraphLayoutEngine {
+    /** LRU (Map insertion order) of PreparedRichInline keyed by {@link preparedCacheKey}. */
     private preparedCache;
+    private readonly cacheMax;
+    constructor(cacheMax?: number);
+    /** Drop all cached prepared-line data (e.g. on document close). */
+    clearCache(): void;
     /**
      * Layout a single paragraph — basic variant.
      *
@@ -26,12 +33,10 @@ export declare class ParagraphLayoutEngine {
      * @param fontProvider — optional metrics provider (default: fontMetricsProvider)
      * @returns ParagraphLayoutResult with Line[]
      */
-    layout(paragraph: Paragraph, maxWidth: number, yOffset?: number, fontProvider?: IFontMetricsProvider, listStyle?: ListStyle, listIndex?: number, listMarkerWidth?: number): ParagraphLayoutResult;
+    layout(paragraph: Paragraph, maxWidth: number, yOffset?: number, fontProvider?: IFontMetricsProvider, listStyle?: ListStyle, listIndex?: number, listMarkerWidth?: number, wantGlyphAdvances?: boolean, mode?: 'browser' | 'office', onMissingFont?: OnMissingFont): ParagraphLayoutResult;
     /**
-     * Layout with per-glyph advance widths (for SVG glyph mode).
-     *
-     * glyphAdvances are now filled by layout() automatically, so
-     * this method is equivalent to layout(). Kept for API compatibility.
+     * Layout with per-glyph advance widths filled on every text span
+     * (SVG "glyph" preset, caret hit-testing).
      */
     layoutGlyph(paragraph: Paragraph, maxWidth: number, yOffset?: number): ParagraphLayoutResult;
     /**

package/dist/layout/ParagraphLayoutEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParagraphLayoutEngine.d.ts","sourceRoot":"","sources":["../../src/layout/ParagraphLayoutEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAqCrE,qBAAa,qBAAqB;IAChC,OAAO,CAAC,aAAa,CAAyC;IAE9D;;;;;;;OAOG;IACH,MAAM,CACJ,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,MAAU,EACnB,YAAY,CAAC,EAAE,oBAAoB,EACnC,SAAS,CAAC,EAAE,SAAS,EACrB,SAAS,CAAC,EAAE,MAAM,EAClB,eAAe,CAAC,EAAE,MAAM,GACvB,qBAAqB;IA+HxB;;;;;OAKG;IACH,WAAW,CACT,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,MAAU,GAClB,qBAAqB;IAIxB;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;CAoC7B;AAED,gBAAgB;AAChB,eAAO,MAAM,qBAAqB,EAAE,qBAAmD,CAAC"}
+{"version":3,"file":"ParagraphLayoutEngine.d.ts","sourceRoot":"","sources":["../../src/layout/ParagraphLayoutEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAQrE,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AA+E1E,qBAAa,qBAAqB;IAChC,yFAAyF;IACzF,OAAO,CAAC,aAAa,CAAyC;IAC9D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,QAAQ,GAAE,MAAmC;IAIzD,mEAAmE;IACnE,UAAU,IAAI,IAAI;IAIlB;;;;;;;OAOG;IACH,MAAM,CACJ,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,MAAU,EACnB,YAAY,CAAC,EAAE,oBAAoB,EACnC,SAAS,CAAC,EAAE,SAAS,EACrB,SAAS,CAAC,EAAE,MAAM,EAClB,eAAe,CAAC,EAAE,MAAM,EACxB,iBAAiB,GAAE,OAAe,EAClC,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,EAC3B,aAAa,GAAE,aAAuB,GACrC,qBAAqB;IAgLxB;;;OAGG;IACH,WAAW,CACT,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,MAAU,GAClB,qBAAqB;IAIxB;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;CAoC7B;AAED,gBAAgB;AAChB,eAAO,MAAM,qBAAqB,EAAE,qBAAmD,CAAC"}

package/dist/layout/PositioningEngine.d.ts

@@ -18,7 +18,7 @@
 import type { ParagraphStyle, ListStyle } from '../types/Document.js';
 import type { FontMetrics } from '../types/FontTypes.js';
 import type { Line } from '../types/LayoutTypes.js';
-import type { PreparedRichInlineItem } from '../compile/DocumentCompiler.js';
+import type { PreparedRichInlineItem } from '../compile/ParagraphCompiler.js';
 interface PretextFragment {
     itemIndex: number;
     text: string;

package/dist/layout/PositioningEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PositioningEngine.d.ts","sourceRoot":"","sources":["../../src/layout/PositioningEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAgB,MAAM,sBAAsB,CAAC;AACpF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,IAAI,EAAyB,MAAM,yBAAyB,CAAC;AAC3E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAO7E,UAAU,eAAe;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IACvD,GAAG,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CACtD;AAED,UAAU,WAAW;IACnB,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CACtD;AA8CD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,WAAW,EAAE,EAC3B,KAAK,EAAE,sBAAsB,EAAE,EAC/B,aAAa,EAAE,CAAC,IAAI,EAAE,sBAAsB,KAAK,WAAW,EAC5D,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,YAAI,EAClB,IAAI,EAAE,SAAS,GAAG,QAAQ,YAAY,EACtC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,KAAK,MAAM,EACrH,GAAG,CAAC,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,SAAS,EACrB,SAAS,CAAC,EAAE,MAAM,EAClB,eAAe,CAAC,EAAE,MAAM,GACvB;IAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CA8ezC"}
+{"version":3,"file":"PositioningEngine.d.ts","sourceRoot":"","sources":["../../src/layout/PositioningEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAgB,MAAM,sBAAsB,CAAC;AACpF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,IAAI,EAAyB,MAAM,yBAAyB,CAAC;AAC3E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAK9E,UAAU,eAAe;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IACvD,GAAG,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CACtD;AAED,UAAU,WAAW;IACnB,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;CACtD;AAmDD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,WAAW,EAAE,EAC3B,KAAK,EAAE,sBAAsB,EAAE,EAC/B,aAAa,EAAE,CAAC,IAAI,EAAE,sBAAsB,KAAK,WAAW,EAC5D,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,YAAI,EAClB,IAAI,EAAE,SAAS,GAAG,QAAQ,YAAY,EACtC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,KAAK,MAAM,EACrH,GAAG,CAAC,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,SAAS,EACrB,SAAS,CAAC,EAAE,MAAM,EAClB,eAAe,CAAC,EAAE,MAAM,GACvB;IAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CA6gBzC"}

package/dist/layout/TextFrameLayoutEngine.d.ts

@@ -21,7 +21,8 @@
  *   5. If no frame.height, columns are infinite (all lines stay in column 0)
  */
 import type { TextFrame } from '../types/Document.js';
-import type { Line } from '../types/LayoutTypes.js';
+import type { Line, LayoutWarning } from '../types/LayoutTypes.js';
+import { ParagraphLayoutEngine } from './ParagraphLayoutEngine.js';
 /**
  * Result of laying out a full TextFrame.
  *
@@ -31,21 +32,89 @@ import type { Line } from '../types/LayoutTypes.js';
  */
 export interface TextFrameLayoutResult {
     lines: Line[];
-    /** 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';
+    /** Intrinsic content box — the text bounding box. */
+    content: {
+        width: number;
+        height: number;
+    };
+    /** Frame box as given on the input; an axis is omitted when its size was not set. */
+    frame: {
+        width?: number;
+        height?: number;
+    };
+    /**
+     * Whether content spills past the frame on each axis. `false` for an axis
+     * with no frame size. Use it to decide auto-grow vs clip vs autofit.
+     */
+    overflow: {
+        horizontal: boolean;
+        vertical: boolean;
+    };
+    /**
+     * Which size a renderer should use per axis: `'frame'` when a frame size was
+     * provided, otherwise `'content'`.
+     */
+    fit: {
+        horizontal: 'frame' | 'content';
+        vertical: 'frame' | 'content';
+    };
+    /** Present when autofit ran — the scale applied and whether it bottomed out. */
+    autofit?: AutofitOutcome;
+    /** Non-fatal issues (font fallback / substitution). Omitted when empty. */
+    warnings?: LayoutWarning[];
+}
+/** Options for {@link layoutTextFrame}. */
+export interface LayoutOptions {
+    /**
+     * Fill `Span.glyphAdvances` on every text span. Needed only by the SVG
+     * `glyph` preset and by caret hit-testing; off by default because it costs
+     * O(chars) font lookups + allocation on every layout.
+     */
+    glyphAdvances?: boolean;
+    /**
+     * Metric mode for this layout, overriding the provider's global mode:
+     *   - `'browser'` (default) — CSS/Chrome line-box, hhea ascent/descent
+     *   - `'office'` — PowerPoint/DrawingML line-box, OS/2 winAscent/winDescent
+     */
+    mode?: 'browser' | 'office';
+    /**
+     * Shrink every run's `fontSize` proportionally until the content fits the
+     * frame box. `true` uses defaults; an object bounds the minimum size.
+     * The chosen scale is reported on `result.autofit`.
+     */
+    autofit?: boolean | {
+        minFontSize?: number;
+    };
+    /**
+     * What to do when none of a run's `fontFamily` entries are registered:
+     *   - `'throw'` (default) — raise `FontNotFoundError`
+     *   - `'substitute'` — use any registered family and add a `result.warnings`
+     *     entry instead of failing
+     */
+    onMissingFont?: 'throw' | 'substitute';
+    /**
+     * Measure widths through fontkit's `layout()` — GPOS kerning + GSUB ligatures,
+     * i.e. what a browser paints — instead of the default per-code-point advance
+     * sum. Applies to line breaking and positioning for this call only. Leave off
+     * unless the output is consumed by a browser (SVG `browser` preset).
+     */
+    shaping?: boolean;
+}
+/** Autofit outcome, present on the result when {@link LayoutOptions.autofit} was set. */
+export interface AutofitOutcome {
+    /** Proportional font-size scale applied (1 = no shrink). */
+    scale: number;
+    /** True when the min-size floor was hit and content still overflows. */
+    clampedToMin: boolean;
 }
 /**
- * Layout a full TextFrame by stacking paragraphs with Y offset accumulation.
+ * Layout a full TextFrame (paragraphs stacked with Y-offset accumulation).
+ *
+ * Uses a shared default engine with its own bounded prepared-line cache. For
+ * isolation, an explicit cache bound, or `clearCache()`, make your own via
+ * {@link createLayoutEngine}.
  */
-export declare function layoutTextFrame(frame: TextFrame): TextFrameLayoutResult;
+export declare function layoutTextFrame(frame: TextFrame, options?: LayoutOptions): TextFrameLayoutResult;
+/** @internal Shared implementation, parameterised by the engine instance. */
+export declare function runFlow(frame: TextFrame, options: LayoutOptions, engine: ParagraphLayoutEngine): TextFrameLayoutResult;
 //# sourceMappingURL=TextFrameLayoutEngine.d.ts.map

package/dist/layout/TextFrameLayoutEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TextFrameLayoutEngine.d.ts","sourceRoot":"","sources":["../../src/layout/TextFrameLayoutEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,SAAS,EAA2C,MAAM,sBAAsB,CAAC;AAC/F,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAKpD;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,aAAa,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,aAAa,EAAE,OAAO,GAAG,SAAS,CAAC;IACnC,mEAAmE;IACnE,WAAW,EAAE,OAAO,GAAG,SAAS,CAAC;CAClC;AAmED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,qBAAqB,CAoRvE"}
+{"version":3,"file":"TextFrameLayoutEngine.d.ts","sourceRoot":"","sources":["../../src/layout/TextFrameLayoutEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,SAAS,EAA2C,MAAM,sBAAsB,CAAC;AAC/F,OAAO,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAyB,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAM1F;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,qDAAqD;IACrD,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,qFAAqF;IACrF,KAAK,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C;;;OAGG;IACH,QAAQ,EAAE;QAAE,UAAU,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC;IACrD;;;OAGG;IACH,GAAG,EAAE;QAAE,UAAU,EAAE,OAAO,GAAG,SAAS,CAAC;QAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;KAAE,CAAC;IACxE,gFAAgF;IAChF,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;CAC5B;AAmED,2CAA2C;AAC3C,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC5B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,GAAG,YAAY,CAAC;IACvC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,yFAAyF;AACzF,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,GAAE,aAAkB,GAAG,qBAAqB,CAEpG;AAED,6EAA6E;AAC7E,wBAAgB,OAAO,CACrB,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,qBAAqB,GAC5B,qBAAqB,CA0SvB"}

package/dist/layout/create-engine.d.ts

@@ -0,0 +1,32 @@
+/**
+ * create-engine.ts — a layout engine you own.
+ *
+ * `layoutTextFrame` is a convenience wrapper over a shared default engine. When
+ * you need isolation (a per-document or per-request cache), an explicit cache
+ * bound, or the ability to drop the cache, create your own:
+ *
+ * ```ts
+ * const engine = createLayoutEngine({ cache: { max: 1024 } });
+ * const result = engine.layout(frame);
+ * engine.clearCache();   // e.g. on document close
+ * ```
+ */
+import type { TextFrame } from '../types/Document.js';
+import type { LayoutOptions, TextFrameLayoutResult } from './TextFrameLayoutEngine.js';
+/** Configuration for {@link createLayoutEngine}. */
+export interface LayoutEngineOptions {
+    /** Prepared-line cache bound (LRU entries). Default 4096. */
+    cache?: {
+        max?: number;
+    };
+}
+/** A layout engine with its own prepared-line cache. */
+export interface LayoutEngine {
+    /** Lay out a full text frame. Same result shape as {@link layoutTextFrame}. */
+    layout(frame: TextFrame, options?: LayoutOptions): TextFrameLayoutResult;
+    /** Drop all cached prepared-line data. */
+    clearCache(): void;
+}
+/** Create a layout engine with an isolated, bounded prepared-line cache. */
+export declare function createLayoutEngine(options?: LayoutEngineOptions): LayoutEngine;
+//# sourceMappingURL=create-engine.d.ts.map

package/dist/layout/create-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-engine.d.ts","sourceRoot":"","sources":["../../src/layout/create-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,KAAK,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEvF,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC,6DAA6D;IAC7D,KAAK,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1B;AAED,wDAAwD;AACxD,MAAM,WAAW,YAAY;IAC3B,+EAA+E;IAC/E,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,qBAAqB,CAAC;IACzE,0CAA0C;IAC1C,UAAU,IAAI,IAAI,CAAC;CACpB;AAED,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,YAAY,CAMlF"}

package/dist/layout/resolve-font.d.ts

@@ -0,0 +1,25 @@
+/**
+ * resolve-font.ts — turn a `fontFamily` (single name or CSS-style fallback
+ * list) into one concrete registered family, per the `onMissingFont` policy.
+ *
+ * Everything downstream (positioning, rendering) sees a plain string.
+ */
+import type { FontFace } from '../measure/FontEngine.js';
+import type { LayoutWarning } from '../types/LayoutTypes.js';
+/** How to react when none of a run's requested families are registered. */
+export type OnMissingFont = 'throw' | 'substitute';
+/** Minimal provider surface this module needs. */
+export interface FontResolverLike {
+    getFont(family: string, weight?: string, style?: string): FontFace | undefined;
+    getRegisteredFamilies(): string[];
+}
+export interface ResolvedFamily {
+    family: string;
+    warning: Omit<LayoutWarning, 'runIndex'> | null;
+}
+/**
+ * @param family      run's `fontFamily`: a name, or a fallback list
+ * @param onMissing   policy when nothing matches (default `'throw'`)
+ */
+export declare function resolveFontFamily(provider: FontResolverLike, family: string | string[], weight: string, style: string, onMissing?: OnMissingFont): ResolvedFamily;
+//# sourceMappingURL=resolve-font.d.ts.map

package/dist/layout/resolve-font.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-font.d.ts","sourceRoot":"","sources":["../../src/layout/resolve-font.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,2EAA2E;AAC3E,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,YAAY,CAAC;AAEnD,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC/E,qBAAqB,IAAI,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,CAAC,GAAG,IAAI,CAAC;CACjD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,EACzB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,SAAS,GAAE,aAAuB,GACjC,cAAc,CAqBhB"}

package/dist/measure/FontEngine.d.ts

@@ -11,6 +11,15 @@
  * is removed (or when the import is not blocked by stubs).
  */
 import type { FontMetrics } from '../types/FontTypes.js';
+/**
+ * Factor used when a glyph is not present in the font.
+ * Multiplied by fontSize to estimate the missing glyph's advance.
+ *
+ * Lives here, in the fontkit facade, so every measurement path can share one
+ * definition without importing FontMetricsProvider (which installs globals as
+ * an import side effect).
+ */
+export declare const MISSING_GLYPH_FACTOR = 0.5;
 /** Opaque font face handle returned by FontEngine.create() */
 export interface FontFace {
     /** fontkit font object (private — not meant for direct access) */
@@ -27,9 +36,43 @@ export interface FontFace {
  * Create a font face from a binary buffer.
  *
  * @param buffer  Font file bytes (ArrayBuffer in browser, Uint8Array/Buffer in Node.js)
+ * @param opts.variation  For a variable font, axis values to instance before use
+ *   (e.g. `{ wght: 700, wdth: 100 }`). Ignored when the font has no axes. Every
+ *   downstream call — `glyphForCodePoint`, `layout`, metric extraction — then
+ *   sees the instanced master, matching what a browser renders for that weight.
  * @returns       Opaque FontFace handle
  */
-export declare function createFontFace(buffer: ArrayBuffer | Uint8Array): Promise<FontFace>;
+export declare function createFontFace(buffer: ArrayBuffer | Uint8Array, opts?: {
+    variation?: Record<string, number>;
+}): Promise<FontFace>;
+/** One shaped glyph: its id and its post-GPOS advance / offset, in font units. */
+export interface ShapedGlyph {
+    glyphId: number;
+    xAdvance: number;
+    xOffset: number;
+}
+/** Result of {@link shapeRun}: total advance + per-glyph detail, in font units. */
+export interface ShapedRun {
+    /** Sum of every glyph's xAdvance after kerning / ligature substitution. */
+    advanceWidth: number;
+    glyphs: ShapedGlyph[];
+}
+/**
+ * Shape `text` through fontkit's OpenType layout engine — the same GPOS kerning
+ * and GSUB substitutions (`liga`, `clig`, `calt`, `ccmp`) a browser applies by
+ * default. Use this instead of summing {@link getGlyphAdvance} when the measured
+ * width has to line up with what the browser will actually paint.
+ *
+ * Widths are in font units; multiply by `fontSize / unitsPerEm`.
+ *
+ * @param opts.features  OpenType feature overrides, e.g. `{ liga: false }` to
+ *   emulate `text-rendering: optimizeSpeed`. Omit for browser-default behaviour.
+ */
+export declare function shapeRun(font: FontFace, text: string, opts?: {
+    features?: Record<string, boolean>;
+    script?: string;
+    language?: string;
+}): ShapedRun;
 /**
  * Get the advance width (in font units) for a single code point.
  *

package/dist/measure/FontEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FontEngine.d.ts","sourceRoot":"","sources":["../../src/measure/FontEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAKzD,8DAA8D;AAC9D,MAAM,WAAW,QAAQ;IACvB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC;IACnB,kDAAkD;IAClD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAkDD;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,CAQxF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIhF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,WAAW,CAqB7G;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9D"}
+{"version":3,"file":"FontEngine.d.ts","sourceRoot":"","sources":["../../src/measure/FontEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAIzD;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAKxC,8DAA8D;AAC9D,MAAM,WAAW,QAAQ;IACvB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC;IACnB,kDAAkD;IAClD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAkDD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,WAAW,GAAG,UAAU,EAChC,IAAI,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC5C,OAAO,CAAC,QAAQ,CAAC,CAWnB;AAID,kFAAkF;AAClF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,mFAAmF;AACnF,MAAM,WAAW,SAAS;IACxB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAChF,SAAS,CAYX;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIhF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,WAAW,CAqB7G;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO9D"}

package/dist/measure/FontMetricsProvider.d.ts

@@ -14,11 +14,7 @@
  */
 import type { FontMetrics, IFontMetricsProvider } from '../types/FontTypes.js';
 import type { FontFace } from './FontEngine.js';
-/**
- * Factor used when a glyph is not found in the font.
- * Multiplied by fontSize to estimate the missing glyph width.
- */
-export declare const MISSING_GLYPH_FACTOR = 0.5;
+export { MISSING_GLYPH_FACTOR } from './FontEngine.js';
 /**
  * Font metrics provider — registers, resolves, and measures fonts.
  *
@@ -58,10 +54,6 @@ export declare class FontMetricsProvider implements IFontMetricsProvider {
     setMode(mode: 'browser' | 'office'): void;
     /** Get current measurement mode. */
     getMode(): 'browser' | 'office';
-    /**
-     * @internal Flatten the nested registry for office mode.
-     */
-    private _flattenCache;
     /**
      * Register a binary font for use with fontkit.
      *
@@ -75,6 +67,7 @@ export declare class FontMetricsProvider implements IFontMetricsProvider {
     registerFont(family: string, options: {
         weight?: string;
         style?: string;
+        variation?: Record<string, number>;
     }, source: string | ArrayBuffer | Uint8Array, sourcePath?: string): Promise<void>;
     /** @internal Internal registration logic */
     private _registerFontInternal;
@@ -117,7 +110,7 @@ export declare class FontMetricsProvider implements IFontMetricsProvider {
      *
      * @throws FontNotFoundError when font is neither registered nor available via Canvas
      */
-    getMetrics(fontFamily: string, fontSize: number, weight?: string, style?: string): FontMetrics;
+    getMetrics(fontFamily: string, fontSize: number, weight?: string, style?: string, mode?: 'browser' | 'office'): FontMetrics;
 }
 /** Singleton */
 export declare const fontMetricsProvider: FontMetricsProvider;

package/dist/measure/FontMetricsProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FontMetricsProvider.d.ts","sourceRoot":"","sources":["../../src/measure/FontMetricsProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAMhD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAyExC;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,mBAAoB,YAAW,oBAAoB;IAC9D,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAA4C;IAE5D,gEAAgE;IAChE,OAAO,CAAC,YAAY,CAAkC;IAEtD,gBAAgB;IAChB,OAAO,CAAC,IAAI,CAAmC;IAE/C,qFAAqF;IACrF,OAAO,CAAC,oBAAoB,CAA4B;IAExD,2EAA2E;IAC3E,OAAO,CAAC,cAAc,CAAoD;IAC1E,gBAAgB;IAChB,OAAO,CAAC,WAAW,CAA6E;IAEhG,wDAAwD;IACxD,OAAO,CAAC,kBAAkB;IAe1B;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,IAAI;IAWzC,oCAAoC;IACpC,OAAO,IAAI,SAAS,GAAG,QAAQ;IAI/B;;OAEG;IACH,OAAO,CAAC,aAAa;IAYrB;;;;;;;;;OASG;IACG,YAAY,CAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAC5C,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,EACzC,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC;IAUhB,4CAA4C;YAC9B,qBAAqB;IAmCnC;;;;;OAKG;IACG,2BAA2B,IAAI,OAAO,CAAC,IAAI,CAAC;IAMlD;;;;OAIG;IACH,qBAAqB,IAAI,MAAM,EAAE;IAIjC;;;;;OAKG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAO3C;;;OAGG;IACH,OAAO,CACL,MAAM,EAAE,MAAM,EACd,MAAM,SAAW,EACjB,KAAK,SAAW,GACf,QAAQ,GAAG,SAAS;IAMvB;;;OAGG;IACH,OAAO,CAAC,YAAY;IAsEpB;;;;;;;;OAQG;IACH,UAAU,CACR,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,MAAM,SAAW,EACjB,KAAK,SAAW,GACf,WAAW;CA6Ef;AAED,gBAAgB;AAChB,eAAO,MAAM,mBAAmB,EAAE,mBAA+C,CAAC"}
+{"version":3,"file":"FontMetricsProvider.d.ts","sourceRoot":"","sources":["../../src/measure/FontMetricsProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAQhD,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAyEvD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,mBAAoB,YAAW,oBAAoB;IAC9D,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAA4C;IAE5D,gEAAgE;IAChE,OAAO,CAAC,YAAY,CAAkC;IAEtD,gBAAgB;IAChB,OAAO,CAAC,IAAI,CAAmC;IAE/C,qFAAqF;IACrF,OAAO,CAAC,oBAAoB,CAA4B;IAExD,2EAA2E;IAC3E,OAAO,CAAC,cAAc,CAAoD;IAC1E,gBAAgB;IAChB,OAAO,CAAC,WAAW,CAA6E;IAEhG,wDAAwD;IACxD,OAAO,CAAC,kBAAkB;IAe1B;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,IAAI;IASzC,oCAAoC;IACpC,OAAO,IAAI,SAAS,GAAG,QAAQ;IAM/B;;;;;;;;;OASG;IACG,YAAY,CAChB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,EAChF,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,EACzC,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC;IAUhB,4CAA4C;YAC9B,qBAAqB;IAmCnC;;;;;OAKG;IACG,2BAA2B,IAAI,OAAO,CAAC,IAAI,CAAC;IAMlD;;;;OAIG;IACH,qBAAqB,IAAI,MAAM,EAAE;IAIjC;;;;;OAKG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAO3C;;;OAGG;IACH,OAAO,CACL,MAAM,EAAE,MAAM,EACd,MAAM,SAAW,EACjB,KAAK,SAAW,GACf,QAAQ,GAAG,SAAS;IAMvB;;;OAGG;IACH,OAAO,CAAC,YAAY;IAsEpB;;;;;;;;OAQG;IACH,UAAU,CACR,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,MAAM,SAAW,EACjB,KAAK,SAAW,EAChB,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,GAC1B,WAAW;CAgFf;AAED,gBAAgB;AAChB,eAAO,MAAM,mBAAmB,EAAE,mBAA+C,CAAC"}

package/dist/measure/FontkitMeasureContext.d.ts

@@ -0,0 +1,109 @@
+/**
+ * FontkitMeasureContext.ts — the measurement seam for vendored pretext.
+ *
+ * `src/vendor/pretext/measurement.js` calls `getMeasureContext()` from this
+ * module instead of reaching for a canvas 2d context. That is the whole
+ * integration: pretext only ever uses two members of the object it gets back —
+ * `ctx.font = "..."` and `ctx.measureText(s).width` — so the contract is tiny.
+ * It draws nothing, and it reads no other property (letter-spacing is pretext's
+ * own arithmetic, not the canvas attribute).
+ *
+ * Backends:
+ *
+ *   - fontkit (the default; installed by `ParagraphLayoutEngine` at module load
+ *     via `setMeasureContext(createFontkitMeasureContext(...))`) — measures from
+ *     the font tables. Same per-code-point advances and missing-glyph policy as
+ *     glyph positioning, so line breaking and positioning agree.
+ *   - canvas (`createCanvasMeasureContext`) — pretext's original behaviour, kept
+ *     only as a browser-only escape hatch via `setMeasureContext(null)`. It
+ *     needs a real `OffscreenCanvas`/`document`; in Node/Bun it now throws
+ *     rather than pulling a canvas polyfill.
+ *
+ * Shaping (kerning, ligatures via `font.layout()`) is a separate, later change.
+ * Landing it at the same time would make the snapshot delta unreadable.
+ */
+import type { FontFace } from './FontEngine.js';
+/**
+ * The slice of `CanvasRenderingContext2D` that pretext actually consumes.
+ */
+export interface MeasureContextLike {
+    font: string;
+    measureText(text: string): {
+        width: number;
+    };
+}
+/**
+ * Font lookup, structurally satisfied by `FontMetricsProvider`.
+ * Kept minimal so this module does not depend on the provider.
+ */
+export interface FontResolver {
+    getFont(family: string, weight?: string, style?: string): FontFace | undefined;
+}
+/**
+ * How widths are computed from the font tables.
+ *
+ *   - `'advance'` (default) — Σ per-code-point `advanceWidth`. Fast, and
+ *     shaping-invariant, but ignores kerning and ligatures, so it drifts from
+ *     what a browser paints (up to a few px per word on a kerned Latin font).
+ *   - `'shape'` — fontkit `layout()` advance: GPOS kerning + GSUB (`liga`,
+ *     `clig`, `calt`, `ccmp`), i.e. browser-default behaviour. Use for the SVG
+ *     `browser` preset when on-screen width has to match the layout.
+ */
+export interface MeasureProfile {
+    engine: 'advance' | 'shape';
+    /** `'shape'` only — OpenType feature overrides, e.g. `{ liga: false }`. */
+    features?: Record<string, boolean>;
+}
+/**
+ * Register a callback fired whenever {@link setMeasureProfile} changes the
+ * profile — used to drop pretext's per-segment width cache, which is keyed by
+ * text only and would otherwise serve `advance` widths to a `shape` layout.
+ */
+export declare function setProfileChangeHook(fn: (() => void) | null): void;
+/** Install the measurement profile used by every fontkit-backed measure path. */
+export declare function setMeasureProfile(next: MeasureProfile): void;
+/** The active measurement profile. */
+export declare function getMeasureProfile(): MeasureProfile;
+/**
+ * Install the measure context pretext will use.
+ *
+ * Pass `null` to fall back to canvas. Takes effect on the next measurement —
+ * unlike upstream, nothing is latched, so this is safe to flip in tests.
+ */
+export declare function setMeasureContext(ctx: MeasureContextLike | null): void;
+/** The currently installed context, or `null` when on the canvas fallback. */
+export declare function getInstalledMeasureContext(): MeasureContextLike | null;
+/**
+ * Called by vendored pretext on every measurement.
+ *
+ * Resolution is lazy and per-call rather than latched at module init, so there
+ * is no installation order to get wrong and no window in which a worker thread
+ * measures through the wrong backend.
+ */
+export declare function getMeasureContext(): MeasureContextLike;
+/**
+ * Reproduces pretext's original `getMeasureContext()`. Browser-only: needs a
+ * real `OffscreenCanvas` or `document`. Only reached after an explicit
+ * `setMeasureContext(null)`; the fontkit backend is the default everywhere.
+ */
+export declare function createCanvasMeasureContext(): MeasureContextLike;
+/**
+ * Build a measure context backed by the font tables.
+ *
+ * @param resolver - font lookup, normally the shared `fontMetricsProvider`
+ */
+/**
+ * Pixel width of `text` under `profile`. Shared by the pretext measure context
+ * and `ParagraphLayoutEngine`'s fragment measurement so line breaking and
+ * positioning never disagree.
+ *
+ *   - `advance` — Σ per-code-point `advanceWidth`, surrogate-aware, with the
+ *     `MISSING_GLYPH_FACTOR · fontSize` estimate for absent glyphs.
+ *   - `shape`   — fontkit `layout()` advance (kerning + ligatures). Missing
+ *     glyphs there fall back to the same per-code-point estimate for the
+ *     stretch that produced no advance, so the two profiles agree on
+ *     un-shapeable text.
+ */
+export declare function measurePx(raw: any, scale: number, fontSize: number, text: string, prof?: MeasureProfile): number;
+export declare function createFontkitMeasureContext(resolver: FontResolver): MeasureContextLike;
+//# sourceMappingURL=FontkitMeasureContext.d.ts.map

package/dist/measure/FontkitMeasureContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FontkitMeasureContext.d.ts","sourceRoot":"","sources":["../../src/measure/FontkitMeasureContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAMhD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;CAChF;AAID;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAKD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAElE;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAI5D;AAED,sCAAsC;AACtC,wBAAgB,iBAAiB,IAAI,cAAc,CAElD;AAOD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI,GAAG,IAAI,CAEtE;AAED,8EAA8E;AAC9E,wBAAgB,0BAA0B,IAAI,kBAAkB,GAAG,IAAI,CAEtE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,kBAAkB,CAItD;AAID;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,kBAAkB,CAW/D;AAqDD;;;;GAIG;AACH;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,cAAwB,GAC7B,MAAM,CA8BR;AAED,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,YAAY,GAAG,kBAAkB,CA+CtF"}

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

@@ -11,8 +11,13 @@
  * Exports enableOfficeTextMeasure / disableOfficeTextMeasure —
  * ctx.measureText override for FontEngine-based measurements in Office mode.
  *
- * ⚠️ All Node.js built-in module imports are dynamic (lazy) to avoid
- * Vite/Webpack externalization errors in browser builds.
+ * ⚠️ Node.js built-in module access is synchronous via process.getBuiltinModule
+ * (Node ≥20.16 / ≥22, Bun ≥1.1) to avoid top-level await race conditions
+ * in worker threads (e.g. Piscina). The previous implementation used
+ * `await import('module')` which created a race window where layoutTextFrame
+ * could be called before the polyfill initialised, returning 0×0.
+ *
+ * @see https://nodejs.org/api/process.html#processgetbuiltinmoduleid
  */
 /**
  * Register a font with @napi-rs/canvas so ctx.measureText() works in Node.js.

package/dist/measure/canvas-polyfill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"canvas-polyfill.d.ts","sourceRoot":"","sources":["../../src/measure/canvas-polyfill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAwLH;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAUzE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CASzE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAS/C"}
+{"version":3,"file":"canvas-polyfill.d.ts","sourceRoot":"","sources":["../../src/measure/canvas-polyfill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAwNH;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAUzE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CASzE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAS/C"}