@beyondwork/docx-react-component 1.0.103 → 1.0.105

package/src/runtime/workflow/coordinator.ts

@@ -62,6 +62,7 @@ import type {
   WorkflowMetadataDefinition,
   WorkflowMetadataEntry,
   WorkflowMetadataSnapshot,
+  WorkflowEventOrigin,
   WorkflowOverlay,
   WorkflowScope,
   WorkflowScopeGuardPolicy,
@@ -100,10 +101,8 @@ import {
 } from "./visibility-policy.ts";
 import { type WorkflowMarkupModePolicy } from "./markup-mode-policy.ts";
 
-/** Shape of origin metadata attached to commands. The runtime has a
- * richer `CommandOrigin` type; we only pass it through, so we keep an
- * open shape here to avoid coupling. */
-type CoordinatorCommandOrigin = { readonly source: string; readonly at?: string };
+/** Shape of origin metadata attached to workflow commands/events. */
+type CoordinatorCommandOrigin = WorkflowEventOrigin;
 
 /** Document-mutation commands the coordinator emits through `deps.dispatch`. */
 type CoordinatorDispatchedCommand =
@@ -157,10 +156,17 @@ export interface WorkflowEmittableEvent {
   readonly type:
     | "workflow_overlay_changed"
     | "workflow_active_work_item_changed"
-    | "workflow_metadata_changed";
+    | "workflow_metadata_changed"
+    | "workflow_shared_state_changed"
+    | "workflow_visibility_policy_changed"
+    | "workflow_markup_mode_policy_changed";
   readonly documentId: string;
   readonly snapshot?: WorkflowScopeSnapshot | WorkflowMetadataSnapshot | null;
   readonly activeWorkItemId?: string | null;
+  readonly state?: SharedWorkflowState | null;
+  readonly kind?: OverlayKind;
+  readonly policy?: OverlayVisibilityPolicy | WorkflowMarkupModePolicy | null;
+  readonly origin?: CoordinatorCommandOrigin;
 }
 
 export interface PerfCounters {
@@ -276,7 +282,10 @@ export interface WorkflowCoordinator {
    * seam) so UI surfaces re-fire when policy changes mid-session. */
   subscribeMarkupModePolicy(listener: () => void): () => void;
   /* --- collab shared state --- */
-  setSharedWorkflowState(state: SharedWorkflowState | null): void;
+  setSharedWorkflowState(
+    state: SharedWorkflowState | null,
+    origin?: CoordinatorCommandOrigin,
+  ): void;
   /* --- snapshots (cached) --- */
   getInteractionGuardSnapshot(): InteractionGuardSnapshot;
   getWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null;
@@ -1133,12 +1142,21 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     return overlayStore.getMetadataSnapshot();
   }
 
-  function setSharedWorkflowState(state: SharedWorkflowState | null): void {
+  function setSharedWorkflowState(
+    state: SharedWorkflowState | null,
+    origin: CoordinatorCommandOrigin = { source: "api", at: clock() },
+  ): void {
     const prior = overlayStore.getSharedWorkflowState();
     if (state === prior) return;
     overlayStore.replaceSharedWorkflowState(state);
     cachedInteractionGuardSnapshot = undefined;
     cachedWorkflowScopeSnapshot = undefined;
+    deps.emitEvent({
+      type: "workflow_shared_state_changed",
+      documentId: deps.getState().documentId,
+      state,
+      origin,
+    });
   }
 
   function setScopeChromeVisibility(state: ScopeChromeVisibilityState): void {
@@ -1161,13 +1179,13 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
 
   function setVisibilityPolicy(policy: OverlayVisibilityPolicy): boolean {
     const changed = overlayStore.replaceVisibilityPolicy(policy.kind, policy);
-    if (changed) emitVisibilityPolicyChanged();
+    if (changed) emitVisibilityPolicyChanged(policy.kind, policy);
     return changed;
   }
 
   function clearVisibilityPolicy(kind: OverlayKind): boolean {
     const changed = overlayStore.replaceVisibilityPolicy(kind, null);
-    if (changed) emitVisibilityPolicyChanged();
+    if (changed) emitVisibilityPolicyChanged(kind, null);
     return changed;
   }
 
@@ -1175,7 +1193,10 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     policies: readonly OverlayVisibilityPolicy[],
   ): boolean {
     const changed = overlayStore.replaceVisibilityPolicies(policies);
-    if (changed) emitVisibilityPolicyChanged();
+    if (changed) emitVisibilityPolicyChanged(undefined, undefined, {
+      source: "runtime",
+      at: clock(),
+    });
     return changed;
   }
 
@@ -1195,6 +1216,12 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     const changed = overlayStore.replaceMarkupModePolicy(policy);
     if (changed) {
       overlayStore.notifyMarkupModePolicyChanged();
+      deps.emitEvent({
+        type: "workflow_markup_mode_policy_changed",
+        documentId: deps.getState().documentId,
+        policy,
+        origin: { source: "api", at: clock() },
+      });
       if (deps.telemetryBus.isEnabled("scope")) {
         deps.telemetryBus.emit({
           channel: "scope",
@@ -1211,11 +1238,22 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
     return overlayStore.subscribeMarkupModePolicy(listener);
   }
 
-  function emitVisibilityPolicyChanged(): void {
+  function emitVisibilityPolicyChanged(
+    kind?: OverlayKind,
+    policy?: OverlayVisibilityPolicy | null,
+    origin: CoordinatorCommandOrigin = { source: "api", at: clock() },
+  ): void {
     // Notify direct subscribers first — L10 X3's ui.overlays.subscribeVisibility
     // chains onto this signal so UI surfaces re-fire when an authoring tool
     // mutates policy mid-session.
     overlayStore.notifyVisibilityPolicyChanged();
+    deps.emitEvent({
+      type: "workflow_visibility_policy_changed",
+      documentId: deps.getState().documentId,
+      ...(kind !== undefined ? { kind } : {}),
+      ...(policy !== undefined ? { policy } : {}),
+      origin,
+    });
     if (!deps.telemetryBus.isEnabled("scope")) return;
     deps.telemetryBus.emit({
       channel: "scope",
@@ -1301,12 +1339,14 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
           type: "workflow_overlay_changed",
           documentId,
           snapshot,
+          origin: command.origin,
         });
         if (command.overlay.activeWorkItemId !== undefined) {
           deps.emitEvent({
             type: "workflow_active_work_item_changed",
             documentId,
             activeWorkItemId: command.overlay.activeWorkItemId ?? null,
+            origin: command.origin,
           });
         }
         return warningDelta;
@@ -1323,6 +1363,7 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
           type: "workflow_active_work_item_changed",
           documentId,
           activeWorkItemId: null,
+          origin: command.origin,
         });
         deps.emitEvent({
           type: "workflow_overlay_changed",
@@ -1334,6 +1375,7 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
             candidates: [],
             blockedReasons: [],
           },
+          origin: command.origin,
         });
         return warningDelta;
       }
@@ -1343,6 +1385,7 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
           type: "workflow_metadata_changed",
           documentId,
           snapshot: overlayStore.getMetadataSnapshot(),
+          origin: command.origin,
         });
         return null;
       }
@@ -1352,6 +1395,7 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
           type: "workflow_metadata_changed",
           documentId,
           snapshot: overlayStore.getMetadataSnapshot(),
+          origin: command.origin,
         });
         return null;
       }
@@ -1361,6 +1405,7 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
           type: "workflow_metadata_changed",
           documentId,
           snapshot: overlayStore.getMetadataSnapshot(),
+          origin: command.origin,
         });
         return null;
       }
@@ -1370,6 +1415,7 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
           type: "workflow_metadata_changed",
           documentId,
           snapshot: overlayStore.getMetadataSnapshot(),
+          origin: command.origin,
         });
         return null;
       }

package/src/ui/ui-controller-factory.ts

@@ -54,6 +54,8 @@ import type {
   ChromePosture,
   GeometryRect,
   OverlayAnchorQuery,
+  UiOverlayLaneKind,
+  UiOverlayLaneSnapshot,
   UiController,
   UiControllerFactory,
   UiListener,
@@ -119,6 +121,13 @@ export interface ShellUiControllerDeps {
   readonly subscribeOverlays?: (
     listener: UiListener<OverlayAnchorQuery>,
   ) => UiUnsubscribe;
+  /** PE2 overlay-lane snapshot resolver. */
+  readonly getOverlayLane?: (kind: UiOverlayLaneKind) => UiOverlayLaneSnapshot;
+  /** PE2 overlay-lane subscription channel. */
+  readonly subscribeOverlayLane?: (
+    kind: UiOverlayLaneKind,
+    listener: UiListener<UiOverlayLaneSnapshot>,
+  ) => UiUnsubscribe;
 }
 
 /**
@@ -146,6 +155,8 @@ export function makeShellUiControllerFactory(
       ...(deps.getViewport ? { getViewport: deps.getViewport } : {}),
       ...(deps.subscribeViewport ? { subscribeViewport: deps.subscribeViewport } : {}),
       ...(deps.subscribeOverlays ? { subscribeOverlays: deps.subscribeOverlays } : {}),
+      ...(deps.getOverlayLane ? { getOverlayLane: deps.getOverlayLane } : {}),
+      ...(deps.subscribeOverlayLane ? { subscribeOverlayLane: deps.subscribeOverlayLane } : {}),
     };
     return controller;
   };

package/src/ui-tailwind/chrome-overlay/tw-page-stack-overlay-layer.tsx

@@ -839,6 +839,7 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
         null,
       );
       if (geometryRects !== null) {
+        incrementInvalidationCounter("overlay.page.geometry.hit");
         setRectsIfChanged(reconcilePaperRectsWithFlow(geometryRects, pageCount));
         return;
       }
@@ -854,6 +855,7 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
     // above via `geometryFacet` or the UI-API resolver. Lines below
     // fire only before the first render frame.
     if (origin) {
+      incrementInvalidationCounter("overlay.page.dom.degraded");
       const widgets = measureWidgetsViaBoundingRect(scrollRoot, origin, {
         pageCount,
         visiblePageIndexRange: null,
@@ -870,6 +872,7 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
       });
       setRectsIfChanged(reconcilePaperRectsWithFlow(domRects, pageCount));
     } else {
+      incrementInvalidationCounter("overlay.page.dom.degraded");
       const widgets = measureWidgetsViaOffsetChain(scrollRoot, {
         pageCount,
         visiblePageIndexRange: null,