superdoc 2.2.0 → 2.3.0

package/dist/layout-engine/layout-engine/src/layout-utils.d.ts

@@ -0,0 +1,104 @@
+import { Line, ParagraphBlock, ParagraphMeasure, LinePmRange } from '../../contracts/src/index.js';
+/**
+ * Tracks which paragraph spacing properties were explicitly set.
+ *
+ * Used to distinguish between explicit spacing values and those inherited
+ * from docDefaults/styles. This affects empty paragraph rendering because
+ * Word suppresses inherited spacing on empty paragraphs but honors explicit spacing.
+ */
+export type SpacingExplicit = {
+    /** Whether 'before' spacing was explicitly set */
+    before?: boolean;
+    /** Whether 'after' spacing was explicitly set */
+    after?: boolean;
+    /** Whether 'line' spacing was explicitly set */
+    line?: boolean;
+};
+/**
+ * Checks if a paragraph block is an empty text paragraph.
+ *
+ * An empty text paragraph is defined as:
+ * - No runs at all, OR
+ * - Exactly one text run with an empty string
+ *
+ * This is used to determine if special empty paragraph handling
+ * should apply (e.g., suppressing inherited spacing).
+ *
+ * @param block - The paragraph block to check
+ * @returns True if the paragraph is empty text
+ *
+ * @example
+ * ```typescript
+ * isEmptyTextParagraph({ kind: 'paragraph', runs: [] }); // true
+ * isEmptyTextParagraph({ kind: 'paragraph', runs: [{ text: '' }] }); // true
+ * isEmptyTextParagraph({ kind: 'paragraph', runs: [{ text: 'Hi' }] }); // false
+ * isEmptyTextParagraph({ kind: 'paragraph', runs: [{ kind: 'image', src: '...' }] }); // false
+ * ```
+ */
+export declare const isEmptyTextParagraph: (block: ParagraphBlock) => boolean;
+/**
+ * Determines if spacing should be suppressed for an empty paragraph.
+ *
+ * In Microsoft Word, empty paragraphs only show spacing if it was explicitly
+ * set on the paragraph. Spacing inherited from docDefaults or styles is
+ * suppressed for empty paragraphs.
+ *
+ * @param block - The paragraph block to check
+ * @param side - Which spacing side to check ('before' or 'after')
+ * @returns True if spacing should be suppressed (paragraph is empty and spacing is not explicit)
+ *
+ * @example
+ * ```typescript
+ * // Empty paragraph with inherited spacing - suppress
+ * shouldSuppressSpacingForEmpty(emptyBlock, 'before'); // true
+ *
+ * // Empty paragraph with explicit spacing - don't suppress
+ * shouldSuppressSpacingForEmpty(emptyBlockWithExplicit, 'before'); // false
+ *
+ * // Non-empty paragraph - don't suppress
+ * shouldSuppressSpacingForEmpty(nonEmptyBlock, 'before'); // false
+ * ```
+ */
+export declare const shouldSuppressSpacingForEmpty: (block: ParagraphBlock, side: "before" | "after") => boolean;
+export declare function normalizeLines(measure: ParagraphMeasure): ParagraphMeasure['lines'];
+export declare function sliceLines(lines: ParagraphMeasure['lines'], startIndex: number, availableHeight: number): {
+    toLine: number;
+    height: number;
+};
+export type { LinePmRange };
+export declare const computeFragmentPmRange: (block: ParagraphBlock, lines: ParagraphMeasure["lines"], fromLine: number, toLine: number) => LinePmRange;
+export declare const computeLinePmRange: (block: ParagraphBlock, line: Line) => LinePmRange;
+/**
+ * Per-paragraph contextual spacing (OOXML w:contextualSpacing).
+ *
+ * A paragraph suppresses its own before/after spacing when it has
+ * contextualSpacing enabled and the adjacent paragraph shares the same styleId.
+ * The adjacent paragraph's contextualSpacing flag is NOT consulted — each
+ * paragraph independently decides whether to suppress its own spacing.
+ *
+ * @see https://learn.microsoft.com/en-us/dotnet/api/documentformat.openxml.wordprocessing.contextualspacing
+ */
+export declare function shouldSuppressOwnSpacing(ownStyleId: string | undefined, ownContextualSpacing: boolean, adjacentStyleId: string | undefined): boolean;
+/** Pixels of spacing.before to add after collapsing against previous trailingSpacing. */
+export declare function collapseSpacingBefore(spacingBefore: number, trailingSpacing: number | undefined): number;
+/** OOXML contextual spacing: previous paragraph rewinds its after-gap from cursorY. */
+export declare function rewindPreviousParagraphTrailing(cursorY: number, trailingSpacing: number | undefined): number;
+/**
+ * Y coordinate where paragraph text begins (after spacing-before collapse).
+ * Does not advance pages — pagination stays in layout-paragraph PHASE 2.
+ */
+export declare function computeParagraphContentStartY(cursorY: number, spacingBefore: number, appliedSpacingBefore: boolean, trailingSpacing: number | undefined): number;
+/**
+ * Paragraph text start Y including contextual-spacing rewind from the previous paragraph.
+ * Used for float-scan preview at paragraph entry; PHASE 2 uses the same primitives inline.
+ */
+export declare function computeParagraphLayoutStartY(input: {
+    cursorY: number;
+    spacingBefore: number;
+    trailingSpacing?: number;
+    suppressSpacingBefore?: boolean;
+    rewindTrailingFromPrevious?: boolean;
+}): number;
+export declare const extractBlockPmRange: (block: {
+    attrs?: Record<string, unknown>;
+} | null | undefined) => LinePmRange;

package/dist/layout-engine/layout-engine/src/normalize-header-footer-fragments.d.ts

@@ -0,0 +1,45 @@
+import { FlowBlock, Fragment, Measure } from '../../contracts/src/index.js';
+/**
+ * Subset of HeaderFooterConstraints needed for fragment normalization.
+ * Defined locally to avoid circular imports with index.ts.
+ */
+export type RegionConstraints = {
+    width?: number;
+    pageWidth?: number;
+    pageHeight?: number;
+    margins?: {
+        left: number;
+        right: number;
+        top?: number;
+        bottom?: number;
+        header?: number;
+        footer?: number;
+    };
+};
+/**
+ * Post-normalize anchored fragment Y positions in header/footer layout.
+ *
+ * Problem: The inner `layoutDocument()` uses body content height as its page
+ * height. For page-relative footer anchors and margin-relative header anchors,
+ * this can produce incorrect Y positions because the real physical page/header
+ * band geometry is different.
+ *
+ * Solution: After layout, rewrite affected anchored fragments into the region's
+ * local coordinate system. Footer page-relative anchors use the real physical
+ * page height and footer-band origin. Header page-relative anchors use their
+ * physical page offset directly because header story coordinates are page-top
+ * local. Header margin-relative content anchors reset to the header-local
+ * offset so they do not inflate the reserved header height by carrying
+ * body-canvas coordinates.
+ *
+ * Page-anchored paragraph frames are likewise converted from physical-page
+ * coordinates; other paragraphs, inline images, and absolute overlays pass
+ * through unchanged.
+ */
+export declare function normalizeFragmentsForRegion(pages: Array<{
+    number: number;
+    fragments: Fragment[];
+}>, blocks: FlowBlock[], _measures: Measure[], kind: 'header' | 'footer', constraints: RegionConstraints): Array<{
+    number: number;
+    fragments: Fragment[];
+}>;

package/dist/layout-engine/layout-engine/src/pageNumbering.d.ts

@@ -0,0 +1,73 @@
+import { formatPageNumber, formatPageNumberFieldValue, formatSectionPageNumberText, FlowBlock, Layout, Page, PageNumberChapterSeparator, PageNumberFormat, SectionMetadata } from '../../contracts/src/index.js';
+export { formatPageNumber, formatPageNumberFieldValue, formatSectionPageNumberText };
+export type { PageNumberFormat };
+export interface ChapterPageInfo {
+    chapterNumberText?: string;
+    chapterStyle?: number;
+}
+/**
+ * Display page information for a single page in the document.
+ * Contains both the physical page number and the section-aware display number.
+ */
+export interface DisplayPageInfo {
+    /** Physical page number (1-indexed, continuous across the document) */
+    physicalPage: number;
+    /** Section-aware display page number (respects restart and offset) */
+    displayNumber: number;
+    /** Formatted display text (e.g., "III", "C", "23") */
+    displayText: string;
+    /** Index of the section this page belongs to */
+    sectionIndex: number;
+    /** Physical page count in the current section */
+    sectionPageCount: number;
+    /** Section PAGE number format before any run-local PAGE switch is applied. */
+    pageFormat?: PageNumberFormat;
+    /** MVP chapter prefix text derived from the nearest numbered Heading N marker. */
+    chapterNumberText?: string;
+    /** Separator between chapter prefix and page number component. */
+    chapterSeparator?: PageNumberChapterSeparator;
+}
+export declare function normalizeChapterMarkerText(markerText: unknown): string | undefined;
+export declare function buildChapterContextByPage(layout: Layout, blocks: FlowBlock[] | ReadonlyMap<string, FlowBlock>, sections: SectionMetadata[]): Map<number, ChapterPageInfo>;
+/**
+ * Computes section-aware display page numbers for all pages in a document.
+ *
+ * This function implements MS Word's section numbering behavior:
+ * - Each section can have its own page number format
+ * - Sections can restart numbering at a specific value
+ * - Continuous sections inherit the previous section's running count unless restart is set
+ * - Display numbers are calculated as: pageIndexWithinSection + offset (or restart value)
+ * - Display numbers are never less than 1
+ *
+ * Algorithm:
+ * 1. Map each page to its owning section
+ * 2. For each section:
+ *    - If restart/start is set, begin counting from that value
+ *    - Otherwise, continue from previous section's count
+ * 3. For each page within a section:
+ *    - Calculate displayIndex = pageIndexWithinSection + offset
+ *    - Clamp displayNumber = max(1, displayIndex)
+ *    - Format displayText using the section's number format
+ *
+ * @param pages - Array of pages from the layout (with page.number 1-indexed)
+ * @param sections - Array of section metadata (aligned by sectionIndex)
+ * @returns Array of display page information for each page
+ *
+ * @example
+ * ```typescript
+ * const pages = [
+ *   { number: 1, ... },
+ *   { number: 2, ... },
+ *   { number: 3, ... },
+ * ];
+ * const sections = [
+ *   { sectionIndex: 0, numbering: { format: 'lowerRoman', start: 1 } },
+ *   { sectionIndex: 1, numbering: { format: 'decimal', start: 1 } },
+ * ];
+ * const displayInfo = computeDisplayPageNumber(pages, sections);
+ * // displayInfo[0]: { physicalPage: 1, displayNumber: 1, displayText: "i", sectionIndex: 0 }
+ * // displayInfo[1]: { physicalPage: 2, displayNumber: 2, displayText: "ii", sectionIndex: 0 }
+ * // displayInfo[2]: { physicalPage: 3, displayNumber: 1, displayText: "1", sectionIndex: 1 }
+ * ```
+ */
+export declare function computeDisplayPageNumber(pages: Page[], sections: SectionMetadata[], chapterInfoByPage?: ReadonlyMap<number, ChapterPageInfo>): DisplayPageInfo[];

package/dist/layout-engine/layout-engine/src/paginator.d.ts

@@ -0,0 +1,131 @@
+import { ColumnLayout, Page, PageMargins } from '../../contracts/src/index.js';
+export type ConstraintBoundary = {
+    y: number;
+    columns: ColumnLayout;
+};
+export type PageState = {
+    page: Page;
+    cursorY: number;
+    columnIndex: number;
+    topMargin: number;
+    contentBottom: number;
+    constraintBoundaries: ConstraintBoundary[];
+    activeConstraintIndex: number;
+    trailingSpacing: number;
+    lastParagraphStyleId?: string;
+    lastParagraphContextualSpacing: boolean;
+    /** Border hash of the last paragraph for between-border group detection. */
+    lastParagraphBorderHash?: string;
+    /** Tracks the maximum cursorY reached across all columns on this page.
+     *  Used when starting a mid-page region so the new section begins below
+     *  all column content, not just the current column's cursor. */
+    maxCursorY: number;
+    /**
+     * SD-3049: Page-level footnote reserve already baked into `contentBottom`
+     * via `getActiveBottomMargin`. The block-aware break decision compares
+     * `footnoteDemandThisPage` against this; only the excess shrinks the body.
+     */
+    pageFootnoteReserve: number;
+    /**
+     * SD-3049: Accumulated measured body height of footnote refs anchored on
+     * fragments already committed to this page (and column-wide). Used by the
+     * paragraph break decision so the body packs tight to footnote demand
+     * instead of relying solely on the post-hoc page-level reserve.
+     */
+    footnoteDemandThisPage: number;
+    /**
+     * SD-2656: Number of distinct footnote refs anchored on this page so far.
+     * Drives the slicer's band-overhead computation (separator + per-extra-ref
+     * gap + safety margin), which must match the planner's reserve formula.
+     */
+    footnoteRefsThisPage: number;
+    /**
+     * SD-2656: ordered list of footnote anchors committed to this page (by
+     * document/PM order). The body slicer pushes a new entry when it accepts a
+     * candidate line that introduces a new anchor. The list drives the ordered-
+     * cluster demand formula:
+     *   demand = sum(fullHeight of cluster[0..N-1]) + firstLineHeight(cluster[N-1])
+     * i.e. all anchors except the last must fit fully; only the last may split.
+     * Identified by refId so callers can dedupe and walk in document order.
+     */
+    footnoteAnchorsThisPage: Array<{
+        pmPos: number;
+        refId: string;
+        fullHeight: number;
+        firstLineHeight: number;
+    }>;
+};
+export type PaginatorOptions = {
+    margins: {
+        left: number;
+        right: number;
+    };
+    getActiveTopMargin(): number;
+    getActiveBottomMargin(): number;
+    getActiveHeaderDistance(): number;
+    getActiveFooterDistance(): number;
+    getActivePageSize(): {
+        w: number;
+        h: number;
+    };
+    getDefaultPageSize(): {
+        w: number;
+        h: number;
+    };
+    getActiveColumns(): ColumnLayout;
+    /** Exact first-page state from an engine-authored paragraph checkpoint. */
+    initialPageState?: {
+        prefixFragments: readonly Page['fragments'][number][];
+        cursorY: number;
+        maxCursorY: number;
+        columnIndex: number;
+        trailingSpacing: number;
+        lastParagraphStyleId?: string;
+        lastParagraphContextualSpacing: boolean;
+        lastParagraphBorderHash?: string;
+        constraintBoundaries: readonly ConstraintBoundary[];
+        activeConstraintIndex: number;
+        footnoteDemandThisPage: number;
+        footnoteRefsThisPage: number;
+        footnoteAnchorsThisPage: readonly PageState['footnoteAnchorsThisPage'][number][];
+    };
+    pageNumberOffset?: number;
+    createPage(number: number, pageMargins: PageMargins, pageSizeOverride?: {
+        w: number;
+        h: number;
+    }): Page;
+    onNewPage?: (state: PageState) => void;
+    shouldStopBeforeNewPage?: (input: {
+        completedPageIndex: number;
+        pages: readonly Page[];
+        states: readonly PageState[];
+    }) => boolean;
+    /**
+     * SD-3049: per-page footnote reserve (the value already added to
+     * `getActiveBottomMargin`). Returned by index for the page about to be
+     * created. Defaults to 0 when not provided.
+     */
+    getFootnoteReserveForPage?: (pageIndex: number) => number;
+};
+export declare class PaginationEarlyStop extends Error {
+    constructor();
+}
+export declare function isPaginationEarlyStop(error: unknown): error is PaginationEarlyStop;
+/**
+ * Break paragraph-only spacing and border adjacency at an in-flow block boundary.
+ *
+ * Paragraph layout has already included `trailingSpacing` in `cursorY`, so this
+ * intentionally does not move the cursor. It only prevents a later paragraph
+ * from collapsing spacing or borders through an intervening block.
+ */
+export declare function breakParagraphAdjacency(state: PageState): void;
+export declare function createPaginator(opts: PaginatorOptions): {
+    readonly pages: Page[];
+    readonly states: PageState[];
+    readonly startNewPage: () => PageState;
+    readonly ensurePage: () => PageState;
+    readonly advanceColumn: (state: PageState) => PageState;
+    readonly getActiveColumnsForState: (state: PageState) => ColumnLayout;
+    readonly getPageByNumber: (pageNumber: number) => PageState;
+    readonly pruneTrailingEmptyPages: () => void;
+};

package/dist/layout-engine/layout-engine/src/paragraph-layout-eligibility.d.ts

@@ -0,0 +1 @@
+export { isReviewableSectionBoundaryMarkerBlock, shouldSkipParagraphDuringLayout } from '../../contracts/src/index.js';

package/dist/layout-engine/layout-engine/src/resolvePageRefs.d.ts

@@ -0,0 +1,31 @@
+import { Layout, FlowBlock, ParagraphBlock } from '../../contracts/src/index.js';
+/**
+ * Build an anchor map from bookmarks and layout fragments.
+ *
+ * For each bookmark, determines which page it appears on by checking
+ * if the bookmark's PM position falls within any fragment's PM range.
+ *
+ * @param bookmarks - Map of bookmark names to PM positions
+ * @param layout - Completed layout with positioned fragments
+ * @returns Map of bookmark names to page numbers (1-indexed)
+ */
+export declare function buildAnchorMap(bookmarks: Map<string, number>, layout: Layout): Map<string, number>;
+/**
+ * Resolve pageReference tokens in blocks using the anchor map.
+ *
+ * Finds all runs with token='pageReference', looks up the target bookmark
+ * in the anchor map, and replaces the run's text with the resolved page number.
+ *
+ * @param blocks - FlowBlocks containing runs with pageReference tokens
+ * @param anchorMap - Map of bookmark names to page numbers
+ * @returns Array of block IDs that had tokens resolved (for re-measurement)
+ */
+export declare function resolvePageRefTokens(blocks: FlowBlock[], anchorMap: Map<string, number>): Set<string>;
+/**
+ * Filter blocks to only include TOC entries that need re-measurement.
+ *
+ * @param blocks - All FlowBlocks
+ * @param affectedBlockIds - Set of block IDs that had tokens resolved
+ * @returns Array of ParagraphBlocks that are TOC entries and were affected
+ */
+export declare function getTocBlocksForRemeasurement(blocks: FlowBlock[], affectedBlockIds: Set<string>): ParagraphBlock[];

package/dist/layout-engine/layout-engine/src/resolvePageTokens.d.ts

@@ -0,0 +1,82 @@
+import { Layout, FlowBlock, ParagraphBlock, Measure } from '../../contracts/src/index.js';
+import { DisplayPageInfo } from './pageNumbering.js';
+/**
+ * Numbering context for page token resolution.
+ * Contains display page information for each physical page in the document.
+ */
+export interface NumberingContext {
+    /** Total number of pages in the document */
+    totalPages: number;
+    /** Display page information for each page (indexed by physical page number - 1) */
+    displayPages: DisplayPageInfo[];
+}
+/**
+ * Result of page number token resolution.
+ * Contains affected block IDs and their updated clones.
+ */
+export interface ResolvePageTokensResult {
+    /** Set of block IDs that had tokens resolved */
+    affectedBlockIds: Set<string>;
+    /** Map of block ID to updated block clone (only for affected blocks) */
+    updatedBlocks: Map<string, FlowBlock>;
+}
+/**
+ * Resolves page number and total page count tokens in document blocks using layout and numbering context.
+ *
+ * This function walks through all pages and fragments in the layout, finding blocks with
+ * page number tokens. For each affected block, it creates a clone with resolved token text,
+ * using section-aware display page numbers from the numbering context.
+ *
+ * The function does NOT mutate original blocks - it returns clones of affected blocks.
+ * This ensures thread-safety and allows for clean rollback if re-measurement fails.
+ *
+ * @param layout - Completed layout with page-numbered fragments
+ * @param blocks - Original FlowBlocks array (will not be mutated)
+ * @param measures - Measure array (parallel to blocks, used to detect hasPageTokens flag)
+ * @param numberingCtx - Numbering context with display page info and total pages
+ * @returns Result containing affected block IDs and updated block clones
+ *
+ * @example
+ * ```typescript
+ * const layout = layoutDocument(blocks, measures, options);
+ * const numberingCtx = buildNumberingContext(layout, sections);
+ * const result = resolvePageNumberTokens(layout, blocks, measures, numberingCtx);
+ *
+ * if (result.affectedBlockIds.size > 0) {
+ *   // Re-measure affected blocks and re-run pagination
+ *   const updatedBlocks = blocks.map(b => result.updatedBlocks.get(b.id) ?? b);
+ *   // ... remeasure and re-layout ...
+ * }
+ * ```
+ */
+export interface ResolvePageTokensOptions {
+    /**
+     * When `false`, `totalPageCount` / `sectionPageCount` tokens keep their
+     * source-cached DOCX result text (em dash when absent) instead of resolving
+     * to the current — possibly partial — page totals. `pageNumber` always
+     * resolves. Defaults to `true` (exact totals).
+     */
+    pageCountFieldsExact?: boolean;
+}
+export declare function resolvePageNumberTokens(layout: Layout, blocks: FlowBlock[], measures: Measure[], numberingCtx: NumberingContext, options?: ResolvePageTokensOptions): ResolvePageTokensResult;
+/**
+ * Resolves page number tokens in paragraph blocks.
+ *
+ * This is a helper function that processes a single paragraph block's runs,
+ * resolving any pageNumber or totalPageCount tokens. It's designed to be called
+ * from the layout pipeline where both the layout and blocks are available.
+ *
+ * @param block - Paragraph block to process
+ * @param pageNumber - Current page number (1-indexed)
+ * @param totalPages - Total number of pages in the document
+ * @returns True if any tokens were resolved in this block
+ *
+ * @example
+ * ```typescript
+ * const wasModified = resolveTokensInBlock(paragraphBlock, 3, 10);
+ * if (wasModified) {
+ *   // Block was modified, may need re-measurement
+ * }
+ * ```
+ */
+export declare function resolveTokensInBlock(block: ParagraphBlock, pageNumber: number, totalPages: number): boolean;

package/dist/layout-engine/layout-engine/src/section-breaks.d.ts

@@ -0,0 +1,98 @@
+import { ColumnLayout, SectionBreakBlock } from '../../contracts/src/index.js';
+export type SectionState = {
+    activeTopMargin: number;
+    activeBottomMargin: number;
+    activeLeftMargin: number;
+    activeRightMargin: number;
+    pendingTopMargin: number | null;
+    pendingBottomMargin: number | null;
+    pendingLeftMargin: number | null;
+    pendingRightMargin: number | null;
+    activeHeaderDistance: number;
+    activeFooterDistance: number;
+    pendingHeaderDistance: number | null;
+    pendingFooterDistance: number | null;
+    activePageSize: {
+        w: number;
+        h: number;
+    };
+    pendingPageSize: {
+        w: number;
+        h: number;
+    } | null;
+    activeColumns: ColumnLayout;
+    pendingColumns: ColumnLayout | null;
+    activeOrientation: 'portrait' | 'landscape' | null;
+    pendingOrientation: 'portrait' | 'landscape' | null;
+    hasAnyPages: boolean;
+};
+export type BreakDecision = {
+    forcePageBreak: boolean;
+    forceMidPageRegion: boolean;
+    requiredParity?: 'even' | 'odd';
+};
+/** Default single-column configuration per OOXML spec (absence of w:cols element) */
+export declare const SINGLE_COLUMN_DEFAULT: Readonly<ColumnLayout>;
+export declare function isInitialSectionBreak(block: SectionBreakBlock, hasAnyPages: boolean): boolean;
+/**
+ * Schedule section break effects by updating pending/active state and returning a break decision.
+ *
+ * This function analyzes a section break block to determine what layout changes should occur
+ * (e.g., page break, column changes) and schedules the new section properties (margins, page size,
+ * columns) to be applied at the appropriate boundary. It is pure with respect to inputs/outputs
+ * and does not mutate external variables.
+ *
+ * The function handles special cases like the first section (applied immediately to active state)
+ * and accounts for header content height to prevent header/body overlap.
+ *
+ * Column handling follows OOXML spec: absence of <w:cols> element means single column layout.
+ * When a section break has no columns defined, it resets to single column (not inherited from previous).
+ *
+ * @param block - The section break block with margin/page/column settings
+ * @param state - Current section state containing active and pending layout properties
+ * @param baseMargins - Base document margins in pixels (top, bottom, left, right)
+ * @param maxHeaderContentHeight - Maximum header content height in pixels across all header variants.
+ *        When provided (> 0), ensures body content starts below header content by adjusting top margin
+ *        to be at least headerDistance + maxHeaderContentHeight. Defaults to 0 (no header overlap prevention).
+ * @param maxFooterContentHeight - Maximum footer content height in pixels across all footer variants.
+ *        When provided (> 0), ensures body content ends above footer content by adjusting bottom margin
+ *        to be at least footerDistance + maxFooterContentHeight. Defaults to 0 (no footer overlap prevention).
+ * @returns Object containing:
+ *   - decision: Break decision with flags for page breaks, mid-page regions, and parity requirements
+ *   - state: Updated section state with scheduled pending properties
+ * @example
+ * ```typescript
+ * // Schedule a next-page section break with new margins
+ * const { decision, state: newState } = scheduleSectionBreak(
+ *   {
+ *     kind: 'sectionBreak',
+ *     type: 'nextPage',
+ *     margins: { top: 72, bottom: 72, header: 36, footer: 36 },
+ *     columns: { count: 2, gap: 24 }
+ *   },
+ *   currentState,
+ *   { top: 72, bottom: 72, left: 72, right: 72 },
+ *   48 // header content height
+ * );
+ * // decision.forcePageBreak === true
+ * // newState.pendingTopMargin === Math.max(72, 36 + 48) = 84
+ * ```
+ */
+export declare function scheduleSectionBreak(block: SectionBreakBlock, state: SectionState, baseMargins: {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}, maxHeaderContentHeight?: number, maxFooterContentHeight?: number): {
+    decision: BreakDecision;
+    state: SectionState;
+};
+/**
+ * Apply pending section state to active state at a page boundary.
+ * Transfers all pending values (margins, page size, columns, orientation) to their
+ * active counterparts and clears the pending values.
+ *
+ * @param state - Current section state with pending values to apply
+ * @returns New section state with pending values applied to active and pending cleared
+ */
+export declare function applyPendingToActive(state: SectionState): SectionState;

package/dist/layout-engine/layout-engine/src/section-props.d.ts

@@ -0,0 +1,65 @@
+import { ColumnLayout, FlowBlock, SectionVerticalAlign } from '../../contracts/src/index.js';
+/**
+ * Section-level formatting properties that control page layout.
+ *
+ * Used to apply Word-style section breaks with custom page dimensions,
+ * margins, columns, and orientation. Each section can have independent
+ * formatting, enabling mixed layouts within a single document.
+ *
+ * @property margins - Page margin distances from page edges (in pixels)
+ * @property pageSize - Page dimensions in pixels (width and height)
+ * @property columns - Multi-column layout configuration
+ * @property orientation - Page orientation (portrait or landscape)
+ * @property vAlign - Vertical alignment of content within the section's pages
+ */
+export type SectionProps = {
+    margins?: {
+        header?: number;
+        footer?: number;
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    pageSize?: {
+        w: number;
+        h: number;
+    };
+    columns?: ColumnLayout;
+    orientation?: 'portrait' | 'landscape';
+    vAlign?: SectionVerticalAlign;
+};
+/**
+ * Pre-scans sectionBreak blocks to map each DOCX-derived boundary to the next section's properties.
+ *
+ * Word uses "end-tagged" sectPr semantics: the properties that apply to a section are stored
+ * at the END of that section (on the following sectPr node). This function walks backwards
+ * through the block list to build a lookahead map that tells the layout engine which properties
+ * to use when starting a new page after each section break.
+ *
+ * Special cases:
+ * - The first section (`isFirstSection=true`) keeps its own properties (no lookahead)
+ * - Non-DOCX section breaks (`attrs.source !== 'sectPr'`) are ignored
+ * - The final section break falls back to its own properties when there's no following sectPr
+ *
+ * Guard for PM-adapter blocks with sectionIndex:
+ * The layout engine only applies this lookahead when a sectionBreak lacks `attrs.sectionIndex`.
+ * PM-adapter blocks that have a sectionIndex already embed the upcoming section's metadata
+ * directly on the block, so they don't need the map-based lookahead. This prevents double-
+ * application and ensures the map is only used for synthetic test fixtures or legacy structures.
+ *
+ * @param blocks - Array of FlowBlocks to scan for section breaks
+ * @returns Map from block index to the section properties that should apply AFTER that break
+ *
+ * @example
+ * ```typescript
+ * import { computeNextSectionPropsAtBreak } from './section-props.js';
+ *
+ * const map = computeNextSectionPropsAtBreak(blocks);
+ * const propsForNextPage = map.get(sectionBreakIndex);
+ * if (propsForNextPage) {
+ *   // Apply these properties when starting the page after this break
+ * }
+ * ```
+ */
+export declare function computeNextSectionPropsAtBreak(blocks: FlowBlock[]): Map<number, SectionProps>;