superdoc 2.2.0 → 2.3.0

package/dist/layout-engine/layout-bridge/src/footnote-scorer.d.ts

@@ -0,0 +1,63 @@
+import { FootnotePageLedger, Layout } from '../../contracts/src/index.js';
+export type FootnoteWindowScoreReason = 'globally-safe' | 'cluster-spill' | 'new-mandatory-only' | 'candidate-not-improved' | 'page-count-grew' | 'dead-reserve-bloat';
+export type FootnotePreferredReserveCandidate = {
+    pageIndex: number;
+    anchorIds: string[];
+    mandatoryReservePx: number;
+    preferredReservePx: number;
+    reserveDeltaPx: number;
+    actualBandHeightPx: number;
+    lastAnchorRenderedLines: number;
+};
+export type FootnoteWindowStats = {
+    totalPages: number;
+    mandatoryOnlyCount: number;
+    deadReserveSum: number;
+    clusterSplitCount: number;
+    candidateRenderedLines?: number;
+    /**
+     * Analyzer-only metric. Runtime layout does not know the Word baseline, but
+     * the scorer can carry this when a caller has external alignment data.
+     */
+    driftEvents?: number;
+};
+export type FootnoteWindowScoreInput = {
+    beforeLayout: Layout;
+    afterLayout: Layout;
+    candidatePageIndex: number;
+    candidateAnchorId?: string;
+    beforeLedger: FootnotePageLedger[];
+    afterLedger: FootnotePageLedger[];
+    windowAhead?: number;
+    preferredDeltaThresholdPx?: number;
+    mandatoryOnlyTolerancePx?: number;
+    deadReserveBloatThresholdPx?: number;
+    wholeDocumentDeadReserveBloatThresholdPx?: number;
+};
+export type FootnoteWindowScoreResult = {
+    accept: boolean;
+    reason: FootnoteWindowScoreReason;
+    before: FootnoteWindowStats;
+    after: FootnoteWindowStats;
+};
+export declare const isMandatoryOnlyFootnotePage: (ledger: FootnotePageLedger, preferredDeltaThresholdPx?: number, mandatoryOnlyTolerancePx?: number) => boolean;
+/**
+ * SD-2656 (post-Vivienne-feedback): a page whose LAST anchor partially rendered
+ * but spilled to a later page. The user-visible bug is a footnote split across
+ * pages even when the preferred reserve would fit the whole anchor on the
+ * anchor page (Word does keep it together).
+ *
+ * The "mandatory-only" predicate catches first-line-only splits; this predicate
+ * catches partial splits (lastAnchorRenderedLines > 1 but the rest still spilled).
+ * Both feed into the same scorer trial. The scorer's accept criteria
+ * (no new cluster spills, no new mandatory-only pages, bounded dead-reserve
+ * growth, candidate rendered lines improved) still gates whether the bump
+ * actually lands.
+ */
+export declare const isSplitLastAnchorFootnotePage: (ledger: FootnotePageLedger, preferredDeltaThresholdPx?: number) => boolean;
+export declare const getPreferredReserveCandidates: (ledgers: FootnotePageLedger[], preferredDeltaThresholdPx?: number, mandatoryOnlyTolerancePx?: number) => FootnotePreferredReserveCandidate[];
+export declare const getPreferredReserveTrialTargets: (candidate: FootnotePreferredReserveCandidate, currentReservePx: number, preferredDeltaThresholdPx?: number, maxTargets?: number) => number[];
+export declare const shouldAbsorbOneLineFootnoteWidow: (ledger: FootnotePageLedger, tailPx: number, oneLineTailPx?: number) => boolean;
+export declare const collectFootnoteLedgers: (layout: Layout) => FootnotePageLedger[];
+export declare const summarizeFootnoteWindow: (layout: Layout, ledgers: FootnotePageLedger[], candidatePageIndex: number, windowAhead?: number, preferredDeltaThresholdPx?: number, mandatoryOnlyTolerancePx?: number, candidateAnchorId?: string) => FootnoteWindowStats;
+export declare const scoreFootnoteWindow: (input: FootnoteWindowScoreInput) => FootnoteWindowScoreResult;

package/dist/layout-engine/layout-bridge/src/headerFooterUtils.d.ts

@@ -0,0 +1,218 @@
+import { HeaderFooterType, Layout, SectionMetadata, Page, HeaderFooterResolutionSection } from '../../contracts/src/index.js';
+export type HeaderFooterIdentifier = {
+    headerIds: Record<'default' | 'first' | 'even' | 'odd', string | null>;
+    footerIds: Record<'default' | 'first' | 'even' | 'odd', string | null>;
+    titlePg: boolean;
+    alternateHeaders: boolean;
+};
+export declare const defaultHeaderFooterIdentifier: () => HeaderFooterIdentifier;
+export type ConverterLike = {
+    headerIds?: {
+        default?: string | null;
+        first?: string | null;
+        even?: string | null;
+        odd?: string | null;
+        titlePg?: boolean;
+    };
+    footerIds?: {
+        default?: string | null;
+        first?: string | null;
+        even?: string | null;
+        odd?: string | null;
+        titlePg?: boolean;
+    };
+    pageStyles?: {
+        alternateHeaders?: boolean;
+    };
+};
+export declare const extractIdentifierFromConverter: (converter?: ConverterLike | null) => HeaderFooterIdentifier;
+export declare const getHeaderFooterType: (pageNumber: number, identifier: HeaderFooterIdentifier, options?: {
+    kind?: "header" | "footer";
+    parityPageNumber?: number;
+}) => HeaderFooterType | null;
+export declare const resolveHeaderFooterForPage: (layout: Layout, pageIndex: number, identifier: HeaderFooterIdentifier, options?: {
+    kind?: "header" | "footer";
+    parityPageNumber?: number;
+}) => {
+    type: HeaderFooterType;
+    layout: import('../../contracts/src/index.js').HeaderFooterLayout;
+    page: import('../../contracts/src/index.js').HeaderFooterPage;
+} | null;
+/**
+ * Type for per-section header/footer ID mappings.
+ * Maps variant types (default, first, even, odd) to their content IDs.
+ */
+export type SectionHeaderFooterIds = Record<'default' | 'first' | 'even' | 'odd', string | null>;
+/**
+ * Extended identifier that supports per-section header/footer mappings.
+ * Backward compatible with single-section documents via legacy fields.
+ */
+export type MultiSectionHeaderFooterIdentifier = {
+    headerIds: SectionHeaderFooterIds;
+    footerIds: SectionHeaderFooterIds;
+    titlePg: boolean;
+    alternateHeaders: boolean;
+    sectionCount: number;
+    sectionHeaderIds: Map<number, SectionHeaderFooterIds>;
+    sectionFooterIds: Map<number, SectionHeaderFooterIds>;
+    sectionTitlePg: Map<number, boolean>;
+    sections: HeaderFooterResolutionSection[];
+};
+/**
+ * Creates an empty multi-section identifier with default values.
+ */
+export declare const defaultMultiSectionIdentifier: () => MultiSectionHeaderFooterIdentifier;
+/**
+ * Builds a multi-section header/footer identifier from section metadata.
+ *
+ * This function creates mappings from section indices to their header/footer
+ * content IDs. It also maintains backward-compatible legacy fields populated
+ * from section 0 (or the first available section).
+ *
+ * @param sectionMetadata - Array of section metadata from layout options
+ * @param pageStyles - Optional page styles containing alternateHeaders flag
+ * @param converterIds - Optional converter-provided header/footer IDs to use as fallbacks
+ *   for dynamically created headers/footers. These IDs are only used when the corresponding
+ *   section metadata value is null. Existing section metadata always takes precedence.
+ * @returns MultiSectionHeaderFooterIdentifier with per-section mappings
+ *
+ * @example
+ * ```typescript
+ * const sections = [
+ *   { sectionIndex: 0, headerRefs: { default: 'rId1' }, footerRefs: { default: 'rId2' } },
+ *   { sectionIndex: 1, headerRefs: { default: 'rId3' }, footerRefs: { default: 'rId4' } },
+ * ];
+ * const identifier = buildMultiSectionIdentifier(sections);
+ * // identifier.sectionHeaderIds.get(0)?.default === 'rId1'
+ * // identifier.sectionFooterIds.get(1)?.default === 'rId4'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With converter IDs as fallbacks
+ * const sections = [
+ *   { sectionIndex: 0, headerRefs: { default: null }, footerRefs: { default: null } },
+ * ];
+ * const converterIds = {
+ *   headerIds: { default: 'conv-header-1' },
+ *   footerIds: { default: 'conv-footer-1' },
+ * };
+ * const identifier = buildMultiSectionIdentifier(sections, undefined, converterIds);
+ * // identifier.headerIds.default === 'conv-header-1' (from converter fallback)
+ * ```
+ */
+export declare function buildMultiSectionIdentifier(sectionMetadata: SectionMetadata[], pageStyles?: {
+    alternateHeaders?: boolean;
+}, converterIds?: {
+    headerIds?: {
+        default?: string | null;
+        first?: string | null;
+        even?: string | null;
+        odd?: string | null;
+        titlePg?: boolean;
+    };
+    footerIds?: {
+        default?: string | null;
+        first?: string | null;
+        even?: string | null;
+        odd?: string | null;
+        titlePg?: boolean;
+    };
+}): MultiSectionHeaderFooterIdentifier;
+/**
+ * Gets the header/footer variant type for a specific page within a section.
+ *
+ * This function determines which header/footer variant (default, first, even, odd)
+ * should be used for a given page number within a specific section. It respects:
+ * - Per-section titlePg (first page of section uses 'first' variant)
+ * - Alternate headers (even/odd pages based on the effective Word page number)
+ * - Fallback to default variant
+ *
+ * **Important**: When `titlePg` is enabled, this function returns 'first' even if the
+ * section doesn't explicitly define a 'first' header/footer. This supports Word's
+ * inheritance behavior where sections inherit header/footer definitions from previous
+ * sections. The rendering layer is responsible for resolving the actual content ID
+ * through inheritance fallback logic.
+ *
+ * @param pageNumber - Effective Word page number (1-indexed), after section page numbering settings
+ * @param sectionIndex - Index of the section this page belongs to
+ * @param identifier - Multi-section identifier with per-section mappings
+ * @param options - Optional settings (kind, sectionPageNumber, parityPageNumber)
+ * @returns HeaderFooterType ('default' | 'first' | 'even' | 'odd') or null if no header/footer content exists
+ *
+ * @example
+ * ```typescript
+ * // First page of section 1 with titlePg enabled and 'first' header defined
+ * const type = getHeaderFooterTypeForSection(1, 1, identifier, { kind: 'header' });
+ * // Returns 'first'
+ *
+ * // First page of section 2 with titlePg enabled but NO 'first' header defined
+ * // (section 2 only has 'default' header)
+ * const type = getHeaderFooterTypeForSection(2, 1, identifier, { kind: 'header' });
+ * // Returns 'first' - rendering layer will inherit from section 1's 'first' header
+ * ```
+ */
+export declare function getHeaderFooterTypeForSection(pageNumber: number, sectionIndex: number, identifier: MultiSectionHeaderFooterIdentifier, options?: {
+    kind?: 'header' | 'footer';
+    sectionPageNumber?: number;
+    parityPageNumber?: number;
+}): HeaderFooterType | null;
+/**
+ * Gets the header/footer content ID for a specific page using its section information.
+ *
+ * This function reads the page's sectionIndex and sectionRefs to determine
+ * the correct content ID for rendering the header or footer. It supports
+ * multi-section documents where each section can have different header/footer content.
+ *
+ * @param page - The Page object containing sectionIndex and sectionRefs
+ * @param identifier - Multi-section identifier (can be used for variant resolution)
+ * @param options - Optional settings (kind, sectionPageNumber, parityPageNumber)
+ * @returns The content ID string, or null if not available
+ *
+ * @example
+ * ```typescript
+ * // Page in section 2 with footerRefs.default = 'rId8'
+ * const footerId = getHeaderFooterIdForPage(page, identifier, { kind: 'footer' });
+ * // Returns 'rId8'
+ * ```
+ */
+export declare function getHeaderFooterIdForPage(page: Page, identifier: MultiSectionHeaderFooterIdentifier, options?: {
+    kind?: 'header' | 'footer';
+    sectionPageNumber?: number;
+    parityPageNumber?: number;
+}): string | null;
+/**
+ * Resolves header/footer layout information for a page using section-aware logic.
+ *
+ * This is the main entry point for section-aware header/footer resolution.
+ * It combines the page's section information with the multi-section identifier
+ * to select the correct header/footer content for rendering.
+ *
+ * @param layout - The complete Layout object with pages and headerFooter slots
+ * @param pageIndex - Index of the page in layout.pages array (0-indexed)
+ * @param identifier - Multi-section identifier with per-section mappings
+ * @param options - Optional settings (kind, parityPageNumber)
+ * @returns Resolution result with type, layout slot, page, and section info, or null
+ *
+ * @example
+ * ```typescript
+ * const result = resolveHeaderFooterForPageAndSection(layout, 5, identifier, { kind: 'footer' });
+ * if (result) {
+ *   // result.type: 'default' | 'first' | 'even' | 'odd'
+ *   // result.layout: HeaderFooterLayout for this variant
+ *   // result.page: HeaderFooterPage with fragments
+ *   // result.sectionIndex: Which section this page belongs to
+ *   // result.contentId: The rId for the header/footer XML content
+ * }
+ * ```
+ */
+export declare function resolveHeaderFooterForPageAndSection(layout: Layout, pageIndex: number, identifier: MultiSectionHeaderFooterIdentifier, options?: {
+    kind?: 'header' | 'footer';
+    parityPageNumber?: number;
+}): {
+    type: HeaderFooterType;
+    layout: NonNullable<NonNullable<Layout['headerFooter']>[HeaderFooterType]>;
+    page: NonNullable<NonNullable<Layout['headerFooter']>[HeaderFooterType]>['pages'][number];
+    sectionIndex: number;
+    contentId: string | null;
+} | null;

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

@@ -0,0 +1,81 @@
+/**
+ * IME Handler
+ *
+ * Handles Input Method Editor (IME) composition events for languages that require
+ * multi-key input sequences (e.g., Chinese, Japanese, Korean).
+ *
+ * Strategy:
+ * 1. Track composition state (start, update, end)
+ * 2. Defer aggressive layout updates during composition
+ * 3. Provide composition text for cursor positioning
+ * 4. Signal when full layout should resume
+ *
+ * @module ime-handler
+ */
+/**
+ * IME composition state.
+ */
+export interface ImeState {
+    /** Whether IME composition is currently active */
+    active: boolean;
+    /** Current composition text */
+    text: string;
+    /** Selection start within composition */
+    start: number;
+    /** Selection end within composition */
+    end: number;
+}
+/**
+ * ImeHandler manages IME composition events and provides signals for
+ * layout debouncing during multi-key input sequences.
+ */
+export declare class ImeHandler {
+    private state;
+    private layoutDebounceActive;
+    /**
+     * Called when composition starts (compositionstart event).
+     *
+     * @param event - CompositionEvent from browser
+     */
+    onCompositionStart(event: CompositionEvent): void;
+    /**
+     * Called when composition updates (compositionupdate event).
+     *
+     * @param event - CompositionEvent from browser
+     */
+    onCompositionUpdate(event: CompositionEvent): void;
+    /**
+     * Called when composition ends (compositionend event).
+     *
+     * @param event - CompositionEvent from browser
+     */
+    onCompositionEnd(event: CompositionEvent): void;
+    /**
+     * Check if IME composition is currently active.
+     *
+     * @returns True if composition is in progress
+     */
+    isActive(): boolean;
+    /**
+     * Get current composition text.
+     *
+     * @returns Composition text, or empty string if not composing
+     */
+    getCompositionText(): string;
+    /**
+     * Should layout be debounced more aggressively during composition?
+     *
+     * @returns True if layout should be deferred
+     */
+    shouldDeferLayout(): boolean;
+    /**
+     * Get full composition state for cursor positioning.
+     *
+     * @returns Current IME state
+     */
+    getState(): ImeState;
+    /**
+     * Manually reset IME state (useful for testing or error recovery).
+     */
+    reset(): void;
+}