superdoc 2.11.0 → 2.11.1-next.2

package/dist/collaboration-upgrade-engine.cjs

@@ -19,7 +19,7 @@ var COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = (0, _superdoc_docx_engine_collaboration_upgrade_engine.getCollaborationUpgradeEngineInfo)();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.11.0",
+	superdocVersion: "2.11.1-next.2",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

package/dist/collaboration-upgrade-engine.es.js

@@ -18,7 +18,7 @@ var COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR = 20;
 var PRIVATE_ENGINE_INFO = getCollaborationUpgradeEngineInfo$1();
 var ENGINE_INFO = Object.freeze({
 	...PRIVATE_ENGINE_INFO,
-	superdocVersion: "2.11.0",
+	superdocVersion: "2.11.1-next.2",
 	roomSchemaVersion: Object.freeze({ ...PRIVATE_ENGINE_INFO.roomSchemaVersion }),
 	supportedBundleVersions: SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS,
 	supportedV1ReaderContractVersions: SUPPORTED_V1_READER_CONTRACT_VERSIONS

package/dist/layout-engine/contracts/src/index.d.ts

@@ -2762,9 +2762,13 @@ export type HeaderFooterLayout = {
 export type LayoutBlockResumeCheckpoint = {
     blockId: BlockId;
     pageIndex: number;
+    /** Page before keep/fit decisions; editing may pull a deferred paragraph back here. */
+    preflightPageIndex?: number;
     prefixFragmentCount: number;
     cursorY: number;
     maxCursorY: number;
+    /** Exact accepted body footprint for coupled paragraph/note pagination. */
+    committedBodyBottom?: number;
     columnIndex: number;
     trailingSpacing: number;
     lastParagraphStyleId?: string;

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

@@ -0,0 +1,59 @@
+import { Page } from '../../contracts/src/index.js';
+import { FootnoteSlice } from './footnote-content.js';
+import { FootnotePageLedgerDraft, FootnotePagePlanInput, PendingFootnote } from './footnote-page-planner.js';
+export type CoupledFootnotePaginationOptions = Omit<FootnotePagePlanInput, 'pageIndex' | 'columnCount' | 'availableHeight' | 'idsByColumn' | 'pendingByColumn'> & {
+    pageSize: {
+        w: number;
+        h: number;
+    };
+    /** The bridge must validate exact boundary provenance before supplying a start, never a height-only seed. */
+    start?: {
+        pageIndex: number;
+        pendingByColumn: FootnotePagePlanInput['pendingByColumn'];
+        isPreviouslyAnchored(id: string): boolean;
+    };
+};
+export type CoupledFootnotePageCompletion = {
+    page: Page;
+    pageIndex: number;
+    bodyBottom: number;
+    physicalBottom: number;
+    anchors: readonly {
+        refId: string;
+    }[];
+};
+export type CoupledFootnotePageFlow = {
+    incomingDemand(pageIndex: number): {
+        height: number;
+        refs: number;
+    };
+    completePage(completion: CoupledFootnotePageCompletion): void;
+    hasPendingContinuation(): boolean;
+};
+export type CoupledFootnotePagination = {
+    flow: CoupledFootnotePageFlow;
+    plan: {
+        slicesByPage: Map<number, FootnoteSlice[]>;
+        reserves: number[];
+        hasContinuationByColumn: Map<string, boolean>;
+        separatorSpacingBefore: number;
+        ledgersByPage: Map<number, FootnotePageLedgerDraft>;
+        incomingByPage: Map<number, Map<number, PendingFootnote[]>>;
+        outgoingByPage: Map<number, Map<number, PendingFootnote[]>>;
+    };
+};
+export type CoupledFootnotePaginationFailure = 'unsupported-page' | 'page-sequence' | 'missing-anchor' | 'duplicate-claim' | 'ordered-minimum' | 'physical-overflow' | 'range-conservation' | 'reference-conservation' | 'no-progress';
+export declare class CoupledFootnotePaginationError extends Error {
+    readonly code: CoupledFootnotePaginationFailure;
+    readonly pageIndex: number;
+    readonly footnoteId?: string | undefined;
+    readonly name = "CoupledFootnotePaginationError";
+    constructor(code: CoupledFootnotePaginationFailure, pageIndex: number, message: string, footnoteId?: string | undefined);
+}
+/** Call only at real document EOF; expected IDs exclude references anchored before this pass. */
+export declare const validateCoupledFootnoteReferenceConservation: (plan: Pick<CoupledFootnotePagination["plan"], "ledgersByPage">, expectedAnchorIds: Iterable<string>) => void;
+/**
+ * Owns forward page admission from a fresh start or a bridge-validated boundary.
+ * Prepared inventories and prior anchor ownership remain lookup-only.
+ */
+export declare const createCoupledFootnotePagination: (options: CoupledFootnotePaginationOptions) => CoupledFootnotePagination;

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

@@ -0,0 +1,37 @@
+import { FlowBlock, Measure } from '../../contracts/src/index.js';
+import { LayoutOptions } from '../../layout-engine/src/index.js';
+export type CoupledFootnoteReference = {
+    id: string;
+    pos: number;
+    blockId?: string;
+    runOrdinal?: number | null;
+};
+export type CoupledFootnoteProfileRejection = 'no-footnote-references' | 'partial-or-semantic-flow' | 'multiple-sections' | 'invalid-page-geometry' | 'unsupported-columns' | 'unsupported-vertical-alignment' | 'unsupported-section-boundary' | 'unsupported-body-block' | 'unsupported-paragraph-geometry' | 'body-page-token' | 'measure-mismatch' | 'duplicate-block-id' | 'duplicate-reference-id' | 'missing-native-owner' | 'unresolved-reference-line' | 'unordered-native-references' | 'retained-profile-unproved' | 'reference-topology-changed';
+export type CoupledFootnoteParagraphUpdate = {
+    block: FlowBlock;
+    measure: Measure;
+    refs: readonly CoupledFootnoteReference[];
+    previousRefs: readonly CoupledFootnoteReference[];
+    /** Immediate CURRENT neighbors; null only at a true story boundary. */
+    predecessor: FlowBlock | null;
+    successor: FlowBlock | null;
+};
+export type CoupledFootnoteLocalProfileProof = {
+    baselineProfileExact: true;
+    referenceTopologyExact: true;
+};
+/**
+ * Revalidates only changed paragraphs beneath a bridge-owned retained global
+ * profile and exact current note topology. The bridge must prove those owners
+ * and supply all affected paragraphs, including referenced neighbors whose
+ * skip context changed. These flags do not mint a global/profile certificate.
+ */
+export declare const getCoupledFootnoteParagraphUpdatesUnsupportedReason: (updates: readonly CoupledFootnoteParagraphUpdate[], proof: CoupledFootnoteLocalProfileProof | null | undefined) => CoupledFootnoteProfileRejection | null;
+export declare const supportsCoupledFootnoteParagraphUpdates: (updates: readonly CoupledFootnoteParagraphUpdate[], proof: CoupledFootnoteLocalProfileProof | null | undefined) => boolean;
+/**
+ * Admission for fresh, single-section body/note flow. This does not certify
+ * note-content inventories or retained pages; their owners validate those.
+ * Rejection codes carry no document text and are suitable for diagnostics.
+ */
+export declare const getCoupledFootnotePaginationUnsupportedReason: (blocks: FlowBlock[], measures: readonly Measure[], options: LayoutOptions, refs: readonly CoupledFootnoteReference[]) => CoupledFootnoteProfileRejection | null;
+export declare const supportsCoupledFootnotePagination: (blocks: FlowBlock[], measures: readonly Measure[], options: LayoutOptions, refs: readonly CoupledFootnoteReference[]) => boolean;

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

@@ -0,0 +1,39 @@
+import { FlowBlock, Measure, ParagraphBlock } from '../../contracts/src/index.js';
+export type FootnoteRange = {
+    kind: 'paragraph';
+    blockId: string;
+    fromLine: number;
+    toLine: number;
+    totalLines: number;
+    height: number;
+    spacingAfter: number;
+} | {
+    kind: 'list-item';
+    blockId: string;
+    itemId: string;
+    fromLine: number;
+    toLine: number;
+    totalLines: number;
+    height: number;
+    spacingAfter: number;
+} | {
+    kind: 'table' | 'image' | 'drawing';
+    blockId: string;
+    height: number;
+};
+export type FootnoteSlice = {
+    id: string;
+    pageIndex: number;
+    columnIndex: number;
+    isContinuation: boolean;
+    ranges: FootnoteRange[];
+    totalHeight: number;
+};
+export declare const getParagraphSpacingAfter: (block: ParagraphBlock) => number;
+export declare const resolveSeparatorSpacingBefore: (rangesByFootnoteId: ReadonlyMap<string, readonly FootnoteRange[]>, measuresById: ReadonlyMap<string, Measure>, explicitValue: number | undefined, fallbackValue: number) => number;
+export declare const getRangeRenderHeight: (range: FootnoteRange) => number;
+export declare const buildFootnoteRanges: (blocks: readonly FlowBlock[], measuresById: ReadonlyMap<string, Measure>) => FootnoteRange[];
+export declare const fitFootnoteContent: (id: string, inputRanges: readonly FootnoteRange[], availableHeight: number, pageIndex: number, columnIndex: number, isContinuation: boolean, measuresById: ReadonlyMap<string, Measure>, forceFirstRange: boolean) => {
+    slice: FootnoteSlice;
+    remainingRanges: FootnoteRange[];
+};

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

@@ -0,0 +1,38 @@
+import { Page } from '../../contracts/src/index.js';
+import { CoupledFootnotePaginationOptions } from './coupled-footnote-pagination.js';
+import { FootnoteRange } from './footnote-content.js';
+export type FootnoteCertificatePreparedOptions = Readonly<Omit<CoupledFootnotePaginationOptions, 'start'>>;
+type PendingEntry = Readonly<{
+    id: string;
+    ranges: readonly Readonly<FootnoteRange>[];
+}>;
+export type FootnotePendingQueue = ReadonlyMap<number, readonly PendingEntry[]>;
+declare const ownerBrand: unique symbol;
+declare const certificateBrand: unique symbol;
+export type FootnoteCertificateOwner = Readonly<{
+    prepared: FootnoteCertificatePreparedOptions;
+    [ownerBrand]: true;
+}>;
+export type FootnotePageCertificateFacts = Readonly<{
+    /** Issuance/source index; transporting a certificate does not rebase it. */
+    pageIndex: number;
+    incomingByColumn: FootnotePendingQueue;
+    outgoingByColumn: FootnotePendingQueue;
+}>;
+export type FootnotePageCertificate = FootnotePageCertificateFacts & Readonly<{
+    owner: FootnoteCertificateOwner;
+    [certificateBrand]: true;
+}>;
+/** Prepared inputs must remain unchanged for the owner's lifetime; no inventory is copied or scanned here. */
+export declare const createFootnoteCertificateOwner: (prepared: FootnoteCertificatePreparedOptions) => FootnoteCertificateOwner;
+export declare const issueFootnotePageCertificate: (page: Page, owner: FootnoteCertificateOwner, facts: FootnotePageCertificateFacts) => FootnotePageCertificate;
+/** Omitting expectedOwner discovers retained inputs only; tail admission must supply its validated owner. */
+export declare const readFootnotePageCertificate: (page: Page | null | undefined, expectedOwner?: FootnoteCertificateOwner) => FootnotePageCertificate | null;
+/**
+ * Restores note-continuation provenance lost by string-key page cloning.
+ * The caller must separately prove body/rekey equivalence; this does not certify body reuse.
+ */
+export declare const transferFootnotePageCertificate: (source: Page, target: Page, pageIndexDelta: number) => FootnotePageCertificate | null;
+/** Queue order and every range field are part of the boundary; equal height is not equivalence. */
+export declare const pendingFootnoteQueuesEqual: (left: FootnotePendingQueue, right: FootnotePendingQueue) => boolean;
+export {};

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

@@ -0,0 +1,49 @@
+import { FootnotePageLedger, Measure } from '../../contracts/src/index.js';
+import { FootnoteRange, FootnoteSlice } from './footnote-content.js';
+export type PendingFootnote = {
+    id: string;
+    ranges: FootnoteRange[];
+};
+type IncomingFootnote = {
+    readonly id: string;
+    readonly ranges: readonly FootnoteRange[];
+};
+export type FootnotePageLedgerDraft = Omit<FootnotePageLedger, 'pageIndex' | 'appliedBodyReservePx' | 'deadReservePx'>;
+export type FootnotePagePlanInput = {
+    pageIndex: number;
+    columnCount: number;
+    /** Physical capacity for this page's note band, including separator, padding, and gaps. */
+    availableHeight: number;
+    idsByColumn: ReadonlyMap<number, readonly string[]>;
+    rangesByFootnoteId: ReadonlyMap<string, readonly FootnoteRange[]>;
+    measuresById: ReadonlyMap<string, Measure>;
+    fullHeightById: ReadonlyMap<string, number>;
+    firstLineHeightById: ReadonlyMap<string, number>;
+    pendingByColumn: ReadonlyMap<number, readonly IncomingFootnote[]>;
+    separatorSpacingBefore: number;
+    dividerHeight: number;
+    continuationDividerHeight: number;
+    topPadding: number;
+    gap: number;
+};
+export type FootnotePagePlan = {
+    slices: FootnoteSlice[];
+    pendingByColumn: Map<number, PendingFootnote[]>;
+    ledger: FootnotePageLedgerDraft;
+    /** Rounded reserve capped at the supplied capacity; not a proof that every slice fits. */
+    reserve: number;
+    /** Unrounded, uncapped height of the tallest placed column. */
+    actualReserve: number;
+    hasContinuationByColumn: Map<number, boolean>;
+    capped: boolean;
+    overflowHeightPx: number;
+    overflowHeightByColumn: Map<number, number>;
+    /** Outgoing ranges or physical overflow still require a controller decision. */
+    hasUnresolvedContent: boolean;
+};
+/**
+ * Places one page from exact incoming ranges. Global inventories are lookup-only;
+ * body placement and any future-page capacity decision belong to the caller.
+ */
+export declare const planFootnotePage: (input: FootnotePagePlanInput) => FootnotePagePlan;
+export {};

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

@@ -4,6 +4,7 @@ import { LayoutOptions, HeaderFooterConstraints, LayoutExecutionCheckpoint } fro
 import { computeDirtyRegions } from './diff.js';
 import { MeasureCache } from './cache.js';
 import { HeaderFooterBatch } from './layoutHeaderFooter.js';
+import { FootnoteCertificateOwner, FootnoteCertificatePreparedOptions } from './footnote-page-certificate.js';
 export type HeaderFooterMeasureFn = (block: FlowBlock, constraints: {
     maxWidth: number;
     maxHeight: number;
@@ -32,6 +33,10 @@ export type HeaderFooterLayoutResult = {
  * hashes — see the SD-3418 post-mortem for why identity keys are forbidden).
  */
 export type FootnoteReserveSeed = {
+    /** Identifies canonical forward output; not, by itself, a reuse certificate. */
+    paginationPolicy?: 'coupled-v1';
+    /** Opaque bridge-issued note/profile state; numeric reserve vectors never authorize page reuse. */
+    coupled?: CoupledFootnoteRetainedState;
     reserves: number[];
     /** Sparse page indexes that held a reserve, ledger, or injected note slice. */
     notePageIndexes?: number[];
@@ -63,6 +68,23 @@ export type FootnoteReserveSeed = {
         referencePageIndexes: number[];
     };
 };
+type CoupledFootnoteRetainedState = {
+    readonly owner: FootnoteCertificateOwner;
+    /** Current note inventory; may extend the certificate owner's page input during exact Undo. */
+    readonly prepared: FootnoteCertificatePreparedOptions;
+    readonly headerFooterGeometryFingerprint: string;
+    readonly reserves: readonly number[];
+    readonly notePageIndexes: readonly number[];
+    readonly refs: readonly FootnoteReference[];
+    readonly referencePlaneIdentity: FootnotesLayoutInput['refs'];
+    readonly referenceTopologyRevision: string | undefined;
+    readonly refIndexesByBlock: ReadonlyMap<string, readonly number[]>;
+    readonly refIndexById: ReadonlyMap<string, number>;
+    readonly blocksById: Map<string, FlowBlock>;
+    readonly extraBlocks: FlowBlock[];
+    readonly extraMeasures: Measure[];
+    readonly extraIndexById: ReadonlyMap<string, number>;
+};
 export type IncrementalLayoutResult = {
     layout: Layout;
     /** Pass-owned block plane after derived layout annotations are attached. */
@@ -104,6 +126,8 @@ export type IncrementalLayoutResult = {
     bridgeTiming: IncrementalLayoutBridgeTiming;
 };
 export type IncrementalLayoutBridgeTiming = {
+    /** Content-free reason a document used the conservative note fallback. */
+    footnoteCoupledRejection?: string;
     totalMs: number;
     inputPreparationMs: number;
     measureTotalMs: number;
@@ -169,6 +193,9 @@ export type IncrementalLayoutBridgeTiming = {
         footnoteWidowRelayouts: number;
         footnoteRevertRelayouts: number;
         footnoteOtherRelayouts: number;
+        footnoteCoupledRelayouts?: number;
+        footnoteCoupledPages?: number;
+        footnoteCoupledFallbacks?: number;
         footnoteAssignmentReferencesRead: number;
         footnoteAssignmentReferencesReused: number;
         footnoteAssignmentPagesIndexed: number;
@@ -397,6 +424,11 @@ export type IncrementalLayoutReuseOptions = {
         noteIds: readonly string[];
         bodyReferenceBlockIds: readonly string[];
     };
+    /** History-only inverse of a compiler-proved footnote removal. */
+    provedNoteReferenceRestoration?: {
+        sourceTxId: string;
+        restoredNoteIds: readonly string[];
+    };
     /**
      * Host-proved header/footer-only refresh. The bridge still compares the
      * current pre-layout height fingerprint before retaining body pagination.
@@ -416,6 +448,45 @@ export declare const measureCache: MeasureCache<Measure>;
  * state that can legally shift page geometry.
  */
 export declare function clearIncrementalModuleState(): void;
+type FootnoteReference = {
+    id: string;
+    /**
+     * Legacy v1 PM-position anchor. Resolved via fragment `pmStart` / `pmEnd`
+     * range matching. Required for v1 producers; v2 producers may set this
+     * to a synthetic value (e.g. block ordinal) and supply a `blockId`
+     * anchor for resolution.
+     */
+    pos: number;
+    /**
+     * v2 source anchor identifying the rendered body
+     * reference marker. When set, `assignFootnotesToColumns` resolves
+     * the reference's page/column by matching against
+     * `layout.pages[].fragments[].blockId` instead of falling back to
+     * positional fragment lookup. Editor-neutral by design.
+     */
+    blockId?: string;
+    /**
+     * Optional paragraph-run anchor used by v2 refs.
+     *
+     * A long paragraph can span multiple page fragments. When `blockId` alone
+     * is used, the bridge can only resolve the FIRST fragment carrying that
+     * block, which places later-line footnotes too early and cascades reserve
+     * drift across the document. When `runOrdinal` is present and a paragraph
+     * measure is available, the bridge resolves the fragment whose line range
+     * actually contains the referenced run.
+     */
+    runOrdinal?: number | null;
+};
+type FootnotesLayoutInput = {
+    refs: FootnoteReference[];
+    blocksById: Map<string, FlowBlock[]>;
+    /** Host-issued identity for the body reference topology. */
+    referenceTopologyRevision?: string;
+    gap?: number;
+    topPadding?: number;
+    dividerHeight?: number;
+    separatorSpacingBefore?: number;
+};
 type FootnoteGrowConvergenceState = {
     appliedReserves: readonly number[];
     plannedReserves: readonly number[];
@@ -472,12 +543,33 @@ export declare function incrementalLayout(previousBlocks: FlowBlock[], _previous
         blocks: FlowBlock[];
         measures: Measure[];
     };
+    /** Bridge-issued pre-removal owner selected by the exact history source tx. */
+    historyFootnoteRestoration?: {
+        sourceTxId: string;
+        restoredNoteIds: readonly string[];
+        sourceSeed: FootnoteReserveSeed;
+    };
     /** Current immutable host owner and the prior bridge-issued geometry seed. */
     headerFooterGeometry?: {
         ownerFingerprint: string;
         retainedSeed: HeaderFooterGeometrySeed | null;
     };
 }, layoutReuse?: IncrementalLayoutReuseOptions, measureReuseProof?: IncrementalMeasureReuseProof, execution?: IncrementalLayoutExecutionControl): Promise<IncrementalLayoutResult>;
+declare function shouldAttemptPreparedCoupledConvergenceRetry(input: {
+    preparedCoupled: boolean;
+    provedPrefixToDocumentEnd: boolean;
+    sameInvocationReserveRelayout: boolean;
+    paginationPrefix: boolean;
+    boundedRenderDiagnosticRetry: boolean;
+    retryAttempted: boolean;
+    terminalAttempted: boolean;
+    reachesSourceTail: boolean;
+    currentPageHorizon: number;
+    sourceAffectedFrontierPageIndex: number;
+    checkpointPageIndex: number;
+    previousPageCount: number;
+}): boolean;
+export declare const __test_only_shouldAttemptPreparedCoupledConvergenceRetry: typeof shouldAttemptPreparedCoupledConvergenceRetry;
 export declare function __test_only_splicedCheckpointStats(map: ReadonlyMap<string, LayoutBlockResumeCheckpoint> | undefined): {
     pieceCount: number;
     sourceCount: number;

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

@@ -1,4 +1,4 @@
-export type LayoutExecutionPhase = 'measure:block' | 'layout-document:prepare' | 'layout-document:preflight-section' | 'layout-document:preflight-footnote' | 'layout-document:preflight-anchor' | 'layout-document:preflight-keep-next' | 'layout-document:block' | 'layout-document:table-fragment' | 'layout-document:finalize-page' | 'layout-document:finalize-section' | 'page-token:prepare' | 'page-token:page' | 'numbering-context:chapter' | 'numbering-context:page' | 'footnote:phase' | 'header-footer:variant' | 'header-footer:block' | 'header-footer:page';
+export type LayoutExecutionPhase = 'measure:block' | 'layout-document:prepare' | 'layout-document:preflight-section' | 'layout-document:preflight-footnote' | 'layout-document:preflight-anchor' | 'layout-document:preflight-keep-next' | 'layout-document:block' | 'layout-document:table-fragment' | 'layout-document:footnote-continuation' | 'layout-document:finalize-page' | 'layout-document:finalize-section' | 'page-token:prepare' | 'page-token:page' | 'numbering-context:chapter' | 'numbering-context:page' | 'footnote:phase' | 'header-footer:variant' | 'header-footer:block' | 'header-footer:page';
 export type LayoutExecutionCheckpoint = {
     phase: LayoutExecutionPhase;
     index?: number;

package/dist/layout-engine/layout-engine/src/footnote-anchor-index.d.ts

@@ -2,10 +2,13 @@ import { FlowBlock } from '../../contracts/src/index.js';
 import { LayoutWorkCheckpoint } from './execution.js';
 import { FootnoteAnchorRef } from './layout-paragraph.js';
 export type FootnoteAnchorIndexInput = {
+    /** Use proved native paragraph/run ownership in the coupled page path. */
+    nativeRunOwnership?: boolean;
     refs?: Array<{
         id: string;
         pos: number;
         blockId?: string;
+        runOrdinal?: number | null;
     }>;
     bodyHeightById?: Map<string, number>;
     firstLineHeightById?: Map<string, number>;

package/dist/layout-engine/layout-engine/src/footnote-page-flow.d.ts

@@ -0,0 +1,28 @@
+import { Page } from '../../contracts/src/index.js';
+import { PageState } from './paginator.js';
+import { FootnoteAnchorRef } from './layout-paragraph.js';
+/** Internal body/notes handshake. The bridge owns exact continuation ranges. */
+export type FootnotePageFlow = {
+    /** False for a bounded block horizon: its EOF is not the document's EOF. */
+    completeDocument?: boolean;
+    incomingDemand(pageIndex: number): {
+        height: number;
+        refs: number;
+    };
+    completePage(input: {
+        page: Page;
+        pageIndex: number;
+        bodyBottom: number;
+        physicalBottom: number;
+        anchors: readonly FootnoteAnchorRef[];
+    }): void;
+    hasPendingContinuation(): boolean;
+};
+/**
+ * Both kept groups and individual lines use this budget. A numeric reserve
+ * from an earlier pagination has no authority over this page's exact queue.
+ */
+export declare function coupledFootnoteBodyBottom(state: PageState, anchoredHeight: number, anchoredRefs: number, incoming: {
+    height: number;
+    refs: number;
+}, overhead: (refs: number) => number, minimumBodyHeight?: number): number;

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

@@ -1,6 +1,9 @@
 import { ColumnLayout, FlowBlock, HeaderFooterLayout, Layout, Measure, Page, ParagraphBlock, ParagraphMeasure, SectionMetadata, FlowMode, DocumentBackground, ParagraphLineRegion } from '../../contracts/src/index.js';
+import { FootnotePageFlow } from './footnote-page-flow.js';
 import { PageState, ConstraintBoundary } from './paginator.js';
 import { LayoutExecutionControl } from './execution.js';
+export type { FootnotePageFlow } from './footnote-page-flow.js';
+export { findLineIndexForRunOrdinal } from './layout-utils.js';
 type PageSize = {
     w: number;
     h: number;
@@ -19,6 +22,8 @@ type Margins = {
  */
 export declare const SEMANTIC_PAGE_HEIGHT_PX = 1000000;
 export type LayoutOptions = {
+    /** @internal Exact forward body/note pagination; never supplied by document authors. */
+    footnotePageFlow?: FootnotePageFlow;
     pageSize?: PageSize;
     margins?: Margins;
     documentBackground?: DocumentBackground;
@@ -53,6 +58,8 @@ export type LayoutOptions = {
         refs?: Array<{
             id: string;
             pos: number;
+            blockId?: string;
+            runOrdinal?: number | null;
         }>;
         /**
          * SD-3049: total measured body height per footnote id (sum of measured
@@ -204,6 +211,7 @@ export type LayoutOptions = {
             prefixFragments: readonly Page['fragments'][number][];
             cursorY: number;
             maxCursorY: number;
+            committedBodyBottom?: number;
             columnIndex: number;
             trailingSpacing: number;
             lastParagraphStyleId?: string;

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

@@ -1,5 +1,6 @@
 import { FloatingObjectManager } from './floating-objects.js';
 import { PageState } from './paginator.js';
+import { FootnotePageFlow } from './footnote-page-flow.js';
 import { PageMargins, ParagraphBlock, ParagraphMeasure, ImageBlock, ImageMeasure, DrawingBlock, DrawingMeasure, ParagraphLineRegion } from '../../contracts/src/index.js';
 import { AnchoredTable } from './anchors.js';
 /**
@@ -9,11 +10,14 @@ import { AnchoredTable } from './anchors.js';
  */
 export type FootnoteAnchorRef = {
     pmPos: number;
+    /** Exact run in this paragraph; absent for legacy or containing-table anchors. */
+    runOrdinal?: number;
     refId: string;
     fullHeight: number;
     firstLineHeight: number;
 };
 export type ParagraphLayoutContext = {
+    incomingFootnoteDemand?: FootnotePageFlow['incomingDemand'];
     block: ParagraphBlock;
     measure: ParagraphMeasure;
     columnWidth: number;

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

@@ -66,6 +66,8 @@ export declare function sliceLines(lines: ParagraphMeasure['lines'], startIndex:
     height: number;
 };
 export type { LinePmRange };
+/** A marker belongs to the first measured line containing its run. */
+export declare const findLineIndexForRunOrdinal: (lines: readonly Line[] | undefined, runOrdinal: number) => number | null;
 export declare const computeFragmentPmRange: (block: ParagraphBlock, lines: ParagraphMeasure["lines"], fromLine: number, toLine: number) => LinePmRange;
 export declare const computeLinePmRange: (block: ParagraphBlock, line: Line) => LinePmRange;
 /**

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

@@ -20,6 +20,8 @@ export type PageState = {
      *  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;
+    /** Committed paragraph footprint, excluding speculative before/after spacing. */
+    committedBodyBottom?: number;
     /**
      * SD-3049: Page-level footnote reserve already baked into `contentBottom`
      * via `getActiveBottomMargin`. The block-aware break decision compares
@@ -78,6 +80,7 @@ export type PaginatorOptions = {
         prefixFragments: readonly Page['fragments'][number][];
         cursorY: number;
         maxCursorY: number;
+        committedBodyBottom?: number;
         columnIndex: number;
         trailingSpacing: number;
         lastParagraphStyleId?: string;
@@ -108,6 +111,8 @@ export type PaginatorOptions = {
      * created. Defaults to 0 when not provided.
      */
     getFootnoteReserveForPage?: (pageIndex: number) => number;
+    /** Coupled note-only continuation pages are real content before note injection. */
+    keepNoteOnlyPages?: boolean;
 };
 export declare class PaginationEarlyStop extends Error {
     constructor();

package/dist/superdoc.cjs

@@ -316,7 +316,7 @@ var shuffleArray = (array) => {
 var DEFAULT_ENDPOINT = "https://ingest.superdoc.dev/v1/collect";
 function getSuperdocVersion() {
 	try {
-		return "2.11.0";
+		return "2.11.1-next.2";
 	} catch {
 		return "unknown";
 	}
@@ -45188,7 +45188,7 @@ var SuperDoc = class extends require_eventemitter3.import_eventemitter3.default
 		this.config.colors = shuffleArray(this.config.colors);
 		this.userColorMap = /* @__PURE__ */ new Map();
 		this.colorIndex = 0;
-		this.version = "2.11.0";
+		this.version = "2.11.1-next.2";
 		this.#log("🦋 [superdoc] Using SuperDoc version:", this.version);
 		this.superdocId = config.superdocId || require_uuid.v4();
 		this.colors = this.config.colors ?? [];

package/dist/superdoc.es.js

@@ -315,7 +315,7 @@ var shuffleArray = (array) => {
 var DEFAULT_ENDPOINT = "https://ingest.superdoc.dev/v1/collect";
 function getSuperdocVersion() {
 	try {
-		return "2.11.0";
+		return "2.11.1-next.2";
 	} catch {
 		return "unknown";
 	}
@@ -45119,7 +45119,7 @@ var SuperDoc = class extends import_eventemitter3.default {
 		this.config.colors = shuffleArray(this.config.colors);
 		this.userColorMap = /* @__PURE__ */ new Map();
 		this.colorIndex = 0;
-		this.version = "2.11.0";
+		this.version = "2.11.1-next.2";
 		this.#log("🦋 [superdoc] Using SuperDoc version:", this.version);
 		this.superdocId = config.superdocId || v4();
 		this.colors = this.config.colors ?? [];