@vyaz/core 0.0.16 → 0.3.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;AAyG1E,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;IAmLxB;;;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,CAohBzC"}

package/dist/layout/TableLayoutEngine.d.ts

@@ -0,0 +1,174 @@
+/**
+ * TableLayoutEngine.ts — TableFrame → positioned grid.
+ *
+ * Column widths and row heights are *measured*, not required from the caller
+ * (unlike svg-table-core, whose `calculateRows` takes them as input — see
+ * TableTypes.ts header): each cell's `TextFrame` content is laid out twice —
+ * once unconstrained to get its natural width, once at the final column width
+ * to get its wrapped height.
+ *
+ * Pipeline:
+ *   1. placeCells    — colSpan/rowSpan → each cell's (startRow, startCol),
+ *                       borrowing svg-table-core's "occupied slot" idea
+ *                       (calculateRows' insertIgnoredCell), done natively.
+ *   2. column widths  — span-1 cells set the per-column max; span>N cells only
+ *                       *widen* their spanned columns, evenly, if their own
+ *                       natural width doesn't already fit (never shrink).
+ *   3. per-cell content — laid out once at its final (possibly multi-column)
+ *                       width, inset by padding *and* border width (border-box
+ *                       model — a border never overlaps the text); same
+ *                       deficit-widen rule for row heights and rowSpan cells.
+ *   4. position        — column/row offsets accumulated from final sizes.
+ *
+ * `table.width`/`table.height` (both optional) scale the *final* colWidths/
+ * rowHeights arrays proportionally to fit, applied after whichever source
+ * produced them (measured or an explicit `columnWidths`/`rowHeights`
+ * override) — symmetric, but width-shrink reflows text via wrapping while
+ * height-shrink has no equivalent and simply overflows the row.
+ *
+ * Border dash patterns (`borderPatterns`) and per-side `stroke-linecap`
+ * (`borderShapes`) resolve here (`resolveBorder`) but paint in
+ * `@vyaz/renderer`'s `TableRenderer.ts` (`borderMarkup`) — this engine only
+ * produces the resolved per-side values. Asymmetric corner radii (only a
+ * uniform `rx`/`ry` today) remain a possible future addition.
+ *
+ * Nested tables: `TableCell.content` can be a `TableFrame` instead of a
+ * `TextFrame` (`isNestedTable`). Both the natural-width pass and the final
+ * layout pass then call `layoutTableFrame` recursively instead of
+ * `layoutTextFrame` — meaning a nested cell's own two-pass layout happens
+ * *twice* (once per outer pass), so cost roughly doubles per nesting depth.
+ * The nested `TableLayoutResult` is exposed as `TableCellLayoutResult.
+ * nestedTable`; `content` still gets a placeholder `TextFrameLayoutResult`
+ * (zero lines, sized to the nested table) so every existing consumer that
+ * reads cell dimensions off `content.content.{width,height}` keeps working
+ * unchanged — `TableRenderer.ts` checks `nestedTable` first and renders that
+ * instead of `content` when present. `_depth` is an internal recursion
+ * counter (not meant to be set by callers) — past 50 levels this throws
+ * instead of hanging, on the assumption that's a cyclic/pathological input,
+ * not a real document.
+ */
+import type { TableFrame, BorderLineCap } from '../types/TableTypes.js';
+import type { TextFrameLayoutResult } from './TextFrameLayoutEngine.js';
+import { type Side } from '../utils/sides.js';
+/** A resolved, ready-to-paint border. Absent when every side's width is `0`. */
+export interface ResolvedBorder {
+    widths: Record<Side, number>;
+    colors: Record<Side, string>;
+    /** Present only when at least one side has a non-empty dash pattern. */
+    patterns?: Record<Side, number[] | undefined>;
+    /** Present only when `borderShapes` was set anywhere in the style cascade. */
+    shapes?: Record<Side, BorderLineCap>;
+    /** Present only when `rx`/`ry` was set anywhere in the style cascade. */
+    rx?: number;
+    ry?: number;
+}
+export interface TableCellLayoutResult {
+    /** Absolute X of the cell box (border-box) within the table. */
+    x: number;
+    /** Absolute Y of the cell box within the table. */
+    y: number;
+    /** Full box width — sums every spanned column + the gaps between them. */
+    width: number;
+    /** Full box height — sums every spanned row + the gaps between them. */
+    height: number;
+    /** Resolved padding box (inside the border, if any). */
+    padding: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    /** Extra Y offset inside the padding box from `verticalAlign` (0 for `'top'`). */
+    verticalOffset: number;
+    /** `TableCellStyle.cx`/`cy` — an additional px nudge on top of padding/alignment. Default `0`. */
+    cx: number;
+    /** @see cx */
+    cy: number;
+    /** `TableCellStyle.allowOverflow` — let content paint past the cell's padding box. Default `false`. */
+    allowOverflow: boolean;
+    bgColor?: string;
+    border?: ResolvedBorder;
+    /**
+     * The cell's laid-out content — same shape a lone `TextFrame` produces.
+     * When `TableCell.content` was a `TableFrame` (see `nestedTable`), this is
+     * a zero-line placeholder sized to match it — a renderer should check
+     * `nestedTable` first and use that instead of painting `content` as text.
+     */
+    content: TextFrameLayoutResult;
+    /**
+     * Present when `TableCell.content` was a `TableFrame` — a table nested
+     * inside this cell, already laid out at the cell's own content width.
+     * `content` (above) is a same-sized placeholder in this case, not real
+     * text — paint this instead.
+     */
+    nestedTable?: TableLayoutResult;
+    /**
+     * `TableCell.before`, laid out unwrapped at its own natural size and
+     * positioned absolute-within-the-table, already vertically centered.
+     * Absent when the cell has no `before`.
+     */
+    before?: {
+        content: TextFrameLayoutResult;
+        x: number;
+        y: number;
+    };
+    /** @see before — from `TableCell.after`, right-anchored instead. */
+    after?: {
+        content: TextFrameLayoutResult;
+        x: number;
+        y: number;
+    };
+    /** Columns this cell occupies (>1 for `colSpan`). */
+    colSpan: number;
+    /** Rows this cell occupies (>1 for `rowSpan`). */
+    rowSpan: number;
+}
+export interface TableRowLayoutResult {
+    y: number;
+    height: number;
+    bgColor?: string;
+    border?: ResolvedBorder;
+    /** Only cells that *start* in this row (a rowSpan cell from above is not repeated here). */
+    cells: TableCellLayoutResult[];
+}
+export interface TableLayoutResult {
+    /** Full outer box width, margins included. */
+    width: number;
+    /** Full outer box height, margins included. */
+    height: number;
+    bgColor?: string;
+    /** The table's own outer border (`TableStyle`), distinct from row/cell borders. */
+    border?: ResolvedBorder;
+    /**
+     * The border-box — the outer box with `TableStyle.margins` excluded. Rows
+     * span its full width; `border` (above) is drawn at this box. A renderer
+     * uses it directly instead of re-deriving margins from row/cell positions.
+     */
+    contentBox: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    rows: TableRowLayoutResult[];
+}
+export interface TableLayoutOptions {
+    mode?: 'browser' | 'office';
+    /**
+     * What to do when a cell's `fontFamily` isn't registered — forwarded to
+     * every cell's own `layoutTextFrame` call. `'throw'` (default) raises
+     * `FontNotFoundError`; `'substitute'` uses any registered family and folds
+     * the cell's own warnings into the table's (none surfaced directly here —
+     * a caller wanting them should lay out a cell's `TextFrame` itself).
+     */
+    onMissingFont?: 'throw' | 'substitute';
+    /**
+     * Internal nested-table recursion counter — do not set this yourself.
+     * `layoutTableFrame` increments it on every recursive call (a `TableCell`
+     * whose `content` is itself a `TableFrame`) and throws past 50 levels.
+     * @internal
+     */
+    _depth?: number;
+}
+export declare function layoutTableFrame(table: TableFrame, options?: TableLayoutOptions): TableLayoutResult;
+//# sourceMappingURL=TableLayoutEngine.d.ts.map

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

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

package/dist/layout/TextFrameLayoutEngine.d.ts

@@ -20,8 +20,9 @@
  *   4. If frame.height is set, lines overflow to next column when colHeight exceeded
  *   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 { TextFrame, WritingMode } from '../types/Document.js';
+import type { Line, LayoutWarning } from '../types/LayoutTypes.js';
+import { ParagraphLayoutEngine } from './ParagraphLayoutEngine.js';
 /**
  * Result of laying out a full TextFrame.
  *
@@ -31,21 +32,119 @@ 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;
+    /**
+     * Block flow direction this layout was produced for — echoes
+     * `TextFrame.writingMode`, defaulting to `'horizontal-tb'`.
+     */
+    writingMode: WritingMode;
+    /**
+     * Post-layout rigid transform to realise `writingMode: 'sideways-*'` and/or
+     * `TextFrame.rotation`. Omitted when the net rotation is a multiple of 360°
+     * (nothing to apply). `lines`, `content` bbox aside, live in pre-rotation
+     * layout space; `content` / `overflow` are reported in **visual** space.
+     */
+    transform?: FrameTransform;
+    /** Non-fatal issues (font fallback / substitution). Omitted when empty. */
+    warnings?: LayoutWarning[];
 }
 /**
- * Layout a full TextFrame by stacking paragraphs with Y offset accumulation.
+ * Rigid transform a renderer applies to {@link TextFrameLayoutResult.lines} so a
+ * `sideways-*` writing mode or an explicit `rotation` takes visual effect. The
+ * layout math itself (line breaking, measuring, positioning) is unchanged.
  */
-export declare function layoutTextFrame(frame: TextFrame): TextFrameLayoutResult;
+export interface FrameTransform {
+    /** Net clockwise rotation in degrees, normalised to `[0, 360)`. */
+    rotate: number;
+    /**
+     * The box `lines` occupy in their own pre-rotation coordinate space. The
+     * renderer rotates this box about its centre; for `rotate` of 90 / 270 the
+     * visible canvas is this box with width and height swapped.
+     */
+    layoutBox: {
+        width: number;
+        height: number;
+    };
+}
+/** 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 (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, 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,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC5G,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;;;OAGG;IACH,WAAW,EAAE,WAAW,CAAC;IACzB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9C;AAyED,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,CAoVvB"}

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"}