@beyondwork/docx-react-component 1.0.42 → 1.0.45

package/src/runtime/render/render-kernel.ts

@@ -17,7 +17,10 @@ import { MAIN_STORY_TARGET } from "../../core/selection/mapping.ts";
 import { recordPerfSample } from "../../ui-tailwind/editor-surface/perf-probe.ts";
 import type { EditorStoryTarget } from "../../api/public-types";
 import type {
+  PublicBlockFragment,
   PublicPageNode,
+  PublicPageRegion,
+  PublicRegionBlock,
   WordReviewEditorLayoutFacet,
 } from "../layout/public-facet.ts";
 import type {
@@ -305,6 +308,7 @@ function buildPage(
       zoom,
       "header",
       page.stories.header,
+      facet,
     );
   }
   if (page.stories.footer) {
@@ -314,9 +318,18 @@ function buildPage(
       zoom,
       "footer",
       page.stories.footer,
+      facet,
     );
   }
 
+  const footnoteRegions = buildFootnoteRegions(page, topPx, zoom, facet);
+  if (footnoteRegions.length > 0) {
+    regions.footnotes = footnoteRegions;
+  }
+  // Endnotes intentionally skipped — per-page endnote projection is not
+  // populated; endnotes use document-end placement via
+  // `facet.getDocumentEndnoteBlocks()`.
+
   const chromeReservations: PageChromeReservations = {
     ...defaultChromeReservations(layout, zoom),
   };
@@ -440,51 +453,181 @@ function buildHeaderFooterRegion(
   zoom: RenderZoom,
   kind: "header" | "footer",
   storyTarget: EditorStoryTarget,
+  facet: WordReviewEditorLayoutFacet,
 ): RenderStoryRegion {
   const layout = page.layout;
-  const widthTwips =
+  const fallbackWidthTwips =
     layout.pageWidth - layout.marginLeft - layout.marginRight;
-  let topTwips = 0;
-  let heightTwips = 0;
-  if (kind === "header") {
-    topTwips = layout.headerMargin ?? 720;
-    heightTwips = Math.max(0, layout.marginTop - topTwips);
-  } else {
-    topTwips = layout.pageHeight - layout.marginBottom;
-    heightTwips = Math.max(0, layout.marginBottom - (layout.footerMargin ?? 720));
-  }
+  const fallbackTopTwips =
+    kind === "header"
+      ? (layout.headerMargin ?? 720)
+      : layout.pageHeight - layout.marginBottom;
+  const fallbackHeightTwips =
+    kind === "header"
+      ? Math.max(0, layout.marginTop - (layout.headerMargin ?? 720))
+      : Math.max(0, layout.marginBottom - (layout.footerMargin ?? 720));
+
+  const region: PublicPageRegion =
+    (kind === "header" ? page.regions.header : page.regions.footer) ?? {
+      kind,
+      originTwips: fallbackTopTwips,
+      widthTwips: fallbackWidthTwips,
+      heightTwips: fallbackHeightTwips,
+      fragmentCount: 0,
+    };
 
   const frame: RenderFrameRect = {
     leftPx: layout.marginLeft * zoom.pxPerTwip,
-    topPx: pageTopPx + topTwips * zoom.pxPerTwip,
-    widthPx: widthTwips * zoom.pxPerTwip,
-    heightPx: heightTwips * zoom.pxPerTwip,
+    topPx: pageTopPx + region.originTwips * zoom.pxPerTwip,
+    widthPx: region.widthTwips * zoom.pxPerTwip,
+    heightPx: region.heightTwips * zoom.pxPerTwip,
   };
 
-  const region = kind === "header" ? page.regions.header : page.regions.footer;
-  if (!region) {
-    return {
-      storyTarget,
-      region: {
-        kind,
-        originTwips: topTwips,
-        widthTwips,
-        heightTwips,
-        fragmentCount: 0,
-      },
-      frame,
-      blocks: [],
-    };
-  }
+  const regionBlocks = facet.getStoryBlocksForRegion(page.pageIndex, kind);
+  const blocks = projectRegionBlocks(
+    regionBlocks,
+    frame,
+    zoom.pxPerTwip,
+    page.pageId,
+    page.pageIndex,
+    kind,
+  );
 
   return {
     storyTarget,
     region,
     frame,
-    blocks: [],
+    blocks,
   };
 }
 
+/**
+ * P8.3 — Build one `RenderStoryRegion` per `page.regions.footnotes` entry.
+ * The page graph reserves footnote regions at the bottom of the page
+ * (above the footer band) when `noteAllocations` produced fragments.
+ * Blocks come from `facet.getStoryBlocksForRegion(pageIndex, "footnote-area")`
+ * — one entry per allocated note body, stacked vertically.
+ *
+ * Currently the page graph emits a single footnote region per page
+ * covering every allocation, so the returned array has length 0 or 1. The
+ * shape allows for future allocation-splitting without changing the
+ * render-kernel contract.
+ */
+function buildFootnoteRegions(
+  page: PublicPageNode,
+  pageTopPx: number,
+  zoom: RenderZoom,
+  facet: WordReviewEditorLayoutFacet,
+): RenderStoryRegion[] {
+  const footnoteRegions = page.regions.footnotes;
+  if (!footnoteRegions || footnoteRegions.length === 0) return [];
+
+  const regionBlocks = facet.getStoryBlocksForRegion(
+    page.pageIndex,
+    "footnote-area",
+  );
+  if (regionBlocks.length === 0) return [];
+
+  const results: RenderStoryRegion[] = [];
+  // Today the runtime emits a single footnote-area region per page; if that
+  // ever changes we will split `regionBlocks` across each region entry's
+  // `fragmentCount`.  Preserve the shape so consumers can iterate safely.
+  let cursor = 0;
+  for (const region of footnoteRegions) {
+    const frame: RenderFrameRect = {
+      leftPx: page.layout.marginLeft * zoom.pxPerTwip,
+      topPx: pageTopPx + region.originTwips * zoom.pxPerTwip,
+      widthPx: region.widthTwips * zoom.pxPerTwip,
+      heightPx: region.heightTwips * zoom.pxPerTwip,
+    };
+
+    const blocksForThisRegion =
+      footnoteRegions.length === 1
+        ? regionBlocks
+        : regionBlocks.slice(cursor, cursor + region.fragmentCount);
+    cursor += region.fragmentCount;
+
+    const blocks = projectRegionBlocks(
+      blocksForThisRegion,
+      frame,
+      zoom.pxPerTwip,
+      page.pageId,
+      page.pageIndex,
+      "footnote-area",
+    );
+
+    // Footnote regions don't have a single canonical storyTarget (each
+    // block belongs to a different footnote body).  Pick the first block's
+    // note as the region's primary story when available so chrome surfaces
+    // keyed on `storyTarget.kind === "footnote"` can dispatch on the band.
+    const firstNote = page.noteAllocations.find(
+      (alloc) => alloc.noteKind === "footnote",
+    );
+    const storyTarget: EditorStoryTarget = firstNote
+      ? { kind: "footnote", noteId: firstNote.noteId }
+      : MAIN_STORY_TARGET;
+
+    results.push({
+      storyTarget,
+      region,
+      frame,
+      blocks,
+    });
+  }
+
+  return results;
+}
+
+/**
+ * P8.3 — Stack a `PublicRegionBlock[]` into `RenderBlock[]` inside the
+ * given region frame.  The cursor starts at `regionFrame.topPx` and
+ * advances by each block's `heightTwips × pxPerTwip`.  Synthesizes a
+ * `PublicBlockFragment` shape for each block so chrome surfaces reading
+ * `RenderBlock.fragment` see a consistent shape across body / header /
+ * footer / footnote-area regions.
+ */
+function projectRegionBlocks(
+  regionBlocks: readonly PublicRegionBlock[],
+  regionFrame: RenderFrameRect,
+  pxPerTwip: number,
+  pageId: string,
+  pageIndex: number,
+  regionKind: PublicPageRegion["kind"],
+): RenderBlock[] {
+  const blocks: RenderBlock[] = [];
+  let y = regionFrame.topPx;
+  for (let i = 0; i < regionBlocks.length; i += 1) {
+    const regionBlock = regionBlocks[i]!;
+    const blockHeightPx = Math.max(0, regionBlock.heightTwips) * pxPerTwip;
+    const blockFrame: RenderFrameRect = {
+      leftPx: regionFrame.leftPx,
+      topPx: y,
+      widthPx: regionFrame.widthPx,
+      heightPx: blockHeightPx,
+    };
+    const fragment: PublicBlockFragment = {
+      fragmentId: regionBlock.fragmentId,
+      blockId: regionBlock.blockId,
+      pageId,
+      pageIndex,
+      regionKind,
+      from: regionBlock.runtimeFromOffset,
+      to: regionBlock.runtimeToOffset,
+      heightTwips: regionBlock.heightTwips,
+      orderInRegion: i,
+    };
+    blocks.push({
+      fragment,
+      frame: blockFrame,
+      kind: classifyBlockKindFromId(regionBlock.blockId),
+      lines: [],
+      blockDecorations: [],
+    });
+    y += blockHeightPx;
+  }
+  return blocks;
+}
+
 // classifyBlockKind moved to `./block-fragment-projection.ts` (P4).
 
 function buildAnchorIndex(

package/src/runtime/selection/post-edit-validator.ts

@@ -0,0 +1,77 @@
+import type { CanonicalDocumentEnvelope } from "../../core/state/editor-state.ts";
+import type { SelectionSnapshot } from "../../core/state/editor-state.ts";
+
+/**
+ * Snap a selection to a valid position relative to the document.
+ *
+ * Pure function.  O(1) on the identity (in-bounds) fast path — returns
+ * the SAME object reference when no change is needed.  Callers should
+ * compare with `!==` to detect a snap (e.g. to decide whether to
+ * re-spread runtime state).
+ *
+ * Wired into the runtime snapshot-emit chokepoint
+ * (`applyTransactionToState` -> `cachedRenderSnapshot = refreshRenderSnapshot()`),
+ * so it runs once per transaction commit.  Must NOT walk the document;
+ * the caller is responsible for passing a valid `maxOffset` (the
+ * POST-mutation `surface.storySize`, primed via
+ * `getCachedSurface(state.document, activeStory).storySize`).
+ *
+ * NodeAnchor invalidation is deferred until CanonicalDocumentEnvelope
+ * grows an O(1) node-by-id accessor.  Until then, NodeAnchor selections
+ * are returned unchanged (identity).
+ *
+ * @param document   The post-mutation canonical document.  Currently
+ *                   unused except for the deferred NodeAnchor branch;
+ *                   the parameter is kept for API stability.
+ * @param selection  The selection to validate.
+ * @param maxOffset  The POST-mutation maximum story offset.  Caller
+ *                   passes `getCachedSurface(state.document,
+ *                   activeStory).storySize` (which primes the cache
+ *                   that `refreshRenderSnapshot` reuses on its next
+ *                   call — no extra surface walk).  The validator does
+ *                   NOT walk the document to compute this.  Do NOT pass
+ *                   the pre-mutation snapshot's storySize: at end-of-doc
+ *                   inserts, the new selection legitimately exceeds the
+ *                   old bound and the validator would clamp the caret
+ *                   backward by one position per keystroke.  Pass
+ *                   `Number.POSITIVE_INFINITY` to skip the upper-bound
+ *                   clamp.
+ */
+export function validateSelectionAgainstDocument(
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars -- reserved for deferred NodeAnchor lookup
+  document: CanonicalDocumentEnvelope,
+  selection: SelectionSnapshot,
+  maxOffset: number,
+): SelectionSnapshot {
+  if (selection.activeRange.kind === "node") {
+    // Deferred: NodeAnchor invalidation requires an O(1) node-by-id
+    // accessor on CanonicalDocumentEnvelope.  Until that lands, return
+    // identity so we never falsely invalidate a still-valid node anchor.
+    return selection;
+  }
+
+  const anchor = clamp(selection.anchor, 0, maxOffset);
+  const head = clamp(selection.head, 0, maxOffset);
+
+  if (anchor === selection.anchor && head === selection.head) {
+    // Identity fast path — no allocation, same reference returned.
+    return selection;
+  }
+
+  const range = { from: Math.min(anchor, head), to: Math.max(anchor, head) };
+  const assoc =
+    selection.activeRange.kind === "range"
+      ? selection.activeRange.assoc
+      : { start: 1 as const, end: 1 as const };
+
+  return {
+    anchor,
+    head,
+    isCollapsed: anchor === head,
+    activeRange: { kind: "range", range, assoc },
+  };
+}
+
+function clamp(n: number, lo: number, hi: number): number {
+  return n < lo ? lo : n > hi ? hi : n;
+}

package/src/runtime/surface-projection.ts

@@ -68,11 +68,17 @@ interface ParagraphAccumulator {
   segments: SurfaceInlineSegment[];
 }
 
+export interface SurfaceProjectionOptions {
+  viewportBlockRange?: { start: number; end: number } | null;
+}
+
 export function createEditorSurfaceSnapshot(
   document: CanonicalDocumentEnvelope,
   _selection: SelectionSnapshot,
   activeStory: EditorStoryTarget = { kind: "main" },
+  options: SurfaceProjectionOptions = {},
 ): EditorSurfaceSnapshot {
+  const viewportBlockRange = options.viewportBlockRange ?? null;
   const root = normalizeDocumentRoot({
     type: "doc",
     children: [...getStoryBlocks(document, activeStory)],
@@ -99,15 +105,41 @@ export function createEditorSurfaceSnapshot(
       numberingPrefixResolver,
       activeStory.kind !== "main",
     );
-    blocks.push(surfaceBlock.block);
-    lockedFragmentIds.push(...surfaceBlock.lockedFragmentIds);
+    const isInViewport =
+      viewportBlockRange === null ||
+      (index >= viewportBlockRange.start && index < viewportBlockRange.end);
+
+    if (isInViewport) {
+      blocks.push(surfaceBlock.block);
+      lockedFragmentIds.push(...surfaceBlock.lockedFragmentIds);
+    } else {
+      // Replace with size-preserving placeholder. from/to track the SAME
+      // position range as the real block, so selection and anchor stability
+      // outside the viewport is preserved.
+      const placeholderSize = surfaceBlock.nextCursor - cursor;
+      const placeholderBlockId = `placeholder-culled-${index}`;
+      blocks.push({
+        blockId: placeholderBlockId,
+        kind: "opaque_block",
+        from: cursor,
+        to: surfaceBlock.nextCursor,
+        fragmentId: placeholderBlockId,
+        warningId: placeholderBlockId,
+        label: "",
+        detail: "",
+        placeholderSize,
+        state: "placeholder-culled",
+      } as SurfaceBlockSnapshot);
+      // Do NOT push lockedFragmentIds — placeholder has no real fragment.
+    }
+
     cursor = surfaceBlock.nextCursor;
     if (index < root.children.length - 1 && root.children[index + 1]?.type === "paragraph") {
       cursor += 1;
     }
   }
 
-  const secondaryStories = createSecondaryStorySurfaces(document);
+  const secondaryStories = createSecondaryStorySurfaces(document, numberingPrefixResolver);
 
   return {
     storySize: cursor,
@@ -115,6 +147,7 @@ export function createEditorSurfaceSnapshot(
     blocks,
     lockedFragmentIds,
     secondaryStories,
+    viewportBlockRange,
   };
 }
 
@@ -886,9 +919,13 @@ function appendInlineSegments(
       return { nextCursor: start + 1, lockedFragmentIds: [node.fragmentId] };
     }
     case "chart_preview":
-      return appendComplexPreviewSegment(paragraph, node, start, "Embedded chart", createChartDetail(node));
+      return appendComplexPreviewSegment(paragraph, node, start, "Embedded chart", createChartDetail(node), {
+        previewMediaId: node.previewMediaId,
+      });
     case "smartart_preview":
-      return appendComplexPreviewSegment(paragraph, node, start, "SmartArt diagram", createSmartArtDetail(node));
+      return appendComplexPreviewSegment(paragraph, node, start, "SmartArt diagram", createSmartArtDetail(node), {
+        previewMediaId: node.previewMediaId,
+      });
     case "shape":
       if (promoteSecondaryStoryTextBoxes && node.isTextBox && node.text) {
         return appendTextBoxSegment(
@@ -1023,6 +1060,7 @@ function appendComplexPreviewSegment(
   start: number,
   label: string,
   detail: string,
+  extras: { previewMediaId?: string } = {},
 ): { nextCursor: number; lockedFragmentIds: string[] } {
   paragraph.segments.push({
     segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
@@ -1033,6 +1071,7 @@ function appendComplexPreviewSegment(
     warningId: `warning:complex-preview:${start}`,
     label,
     detail,
+    ...(extras.previewMediaId ? { previewMediaId: extras.previewMediaId } : {}),
     state: "locked-preserve-only",
   });
   return { nextCursor: start + 1, lockedFragmentIds: [] };
@@ -1174,6 +1213,7 @@ function createPlainText(
 
 function createSecondaryStorySurfaces(
   document: CanonicalDocumentEnvelope,
+  numberingPrefixResolver: NumberingPrefixResolver,
 ): SecondaryStorySurface[] {
   const surfaces: SecondaryStorySurface[] = [];
   const subParts = document.subParts;
@@ -1181,8 +1221,6 @@ function createSecondaryStorySurfaces(
     return surfaces;
   }
 
-  const numberingPrefixResolver = createNumberingPrefixResolver(document.numbering);
-
   for (const section of collectSectionContexts(document)) {
     const headerVariants = resolveSectionVariants(
       "header",

package/src/runtime/workflow-markup.ts

@@ -22,28 +22,32 @@ import type {
   WorkflowCommentMarkup,
 } from "../api/public-types";
 import { MAIN_STORY_TARGET } from "../core/selection/mapping.ts";
-import { searchSurfaceBlocks } from "../core/search/search-text.ts";
+import {
+  projectSurfaceText,
+  searchProjectedSurfaceText,
+} from "../core/search/search-text.ts";
 import { describeOpaqueFragment, isBlockedImportFeatureKey } from "../preservation/store.ts";
 import type { CanonicalDocumentEnvelope } from "../core/state/editor-state.ts";
 
-export function collectWorkflowMarkupSnapshot(input: {
-  renderSnapshot: RuntimeRenderSnapshot;
-  fieldSnapshot: FieldSnapshot;
-  protectionSnapshot: ProtectionSnapshot;
-  preservation: CanonicalDocumentEnvelope["preservation"];
-  workflowMetadataSnapshot?: WorkflowMetadataSnapshot;
-}): WorkflowMarkupSnapshot {
+/**
+ * Surface-derived markup (highlights + block-level opaque fragments).
+ *
+ * Pure function of `(surface, preservation)` — extracted from
+ * `collectWorkflowMarkupSnapshot` so callers can cache the expensive walk
+ * separately from the cheap reference-equal inputs (metadata, comments,
+ * revisions, protected ranges).
+ */
+export function collectWorkflowSurfaceMarkup(
+  surface: RuntimeRenderSnapshot["surface"],
+  preservation: CanonicalDocumentEnvelope["preservation"],
+): { highlights: WorkflowHighlightMarkup[]; opaqueFragments: WorkflowOpaqueFragmentMarkup[] } {
   const highlights: WorkflowHighlightMarkup[] = [];
-  const metadata = collectWorkflowMetadataMarkup(input.workflowMetadataSnapshot);
-  const fields: WorkflowFieldMarkup[] = [];
   const opaqueFragments: WorkflowOpaqueFragmentMarkup[] = [];
-  const surface = input.renderSnapshot.surface;
-
   if (surface) {
     collectSurfaceMarkup(
       surface.blocks,
       MAIN_STORY_TARGET,
-      input.preservation,
+      preservation,
       highlights,
       opaqueFragments,
     );
@@ -51,16 +55,55 @@ export function collectWorkflowMarkupSnapshot(input: {
       collectSurfaceMarkup(
         story.blocks,
         story.target,
-        input.preservation,
+        preservation,
         highlights,
         opaqueFragments,
       );
     }
+  }
+  return { highlights, opaqueFragments };
+}
 
+export function collectWorkflowMarkupSnapshot(input: {
+  renderSnapshot: RuntimeRenderSnapshot;
+  fieldSnapshot: FieldSnapshot;
+  protectionSnapshot: ProtectionSnapshot;
+  preservation: CanonicalDocumentEnvelope["preservation"];
+  workflowMetadataSnapshot?: WorkflowMetadataSnapshot;
+  surfaceMarkupCache?: {
+    highlights: WorkflowHighlightMarkup[];
+    opaqueFragments: WorkflowOpaqueFragmentMarkup[];
+  };
+  perfStage?: (name: string, durationMs: number) => void;
+}): WorkflowMarkupSnapshot {
+  const perf = input.perfStage;
+  const stageStart = perf ? () => performance.now() : () => 0;
+  const stageEnd = perf ? (name: string, t0: number) => perf(name, performance.now() - t0) : () => {};
+
+  const tMeta = stageStart();
+  const metadata = collectWorkflowMetadataMarkup(input.workflowMetadataSnapshot);
+  stageEnd("metadata", tMeta);
+
+  const fields: WorkflowFieldMarkup[] = [];
+  const surface = input.renderSnapshot.surface;
+
+  const tSurface = stageStart();
+  const surfaceMarkup = input.surfaceMarkupCache ??
+    collectWorkflowSurfaceMarkup(surface, input.preservation);
+  const highlights = surfaceMarkup.highlights.slice();
+  const opaqueFragments = surfaceMarkup.opaqueFragments.slice();
+  stageEnd("surface", tSurface);
+
+  if (surface) {
+    const tFields = stageStart();
     fields.push(...collectFieldMarkup(surface, input.fieldSnapshot));
+    stageEnd("fields", tFields);
   }
+  const tOpaqueRest = stageStart();
   opaqueFragments.push(...collectOpaqueFragmentMarkup(input.preservation, opaqueFragments));
+  stageEnd("opaqueRest", tOpaqueRest);
 
+  const tCommentsEtc = stageStart();
   const comments = input.renderSnapshot.comments.threads.map((thread): WorkflowCommentMarkup => ({
     markupId: `comment:${thread.commentId}`,
     kind: "comment",
@@ -113,6 +156,8 @@ export function collectWorkflowMarkupSnapshot(input: {
       }),
     );
 
+  stageEnd("commentsEtc", tCommentsEtc);
+
   const items: WorkflowMarkupItem[] = [
     ...highlights,
     ...metadata,
@@ -303,11 +348,21 @@ function collectFieldMarkup(
     return [];
   }
 
+  // L7 Phase 1.5: project each story's text once up-front. The prior code
+  // called searchSurfaceBlocks per field, which re-projected the entire
+  // surface on every invocation. For the CCEP large-tables fixture this
+  // was ~220 ms per commit. Hoisting the projection out of the per-field
+  // loop collapses that to a single projection per story.
   const stories = [
-    { blocks: surface.blocks, storyTarget: MAIN_STORY_TARGET },
+    {
+      blocks: surface.blocks,
+      storyTarget: MAIN_STORY_TARGET,
+      projection: projectSurfaceText(surface.blocks),
+    },
     ...surface.secondaryStories.map((story) => ({
       blocks: story.blocks,
       storyTarget: story.target,
+      projection: projectSurfaceText(story.blocks),
     })),
   ];
 
@@ -318,7 +373,7 @@ function collectFieldMarkup(
     }
 
     for (const story of stories) {
-      const matches = searchSurfaceBlocks(story.blocks, displayText, { limit: 2 });
+      const matches = searchProjectedSurfaceText(story.projection, displayText, { limit: 2 });
       if (matches.length === 1) {
         const match = matches[0]!;
         return [