@stll/folio-core 0.0.1-placeholder.0 → 0.1.0

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

@@ -0,0 +1,1031 @@
+import { OutlineStyleAttr } from "../types/documentEnumValues.js";
+import { ImagePosition, ImageWrap, SdtProperties, SdtType, 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, Run, RunFormatting, SdtGroup, SectionBreakBlock, SectionBreakMeasure, TabAlignment, TabRun, TabStop, TableBlock, TableCell, TableCellMeasure, TableFragment, TableMeasure, TableRow, TableRowMeasure, TextBoxBlock, TextBoxFlowAttrs, TextBoxFragment, TextBoxMeasure, TextRun, floatingTextBoxReservesBand, floatingTextBoxWrapsText, isFloatingImageRun, isFloatingTextBoxBlock, isTextWrappingFloatingImageRun };
+}
+/**
+ * Unique identifier for a block in the document.
+ * Format: typically `${index}-${type}` or just the block index.
+ */
+type BlockId = string | number;
+/**
+ * Common run formatting properties applied to text runs.
+ */
+type RunFormatting = {
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean | {
+    style?: string;
+    color?: string;
+  };
+  strike?: boolean;
+  color?: string;
+  textColorSource?: "direct" | "paragraphDefault";
+  highlight?: string;
+  /**
+   * Run-level shading (w:shd) used as a background, stored as a *resolved CSS*
+   * color (like `highlight`). Painted only when there is no `highlight` (an
+   * explicit highlight wins). eigenpal #722 (#712).
+   */
+  shading?: string;
+  fontFamily?: string;
+  /**
+   * Resolved East-Asian font (`w:eastAsia` / `eastAsiaTheme`). CJK code points
+   * in this run measure and paint with this font; non-CJK keeps `fontFamily`
+   * (ascii/hAnsi). Both the measurer and the painter segment identically (see
+   * `segmentByScript`) so wrapping stays correct. Absent means CJK falls back
+   * to `fontFamily`.
+   */
+  eastAsiaFontFamily?: string;
+  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. */
+  kerningMinPt?: number;
+  imprint?: boolean;
+  emboss?: boolean;
+  textShadow?: boolean;
+  textOutline?: boolean;
+  emphasisMark?: "dot" | "comma" | "circle" | "underDot";
+  /**
+   * Hidden run (OOXML w:vanish, §17.3.2.41). Word's print/normal view
+   * suppresses it entirely, but the editing view dims it with a dotted
+   * underline so the author can navigate to and edit it. The painter
+   * mirrors the editing-view treatment so PM cursor traversal works.
+   */
+  hidden?: boolean;
+  /**
+   * Per-run right-to-left direction (w:rtl). When true the painter sets
+   * `dir="rtl"` on the run span; the browser's bidi algorithm handles
+   * reordering. `false` means an explicit override that disables inherited
+   * RTL; the painter sets `dir="ltr"` so style/paragraph RTL does not leak in.
+   */
+  rtl?: boolean;
+  /**
+   * Text effect animation hint (w:effect). Word 2013+ no longer animates,
+   * 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) */
+  changeRevisionId?: number;
+};
+/**
+ * Hyperlink information for a run.
+ */
+type HyperlinkInfo = {
+  href: string;
+  tooltip?: string;
+  /**
+   * When true, the painter must not apply Word-default link styling
+   * (blue + underline) to this run. Set by the bridge for TOC entries —
+   * Word renders TOCx hyperlinks in the paragraph's own colour, not in
+   * the Hyperlink character style. The PM doc keeps the original marks
+   * so copy/paste out of a TOC still carries Hyperlink styling.
+   */
+  noDefaultStyle?: boolean;
+};
+/**
+ * A text run within a paragraph.
+ */
+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. */
+  pmEnd?: number;
+  /**
+   * Set when this run is a template fill-preview substitution: the text is
+   * the typed value while [pmStart, pmEnd) still addresses the source
+   * `{{marker}}` range, so `text.length` may differ from the PM span. The
+   * painter adds the preview classes from this (`highlighted` paints the
+   * accent chip); pm↔char mappers must use the run's own pm bounds instead
+   * of assuming one PM position per character.
+   */
+  templatePreview?: "highlighted" | "plain";
+};
+/**
+ * A tab character run.
+ */
+type TabRun = RunFormatting & {
+  kind: "tab";
+  width?: number;
+  pmStart?: number;
+  pmEnd?: number;
+};
+/**
+ * Position data for floating/anchored images.
+ */
+type ImageRunPosition = {
+  horizontal?: {
+    relativeTo?: NonNullable<ImagePosition["horizontal"]["relativeTo"]>;
+    posOffset?: number;
+    align?: NonNullable<ImagePosition["horizontal"]["alignment"]>;
+  };
+  vertical?: {
+    relativeTo?: NonNullable<ImagePosition["vertical"]["relativeTo"]>;
+    posOffset?: number;
+    align?: NonNullable<ImagePosition["vertical"]["alignment"]>;
+  };
+};
+/**
+ * An inline image run.
+ */
+type ImageRun = {
+  kind: "image";
+  src: string;
+  width: number;
+  height: number;
+  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; /** 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;
+  /**
+   * wp:srcRect crop fractions in [0, 1]; emit as CSS `clip-path: inset(...)`
+   * to match Word's visible region. eigenpal #424 (image-crop subset).
+   */
+  cropTop?: number;
+  cropRight?: number;
+  cropBottom?: number;
+  cropLeft?: number; /** 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;
+};
+/**
+ * A line break run.
+ */
+type LineBreakRun = {
+  kind: "lineBreak";
+  pmStart?: number;
+  pmEnd?: number;
+};
+/**
+ * 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. */
+  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`). */
+  fldLock?: boolean;
+  pmStart?: number;
+  pmEnd?: number;
+};
+/**
+ * A native math equation run. The painter converts `ommlXml` to MathML
+ * and injects a `<math>` element inline; `plainText` is the screen-reader
+ * fallback and the measurer's width estimate.
+ *
+ * The raw OMML XML lives on the run so the painter can re-convert when
+ * markup changes; it is never modified on save (round-trip happens via
+ * 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. */
+  plainText: string;
+  pmStart?: number;
+  pmEnd?: number;
+};
+/**
+ * Union of all run types.
+ */
+type Run = TextRun | TabRun | ImageRun | LineBreakRun | FieldRun | MathRun;
+/**
+ * Paragraph spacing configuration.
+ */
+type ParagraphSpacing = {
+  before?: number;
+  after?: number;
+  line?: number;
+  lineUnit?: "px" | "multiplier";
+  lineRule?: "auto" | "exact" | "atLeast";
+};
+/**
+ * Paragraph indentation configuration.
+ */
+type ParagraphIndent = {
+  left?: number;
+  right?: number;
+  firstLine?: number;
+  hanging?: number;
+};
+/**
+ * Tab stop alignment types
+ */
+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 */
+  leader?: "none" | "dot" | "hyphen" | "underscore" | "heavy" | "middleDot";
+};
+/**
+ * Border specification for paragraphs.
+ */
+type BorderStyle = {
+  style?: string;
+  width?: number;
+  color?: string;
+  space?: number;
+};
+/**
+ * Paragraph borders.
+ */
+type ParagraphBorders = {
+  top?: BorderStyle;
+  bottom?: BorderStyle;
+  left?: BorderStyle;
+  right?: BorderStyle;
+  between?: BorderStyle;
+  bar?: BorderStyle;
+};
+/**
+ * List numbering properties for a paragraph.
+ */
+type ListNumPr = {
+  numId?: number;
+  ilvl?: number;
+};
+/**
+ * Paragraph block attributes.
+ */
+type ParagraphAttrs = {
+  alignment?: "left" | "center" | "right" | "justify";
+  spacing?: ParagraphSpacing;
+  /**
+   * Tracks which `spacing` sides came from inline (`<w:pPr><w:spacing>`)
+   * formatting versus inherited via paragraph style. Word collapses
+   * style-inherited spacing on empty paragraphs (only direct formatting
+   * survives), so the layout engine consults this flag in
+   * `getSpacingBefore`/`getSpacingAfter`. Both sides default to false (style
+   * inheritance assumed) when the field is absent.
+   */
+  spacingExplicit?: {
+    before?: boolean;
+    after?: boolean;
+  };
+  indent?: ParagraphIndent;
+  keepNext?: boolean;
+  keepLines?: boolean;
+  pageBreakBefore?: boolean;
+  styleId?: string;
+  contextualSpacing?: boolean;
+  /**
+   * Run-in heading: paragraph mark carries `<w:specVanish/>` and the
+   * next paragraph should flow inline on the same line. The layout
+   * 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 */
+  bidi?: boolean;
+  borders?: ParagraphBorders;
+  shading?: string;
+  tabs?: TabStop[]; /** Render structural empty paragraphs as zero-height anchors. */
+  suppressEmptyParagraphHeight?: boolean;
+  numPr?: ListNumPr;
+  listMarker?: string;
+  listIsBullet?: boolean;
+  listMarkerHidden?: boolean;
+  listMarkerFontFamily?: string;
+  listMarkerFontSize?: number;
+  /**
+   * `w:suff` (§17.9.25) — what follows the marker before body text.
+   * `tab` (default) grows the marker to the next tab stop; `space` adds
+   * one space glyph; `nothing` lets body text butt against the marker.
+   */
+  listMarkerSuffix?: "tab" | "space" | "nothing";
+  /**
+   * Tracked-change state of the list numbering itself. When a list is applied
+   * (or removed) under suggesting mode, the marker paints in the insertion /
+   * deletion color so an inserted list item's number reads as part of the
+   * suggestion, matching Word. `undefined` = numbering is not a pending change.
+   */
+  listMarkerRevision?: {
+    kind: "ins" | "del";
+    author?: string;
+    date?: string;
+    revisionId?: number;
+  };
+  /**
+   * When the marker text contains a TAB character (\t), the marker is
+   * rendered as a flex layout with two slots; this is the column offset
+   * (in twips, from the marker zone's left edge) where the second slot
+   * lands. Used to align an inline LISTNUM "(a)" with the deeper level's
+   * marker column.
+   */
+  listMarkerSecondSlotOffsetTwips?: number;
+  defaultFontSize?: number;
+  defaultFontFamily?: string;
+  /**
+   * Document-wide `w:defaultTabStop` (§17.6.13) in twips. Read by the list
+   * marker tab-stop math so long markers align body text at the document's
+   * configured grid. Stamped onto every paragraph block by `toFlowBlocks`
+   * so paragraph-local helpers stay decoupled from `Document`.
+   */
+  defaultTabStopTwips?: number;
+};
+/**
+ * A paragraph block containing runs.
+ */
+type ParagraphBlock = {
+  kind: "paragraph";
+  id: BlockId;
+  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. */
+  pmEnd?: number;
+  /**
+   * Outer→inner SDT wrappers enclosing this block. Empty / undefined when
+   * the block sits at the body root. The painter stamps `data-sdt-*` from
+   * the innermost group and draws boundary chrome per outer→inner level.
+   */
+  sdtGroups?: SdtGroup[];
+};
+/**
+ * Cell border specification for rendering.
+ */
+type CellBorderSpec = {
+  width?: number;
+  color?: string;
+  style?: string;
+};
+/**
+ * Cell borders (all four sides).
+ */
+type CellBorders = {
+  top?: CellBorderSpec;
+  bottom?: CellBorderSpec;
+  left?: CellBorderSpec;
+  right?: CellBorderSpec;
+};
+/**
+ * A table cell with content.
+ */
+type TableCell = {
+  id: BlockId;
+  blocks: FlowBlock[];
+  colSpan?: number;
+  rowSpan?: number;
+  width?: number;
+  verticalAlign?: "top" | "center" | "bottom";
+  background?: string;
+  borders?: CellBorders; /** Per-cell padding in pixels (from w:tcMar or table-level w:tblCellMar) */
+  padding?: {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+  };
+  /**
+   * `w:noWrap` (§17.4.30): when true, the cell forbids soft-wrapping inside
+   * it. The painter emits `white-space: nowrap` on the cell box so content
+   * stays on a single line and the cell expands horizontally instead.
+   */
+  noWrap?: boolean;
+};
+/**
+ * A table row containing cells.
+ */
+type TableRow = {
+  id: BlockId;
+  cells: TableCell[];
+  height?: number;
+  heightRule?: "auto" | "atLeast" | "exact";
+  isHeader?: boolean;
+};
+/**
+ * Floating table positioning info (pixel values).
+ */
+type FloatingTablePosition = {
+  horzAnchor?: "margin" | "page" | "text";
+  vertAnchor?: "margin" | "page" | "text";
+  tblpX?: number;
+  tblpXSpec?: "left" | "center" | "right" | "inside" | "outside";
+  tblpY?: number;
+  tblpYSpec?: "top" | "center" | "bottom" | "inside" | "outside" | "inline";
+  topFromText?: number;
+  bottomFromText?: number;
+  leftFromText?: number;
+  rightFromText?: number;
+};
+/**
+ * A table block containing rows.
+ */
+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'). */
+  widthType?: TableWidthType; /** 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). */
+  sdtGroups?: SdtGroup[];
+};
+/**
+ * An anchored/floating image block.
+ */
+type ImageBlock = {
+  kind: "image";
+  id: BlockId;
+  src: string;
+  width: number;
+  height: number;
+  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;
+  anchor?: {
+    isAnchored?: boolean;
+    offsetH?: number;
+    offsetV?: number;
+    behindDoc?: boolean;
+  }; /** Hyperlink URL for clickable image */
+  hlinkHref?: string;
+  /**
+   * wp:srcRect crop fractions in [0, 1]; emit as CSS `clip-path: inset(...)`.
+   * eigenpal #424 (image-crop subset).
+   */
+  cropTop?: number;
+  cropRight?: number;
+  cropBottom?: number;
+  cropLeft?: number;
+  pmStart?: number;
+  pmEnd?: number;
+};
+/**
+ * Section break block defining page layout changes.
+ */
+type SectionBreakBlock = {
+  kind: "sectionBreak";
+  id: BlockId;
+  type?: "continuous" | "nextPage" | "evenPage" | "oddPage";
+  pageSize?: {
+    w: number;
+    h: number;
+  };
+  orientation?: "portrait" | "landscape";
+  margins?: PageMargins;
+  columns?: ColumnLayout;
+};
+type PageHeaderFooterRefs = {
+  titlePg?: boolean;
+  headerDefault?: string;
+  headerFirst?: string;
+  headerEven?: string;
+  footerDefault?: string;
+  footerFirst?: string;
+  footerEven?: string;
+};
+/**
+ * Explicit page break block.
+ */
+type PageBreakBlock = {
+  kind: "pageBreak";
+  id: BlockId;
+  pmStart?: number;
+  pmEnd?: number;
+};
+/**
+ * Column break block.
+ */
+type ColumnBreakBlock = {
+  kind: "columnBreak";
+  id: BlockId;
+  pmStart?: number;
+  pmEnd?: number;
+};
+/** Default internal margins for text boxes (OOXML defaults in pixels) */
+declare const DEFAULT_TEXTBOX_MARGINS: {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+};
+/** Default text box width in pixels when no width is specified */
+declare const DEFAULT_TEXTBOX_WIDTH = 200;
+/**
+ * Text box block — positioned container with paragraph content.
+ */
+type TextBoxBlock = {
+  kind: "textBox";
+  id: BlockId; /** Width in pixels */
+  width: number; /** Height in pixels (may be auto-calculated) */
+  height?: number; /** 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;
+  }; /** Paragraph blocks inside the text box */
+  content: ParagraphBlock[]; /** 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;
+  distRight?: number;
+  pmStart?: number;
+  pmEnd?: number;
+};
+/**
+ * Block-level content-control (OOXML `w:sdt`) projection attached to flow
+ * blocks that fall inside an SDT wrapper. The painter stamps `data-sdt-*`
+ * attributes from this so CSS / interactive widgets can find the group.
+ *
+ * `id` is a per-document, monotonically assigned identifier so nested SDTs
+ * stay disambiguated even when alias/tag/sdtId collide.
+ */
+type SdtGroup = {
+  /** 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). */
+  listItemsJson?: string;
+  /**
+   * Position of the carrying block within its SDT group (`first`/`middle`/
+   * `last`/`only`). The painter stamps `data-sdt-position` from this so the
+   * CSS chrome can draw a continuous outline across the block sequence —
+   * top edge on `first`, bottom edge on `last`, only side edges in
+   * between. Without this, every block painted its own closed box and a
+   * multi-paragraph SDT looked like several stacked rectangles.
+   */
+  position?: "first" | "middle" | "last" | "only";
+};
+/**
+ * Union of all flow block types (input to layout engine).
+ */
+type FlowBlock = ParagraphBlock | TableBlock | ImageBlock | TextBoxBlock | SectionBreakBlock | PageBreakBlock | ColumnBreakBlock;
+/**
+ * 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). */
+  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;
+};
+/**
+ * Measurement result for a paragraph block.
+ */
+type ParagraphMeasure = {
+  kind: "paragraph";
+  lines: MeasuredLine[];
+  totalHeight: number;
+};
+/**
+ * Measurement result for an image block.
+ */
+type ImageMeasure = {
+  kind: "image";
+  width: number;
+  height: number;
+  /**
+   * Leading space (px) layout inserts before the block to clear a page-pinned
+   * topAndBottom band on the same page. Paragraphs absorb this per line via
+   * `floatSkipBefore`; non-paragraph blocks reserve it here. eigenpal #694.
+   */
+  bandSkipBefore?: number;
+};
+/**
+ * Measurement result for a table cell.
+ */
+type TableCellMeasure = {
+  blocks: Measure[];
+  width: number;
+  height: number;
+  colSpan?: number;
+  rowSpan?: number;
+};
+/**
+ * Measurement result for a table row.
+ */
+type TableRowMeasure = {
+  cells: TableCellMeasure[];
+  height: number;
+};
+/**
+ * Measurement result for a table block.
+ */
+type TableMeasure = {
+  kind: "table";
+  rows: TableRowMeasure[];
+  columnWidths: number[];
+  totalWidth: number;
+  totalHeight: number;
+  /** Leading space (px) before the table to clear a page-pinned band on the
+   * same page; applied to the table's first fragment. See {@link ImageMeasure}. */
+  bandSkipBefore?: number;
+};
+/**
+ * Measurement result for section break (no visual size).
+ */
+type SectionBreakMeasure = {
+  kind: "sectionBreak";
+};
+/**
+ * Measurement result for page break (no visual size).
+ */
+type PageBreakMeasure = {
+  kind: "pageBreak";
+};
+/**
+ * Measurement result for column break (no visual size).
+ */
+type ColumnBreakMeasure = {
+  kind: "columnBreak";
+};
+/**
+ * Measurement result for a text box block.
+ */
+type TextBoxMeasure = {
+  kind: "textBox";
+  width: number;
+  height: number; /** Pre-measured inner paragraph measures (avoids re-measuring during render) */
+  innerMeasures: ParagraphMeasure[];
+};
+/**
+ * Union of all measurement types.
+ */
+type Measure = ParagraphMeasure | ImageMeasure | TableMeasure | TextBoxMeasure | SectionBreakMeasure | PageBreakMeasure | ColumnBreakMeasure;
+/**
+ * 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). */
+  pmEnd?: number;
+  /**
+   * Outer→inner SDT wrappers enclosing the originating block. Copied
+   * verbatim from the FlowBlock so the painter can stamp `data-sdt-*`
+   * attributes per fragment.
+   */
+  sdtGroups?: SdtGroup[];
+};
+/**
+ * A paragraph fragment positioned on a page.
+ * 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. */
+  continuesOnNext?: boolean;
+};
+/**
+ * A table fragment positioned on a page.
+ * 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). */
+  headerRowCount?: number;
+  /**
+   * Mid-content row break (eigenpal #698): when a single row is taller than a
+   * whole page it is split across pages between whole text lines. The visible
+   * band of the broken row is `[topClip, bottomClip)` in the row's own
+   * coordinates. `topClip` is the px already shown on the previous page (the
+   * continuation fragment starts here); `bottomClip` is where this fragment
+   * cuts the row. Undefined on fragments that break only at row boundaries.
+   */
+  topClip?: number;
+  bottomClip?: number;
+};
+/**
+ * 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. */
+  zIndex?: number;
+};
+/**
+ * A text box fragment positioned on a page.
+ */
+type TextBoxFragment = FragmentBase & {
+  kind: "textBox"; /** Height of the text box. */
+  height: number;
+};
+/**
+ * Union of all fragment types.
+ */
+type Fragment = ParagraphFragment | TableFragment | ImageFragment | TextBoxFragment;
+/**
+ * Page margin configuration.
+ */
+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. */
+  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). */
+  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). */
+  columns?: ColumnLayout;
+};
+/**
+ * Column layout configuration.
+ */
+type ColumnLayout = {
+  count: number;
+  gap: number;
+  equalWidth?: boolean; /** Draw vertical separator line between columns (w:sep). */
+  separator?: boolean;
+};
+/**
+ * Header/footer layout for a specific type.
+ */
+type HeaderFooterLayout = {
+  height: number;
+  fragments: Fragment[];
+};
+/**
+ * Final layout output ready for rendering/painting.
+ */
+type Layout = {
+  /** 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). */
+  pageGap?: number;
+};
+/**
+ * Header/footer content heights by variant type.
+ */
+type HeaderFooterContentHeights = Partial<Record<"default" | "first" | "even" | "odd", number>>;
+/**
+ * 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. */
+  height: number;
+};
+/**
+ * Options for the layout engine.
+ */
+type LayoutOptions = {
+  /** Initial page size. */pageSize: {
+    w: number;
+    h: number;
+  }; /** Initial page margins. */
+  margins: PageMargins;
+  /**
+   * Margins applied only to page 1 (the title page) when the first
+   * section has `<w:titlePg/>`. Used to extend the top margin for an
+   * overflowing first-page header without forcing pages 2+ to inherit the
+   * same extension.
+   */
+  firstPageMargins?: PageMargins; /** Body-level final section page size. */
+  finalPageSize?: {
+    w: number;
+    h: number;
+  }; /** Body-level final section margins. */
+  finalMargins?: PageMargins; /** 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; /** Per-page footnote reserved heights (pageNumber → height in pixels). */
+  footnoteReservedHeights?: Map<number, number>;
+  /**
+   * Footnote content heights keyed by internal footnote id (the OOXML
+   * `<w:footnoteReference w:id>`). When provided, the layout engine
+   * tracks footnote demand per body line: each line carrying a fn ref
+   * grows its page's reservation by that fn's height before the next
+   * line is fitted. This single-pass approach avoids the static-
+   * reservation + iterative-convergence loop that produced oscillation
+   * (and either body-overflow into the footer or large empty gaps
+   * 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. */
+  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. */
+  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. */
+  pmPos?: number;
+};
+/**
+ * Height of the horizontal separator line drawn above the footnote stack.
+ * Used by the paginator when reserving space and by the painter when laying
+ * out the stack at the bottom of the page.
+ */
+declare const FOOTNOTE_SEPARATOR_HEIGHT = 12;
+/**
+ * Extra bottom margin applied to every rendered footnote entry, in CSS pixels.
+ *
+ * Word footnotes are separate paragraphs in the footnote story, so their
+ * own paragraph spacing already describes the vertical gap between notes.
+ * Keep the wrapper margin at zero to avoid adding whitespace that is not
+ * present in the source DOCX.
+ */
+declare const FOOTNOTE_ENTRY_MARGIN_BOTTOM = 0;
+/**
+ * Line height used when a footnote entry has no measured line height yet.
+ * Conservative fallback so a missing measure does not collapse the entry.
+ */
+declare const FOOTNOTE_FALLBACK_LINE_HEIGHT = 13;
+/**
+ * Header / footer content prepared by the bridge for the painter. Lives here
+ * because both layers reference the shape; the painter must not import it from
+ * 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. */
+  visualBottom?: number;
+  /**
+   * Flow-only bounds used by `computeHeaderFooterMarginExtender` to push
+   * body margins clear of HF overflow. Excludes `behindDoc` images that
+   * the renderer paints behind body content; including them would reserve
+   * a full-page letterhead as body push-down.
+   */
+  marginPushTop?: number;
+  marginPushBottom?: number;
+  /**
+   * Relationship id (`rId`) of the source HF part. Emitted as `data-rid`
+   * on the painted `.layout-page-header` / `.layout-page-footer` so the
+   * pointer pipeline can resolve clicks to the matching hidden HF
+   * EditorView.
+   */
+  rId?: string;
+  /**
+   * Cheap text fingerprint of the rendered blocks. Used to invalidate
+   * cached options hashes so same-height in-place HF edits force the
+   * painter to re-render shells.
+   */
+  textSig?: string;
+};
+/**
+ * `true` when the image run is anchored at page-level coordinates instead of
+ * participating in inline flow. Covers the OOXML floating wrap types
+ * (`square`, `tight`, `through`, `behind`, `inFront`) and the legacy
+ * `displayMode === "float"` escape hatch used by ProseMirror nodes that
+ * pre-date the wrap-type round-trip.
+ *
+ * Pure predicate over `ImageRun` — no DOM, no measurement state. Lives here
+ * so the bridge can call it without importing from the painter.
+ */
+declare const isFloatingImageRun: (run: ImageRun) => boolean;
+/**
+ * `true` when a floating image should also shrink surrounding line widths.
+ * `behind` / `inFront` (wrapNone) and `topAndBottom` do not — text either
+ * paints over/under them or flows above/below as a block — only
+ * `square` / `tight` / `through` carve a horizontal exclusion. The legacy
+ * `displayMode === "float"` path is treated as wrapping when a CSS float
+ * direction is set.
+ */
+declare const isTextWrappingFloatingImageRun: (run: ImageRun) => boolean;
+type TextBoxFlowAttrs = Pick<TextBoxBlock, "displayMode" | "wrapType">;
+/**
+ * `true` when the text box is anchored outside normal block flow — either
+ * via the `float` display mode or via an OOXML floating wrap type (which
+ * includes `topAndBottom`; see {@link floatingTextBoxReservesBand}).
+ */
+declare function isFloatingTextBoxBlock(block: TextBoxFlowAttrs): boolean;
+/**
+ * `true` when a floating text box should also reduce surrounding text
+ * line widths. Excludes wrapNone (`behind`/`inFront`) and `topAndBottom`
+ * which are positioned floats but do not carve a horizontal exclusion.
+ */
+declare function floatingTextBoxWrapsText(block: TextBoxFlowAttrs): boolean;
+/**
+ * `true` when a floating text box reserves a full-width vertical band rather
+ * than a side exclusion. `topAndBottom` boxes break the text above and below
+ * the box (no text beside it), so surrounding lines flow past the band.
+ * Ported from eigenpal #694.
+ */
+declare function floatingTextBoxReservesBand(block: TextBoxFlowAttrs): boolean;
+//#endregion
+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, Run, RunFormatting, SdtGroup, SectionBreakBlock, SectionBreakMeasure, TabAlignment, TabRun, TabStop, TableBlock, TableCell, TableCellMeasure, TableFragment, TableMeasure, TableRow, TableRowMeasure, TextBoxBlock, TextBoxFlowAttrs, TextBoxFragment, TextBoxMeasure, TextRun, floatingTextBoxReservesBand, floatingTextBoxWrapsText, isFloatingImageRun, isFloatingTextBoxBlock, isTextWrappingFloatingImageRun, types_d_exports };