@beyondwork/docx-react-component 1.0.42 → 1.0.43

package/src/runtime/editor-state-integration.ts

@@ -0,0 +1,217 @@
+/**
+ * editor-state-integration.ts — Schema 1.2 Task D + E helpers.
+ *
+ * Factored out of document-runtime.ts / docx-session.ts to keep
+ * those files focused.  Two entry points:
+ *
+ * - `hydrateEditorStateFromEnvelope`: called right after the runtime
+ *   is created and the envelope parsed; drives the load-path.
+ * - `collectEditorStateForSerialize`: called inside exportDocx before
+ *   `buildWorkflowPayloadParts`; drives the save-path.
+ */
+
+import type { EditorStateNamespace } from "../api/editor-state-types.ts";
+import type { EditorStateChannel } from "./editor-state-channel.ts";
+import type {
+  EditorStatePayload,
+  EditorStatePayloadNamespaceEntry,
+} from "../io/ooxml/workflow-payload.ts";
+
+// All namespaces the runtime currently knows about.
+export const ALL_EDITOR_STATE_NAMESPACES: readonly EditorStateNamespace[] = [
+  "hostAnnotations",
+  "workflowOverlay",
+  "workflowMetadata",
+  "workItems",
+] as const;
+
+// ---------------------------------------------------------------------------
+// Load-path: hydrateEditorStateFromEnvelope
+// ---------------------------------------------------------------------------
+
+export interface HydrateEditorStateArgs {
+  /** The editorState block parsed from the workflow-payload envelope. */
+  editorState: EditorStatePayload;
+  channel: EditorStateChannel;
+  /**
+   * Called for each namespace whose blob has been resolved/loaded.
+   * Responsible for applying the blob to the appropriate subsystem store
+   * (e.g. calling runtime.setHostAnnotationOverlay).
+   */
+  applyBlob: (namespace: EditorStateNamespace, data: unknown) => void;
+}
+
+/**
+ * Drives the load-path for schema 1.2 editor-state entries.
+ *
+ * - Unknown namespaces → preserved opaquely, `unknown_namespace` event.
+ * - Inline entries under in-document policy → applied directly.
+ * - Keyed entries → resolver called; result applied (or failure handled).
+ * - Policy mismatch → `policy_migrated` event.
+ *
+ * Returns a promise that resolves when all namespaces have been
+ * processed.  Rejects only when `onResolveError` is `"block"` for a
+ * namespace and the resolver fails — the caller should fail the load.
+ */
+export async function hydrateEditorStateFromEnvelope(
+  args: HydrateEditorStateArgs,
+): Promise<void> {
+  const { editorState, channel, applyBlob } = args;
+
+  // Record unknown namespaces first — they are preserved opaquely by
+  // the payload layer; we emit the warning event AND hand the raw XML
+  // to the channel so the next save round-trips it verbatim.
+  for (const unknown of editorState.unknownNamespaces ?? []) {
+    channel.recordUnknownNamespace(unknown.name, { rawXml: unknown.rawXml });
+  }
+
+  for (const entry of editorState.entries) {
+    await hydrateEntry({ entry, channel, applyBlob });
+  }
+}
+
+async function hydrateEntry(args: {
+  entry: EditorStatePayloadNamespaceEntry;
+  channel: EditorStateChannel;
+  applyBlob: (namespace: EditorStateNamespace, data: unknown) => void;
+}): Promise<void> {
+  const { entry, channel, applyBlob } = args;
+  const ns = entry.namespace;
+  const policyEntry = channel.getPolicyEntry(ns);
+
+  // Malformed inline JSON: surface as a load failure; don't apply.
+  if (entry.malformedInline) {
+    channel.recordLoadFailure({
+      namespace: ns,
+      error: new Error(`Malformed inline JSON for namespace "${ns}"`),
+      fallback: policyEntry.onResolveError === "block" ? "empty" : policyEntry.onResolveError,
+    });
+    return;
+  }
+
+  // Policy-migration detection: compare payload-written location vs
+  // current policy location.
+  const payloadLocation: string = entry.storageRef
+    ? entry.storageRef.location
+    : "in-document";
+  if (payloadLocation !== policyEntry.location) {
+    channel.recordPolicyMigration({
+      namespace: ns,
+      from: payloadLocation as import("../api/editor-state-types.ts").EditorStateLocation,
+      to: policyEntry.location,
+      key: entry.storageRef?.entryKey,
+    });
+  }
+
+  // Inline path: apply directly when both payload and policy agree on
+  // in-document.
+  if (entry.inline !== undefined && policyEntry.location === "in-document") {
+    applyBlob(ns, entry.inline);
+    channel.recordLoaded(ns, {
+      namespace: ns,
+      schemaVersion: entry.schemaVersion,
+      data: entry.inline,
+    });
+    return;
+  }
+
+  // Keyed path: set the key from the payload, then call the resolver.
+  if (entry.storageRef) {
+    channel.setKey(ns, entry.storageRef.entryKey);
+    // Under keyed policy the resolver wins over any inline blob.
+    const result = await channel.resolve(ns, entry.storageRef.entryKey);
+    if (result.blob !== null) {
+      applyBlob(ns, result.blob.data);
+      if (!result.appliedFallback) {
+        channel.recordLoaded(ns, result.blob);
+      }
+    }
+    // result.blob === null → failure already handled by channel (event
+    // emitted, fallback mode applied).  Nothing more to apply.
+    return;
+  }
+
+  // Mismatch: payload is inline but policy is keyed.  Apply inline as
+  // fallback (no key to resolve against).
+  if (entry.inline !== undefined) {
+    applyBlob(ns, entry.inline);
+    channel.recordLoaded(ns, {
+      namespace: ns,
+      schemaVersion: entry.schemaVersion,
+      data: entry.inline,
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Save-path: collectEditorStateForSerialize
+// ---------------------------------------------------------------------------
+
+export interface CollectEditorStateArgs {
+  channel: EditorStateChannel;
+  /**
+   * Returns the current in-memory blob for a namespace, or null if
+   * the namespace has no data to persist.
+   */
+  getNamespaceData: (ns: EditorStateNamespace) => { schemaVersion: string; data: unknown } | null;
+}
+
+/**
+ * Builds the `EditorStatePayload` for the serializer.
+ *
+ * 1. Flushes any pending debounced persists so the docx captures
+ *    the last-known-good state for rowstore namespaces.
+ * 2. For each namespace with data: emits inline or storageRef per policy.
+ * 3. Returns undefined when no namespaces have data — the serializer
+ *    then omits `<bw:editorState>` entirely (downgrade to 1.1/1.0).
+ */
+export async function collectEditorStateForSerialize(
+  args: CollectEditorStateArgs,
+): Promise<EditorStatePayload | undefined> {
+  const { channel, getNamespaceData } = args;
+
+  // Flush pending debounced persists before serialize resolves.
+  await channel.flush();
+
+  const entries: EditorStatePayloadNamespaceEntry[] = [];
+
+  for (const ns of ALL_EDITOR_STATE_NAMESPACES) {
+    const current = getNamespaceData(ns);
+    if (!current) continue;
+
+    const policyEntry = channel.getPolicyEntry(ns);
+
+    if (policyEntry.location === "in-document") {
+      entries.push({
+        namespace: ns,
+        schemaVersion: current.schemaVersion,
+        inline: current.data,
+      });
+    } else {
+      const key = channel.getKey(ns);
+      if (!key) continue; // Keyed policy without a key — can't serialize ref.
+      entries.push({
+        namespace: ns,
+        schemaVersion: current.schemaVersion,
+        storageRef: {
+          location: policyEntry.location as Exclude<
+            import("../api/editor-state-types.ts").EditorStateLocation,
+            "in-document"
+          >,
+          entryKey: key,
+        },
+      });
+    }
+  }
+
+  const unknownEntries = channel.getUnknownEntries();
+  const unknownNamespaces = unknownEntries
+    .filter((u): u is typeof u & { rawXml: string } => typeof u.rawXml === "string")
+    .map((u) => ({ name: u.name, rawXml: u.rawXml }));
+
+  if (entries.length === 0 && unknownNamespaces.length === 0) return undefined;
+  return {
+    entries,
+    ...(unknownNamespaces.length > 0 ? { unknownNamespaces } : {}),
+  };
+}

package/src/runtime/layout/index.ts

@@ -172,6 +172,8 @@ export {
   type PublicPageNode,
   type PublicPageRegions,
   type PublicPageRegion,
+  type PublicRegionBlock,
+  type PublicRegionKind,
   type PublicBlockFragment,
   type PublicLineBox,
   type PublicNoteAllocation,

package/src/runtime/layout/inert-layout-facet.ts

@@ -36,6 +36,8 @@ export function createInertLayoutFacet(): WordReviewEditorLayoutFacet {
     getLineBoxes: () => [],
     getLineBoxesForRegion: () => [],
     getStoryRegionsOnPage: () => [],
+    getStoryBlocksForRegion: () => [],
+    getDocumentEndnoteBlocks: () => [],
     getFragmentsForPage: () => [],
     getPageFormatCatalog: () => PAGE_FORMAT_CATALOG,
     getActivePageFormat: () => null,

package/src/runtime/layout/layout-engine-instance.ts

@@ -296,16 +296,24 @@ export function createLayoutEngine(
     );
     const pages = pageStack.pages;
     const stories = resolvePageStories(pages);
-    const fragmentsByPageIndex = projectSurfaceBlocksToPageFragments(
+    const bodyFragmentsByPageIndex = projectSurfaceBlocksToPageFragments(
       mainSurface,
       pages,
       pageStack.splits,
     );
+    // P8.1b — merge per-note fragments (regionKind: "footnote-area") into the
+    // main fragments map so buildPageGraph sees them alongside body fragments.
+    const fragmentsByPageIndex = new Map(bodyFragmentsByPageIndex);
+    for (const [pageIndex, noteFragments] of (pageStack.noteFragmentsByPageIndex ?? new Map())) {
+      const existing = fragmentsByPageIndex.get(pageIndex) ?? [];
+      fragmentsByPageIndex.set(pageIndex, [...existing, ...noteFragments]);
+    }
     const graph = buildPageGraph({
       pages,
       sections,
       stories,
       fragmentsByPageIndex,
+      noteAllocationsByPageIndex: pageStack.noteAllocationsByPageIndex,
     });
 
     // Field dirtiness diff from previous graph
@@ -413,16 +421,23 @@ export function createLayoutEngine(
     const freshStories = resolvePageStories(freshSnapshots);
     // Project fragments for the fresh tail pages, threading paragraph
     // line-range splits produced by intra-paragraph pagination.
-    const freshFragmentsByPageIndex = projectSurfaceBlocksToPageFragments(
+    const freshBodyFragmentsByPageIndex = projectSurfaceBlocksToPageFragments(
       mainSurface,
       freshSnapshots,
       freshResult.splits,
     );
+    // P8.1b — merge per-note fragments into the fresh fragments map.
+    const freshFragmentsByPageIndex = new Map(freshBodyFragmentsByPageIndex);
+    for (const [pageIndex, noteFragments] of (freshResult.noteFragmentsByPageIndex ?? new Map())) {
+      const existing = freshFragmentsByPageIndex.get(pageIndex) ?? [];
+      freshFragmentsByPageIndex.set(pageIndex, [...existing, ...noteFragments]);
+    }
     const freshGraph = buildPageGraph({
       pages: freshSnapshots,
       sections,
       stories: freshStories,
       fragmentsByPageIndex: freshFragmentsByPageIndex,
+      noteAllocationsByPageIndex: freshResult.noteAllocationsByPageIndex,
     });
     const freshNodes = freshGraph.pages;
 

package/src/runtime/layout/paginated-layout-engine.ts

@@ -41,6 +41,10 @@ import type {
   FootnoteCollection,
 } from "../../model/canonical-document.ts";
 import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import type {
+  RuntimeNoteAllocation,
+  RuntimeBlockFragment,
+} from "./page-graph.ts";
 import {
   buildPageLayoutSnapshot,
   buildResolvedSections,
@@ -138,6 +142,19 @@ export interface BlockSplits {
 export interface PageStackResultWithSplits {
   pages: DocumentPageSnapshot[];
   splits: BlockSplits;
+  /**
+   * P8.1b — per-page note allocations emitted by the engine.
+   * Keyed by zero-based global page index.
+   * Absent entries mean the page has no footnotes.
+   * Endnote allocations are deferred to P8 Task 7.
+   */
+  noteAllocationsByPageIndex?: ReadonlyMap<number, RuntimeNoteAllocation[]>;
+  /**
+   * P8.1b — per-page note body fragments emitted by the engine.
+   * Each fragment has `regionKind: "footnote-area"`.
+   * Parallel to `noteAllocationsByPageIndex`.
+   */
+  noteFragmentsByPageIndex?: ReadonlyMap<number, Array<Omit<RuntimeBlockFragment, "pageId">>>;
 }
 
 // ---------------------------------------------------------------------------
@@ -182,6 +199,13 @@ export function buildPageStackWithSplits(
 ): PageStackResultWithSplits {
   const pages: DocumentPageSnapshot[] = [];
   const splitsByBlock = new Map<string, ParagraphLineSlice[]>();
+  // P8.1b — aggregate note allocations and fragments across all sections,
+  // keyed by global page index.
+  const globalNoteAllocationsByPageIndex = new Map<number, RuntimeNoteAllocation[]>();
+  const globalNoteFragmentsByPageIndex = new Map<
+    number,
+    Array<Omit<RuntimeBlockFragment, "pageId">>
+  >();
   let globalPageIndex = 0;
   // A single cache lives for the whole pagination pass so cross-section
   // re-measurement (rare but possible through keepNext heuristics) still
@@ -305,6 +329,21 @@ export function buildPageStackWithSplits(
       }
       if (existing.length > 0) splitsByBlock.set(blockId, existing);
     }
+
+    // P8.1b — resolve per-section note allocations + fragments to global
+    // page index and merge into the global maps.
+    for (const [pageInSec, sectionAllocs] of paginatedResult.noteAllocationsByPageInSection) {
+      const globalPageIdx = pageInSectionToGlobal.get(pageInSec);
+      if (globalPageIdx === undefined) continue;
+      const existing = globalNoteAllocationsByPageIndex.get(globalPageIdx) ?? [];
+      globalNoteAllocationsByPageIndex.set(globalPageIdx, [...existing, ...sectionAllocs]);
+    }
+    for (const [pageInSec, sectionFrags] of paginatedResult.noteFragmentsByPageInSection) {
+      const globalPageIdx = pageInSectionToGlobal.get(pageInSec);
+      if (globalPageIdx === undefined) continue;
+      const existing = globalNoteFragmentsByPageIndex.get(globalPageIdx) ?? [];
+      globalNoteFragmentsByPageIndex.set(globalPageIdx, [...existing, ...sectionFrags]);
+    }
   }
 
   // Guarantee at least one page
@@ -328,6 +367,12 @@ export function buildPageStackWithSplits(
   return {
     pages,
     splits: { byBlockId: splitsByBlock, tablesByBlockId: tableSplitsByBlock },
+    noteAllocationsByPageIndex: globalNoteAllocationsByPageIndex.size > 0
+      ? globalNoteAllocationsByPageIndex
+      : undefined,
+    noteFragmentsByPageIndex: globalNoteFragmentsByPageIndex.size > 0
+      ? globalNoteFragmentsByPageIndex
+      : undefined,
   };
 }
 
@@ -984,6 +1029,10 @@ interface SectionLocalSlice {
 interface SectionPaginationResult {
   pages: Omit<DocumentPageSnapshot, "pageIndex">[];
   splits: { byBlockId: Map<string, SectionLocalSlice[]> };
+  /** P8.1b — per-page note allocations keyed by pageInSection index. */
+  noteAllocationsByPageInSection: Map<number, RuntimeNoteAllocation[]>;
+  /** P8.1b — per-page note body fragments keyed by pageInSection index. */
+  noteFragmentsByPageInSection: Map<number, Array<Omit<RuntimeBlockFragment, "pageId">>>;
 }
 
 /**
@@ -1009,7 +1058,7 @@ function paginateSectionBlocks(
   ).pages;
 }
 
-function paginateSectionBlocksWithSplits(
+export function paginateSectionBlocksWithSplits(
   section: ResolvedDocumentSection,
   blocks: readonly SurfaceBlockSnapshot[],
   layout: DocumentPageSnapshot["layout"],
@@ -1029,6 +1078,8 @@ function paginateSectionBlocksWithSplits(
         },
       ],
       splits: { byBlockId: new Map() }, // section-local; global map includes tablesByBlockId via collectTableRowSlices
+      noteAllocationsByPageInSection: new Map(),
+      noteFragmentsByPageInSection: new Map(),
     };
   }
 
@@ -1048,14 +1099,104 @@ function paginateSectionBlocksWithSplits(
   // table is fully placed.
   const tableProgress = new Map<string, number>();
 
+  // P8.1b — per-page note tracking.
+  // `pendingNoteKeys` parallels `reservedNotes` but is only snapshotted on
+  // page-push (finalization), NOT on column break.
+  // `pendingNoteBlockFroms` records the referencing block's `from` offset
+  // for each note key, enabling hit-test via `RuntimeBlockFragment.from`.
+  const noteAllocationsByPageInSection = new Map<number, RuntimeNoteAllocation[]>();
+  const noteFragmentsByPageInSection = new Map<
+    number,
+    Array<Omit<RuntimeBlockFragment, "pageId">>
+  >();
+  const pendingNoteKeys = new Set<string>();
+  const pendingNoteBlockFroms = new Map<string, { blockFrom: number; blockTo: number }>();
+  // Track the columnWidth at the time each note was accumulated so the
+  // measurement is reproducible at page-close time.
+  const pendingNoteColumnWidths = new Map<string, number>();
+
+  /**
+   * Snapshot the pending note state into `noteAllocationsByPageInSection` and
+   * `noteFragmentsByPageInSection` for the page that is about to close.
+   * Must be called BEFORE clearing `pendingNoteKeys`.
+   */
+  const snapshotNoteAllocations = (closingPageInSection: number, columnWidth: number): void => {
+    if (pendingNoteKeys.size === 0 || !footnotes) return;
+
+    const allocations: RuntimeNoteAllocation[] = [];
+    const fragments: Array<Omit<RuntimeBlockFragment, "pageId">> = [];
+    let orderInRegion = 0;
+
+    for (const noteKey of pendingNoteKeys) {
+      const colonIdx = noteKey.indexOf(":");
+      if (colonIdx === -1) continue;
+      const noteKind = noteKey.slice(0, colonIdx) as "footnote" | "endnote";
+      const noteId = noteKey.slice(colonIdx + 1);
+
+      // P8.1b: endnote allocations are deferred to P8 Task 7 (endnote area
+      // component).  The existing reservedNoteHeight math still reserves space
+      // for endnotes, but we do not emit RuntimeNoteAllocation for them here.
+      // See P8 plan, Task 7.
+      if (noteKind === "endnote") continue;
+
+      const effectiveColumnWidth =
+        pendingNoteColumnWidths.get(noteKey) ?? columnWidth;
+      const { heightTwips } = measureNoteBody(
+        noteKind,
+        noteId,
+        footnotes,
+        effectiveColumnWidth,
+      );
+
+      const fragmentId = `note-${closingPageInSection}-${noteKind}-${noteId}`;
+      const refRange = pendingNoteBlockFroms.get(noteKey) ?? {
+        blockFrom: pageStart,
+        blockTo: pageStart + 1,
+      };
+
+      const allocation: RuntimeNoteAllocation = {
+        noteKind,
+        noteId,
+        reservedHeightTwips: heightTwips + FOOTNOTE_REFERENCE_RESERVATION_TWIPS,
+        fragmentId,
+      };
+
+      const fragment: Omit<RuntimeBlockFragment, "pageId"> = {
+        fragmentId,
+        blockId: `note-body-${noteKind}-${noteId}`,
+        orderInRegion,
+        regionKind: "footnote-area",
+        from: refRange.blockFrom,
+        to: refRange.blockTo,
+        heightTwips: heightTwips + FOOTNOTE_REFERENCE_RESERVATION_TWIPS,
+        kind: "whole",
+      };
+
+      allocations.push(allocation);
+      fragments.push(fragment);
+      orderInRegion += 1;
+    }
+
+    if (allocations.length > 0) {
+      noteAllocationsByPageInSection.set(closingPageInSection, allocations);
+      noteFragmentsByPageInSection.set(closingPageInSection, fragments);
+    }
+  };
+
   const pushPage = (endOffset: number): void => {
     const boundedEnd = Math.max(pageStart, Math.min(endOffset, section.end));
     if (boundedEnd === pageStart && pages.length > 0) {
       return;
     }
+    const closingPageInSection = pageInSection;
+    const columnWidth =
+      columnMetrics[Math.min(columnIndex, columnMetrics.length - 1)]?.width ??
+      getUsableColumnWidth(layout);
+    // Snapshot note allocations for the page being closed BEFORE clearing state.
+    snapshotNoteAllocations(closingPageInSection, columnWidth);
     pages.push({
       sectionIndex: section.index,
-      pageInSection,
+      pageInSection: closingPageInSection,
       startOffset: pageStart,
       endOffset: boundedEnd,
       layout,
@@ -1066,6 +1207,10 @@ function paginateSectionBlocksWithSplits(
     columnIndex = 0;
     reservedNoteHeight = 0;
     reservedNotes.clear();
+    // P8.1b: also clear pending note tracking on page finalization.
+    pendingNoteKeys.clear();
+    pendingNoteBlockFroms.clear();
+    pendingNoteColumnWidths.clear();
   };
 
   for (let index = 0; index < blocks.length; index += 1) {
@@ -1183,10 +1328,15 @@ function paginateSectionBlocksWithSplits(
       // Overflow check — paragraph doesn't fit on current page
       if (projectedHeight > usableHeight && pageStart < block.from) {
         if (columnIndex < maxColumns - 1) {
+          // Advance to next column without a page break — do NOT snapshot.
           columnIndex += 1;
           columnHeight = 0;
           reservedNoteHeight = 0;
           reservedNotes.clear();
+          // P8.1b: clear pending note state WITHOUT snapshotting.
+          pendingNoteKeys.clear();
+          pendingNoteBlockFroms.clear();
+          pendingNoteColumnWidths.clear();
           continue;
         }
 
@@ -1264,10 +1414,15 @@ function paginateSectionBlocksWithSplits(
       // span the full page if it's truly larger than a page).
       if (keepLinesActive && columnHeight > 0 && baseHeight > usableHeight - columnHeight && pageStart < block.from) {
         if (columnIndex < maxColumns - 1) {
+          // Column advance without page break — do NOT snapshot.
           columnIndex += 1;
           columnHeight = 0;
           reservedNoteHeight = 0;
           reservedNotes.clear();
+          // P8.1b: clear pending note state WITHOUT snapshotting.
+          pendingNoteKeys.clear();
+          pendingNoteBlockFroms.clear();
+          pendingNoteColumnWidths.clear();
           continue;
         }
         pushPage(block.from);
@@ -1282,14 +1437,32 @@ function paginateSectionBlocksWithSplits(
       );
       columnHeight += baseHeight;
       reservedNoteHeight += effectiveNoteHeight;
-      currentPageNoteIds(block).forEach((noteKey) => reservedNotes.add(noteKey));
+      currentPageNoteIds(block).forEach((noteKey) => {
+        reservedNotes.add(noteKey);
+        // P8.1b: also track the referencing block range for hit-test.
+        // Only record the first reference (earliest block.from) per noteKey
+        // so the fragment's from/to points to the paragraph that introduced it.
+        if (!pendingNoteKeys.has(noteKey)) {
+          pendingNoteKeys.add(noteKey);
+          pendingNoteBlockFroms.set(noteKey, { blockFrom: block.from, blockTo: block.to });
+          pendingNoteColumnWidths.set(noteKey, columnWidth);
+        }
+      });
 
       if (hasColumnBreak(block)) {
         if (columnIndex < maxColumns - 1) {
+          // Column break within a multi-column layout: advance to next column.
+          // DO NOT snapshot note allocations — only page-push triggers snapshotting.
+          // Clear pending note state alongside reservedNotes so notes that only
+          // appeared before the column break don't get double-counted.
           columnIndex += 1;
           columnHeight = 0;
           reservedNoteHeight = 0;
           reservedNotes.clear();
+          // P8.1b: clear pending note state WITHOUT snapshotting.
+          pendingNoteKeys.clear();
+          pendingNoteBlockFroms.clear();
+          pendingNoteColumnWidths.clear();
         } else {
           pushPage(nextBoundary);
         }
@@ -1317,9 +1490,37 @@ function paginateSectionBlocksWithSplits(
             },
           ],
     splits: { byBlockId: splitsByBlock },
+    noteAllocationsByPageInSection,
+    noteFragmentsByPageInSection,
   };
 }
 
+/**
+ * Measure the height consumed by one note's body blocks, plus return those
+ * blocks for use in building a `RuntimeBlockFragment`.
+ *
+ * Factored out of `estimateFootnoteReservation` so both the reservation-math
+ * path and the P8.1b allocation-emission path share the same measurement.
+ */
+function measureNoteBody(
+  noteKind: "footnote" | "endnote",
+  noteId: string,
+  footnotes: FootnoteCollection,
+  columnWidth: number,
+): { heightTwips: number } {
+  const noteCollection =
+    noteKind === "endnote" ? footnotes.endnotes : footnotes.footnotes;
+  const note = noteCollection[noteId];
+  if (!note) {
+    return { heightTwips: 0 };
+  }
+  const heightTwips = note.blocks.reduce(
+    (total, child) => total + estimateCanonicalNoteBlockHeight(child, columnWidth),
+    0,
+  );
+  return { heightTwips };
+}
+
 function estimateFootnoteReservation(
   block: SurfaceBlockSnapshot,
   footnotes: FootnoteCollection | undefined,
@@ -1336,17 +1537,13 @@ function estimateFootnoteReservation(
       continue;
     }
 
-    const [noteKind, noteId] = noteKey.split(":");
-    const noteCollection =
-      noteKind === "endnote" ? footnotes.endnotes : footnotes.footnotes;
-    const note = noteCollection[noteId];
-    reservation += FOOTNOTE_REFERENCE_RESERVATION_TWIPS;
-    if (note) {
-      reservation += note.blocks.reduce(
-        (total, child) => total + estimateCanonicalNoteBlockHeight(child, columnWidth),
-        0,
-      );
-    }
+    const colonIdx = noteKey.indexOf(":");
+    if (colonIdx === -1) continue;
+    const noteKind = noteKey.slice(0, colonIdx) as "footnote" | "endnote";
+    const noteId = noteKey.slice(colonIdx + 1);
+    // Use measureNoteBody so reservation math and emission share the same path.
+    const { heightTwips } = measureNoteBody(noteKind, noteId, footnotes, columnWidth);
+    reservation += FOOTNOTE_REFERENCE_RESERVATION_TWIPS + heightTwips;
   }
 
   return reservation;