@betteroffice/docx 0.0.1

package/dist/layout/index.d.mts

@@ -0,0 +1,307 @@
+export { ToLayoutBlocksOptions, convertBorderSpecToLayout, demoteBlockLikeFloatingTables, isBlockLikeFloatingTable, resetBlockIdCounter, resolveListTemplate, toLayoutBlocks } from './flow/index.mjs';
+import { ao as TableBlock, P as PageMargins, e as LayoutBlock, H as HeaderFooterContent, B as BlockExtent, ar as TableExtent, C as ColumnLayout } from '../types-DNrYr6yQ.mjs';
+export { F as FloatPageGeometry, a as FloatingExclusionRect, b as FloatingImageZone, c as FloatingLineSegmentZone, M as MeasureBlockFn, d as clampFloatingWrapMargins, g as getFloatingMargins, m as measureBlocksWithFloats, r as rectsToFloatingZones } from '../measureBlocksPipeline-Df0Bbrwy.mjs';
+export { BundledFontProvider, EmbeddedFaceInput, FontScript, FontStyle, RustMeasureSource, RustMeasureStats, RustTextEngine, createRustMeasureSource, getRustTextEngine, hashParagraphBlock } from './measure/index.mjs';
+export { C as ConvertFootnoteOptions, a as ConvertHeaderFooterOptions, F as FOOTNOTE_COLUMN_GAP_PX, b as FOOTNOTE_SEPARATOR_HEIGHT, c as FootnoteRefLocation, H as HeaderFooterMetrics, M as MAX_FOOTNOTE_LAYOUT_PASSES, d as MeasureBlocksFn, S as StabilizeFootnoteLayoutArgs, e as StabilizeFootnoteLayoutResult, f as applyFootnotePresentation, g as buildFootnoteContentMap, h as buildFootnoteRenderItems, i as calculateFootnoteReservedHeights, j as calculateHeaderFooterVisualBounds, k as collectFootnoteRefs, l as computeHfCaretRectsFromDisplayList, m as computeHfSelectionRectsFromDisplayList, n as contributesToHeaderFooterFlowHeight, o as convertFootnoteToContent, p as convertHeaderFooterToContent, q as distributeFootnotesIntoColumns, r as footnoteReservedHeightsEqual, s as mapFootnotesToPages, t as normalizeHeaderFooterMeasureBlocks, u as resolveHeaderFooterVisualTop, v as stabilizeFootnoteLayout } from '../headerFooterLayout-0zPT64Qc.mjs';
+import { S as SectionLayoutConfig } from '../sectionConfigs-DW3J8q0X.mjs';
+import { Document } from '../types/document.mjs';
+import { S as SectionProperties, m as HeaderFooter } from '../content-sSHuWw49.mjs';
+import '../editorTree-DO5PyDK8.mjs';
+import '../formatting-DoL7KBSL.mjs';
+import '../settingsParser-CcGvtmCK.mjs';
+import '../styles-VxNcXLdi.mjs';
+import '../measuredBlock-DZwz8zhD.mjs';
+import '../displayListQueries-p-ijSzdh.mjs';
+import '../rustDisplayList-dqunvwxH.mjs';
+import '../docx/wrapTypes.mjs';
+
+/**
+ * @internal Helpers for resolving DOCX table-width metadata into pixel widths.
+ */
+
+/**
+ * Resolve a DOCX width pair to pixels. `pct` values are 50ths of a percent
+ * (ECMA-376 §17.18.111 — 5000 means 100%). `dxa` / `auto` / unset are twips.
+ *
+ * @internal
+ */
+declare function resolveTableWidthPx(value: number | undefined, widthType: string | undefined, parentWidth: number): number | undefined;
+/** A cell with its resolved grid position (column index honoring spans). */
+interface ResolvedGridCell {
+    rowIndex: number;
+    cellIndex: number;
+    columnIndex: number;
+    colSpan: number;
+    rowSpan: number;
+}
+/**
+ * Resolve every cell's grid column index, accounting for `colSpan` and the
+ * columns occupied by vertically-merged (`rowSpan`) cells from earlier rows.
+ *
+ * Single source of truth for table grid geometry — the measurer, the painter,
+ * and the row-break paginator all consume this so they agree on which column a
+ * cell lives in. Width-free on purpose: callers multiply `columnIndex` by their
+ * own (possibly scaled) column widths to get an x offset.
+ *
+ * @internal
+ */
+declare function resolveCellGrid(tableBlock: TableBlock): ResolvedGridCell[];
+/** Total grid columns, derived from the widest row's accumulated colSpans. */
+declare function countTableColumns(tableBlock: TableBlock): number;
+/**
+ * Make `columnWidths` exactly `colCount` long with every entry positive.
+ * Missing trailing columns inherit the average of existing positives; zero
+ * or negative entries split the leftover `targetWidth` evenly. Callers
+ * scale down totals that exceed the target — this helper only fills gaps.
+ */
+declare function normalizeTableColumnWidths(columnWidths: number[], colCount: number, targetWidth: number): number[];
+/**
+ * Resolve a table's per-column pixel widths from its grid metadata and width
+ * budget — the width half of `measureTableBlock`, with NO cell-content
+ * measurement. Factored out so a caller that only needs widths (e.g. deciding
+ * whether a floating table is effectively full-width, before the main measure
+ * pass) doesn't have to measure every cell.
+ *
+ * @internal
+ */
+declare function resolveTableColumnWidths(tableBlock: TableBlock, contentWidth: number): number[];
+/**
+ * Total pixel width of a table — sum of its resolved column widths, falling
+ * back to the explicit table width or the content-width budget. No cell-content
+ * measurement, so it is safe to call before the main measure pass. Mirrors the
+ * `totalWidth` that `measureTableBlock` produces.
+ *
+ * @internal
+ */
+declare function resolveTableTotalWidthPx(tableBlock: TableBlock, contentWidth: number): number;
+
+/**
+ * Selection-overlay geometry value types, shared by the canvas overlays and
+ * the display-list queries (`selectionToRectsFromDisplayList` /
+ * `getCaretPositionFromDisplayList`).
+ *
+ * @packageDocumentation
+ * @public
+ */
+/**
+ * A rectangle representing part of a selection.
+ *
+ * @public
+ */
+type SelectionRect = {
+    /** X coordinate in container space. */
+    x: number;
+    /** Y coordinate in container space. */
+    y: number;
+    /** Width of the rectangle. */
+    width: number;
+    /** Height of the rectangle (typically line height). */
+    height: number;
+    /** Page index (0-based). */
+    pageIndex: number;
+};
+/**
+ * Caret position for collapsed selection.
+ *
+ * @public
+ */
+type CaretPosition = {
+    /** X coordinate in container space. */
+    x: number;
+    /** Y coordinate in container space. */
+    y: number;
+    /** Height of the caret (line height). */
+    height: number;
+    /** Page index (0-based). */
+    pageIndex: number;
+};
+
+/**
+ * Header/footer body-margin extension.
+ *
+ * Word grows the header (or footer) band when its in-flow content is taller
+ * than the authored top (or bottom) margin minus the header/footer distance,
+ * pushing the body text down (or up). This module owns that computation so the
+ * React and Vue adapters share one implementation instead of byte-identical
+ * inline copies (the layout pipelines were drifting candidates — see
+ * `docx-editor` engine-unification work, issue #696).
+ *
+ * Two correctness rules live here:
+ *
+ *  1. The band height is driven by `HeaderFooterContent.flowHeight` (in-flow
+ *     content only), NOT `height` / `visualBottom`. A page/margin-anchored
+ *     float — e.g. a full-page letterhead anchored in a header — is positioned
+ *     on the page and does not push the body in Word. Counting it inflated the
+ *     effective top margin past the page on real-world templates, so the
+ *     paginator hard-threw "page size and margins yield no content area" and
+ *     the document rendered blank (issue #705).
+ *
+ *  2. A clamp guarantees `top + bottom` never consumes the whole page, so a
+ *     pathological in-flow header degrades to a thin content band with a
+ *     warning instead of aborting pagination.
+ */
+
+/** @public */
+interface ExtendMarginsForHeaderFooterInput {
+    pageSize: {
+        w: number;
+        h: number;
+    };
+    /** Body fallback margins. */
+    margins: PageMargins;
+    /** Final-section margins (last `sectPr`). */
+    finalMargins: PageMargins;
+    /**
+     * Body flow blocks. Each `sectionBreak` block's `margins` is extended IN
+     * PLACE so multi-section documents paginate with the same band growth (the
+     * layout engine prefers `sectionBreak.margins` over the body fallback).
+     */
+    bodyBlocks?: LayoutBlock[];
+    /** Header variants in play this layout (e.g. default + first-page). */
+    headers?: Array<HeaderFooterContent | undefined>;
+    /** Footer variants in play this layout. */
+    footers?: Array<HeaderFooterContent | undefined>;
+    /** Optional diagnostic sink for the clamp (adapters pass `console.warn`). */
+    warn?: (message: string) => void;
+}
+/** @public */
+interface ExtendMarginsForHeaderFooterResult {
+    margins: PageMargins;
+    finalMargins: PageMargins;
+}
+/**
+ * Extend body margins so the body clears the header/footer bands, mirroring
+ * Word. Returns new `margins` / `finalMargins`; mutates `sectionBreak.margins`
+ * in place. When no extension is needed the original objects are returned
+ * unchanged.
+ *
+ * @public
+ */
+declare function extendMarginsForHeaderFooter(input: ExtendMarginsForHeaderFooterInput): ExtendMarginsForHeaderFooterResult;
+
+/** Coordinates selection paint with the latest completed layout sequence. */
+declare class LayoutSelectionGate {
+    #private;
+    setStateSeq(sequence: number): void;
+    incrementStateSeq(): number;
+    getStateSeq(): number;
+    getRenderSeq(): number;
+    onLayoutStart(): void;
+    onLayoutComplete(sequence: number): void;
+    isSafeToRender(): boolean;
+    requestRender(): void;
+    onRender(callback: () => void): () => void;
+    reset(): void;
+    getDebugInfo(): {
+        stateSeq: number;
+        renderSeq: number;
+        layoutUpdating: boolean;
+        hasPendingRender: boolean;
+        isSafe: boolean;
+    };
+}
+
+/**
+ * Shared table measurement helper.
+ *
+ * Both React's PagedEditor and Vue's useDocxEditor measure tables the
+ * same way: resolve column widths through `tableWidthUtils`, track
+ * column occupancy across vertically merged cells, then call back into
+ * the adapter's `measureBlock` for each cell's contained blocks.
+ *
+ * This module lives in core (not in either adapter) so a fix on one
+ * side automatically applies to both. The recursive cell-content
+ * measurement is delegated to the caller via `measureBlock` because
+ * each adapter's block coverage differs (React supports floating
+ * zones, footnotes, textBoxes; Vue is a subset).
+ */
+
+/**
+ * Visual height of a single block inside a table cell.
+ *
+ * A one-line paragraph that contains only image runs is laid out at the
+ * image's intrinsic height (plus the paragraph's explicit spacing), not
+ * a full text line — matching Word's per-cell layout. Everything else
+ * uses the measured `totalHeight` / `height`.
+ */
+declare function measureTableCellBlockVisualHeight(block: LayoutBlock, blockMeasure: BlockExtent): number;
+/**
+ * measure a `TableBlock` against a content-width budget: resolve the column
+ * grid, measure every cell's blocks, then size rows — with vertically merged
+ * cells distributing their surplus height in a second pass.
+ *
+ * `measureBlock` is the per-cell-content callback; the adapter supplies its
+ * own so block coverage stays per-renderer.
+ */
+declare function measureTableBlock(tableBlock: TableBlock, contentWidth: number, measureBlock: (block: LayoutBlock, contentWidth: number) => BlockExtent): TableExtent;
+
+/**
+ * Section-properties → page geometry helpers.
+ *
+ * Both adapters need the same translation from `SectionProperties` (twips
+ * + DOCX field names) into the layout engine's pixel-shaped `PageSize`
+ * and `PageMargins`. Living in core eliminates the subtle React/Vue
+ * drift that grows when each adapter ships its own twipsToPixels math.
+ */
+
+/** US Letter at 96 DPI — Word's default page size. */
+declare const DEFAULT_PAGE_WIDTH_PX = 816;
+/** US Letter at 96 DPI. */
+declare const DEFAULT_PAGE_HEIGHT_PX = 1056;
+/** 1 inch at 96 DPI — Word's default body margins. */
+declare const DEFAULT_BODY_MARGIN_PX = 96;
+/** Word's default `headerDistance` / `footerDistance` (0.5in = 48px). */
+declare const DEFAULT_HF_DISTANCE_PX = 48;
+/** Convert twips to pixels (1 twip = 1/20 point, 96 pixels per inch). */
+declare function twipsToPixels(twips: number): number;
+/**
+ * Convert SectionProperties page size (twips) → pixel `{ w, h }`.
+ *
+ * Page size is a SIZE: a literal `0` (malformed `w:pgSz`) defaults to Letter
+ * rather than rendering a zero-area page — so the truthy guard is intentional
+ * here (contrast `getMargins`, where `0` is honored). See `twipsToPxOr`.
+ */
+declare function getPageSize(sp: SectionProperties | null | undefined): {
+    w: number;
+    h: number;
+};
+/**
+ * Convert SectionProperties margins (twips) → pixel `PageMargins`.
+ *
+ * Every distance is an OFFSET, so an explicit `0` is honored (full-bleed body
+ * margins; a header/footer pinned to the page edge — issue #740). Only an
+ * ABSENT distance falls back to Word's default. `header`/`footer` default to
+ * 48px (Word's 0.5in) so the HF margin-extension math needn't special-case
+ * undefined.
+ */
+declare function getMargins(sp: SectionProperties | null | undefined): PageMargins;
+/**
+ * Resolve the HeaderFooter pair (default + first-page) for a section.
+ *
+ * Mirrors React's lookup in DocxEditor.tsx: read `pkg.headers`/`footers`
+ * (Maps keyed by rId), resolve through `sp.headerReferences` /
+ * `footerReferences`. When `titlePg` is unset and only `first` HFs
+ * exist, they serve as the default — same Word fallback both adapters
+ * have shipped.
+ */
+declare function resolveHeaderFooter(doc: Document | null, sp: SectionProperties | null | undefined): {
+    header: HeaderFooter | null;
+    footer: HeaderFooter | null;
+    firstHeader: HeaderFooter | null;
+    firstFooter: HeaderFooter | null;
+};
+/**
+ * Extract column layout from section properties.
+ * Returns undefined for single-column (default) to avoid unnecessary paginator overhead.
+ */
+declare function getColumns(sectionProps: SectionProperties | null | undefined): ColumnLayout | undefined;
+declare function columnWidthForSection(config: SectionLayoutConfig): number;
+/**
+ * Compute per-block measurement widths by scanning for section breaks.
+ * Blocks must be measured with the page width/margins/columns of their own
+ * section so that the layout engine can paginate them against the right
+ * geometry without remeasuring.
+ */
+declare function computePerBlockWidths(blocks: LayoutBlock[], initialConfig: SectionLayoutConfig, finalConfig: SectionLayoutConfig): number[];
+
+export { type CaretPosition, DEFAULT_BODY_MARGIN_PX, DEFAULT_HF_DISTANCE_PX, DEFAULT_PAGE_HEIGHT_PX, DEFAULT_PAGE_WIDTH_PX, type ExtendMarginsForHeaderFooterInput, type ExtendMarginsForHeaderFooterResult, LayoutSelectionGate, type ResolvedGridCell, type SelectionRect, columnWidthForSection, computePerBlockWidths, countTableColumns, extendMarginsForHeaderFooter, getColumns, getMargins, getPageSize, measureTableBlock, measureTableCellBlockVisualHeight, normalizeTableColumnWidths, resolveCellGrid, resolveHeaderFooter, resolveTableColumnWidths, resolveTableTotalWidthPx, resolveTableWidthPx, twipsToPixels };

package/dist/layout/index.mjs

@@ -0,0 +1 @@
+export{A as DEFAULT_BODY_MARGIN_PX,B as DEFAULT_HF_DISTANCE_PX,z as DEFAULT_PAGE_HEIGHT_PX,y as DEFAULT_PAGE_WIDTH_PX,b as FOOTNOTE_COLUMN_GAP_PX,a as FOOTNOTE_SEPARATOR_HEIGHT,x as LayoutSelectionGate,c as MAX_FOOTNOTE_LAYOUT_PASSES,h as applyFootnotePresentation,k as buildFootnoteContentMap,o as buildFootnoteRenderItems,m as calculateFootnoteReservedHeights,s as calculateHeaderFooterVisualBounds,f as collectFootnoteRefs,H as columnWidthForSection,u as computeHfCaretRectsFromDisplayList,v as computeHfSelectionRectsFromDisplayList,I as computePerBlockWidths,r as contributesToHeaderFooterFlowHeight,i as convertFootnoteToContent,t as convertHeaderFooterToContent,l as distributeFootnotesIntoColumns,w as extendMarginsForHeaderFooter,d as footnoteReservedHeightsEqual,G as getColumns,E as getMargins,D as getPageSize,g as mapFootnotesToPages,p as normalizeHeaderFooterMeasureBlocks,F as resolveHeaderFooter,q as resolveHeaderFooterVisualTop,n as stabilizeFootnoteLayout,C as twipsToPixels}from'../chunk-P3KDV4M2.mjs';export{h as createRustMeasureSource,e as getRustTextEngine,d as hashParagraphBlock,c as measureBlocksWithFloats,b as measureTableBlock,a as measureTableCellBlockVisualHeight}from'../chunk-7DEIW7FL.mjs';export{a as convertBorderSpecToLayout,e as demoteBlockLikeFloatingTables,d as isBlockLikeFloatingTable,b as resolveListTemplate,c as toLayoutBlocks}from'../chunk-IL5JZJT7.mjs';export{d as resetBlockIdCounter}from'../chunk-GWKJ2Y4Y.mjs';export{g as clampFloatingWrapMargins,c as countTableColumns,i as getFloatingMargins,d as normalizeTableColumnWidths,h as rectsToFloatingZones,b as resolveCellGrid,e as resolveTableColumnWidths,f as resolveTableTotalWidthPx,a as resolveTableWidthPx}from'../chunk-52GB3Y42.mjs';import'../chunk-7PCO5I2O.mjs';import'../chunk-X4XDO3LZ.mjs';import'../chunk-L5ISVQ3W.mjs';import'../chunk-OMR3TWCD.mjs';import'../chunk-XWUOLYRQ.mjs';import'../chunk-HJGAQIU7.mjs';import'../chunk-FZIA7OFY.mjs';import'../chunk-OBQGPMPQ.mjs';import'../chunk-3UBMCDME.mjs';import'../chunk-FPZBTOD6.mjs';import'../chunk-H3JCIGWK.mjs';import'../chunk-SINEY6ZF.mjs';import'../chunk-T4EZMUXM.mjs';import'../chunk-TTRUPDAB.mjs';

package/dist/layout/measure/index.d.mts

@@ -0,0 +1,324 @@
+import { M as MeasureBlockFn } from '../../measureBlocksPipeline-Df0Bbrwy.mjs';
+export { F as FloatPageGeometry, a as FloatingExclusionRect, b as FloatingImageZone, c as FloatingLineSegmentZone, d as clampFloatingWrapMargins, g as getFloatingMargins, m as measureBlocksWithFloats, r as rectsToFloatingZones } from '../../measureBlocksPipeline-Df0Bbrwy.mjs';
+import { C as CompatibilityFlags } from '../../settingsParser-CcGvtmCK.mjs';
+import { e as LayoutBlock, a1 as ParagraphBlock } from '../../types-DNrYr6yQ.mjs';
+import '../../content-sSHuWw49.mjs';
+import '../../formatting-DoL7KBSL.mjs';
+import '../../docx/wrapTypes.mjs';
+
+/**
+ * Script bucket a fallback face provides glyph coverage for. Han text is
+ * region-resolved by the caller (SC/TC/JP/KR — see `rustMeasureSource.ts`);
+ * kana, Hangul, Arabic and Hebrew detect directly.
+ *
+ * @public
+ */
+type FontScript = 'cjk-sc' | 'cjk-tc' | 'cjk-jp' | 'cjk-kr' | 'arabic' | 'hebrew';
+/**
+ * Resolver for the bundled metric-compatible set (Carlito↔Calibri,
+ * Liberation↔Arial/Times/Courier, …). Returns a lazy byte loader so the
+ * (lazily fetched, same-origin) binary is only downloaded when a document
+ * actually needs the face, or `undefined` when the family has no bundled
+ * substitute.
+ *
+ * @public
+ */
+interface BundledFontProvider {
+    /** Resolve a Word family to bundled metric-compatible face byte loaders, or undefined. */
+    resolve(family: string, bold: boolean, italic: boolean): (() => Promise<ArrayBuffer>) | undefined;
+    /**
+     * Optional per-script coverage fallback (Noto CJK/RTL faces). Same loader
+     * contract as {@link BundledFontProvider.resolve}; providers without
+     * script faces simply omit the method. These faces are coverage fallbacks
+     * first, metric approximations second — CJK metric compatibility is much
+     * weaker than the Carlito/Calibri class of substitutes.
+     */
+    resolveScriptFallback?(script: FontScript, bold: boolean, italic: boolean): (() => Promise<ArrayBuffer>) | undefined;
+    /**
+     * The always-available last-resort base face (broad-coverage Latin —
+     * Liberation Sans/Serif per serif-ness). Unlike {@link
+     * BundledFontProvider.resolve}, a conforming provider (e.g.
+     * `@betteroffice/docx-fonts`'s `resolveLastResortFace`) returns a loader for
+     * EVERY family, so the chain this registry builds is guaranteed non-empty
+     * and a run never routes to the browser measurer for want of font bytes. The
+     * face's metrics are the base font's, not the requested family's — the
+     * accepted divergence for a truly-unknown font, in exchange for staying on
+     * the native measurement path.
+     *
+     * Optional so mock/partial providers can omit it; when absent (or returning
+     * undefined) an unmapped family still yields an empty chain and the caller
+     * browser-falls-back that run — the pre-policy behavior. Same lazy loader
+     * contract as {@link BundledFontProvider.resolve}.
+     */
+    resolveLastResort?(family: string, bold: boolean, italic: boolean): (() => Promise<ArrayBuffer>) | undefined;
+}
+/**
+ * One embedded face extracted from the open document. Structurally identical
+ * to `EmbeddedFontFace` (`utils/embeddedFonts.ts`), so the output of
+ * `getEmbeddedFontFaces` feeds straight in; duplicated here so this module
+ * stays decoupled from the loader.
+ *
+ * @public
+ */
+interface EmbeddedFaceInput {
+    /** Word font name the face is registered under (attacker-controlled). */
+    family: string;
+    /** `'bold'` for the embedBold/embedBoldItalic slots, else `'normal'`. */
+    weight: 'normal' | 'bold';
+    /** `'italic'` for the embedItalic/embedBoldItalic slots, else `'normal'`. */
+    style: 'normal' | 'italic';
+    /** De-obfuscated OpenType/TrueType bytes. */
+    data: ArrayBuffer;
+    /** Whether the source face was subsetted (`w:subsetted`). */
+    subsetted: boolean;
+}
+
+/**
+ * The Rust measurement source — the SOLE text/layout measurement path. Every
+ * block kind is measured here: paragraphs through the wasm `docx-text` engine
+ * (Word metrics), tables/text boxes/shapes by pure recursion through the same
+ * measurer, and image/chart/break extents synthesized from declared
+ * dimensions. There is no browser `measureText` anywhere in layout.
+ *
+ * Division of labor:
+ *  - {@link TextMeasureFontRegistry} (owned here) turns Word font requests
+ *    into ordered engine font-id chains from embedded + bundled bytes, and
+ *    resolves the shared per-script coverage fallbacks (CJK/RTL Noto faces).
+ *    Resolution is deterministic: embedded faces → bundled metric-compatible
+ *    face → always-available last-resort base face; never OS/local fonts.
+ *  - {@link RustMeasureSource.prepareFonts} is the ONLY async step: it warms
+ *    the registry for every (family, bold, italic) combo a block list uses,
+ *    plus the script fallbacks for every script detected in the blocks'
+ *    text — and for every request an earlier measure pass found unresolved
+ *    (header/footer and footnote paragraphs reach measurement without
+ *    passing through the adapters' block notifications; recording their
+ *    misses here closes that gap). Call sites re-layout after it resolves.
+ *  - {@link RustMeasureSource.createMeasureBlock} builds the sync
+ *    `MeasureBlockFn` the float pipeline consumes. Paragraph blocks whose
+ *    font chains are cached go to the engine — float-zoned blocks included,
+ *    with the zones and cumulative Y passed through in the envelope.
+ *
+ * READINESS GATE (how measurement never races an unloaded face): a paragraph
+ * whose font chain (or script fallback) has not settled yet measures as a
+ * deterministic SYNTHETIC extent and records the miss;
+ * {@link RustMeasureSource.hasPendingFonts} then reports true, the adapter
+ * discards that provisional pass instead of committing it, and re-runs the
+ * pipeline when `prepareFonts` settles. Once settled, `font-unready` can
+ * never recur for those chains (the sync registry view is populated), so
+ * committed layouts are always measured against real, loaded font bytes.
+ *
+ * SELF-SUFFICIENT FONTS: every family chain the registry builds terminates in
+ * an always-available last-resort base face (broad-coverage Liberation
+ * Sans/Serif per serif-ness, supplied by the bundled provider's
+ * `resolveLastResort`), and the per-script Noto fallback is appended whenever
+ * a covered script is detected. A run whose family has no embedded/bundled
+ * match — or a character outside the family chain's coverage — still has real
+ * font bytes to measure with; the engine substitutes the terminal face's
+ * `.notdef` for genuinely uncovered characters. For a truly-unknown font the
+ * measured metrics are the base font's, not the requested family's — the
+ * accepted, deterministic substitution tradeoff.
+ *
+ * SYNTHETIC extents (deterministic pure arithmetic, no font tables, no
+ * platform state) stand in for exactly two residual cases: (a) an engine
+ * refusal — degenerate/attacker-crafted input tripping the security clamps,
+ * or a malformed payload; (b) a chain that SETTLED EMPTY, which can only
+ * happen when the host injects no bundled provider (`resolveLastResort`
+ * guarantees non-empty chains otherwise) and the document embeds nothing for
+ * the family. Both are counted in {@link RustMeasureStats}.
+ *
+ * Script fallbacks: runs are scanned for Unicode script ranges — kana → JP,
+ * Hangul → KR, Arabic → arabic, Hebrew → hebrew — and Han is region-resolved:
+ * kana in the same block wins (Japanese text), else the document's
+ * `w:themeFontLang` eastAsia hint ({@link RustMeasureSource.setScriptHints}),
+ * else Hangul in the block (hanja), else SC. The resolved script ids are
+ * appended AFTER the family faces of every chain the block uses, so the
+ * family face keeps supplying metrics/Latin glyphs and the script face only
+ * covers what the family face cannot. RTL text measures natively (the engine
+ * splits UBA level runs before shaping).
+ *
+ * @packageDocumentation
+ * @public
+ */
+
+/**
+ * Font styling properties for a short-text measurement request (the
+ * `measureTextWidthWithActiveRustSource` latch and tab-leader glyph
+ * sizing).
+ *
+ * @public
+ */
+interface FontStyle {
+    fontFamily?: string;
+    /** In points. */
+    fontSize?: number;
+    bold?: boolean;
+    italic?: boolean;
+    /** In pixels. */
+    letterSpacing?: number;
+}
+/**
+ * Thin sync facade over the wasm measure exports (`register_measure_font`,
+ * `clear_measure_fonts`, `measure_paragraph_json`). Injectable so unit tests
+ * can script responses without loading wasm.
+ *
+ * @public
+ */
+interface RustTextEngine {
+    /** Register raw sfnt bytes; returns the engine font id. Throws on bad bytes. */
+    registerFont(bytes: Uint8Array): number;
+    /** Drop every registered font (ids restart at 0). */
+    clearFonts(): void;
+    /**
+     * Measurement input JSON in, `ParagraphExtent` JSON out. Throws with a
+     * message starting `UNSUPPORTED:` for blocks the engine cannot measure.
+     */
+    measureParagraphJson(input: string): string;
+}
+/**
+ * Lazily load the embedded wasm module and expose its measure surface as a
+ * {@link RustTextEngine}. The dynamic `import()` keeps the ~800KB base64
+ * module out of the default bundle — only callers that actually enable Rust
+ * measurement pay for it (same pattern as the display-list builder's
+ * `loadEngine`).
+ *
+ * @public
+ */
+declare function getRustTextEngine(): Promise<RustTextEngine>;
+/** Counters for the debug log line (rust vs synthetic per layout pass). */
+interface RustMeasureStats {
+    /** Paragraph blocks measured by the Rust engine (including memo hits). */
+    rustMeasured: number;
+    /** Paragraphs that measured as a synthetic extent — sum of the reasons below. */
+    syntheticFallback: number;
+    /**
+     * Synthetic extents caused by a font chain (or script fallback) not having
+     * resolved yet. Transient by construction: the miss is recorded, the
+     * adapter discards the pass (`hasPendingFonts`), and the fonts-settled
+     * re-layout measures natively — so no COMMITTED layout ever contains one,
+     * and this MUST hold constant once `prepareFonts` settles.
+     */
+    syntheticFontUnready: number;
+    /**
+     * Synthetic extents caused by an engine glyph-coverage refusal. Dormant —
+     * chains terminate in a last-resort face whose `.notdef` the shaper
+     * substitutes — but kept so a coverage regression is categorized rather
+     * than lumped in with `non-font` refusals.
+     */
+    syntheticUncovered: number;
+    /**
+     * Synthetic-extent counts by `LayoutBlock.kind`. The audit counter proving
+     * text-bearing block kinds (`paragraph`, `table`, `textBox`) measure
+     * natively once fonts are ready.
+     */
+    syntheticBlockKinds: Record<string, number>;
+}
+/**
+ * The selectable measurement source. Create with
+ * {@link createRustMeasureSource}; see the module doc for the contract.
+ *
+ * @public
+ */
+interface RustMeasureSource {
+    /** Feed the open document's embedded faces (invalidates the measure memo). */
+    setEmbeddedFaces(faces: EmbeddedFaceInput[]): void;
+    /**
+     * Thread the document's compat flags (`w:compat`) into every subsequent
+     * engine call. Pass `undefined` to reset to all-off defaults. The memo key
+     * includes the flags, so switching documents cannot serve stale extents.
+     */
+    setCompat(flags: CompatibilityFlags | undefined): void;
+    /**
+     * Thread document-level script hints into Han region resolution: pass the
+     * `w:themeFontLang` eastAsia tag (`settingsParser` → `themeFontLang`).
+     * Without a hint (or with a non-East-Asian tag) Han-only text defaults to
+     * Simplified Chinese. Invalidates the measure memo — region choice changes
+     * the fallback face and therefore the measured extents.
+     */
+    setScriptHints(hints: {
+        eastAsia?: string;
+    } | undefined): void;
+    /**
+     * Warm the font registry for every (family, bold, italic) combo — plus the
+     * per-family regulars and the per-script coverage fallbacks — that
+     * `blocks`' paragraphs use, AND for every request an earlier measure pass
+     * recorded as unresolved (header/footer and footnote paragraphs reach the
+     * measurer without appearing in the adapters' block lists). The only async
+     * step; per-face failures are tolerated (the chain settles without that
+     * face). Resolves `true` when at least one previously-unsettled chain or
+     * script fallback settled — even settled-empty — i.e. a re-layout would
+     * measure differently (or the deferred pass can now proceed).
+     */
+    prepareFonts(blocks: LayoutBlock[]): Promise<boolean>;
+    /**
+     * True while a font chain (or script fallback) some measured paragraph
+     * needed is still unresolved. The adapter's readiness gate: a pass measured
+     * with pending fonts is provisional (those paragraphs carry synthetic
+     * extents) and must be discarded, not committed; `prepareFonts` settles the
+     * pending set and the fonts-ready re-layout measures natively. Self-clears
+     * once every recorded request has settled.
+     */
+    hasPendingFonts(): boolean;
+    /**
+     * The sync measure function for the float pipeline — the sole measurement
+     * path, exhaustive over every `LayoutBlock` kind. Paragraph blocks whose
+     * chains (and detected script fallbacks) are cached go to the engine —
+     * float-zoned blocks pass their zones and cumulative Y through in the
+     * envelope (measured fresh, never memoized). Tables, text boxes and shapes
+     * recurse through the same measurer; images/charts/breaks synthesize
+     * extents from declared dimensions. Unresolved chains and engine refusals
+     * produce deterministic synthetic extents (see the module doc).
+     */
+    createMeasureBlock(): MeasureBlockFn;
+    /**
+     * The merged, doc-wide font-id chain map for `blocks` — every
+     * `"<family lowercase>|<bold 0|1>|<italic 0|1>"` combo the blocks' paragraphs
+     * use, mapped to its cached engine font-id chain (with the per-block script
+     * fallbacks appended after the family faces, exactly as
+     * {@link RustMeasureSource.createMeasureBlock} assembles them). Only chains that
+     * are already resolved (non-empty in the sync registry cache) are included; a
+     * combo whose chain has not settled yet is simply omitted (its runs stay on
+     * the char-distributed draw path until `prepareFonts` settles and a
+     * re-layout retries). Returns an empty object when nothing is resolved.
+     *
+     * This is the map the canvas display-list builder consumes to gate GlyphRun
+     * emission: the ids reference the same measurement `FontStore` the engine
+     * registered, so the outline provider can rasterize them.
+     */
+    getDocumentFontChains(blocks: LayoutBlock[]): Record<string, number[]>;
+    /** Drop every cached chain, registration, and memoized measure. */
+    clear(): void;
+    /** Snapshot of the rust-vs-fallback counters (never reset implicitly). */
+    getStats(): RustMeasureStats;
+}
+/**
+ * Build a {@link RustMeasureSource} over a loaded engine. The source owns a
+ * {@link TextMeasureFontRegistry} whose sink is `engine.registerFont`;
+ * `bundled` is the optional metric-compatible font provider (injected — core
+ * never imports a fonts package).
+ *
+ * @public
+ */
+declare function createRustMeasureSource(opts: {
+    engine: RustTextEngine;
+    bundled?: BundledFontProvider;
+}): RustMeasureSource;
+
+/**
+ * Stable identity hash for a paragraph block, used as the Rust measure
+ * memo's key so blocks that would lay out identically share one measurement.
+ * Every field that can change the rendered result contributes a labelled
+ * token; the assembled token list is serialized as JSON so no separator
+ * character can leak in from content.
+ *
+ * @packageDocumentation
+ * @public
+ */
+
+/**
+ * Build the stable identity string for a paragraph block.
+ *
+ * @public
+ */
+declare function hashParagraphBlock(block: ParagraphBlock): string;
+
+export { type BundledFontProvider, type EmbeddedFaceInput, type FontScript, type FontStyle, MeasureBlockFn, type RustMeasureSource, type RustMeasureStats, type RustTextEngine, createRustMeasureSource, getRustTextEngine, hashParagraphBlock };

package/dist/layout/measure/index.mjs

@@ -0,0 +1 @@
+export{h as createRustMeasureSource,e as getRustTextEngine,d as hashParagraphBlock,c as measureBlocksWithFloats}from'../../chunk-7DEIW7FL.mjs';export{g as clampFloatingWrapMargins,i as getFloatingMargins,h as rectsToFloatingZones}from'../../chunk-52GB3Y42.mjs';import'../../chunk-7PCO5I2O.mjs';import'../../chunk-X4XDO3LZ.mjs';import'../../chunk-OBQGPMPQ.mjs';import'../../chunk-3UBMCDME.mjs';import'../../chunk-TTRUPDAB.mjs';