@docx-editor.dev/core 2.25.0 → 2.27.0

package/dist/{protocol-BhmenALD.d.ts → protocol-aKYr8r3u.d.ts}

@@ -1,5 +1,14 @@
-import { a6 as AutomationTableMutation, a3 as RevisionBatchResult } from './types-barrel-BO73JqHG.js';
-import { e as HeaderFooterVariant, N as NoteKind } from './tree-package-fragment-YPyYC1aD.js';
+import { a6 as AutomationTableMutation, a3 as RevisionBatchResult } from './types-barrel-BFKR8Pzp.js';
+import { c as HeaderFooterVariant, N as NoteKind } from './tree-package-fragment-DYZIk1rY.js';
+
+/** Word's shape types, as `Word.ShapeType` spells them. */
+type AutomationShapeType = 'TextBox' | 'GeometricShape' | 'Picture' | 'Group' | 'Canvas' | 'Unsupported';
+/** What a shape read answers. */
+interface AutomationShapeRead {
+    readonly id: number;
+    readonly name: string;
+    readonly type: AutomationShapeType;
+}
 
 interface AutomationInlinePictureRead {
     readonly width: number;
@@ -193,6 +202,21 @@ type AutomationAuthoringOperation = {
     readonly rowCount: number;
     readonly columnCount: number;
     readonly values?: readonly (readonly string[])[];
+}
+/** The floating shapes anchored in a span's paragraphs, in reading order. */
+ | {
+    readonly op: 'getShapes';
+    readonly span: AutomationSpanRef;
+    /** Only shapes of these types. Absent lists every type. */
+    readonly types?: readonly AutomationShapeType[];
+} | {
+    readonly op: 'getShape';
+    readonly shape: AutomationHandle;
+}
+/** A text box's own story. Any other shape has no body and refuses. */
+ | {
+    readonly op: 'getShapeBody';
+    readonly shape: AutomationHandle;
 } | {
     readonly op: 'getInlinePictures';
     readonly span: AutomationSpanRef;
@@ -653,9 +677,10 @@ type AutomationOperation = AutomationAuthoringOperation | {
 /**
  * The header or footer story a section declares or inherits, as a BODY.
  *
- * A variant the document has neither declared nor inherited is refused: minting the part would
- * make a read write, and a header that exists only because it was asked about is a header the
- * document did not have.
+ * A variant the document has neither declared nor inherited is still answered, as an empty
+ * body: every read on it answers what it answers for an empty story. Asking does not create
+ * the part. The first text written into the body creates it; any other write that would change
+ * the body is refused until then.
  */
  | {
     readonly op: 'getFurniture';
@@ -1251,7 +1276,7 @@ type AutomationOperationKind = AutomationOperation['op'];
  * `body` is one STORY — the main body, a header or footer variant of a section, or one note — so
  * every object reached through a body is reached in a named story rather than in "the document".
  */
-type AutomationObjectKind = 'document' | 'body' | 'paragraph' | 'section' | 'note' | 'comment' | 'revision' | 'bookmark' | 'list' | 'contentControl' | 'table' | 'tableRow' | 'tableCell' | 'field' | 'inlinePicture';
+type AutomationObjectKind = 'document' | 'body' | 'paragraph' | 'section' | 'note' | 'comment' | 'revision' | 'bookmark' | 'list' | 'contentControl' | 'table' | 'tableRow' | 'tableCell' | 'field' | 'inlinePicture' | 'shape';
 declare const AUTOMATION_HANDLE_BRAND: unique symbol;
 /**
  * An opaque host-minted name for a document object.
@@ -1416,6 +1441,9 @@ type AutomationValue = {
 } | {
     readonly kind: 'inlinePicture';
     readonly picture: AutomationInlinePictureRead;
+} | {
+    readonly kind: 'shape';
+    readonly shape: AutomationShapeRead;
 } | {
     readonly kind: 'handle';
     readonly handle: AutomationHandle;

package/dist/{review-paragraph-order-BwhRT264.d.ts → review-paragraph-order-Ddj5d6rp.d.ts}

@@ -1,4 +1,4 @@
-import { N as OoxmlNode, Z as OoxmlElement, _ as OoxmlContentControlNode, V as OoxmlGenericElementNode, $ as OoxmlContentControlContentNode, C as CommentRecord, O as OoxmlPart } from './types-barrel-BO73JqHG.js';
+import { N as OoxmlNode, Z as OoxmlElement, _ as OoxmlContentControlNode, V as OoxmlGenericElementNode, $ as OoxmlContentControlContentNode, C as CommentRecord, O as OoxmlPart } from './types-barrel-BFKR8Pzp.js';
 
 /** Nested content-control wrappers deeper than this stop flattening; content stays preserved. */
 declare const MAX_CONTENT_CONTROL_NESTING = 32;
@@ -57,7 +57,11 @@ declare function walkParagraphInline(children: readonly OoxmlNode[], depth: numb
     readonly descendRevisions?: boolean;
 }): void;
 
-/** Plain text of a comment's body, so a card never re-implements the run walk. */
+/**
+ * Plain text of a comment's body, as a card shows it: a non-breaking hyphen is U+2011, an
+ * optional hyphen shows nothing, and a symbol shows its glyph. A card never re-implements the
+ * run walk.
+ */
 declare function commentBodyText(comment: CommentRecord): string;
 /** Author initials for an avatar, from `@w:initials` or the name. */
 declare function commentInitials(comment: CommentRecord): string;

package/dist/{revision-projection-DfWxdBqA.d.ts → revision-projection-CSNFudZY.d.ts}

@@ -1,4 +1,74 @@
-import { N as OoxmlNode } from './types-barrel-BO73JqHG.js';
+import { N as OoxmlNode } from './types-barrel-BFKR8Pzp.js';
+
+/** Named revision colors. Identifiers are stable and never contain CSS. @public */
+declare const REVISION_MARKUP_COLORS: readonly ['black', 'blue', 'turquoise', 'green', 'pink', 'red', 'yellow', 'white', 'darkBlue', 'teal', 'darkGreen', 'violet', 'darkRed', 'darkYellow', 'gray50', 'gray25', 'lightBlue', 'lightYellow', 'lightOrange', 'lightPurple', 'lightGreen', 'gray'];
+/** @public */
+type RevisionMarkupNamedColor = (typeof REVISION_MARKUP_COLORS)[number];
+/** @public */
+type RevisionMarkupColor = RevisionMarkupNamedColor | 'byAuthor' | 'auto';
+/** @public */
+type RevisionMarkupMark = 'none' | 'colorOnly' | 'bold' | 'italic' | 'underline' | 'doubleUnderline' | 'strikethrough' | 'doubleStrikethrough';
+/** @public */
+type RevisionDeletionMark = RevisionMarkupMark | 'hidden' | 'caret' | 'pound';
+/** @public */
+type RevisionChangedLinesMark = 'none' | 'leftBorder' | 'rightBorder' | 'outsideBorder';
+/** @public */
+interface RevisionMarkupStyle<Mark extends string = RevisionMarkupMark> {
+    readonly mark: Mark;
+    readonly color: RevisionMarkupColor;
+}
+/** Viewer-only text styling. Document highlighting remains unchanged. @public */
+interface RevisionMarkupTextStyle<Mark extends string = RevisionMarkupMark> extends RevisionMarkupStyle<Mark> {
+    /** Background color behind revision text. Defaults to `none`. */
+    readonly background: RevisionMarkupNamedColor | 'byAuthor' | 'none';
+}
+/** Fully resolved, immutable viewer preferences. @public */
+interface ResolvedRevisionMarkup {
+    readonly insertions: RevisionMarkupTextStyle;
+    readonly deletions: RevisionMarkupTextStyle<RevisionDeletionMark>;
+    readonly movedFrom: RevisionMarkupTextStyle<RevisionDeletionMark>;
+    readonly movedTo: RevisionMarkupTextStyle;
+    readonly formatting: RevisionMarkupTextStyle;
+    readonly changedLines: RevisionMarkupStyle<RevisionChangedLinesMark>;
+    readonly cells: {
+        readonly inserted: RevisionMarkupNamedColor | 'byAuthor' | 'none';
+        readonly deleted: RevisionMarkupNamedColor | 'byAuthor' | 'none';
+        readonly merged: RevisionMarkupNamedColor | 'byAuthor' | 'none';
+        readonly split: RevisionMarkupNamedColor | 'byAuthor' | 'none';
+    };
+    readonly trackMoves: boolean;
+    readonly trackFormatting: boolean;
+}
+/** Partial viewer preferences. Omitted values keep the previous value. @public */
+type RevisionMarkupOptions = {
+    readonly [K in keyof ResolvedRevisionMarkup]?: ResolvedRevisionMarkup[K] extends boolean ? boolean : Partial<ResolvedRevisionMarkup[K]>;
+};
+/** Initial viewer preferences. @public */
+declare const DEFAULT_REVISION_MARKUP: ResolvedRevisionMarkup;
+/** Validate and merge preferences without modifying the input. @public */
+declare function resolveRevisionMarkup(input?: RevisionMarkupOptions, previous?: ResolvedRevisionMarkup): ResolvedRevisionMarkup;
+/** A local settings draft owned by the editor. @public */
+interface RevisionMarkupDialogSession {
+    /** Aborts on close, replacement, load, detach, destroy, or renderer disposal. */
+    readonly signal: AbortSignal;
+    /** Read the immutable draft. */
+    get(): ResolvedRevisionMarkup;
+    /** Merge validated options into the draft without committing preferences. */
+    set(options: RevisionMarkupOptions): void;
+    /** Restore default preferences in the draft only. */
+    reset(): void;
+    /** Observe draft changes, including effective external preference changes. */
+    subscribe(listener: () => void): () => void;
+    canApply(): boolean;
+    /** Commit the draft and close. Returns false after cancellation. */
+    apply(): boolean;
+    /** Close without committing the draft. */
+    cancel(): void;
+}
+/** Host rendering for the Track changes options dialog. @public */
+interface RevisionMarkupChromeHandlers {
+    readonly onRequest?: (session: RevisionMarkupDialogSession) => void;
+}
 
 /**
  * What a revision wrapper asserts about the content inside it.
@@ -59,6 +129,7 @@ declare const DEFAULT_REVISION_DISPLAY_MODE: RevisionDisplayMode;
  * delimiter-based key.
  */
 interface RevisionFilter {
+    readonly revisionMarkup?: ResolvedRevisionMarkup;
     readonly hiddenAuthors: ReadonlySet<string>;
     readonly includes?: (revision: RevisionAttribution) => boolean;
     readonly includesNode?: (nodeId: string, author: string) => boolean;
@@ -167,5 +238,5 @@ declare function formatRevisionOf(properties: readonly {
 /** True when this stack of revisions marks its content as deleted from the live document. */
 declare function revisionsAreDeletion(revisions: readonly RevisionAttribution[]): boolean;
 
-export { DEFAULT_REVISION_DISPLAY_MODE as D, formatRevisionOf as f, paragraphMarkRevisionOf as g, paragraphMarkRevisionsOf as h, revisionsAreDeletion as i, revisionsVisible as j, markRevisionRemovesMark as m, paragraphMarkFormatRevisionOf as p, revisionAuthorFilter as r, shownMarkRevision as s };
-export type { ReviewDisplayMode as R, RevisionDisplayMode as a, RevisionAuthorFilter as b, RevisionAttribution as c, RevisionFilter as d, RevisionKind as e };
+export { revisionsVisible as A, shownMarkRevision as B, DEFAULT_REVISION_MARKUP as D, REVISION_MARKUP_COLORS as f, DEFAULT_REVISION_DISPLAY_MODE as p, resolveRevisionMarkup as r, formatRevisionOf as t, markRevisionRemovesMark as u, paragraphMarkFormatRevisionOf as v, paragraphMarkRevisionOf as w, paragraphMarkRevisionsOf as x, revisionAuthorFilter as y, revisionsAreDeletion as z };
+export type { RevisionMarkupDialogSession as R, ReviewDisplayMode as a, RevisionDisplayMode as b, RevisionAuthorFilter as c, ResolvedRevisionMarkup as d, RevisionMarkupOptions as e, RevisionChangedLinesMark as g, RevisionDeletionMark as h, RevisionMarkupChromeHandlers as i, RevisionMarkupColor as j, RevisionMarkupMark as k, RevisionMarkupNamedColor as l, RevisionMarkupStyle as m, RevisionMarkupTextStyle as n, RevisionAttribution as o, RevisionFilter as q, RevisionKind as s };

package/dist/{semantic-cell-selection-CC3NwCtx.d.ts → semantic-cell-selection-DoqYCz_F.d.ts}

@@ -1,7 +1,25 @@
-import { O as OoxmlPart, Z as OoxmlElement, N as OoxmlNode } from './types-barrel-BO73JqHG.js';
-import { a as RevisionDisplayMode, b as RevisionAuthorFilter } from './revision-projection-DfWxdBqA.js';
-import { b as SectionPageBorders, P as PageGeometry, I as InlineDrawingRecord, A as AnchoredDrawingRecord, T as TextMeasurer, L as LineRecord, a as StyleSpanRecord, S as SemanticLayout, C as ContentControlBoundaryRecord, c as TableRowFragmentRecord, d as TableCellFragmentRecord } from './semantic-records-DrExlBy-.js';
-import { S as SemanticPosition, C as CaretGeometry, a as SemanticSelection } from './semantic-interaction-BHlV61hK.js';
+import { O as OoxmlPart, Z as OoxmlElement, N as OoxmlNode } from './types-barrel-BFKR8Pzp.js';
+import { b as RevisionDisplayMode, c as RevisionAuthorFilter } from './revision-projection-CSNFudZY.js';
+import { f as SectionPageBorders, I as InlineDrawingRecord, A as AnchoredDrawingRecord, T as TextMeasurer, L as LineRecord, e as StyleSpanRecord, S as SemanticLayout, C as ContentControlBoundaryRecord, g as TableRowFragmentRecord, h as TableCellFragmentRecord } from './semantic-records-B9OolWGN.js';
+import { S as SemanticPosition, C as CaretGeometry, a as SemanticSelection } from './semantic-interaction-G0bjmmmk.js';
+
+/** Page geometry, in points. */
+interface PageGeometry {
+    readonly width: number;
+    readonly height: number;
+    readonly margin: {
+        readonly top: number;
+        readonly right: number;
+        readonly bottom: number;
+        readonly left: number;
+    };
+    /** `w:pgMar/@header` — sheet edge to header top, in points. Defaults to 36 (720 twips). */
+    readonly headerDistance?: number;
+    /** `w:pgMar/@footer` — sheet edge to footer bottom, in points. Defaults to 36. */
+    readonly footerDistance?: number;
+}
+/** US Letter with one-inch margins, in points. */
+declare const DEFAULT_PAGE_GEOMETRY: PageGeometry;
 
 /**
  * Hard ceiling on sections enumerated from a document (matches write-path
@@ -422,7 +440,7 @@ declare function cellSelectionRects(layout: SemanticLayout, cellIds: readonly st
  * the only shape that survives the trip: the text range a rectangle stands in for would paste
  * back as one run of characters with the grid gone.
  */
-declare function cellSelectionText(layout: SemanticLayout, selection: CellSelection): string;
+declare function cellSelectionText(layout: SemanticLayout, selection: CellSelection, paragraphText?: (layout: SemanticLayout, paragraphId: string) => string): string;
 /** Where a paragraph sits in a table, if it sits in one. */
 interface TableCellContext {
     readonly tableId: string;
@@ -440,5 +458,5 @@ interface TableCellContext {
  */
 declare function tableContextAt(layout: SemanticLayout, paragraphId: string): TableCellContext | null;
 
-export { pageAtY as A, paragraphSectionNode as B, DEFAULT_SECTION_PROPERTIES as D, paragraphsInCells as E, parsePageNumbering as F, parseSectionProperties as G, projectedSectionSourceIndexes as I, readSectionProperties as J, spanOffsetX as K, spansInCells as L, MAX_DOCUMENT_SECTIONS as M, tableContextAt as N, DEFAULT_VERTICAL_WEIGHT as b, caretBoxOnLine as n, cellSelectionBetween as o, cellSelectionRects as p, cellSelectionText as q, contentControlAtPoint as r, enumerateDocumentSections as s, enumerateDocumentSectionsBounded as t, findDrawingOverlayFrameInLayout as u, geometryOfSection as v, hitTestPage as w, hitTestSheet as x, isFurniturePoint as y, lineEndOffset as z };
-export type { CellSelection as C, HitPoint as H, PlacedCell as P, SectionProperties as S, TableCellAddress as T, SectionColumns as a, DocumentSection as c, DocumentSectionsEnumeration as d, DrawingOverlayFrame as e, HitTestOptions as f, SectionBreakType as g, SectionColumnDefinition as h, SectionMargins as i, SectionPageNumbering as j, SemanticHit as k, SemanticHitDrawing as l, TableCellContext as m };
+export { isFurniturePoint as A, lineEndOffset as B, DEFAULT_PAGE_GEOMETRY as D, pageAtY as E, paragraphSectionNode as F, paragraphsInCells as G, parsePageNumbering as I, parseSectionProperties as J, projectedSectionSourceIndexes as K, readSectionProperties as L, MAX_DOCUMENT_SECTIONS as M, spanOffsetX as N, spansInCells as O, tableContextAt as Q, DEFAULT_SECTION_PROPERTIES as b, DEFAULT_VERTICAL_WEIGHT as c, caretBoxOnLine as p, cellSelectionBetween as q, cellSelectionRects as r, cellSelectionText as s, contentControlAtPoint as t, enumerateDocumentSections as u, enumerateDocumentSectionsBounded as v, findDrawingOverlayFrameInLayout as w, geometryOfSection as x, hitTestPage as y, hitTestSheet as z };
+export type { CellSelection as C, HitPoint as H, PageGeometry as P, SectionProperties as S, TableCellAddress as T, SectionColumns as a, DocumentSection as d, DocumentSectionsEnumeration as e, DrawingOverlayFrame as f, HitTestOptions as g, PlacedCell as h, SectionBreakType as i, SectionColumnDefinition as j, SectionMargins as k, SectionPageNumbering as l, SemanticHit as m, SemanticHitDrawing as n, TableCellContext as o };

package/dist/{semantic-interaction-BHlV61hK.d.ts → semantic-interaction-G0bjmmmk.d.ts}

@@ -1,4 +1,4 @@
-import { T as TextMeasurer, S as SemanticLayout, B as BlockFragmentRecord, C as ContentControlBoundaryRecord, a as StyleSpanRecord } from './semantic-records-DrExlBy-.js';
+import { T as TextMeasurer, S as SemanticLayout, B as BlockFragmentRecord, C as ContentControlBoundaryRecord, e as StyleSpanRecord } from './semantic-records-B9OolWGN.js';
 
 /** A caret position in the model. */
 interface SemanticPosition {

package/dist/{semantic-paint-DfWIWUs6.d.ts → semantic-paint-CsMzF8-O.d.ts}

@@ -1,5 +1,7 @@
-import { C as ContentControlBoundaryRecord, S as SemanticLayout } from './semantic-records-DrExlBy-.js';
-import { V as ValidatedImageBytesHandle, R as RenderableImageMime } from './image-resources-DfagDguq.js';
+import { d as ResolvedRevisionMarkup } from './revision-projection-CSNFudZY.js';
+import { a as PageRecord, C as ContentControlBoundaryRecord, S as SemanticLayout } from './semantic-records-B9OolWGN.js';
+import { S as SemanticRootStoryKind } from './semantic-record-queries-1du6lQqS.js';
+import { V as ValidatedImageBytesHandle, R as RenderableImageMime } from './image-resources-BDFxcu7W.js';
 
 /**
  * Everything a host can say about ONE author's presentation. Every field is optional and
@@ -101,6 +103,21 @@ interface ReviewAuthorInfo {
     /** The host-supplied style, normalised; absent when the author rides the ramp. */
     readonly style?: RevisionAuthorStyle;
 }
+/**
+ * The resolved form the painter consumes: the document's author→slot map, the host's
+ * per-author styles, what UNSTYLED authors take, and the paint-reuse key for all of it.
+ * `null` means the default kind colouring for everyone.
+ */
+interface RevisionStyleContext {
+    readonly authorSlots: ReadonlyMap<string, number>;
+    readonly styles: ReadonlyMap<string, RevisionAuthorStyle>;
+    /** `spanClassName` pre-split into tokens, so paint does not split per span. */
+    readonly classTokens: ReadonlyMap<string, readonly string[]>;
+    /** Authors without a style: `'kind'` colours, or the ramp. */
+    readonly others: 'kind' | 'author';
+    /** See {@link revisionStyleContextKey}. Computed once, with the context. */
+    readonly key: string;
+}
 
 /** Host port for safe blob URLs — only called for {@link ImageResourceState.kind} `ready`. */
 interface PaintImageUrlPort {
@@ -120,8 +137,40 @@ interface DrawingPaintStrings {
     readonly pendingResource: string;
 }
 
-/** Which bars a paint draws: the view's own, or none for the resolved views. */
+/** Which bars a paint draws. @public */
 type ChangeBarsMode = 'all-markup' | 'simple-markup' | 'none';
+/** Which story a bar stands beside; the header-editing chrome dims every other story's. */
+type BarStory = Exclude<SemanticRootStoryKind, 'note-separator'>;
+/** One rule in sheet coordinates (points from the page's top-left corner). */
+interface BarRun {
+    author?: string;
+    color?: string;
+    top: number;
+    bottom: number;
+    story: BarStory;
+    insertion: boolean;
+    deletion: boolean;
+    format: boolean;
+}
+/** Page change bars in page coordinates. @public */
+interface PageChangeBars {
+    readonly mode: ChangeBarsMode;
+    readonly color?: string;
+    /** Whether the bars take the pointer as Word's toggle. */
+    readonly toggle: boolean;
+    /** Sheet-relative x of the column, already scaled and snapped to a whole pixel. */
+    readonly left: number;
+    readonly runs: readonly BarRun[];
+    /** Cheap identity of `left` + `runs`, for the block-adoption path to compare. */
+    readonly signature: string;
+}
+/**
+ * The rules one page needs, in sheet coordinates: every root story the page paints, the
+ * blocks of each (tracked rows and rotated cells included), and the text-box stories its
+ * anchored drawings carry, each at the origin the painter places it at.
+ * @public
+ */
+declare function collectPageChangeBars(page: PageRecord, scale: number, mode: ChangeBarsMode, toggle?: boolean, markup?: ResolvedRevisionMarkup, facingPages?: boolean, colors?: RevisionStyleContext): PageChangeBars;
 
 /**
  * When a field's result is drawn on its grey block, following Word's own View option.
@@ -179,6 +228,9 @@ interface PaintOptions {
      * See {@link RevisionStyles}.
      */
     readonly revisionStyles?: RevisionStyles;
+    readonly revisionMarkup?: ResolvedRevisionMarkup;
+    readonly revisionKindColors?: boolean;
+    readonly facingPages?: boolean;
     /**
      * Which change bars the margin draws: All Markup's neutral rule beside attributed lines
      * (the default, whatever the layout's projection — a layout that carries attribution gets
@@ -270,5 +322,5 @@ interface PaintOptions {
  */
 declare function paintSemanticLayout(container: HTMLElement, layout: SemanticLayout, options?: PaintOptions): void;
 
-export { DEFAULT_FIELD_SHADING as D, paintSemanticLayout as p };
-export type { FieldShadingMode as F, PaintOptions as P, ReviewAuthorInfo as R, RevisionAuthorAssignments as a, RevisionAuthorStyle as b, RevisionStyles as c, DrawingPaintStrings as d };
+export { DEFAULT_FIELD_SHADING as D, collectPageChangeBars as e, paintSemanticLayout as p };
+export type { ChangeBarsMode as C, FieldShadingMode as F, PageChangeBars as P, ReviewAuthorInfo as R, PaintOptions as a, RevisionAuthorAssignments as b, RevisionAuthorStyle as c, RevisionStyles as d, DrawingPaintStrings as f };

package/dist/semantic-record-queries-1du6lQqS.d.ts

@@ -0,0 +1,177 @@
+import { I as InlineDrawingRecord, A as AnchoredDrawingRecord, P as ParagraphFragmentRecord, L as LineRecord, a as PageRecord, N as NoteAreaRecord, b as LayoutBox, H as HeaderFooterStoryRecord, c as NoteStoryRecord, B as BlockFragmentRecord, S as SemanticLayout, C as ContentControlBoundaryRecord, d as ContentControlLock } from './semantic-records-B9OolWGN.js';
+
+/**
+ * Depth-first paragraph fragments of one page, in reading order.
+ *
+ * Table interiors flatten through rows and cells; header-repeat rows are skipped unless
+ * asked for, so interaction sees each caret stop exactly once while paint sees everything.
+ */
+declare function paragraphFragmentsOf(page: PageRecord, includeHeaderRepeats?: boolean): ParagraphFragmentRecord[];
+declare function paragraphFragmentsOfBlocks(blocks: readonly BlockFragmentRecord[], includeHeaderRepeats?: boolean): ParagraphFragmentRecord[];
+/** Every line in a layout, in reading order — the order caret navigation walks. */
+declare function linesOf(layout: SemanticLayout): LineRecord[];
+/** The fragment-plus-anchored-drawings shape every laid-out story shares. */
+interface StoryDrawingHost {
+    /** Root story fragments in their published reading order. */
+    readonly fragments: readonly BlockFragmentRecord[];
+    /** Story-level positioned drawings, when that story supports anchors. */
+    readonly anchoredDrawings?: readonly AnchoredDrawingRecord[];
+}
+/** Root story kinds published directly from one page record. @public */
+type SemanticRootStoryKind = 'body' | 'header' | 'footer' | 'footnote' | 'endnote' | 'note-separator';
+/** Story containing a visited semantic record. @public */
+type SemanticStoryKind = SemanticRootStoryKind | 'textbox';
+/**
+ * One root story in the engine's complete published page/story order.
+ *
+ * The story discriminant preserves the precise published host type so exporters can consume
+ * furniture and note metadata without casting or searching the page graph a second time.
+ * @public
+ */
+type SemanticStoryVisit = {
+    readonly page: PageRecord;
+    readonly story: 'body';
+    readonly host: PageRecord;
+    /** Absolute story bounds; body records are relative to the page content box. */
+    readonly box: LayoutBox;
+    /** Absolute origin to add to story-relative fragment and drawing coordinates. */
+    readonly origin: Readonly<{
+        x: number;
+        y: number;
+    }>;
+    readonly noteScopeId: null;
+    readonly noteAreaKind: null;
+} | {
+    readonly page: PageRecord;
+    readonly story: 'header' | 'footer';
+    readonly host: HeaderFooterStoryRecord;
+    readonly box: LayoutBox;
+    readonly origin: Readonly<{
+        x: number;
+        y: number;
+    }>;
+    readonly noteScopeId: null;
+    readonly noteAreaKind: null;
+} | {
+    readonly page: PageRecord;
+    readonly story: 'footnote' | 'endnote';
+    readonly host: NoteStoryRecord;
+    readonly box: LayoutBox;
+    readonly origin: Readonly<{
+        x: number;
+        y: number;
+    }>;
+    readonly noteScopeId: string;
+    readonly noteAreaKind: NoteAreaRecord['kind'];
+} | {
+    readonly page: PageRecord;
+    readonly story: 'note-separator';
+    readonly host: NonNullable<NoteAreaRecord['separator']>;
+    readonly box: LayoutBox;
+    readonly origin: Readonly<{
+        x: number;
+        y: number;
+    }>;
+    readonly noteScopeId: null;
+    readonly noteAreaKind: NoteAreaRecord['kind'];
+};
+/** Visit every root story in a semantic layout, preserving page/story order. @public */
+declare function forEachSemanticStory(layout: SemanticLayout, visit: (story: SemanticStoryVisit) => void): void;
+/** Location of one paragraph fragment within a recursively painted story graph. @public */
+interface StoryParagraphFragmentContext {
+    /** Absolute origin of the immediate story containing this record. */
+    readonly storyOrigin: Readonly<{
+        x: number;
+        y: number;
+    }>;
+    /** Zero for the supplied story; increments for every textbox boundary. */
+    readonly textboxDepth: number;
+    /** Drawing whose textbox directly owns this fragment, or null for the root story. */
+    readonly textboxOwner: TextboxOwnerRecord | null;
+    /** Root-to-leaf owning drawings, empty for the supplied story. */
+    readonly textboxPath: readonly TextboxOwnerRecord[];
+}
+/** A drawing that owns a text-box story: anchored, or inline on a line. @public */
+type TextboxOwnerRecord = InlineDrawingRecord | AnchoredDrawingRecord;
+/** Location of one drawing within a recursively painted story graph. @public */
+interface StoryDrawingContext extends StoryParagraphFragmentContext {
+    /** Enclosing paragraph for an inline drawing; null for a story-level anchor. */
+    readonly paragraph: ParagraphFragmentRecord | null;
+    /** Enclosing line for an inline drawing; null for a story-level anchor. */
+    readonly line: LineRecord | null;
+}
+type RootDrawingOrigin = (drawing: AnchoredDrawingRecord) => Readonly<{
+    x: number;
+    y: number;
+}>;
+/** Drawing layer relative to its owning story's text. @public */
+type SemanticDrawingLayer = 'behind-text' | 'inline' | 'in-front-of-text';
+/**
+ * One drawing in bounded graph-enumeration order with exporter-grade provenance.
+ *
+ * Enumeration is deliberately not paint order: story anchors (and nested textboxes) are visited
+ * before inline line drawings. Renderers use `paintLayer` plus record geometry to compose layers.
+ * @public
+ */
+interface SemanticDrawingVisit extends StoryDrawingContext {
+    /** Physical page carrying this drawing occurrence. */
+    readonly page: PageRecord;
+    /** Immediate story classification; `textbox` after textbox descent. */
+    readonly story: SemanticStoryKind;
+    /** Root story from which textbox descent began. */
+    readonly rootStory: SemanticRootStoryKind;
+    /** Note scope for drawings in note stories; null elsewhere. */
+    readonly noteScopeId: string | null;
+    /** Owning note-area kind for note/separator drawings; null elsewhere. */
+    readonly noteAreaKind: NoteAreaRecord['kind'] | null;
+    /** Precise root host and absolute origin for story-relative geometry. */
+    readonly root: SemanticStoryVisit;
+    /** Absolute origin of this drawing's extent in page-stack coordinates. */
+    readonly drawingOrigin: Readonly<{
+        x: number;
+        y: number;
+    }>;
+    /** Absolute painted bounds, including effects and clipping. */
+    readonly absolutePaintBounds: LayoutBox;
+    /** Absolute pointer/hit bounds. */
+    readonly absoluteHitBounds: LayoutBox;
+    /** Layer relative to text in the immediate owning story. */
+    readonly paintLayer: SemanticDrawingLayer;
+    /** Published drawing record; inline visits also carry paragraph and line. */
+    readonly drawing: InlineDrawingRecord | AnchoredDrawingRecord;
+}
+/** Visit every drawing through the canonical root-story and recursive textbox walks. @public */
+declare function forEachSemanticDrawing(layout: SemanticLayout, visit: (drawing: SemanticDrawingVisit) => void): void;
+/**
+ * Visit every paragraph fragment one story paints — its own (table interiors flattened,
+ * header repeats included) and the fragments inside each anchored drawing's text-box story,
+ * recursively.
+ *
+ * The fragment sibling of {@link forEachStoryDrawing}, sharing its depth bound, for
+ * consumers that read per-paragraph published fields (list markers) rather than drawings.
+ * The furniture list-marker token walks with this; a fragment it misses leaves a reused
+ * page showing a stale marker.
+ */
+declare function forEachStoryParagraphFragment(story: StoryDrawingHost, visit: (fragment: ParagraphFragmentRecord, context: StoryParagraphFragmentContext) => void, rootOrigin?: Readonly<{
+    x: number;
+    y: number;
+}>, rootDrawingOrigin?: RootDrawingOrigin): void;
+/** Every fragment belonging to one paragraph, in order, across page boundaries. */
+declare function fragmentsOfParagraph(layout: SemanticLayout, paragraphId: string): ParagraphFragmentRecord[];
+/** The line containing a model position, or null when the position is not laid out. */
+declare function lineAtPosition(layout: SemanticLayout, paragraphId: string, offset: number, 
+/** Lines to test, when the caller already knows which ones can carry the paragraph. */
+candidates?: Iterable<LineRecord>): LineRecord | null;
+/** Every content-control boundary on a layout, preferring the layout-level list. */
+declare function contentControlsOfLayout(layout: SemanticLayout): readonly ContentControlBoundaryRecord[];
+/**
+ * Axis-aligned union of boxes, or null when the list is empty.
+ *
+ * Used when a control's content spans several fragments or spans on one page.
+ */
+declare function unionLayoutBoxes(boxes: readonly LayoutBox[]): LayoutBox | null;
+/** Collapse raw + ancestor locks into one `ST_Lock` vocabulary value. */
+declare function effectiveContentControlLock(locks: readonly ContentControlLock[]): ContentControlLock;
+
+export { contentControlsOfLayout as h, effectiveContentControlLock as i, forEachSemanticDrawing as j, forEachSemanticStory as k, forEachStoryParagraphFragment as l, fragmentsOfParagraph as m, lineAtPosition as n, linesOf as o, paragraphFragmentsOf as p, paragraphFragmentsOfBlocks as q, unionLayoutBoxes as u };
+export type { SemanticRootStoryKind as S, TextboxOwnerRecord as T, SemanticStoryKind as a, SemanticStoryVisit as b, SemanticDrawingLayer as c, SemanticDrawingVisit as d, StoryDrawingContext as e, StoryDrawingHost as f, StoryParagraphFragmentContext as g };