@beyondwork/docx-react-component 1.0.105 → 1.0.106

package/src/api/v3/ui/_types.ts

@@ -118,6 +118,21 @@ export interface UiController {
    * error rather than silently no-op.
    */
   readonly subscribeViewport?: (listener: UiListener<ViewportState>) => UiUnsubscribe;
+  /**
+   * PE2 page-residency policy read. L10 owns the observable residency
+   * shape; L11 owns realized DOM/PM attachment and L05 owns geometry
+   * caches. Omitting the hook makes `ui.viewport.getPageResidency`
+   * return an explicit unavailable snapshot.
+   */
+  readonly getPageResidency?: (pageIndex: number) => PageResidencySnapshot;
+  /**
+   * Page-residency subscription. Fires when the mounted surface changes
+   * whether a page is realized, cold, or evicted.
+   */
+  readonly subscribePageResidency?: (
+    pageIndex: number,
+    listener: UiListener<PageResidencySnapshot>,
+  ) => UiUnsubscribe;
   /**
    * Overlay invalidation subscription. Fires when geometry invalidation
    * ranges overlap attached overlay queries (U7). `ui.overlays.subscribe`
@@ -234,6 +249,29 @@ export interface ViewportState {
   readonly devicePixelRatio: number;
 }
 
+export type PageResidency = "realized" | "cold" | "evicted";
+
+export type RehydrationStatus =
+  | "available"
+  | "requires-rehydration"
+  | "unavailable";
+
+export type PageResidencySource =
+  | "controller"
+  | "unavailable";
+
+export interface PageResidencySnapshot {
+  readonly __mock?: true;
+  /** 0-based page index, matching GeometryFacet.getPage(index). */
+  readonly pageIndex: number;
+  readonly pageId?: string;
+  readonly residency: PageResidency;
+  readonly status: RehydrationStatus;
+  readonly revision: number;
+  readonly source: PageResidencySource;
+  readonly reason?: string;
+}
+
 export type ScrollTargetBehavior = "auto" | "smooth" | "instant";
 
 export type ScrollTarget =
@@ -452,6 +490,21 @@ export interface ApiV3UiSurface {
 export interface ApiV3UiViewport {
   get(): ViewportState;
   subscribe(listener: UiListener<ViewportState>): UiUnsubscribe;
+  /**
+   * Read L10's page-residency policy for a 0-based page index. When no
+   * mounted controller has supplied a residency policy yet, returns an
+   * explicit `unavailable` mock snapshot instead of probing geometry or
+   * realizing DOM.
+   */
+  getPageResidency(pageIndex: number): PageResidencySnapshot;
+  /**
+   * Subscribe to residency changes for a 0-based page index. The listener
+   * receives plain snapshots; realization/teardown stays owned by L11.
+   */
+  subscribePageResidency(
+    pageIndex: number,
+    listener: UiListener<PageResidencySnapshot>,
+  ): UiUnsubscribe;
 
   /**
    * Scroll the mounted surface to a specific 1-based page number.

package/src/api/v3/ui/index.ts

@@ -24,6 +24,10 @@ export type {
   UiScopeListFilter,
   UiScopeRailOptions,
   ViewportState,
+  PageResidency,
+  PageResidencySnapshot,
+  PageResidencySource,
+  RehydrationStatus,
   ScrollTarget,
   ScrollTargetBehavior,
   ScrollToPageResult,

package/src/api/v3/ui/viewport.ts

@@ -24,6 +24,7 @@
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
 import type {
   ViewportState,
+  PageResidencySnapshot,
   UiListener,
   UiUnsubscribe,
   WorkflowMarkupMode,
@@ -86,6 +87,52 @@ export const subscribeMetadata: ApiV3FnMetadata = {
   rwdReference: "§UI API § ui.viewport.subscribe. Adapter delegates to UiController.subscribeViewport; throws when the active binding has no hook. Subscribe call emits one `ux.response.ui.viewport.subscribe` acknowledgement; per-tick ViewportState deliveries flow through the listener (rAF-coalesced, U7).",
 };
 
+export const getPageResidencyMetadata: ApiV3FnMetadata = {
+  name: "ui.viewport.getPageResidency",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/viewport-residency.test.ts",
+    commit: "refactor-10-pe2-residency",
+  },
+  mockShape: {
+    deterministic: true,
+    seededFrom: "fixed",
+    shapeDescription: "Mock PageResidencySnapshot with residency='evicted' and status='unavailable' when no mounted controller exposes L10 residency policy.",
+    carriesMockFlag: true,
+  },
+  uxIntent: { uiVisible: false },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-viewport-read" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference: "§PE2 § Virtual Page Windowing. Reads L10 page residency policy (realized/cold/evicted) without probing L05 geometry or realizing L11 DOM.",
+};
+
+export const subscribePageResidencyMetadata: ApiV3FnMetadata = {
+  name: "ui.viewport.subscribePageResidency",
+  status: "live-with-adapter",
+  sourceLayer: "presentation",
+  liveEvidence: {
+    runnerTest: "test/api/v3/ui/viewport-residency.test.ts",
+    commit: "refactor-10-pe2-residency",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "surface-refresh",
+    expectedDelta: "page-residency subscriber attached; future realized/cold/evicted changes propagate through the listener",
+  },
+  agentMetadata: { readOrMutate: "read", boundedScope: "session", auditCategory: "ui-viewport-subscribe" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  bidirectional: true,
+  subscriptionShape: {
+    eventType: "ui.viewport.page_residency_changed",
+    payloadType: "PageResidencySnapshot",
+    coalescing: "raf",
+  },
+  rwdReference: "§PE2 § Virtual Page Windowing. Adapter delegates to UiController.subscribePageResidency; emissions are plain snapshots and do not dispatch PM transactions or force geometry rehydration.",
+};
+
 // ----- scrollToPage (coord-10 §γ — visual-fidelity / Go-to-page UX) -----
 
 export const scrollToPageMetadata: ApiV3FnMetadata = {
@@ -245,6 +292,23 @@ export function createViewportFamily(ctx: UiApiContext) {
     notifyMarkupModeSubscribers();
   });
 
+  function normalizePageIndex(pageIndex: number): number {
+    if (!Number.isFinite(pageIndex)) return 0;
+    return Math.max(0, Math.floor(pageIndex));
+  }
+
+  function unavailableResidency(pageIndex: number): PageResidencySnapshot {
+    return Object.freeze({
+      __mock: true,
+      pageIndex: normalizePageIndex(pageIndex),
+      residency: "evicted",
+      status: "unavailable",
+      revision: 0,
+      source: "unavailable",
+      reason: "page-residency policy is not wired on the active controller",
+    } as const);
+  }
+
   return {
     // Slice 11 — composes scroll/dpr/zoom from `handle.geometry` with
     // width/height from the bound controller (see
@@ -279,6 +343,39 @@ export function createViewportFamily(ctx: UiApiContext) {
       });
       return unsubscribe;
     },
+    getPageResidency(pageIndex: number): PageResidencySnapshot {
+      const normalized = normalizePageIndex(pageIndex);
+      const resolver = ctx.binding?.controller.getPageResidency;
+      if (!resolver) return unavailableResidency(normalized);
+      return resolver(normalized);
+    },
+    subscribePageResidency(
+      pageIndex: number,
+      listener: UiListener<PageResidencySnapshot>,
+    ): UiUnsubscribe {
+      const controller = ctx.binding?.controller;
+      if (!controller) {
+        throw new Error(
+          "ui.viewport.subscribePageResidency: no controller bound — call ui.session.bind(controller) first",
+        );
+      }
+      if (!controller.subscribePageResidency) {
+        throw new Error(
+          `ui.viewport.subscribePageResidency: controller of kind "${controller.kind}" did not provide a subscribePageResidency hook`,
+        );
+      }
+      const normalized = normalizePageIndex(pageIndex);
+      const unsubscribe = controller.subscribePageResidency(normalized, listener);
+      emitUxResponse(ctx.handle, {
+        apiFn: subscribePageResidencyMetadata.name,
+        intent: subscribePageResidencyMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live-with-adapter",
+        uiVisible: true,
+        expectedDelta: subscribePageResidencyMetadata.uxIntent.expectedDelta,
+        actualDelta: { kind: "surface-refresh", payload: { subscribed: "ui.viewport.pageResidency", pageIndex: normalized } },
+      });
+      return unsubscribe;
+    },
 
     // ----- scrollToPage (coord-10 §γ) -----
 

package/src/model/layout/page-graph-types.ts

@@ -202,6 +202,27 @@ export interface RuntimeTableVerticalMergeCarry {
   restartRowIndex: number;
 }
 
+export type RuntimeFragmentLayoutObjectKind =
+  | "paragraph"
+  | "numbered-paragraph"
+  | "table"
+  | "field-region"
+  | "footnote-body"
+  | "sdt-block"
+  | "opaque-block";
+
+export interface RuntimeFragmentLayoutObject {
+  objectId: string;
+  kind: RuntimeFragmentLayoutObjectKind;
+  sourceBlockId: string;
+  paginationRole: "whole" | "slice" | "continuation";
+  measuredExtentTwips: {
+    heightTwips: number;
+    widthTwips?: number;
+  };
+  fieldFamilies?: readonly string[];
+}
+
 // ---------------------------------------------------------------------------
 // Fragment types
 // ---------------------------------------------------------------------------
@@ -265,6 +286,14 @@ export interface RuntimeBlockFragment {
    * consumers without reading DOM or canonical tables again.
    */
   continuation?: RuntimeLayoutContinuationCursor;
+  /**
+   * PE2 Slice 3 — measured layout-object descriptor for this fragment.
+   * This is the internal object protocol layer: one stable row per
+   * page-local fragment, expressed only in ids/enums/twips. It lets debug,
+   * render, and future truth joins reason about paragraph/table/note
+   * placement without re-reading DOM or source model objects.
+   */
+  layoutObject?: RuntimeFragmentLayoutObject;
   /**
    * Slice 5 — opaque style-chain ref derived from the block's `styleId`.
    * Used by `analyzeStylesChange` to bound invalidation to the first page

package/src/runtime/document-runtime.ts

@@ -3271,14 +3271,6 @@ export function createDocumentRuntime(
         const timestamp = clock();
 
         if (suggesting) {
-          if (activeStory.kind !== "main") {
-            this.emitBlockedCommand(commandName, [{
-              code: "suggesting_unsupported",
-              message: `"${commandName}" is not supported in suggesting mode for this story.`,
-            }]);
-            return;
-          }
-
           if (
             operation.type === "set-alignment" ||
             operation.type === "indent" ||
@@ -3313,9 +3305,14 @@ export function createDocumentRuntime(
               },
               timestamp,
             );
+            const nextFullDocument = stitchActiveStoryDocument(
+              persistedDocument,
+              activeStory,
+              nextDocument,
+            );
             this.dispatch({
               type: "document.replace",
-              document: { ...nextDocument, updatedAt: timestamp },
+              document: { ...nextFullDocument, updatedAt: timestamp },
               mapping: createEmptyMapping(),
               selection: toInternalSelectionSnapshot(result.selection),
               origin: createOrigin("api", timestamp),
@@ -3353,9 +3350,14 @@ export function createDocumentRuntime(
             },
             timestamp,
           );
+          const nextFullDocument = stitchActiveStoryDocument(
+            persistedDocument,
+            activeStory,
+            nextDocument,
+          );
           this.dispatch({
             type: "document.replace",
-            document: { ...nextDocument, updatedAt: timestamp },
+            document: { ...nextFullDocument, updatedAt: timestamp },
             mapping: createEmptyMapping(),
             selection: toInternalSelectionSnapshot(result.selection),
             origin: createOrigin("api", timestamp),
@@ -4187,13 +4189,6 @@ export function createDocumentRuntime(
       const suggesting =
         workflowCoordinator.getEffectiveDocumentMode(state.selection) === "suggesting";
       if (suggesting) {
-        if (activeStory.kind !== "main") {
-          this.emitBlockedCommand("clearHighlight", [{
-            code: "suggesting_unsupported",
-            message: `"clearHighlight" is not supported in suggesting mode for this story.`,
-          }]);
-          return;
-        }
         const segment = findSingleSelectedTextSegment(syntheticSnapshot);
         if (!segment) {
           this.emitBlockedCommand("clearHighlight", [{
@@ -4225,9 +4220,14 @@ export function createDocumentRuntime(
           },
           timestamp,
         );
+        const nextFullDocument = stitchActiveStoryDocument(
+          state.document,
+          activeStory,
+          nextDocument,
+        );
         this.dispatch({
           type: "document.replace",
-          document: nextDocument,
+          document: { ...nextFullDocument, updatedAt: timestamp },
           mapping: createEmptyMapping(),
           origin: createOrigin("api", timestamp),
         });
@@ -9223,6 +9223,27 @@ function appendPropertyChangeSuggestion(
   };
 }
 
+function stitchActiveStoryDocument(
+  persistedDocument: CanonicalDocumentEnvelope,
+  activeStory: EditorStoryTarget,
+  storyDocument: CanonicalDocumentEnvelope,
+): CanonicalDocumentEnvelope {
+  if (activeStory.kind === "main") {
+    return storyDocument;
+  }
+
+  return replaceStoryBlocks(
+    {
+      ...persistedDocument,
+      review: storyDocument.review,
+      diagnostics: storyDocument.diagnostics,
+      preservation: storyDocument.preservation,
+    },
+    activeStory,
+    storyDocument.content.children,
+  );
+}
+
 function createRuntimeSuggestionChangeId(
   existing: CanonicalDocumentEnvelope["review"]["revisions"],
   timestamp: string,

package/src/runtime/geometry/geometry-index.ts

@@ -259,6 +259,11 @@ export function projectGeometryIndexFromFrame(
       regionIds,
     });
     recordPrecision(precision, "exact");
+    appendPageLocalObjectHandleEntries({
+      page,
+      entries: objectHandleEntries,
+      precision,
+    });
   }
 
   appendScopeReplacementEnvelopeEntries({
@@ -762,6 +767,75 @@ function appendCanonicalObjectHandleEntries(input: {
   }
 }
 
+function appendPageLocalObjectHandleEntries(input: {
+  page: RenderPage;
+  entries: Map<string, MutableObjectHandleEntry>;
+  precision: GeometryPrecisionCounts;
+}): void {
+  const { page, entries, precision } = input;
+  const stories = page.page.frame?.pageLocalStories ?? [];
+  for (const story of stories) {
+    const regionFrame =
+      story.kind === "header" ? page.regions.header?.frame : page.regions.footer?.frame;
+    if (!regionFrame) continue;
+    for (const object of story.anchoredObjects) {
+      const objectFrame = pageLocalObjectFrame(
+        regionFrame,
+        object.extentTwips,
+        page.page.layout.pageWidth > 0
+          ? page.frame.widthPx / page.page.layout.pageWidth
+          : 1,
+      );
+      const handleRects = buildObjectHandleRectsFromRect(objectFrame, "heuristic");
+      const sourceIdentity: GeometrySourceIdentity = {
+        storyKey: story.storyKey,
+        objectKey: object.objectId,
+        objectKind: object.sourceType,
+        editPosture: object.preserveOnly ? "preserve-only" : "editable",
+        joinKind: "block-scoped",
+      };
+      const existing = entries.get(object.objectId);
+      if (existing) {
+        appendUnique(existing.pageIds, page.page.pageId);
+        existing.rects.push(...handleRects);
+        if (existing.precision !== "heuristic") {
+          existing.precision = "heuristic";
+          existing.status = "requires-rehydration";
+          existing.sourceIdentity = sourceIdentity;
+        }
+        continue;
+      }
+      entries.set(object.objectId, {
+        objectId: object.objectId,
+        pageIds: [page.page.pageId],
+        rects: [...handleRects],
+        status: "requires-rehydration",
+        precision: "heuristic",
+        sourceIdentity,
+      });
+      recordPrecision(precision, "heuristic");
+    }
+  }
+}
+
+function pageLocalObjectFrame(
+  regionFrame: RenderFrameRect,
+  extentTwips:
+    | { readonly widthTwips: number; readonly heightTwips: number }
+    | undefined,
+  pxPerTwip: number,
+): RenderFrameRect {
+  if (!extentTwips) return regionFrame;
+  const widthPx = Math.max(0, extentTwips.widthTwips * pxPerTwip);
+  const heightPx = Math.max(0, extentTwips.heightTwips * pxPerTwip);
+  return {
+    leftPx: regionFrame.leftPx,
+    topPx: regionFrame.topPx,
+    widthPx: widthPx > 0 ? Math.min(widthPx, regionFrame.widthPx) : regionFrame.widthPx,
+    heightPx: heightPx > 0 ? Math.min(heightPx, regionFrame.heightPx) : regionFrame.heightPx,
+  };
+}
+
 function finalizeObjectHandleEntries(
   entries: ReadonlyMap<string, MutableObjectHandleEntry>,
 ): GeometryObjectHandleEntry[] {

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

@@ -1074,8 +1074,15 @@
  *   table header rows, and vertical-merge carry metadata. Cache envelopes
  *   from v67 invalidate because fragment payloads can now include
  *   continuation state. Shipped via pe2 commit `33fbf45ac`.
+ *
+ *  69 — PE2 Slice 3 measured layout-object descriptors (Layer 04). Body
+ *   fragments and footnote-area fragments now carry a twips/plain
+ *   `layoutObject` row with stable object id, source block id, object kind,
+ *   pagination role, measured extent, and field-family hints where applicable.
+ *   Cache envelopes from v68 invalidate because fragment payloads can now
+ *   include layout-object descriptors. Shipped via pe2 commit `9c4417418`.
  */
-export const LAYOUT_ENGINE_VERSION = 68 as const;
+export const LAYOUT_ENGINE_VERSION = 69 as const;
 
 /**
  * Serialization schema version for the LayCache payload (the cache envelope

package/src/runtime/layout/page-graph.ts

@@ -72,6 +72,8 @@ export type {
   RuntimeParagraphContinuationCursor,
   RuntimeTableContinuationCursor,
   RuntimeTableVerticalMergeCarry,
+  RuntimeFragmentLayoutObjectKind,
+  RuntimeFragmentLayoutObject,
   RuntimeBlockFragment,
   RuntimeLineBox,
   RuntimeNoteAllocation,

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

@@ -1791,6 +1791,16 @@ export function paginateSectionBlocksWithSplits(
         to: refRange.blockTo,
         heightTwips: heightTwips + FOOTNOTE_REFERENCE_RESERVATION_TWIPS,
         kind: "whole",
+        layoutObject: {
+          objectId: `footnote-body:${fragmentId}`,
+          kind: "footnote-body",
+          sourceBlockId: `note-body-${noteKind}-${noteId}`,
+          paginationRole: "whole",
+          measuredExtentTwips: {
+            heightTwips: heightTwips + FOOTNOTE_REFERENCE_RESERVATION_TWIPS,
+            widthTwips: effectiveColumnWidth,
+          },
+        },
       };
 
       allocations.push(allocation);

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

@@ -126,6 +126,14 @@ export function projectSurfaceBlocksToPageFragments(
     if (pageIndex === null) continue;
 
     const columnIndex = columnIndexFor(pageIndex, block.blockId);
+    const heightTwips = measuredHeightFor(
+      pageIndex,
+      block.blockId,
+      estimateBlockHeightFromSpan(block),
+    );
+    const widthTwips = fragmentMeasurementsByPageIndex
+      ?.get(pageIndex)
+      ?.get(block.blockId)?.widthTwips;
     const fragment: FragmentWithoutPageId = {
       fragmentId: `fragment-${block.blockId}`,
       blockId: block.blockId,
@@ -133,13 +141,16 @@ export function projectSurfaceBlocksToPageFragments(
       regionKind: "body",
       from: block.from,
       to: block.to,
-      heightTwips: measuredHeightFor(
-        pageIndex,
-        block.blockId,
-        estimateBlockHeightFromSpan(block),
-      ),
+      heightTwips,
       ...deriveStyleMetadata(block),
       kind: "whole",
+      layoutObject: buildFragmentLayoutObject({
+        block,
+        fragmentId: `fragment-${block.blockId}`,
+        heightTwips,
+        widthTwips,
+        paginationRole: "whole",
+      }),
       ...(columnIndex !== undefined ? { columnIndex } : {}),
     };
 
@@ -224,6 +235,7 @@ function emitSlicedParagraph(
 ): void {
   for (let i = 0; i < slices.length; i += 1) {
     const slice = slices[i]!;
+    const heightTwips = slice.heightTwips ?? estimateSliceHeightFromLines(slice.lineRange);
     const fragment: FragmentWithoutPageId = {
       fragmentId: `fragment-${block.blockId}-slice-${i}`,
       blockId: block.blockId,
@@ -231,11 +243,18 @@ function emitSlicedParagraph(
       regionKind: "body",
       from: block.from,
       to: block.to,
-      heightTwips: slice.heightTwips ?? estimateSliceHeightFromLines(slice.lineRange),
+      heightTwips,
       ...deriveStyleMetadata(block),
       kind: "paragraph-slice",
       paragraphLineRange: slice.lineRange,
       continuation: buildParagraphContinuationCursor(slice, i, slices.length),
+      layoutObject: buildFragmentLayoutObject({
+        block,
+        fragmentId: `fragment-${block.blockId}-slice-${i}`,
+        heightTwips,
+        widthTwips: slice.widthTwips,
+        paginationRole: slice.lineRange.from > 0 ? "continuation" : "slice",
+      }),
     };
     emit(slice.pageIndex, fragment);
   }
@@ -281,6 +300,7 @@ function emitSlicedTable(
 ): void {
   for (let i = 0; i < slices.length; i += 1) {
     const slice = slices[i]!;
+    const heightTwips = slice.heightTwips ?? estimateSliceHeightFromRows(slice.rowRange);
     const fragment: FragmentWithoutPageId = {
       fragmentId: `fragment-${block.blockId}-rowslice-${i}`,
       blockId: block.blockId,
@@ -288,11 +308,17 @@ function emitSlicedTable(
       regionKind: "body",
       from: block.from,
       to: block.to,
-      heightTwips: slice.heightTwips ?? estimateSliceHeightFromRows(slice.rowRange),
+      heightTwips,
       ...deriveStyleMetadata(block),
       kind: "table-slice",
       tableRowRange: slice.rowRange,
       continuation: buildTableContinuationCursor(block, slice, i, slices.length),
+      layoutObject: buildFragmentLayoutObject({
+        block,
+        fragmentId: `fragment-${block.blockId}-rowslice-${i}`,
+        heightTwips,
+        paginationRole: slice.rowRange.from > 0 ? "continuation" : "slice",
+      }),
       ...(slice.columnIndex !== undefined ? { columnIndex: slice.columnIndex } : {}),
     };
     emit(slice.pageIndex, fragment);
@@ -391,6 +417,59 @@ function estimateSliceHeightFromRows(rowRange: {
   return rows * 360; // ~1 line + padding per row, approximate
 }
 
+function buildFragmentLayoutObject(input: {
+  block: SurfaceBlockSnapshot;
+  fragmentId: string;
+  heightTwips: number;
+  widthTwips?: number;
+  paginationRole: NonNullable<RuntimeBlockFragment["layoutObject"]>["paginationRole"];
+}): NonNullable<RuntimeBlockFragment["layoutObject"]> {
+  const fieldFamilies = collectFieldFamilies(input.block);
+  const kind = resolveFragmentLayoutObjectKind(input.block, fieldFamilies);
+  return {
+    objectId: `${kind}:${input.fragmentId}`,
+    kind,
+    sourceBlockId: input.block.blockId,
+    paginationRole: input.paginationRole,
+    measuredExtentTwips: {
+      heightTwips: Math.max(0, input.heightTwips),
+      ...(input.widthTwips !== undefined
+        ? { widthTwips: Math.max(0, input.widthTwips) }
+        : {}),
+    },
+    ...(fieldFamilies.length > 0 ? { fieldFamilies } : {}),
+  };
+}
+
+function resolveFragmentLayoutObjectKind(
+  block: SurfaceBlockSnapshot,
+  fieldFamilies: readonly string[],
+): NonNullable<RuntimeBlockFragment["layoutObject"]>["kind"] {
+  switch (block.kind) {
+    case "paragraph":
+      if (fieldFamilies.length > 0) return "field-region";
+      return block.numbering ? "numbered-paragraph" : "paragraph";
+    case "table":
+      return "table";
+    case "sdt_block":
+      return "sdt-block";
+    case "opaque_block":
+      return "opaque-block";
+  }
+}
+
+function collectFieldFamilies(block: SurfaceBlockSnapshot): string[] {
+  if (block.kind !== "paragraph") return [];
+  const families: string[] = [];
+  const seen = new Set<string>();
+  for (const segment of block.segments) {
+    if (segment.kind !== "field_ref" || seen.has(segment.fieldFamily)) continue;
+    seen.add(segment.fieldFamily);
+    families.push(segment.fieldFamily);
+  }
+  return families;
+}
+
 function findPageIndexForOffset(
   pages: readonly DocumentPageSnapshot[],
   offset: number,