superdoc 2.2.1 → 2.3.0

package/dist/layout-engine/layout-bridge/src/track-changes-handler.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Track Changes Handler
+ *
+ * Handles cursor positioning and visual position calculations when track changes
+ * are enabled, accounting for deleted text that affects visual layout.
+ *
+ * Strategy:
+ * 1. Extract track change spans from document
+ * 2. Calculate visual positions ignoring deleted text
+ * 3. Provide cursor offset adjustments
+ * 4. Support both insertion and deletion tracking
+ *
+ * @module track-changes-handler
+ */
+/**
+ * Minimal ProseMirror Node interface for track changes extraction.
+ * This is a subset of the actual ProseMirror Node type.
+ */
+interface PMNode {
+    nodeSize: number;
+    marks?: Array<{
+        type: {
+            name: string;
+        };
+        attrs?: Record<string, unknown>;
+    }>;
+    descendants?: (callback: (node: PMNode, pos: number) => boolean | void) => void;
+}
+/**
+ * A span of tracked changes in the document.
+ */
+export interface TrackChangeSpan {
+    /** PM start position */
+    pmStart: number;
+    /** PM end position */
+    pmEnd: number;
+    /** Type of change */
+    type: 'insertion' | 'deletion';
+    /** Author of the change */
+    author: string;
+}
+/**
+ * TrackChangesHandler provides cursor positioning utilities for documents
+ * with track changes enabled.
+ */
+export declare class TrackChangesHandler {
+    /**
+     * Extract track change spans from ProseMirror document state.
+     *
+     * @param doc - ProseMirror document node
+     * @returns Array of track change spans
+     */
+    extractSpans(doc: PMNode): TrackChangeSpan[];
+    /**
+     * Calculate visual position ignoring deleted text.
+     * Deleted text doesn't contribute to visual position when rendered.
+     *
+     * @param pmPos - ProseMirror position
+     * @param spans - Track change spans
+     * @returns Visual position (accounting for hidden deletions)
+     */
+    getVisualPosition(pmPos: number, spans: TrackChangeSpan[]): number;
+    /**
+     * Get cursor offset adjustment for track changes.
+     * Returns how many positions to adjust cursor due to deleted text.
+     *
+     * @param pmPos - ProseMirror position
+     * @param spans - Track change spans
+     * @returns Offset adjustment (negative for positions after deletions)
+     */
+    getCursorAdjustment(pmPos: number, spans: TrackChangeSpan[]): number;
+    /**
+     * Check if a position is within a deletion.
+     *
+     * @param pmPos - ProseMirror position
+     * @param spans - Track change spans
+     * @returns True if position is inside deleted text
+     */
+    isInDeletion(pmPos: number, spans: TrackChangeSpan[]): boolean;
+    /**
+     * Get all deletions affecting a range.
+     *
+     * @param startPos - Range start position
+     * @param endPos - Range end position
+     * @param spans - Track change spans
+     * @returns Array of deletion spans that intersect the range
+     */
+    getDeletionsInRange(startPos: number, endPos: number, spans: TrackChangeSpan[]): TrackChangeSpan[];
+}
+export {};

package/dist/layout-engine/layout-bridge/src/tracked-changes-utils.d.ts

@@ -0,0 +1,41 @@
+import { Run, TrackedChangeMeta, TextRun, ParagraphBlock } from '../../contracts/src/index.js';
+/**
+ * Type guard to check if a run has tracked change metadata.
+ *
+ * This utility provides a type-safe way to narrow a generic Run to a TextRun
+ * with tracked change metadata, enabling proper type inference in consuming code.
+ *
+ * @param run - The run to check for tracked change metadata
+ * @returns True if the run has tracked change metadata, with type narrowing
+ *
+ * @example
+ * ```typescript
+ * if (hasTrackedChange(run)) {
+ *   // TypeScript now knows run.trackedChange exists
+ *   console.log(run.trackedChange.kind);
+ * }
+ * ```
+ */
+export declare const hasTrackedChange: (run: Run) => run is TextRun & {
+    trackedChange: TrackedChangeMeta;
+};
+/**
+ * Resolves whether tracked changes are enabled for a paragraph block.
+ *
+ * Provides consistent handling of undefined/false/true states across the codebase.
+ * When the `trackedChangesEnabled` attribute is not present or undefined, the
+ * function returns the provided default value.
+ *
+ * @param attrs - The paragraph block attributes to check
+ * @param defaultEnabled - Default value when attribute is not present (default: true)
+ * @returns True if tracked changes are enabled for this block
+ *
+ * @example
+ * ```typescript
+ * const enabled = resolveTrackedChangesEnabled(block.attrs);
+ * if (enabled) {
+ *   // Process tracked changes for this block
+ * }
+ * ```
+ */
+export declare const resolveTrackedChangesEnabled: (attrs: ParagraphBlock["attrs"] | undefined, defaultEnabled?: boolean) => boolean;

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

@@ -0,0 +1,52 @@
+import { FlowBlock, ImageBlock, ImageMeasure, Measure, DrawingBlock, DrawingMeasure, TableBlock, TableMeasure, isPageRelativeAnchor } from '../../contracts/src/index.js';
+import { resolveFloatingTableAnchorResolution } from './floating-table-anchor.js';
+export type { FloatingTableAnchorResolution } from './floating-table-anchor.js';
+export { resolveFloatingTableAnchorResolution };
+export { isPageRelativeAnchor };
+/**
+ * Represents an anchored image or drawing block with its measurements.
+ * Used to bundle block and measure data for anchor processing.
+ */
+export type AnchoredDrawing = {
+    block: ImageBlock | DrawingBlock;
+    measure: ImageMeasure | DrawingMeasure;
+};
+export type AnchoredDrawingCollection = {
+    byParagraph: Map<number, AnchoredDrawing[]>;
+    withoutParagraph: AnchoredDrawing[];
+    readonly size: number;
+    has(index: number): boolean;
+    get(index: number): AnchoredDrawing[] | undefined;
+};
+export type AnchoredTable = {
+    block: TableBlock;
+    measure: TableMeasure;
+    /** Raw w:tblpY offset from the resolved anchor paragraph. */
+    layoutOffsetV?: number;
+    /** True when raw w:tblpY is line-scoped on the anchor paragraph (Word centers tall form fields). */
+    lineScopedOnAnchor?: boolean;
+};
+export type AnchoredObject = AnchoredDrawing | AnchoredTable;
+export type AnchoredTableCollection = {
+    byParagraph: Map<number, AnchoredTable[]>;
+    withoutParagraph: AnchoredTable[];
+};
+/**
+ * Collect anchored images that should be pre-registered before the layout loop.
+ * These are images with vRelativeFrom='margin' or 'page' that affect all paragraphs.
+ *
+ * @param blocks - Array of flow blocks to scan for anchored images
+ * @param measures - Corresponding measures for each block
+ * @returns Array of anchored drawings that should be pre-registered
+ */
+export declare function collectPreRegisteredAnchors(blocks: FlowBlock[], measures: Measure[]): AnchoredDrawing[];
+/**
+ * Collect anchored drawings (images/drawings) mapped to their anchor paragraph index.
+ * Map of paragraph block index -> anchored images/drawings associated with that paragraph.
+ */
+export declare function collectAnchoredDrawings(blocks: FlowBlock[], measures: Measure[]): AnchoredDrawingCollection;
+/**
+ * Collect anchored/floating tables mapped to their anchor paragraph index.
+ * Also returns anchored tables that have no paragraph to attach to.
+ */
+export declare function collectAnchoredTables(blocks: FlowBlock[], measures: Measure[]): AnchoredTableCollection;

package/dist/layout-engine/layout-engine/src/column-balancing.d.ts

@@ -0,0 +1,255 @@
+/**
+ * Column Balancing Module
+ *
+ * Implements Word-compatible column balancing for section boundaries.
+ * Column balancing distributes content evenly across columns at section end,
+ * matching Microsoft Word's behavior.
+ */
+/**
+ * Configuration for column balancing behavior.
+ */
+export interface ColumnBalancingConfig {
+    /** Whether column balancing is enabled */
+    enabled: boolean;
+    /** Acceptable height difference between columns in pixels */
+    tolerance: number;
+    /** Maximum iterations to prevent infinite loops */
+    maxIterations: number;
+    /** Minimum content height per column in pixels */
+    minColumnHeight: number;
+}
+/**
+ * Default configuration for column balancing.
+ * These values are tuned to match Word's behavior.
+ */
+export declare const DEFAULT_BALANCING_CONFIG: ColumnBalancingConfig;
+/**
+ * Context for a column balancing operation.
+ * Contains all information needed to calculate balanced layout.
+ */
+export interface BalancingContext {
+    /** Number of columns to balance across */
+    columnCount: number;
+    /** Width of each column in pixels */
+    columnWidth: number;
+    /** Gap between columns in pixels */
+    columnGap: number;
+    /** Available height from current position to content bottom */
+    availableHeight: number;
+    /** Content blocks to distribute across columns */
+    contentBlocks: BalancingBlock[];
+}
+/**
+ * A content block for balancing calculations.
+ * Contains height and constraint information.
+ */
+export interface BalancingBlock {
+    /** Unique identifier for the block */
+    blockId: string;
+    /** Measured height of the block in pixels */
+    measuredHeight: number;
+    /** Whether this block can be split across columns */
+    canBreak: boolean;
+    /** Whether this block must stay with the next block */
+    keepWithNext: boolean;
+    /** Whether this block must stay together (not split) */
+    keepTogether: boolean;
+    /** Minimum lines at start of column (orphan control) */
+    orphanLines?: number;
+    /** Minimum lines at end of column (widow control) */
+    widowLines?: number;
+    /** Individual line heights for paragraph blocks (for line-level breaking) */
+    lineHeights?: number[];
+}
+/**
+ * Result of a column balancing calculation.
+ */
+export interface BalancingResult {
+    /** Target height for each column */
+    targetColumnHeight: number;
+    /** Map of block ID to assigned column index */
+    columnAssignments: Map<string, number>;
+    /** Whether balancing converged successfully */
+    success: boolean;
+    /** Number of iterations used */
+    iterations: number;
+    /** Optional break points within blocks (for paragraph splitting) */
+    blockBreakPoints?: Map<string, BlockBreakPoint>;
+}
+/**
+ * Break point information for splitting a block across columns.
+ */
+export interface BlockBreakPoint {
+    /** Block ID this break point applies to */
+    blockId: string;
+    /** Line index after which to break (for paragraphs) */
+    breakAfterLine: number;
+    /** Height of content before the break */
+    heightBeforeBreak: number;
+    /** Height of content after the break */
+    heightAfterBreak: number;
+}
+/**
+ * Calculate optimal column height for balanced layout.
+ *
+ * Algorithm:
+ * 1. Sum total content height
+ * 2. Calculate initial target = total / columnCount
+ * 3. Simulate layout with target height
+ * 4. Adjust if columns overflow/underflow
+ * 5. Iterate until balanced or max iterations reached
+ *
+ * @param ctx - Balancing context with column config and content blocks
+ * @param config - Balancing configuration
+ * @returns Balancing result with column assignments
+ */
+export declare function calculateBalancedColumnHeight(ctx: BalancingContext, config?: ColumnBalancingConfig): BalancingResult;
+/**
+ * Check if column balancing should be triggered for a section.
+ *
+ * Balancing is triggered when:
+ * 1. Section type is 'continuous' (mid-page section break)
+ * 2. Section has explicit balanceColumns flag set to true
+ * 3. This is the last section in the document (end of document)
+ *
+ * @param sectionType - Type of section break
+ * @param balanceColumns - Explicit balance flag from section properties
+ * @param isLastSection - Whether this is the document's final section
+ * @returns Whether column balancing should be performed
+ */
+export declare function shouldBalanceColumns(sectionType: 'continuous' | 'nextPage' | 'evenPage' | 'oddPage' | undefined, balanceColumns: boolean | undefined, isLastSection: boolean): boolean;
+/**
+ * Determine if content should skip balancing (optimization).
+ *
+ * Skip balancing when:
+ * 1. Balancing is disabled
+ * 2. Single column (nothing to balance across)
+ * 3. No content blocks
+ * 4. Single unbreakable block that can't be split
+ * 5. Total content fits in a single column (no overflow = no need to balance)
+ * 6. Total content is less than minimum column height
+ *
+ * Word only balances columns when content would overflow a single column.
+ * If all content fits comfortably in column 0, there's no redistribution.
+ *
+ * @param ctx - Balancing context
+ * @param config - Balancing configuration
+ * @returns Whether to skip balancing
+ */
+export declare function shouldSkipBalancing(ctx: BalancingContext, config?: ColumnBalancingConfig): boolean;
+/**
+ * Fragment with required properties for column balancing.
+ * Represents a positioned content block that can be redistributed across columns.
+ */
+export interface BalancingFragment {
+    /** Horizontal position in pixels from left edge of page */
+    x: number;
+    /** Vertical position in pixels from top edge of page */
+    y: number;
+    /** Width of the fragment in pixels (updated during balancing to match column width) */
+    width: number;
+    /** Type of content: 'para', 'image', 'drawing', 'table', etc. */
+    kind: string;
+    /** Unique identifier linking fragment to its source block */
+    blockId: string;
+    /** Starting line index for partial paragraph fragments */
+    fromLine?: number;
+    /** Ending line index (exclusive) for partial paragraph fragments */
+    toLine?: number;
+    /**
+     * Remeasured lines carried by the fragment itself (set when a paragraph measured at one
+     * width is placed in a narrower column or beside a float). When present, the resolve
+     * stage renders THIS array and ignores fromLine/toLine into measure.lines - so balancing
+     * must source heights from it and slice it when splitting a fragment across columns.
+     */
+    lines?: Array<{
+        lineHeight: number;
+    }>;
+    /** Pre-computed height for non-paragraph fragments */
+    height?: number;
+}
+/**
+ * Measure data used to calculate fragment heights.
+ * Contains layout measurements from the measuring phase.
+ */
+export interface MeasureData {
+    /** Type of measure: 'paragraph', 'image', etc. */
+    kind: string;
+    /** Line measurements for paragraph content */
+    lines?: Array<{
+        lineHeight: number;
+    }>;
+    /** Total height for non-paragraph content (image, drawing) */
+    height?: number;
+    /** Total height for table content (TableMeasure stores this rather than `height`). */
+    totalHeight?: number;
+}
+/**
+ * Column layout properties relevant to balancing decisions.
+ * Mirrors the subset of ColumnLayout that this module reads.
+ */
+export interface SectionColumnLayout {
+    count: number;
+    gap: number;
+    width?: number;
+    widths?: number[];
+    /**
+     * Per-column gaps (px), length count-1; explicit mode only. Drives geometry so equal-width
+     * sections with non-uniform gaps (e.g. F9) balance with correct column positions. (SD-2629)
+     */
+    gaps?: number[];
+    equalWidth?: boolean;
+}
+export interface BalanceSectionOnPageArgs {
+    /** All fragments on the target page. Only those belonging to sectionIndex are balanced (mutated in place). */
+    fragments: BalancingFragment[];
+    /** Section whose content ends on this page. */
+    sectionIndex: number;
+    /** Column layout of the ending section. */
+    sectionColumns: SectionColumnLayout;
+    /** True if the section contains an explicit <w:br w:type="column"/> — skip balancing to preserve author intent. */
+    sectionHasExplicitColumnBreak: boolean;
+    /** blockId -> sectionIndex map (built once per layout, shared across calls). */
+    blockSectionMap: Map<string, number>;
+    /** Left page margin, used to compute column X positions. */
+    margins: {
+        left: number;
+    };
+    /** Y position where the section's region begins on this page. */
+    topMargin: number;
+    /** Column width — passed to balancePageColumns so it can resize fragments. */
+    columnWidth: number;
+    /** Available height from topMargin to content bottom. */
+    availableHeight: number;
+    /** Measurement data for fragments (built from measures array). */
+    measureMap: Map<string, MeasureData>;
+    /**
+     * Block IDs of paragraphs that exist only to carry `<w:sectPr>` properties.
+     * These contribute zero height to balanced columns — see `getBalancingHeight`.
+     * Optional; when omitted no fragment is treated as a marker.
+     */
+    sectPrMarkerBlockIds?: Set<string>;
+    /**
+     * Block IDs of paragraphs with `w:keepLines` — the author asked Word not to
+     * split these, so they stay atomic during balancing. Optional; when omitted
+     * every multi-line paragraph is splittable. (SD-3359)
+     */
+    keepLinesBlockIds?: Set<string>;
+}
+/**
+ * Balance the fragments of one section on one page.
+ *
+ * Returns the tallest balanced column's bottom Y, or null if balancing was skipped.
+ * Callers can use the returned Y to update paginator cursors so subsequent content
+ * starts just below the balanced section rather than below an unbalanced maxCursorY.
+ *
+ * Guards (skip balancing when):
+ *   - Section has <= 1 column (nothing to balance)
+ *   - Section contains an explicit column break (author intent wins)
+ *   - Section uses GENUINELY-unequal column widths (Word fills these column-by-column;
+ *     explicit widths that are all equal still balance — SD-2324)
+ *   - No fragments on this page belong to the section
+ */
+export declare function balanceSectionOnPage(args: BalanceSectionOnPageArgs): {
+    maxY: number;
+} | null;

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

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

package/dist/layout-engine/layout-engine/src/floating-objects.d.ts

@@ -0,0 +1,60 @@
+import { ImageBlock, ImageMeasure, ExclusionZone, DrawingBlock, DrawingMeasure, TableBlock, TableMeasure, ColumnLayoutForAnchor } from '../../contracts/src/index.js';
+type FloatBlock = ImageBlock | DrawingBlock;
+type FloatMeasure = ImageMeasure | DrawingMeasure;
+export type FloatingObjectManager = {
+    /**
+     * Register an anchored drawing as an exclusion zone.
+     * Should be called before laying out paragraphs.
+     *
+     * @param resolvedAnchorY — Fully resolved paint Y from {@link resolveAnchoredGraphicY}
+     *   (already includes `offsetV`). Must not add vertical offset again.
+     */
+    registerDrawing(drawingBlock: FloatBlock, measure: FloatMeasure, resolvedAnchorY: number, columnIndex: number, pageNumber: number): void;
+    /**
+     * Register an anchored/floating table as an exclusion zone.
+     * Should be called during Layout Pass 1 before laying out paragraphs.
+     */
+    /**
+     * @param resolvedAnchorY — Fully resolved paint Y (already includes `offsetV`).
+     */
+    registerTable(tableBlock: TableBlock, measure: TableMeasure, resolvedAnchorY: number, columnIndex: number, pageNumber: number): void;
+    /**
+     * Get all exclusion zones that vertically overlap the given line.
+     * Used during paragraph layout to detect affected lines.
+     */
+    getExclusionsForLine(lineY: number, lineHeight: number, columnIndex: number, pageNumber: number): ExclusionZone[];
+    /**
+     * Compute available width for a line considering exclusion zones.
+     * Returns reduced width and horizontal offset if exclusions present.
+     */
+    computeAvailableWidth(lineY: number, lineHeight: number, baseWidth: number, columnIndex: number, pageNumber: number): {
+        width: number;
+        offsetX: number;
+    };
+    /**
+     * Get all floating images for a page (for debugging/painting).
+     */
+    getAllFloatsForPage(pageNumber: number): ExclusionZone[];
+    /**
+     * Clear all registered exclusion zones.
+     */
+    clear(): void;
+    /**
+     * Update layout context used for positioning and wrapping (columns, margins, page width).
+     */
+    setLayoutContext(columns: ColumnLayout, margins?: {
+        left?: number;
+        right?: number;
+    }, pageWidth?: number): void;
+};
+type ColumnLayout = ColumnLayoutForAnchor;
+export declare function createFloatingObjectManager(columns: ColumnLayout, margins?: {
+    left?: number;
+    right?: number;
+}, pageWidth?: number): FloatingObjectManager;
+/** @deprecated Use {@link resolveAnchoredGraphicX} from `@superdoc/contracts`. */
+export declare function computeAnchorX(anchor: NonNullable<ImageBlock['anchor']>, columnIndex: number, columns: ColumnLayout, imageWidth: number, margins?: {
+    left?: number;
+    right?: number;
+}, pageWidth?: number): number;
+export {};

package/dist/layout-engine/layout-engine/src/floating-table-anchor.d.ts

@@ -0,0 +1,21 @@
+import { FlowBlock, Measure, TableBlock, TableMeasure } from '../../contracts/src/index.js';
+export type FloatingTableAnchorResolution = {
+    paragraphIndex: number;
+    offsetV: number;
+    /**
+     * True when w:tblpY applies directly on the anchor paragraph's first line (Word line-scoped).
+     * Tall wrap-none form fields vertically center on that line.
+     */
+    lineScopedOnAnchor?: boolean;
+};
+/** Width ratio for inline (paginated) layout vs single float fragment. */
+export declare const ANCHORED_TABLE_FULL_WIDTH_RATIO = 0.99;
+/**
+ * True when an anchored table should paginate inline instead of as one float fragment.
+ * Uses tbl width, flow-affecting wrap distances from w:tblpPr, and table indent — not a fixed px fudge factor.
+ */
+export declare function isAnchoredTableFullWidth(block: TableBlock, measure: TableMeasure, columnWidth: number): boolean;
+/**
+ * Resolve anchor paragraph + vertical offset for a block-level floating table.
+ */
+export declare function resolveFloatingTableAnchorResolution(blocks: FlowBlock[], measures: Measure[], len: number, tableIndex: number, tableBlock: TableBlock, paragraphIndexById: Map<string, number>): FloatingTableAnchorResolution | null;