@beyondwork/docx-react-component 1.0.66 → 1.0.69

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

@@ -9,8 +9,21 @@
  *   - `nextPage` (default) — new page set per section
  *   - `evenPage` / `oddPage` — blank filler pages to meet parity
  *   - `continuous` — the new section continues on the previous section's last page
- *   - `nextColumn` — treated as `continuous` (column advance still TODO for
- *     true multi-column typeset; see `paginateSectionBlocks`)
+ *   - `nextColumn` — within a section, a block-level column break
+ *     (`<w:br w:type="column"/>`) advances the active column; on column
+ *     overflow the engine either advances to the next column or pushes
+ *     a new page (which inherits the current section's column layout).
+ *     At section granularity, a `<w:type w:val="nextColumn"/>` section
+ *     break degrades to `continuous` — Word's behavior on single-column
+ *     sections, preserved verbatim for multi-column sections in this
+ *     slice so cross-section column-state carry is explicit follow-up
+ *     work rather than implicit semantics.
+ *
+ * Column placement is tracked per block and surfaced via
+ * `PageStackResultWithSplits.columnByBlockIdByPageIndex`;
+ * `project-block-fragments.ts` consumes it to stamp
+ * `RuntimeBlockFragment.columnIndex`, and `buildRegions` routes fragments
+ * into `RuntimePageRegions.columns[i].fragmentIds`.
  *
  * Paragraph-level pagination hints:
  *   - `keepNext` — already honored in `paginateSectionBlocks`
@@ -58,6 +71,7 @@ import {
   getUsablePageHeight,
 } from "../page-layout-estimation.ts";
 import {
+  buildRunFormattingMap,
   calculateParagraphHeight,
   resolveBlockFormatting,
   resolveCharsPerLine,
@@ -155,6 +169,14 @@ export interface PageStackResultWithSplits {
    * Parallel to `noteAllocationsByPageIndex`.
    */
   noteFragmentsByPageIndex?: ReadonlyMap<number, Array<Omit<RuntimeBlockFragment, "pageId">>>;
+  /**
+   * Refactor/04 Slice 4 — per-block column placement keyed by global page
+   * index. Inner map: `blockId → columnIndex`. Absent when every page on the
+   * graph is single-column; `project-block-fragments.ts` consumes this to
+   * stamp `RuntimeBlockFragment.columnIndex` and route fragments into
+   * `RuntimePageRegions.columns[i].fragmentIds`.
+   */
+  columnByBlockIdByPageIndex?: ReadonlyMap<number, ReadonlyMap<string, number>>;
 }
 
 // ---------------------------------------------------------------------------
@@ -207,6 +229,16 @@ export function buildPageStackWithSplits(
     number,
     Array<Omit<RuntimeBlockFragment, "pageId">>
   >();
+  // Refactor/04 Slice 4 — per-block column placement aggregated across all
+  // sections, keyed by global page index. Populated only for blocks that
+  // paginated under a multi-column layout; absent entries mean single-column.
+  const globalColumnByBlockIdByPageIndex = new Map<number, Map<string, number>>();
+  // Refactor/04 post-Slice-4 — end-column per global page, used by the
+  // next section's `nextColumn` handling to decide whether to seed
+  // section N at `prevEnd + 1` or start fresh on a new page.
+  // "End column" = the highest columnIndex any block on the page
+  // occupied. 0 on single-column pages.
+  const endColumnByGlobalPageIndex = new Map<number, number>();
   let globalPageIndex = 0;
   // A single cache lives for the whole pagination pass so cross-section
   // re-measurement (rare but possible through keepNext heuristics) still
@@ -234,7 +266,41 @@ export function buildPageStackWithSplits(
     const prevSection = sectionIdx > 0 ? sections[sectionIdx - 1] : undefined;
     const breakType = prevSection?.properties?.sectionType;
     const nextDisplayPage = globalPageIndex + 1; // 1-based
-    const isContinuous = breakType === "continuous" || breakType === "nextColumn";
+
+    // Refactor/04 post-Slice-4 — cross-section column carry. A
+    // section-level `nextColumn` break degrades by case:
+    //   - new section single-column (columns <= 1): merge like
+    //     continuous (preserves F01 + CCEP single-column regression).
+    //   - new + prev sections share a column count AND the prev
+    //     section's last page still has room: merge like continuous
+    //     AND seed the new section's starting columnIndex =
+    //     prevEndColumn + 1.
+    //   - column counts mismatch, or prev ended in the last column
+    //     (no room): behave like `nextPage` — no merge, start fresh.
+    // `continuous` sections still behave exactly as before.
+    let nextColumnSeed = 0;
+    let nextColumnDegradesToContinuous = false;
+    if (breakType === "nextColumn" && prevSection) {
+      const newColumns = layout.columns;
+      if (newColumns <= 1) {
+        nextColumnDegradesToContinuous = true;
+      } else {
+        const lastPage = pages.length > 0 ? pages[pages.length - 1] : undefined;
+        const prevColumns = lastPage?.layout.columns ?? 1;
+        if (prevColumns === newColumns && lastPage) {
+          const prevEnd = endColumnByGlobalPageIndex.get(lastPage.pageIndex) ?? 0;
+          if (prevEnd + 1 < newColumns) {
+            nextColumnDegradesToContinuous = true;
+            nextColumnSeed = prevEnd + 1;
+          }
+          // else: prev ended in last column → fall through (no merge,
+          // start fresh on new page in column 0 — matches nextPage).
+        }
+        // else: mismatched layouts → fall through (nextPage-ish).
+      }
+    }
+    const isContinuous =
+      breakType === "continuous" || nextColumnDegradesToContinuous;
 
     if (breakType === "evenPage" && globalPageIndex > 0) {
       if (nextDisplayPage % 2 !== 0) {
@@ -272,6 +338,7 @@ export function buildPageStackWithSplits(
       measurementProvider,
       cache,
       defaultTabInterval,
+      nextColumnSeed,
     );
     const paginated = paginatedResult.pages;
 
@@ -346,6 +413,31 @@ export function buildPageStackWithSplits(
       const existing = globalNoteFragmentsByPageIndex.get(globalPageIdx) ?? [];
       globalNoteFragmentsByPageIndex.set(globalPageIdx, [...existing, ...sectionFrags]);
     }
+
+    // Refactor/04 Slice 4 — merge per-section column placements into the
+    // global map. Sections that shared a page via `continuous` / `nextColumn`
+    // merging each contribute their own block ids to the same global index.
+    for (const [pageInSec, sectionCols] of paginatedResult.columnByBlockIdByPageInSection) {
+      const globalPageIdx = pageInSectionToGlobal.get(pageInSec);
+      if (globalPageIdx === undefined) continue;
+      let forPage = globalColumnByBlockIdByPageIndex.get(globalPageIdx);
+      if (!forPage) {
+        forPage = new Map<string, number>();
+        globalColumnByBlockIdByPageIndex.set(globalPageIdx, forPage);
+      }
+      for (const [blockId, col] of sectionCols) {
+        if (!forPage.has(blockId)) forPage.set(blockId, col);
+      }
+      // Refactor/04 post-Slice-4 — track the end-column per global page
+      // so the NEXT section's `nextColumn` break can decide whether to
+      // seed into this page's remaining columns or push fresh. The
+      // highest columnIndex observed on each page is the "end column".
+      let maxCol = endColumnByGlobalPageIndex.get(globalPageIdx) ?? 0;
+      for (const col of sectionCols.values()) {
+        if (col > maxCol) maxCol = col;
+      }
+      endColumnByGlobalPageIndex.set(globalPageIdx, maxCol);
+    }
   }
 
   // Guarantee at least one page
@@ -375,6 +467,9 @@ export function buildPageStackWithSplits(
     noteFragmentsByPageIndex: globalNoteFragmentsByPageIndex.size > 0
       ? globalNoteFragmentsByPageIndex
       : undefined,
+    columnByBlockIdByPageIndex: globalColumnByBlockIdByPageIndex.size > 0
+      ? globalColumnByBlockIdByPageIndex
+      : undefined,
   };
 }
 
@@ -477,6 +572,15 @@ export function buildPageStackFromWithSplits(
     return {
       pages: tailPages,
       splits: { byBlockId: tailSplits, tablesByBlockId: tailTableSplits },
+      ...(full.columnByBlockIdByPageIndex && full.columnByBlockIdByPageIndex.size > 0
+        ? {
+            columnByBlockIdByPageIndex: new Map(
+              Array.from(full.columnByBlockIdByPageIndex.entries()).filter(
+                ([pi]) => pi >= dirtyPageNumberOffset,
+              ),
+            ),
+          }
+        : {}),
     };
   }
 
@@ -539,6 +643,16 @@ export function buildPageStackFromWithSplits(
           ]),
         )
       : undefined;
+  // Refactor/04 Slice 4 — shift per-block column map in lockstep with pages.
+  const shiftedColumnByBlockId =
+    tailResult.columnByBlockIdByPageIndex && tailResult.columnByBlockIdByPageIndex.size > 0
+      ? new Map<number, ReadonlyMap<string, number>>(
+          Array.from(tailResult.columnByBlockIdByPageIndex.entries()).map(([pi, cols]) => [
+            pi + dirtyPageNumberOffset,
+            cols,
+          ]),
+        )
+      : undefined;
 
   return {
     pages: shiftedPages,
@@ -549,6 +663,9 @@ export function buildPageStackFromWithSplits(
     ...(shiftedNoteFragments !== undefined
       ? { noteFragmentsByPageIndex: shiftedNoteFragments }
       : {}),
+    ...(shiftedColumnByBlockId !== undefined
+      ? { columnByBlockIdByPageIndex: shiftedColumnByBlockId }
+      : {}),
   };
 }
 
@@ -816,7 +933,7 @@ function measureBlockHeight(
             const measured = measurementProvider.measureLineFragments({
               block,
               formatting,
-              runs: new Map(),
+              runs: buildRunFormattingMap(block),
               columnWidth,
             });
             cache?.setLineCount(block, columnWidth, measured.lineCount);
@@ -1024,12 +1141,13 @@ function measureParagraphLineCount(
     const measured = measurementProvider.measureLineFragments({
       block,
       formatting,
-      // The paginated pipeline currently resolves formatting at the
-      // paragraph level only; per-run formatting is not yet threaded
-      // through.  Pass an empty map; the provider's empirical backend
-      // does not consult per-run metrics and the canvas backend falls
-      // back to the paragraph defaults when a run is missing.
-      runs: new Map(),
+      // Per-run formatting threaded via `buildRunFormattingMap`
+      // (Task 3, 2026-04-23). The canvas backend reads
+      // `runs.get("${blockId}:${segmentId}")` for per-segment font
+      // metrics; the empirical backend ignores `runs` (paragraph-
+      // level metrics are sufficient) so the empirical numerical
+      // output is unchanged.
+      runs: buildRunFormattingMap(block),
       columnWidth,
     });
     return Math.max(1, measured.lineCount);
@@ -1158,6 +1276,12 @@ interface SectionPaginationResult {
   noteAllocationsByPageInSection: Map<number, RuntimeNoteAllocation[]>;
   /** P8.1b — per-page note body fragments keyed by pageInSection index. */
   noteFragmentsByPageInSection: Map<number, Array<Omit<RuntimeBlockFragment, "pageId">>>;
+  /**
+   * Refactor/04 Slice 4 — per-block column placement within a multi-column
+   * section. Keyed by pageInSection → (blockId → columnIndex). Absent for
+   * single-column sections; absent for note/footnote blocks.
+   */
+  columnByBlockIdByPageInSection: Map<number, Map<string, number>>;
 }
 
 /**
@@ -1193,6 +1317,16 @@ export function paginateSectionBlocksWithSplits(
   measurementProvider?: LayoutMeasurementProvider,
   cache?: MeasurementCache,
   defaultTabInterval = 720,
+  /**
+   * Refactor/04 post-Slice-4 — cross-section column carry seed. When
+   * section N starts via `<w:type w:val="nextColumn"/>` from a
+   * matching-layout previous section that ended in column K,
+   * the outer pass seeds K+1 here so section N's first block lands in
+   * the next available column rather than restarting at 0. Ignored
+   * for single-column layouts (`maxColumns <= 1`) and clamped to
+   * `[0, maxColumns-1]` defensively.
+   */
+  startColumnIndex = 0,
 ): SectionPaginationResult {
   if (blocks.length === 0) {
     return {
@@ -1208,6 +1342,7 @@ export function paginateSectionBlocksWithSplits(
       splits: { byBlockId: new Map() }, // section-local; global map includes tablesByBlockId via collectTableRowSlices
       noteAllocationsByPageInSection: new Map(),
       noteFragmentsByPageInSection: new Map(),
+      columnByBlockIdByPageInSection: new Map(),
     };
   }
 
@@ -1216,12 +1351,39 @@ export function paginateSectionBlocksWithSplits(
   const usableHeight = getUsablePageHeight(layout);
   const columnMetrics = getUsableColumnMetrics(layout);
   const maxColumns = Math.max(1, columnMetrics.length);
+  const isMultiColumn = maxColumns > 1;
   let pageStart = section.start;
   let columnHeight = 0;
-  let columnIndex = 0;
+  // Refactor/04 post-Slice-4 — seed `columnIndex` from the outer pass
+  // when a matching-layout `nextColumn` section break precedes this
+  // section. Clamp so a malformed seed can't read past `maxColumns-1`.
+  // Single-column layouts ignore the seed (there's no column to
+  // advance into).
+  let columnIndex = isMultiColumn
+    ? Math.min(Math.max(0, startColumnIndex), maxColumns - 1)
+    : 0;
   let pageInSection = 0;
   let reservedNoteHeight = 0;
   const reservedNotes = new Set<string>();
+  // Refactor/04 Slice 4 — per-block column placement. Populated only when
+  // `maxColumns > 1`; single-column sections skip the map allocation entirely
+  // so the cold path pays nothing for documents Word treats as single-column
+  // (F01 + 10 representative CCEP regression path).
+  const columnByBlockIdByPageInSection = new Map<number, Map<string, number>>();
+  const recordColumnPlacement = (blockId: string): void => {
+    if (!isMultiColumn) return;
+    let forPage = columnByBlockIdByPageInSection.get(pageInSection);
+    if (!forPage) {
+      forPage = new Map<string, number>();
+      columnByBlockIdByPageInSection.set(pageInSection, forPage);
+    }
+    // Only record the FIRST placement — paragraphs placed atomically
+    // emit one fragment; table blocks may re-enter the loop with
+    // tableProgress bumps but the block still resolves to one column.
+    if (!forPage.has(blockId)) {
+      forPage.set(blockId, columnIndex);
+    }
+  };
   // P6.c: per-table progress when a table is being split row-by-row
   // across pages.  Map<blockId, nextRowIndexToPlace>.  Cleared once a
   // table is fully placed.
@@ -1430,6 +1592,7 @@ export function paginateSectionBlocksWithSplits(
 
         // Case 1: remainder fits — place and break.
         if (remainderHeight <= remainingForTable) {
+          recordColumnPlacement(block.blockId);
           columnHeight += startRow > 0 ? remainderHeight : baseHeight;
           if (startRow > 0) tableProgress.delete(block.blockId);
           if (index === blocks.length - 1) pushPage(section.end);
@@ -1446,6 +1609,7 @@ export function paginateSectionBlocksWithSplits(
           startRow,
         });
         if (decision.rowsOnCurrentPage > 0) {
+          recordColumnPlacement(block.blockId);
           tableProgress.set(block.blockId, decision.splitRowIndex);
           pushPage(rowOffset(decision.splitRowIndex));
           continue;
@@ -1462,6 +1626,7 @@ export function paginateSectionBlocksWithSplits(
         // Case 4: degraded atomic placement (table on a fresh page that
         // it doesn't fit on, AND the first row alone exceeds page
         // height).  Preserve pre-P6.c semantics so offsets stay clean.
+        recordColumnPlacement(block.blockId);
         columnHeight += baseHeight;
         if (index === blocks.length - 1) pushPage(section.end);
         break;
@@ -1577,6 +1742,10 @@ export function paginateSectionBlocksWithSplits(
         columnWidth,
         reservedNotes,
       );
+      // Refactor/04 Slice 4 — record placement BEFORE the `hasColumnBreak`
+      // branch below advances `columnIndex`; the block itself lives in the
+      // PRE-advance column.
+      recordColumnPlacement(block.blockId);
       columnHeight += baseHeight;
       reservedNoteHeight += effectiveNoteHeight;
       currentPageNoteIds(block).forEach((noteKey) => {
@@ -1634,6 +1803,7 @@ export function paginateSectionBlocksWithSplits(
     splits: { byBlockId: splitsByBlock },
     noteAllocationsByPageInSection,
     noteFragmentsByPageInSection,
+    columnByBlockIdByPageInSection,
   };
 }
 
@@ -1682,6 +1852,11 @@ function estimateFootnoteReservation(
     const colonIdx = noteKey.indexOf(":");
     if (colonIdx === -1) continue;
     const noteKind = noteKey.slice(0, colonIdx) as "footnote" | "endnote";
+    // Endnotes flow to the document-end endnote area, not the per-page
+    // footnote area — they do not reserve page-local height. The
+    // snapshotNoteAllocations loop already skips endnotes on emission;
+    // this skip keeps the reservation math aligned.
+    if (noteKind === "endnote") continue;
     const noteId = noteKey.slice(colonIdx + 1);
     // Use measureNoteBody so reservation math and emission share the same path.
     const { heightTwips } = measureNoteBody(noteKind, noteId, footnotes, columnWidth);

package/src/runtime/layout/project-block-fragments.ts

@@ -37,6 +37,7 @@ export function projectSurfaceBlocksToPageFragments(
   surface: EditorSurfaceSnapshot,
   pages: readonly DocumentPageSnapshot[],
   splits?: BlockSplits,
+  columnByBlockIdByPageIndex?: ReadonlyMap<number, ReadonlyMap<string, number>>,
 ): Map<number, FragmentWithoutPageId[]> {
   const byPage = new Map<number, FragmentWithoutPageId[]>();
   const perPageCounter = new Map<number, number>();
@@ -59,6 +60,10 @@ export function projectSurfaceBlocksToPageFragments(
     return n;
   };
 
+  // Refactor/04 Slice 4 — per-block column placement lookup.
+  const columnIndexFor = (pageIndex: number, blockId: string): number | undefined =>
+    columnByBlockIdByPageIndex?.get(pageIndex)?.get(blockId);
+
   for (const block of surface.blocks) {
     // R3: table split across pages — emit one fragment per row slice.
     // Consumers read `tableRowRange` and prepend header rows when from > 0.
@@ -69,9 +74,11 @@ export function projectSurfaceBlocksToPageFragments(
           block,
           tableSliceList,
           (pageIndex, fragment) => {
+            const columnIndex = columnIndexFor(pageIndex, block.blockId);
             pushFragment(pageIndex, {
               ...fragment,
               orderInRegion: nextOrder(pageIndex),
+              ...(columnIndex !== undefined ? { columnIndex } : {}),
             });
           },
         );
@@ -87,9 +94,11 @@ export function projectSurfaceBlocksToPageFragments(
         block,
         sliceList,
         (pageIndex, fragment) => {
+          const columnIndex = columnIndexFor(pageIndex, block.blockId);
           pushFragment(pageIndex, {
             ...fragment,
             orderInRegion: nextOrder(pageIndex),
+            ...(columnIndex !== undefined ? { columnIndex } : {}),
           });
         },
       );
@@ -101,6 +110,7 @@ export function projectSurfaceBlocksToPageFragments(
     const pageIndex = findPageIndexForOffset(pages, block.from);
     if (pageIndex === null) continue;
 
+    const columnIndex = columnIndexFor(pageIndex, block.blockId);
     const fragment: FragmentWithoutPageId = {
       fragmentId: `fragment-${block.blockId}`,
       blockId: block.blockId,
@@ -111,6 +121,7 @@ export function projectSurfaceBlocksToPageFragments(
       heightTwips: estimateBlockHeightFromSpan(block),
       ...deriveStyleMetadata(block),
       kind: "whole",
+      ...(columnIndex !== undefined ? { columnIndex } : {}),
     };
 
     pushFragment(pageIndex, fragment);

package/src/runtime/layout/projector.ts

@@ -0,0 +1,90 @@
+/**
+ * Layer 04 — layout debug projector.
+ *
+ * Produces a `LayoutDebugEntry` for the debug-inspector snapshot when the
+ * `layout` telemetry channel is on. Architecture reference:
+ * docs/architecture/04-layout-semantics.md §"Projector and oracle surfaces".
+ *
+ * Contract with CLAUDE.md performance invariant 4:
+ *   - Callers gate the call through `bus.isEnabled("layout")` so the
+ *     cost is zero when the channel is off.
+ *   - The projector never widens the wholesale-snapshot path. It reads
+ *     four existing facet accessors (`getPageCount`, `getSections`,
+ *     `getMeasurementFidelity`, `getDirtyFieldFamilies`) and performs no
+ *     extra work beyond their return values.
+ *   - Cache warming caveat: the layout facet is lazy. If the projector
+ *     is the FIRST consumer to read `getPageCount()` on a runtime that
+ *     has never paginated, the underlying engine will run `fullRebuild`
+ *     as part of that call — this is the engine's documented lazy
+ *     behavior, not something the projector causes. A SECOND projector
+ *     call on the same facet is idempotent and adds no commit (see
+ *     `test/runtime/layout/projector-on-demand.test.ts`). In real
+ *     sessions the debug snapshot is invoked after the shell has already
+ *     mounted and read the facet, so the cold-path cost does not fall
+ *     on the debug path.
+ *
+ * The entry is intentionally small. Slice 3 ships the page-count +
+ * section-count + measurement-fidelity + dirty-fields summary plus the
+ * `LAYOUT_ENGINE_VERSION` discriminator so traces from different engine
+ * builds are distinguishable. Slice 4 (multi-column `nextColumn`) adds
+ * per-page column counts.
+ */
+
+import type { LayoutFacet } from "./layout-facet-types.ts";
+import { LAYOUT_ENGINE_VERSION } from "./layout-engine-version.ts";
+import type { DocumentSettings } from "../../model/canonical-document.ts";
+import {
+  resolveLayoutCompatInputs,
+  type LayoutCompatInputs,
+} from "./compat-input-ledger.ts";
+
+export interface LayoutDebugEntry {
+  readonly schemaVersion: 2;
+  /**
+   * `LAYOUT_ENGINE_VERSION` at projection time. Traces from different
+   * engine builds are distinguishable; persisted prerender caches key on
+   * this constant so its value at projection time is a reliable
+   * discriminator.
+   */
+  readonly engineVersion: number;
+  readonly pageCount: number;
+  readonly sectionCount: number;
+  readonly measurementFidelity: string;
+  readonly dirtyFieldFamilies: readonly string[];
+  /**
+   * Task 5 (2026-04-23) — compat-input ledger. Surfaces which
+   * pre-2013/legacy compat flags + `<w:compatSetting>` entries are
+   * active on the document so operators can tell at a glance which
+   * compat-conditional branches would fire. Absent when the document
+   * settings are unavailable (debug projection can be taken against a
+   * facet without an accompanying `DocumentSettings`).
+   */
+  readonly compatInputs?: LayoutCompatInputs;
+}
+
+export interface BuildLayoutDebugEntryInputs {
+  readonly facet: LayoutFacet;
+  /**
+   * Task 5 — when supplied, the projector resolves and attaches
+   * `compatInputs`. Optional so existing callers that never plumbed
+   * settings through continue working unchanged.
+   */
+  readonly settings?: DocumentSettings;
+}
+
+export function buildLayoutDebugEntry(
+  inputs: BuildLayoutDebugEntryInputs,
+): LayoutDebugEntry {
+  const { facet, settings } = inputs;
+  return {
+    schemaVersion: 2,
+    engineVersion: LAYOUT_ENGINE_VERSION,
+    pageCount: facet.getPageCount(),
+    sectionCount: facet.getSections().length,
+    measurementFidelity: facet.getMeasurementFidelity(),
+    dirtyFieldFamilies: facet.getDirtyFieldFamilies(),
+    ...(settings !== undefined
+      ? { compatInputs: resolveLayoutCompatInputs(settings) }
+      : {}),
+  };
+}