@beyondwork/docx-react-component 1.0.104 → 1.0.106

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/index.ts

@@ -65,6 +65,9 @@ export type {
   RuntimeLayoutDivergenceKind,
   RuntimeLayoutDivergence,
   RuntimePageFrame,
+  RuntimePageLocalStoryInstance,
+  RuntimeResolvedStoryField,
+  RuntimeStoryAnchoredObject,
   RuntimeBlockFragment,
   RuntimeLineBox,
   RuntimeNoteAllocation,

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

@@ -107,6 +107,7 @@ export interface RuntimeLayoutDivergence {
   message: string;
   regionKinds?: RuntimePageRegion["kind"][];
   fragmentIds?: string[];
+  objectIds?: string[];
 }
 
 export interface RuntimePageFrame {
@@ -117,10 +118,111 @@ export interface RuntimePageFrame {
   displayPageNumber: number;
   physicalBoundsTwips: RuntimeTwipsRect;
   regions: RuntimeResolvedRegions;
+  pageLocalStories: RuntimePageLocalStoryInstance[];
   divergenceIds: string[];
   signature: string;
 }
 
+export interface RuntimePageLocalStoryInstance {
+  instanceId: string;
+  storyKey: string;
+  pageId: string;
+  kind: "header" | "footer";
+  variant: "default" | "first" | "even" | "odd";
+  relationshipId: string;
+  sectionIndex?: number;
+  resolvedFields: RuntimeResolvedStoryField[];
+  anchoredObjects: RuntimeStoryAnchoredObject[];
+  measuredFrameHeightTwips: number;
+  signature: string;
+}
+
+export interface RuntimeResolvedStoryField {
+  fieldId: string;
+  family: string;
+  displayText: string;
+}
+
+export interface RuntimeStoryAnchoredObject {
+  objectId: string;
+  sourceType:
+    | "image"
+    | "drawing-frame"
+    | "chart-preview"
+    | "smartart-preview"
+    | "shape"
+    | "wordart"
+    | "vml-shape"
+    | "ole-embed"
+    | "opaque-inline";
+  display: "inline" | "floating" | "unknown";
+  extentTwips?: {
+    widthTwips: number;
+    heightTwips: number;
+  };
+  relationshipIds?: readonly string[];
+  preserveOnly: boolean;
+  divergenceIds: string[];
+}
+
+export type RuntimeLayoutContinuationCursor =
+  | RuntimeParagraphContinuationCursor
+  | RuntimeTableContinuationCursor;
+
+export interface RuntimeParagraphContinuationCursor {
+  kind: "paragraph";
+  sequenceIndex: number;
+  sliceCount: number;
+  lineRange: {
+    from: number;
+    to: number;
+    totalLines: number;
+  };
+  continuesFromPreviousPage: boolean;
+  continuesToNextPage: boolean;
+}
+
+export interface RuntimeTableContinuationCursor {
+  kind: "table";
+  sequenceIndex: number;
+  sliceCount: number;
+  rowRange: {
+    from: number;
+    to: number;
+    totalRows: number;
+  };
+  continuesFromPreviousPage: boolean;
+  continuesToNextPage: boolean;
+  repeatedHeaderRowIndexes: readonly number[];
+  verticalMergeCarry: readonly RuntimeTableVerticalMergeCarry[];
+}
+
+export interface RuntimeTableVerticalMergeCarry {
+  columnIndex: number;
+  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
 // ---------------------------------------------------------------------------
@@ -176,6 +278,22 @@ export interface RuntimeBlockFragment {
     to: number;
     totalRows: number;
   };
+  /**
+   * PE2 Slice 3 — typed continuation cursor for fragments that render a
+   * logical block over multiple page/column frames. Existing slice fields
+   * remain for compatibility; this cursor makes repeated-header,
+   * line/row-range, and vertical-merge carry explicit for debug/render
+   * 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/model/layout/runtime-page-graph-types.ts

@@ -14,6 +14,10 @@
  * layer (`src/runtime/layout/page-graph.ts`).
  */
 
+import type {
+  FooterDocument,
+  HeaderDocument,
+} from "../canonical-document.ts";
 import type {
   RuntimeBlockFragment,
   RuntimeLayoutDivergence,
@@ -115,4 +119,13 @@ export interface BuildPageGraphInput {
    * `page-${revision}-${index}` pageId in advance.
    */
   noteAllocationsByPageIndex?: ReadonlyMap<number, RuntimeNoteAllocation[]>;
+  /**
+   * Optional canonical header/footer parts. When present, `buildPageGraph`
+   * resolves page-instance fields inside page-local header/footer story
+   * records without making render/UI consumers re-walk subparts.
+   */
+  subParts?: {
+    headers?: ReadonlyArray<HeaderDocument>;
+    footers?: ReadonlyArray<FooterDocument>;
+  };
 }

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/event-refresh-hints.ts

@@ -26,7 +26,6 @@ export function describeEventImpact(
     case "workflow_overlay_changed":
     case "workflow_active_work_item_changed":
     case "workflow_shared_state_changed":
-    case "workflow_visibility_policy_changed":
     case "workflow_markup_mode_policy_changed":
       return {
         invalidate: [
@@ -40,9 +39,27 @@ export function describeEventImpact(
         staleTargets: ["anchors"],
         changeKinds: ["workflow"],
       };
+    case "workflow_visibility_policy_changed":
+      return {
+        invalidate: [
+          "workflowScope",
+          "workflowMarkup",
+          "reviewWork",
+          "chunks",
+          "contextAnalytics",
+        ],
+        staleTargets: ["none"],
+        changeKinds: ["workflow"],
+      };
     case "workflow_metadata_changed":
       return {
-        invalidate: ["workflowMarkup", "render", "locations", "reviewWork", "chunks"],
+        invalidate: [
+          "workflowMarkup",
+          "locations",
+          "reviewWork",
+          "chunks",
+          "contextAnalytics",
+        ],
         staleTargets: ["anchors"],
         changeKinds: ["workflow"],
       };
@@ -50,10 +67,6 @@ export function describeEventImpact(
     case "change_accepted":
     case "change_rejected":
     case "suggestion_authored":
-    case "suggestion_updated":
-    case "comment_added":
-    case "comment_resolved":
-    case "comments_changed":
       return {
         invalidate: [
           "render",
@@ -72,6 +85,20 @@ export function describeEventImpact(
         staleTargets: ["search_results", "anchors"],
         changeKinds: ["content", "review", "structure"],
       };
+    case "suggestion_updated":
+      return {
+        invalidate: ["trackedChanges", "reviewWork", "chunks", "contextAnalytics"],
+        staleTargets: ["none"],
+        changeKinds: ["review"],
+      };
+    case "comment_added":
+    case "comment_resolved":
+    case "comments_changed":
+      return {
+        invalidate: ["comments", "reviewWork", "chunks", "contextAnalytics"],
+        staleTargets: ["none"],
+        changeKinds: ["review"],
+      };
     case "warning_added":
     case "warning_cleared":
     case "error":

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

@@ -259,7 +259,15 @@ export function createGeometryFacet(
     getGeometryCoverage() {
       const kernel = input.renderKernel?.();
       if (!kernel) return createUnavailableGeometryCoverage();
-      return summarizeGeometryCoverageFromFrame(kernel.getRenderFrame());
+      const frame = kernel.getRenderFrame();
+      const canonicalDocument = input.getCanonicalDocument?.() ?? null;
+      if (canonicalDocument) {
+        return (
+          projectGeometryIndexFromFrame(frame, { canonicalDocument })?.coverage ??
+          createUnavailableGeometryCoverage()
+        );
+      }
+      return summarizeGeometryCoverageFromFrame(frame);
     },
 
     hitTest(point) {