@beyondwork/docx-react-component 1.0.38 → 1.0.40

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

@@ -42,6 +42,7 @@ import type {
   LayoutEngineInstance,
   LayoutEngineQueryInput,
 } from "./layout-engine-instance.ts";
+import type { LayoutMeasurementProvider } from "./layout-measurement-provider.ts";
 import type { PageFragmentMapper } from "./page-fragment-mapper.ts";
 import {
   PAGE_FORMAT_CATALOG,
@@ -56,6 +57,7 @@ import {
   type ActiveMarginPreset,
 } from "./margin-preset-catalog.ts";
 import {
+  attachScopeCardModel,
   collectScopeRailSegments,
   type ScopeRailSegment,
 } from "../workflow-rail-segments.ts";
@@ -64,6 +66,7 @@ import { MAIN_STORY_TARGET } from "../../core/selection/mapping.ts";
 import { createSelectionSnapshot } from "../../core/state/editor-state.ts";
 import { resolveTableStyleResolution } from "../table-style-resolver.ts";
 import { buildTableRenderPlan } from "./table-render-plan.ts";
+import { recordPerfSample } from "../../ui-tailwind/editor-surface/perf-probe.ts";
 import type {
   SurfaceBlockSnapshot,
 } from "../../api/public-types";
@@ -390,12 +393,48 @@ export interface WordReviewEditorLayoutFacet {
   /** Return every scope rail segment across the document. */
   getAllScopeRailSegments(): readonly import("../workflow-rail-segments.ts").ScopeRailSegment[];
 
+  /**
+   * Scope-card projection consumed by the chrome overlay's card layer
+   * (scope-card-overlay P1).  Joins every unique scope segment with
+   * its attached issue metadata (R2 `ISSUE_METADATA_ID`), its
+   * work-item id, and its `primaryAnchorRect` via the render kernel's
+   * anchor index.  P2 fields (`suggestionGroupIds`,
+   * `reviewActionCount`, `agentPending`) are defaulted to empty /
+   * zero / false in P1 and populated by later phases.
+   *
+   * Returns an empty list when no workflow rail input has been wired
+   * or when no scopes are currently on the active story.
+   */
+  getAllScopeCardModels(): readonly import("../../api/public-types.ts").ScopeCardModel[];
+
   // Measurement exposure -------------------------------------------------
   getResolvedFormatting(blockId: string): PublicResolvedParagraphFormatting | null;
   getResolvedRunFormatting(runId: string): PublicResolvedRunFormatting | null;
   getMeasurement(blockId: string): PublicBlockMeasurement | null;
   getMeasurementFidelity(): PublicMeasurementFidelity;
   whenMeasurementReady(): Promise<void>;
+  swapMeasurementProvider(provider: LayoutMeasurementProvider): void;
+
+  // Table render plan (P3e consumed by the render kernel, P4) ------------
+  /**
+   * 0-based page index where the first fragment of `blockId` lands, or
+   * `null` when the block has no fragments in the current page graph.
+   * Used by the tables facet to determine which page to request plans for
+   * without needing PM document offsets.
+   */
+  getFirstPageIndexForBlock(blockId: string): number | null;
+  /**
+   * Build a `TableRenderPlan` for a table block on a given page. Returns
+   * `null` when the blockId does not resolve to a table in the current
+   * surface. The plan carries columnsTwips, bandClasses, verticalMerges,
+   * repeatedHeaderRows, and columnResizeHandles so chrome can render
+   * band-aware cell styling and place column-resize grips without
+   * walking canonical state.
+   */
+  getTableRenderPlan(
+    blockId: string,
+    pageIndex: number,
+  ): import("./table-render-plan.ts").TableRenderPlan | null;
 
   // Table render plan (P3e consumed by the render kernel, P4) ------------
   /**
@@ -447,6 +486,17 @@ export interface CreateLayoutFacetInput {
       >
     | null
     | undefined;
+  /**
+   * Optional workflow-metadata accessor for scope-card issue resolution
+   * (R2 / scope-card-overlay P1).  Returns the
+   * `WorkflowMarkupSnapshot.metadata` array so `getAllScopeCardModels`
+   * can attach issue values to their scopes.  Omit when the host does
+   * not push metadata entries.
+   */
+  getWorkflowMarkupMetadata?: () =>
+    | readonly import("../../api/public-types.ts").WorkflowMetadataMarkup[]
+    | null
+    | undefined;
 }
 
 export function createLayoutFacet(
@@ -659,8 +709,11 @@ export function createLayoutFacet(
     hitTest(pointInRoot) {
       const kernel = input.renderKernel?.();
       if (!kernel) return null;
+      const t0 = typeof performance !== "undefined" ? performance.now() : 0;
       const frame = kernel.getRenderFrame();
-      return resolveHitTest(frame, pointInRoot);
+      const result = resolveHitTest(frame, pointInRoot);
+      if (t0 > 0) recordPerfSample("chrome.hit_test", performance.now() - t0);
+      return result;
     },
 
     getAnchorRects(query) {
@@ -684,6 +737,21 @@ export function createLayoutFacet(
       );
     },
 
+    getAllScopeCardModels() {
+      const railInput = input.getWorkflowRailInput?.();
+      const segments = collectScopeRailSegmentsForQuery(railInput, currentGraph());
+      if (segments.length === 0) return [];
+      const kernel = input.renderKernel?.();
+      const anchorIndex = kernel?.getRenderFrame?.()?.anchorIndex ?? null;
+      const metadata = input.getWorkflowMarkupMetadata?.();
+      return attachScopeCardModel({
+        segments,
+        scopes: railInput?.scopes ?? [],
+        metadata: metadata ?? undefined,
+        anchorIndex,
+      });
+    },
+
     getFragmentsForPage(pageIndex) {
       const graph = currentGraph();
       const node = graph.pages[pageIndex];
@@ -736,6 +804,18 @@ export function createLayoutFacet(
       return engine.whenMeasurementReady();
     },
 
+    getFirstPageIndexForBlock(blockId) {
+      const graph = currentGraph();
+      const fragment = graph.fragments.find((f) => f.blockId === blockId);
+      if (!fragment) return null;
+      const page = graph.pages.find((p) => p.pageId === fragment.pageId);
+      return page?.pageIndex ?? null;
+    },
+
+    swapMeasurementProvider(provider) {
+      engine.swapMeasurementProvider(provider);
+    },
+
     getTableRenderPlan(blockId, pageIndex) {
       const graph = currentGraph();
       const fragment = graph.fragments.find((f) => f.blockId === blockId);

package/src/runtime/layout/resolve-page-fields.ts

@@ -0,0 +1,70 @@
+/**
+ * Resolve `PAGE` and `NUMPAGES` field values per page.
+ *
+ * These two field families (now in `SupportedFieldFamily`) compute differently
+ * from `REF` / `PAGEREF` because the resolved value depends on the *owning
+ * page* of each header/footer instance, not on a single document-level
+ * computation.  A header part is shared across many pages; the same PAGE
+ * field must render "1" on page 1, "2" on page 2, and so on.
+ *
+ * The resolver is a pure function over the page graph — no DOM, no side
+ * effects.  Consumers (per-page header/footer bands) call
+ * `resolvePageFieldDisplayText` at render time to substitute the cached
+ * preserve-only text that currently sits inside the paragraph inline atom.
+ */
+
+import type { RuntimePageGraph, RuntimePageNode } from "./page-graph.ts";
+import type { SupportedFieldFamily } from "../../model/canonical-document.ts";
+
+export interface PageFieldContext {
+  /** The page this header/footer copy renders on. */
+  page: RuntimePageNode;
+  /** The graph the page belongs to (for NUMPAGES resolution). */
+  graph: RuntimePageGraph;
+}
+
+/**
+ * Resolve the display text for a PAGE / NUMPAGES field on a specific page.
+ *
+ * Returns the original cached `displayText` for unsupported families so the
+ * caller can use this as a single resolution helper.
+ */
+export function resolvePageFieldDisplayText(
+  family: SupportedFieldFamily | string,
+  cachedDisplayText: string,
+  context: PageFieldContext,
+): string {
+  switch (family) {
+    case "PAGE":
+      return String(context.page.stories.displayPageNumber);
+    case "NUMPAGES":
+      // Blank fillers (evenPage/oddPage section breaks) don't count toward
+      // NUMPAGES — the graph already excludes them from contentPageCount.
+      return String(context.graph.contentPageCount);
+    default:
+      return cachedDisplayText;
+  }
+}
+
+/**
+ * Build a lookup keyed by pageId → (fieldFamily → resolvedText).  Useful when
+ * a renderer wants to bulk-resolve every page's fields before emitting DOM.
+ * Absent keys mean no override; the cached field text should be used.
+ */
+export function buildPageFieldResolutionTable(
+  graph: RuntimePageGraph,
+  families: ReadonlySet<string> = new Set(["PAGE", "NUMPAGES"]),
+): Map<string, Map<string, string>> {
+  const result = new Map<string, Map<string, string>>();
+  for (const page of graph.pages) {
+    const perPage = new Map<string, string>();
+    for (const family of families) {
+      perPage.set(
+        family,
+        resolvePageFieldDisplayText(family, "", { page, graph }),
+      );
+    }
+    result.set(page.pageId, perPage);
+  }
+  return result;
+}

package/src/runtime/layout/resolve-page-previews.ts

@@ -0,0 +1,185 @@
+/**
+ * Flatten header/footer sub-part blocks to short text previews with PAGE /
+ * NUMPAGES fields resolved for the owning page.  Used by the in-flow page
+ * chrome widgets so the bands show live content ("Page 3 of 5") rather
+ * than a static "Header" / "Footer" placeholder.
+ *
+ * This is a **preview**, not a full renderer — we flatten to plain text
+ * and cap the length.  A per-page band is ~32 px tall; anything more
+ * elaborate belongs to the full editing path, which is entered by double-
+ * clicking the band.
+ */
+
+import type {
+  BlockNode,
+  HeaderDocument,
+  FooterDocument,
+  InlineNode,
+} from "../../model/canonical-document.ts";
+import type {
+  RuntimePageGraph,
+  RuntimePageNode,
+} from "./page-graph.ts";
+import { resolvePageFieldDisplayText } from "./resolve-page-fields.ts";
+
+const MAX_PREVIEW_CHARS = 140;
+
+export interface PagePreviewMaps {
+  /** pageId → short text preview of the resolved header story (if any). */
+  headerPreviewByPageId: Map<string, string>;
+  /** pageId → short text preview of the resolved footer story (if any). */
+  footerPreviewByPageId: Map<string, string>;
+}
+
+export function buildPagePreviewMaps(
+  graph: RuntimePageGraph,
+  subParts: {
+    headers?: ReadonlyArray<HeaderDocument>;
+    footers?: ReadonlyArray<FooterDocument>;
+  },
+): PagePreviewMaps {
+  const headerPreviewByPageId = new Map<string, string>();
+  const footerPreviewByPageId = new Map<string, string>();
+
+  for (const page of graph.pages) {
+    if (page.isBlankFiller) continue;
+    const headerStory = page.stories.header;
+    if (headerStory && headerStory.kind === "header") {
+      const source = findSubPart(subParts.headers, headerStory.relationshipId);
+      if (source) {
+        headerPreviewByPageId.set(
+          page.pageId,
+          flattenBlocksToPreview(source.blocks, page, graph),
+        );
+      }
+    }
+    const footerStory = page.stories.footer;
+    if (footerStory && footerStory.kind === "footer") {
+      const source = findSubPart(subParts.footers, footerStory.relationshipId);
+      if (source) {
+        footerPreviewByPageId.set(
+          page.pageId,
+          flattenBlocksToPreview(source.blocks, page, graph),
+        );
+      }
+    }
+  }
+
+  return { headerPreviewByPageId, footerPreviewByPageId };
+}
+
+function findSubPart<T extends HeaderDocument | FooterDocument>(
+  parts: ReadonlyArray<T> | undefined,
+  relationshipId: string,
+): T | undefined {
+  if (!parts) return undefined;
+  return parts.find((p) => p.relationshipId === relationshipId);
+}
+
+function flattenBlocksToPreview(
+  blocks: ReadonlyArray<BlockNode>,
+  page: RuntimePageNode,
+  graph: RuntimePageGraph,
+): string {
+  const parts: string[] = [];
+  for (const block of blocks) {
+    collectBlockText(block, page, graph, parts);
+    if (joinPreview(parts).length >= MAX_PREVIEW_CHARS) break;
+  }
+  return truncate(joinPreview(parts));
+}
+
+function collectBlockText(
+  block: BlockNode,
+  page: RuntimePageNode,
+  graph: RuntimePageGraph,
+  out: string[],
+): void {
+  switch (block.type) {
+    case "paragraph":
+      for (const child of block.children) {
+        collectInlineText(child, page, graph, out);
+      }
+      break;
+    case "table":
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          for (const childBlock of cell.children) {
+            collectBlockText(childBlock, page, graph, out);
+          }
+        }
+      }
+      break;
+    case "sdt":
+      for (const child of block.children) {
+        collectBlockText(child, page, graph, out);
+      }
+      break;
+    // opaque_block / section_break / custom_xml / alt_chunk — no preview text.
+    default:
+      break;
+  }
+}
+
+function collectInlineText(
+  inline: InlineNode,
+  page: RuntimePageNode,
+  graph: RuntimePageGraph,
+  out: string[],
+): void {
+  switch (inline.type) {
+    case "text":
+      out.push(inline.text);
+      break;
+    case "tab":
+      out.push(" ");
+      break;
+    case "hard_break":
+      out.push(" ");
+      break;
+    case "field": {
+      const family = inline.fieldFamily ?? classifyFieldInstructionLocal(inline.instruction);
+      const cached = flattenInline(inline.children);
+      if (family === "PAGE" || family === "NUMPAGES") {
+        out.push(
+          resolvePageFieldDisplayText(family, cached, { page, graph }),
+        );
+      } else {
+        out.push(cached);
+      }
+      break;
+    }
+    case "hyperlink":
+      for (const child of inline.children) {
+        collectInlineText(child, page, graph, out);
+      }
+      break;
+    // bookmark_start/end, opaque_inline, note_ref etc — skip.
+    default:
+      break;
+  }
+}
+
+function flattenInline(inlines: ReadonlyArray<InlineNode> | undefined): string {
+  if (!inlines) return "";
+  let buf = "";
+  for (const inline of inlines) {
+    if (inline.type === "text") buf += inline.text;
+    else if (inline.type === "hard_break" || inline.type === "tab") buf += " ";
+  }
+  return buf;
+}
+
+function classifyFieldInstructionLocal(instr: string): string {
+  const match = /^\s*(\w+)/.exec(instr);
+  return match ? match[1]!.toUpperCase() : "UNKNOWN";
+}
+
+function joinPreview(parts: readonly string[]): string {
+  return parts.join("").replace(/\s+/g, " ").trim();
+}
+
+function truncate(s: string): string {
+  if (s.length <= MAX_PREVIEW_CHARS) return s;
+  return s.slice(0, MAX_PREVIEW_CHARS - 1).trimEnd() + "…";
+}

package/src/runtime/layout/resolved-formatting-state.ts

@@ -151,11 +151,11 @@ export function resolveBlockFormatting(
     fontSizeHalfPoints: fontInfo.fontSizeHalfPoints,
     averageCharWidthTwips: fontInfo.avgCharWidth,
     tabStops: resolveTabStops(block),
-    keepNext: Boolean(block.keepNext),
-    keepLines: Boolean(block.keepLines),
-    pageBreakBefore: Boolean(block.pageBreakBefore),
-    widowControl: block.widowControl !== false, // default true in Word
-    contextualSpacing: Boolean(block.contextualSpacing),
+    keepNext: Boolean(block.keepNext ?? block.resolvedParagraphFormatting?.keepNext),
+    keepLines: Boolean(block.keepLines ?? block.resolvedParagraphFormatting?.keepLines),
+    pageBreakBefore: Boolean(block.pageBreakBefore ?? block.resolvedParagraphFormatting?.pageBreakBefore),
+    widowControl: (block.widowControl ?? block.resolvedParagraphFormatting?.widowControl) !== false, // default true in Word
+    contextualSpacing: Boolean(block.contextualSpacing ?? block.resolvedParagraphFormatting?.contextualSpacing),
   };
 }
 
@@ -166,9 +166,10 @@ export function resolveBlockFormatting(
 function resolveSpacing(
   block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
 ): ParagraphSpacing {
-  // Numbering geometry spacing overrides direct paragraph spacing
+  // Priority: numbering geometry > direct paragraph > style cascade
   const numbering = block.resolvedNumbering?.geometry.spacing;
   const direct = block.spacing;
+  const cascade = block.resolvedParagraphFormatting?.spacing;
 
   const normalizeLineRule = (
     rule: string | undefined,
@@ -177,21 +178,15 @@ function resolveSpacing(
     return undefined;
   };
 
-  if (numbering) {
+  if (numbering || direct || cascade) {
     return {
-      before: numbering.before ?? direct?.before,
-      after: numbering.after ?? direct?.after,
-      line: numbering.line ?? direct?.line,
-      lineRule: normalizeLineRule(numbering.lineRule) ?? normalizeLineRule(direct?.lineRule),
-    };
-  }
-
-  if (direct) {
-    return {
-      before: direct.before,
-      after: direct.after,
-      line: direct.line,
-      lineRule: normalizeLineRule(direct.lineRule),
+      before: numbering?.before ?? direct?.before ?? cascade?.before,
+      after: numbering?.after ?? direct?.after ?? cascade?.after,
+      line: numbering?.line ?? direct?.line ?? cascade?.line,
+      lineRule:
+        normalizeLineRule(numbering?.lineRule) ??
+        normalizeLineRule(direct?.lineRule) ??
+        normalizeLineRule(cascade?.lineRule),
     };
   }
 
@@ -228,16 +223,25 @@ function resolveIndentation(
     };
   }
 
-  const ind = block.indentation;
-  if (!ind) {
+  const direct = block.indentation;
+  const cascade = block.resolvedParagraphFormatting?.indentation;
+
+  if (!direct && !cascade) {
     return { left: 0, right: 0, firstLine: 0, hanging: 0 };
   }
 
   return {
-    left: ind.left ?? 0,
-    right: ind.right ?? 0,
-    firstLine: ind.firstLine ?? 0,
-    hanging: ind.hanging ?? (typeof ind.firstLine === "number" && ind.firstLine < 0 ? Math.abs(ind.firstLine) : 0),
+    left: direct?.left ?? cascade?.left ?? 0,
+    right: direct?.right ?? cascade?.right ?? 0,
+    firstLine: direct?.firstLine ?? cascade?.firstLine ?? 0,
+    hanging:
+      direct?.hanging ??
+      cascade?.hanging ??
+      (typeof direct?.firstLine === "number" && direct.firstLine < 0
+        ? Math.abs(direct.firstLine)
+        : typeof cascade?.firstLine === "number" && cascade.firstLine < 0
+          ? Math.abs(cascade.firstLine)
+          : 0),
   };
 }
 

package/src/runtime/layout/table-render-plan.ts

@@ -101,6 +101,13 @@ export interface BuildTableRenderPlanInput {
   /** If `columnsTwips` was scaled to the canvas width, pass the scale
    *  factor here; otherwise leave undefined. */
   columnsTwipsScale?: number;
+  /**
+   * R3: true when this plan is for a continuation page of a multi-page
+   * table (i.e. a page other than the one the table first appears on).
+   * When true, header rows from the source table are emitted in
+   * `repeatedHeaderRows` so the consumer can prepend them on render.
+   */
+  isContinuationPage?: boolean;
 }
 
 export function buildTableRenderPlan(
@@ -112,7 +119,20 @@ export function buildTableRenderPlan(
 
   const bandClasses = buildBandClasses(block.rows, resolved);
   const verticalMerges = collectVerticalMerges(block.rows);
-  const repeatedHeaderRows: RepeatedHeaderRowRef[] = [];
+  // R3: header rows are repeated on every continuation page.  When the
+  // render-plan builder is invoked for a page with `isContinuationPage`,
+  // every row with `isHeader === true` gets an entry in repeatedHeaderRows.
+  // First-page plans (or tables that fit on a single page) return an empty
+  // array.  `virtualFragmentId` is deterministic so consumers can key off it.
+  const repeatedHeaderRows: RepeatedHeaderRowRef[] = input.isContinuationPage
+    ? block.rows
+        .map((row, rowIndex) => ({ row, rowIndex }))
+        .filter(({ row }) => row.isHeader === true)
+        .map(({ rowIndex }) => ({
+          sourceRowIndex: rowIndex,
+          virtualFragmentId: `fragment-${blockId}-vheader-p${pageIndex}-r${rowIndex}`,
+        }))
+    : [];
   const columnResizeHandles = buildColumnResizeHandles(columnsTwips, tableHeightTwips);
 
   return {

package/src/runtime/numbering-prefix.ts

@@ -1,4 +1,5 @@
 import type {
+  CanonicalRunFormatting,
   NumberingCatalog,
   NumberingLevelDefinition,
   ParagraphNode,
@@ -23,6 +24,7 @@ export interface NumberingPrefixResult {
   paragraphStyleId?: string;
   isLegalNumbering?: boolean;
   geometry: ResolvedNumberingGeometry;
+  markerRunProperties?: CanonicalRunFormatting;
 }
 
 export interface NumberingPrefixResolver {
@@ -90,6 +92,9 @@ export function createNumberingPrefixResolver(
         ? { paragraphStyleId: resolved.effectiveLevel.paragraphStyleId }
         : {}),
       ...(resolved.effectiveLevel.isLegalNumbering ? { isLegalNumbering: true } : {}),
+      ...(resolved.geometry.markerRunProperties
+        ? { markerRunProperties: resolved.geometry.markerRunProperties }
+        : {}),
       geometry: resolved.geometry,
     };
   }