@stll/folio-core 0.15.0 → 0.15.2

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

@@ -1,7 +1,5 @@
 import { OutlineStyleAttr } from "../types/documentEnumValues.js";
 import { ImagePosition, ImageWrap, SdtProperties, SdtType, ShapeTextBody, TableCellFormatting, TableWidthType } from "@stll/docx-core/model";
-
-//#region src/layout-engine/types.d.ts
 declare namespace types_d_exports {
   export { BlockId, BorderStyle, CellBorderSpec, CellBorders, ColumnBreakBlock, ColumnBreakMeasure, ColumnLayout, DEFAULT_TEXTBOX_MARGINS, DEFAULT_TEXTBOX_WIDTH, DocumentPosition, FOOTNOTE_ENTRY_MARGIN_BOTTOM, FOOTNOTE_FALLBACK_LINE_HEIGHT, FOOTNOTE_SEPARATOR_HEIGHT, FieldRun, FloatingTablePosition, FlowBlock, FootnoteContent, Fragment, FragmentBase, HeaderFooterContent, HeaderFooterContentHeights, HeaderFooterLayout, HitTestResult, HyperlinkInfo, ImageBlock, ImageFragment, ImageMeasure, ImageRun, ImageRunPosition, Layout, LayoutOptions, LineBreakRun, ListNumPr, MathRun, Measure, MeasuredLine, Page, PageBreakBlock, PageBreakMeasure, PageHeaderFooterRefs, PageMargins, ParagraphAttrs, ParagraphBlock, ParagraphBorders, ParagraphFragment, ParagraphIndent, ParagraphMeasure, ParagraphSpacing, RenderedPageBreakRun, Run, RunFormatting, SdtGroup, SectionBreakBlock, SectionBreakMeasure, TabAlignment, TabRun, TabStop, TableBlock, TableCell, TableCellMeasure, TableFragment, TableMeasure, TableRow, TableRowMeasure, TextBoxBlock, TextBoxFlowAttrs, TextBoxFragment, TextBoxMeasure, TextRun, floatingTextBoxReservesBand, floatingTextBoxWrapsText, getTableRowLeadingWidth, isFloatingImageRun, isFloatingTextBoxBlock, isTextWrappingFloatingImageRun, tableColumnsArePinned };
 }
@@ -38,7 +36,8 @@ type RunFormatting = {
    * `segmentByScript`) so wrapping stays correct. Absent means CJK falls back
    * to `fontFamily`.
    */
-  eastAsiaFontFamily?: string; /** Run language metadata resolved from `w:lang`. */
+  eastAsiaFontFamily?: string;
+  /** Run language metadata resolved from `w:lang`. */
   language?: {
     val?: string;
     eastAsia?: string;
@@ -47,11 +46,16 @@ type RunFormatting = {
   fontSize?: number;
   letterSpacing?: number;
   superscript?: boolean;
-  subscript?: boolean; /** Render glyphs as uppercase regardless of source case. */
-  allCaps?: boolean; /** Render lowercase glyphs as small uppercase. */
-  smallCaps?: boolean; /** Vertical baseline shift in CSS pixels. */
-  positionPx?: number; /** Horizontal text scale as a percentage. */
-  horizontalScale?: number; /** Minimum font size in points at which kerning is enabled. */
+  subscript?: boolean;
+  /** Render glyphs as uppercase regardless of source case. */
+  allCaps?: boolean;
+  /** Render lowercase glyphs as small uppercase. */
+  smallCaps?: boolean;
+  /** Vertical baseline shift in CSS pixels. */
+  positionPx?: number;
+  /** Horizontal text scale as a percentage. */
+  horizontalScale?: number;
+  /** Minimum font size in points at which kerning is enabled. */
   kerningMinPt?: number;
   imprint?: boolean;
   emboss?: boolean;
@@ -77,15 +81,24 @@ type RunFormatting = {
    * but the painter emits `docx-text-effect-<name>` plus `data-effect` so
    * host CSS can opt in.
    */
-  textEffect?: "blinkBackground" | "lights" | "antsBlack" | "antsRed" | "shimmer" | "sparkle"; /** Hyperlink info if this run is a link */
-  hyperlink?: HyperlinkInfo; /** Footnote reference ID (if this run contains a footnote reference) */
-  footnoteRefId?: number; /** Endnote reference ID (if this run contains an endnote reference) */
-  endnoteRefId?: number; /** Comment IDs if this run is within a comment range */
-  commentIds?: number[]; /** Whether this run is a tracked insertion */
-  isInsertion?: boolean; /** Whether this run is a tracked deletion */
-  isDeletion?: boolean; /** Author of the tracked change */
-  changeAuthor?: string; /** Date of the tracked change */
-  changeDate?: string; /** Revision ID of the tracked change (for sidebar matching) */
+  textEffect?: "blinkBackground" | "lights" | "antsBlack" | "antsRed" | "shimmer" | "sparkle";
+  /** Hyperlink info if this run is a link */
+  hyperlink?: HyperlinkInfo;
+  /** Footnote reference ID (if this run contains a footnote reference) */
+  footnoteRefId?: number;
+  /** Endnote reference ID (if this run contains an endnote reference) */
+  endnoteRefId?: number;
+  /** Comment IDs if this run is within a comment range */
+  commentIds?: number[];
+  /** Whether this run is a tracked insertion */
+  isInsertion?: boolean;
+  /** Whether this run is a tracked deletion */
+  isDeletion?: boolean;
+  /** Author of the tracked change */
+  changeAuthor?: string;
+  /** Date of the tracked change */
+  changeDate?: string;
+  /** Revision ID of the tracked change (for sidebar matching) */
   changeRevisionId?: number;
   /**
    * Whether this tracked insertion/deletion is an AI-proposed *suggestion*
@@ -93,7 +106,8 @@ type RunFormatting = {
    * dotted stroke and a dedicated hue; they are stripped from serialized DOCX
    * until accepted.
    */
-  isSuggestion?: boolean; /** Groups a suggestion's runs for accept/reject and scroll-to. */
+  isSuggestion?: boolean;
+  /** Groups a suggestion's runs for accept/reject and scroll-to. */
   suggestionId?: string;
 };
 /**
@@ -116,9 +130,12 @@ type HyperlinkInfo = {
  */
 type TextRun = RunFormatting & {
   kind: "text";
-  text: string; /** Hyperlink information if this run is a link. */
-  hyperlink?: HyperlinkInfo; /** Absolute ProseMirror position (inclusive) of first character. */
-  pmStart?: number; /** Absolute ProseMirror position (exclusive) after last character. */
+  text: string;
+  /** Hyperlink information if this run is a link. */
+  hyperlink?: HyperlinkInfo;
+  /** Absolute ProseMirror position (inclusive) of first character. */
+  pmStart?: number;
+  /** Absolute ProseMirror position (exclusive) after last character. */
   pmEnd?: number;
   /**
    * Set when this run is a template fill-preview substitution: the text is
@@ -162,23 +179,31 @@ type ImageRun = {
   src: string;
   width: number;
   height: number;
-  alt?: string; /** CSS transform string (rotation, flip) */
+  alt?: string;
+  /** CSS transform string (rotation, flip) */
   transform?: string;
   /**
    * Opacity in [0, 1] from `<a:alphaModFix amt>`. Undefined or `1` means
    * fully opaque; the painter emits no CSS `opacity` in that case.
    * eigenpal #424 (opacity render pipeline).
    */
-  opacity?: number; /** Position for floating/anchored images */
-  position?: ImageRunPosition; /** Whether a table-cell anchor uses the cell as its positioning scope. Undefined defaults true. */
-  layoutInCell?: boolean; /** Wrap type from DOCX (inline, square, tight, through, topAndBottom, etc.) */
-  wrapType?: ImageWrap["type"]; /** Display mode for CSS rendering */
-  displayMode?: "inline" | "block" | "float"; /** CSS float direction */
-  cssFloat?: "left" | "right" | "none"; /** Wrap distances in pixels */
+  opacity?: number;
+  /** Position for floating/anchored images */
+  position?: ImageRunPosition;
+  /** Whether a table-cell anchor uses the cell as its positioning scope. Undefined defaults true. */
+  layoutInCell?: boolean;
+  /** Wrap type from DOCX (inline, square, tight, through, topAndBottom, etc.) */
+  wrapType?: ImageWrap["type"];
+  /** Display mode for CSS rendering */
+  displayMode?: "inline" | "block" | "float";
+  /** CSS float direction */
+  cssFloat?: "left" | "right" | "none";
+  /** Wrap distances in pixels */
   distTop?: number;
   distBottom?: number;
   distLeft?: number;
-  distRight?: number; /** Use the image box as the exact line height for an embedded-object preview. */
+  distRight?: number;
+  /** Use the image box as the exact line height for an embedded-object preview. */
   exactLineHeight?: boolean;
   /**
    * wp:srcRect crop fractions in [0, 1]; emit as CSS `clip-path: inset(...)`
@@ -187,14 +212,22 @@ type ImageRun = {
   cropTop?: number;
   cropRight?: number;
   cropBottom?: number;
-  cropLeft?: number; /** CSS border width in pixels. eigenpal #1096. */
-  borderWidth?: number; /** CSS border color. eigenpal #1096. */
-  borderColor?: string; /** CSS border style. eigenpal #1096. */
-  borderStyle?: string; /** Whether this picture is itself a tracked insertion (`<w:ins>`). eigenpal #641. */
-  isInsertion?: boolean; /** Whether this picture is itself a tracked deletion (`<w:del>`). eigenpal #641. */
-  isDeletion?: boolean; /** Author of the tracked change wrapping the picture. eigenpal #641. */
-  changeAuthor?: string; /** Date of the tracked change wrapping the picture. eigenpal #641. */
-  changeDate?: string; /** Revision id of the tracked change wrapping the picture. eigenpal #641. */
+  cropLeft?: number;
+  /** CSS border width in pixels. eigenpal #1096. */
+  borderWidth?: number;
+  /** CSS border color. eigenpal #1096. */
+  borderColor?: string;
+  /** CSS border style. eigenpal #1096. */
+  borderStyle?: string;
+  /** Whether this picture is itself a tracked insertion (`<w:ins>`). eigenpal #641. */
+  isInsertion?: boolean;
+  /** Whether this picture is itself a tracked deletion (`<w:del>`). eigenpal #641. */
+  isDeletion?: boolean;
+  /** Author of the tracked change wrapping the picture. eigenpal #641. */
+  changeAuthor?: string;
+  /** Date of the tracked change wrapping the picture. eigenpal #641. */
+  changeDate?: string;
+  /** Revision id of the tracked change wrapping the picture. eigenpal #641. */
   changeRevisionId?: number;
   pmStart?: number;
   pmEnd?: number;
@@ -217,12 +250,15 @@ type RenderedPageBreakRun = RunFormatting & {
  * A field run (PAGE, NUMPAGES, etc.) that gets substituted at render time.
  */
 type FieldRun = RunFormatting & {
-  kind: "field"; /** Coarse render category, kept for cache keys and caret-width fast paths. */
+  kind: "field";
+  /** Coarse render category, kept for cache keys and caret-width fast paths. */
   fieldType: "PAGE" | "NUMPAGES" | "DATE" | "TIME" | "OTHER";
   /** Full OOXML field instruction (e.g. `PAGE \* ROMAN`, `PAGEREF _Ref1 \h`)
    *  for live evaluation; falls back to `fieldType` when absent. */
-  instruction?: string; /** Fallback text if field can't be resolved */
-  fallback?: string; /** Whether OOXML marked this field as locked (`w:fldLock`). */
+  instruction?: string;
+  /** Fallback text if field can't be resolved */
+  fallback?: string;
+  /** Whether OOXML marked this field as locked (`w:fldLock`). */
   fldLock?: boolean;
   pmStart?: number;
   pmEnd?: number;
@@ -237,9 +273,12 @@ type FieldRun = RunFormatting & {
  * the document model, not the layout layer).
  */
 type MathRun = RunFormatting & {
-  kind: "math"; /** `inline` = `<m:oMath>`, `block` = `<m:oMathPara>`. */
-  display: "inline" | "block"; /** Raw OMML XML for conversion + round-trip. */
-  ommlXml: string; /** Plain-text fallback used when MathML rendering is unavailable. */
+  kind: "math";
+  /** `inline` = `<m:oMath>`, `block` = `<m:oMathPara>`. */
+  display: "inline" | "block";
+  /** Raw OMML XML for conversion + round-trip. */
+  ommlXml: string;
+  /** Plain-text fallback used when MathML rendering is unavailable. */
   plainText: string;
   pmStart?: number;
   pmEnd?: number;
@@ -275,8 +314,11 @@ type TabAlignment = "start" | "end" | "center" | "decimal" | "bar" | "clear";
  * Tab stop definition
  */
 type TabStop = {
-  /** Tab alignment mode */val: TabAlignment; /** Position in twips from left margin */
-  pos: number; /** Optional leader character */
+  /** Tab alignment mode */
+  val: TabAlignment;
+  /** Position in twips from left margin */
+  pos: number;
+  /** Optional leader character */
   leader?: "none" | "dot" | "hyphen" | "underscore" | "heavy" | "middleDot";
 };
 /**
@@ -310,19 +352,26 @@ type ListNumPr = {
  * Paragraph block attributes.
  */
 type ParagraphAttrs = {
-  alignment?: "left" | "center" | "right" | "justify"; /** Document-generation policy for justified line fitting. */
+  alignment?: "left" | "center" | "right" | "justify";
+  /** Document-generation policy for justified line fitting. */
   justificationCompatibility?: {
     type: "legacy";
-  }; /** East Asian first/last-character restrictions (`w:kinsoku`). */
-  kinsoku?: boolean; /** Hanging punctuation (`w:overflowPunct`); defaults to enabled when omitted. */
-  overflowPunctuation?: boolean; /** Exempt this paragraph from document automatic hyphenation. */
-  suppressAutoHyphens?: boolean; /** Document-wide automatic hyphenation controls retained for line layout. */
+  };
+  /** East Asian first/last-character restrictions (`w:kinsoku`). */
+  kinsoku?: boolean;
+  /** Hanging punctuation (`w:overflowPunct`); defaults to enabled when omitted. */
+  overflowPunctuation?: boolean;
+  /** Exempt this paragraph from document automatic hyphenation. */
+  suppressAutoHyphens?: boolean;
+  /** Document-wide automatic hyphenation controls retained for line layout. */
   automaticHyphenation?: {
     enabled: true;
     doNotHyphenateCaps?: boolean;
-    consecutiveLineLimit?: number; /** Maximum tolerated line-end whitespace before hyphenation, in twips. */
+    consecutiveLineLimit?: number;
+    /** Maximum tolerated line-end whitespace before hyphenation, in twips. */
     hyphenationZoneTwips?: number;
-  }; /** Document-wide custom line-edge characters and compatibility behavior. */
+  };
+  /** Document-wide custom line-edge characters and compatibility behavior. */
   lineBreakRules?: {
     noLineBreaksBefore?: {
       language?: string;
@@ -333,11 +382,15 @@ type ParagraphAttrs = {
       characters: string;
     };
     useLegacyEthiopicAmharicRules?: boolean;
-  }; /** OOXML outline level (`w:outlineLvl`), where zero is the top level. */
+  };
+  /** OOXML outline level (`w:outlineLvl`), where zero is the top level. */
   outlineLevel?: number;
-  spacing?: ParagraphSpacing; /** Whether this paragraph participates in the active section line grid. */
-  snapToGrid?: boolean; /** Active section line pitch in pixels; present only on top-level body paragraphs. */
-  documentGridLinePitch?: number; /** Spacing sides resolved from OOXML automatic paragraph spacing. */
+  spacing?: ParagraphSpacing;
+  /** Whether this paragraph participates in the active section line grid. */
+  snapToGrid?: boolean;
+  /** Active section line pitch in pixels; present only on top-level body paragraphs. */
+  documentGridLinePitch?: number;
+  /** Spacing sides resolved from OOXML automatic paragraph spacing. */
   automaticSpacing?: {
     before?: boolean;
     after?: boolean;
@@ -359,13 +412,15 @@ type ParagraphAttrs = {
    * source `w:pPr`. Word treats such a blank as authored and keeps its
    * inherited spacing; a bare empty paragraph still collapses that spacing.
    */
-  hasDirectParagraphFormatting?: boolean; /** Whether an empty paragraph carries direct formatting on its paragraph mark. */
+  hasDirectParagraphFormatting?: boolean;
+  /** Whether an empty paragraph carries direct formatting on its paragraph mark. */
   hasDirectParagraphMarkFormatting?: boolean;
   indent?: ParagraphIndent;
   keepNext?: boolean;
   keepLines?: boolean;
   widowControl?: boolean;
-  pageBreakBefore?: boolean; /** Cached OOXML pagination hint (`w:lastRenderedPageBreak`). */
+  pageBreakBefore?: boolean;
+  /** Cached OOXML pagination hint (`w:lastRenderedPageBreak`). */
   renderedPageBreakBefore?: boolean;
   styleId?: string;
   contextualSpacing?: boolean;
@@ -375,12 +430,15 @@ type ParagraphAttrs = {
    * stage merges the next paragraph's runs into this paragraph's
    * fragment (keeping pmStart/pmEnd intact for editing).
    */
-  runInWithNext?: boolean; /** Right-to-left paragraph direction */
+  runInWithNext?: boolean;
+  /** Right-to-left paragraph direction */
   bidi?: boolean;
   borders?: ParagraphBorders;
   shading?: string;
-  tabs?: TabStop[]; /** Render structural empty paragraphs as zero-height anchors. */
-  suppressEmptyParagraphHeight?: boolean; /** Reserve the reference extra line advance for a story-leading empty level-0 outline paragraph. */
+  tabs?: TabStop[];
+  /** Render structural empty paragraphs as zero-height anchors. */
+  suppressEmptyParagraphHeight?: boolean;
+  /** Reserve the reference extra line advance for a story-leading empty level-0 outline paragraph. */
   reserveEmptyOutlineHeight?: boolean;
   numPr?: ListNumPr;
   listMarker?: string;
@@ -394,7 +452,8 @@ type ParagraphAttrs = {
    * that line box without enlarging the marker or Western text glyphs.
    */
   listParagraphMarkFontSize?: number;
-  listMarkerBold?: boolean; /** Horizontal alignment of the marker around the paragraph's list anchor. */
+  listMarkerBold?: boolean;
+  /** Horizontal alignment of the marker around the paragraph's list anchor. */
   listMarkerAlignment?: "left" | "center" | "right";
   /**
    * `w:suff` (§17.9.25) — what follows the marker before body text.
@@ -437,14 +496,17 @@ type ParagraphAttrs = {
  */
 type ParagraphBlock = {
   kind: "paragraph";
-  id: BlockId; /** Stable Word `w14:paraId` / PM `paraId`, when available. */
+  id: BlockId;
+  /** Stable Word `w14:paraId` / PM `paraId`, when available. */
   paraId?: string;
   runs: Run[];
   attrs?: ParagraphAttrs;
   /** Names of bookmarks anchored to this paragraph; used to map a bookmark to
    *  the page it lands on for PAGEREF/REF resolution. */
-  bookmarks?: string[]; /** ProseMirror start position for this block. */
-  pmStart?: number; /** ProseMirror end position for this block. */
+  bookmarks?: string[];
+  /** ProseMirror start position for this block. */
+  pmStart?: number;
+  /** ProseMirror end position for this block. */
   pmEnd?: number;
   /**
    * Outer→inner SDT wrappers enclosing this block. Empty / undefined when
@@ -484,7 +546,8 @@ type TableCell = {
   verticalAlign?: "top" | "center" | "bottom";
   textDirection?: NonNullable<TableCellFormatting["textDirection"]>;
   background?: string;
-  borders?: CellBorders; /** Per-cell padding in pixels (from w:tcMar or table-level w:tblCellMar) */
+  borders?: CellBorders;
+  /** Per-cell padding in pixels (from w:tcMar or table-level w:tblCellMar) */
   padding?: {
     top: number;
     right: number;
@@ -508,7 +571,8 @@ type TableRow = {
   gridAfter?: number;
   height?: number;
   heightRule?: "auto" | "atLeast" | "exact";
-  isHeader?: boolean; /** `w:cantSplit`: keep this row in one flow region. */
+  isHeader?: boolean;
+  /** `w:cantSplit`: keep this row in one flow region. */
   cantSplit?: boolean;
   hidden?: boolean;
 };
@@ -534,8 +598,10 @@ type TableBlock = {
   kind: "table";
   id: BlockId;
   rows: TableRow[];
-  columnWidths?: number[]; /** Table width value (twips for dxa, 50ths of percent for pct). */
-  width?: number; /** Table width type ('auto', 'pct', 'dxa', 'nil'). */
+  columnWidths?: number[];
+  /** Table width value (twips for dxa, 50ths of percent for pct). */
+  width?: number;
+  /** Table width type ('auto', 'pct', 'dxa', 'nil'). */
   widthType?: TableWidthType;
   /**
    * Table layout algorithm (`w:tblLayout`). "fixed" pins columns to their grid
@@ -543,13 +609,18 @@ type TableBlock = {
    * content. Consulted alongside `widthType` to decide whether `w:noWrap` cells
    * can be honored (see `tableColumnsArePinned`).
    */
-  layout?: "fixed" | "autofit"; /** Table horizontal alignment */
-  justification?: "left" | "center" | "right"; /** Table indent from left margin (in pixels, from w:tblInd) */
-  indent?: number; /** Right-to-left column order (w:bidiVisual): logical column 0 paints on the right. */
-  bidi?: boolean; /** Floating table properties (pixel values). */
+  layout?: "fixed" | "autofit";
+  /** Table horizontal alignment */
+  justification?: "left" | "center" | "right";
+  /** Table indent from left margin (in pixels, from w:tblInd) */
+  indent?: number;
+  /** Right-to-left column order (w:bidiVisual): logical column 0 paints on the right. */
+  bidi?: boolean;
+  /** Floating table properties (pixel values). */
   floating?: FloatingTablePosition;
   pmStart?: number;
-  pmEnd?: number; /** Outer→inner SDT wrappers enclosing this table (see ParagraphBlock). */
+  pmEnd?: number;
+  /** Outer→inner SDT wrappers enclosing this table (see ParagraphBlock). */
   sdtGroups?: SdtGroup[];
 };
 /**
@@ -561,7 +632,8 @@ type ImageBlock = {
   src: string;
   width: number;
   height: number;
-  alt?: string; /** CSS transform string (rotation, flip) */
+  alt?: string;
+  /** CSS transform string (rotation, flip) */
   transform?: string;
   /**
    * Opacity in [0, 1] from `<a:alphaModFix amt>`. Undefined or `1` means
@@ -574,7 +646,8 @@ type ImageBlock = {
     offsetH?: number;
     offsetV?: number;
     behindDoc?: boolean;
-  }; /** Hyperlink URL for clickable image */
+  };
+  /** Hyperlink URL for clickable image */
   hlinkHref?: string;
   /**
    * wp:srcRect crop fractions in [0, 1]; emit as CSS `clip-path: inset(...)`.
@@ -583,9 +656,12 @@ type ImageBlock = {
   cropTop?: number;
   cropRight?: number;
   cropBottom?: number;
-  cropLeft?: number; /** CSS border width in pixels. eigenpal #1096. */
-  borderWidth?: number; /** CSS border color. eigenpal #1096. */
-  borderColor?: string; /** CSS border style. eigenpal #1096. */
+  cropLeft?: number;
+  /** CSS border width in pixels. eigenpal #1096. */
+  borderWidth?: number;
+  /** CSS border color. eigenpal #1096. */
+  borderColor?: string;
+  /** CSS border style. eigenpal #1096. */
   borderStyle?: string;
   pmStart?: number;
   pmEnd?: number;
@@ -603,7 +679,8 @@ type SectionBreakBlock = {
   };
   orientation?: "portrait" | "landscape";
   margins?: PageMargins;
-  columns?: ColumnLayout; /** Line pitch authored by the section properties that end at this boundary, in twips. */
+  columns?: ColumnLayout;
+  /** Line pitch authored by the section properties that end at this boundary, in twips. */
   documentGridLinePitchTwips?: number;
 };
 type PageHeaderFooterRefs = {
@@ -648,26 +725,41 @@ declare const DEFAULT_TEXTBOX_WIDTH = 200;
  */
 type TextBoxBlock = {
   kind: "textBox";
-  id: BlockId; /** Width in pixels */
-  width: number; /** Height in pixels (may be auto-calculated) */
-  height?: number; /** Text fitting behavior */
-  autoFit?: ShapeTextBody["autoFit"]; /** Fill/background color */
-  fillColor?: string; /** Border width in pixels */
-  outlineWidth?: number; /** Border color */
-  outlineColor?: string; /** Outline dash style, or `"none"` for an explicit no-outline. */
-  outlineStyle?: OutlineStyleAttr; /** Internal padding */
+  id: BlockId;
+  /** Width in pixels */
+  width: number;
+  /** Height in pixels (may be auto-calculated) */
+  height?: number;
+  /** Text fitting behavior */
+  autoFit?: ShapeTextBody["autoFit"];
+  /** Fill/background color */
+  fillColor?: string;
+  /** Border width in pixels */
+  outlineWidth?: number;
+  /** Border color */
+  outlineColor?: string;
+  /** Outline dash style, or `"none"` for an explicit no-outline. */
+  outlineStyle?: OutlineStyleAttr;
+  /** Internal padding */
   margins?: {
     top: number;
     bottom: number;
     left: number;
     right: number;
-  }; /** Flow blocks inside the text box */
-  content: (ParagraphBlock | TableBlock)[]; /** Display mode copied from the ProseMirror text box node. */
-  displayMode?: "inline" | "float" | "block"; /** CSS float direction copied from the ProseMirror text box node. */
-  cssFloat?: "left" | "right" | "none"; /** OOXML wrap type for anchored text boxes. */
-  wrapType?: ImageWrap["type"]; /** OOXML wrapText direction for anchored text boxes. */
-  wrapText?: "bothSides" | "left" | "right" | "largest"; /** Position for floating/anchored text boxes (OOXML EMU offsets). */
-  position?: ImageRunPosition; /** Wrap distances in pixels. */
+  };
+  /** Flow blocks inside the text box */
+  content: (ParagraphBlock | TableBlock)[];
+  /** Display mode copied from the ProseMirror text box node. */
+  displayMode?: "inline" | "float" | "block";
+  /** CSS float direction copied from the ProseMirror text box node. */
+  cssFloat?: "left" | "right" | "none";
+  /** OOXML wrap type for anchored text boxes. */
+  wrapType?: ImageWrap["type"];
+  /** OOXML wrapText direction for anchored text boxes. */
+  wrapText?: "bothSides" | "left" | "right" | "largest";
+  /** Position for floating/anchored text boxes (OOXML EMU offsets). */
+  position?: ImageRunPosition;
+  /** Wrap distances in pixels. */
   distTop?: number;
   distBottom?: number;
   distLeft?: number;
@@ -684,21 +776,30 @@ type TextBoxBlock = {
  * stay disambiguated even when alias/tag/sdtId collide.
  */
 type SdtGroup = {
-  /** Folio-local identifier (stable within one toFlowBlocks call). */id: string;
+  /** Folio-local identifier (stable within one toFlowBlocks call). */
+  id: string;
   /**
    * ProseMirror position of the blockSdt's open token in the source doc.
    * Stable across renders for the same control and unique per instance —
    * the addressing API uses this to disambiguate SDTs that share a tag.
    */
   pmPos: number;
-  sdtType: SdtType; /** OOXML `w:alias` (friendly display name). */
-  alias?: string; /** OOXML `w:tag` (developer identifier — anchor for addressing API). */
-  tag?: string; /** OOXML numeric `w:id`. */
-  sdtId?: number; /** OOXML `w:lock` setting. */
-  lock?: NonNullable<SdtProperties["lock"]>; /** True if `w:showingPlcHdr` is set. */
-  showingPlaceholder?: boolean; /** Modeled checkbox state, when the control is `w14:checkbox`. */
-  checked?: boolean; /** Modeled `w:date/w:dateFormat`. */
-  dateFormat?: string; /** Modeled `w:dropDownList`/`w:comboBox` items (JSON-encoded). */
+  sdtType: SdtType;
+  /** OOXML `w:alias` (friendly display name). */
+  alias?: string;
+  /** OOXML `w:tag` (developer identifier — anchor for addressing API). */
+  tag?: string;
+  /** OOXML numeric `w:id`. */
+  sdtId?: number;
+  /** OOXML `w:lock` setting. */
+  lock?: NonNullable<SdtProperties["lock"]>;
+  /** True if `w:showingPlcHdr` is set. */
+  showingPlaceholder?: boolean;
+  /** Modeled checkbox state, when the control is `w14:checkbox`. */
+  checked?: boolean;
+  /** Modeled `w:date/w:dateFormat`. */
+  dateFormat?: string;
+  /** Modeled `w:dropDownList`/`w:comboBox` items (JSON-encoded). */
   listItemsJson?: string;
   /**
    * Position of the carrying block within its SDT group (`first`/`middle`/
@@ -718,25 +819,37 @@ type FlowBlock = ParagraphBlock | TableBlock | ImageBlock | TextBoxBlock | Secti
  * A measured line within a paragraph.
  */
 type MeasuredLine = {
-  /** Starting run index (inclusive). */fromRun: number; /** Starting character index within fromRun. */
-  fromChar: number; /** Ending run index (inclusive). */
-  toRun: number; /** Ending character index within toRun (exclusive). */
-  toChar: number; /** Total width of the line in pixels. */
-  width: number; /** Ascent (height above baseline) in pixels. */
-  ascent: number; /** Descent (height below baseline) in pixels. */
-  descent: number; /** Total line height in pixels. */
-  lineHeight: number; /** Left offset from floating images (pixels from content left edge). */
-  leftOffset?: number; /** Right offset from floating images (pixels from content right edge). */
+  /** Starting run index (inclusive). */
+  fromRun: number;
+  /** Starting character index within fromRun. */
+  fromChar: number;
+  /** Ending run index (inclusive). */
+  toRun: number;
+  /** Ending character index within toRun (exclusive). */
+  toChar: number;
+  /** Total width of the line in pixels. */
+  width: number;
+  /** Ascent (height above baseline) in pixels. */
+  ascent: number;
+  /** Descent (height below baseline) in pixels. */
+  descent: number;
+  /** Total line height in pixels. */
+  lineHeight: number;
+  /** Left offset from floating images (pixels from content left edge). */
+  leftOffset?: number;
+  /** Right offset from floating images (pixels from content right edge). */
   rightOffset?: number;
   /**
    * Vertical space inserted before this line to skip past floats that leave
    * no usable horizontal room at the natural line Y. Painters render this
    * as marginTop on the line element; measurement adds it to totalHeight.
    */
-  floatSkipBefore?: number; /** Decorative hyphen inserted at a dictionary break without changing source text. */
+  floatSkipBefore?: number;
+  /** Decorative hyphen inserted at a dictionary break without changing source text. */
   discretionaryHyphen?: {
     runIndex: number;
-  }; /** A cached pagination boundary occurs immediately before this line. */
+  };
+  /** A cached pagination boundary occurs immediately before this line. */
   renderedPageBreakBefore?: boolean;
 };
 /**
@@ -815,7 +928,8 @@ type ColumnBreakMeasure = {
 type TextBoxMeasure = {
   kind: "textBox";
   width: number;
-  height: number; /** Pre-measured inner content (avoids re-measuring during render) */
+  height: number;
+  /** Pre-measured inner content (avoids re-measuring during render) */
   innerMeasures: (ParagraphMeasure | TableMeasure)[];
 };
 /**
@@ -826,11 +940,17 @@ type Measure = ParagraphMeasure | ImageMeasure | TableMeasure | TextBoxMeasure |
  * Base fragment properties common to all fragment types.
  */
 type FragmentBase = {
-  /** Block ID this fragment belongs to. */blockId: BlockId; /** X position on page (relative to page left). */
-  x: number; /** Y position on page (relative to page top). */
-  y: number; /** Width of the fragment. */
-  width: number; /** ProseMirror start position (for click mapping). */
-  pmStart?: number; /** ProseMirror end position (for click mapping). */
+  /** Block ID this fragment belongs to. */
+  blockId: BlockId;
+  /** X position on page (relative to page left). */
+  x: number;
+  /** Y position on page (relative to page top). */
+  y: number;
+  /** Width of the fragment. */
+  width: number;
+  /** ProseMirror start position (for click mapping). */
+  pmStart?: number;
+  /** ProseMirror end position (for click mapping). */
   pmEnd?: number;
   /**
    * Outer→inner SDT wrappers enclosing the originating block. Copied
@@ -844,11 +964,16 @@ type FragmentBase = {
  * May span only part of the paragraph's lines if split across pages.
  */
 type ParagraphFragment = FragmentBase & {
-  kind: "paragraph"; /** First line index (inclusive) from the measure. */
-  fromLine: number; /** Last line index (exclusive) from the measure. */
-  toLine: number; /** Height of this fragment. */
-  height: number; /** True if this continues from a previous page. */
-  continuesFromPrev?: boolean; /** True if this continues onto the next page. */
+  kind: "paragraph";
+  /** First line index (inclusive) from the measure. */
+  fromLine: number;
+  /** Last line index (exclusive) from the measure. */
+  toLine: number;
+  /** Height of this fragment. */
+  height: number;
+  /** True if this continues from a previous page. */
+  continuesFromPrev?: boolean;
+  /** True if this continues onto the next page. */
   continuesOnNext?: boolean;
 };
 /**
@@ -856,13 +981,20 @@ type ParagraphFragment = FragmentBase & {
  * May span only part of the table's rows if split across pages.
  */
 type TableFragment = FragmentBase & {
-  kind: "table"; /** First row index (inclusive). */
-  fromRow: number; /** Last row index (exclusive). */
-  toRow: number; /** Height of this fragment. */
-  height: number; /** True if this is a floating table. */
-  isFloating?: boolean; /** True if this continues from a previous page. */
-  continuesFromPrev?: boolean; /** True if this continues onto the next page. */
-  continuesOnNext?: boolean; /** Number of header rows prepended to this continuation fragment (0 or undefined for first fragment). */
+  kind: "table";
+  /** First row index (inclusive). */
+  fromRow: number;
+  /** Last row index (exclusive). */
+  toRow: number;
+  /** Height of this fragment. */
+  height: number;
+  /** True if this is a floating table. */
+  isFloating?: boolean;
+  /** True if this continues from a previous page. */
+  continuesFromPrev?: boolean;
+  /** True if this continues onto the next page. */
+  continuesOnNext?: boolean;
+  /** Number of header rows prepended to this continuation fragment (0 or undefined for first fragment). */
   headerRowCount?: number;
   /**
    * Mid-content row break (eigenpal #698): when a single row is taller than a
@@ -879,16 +1011,20 @@ type TableFragment = FragmentBase & {
  * An image fragment positioned on a page.
  */
 type ImageFragment = FragmentBase & {
-  kind: "image"; /** Height of the image. */
-  height: number; /** True if this is an anchored/floating image. */
-  isAnchored?: boolean; /** Z-index for layering. */
+  kind: "image";
+  /** Height of the image. */
+  height: number;
+  /** True if this is an anchored/floating image. */
+  isAnchored?: boolean;
+  /** Z-index for layering. */
   zIndex?: number;
 };
 /**
  * A text box fragment positioned on a page.
  */
 type TextBoxFragment = FragmentBase & {
-  kind: "textBox"; /** Height of the text box. */
+  kind: "textBox";
+  /** Height of the text box. */
   height: number;
 };
 /**
@@ -902,27 +1038,40 @@ type PageMargins = {
   top: number;
   right: number;
   bottom: number;
-  left: number; /** Distance from page top to header content. */
-  header?: number; /** Distance from page bottom to footer content. */
+  left: number;
+  /** Distance from page top to header content. */
+  header?: number;
+  /** Distance from page bottom to footer content. */
   footer?: number;
 };
 /**
  * A rendered page containing positioned fragments.
  */
 type Page = {
-  /** Page number (1-indexed). */number: number; /** Fragments positioned on this page. */
-  fragments: Fragment[]; /** Page margins. */
-  margins: PageMargins; /** Page size (width, height). */
+  /** Page number (1-indexed). */
+  number: number;
+  /** Fragments positioned on this page. */
+  fragments: Fragment[];
+  /** Page margins. */
+  margins: PageMargins;
+  /** Page size (width, height). */
   size: {
     w: number;
     h: number;
-  }; /** Page orientation. */
-  orientation?: "portrait" | "landscape"; /** Section index this page belongs to. */
-  sectionIndex?: number; /** 1-based page number within the active section. */
-  sectionPageNumber?: number; /** Header/footer references for this page. */
-  headerFooterRefs?: PageHeaderFooterRefs; /** Footnote IDs that appear on this page (for rendering). */
-  footnoteIds?: number[]; /** Height reserved for the footnote area at page bottom (pixels). */
-  footnoteReservedHeight?: number; /** Column layout for this page (if multi-column). */
+  };
+  /** Page orientation. */
+  orientation?: "portrait" | "landscape";
+  /** Section index this page belongs to. */
+  sectionIndex?: number;
+  /** 1-based page number within the active section. */
+  sectionPageNumber?: number;
+  /** Header/footer references for this page. */
+  headerFooterRefs?: PageHeaderFooterRefs;
+  /** Footnote IDs that appear on this page (for rendering). */
+  footnoteIds?: number[];
+  /** Height reserved for the footnote area at page bottom (pixels). */
+  footnoteReservedHeight?: number;
+  /** Column layout for this page (if multi-column). */
   columns?: ColumnLayout;
 };
 /**
@@ -931,9 +1080,12 @@ type Page = {
 type ColumnLayout = {
   count: number;
   gap: number;
-  equalWidth?: boolean; /** Authored widths for unequal-width section columns. */
-  widths?: number[]; /** Authored space after each column except the last. */
-  gaps?: number[]; /** Draw vertical separator line between columns (w:sep). */
+  equalWidth?: boolean;
+  /** Authored widths for unequal-width section columns. */
+  widths?: number[];
+  /** Authored space after each column except the last. */
+  gaps?: number[];
+  /** Draw vertical separator line between columns (w:sep). */
   separator?: boolean;
 };
 /**
@@ -947,14 +1099,20 @@ type HeaderFooterLayout = {
  * Final layout output ready for rendering/painting.
  */
 type Layout = {
-  /** Default page size for the document. */pageSize: {
+  /** Default page size for the document. */
+  pageSize: {
     w: number;
     h: number;
-  }; /** All rendered pages with positioned fragments. */
-  pages: Page[]; /** Column configuration (if multi-column). */
-  columns?: ColumnLayout; /** Header layouts by type (default, first, even). */
-  headers?: Record<string, HeaderFooterLayout>; /** Footer layouts by type (default, first, even). */
-  footers?: Record<string, HeaderFooterLayout>; /** Gap between pages in pixels (for rendering). */
+  };
+  /** All rendered pages with positioned fragments. */
+  pages: Page[];
+  /** Column configuration (if multi-column). */
+  columns?: ColumnLayout;
+  /** Header layouts by type (default, first, even). */
+  headers?: Record<string, HeaderFooterLayout>;
+  /** Footer layouts by type (default, first, even). */
+  footers?: Record<string, HeaderFooterLayout>;
+  /** Gap between pages in pixels (for rendering). */
   pageGap?: number;
 };
 /**
@@ -965,20 +1123,27 @@ type HeaderFooterContentHeights = Partial<Record<"default" | "first" | "even" |
  * Pre-calculated footnote content for layout and rendering.
  */
 type FootnoteContent = {
-  /** Footnote ID. */id: number; /** Display number (e.g. 1, 2, 3). */
-  displayNumber: number; /** FlowBlocks for rendering the footnote content. */
-  blocks: FlowBlock[]; /** Measurements for the blocks. */
-  measures: Measure[]; /** Total height in pixels. */
+  /** Footnote ID. */
+  id: number;
+  /** Display number (e.g. 1, 2, 3). */
+  displayNumber: number;
+  /** FlowBlocks for rendering the footnote content. */
+  blocks: FlowBlock[];
+  /** Measurements for the blocks. */
+  measures: Measure[];
+  /** Total height in pixels. */
   height: number;
 };
 /**
  * Options for the layout engine.
  */
 type LayoutOptions = {
-  /** Initial page size. */pageSize: {
+  /** Initial page size. */
+  pageSize: {
     w: number;
     h: number;
-  }; /** Initial page margins. */
+  };
+  /** Initial page margins. */
   margins: PageMargins;
   /**
    * Margins applied only to page 1 (the title page) when the first
@@ -986,22 +1151,35 @@ type LayoutOptions = {
    * overflowing first-page header without forcing pages 2+ to inherit the
    * same extension.
    */
-  firstPageMargins?: PageMargins; /** Per-section body margins used on even section pages. */
-  sectionEvenPageMargins?: (PageMargins | undefined)[]; /** Body-level final section page size. */
+  firstPageMargins?: PageMargins;
+  /** Per-section body margins used on even section pages. */
+  sectionEvenPageMargins?: (PageMargins | undefined)[];
+  /** Body-level final section page size. */
   finalPageSize?: {
     w: number;
     h: number;
-  }; /** Body-level final section margins. */
-  finalMargins?: PageMargins; /** Body-level final section column configuration. */
-  finalColumns?: ColumnLayout; /** Column configuration. */
-  columns?: ColumnLayout; /** Gap between rendered pages (for UI). */
-  pageGap?: number; /** Default line height multiplier. */
-  defaultLineHeight?: number; /** Header content heights by variant. */
-  headerContentHeights?: HeaderFooterContentHeights; /** Footer content heights by variant. */
-  footerContentHeights?: HeaderFooterContentHeights; /** Whether section has different first page header/footer. */
-  titlePage?: boolean; /** Whether section has different even/odd headers/footers. */
-  evenAndOddHeaders?: boolean; /** Swap left/right margins on even physical pages. */
-  mirrorMargins?: boolean; /** Per-page footnote reserved heights (pageNumber → height in pixels). */
+  };
+  /** Body-level final section margins. */
+  finalMargins?: PageMargins;
+  /** Body-level final section column configuration. */
+  finalColumns?: ColumnLayout;
+  /** Column configuration. */
+  columns?: ColumnLayout;
+  /** Gap between rendered pages (for UI). */
+  pageGap?: number;
+  /** Default line height multiplier. */
+  defaultLineHeight?: number;
+  /** Header content heights by variant. */
+  headerContentHeights?: HeaderFooterContentHeights;
+  /** Footer content heights by variant. */
+  footerContentHeights?: HeaderFooterContentHeights;
+  /** Whether section has different first page header/footer. */
+  titlePage?: boolean;
+  /** Whether section has different even/odd headers/footers. */
+  evenAndOddHeaders?: boolean;
+  /** Swap left/right margins on even physical pages. */
+  mirrorMargins?: boolean;
+  /** Per-page footnote reserved heights (pageNumber → height in pixels). */
   footnoteReservedHeights?: Map<number, number>;
   /**
    * Footnote content heights keyed by internal footnote id (the OOXML
@@ -1014,26 +1192,36 @@ type LayoutOptions = {
    * above the fn area) on documents with multiple long footnotes per
    * page.
    */
-  footnoteHeightById?: Map<number, number>; /** Section break type for the body-level (final) section (for section transition logic). */
-  bodyBreakType?: "continuous" | "nextPage" | "evenPage" | "oddPage"; /** Header/footer references for each document section, by section index. */
+  footnoteHeightById?: Map<number, number>;
+  /** Section break type for the body-level (final) section (for section transition logic). */
+  bodyBreakType?: "continuous" | "nextPage" | "evenPage" | "oddPage";
+  /** Header/footer references for each document section, by section index. */
   sectionHeaderFooterRefs?: PageHeaderFooterRefs[];
 };
 /**
  * Result of hit-testing a click position.
  */
 type HitTestResult = {
-  /** Page index (0-based). */pageIndex: number; /** Fragment that was hit, if any. */
-  fragment?: Fragment; /** Local X coordinate within the fragment. */
-  localX?: number; /** Local Y coordinate within the fragment. */
+  /** Page index (0-based). */
+  pageIndex: number;
+  /** Fragment that was hit, if any. */
+  fragment?: Fragment;
+  /** Local X coordinate within the fragment. */
+  localX?: number;
+  /** Local Y coordinate within the fragment. */
   localY?: number;
 };
 /**
  * Position within the document model.
  */
 type DocumentPosition = {
-  /** Block index. */blockIndex: number; /** Run index within the block (for paragraphs). */
-  runIndex?: number; /** Character offset within the run. */
-  charOffset?: number; /** ProseMirror position. */
+  /** Block index. */
+  blockIndex: number;
+  /** Run index within the block (for paragraphs). */
+  runIndex?: number;
+  /** Character offset within the run. */
+  charOffset?: number;
+  /** ProseMirror position. */
   pmPos?: number;
 };
 /**
@@ -1062,10 +1250,15 @@ declare const FOOTNOTE_FALLBACK_LINE_HEIGHT = 13;
  * the bridge and the bridge must not import it from the painter.
  */
 type HeaderFooterContent = {
-  /** Flow blocks for the header/footer content. */blocks: FlowBlock[]; /** Measurements for the blocks. */
-  measures: Measure[]; /** Total height of the content. */
-  height: number; /** Top-most visual extent relative to the nominal flow origin. */
-  visualTop?: number; /** Bottom-most visual extent relative to the nominal flow origin. */
+  /** Flow blocks for the header/footer content. */
+  blocks: FlowBlock[];
+  /** Measurements for the blocks. */
+  measures: Measure[];
+  /** Total height of the content. */
+  height: number;
+  /** Top-most visual extent relative to the nominal flow origin. */
+  visualTop?: number;
+  /** Bottom-most visual extent relative to the nominal flow origin. */
   visualBottom?: number;
   /**
    * Flow-only bounds for consumers that need to distinguish normal