@beyondwork/docx-react-component 1.0.105 → 1.0.106

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

@@ -34,6 +34,7 @@ import type {
   RuntimePageNode,
   RuntimePageRegion,
   RuntimePageRegions,
+  RuntimeStoryAnchoredObject,
   RuntimeTwipsRect,
 } from "./page-graph.ts";
 import type {
@@ -168,6 +169,33 @@ export interface PublicPageFrame {
     rectTwips?: PublicTwipsRect;
     fragmentIds: readonly string[];
   }[];
+  pageLocalStories: readonly PublicPageLocalStoryInstance[];
+}
+
+export interface PublicPageLocalStoryInstance {
+  instanceId: string;
+  storyKey: string;
+  pageId: string;
+  kind: "header" | "footer";
+  variant: "default" | "first" | "even" | "odd";
+  relationshipId: string;
+  sectionIndex?: number;
+  anchoredObjects: readonly PublicStoryAnchoredObject[];
+  measuredFrameHeightTwips: number;
+  signature: string;
+}
+
+export interface PublicStoryAnchoredObject {
+  objectId: string;
+  sourceType: RuntimeStoryAnchoredObject["sourceType"];
+  display: RuntimeStoryAnchoredObject["display"];
+  extentTwips?: {
+    widthTwips: number;
+    heightTwips: number;
+  };
+  relationshipIds?: readonly string[];
+  preserveOnly: boolean;
+  divergenceIds: readonly string[];
 }
 
 export interface PublicPageNode {
@@ -265,9 +293,11 @@ export interface PublicBlockFragment {
   };
   columnIndex?: number;
   continuation?: PublicLayoutContinuationCursor;
+  layoutObject?: PublicFragmentLayoutObject;
 }
 
 export type PublicLayoutContinuationCursor = RuntimeLayoutContinuationCursor;
+export type PublicFragmentLayoutObject = NonNullable<RuntimeBlockFragment["layoutObject"]>;
 
 /**
  * P8 — One block snapshot rendered into a region of a page.  Returned by
@@ -1478,6 +1508,45 @@ function toPublicPageFrame(frame: RuntimePageFrame): PublicPageFrame {
     signature: frame.signature,
     exclusionZoneCount: frame.regions.exclusionZones.length,
     regionFrames: frameRegionEntries(frame),
+    pageLocalStories: frame.pageLocalStories.map(toPublicPageLocalStory),
+  };
+}
+
+function toPublicPageLocalStory(
+  story: RuntimePageFrame["pageLocalStories"][number],
+): PublicPageLocalStoryInstance {
+  return {
+    instanceId: story.instanceId,
+    storyKey: story.storyKey,
+    pageId: story.pageId,
+    kind: story.kind,
+    variant: story.variant,
+    relationshipId: story.relationshipId,
+    ...(story.sectionIndex !== undefined ? { sectionIndex: story.sectionIndex } : {}),
+    anchoredObjects: story.anchoredObjects.map(toPublicStoryAnchoredObject),
+    measuredFrameHeightTwips: story.measuredFrameHeightTwips,
+    signature: story.signature,
+  };
+}
+
+function toPublicStoryAnchoredObject(
+  object: RuntimeStoryAnchoredObject,
+): PublicStoryAnchoredObject {
+  return {
+    objectId: object.objectId,
+    sourceType: object.sourceType,
+    display: object.display,
+    ...(object.extentTwips
+      ? {
+          extentTwips: {
+            widthTwips: object.extentTwips.widthTwips,
+            heightTwips: object.extentTwips.heightTwips,
+          },
+        }
+      : {}),
+    ...(object.relationshipIds ? { relationshipIds: [...object.relationshipIds] } : {}),
+    preserveOnly: object.preserveOnly,
+    divergenceIds: [...object.divergenceIds],
   };
 }
 
@@ -1556,6 +1625,9 @@ function toPublicBlockFragment(
     ...(fragment.continuation !== undefined
       ? { continuation: cloneContinuationCursor(fragment.continuation) }
       : {}),
+    ...(fragment.layoutObject !== undefined
+      ? { layoutObject: cloneFragmentLayoutObject(fragment.layoutObject) }
+      : {}),
   };
 }
 
@@ -1576,6 +1648,18 @@ function cloneContinuationCursor(
   };
 }
 
+function cloneFragmentLayoutObject(
+  layoutObject: NonNullable<RuntimeBlockFragment["layoutObject"]>,
+): NonNullable<RuntimeBlockFragment["layoutObject"]> {
+  return {
+    ...layoutObject,
+    measuredExtentTwips: { ...layoutObject.measuredExtentTwips },
+    ...(layoutObject.fieldFamilies !== undefined
+      ? { fieldFamilies: [...layoutObject.fieldFamilies] }
+      : {}),
+  };
+}
+
 function toPublicLineBox(box: RuntimeLineBox): PublicLineBox {
   return {
     fragmentId: box.fragmentId,

package/src/runtime/workflow/index.ts

@@ -19,6 +19,7 @@ export * from "./scope-writer.ts";
 export * from "./metadata-writer.ts";
 export * from "./projector.ts";
 export * from "./overlay-store.ts";
+export * from "./overlay-lanes.ts";
 export * from "./coordinator.ts";
 export * from "./visibility-policy.ts";
 export * from "./markup-mode-policy.ts";

package/src/runtime/workflow/overlay-lanes.ts

@@ -0,0 +1,228 @@
+import type {
+  CommentSidebarSnapshot,
+  SuggestionsSnapshot,
+  TrackedChangesSnapshot,
+  WorkflowMarkupSnapshot,
+  WorkflowScopeSnapshot,
+} from "../../api/public-types.ts";
+import { ISSUE_METADATA_ID } from "../../api/public-types.ts";
+import type {
+  UiOverlayLaneEntry,
+  UiOverlayLaneKind,
+  UiOverlayLaneSnapshot,
+  UiOverlayLaneStatus,
+} from "../../api/v3/ui/index.ts";
+
+export type WorkflowReviewOverlayLaneKind = Extract<
+  UiOverlayLaneKind,
+  "redlines" | "comments" | "issues" | "field-scopes" | "broad-scopes" | "presence"
+>;
+
+export interface WorkflowReviewOverlayLaneInput {
+  readonly comments?: CommentSidebarSnapshot;
+  readonly trackedChanges?: TrackedChangesSnapshot;
+  readonly suggestions?: SuggestionsSnapshot | null;
+  readonly workflowScope?: WorkflowScopeSnapshot;
+  readonly workflowMarkup?: WorkflowMarkupSnapshot;
+  readonly revision?: number;
+}
+
+/**
+ * Layer-06 data handoff for L10/L11 PE2 overlay lanes.
+ *
+ * This projector emits plain lane snapshots only. It does not resolve geometry,
+ * read DOM state, subscribe to awareness, dispatch PM transactions, or wake
+ * layout. Presence is intentionally unavailable here because live cursor/
+ * collaborator state is sourced from Yjs awareness, not durable workflow truth.
+ */
+export function projectWorkflowReviewOverlayLane(
+  kind: WorkflowReviewOverlayLaneKind,
+  input: WorkflowReviewOverlayLaneInput,
+): UiOverlayLaneSnapshot {
+  if (kind === "presence") {
+    return {
+      kind,
+      status: "unavailable",
+      entries: [],
+      revision: input.revision ?? 0,
+      source: "awareness",
+      reason: "presence lane is sourced from Yjs awareness, not durable workflow/review state",
+    };
+  }
+
+  const entries = projectEntries(kind, input);
+  return {
+    kind,
+    status: summarizeStatus(entries),
+    entries,
+    revision: input.revision ?? 0,
+    source: "workflow",
+  };
+}
+
+function projectEntries(
+  kind: Exclude<WorkflowReviewOverlayLaneKind, "presence">,
+  input: WorkflowReviewOverlayLaneInput,
+): UiOverlayLaneEntry[] {
+  switch (kind) {
+    case "comments":
+      return (input.comments?.threads ?? []).map((thread) => ({
+        id: thread.commentId,
+        status: thread.status === "detached" ? "requires-rehydration" : "resolved",
+        anchor: { kind: "comment", value: thread.commentId },
+        reason: thread.detachedReason,
+        data: compactData({
+          laneItemKind: "comment",
+          commentId: thread.commentId,
+          editorAnchor: thread.anchor,
+          status: thread.status,
+          createdAt: thread.createdAt,
+          createdBy: thread.createdBy,
+          entryCount: thread.entryCount,
+          warningCount: thread.warningCount,
+          linkedRevisionId: thread.linkedRevisionId,
+          excerpt: thread.excerpt,
+          anchorLabel: thread.anchorLabel,
+        }),
+      }));
+    case "redlines":
+      return (input.trackedChanges?.revisions ?? []).map((revision) => ({
+        id: revision.revisionId,
+        status: revision.status === "detached" ? "requires-rehydration" : "resolved",
+        anchor: { kind: "revision", value: revision.revisionId },
+        reason: revision.preserveOnlyReason,
+        data: compactData({
+          laneItemKind: "revision",
+          revisionId: revision.revisionId,
+          editorAnchor: revision.anchor,
+          revisionKind: revision.kind,
+          semanticKind: revision.semanticKind,
+          suggestionId: revision.suggestionId,
+          status: revision.status,
+          actionability: revision.actionability,
+          authorId: revision.authorId,
+          createdAt: revision.createdAt,
+          label: revision.label,
+          excerpt: revision.excerpt,
+          storyTarget: revision.storyTarget,
+          canAccept: revision.canAccept,
+          canReject: revision.canReject,
+          warningCount: revision.warningCount,
+          commentThreadIds: revision.commentThreadIds,
+        }),
+      }));
+    case "issues":
+      return projectIssueEntries(input);
+    case "field-scopes":
+      return (input.workflowMarkup?.fields ?? []).map((field) => ({
+        id: `field:${field.fieldIndex}`,
+        status: "resolved",
+        data: compactData({
+          laneItemKind: "field",
+          fieldIndex: field.fieldIndex,
+          editorAnchor: field.anchor,
+          fieldFamily: field.fieldFamily,
+          fieldTarget: field.fieldTarget,
+          refreshStatus: field.refreshStatus,
+          displayText: field.displayText,
+          label: field.label,
+          storyTarget: field.storyTarget,
+        }),
+      }));
+    case "broad-scopes":
+      return [
+        ...(input.workflowScope?.scopes ?? []).map((scope) => ({
+          id: scope.scopeId,
+          status: "resolved" as const,
+          anchor: { kind: "scope" as const, value: scope.scopeId },
+          data: compactData({
+            laneItemKind: "workflow-scope",
+            scopeId: scope.scopeId,
+            editorAnchor: scope.anchor,
+            mode: scope.mode,
+            label: scope.label,
+            domain: scope.domain,
+            workItemId: scope.workItemId,
+            visibility: scope.visibility,
+            guardPolicy: scope.guardPolicy,
+            storyTarget: scope.storyTarget,
+            metadataRefs: scope.metadataRefs,
+          }),
+        })),
+        ...(input.workflowScope?.candidates ?? []).map((candidate) => ({
+          id: candidate.candidateId,
+          status: "resolved" as const,
+          data: compactData({
+            laneItemKind: "workflow-candidate",
+            candidateId: candidate.candidateId,
+            editorAnchor: candidate.anchor,
+            label: candidate.label,
+            source: candidate.source,
+            storyTarget: candidate.storyTarget,
+          }),
+        })),
+      ];
+  }
+}
+
+function projectIssueEntries(input: WorkflowReviewOverlayLaneInput): UiOverlayLaneEntry[] {
+  const suggestionGroupsByIssueId = new Map<string, string[]>();
+  for (const group of input.suggestions?.groups ?? []) {
+    if (!group.issueId) continue;
+    const ids = suggestionGroupsByIssueId.get(group.issueId) ?? [];
+    ids.push(group.groupId);
+    suggestionGroupsByIssueId.set(group.issueId, ids);
+  }
+
+  return (input.workflowMarkup?.metadata ?? [])
+    .filter((entry) => entry.metadataId === ISSUE_METADATA_ID)
+    .map((entry) => {
+      const issueValue = isRecord(entry.value) ? entry.value : undefined;
+      const issueId = typeof issueValue?.issueId === "string" ? issueValue.issueId : undefined;
+      return {
+        id: issueId ?? entry.entryId,
+        status: "resolved",
+        anchor: entry.scopeId ? { kind: "scope", value: entry.scopeId } : undefined,
+        data: compactData({
+          laneItemKind: "issue",
+          entryId: entry.entryId,
+          metadataId: entry.metadataId,
+          issueId,
+          editorAnchor: entry.anchor,
+          scopeId: entry.scopeId,
+          workItemId: entry.workItemId,
+          label: entry.label,
+          title: typeof issueValue?.title === "string" ? issueValue.title : undefined,
+          topic: typeof issueValue?.topic === "string" ? issueValue.topic : undefined,
+          severity: typeof issueValue?.severity === "string" ? issueValue.severity : undefined,
+          checklistState:
+            typeof issueValue?.checklistState === "string" ? issueValue.checklistState : undefined,
+          suggestionGroupIds: issueId ? suggestionGroupsByIssueId.get(issueId) ?? [] : [],
+          persistence: entry.persistence,
+          metadataPersistence: entry.metadataPersistence,
+          storageRef: entry.storageRef,
+          metadataVersion: entry.metadataVersion,
+        }),
+      };
+    });
+}
+
+function summarizeStatus(entries: readonly UiOverlayLaneEntry[]): UiOverlayLaneStatus {
+  return entries.some((entry) => entry.status === "requires-rehydration")
+    ? "requires-rehydration"
+    : "resolved";
+}
+
+function compactData(input: Record<string, unknown>): Readonly<Record<string, unknown>> {
+  const output: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (value !== undefined) {
+      output[key] = value;
+    }
+  }
+  return output;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/ui/presence-overlay-lane.ts

@@ -0,0 +1,131 @@
+import {
+  getRemoteCursorStates,
+  type RemoteCursorState,
+} from "../api/v3/runtime/collab.ts";
+import type {
+  GeometryRect,
+  UiListener,
+  UiOverlayLaneKind,
+  UiOverlayLaneSnapshot,
+  UiOverlayLaneStatus,
+  UiUnsubscribe,
+} from "../api/v3/ui/_types.ts";
+
+type AwarenessChangeListener = () => void;
+
+export interface PresenceAwarenessSource {
+  readonly clientID: number;
+  getStates(): Map<number, Record<string, unknown>>;
+  on(event: "change", listener: AwarenessChangeListener): void;
+  off(event: "change", listener: AwarenessChangeListener): void;
+}
+
+export type PresenceCursorProjection =
+  | { readonly status: "resolved"; readonly rects: readonly GeometryRect[]; readonly reason?: string }
+  | { readonly status: "requires-rehydration" | "unavailable"; readonly rects?: undefined; readonly reason?: string };
+
+export interface PresenceOverlayLaneSourceOptions {
+  readonly awareness: PresenceAwarenessSource;
+  readonly localClientId?: number;
+  readonly getRevision?: () => number;
+  readonly projectCursor?: (cursor: RemoteCursorState) => PresenceCursorProjection;
+}
+
+export interface PresenceOverlayLaneSource {
+  getLane(kind: UiOverlayLaneKind): UiOverlayLaneSnapshot;
+  subscribeLane(
+    kind: UiOverlayLaneKind,
+    listener: UiListener<UiOverlayLaneSnapshot>,
+  ): UiUnsubscribe;
+}
+
+function unavailable(kind: UiOverlayLaneKind, reason: string): UiOverlayLaneSnapshot {
+  return Object.freeze({
+    __mock: true,
+    kind,
+    status: "unavailable",
+    entries: Object.freeze([]),
+    revision: 0,
+    source: "unavailable",
+    reason,
+  } as const);
+}
+
+function coerceLaneStatus(
+  current: UiOverlayLaneStatus,
+  next: UiOverlayLaneStatus,
+): UiOverlayLaneStatus {
+  if (current === "unavailable" || next === "unavailable") return "unavailable";
+  if (current === "requires-rehydration" || next === "requires-rehydration") {
+    return "requires-rehydration";
+  }
+  return "resolved";
+}
+
+export function createPresenceOverlayLaneSource(
+  options: PresenceOverlayLaneSourceOptions,
+): PresenceOverlayLaneSource {
+  const localClientId = options.localClientId ?? options.awareness.clientID;
+
+  function readPresenceLane(): UiOverlayLaneSnapshot {
+    const cursors = getRemoteCursorStates(
+      options.awareness as Parameters<typeof getRemoteCursorStates>[0],
+      localClientId,
+    );
+    let laneStatus: UiOverlayLaneStatus = "resolved";
+    const entries = cursors.map((cursor) => {
+      const projection = options.projectCursor?.(cursor) ?? {
+        status: "requires-rehydration" as const,
+        reason: "presence cursor geometry projection is not wired",
+      };
+      laneStatus = coerceLaneStatus(laneStatus, projection.status);
+      return {
+        id: `presence:${cursor.userId}`,
+        status: projection.status,
+        ...(projection.rects ? { rects: projection.rects } : {}),
+        ...(projection.reason ? { reason: projection.reason } : {}),
+        data: {
+          kind: "remote-cursor",
+          userId: cursor.userId,
+          displayName: cursor.displayName,
+          color: cursor.color,
+          anchor: cursor.anchor,
+          head: cursor.head,
+          storyTarget: cursor.storyTarget,
+        },
+      };
+    });
+
+    return {
+      kind: "presence",
+      status: entries.length === 0 ? "resolved" : laneStatus,
+      entries,
+      revision: options.getRevision?.() ?? 0,
+      source: "awareness",
+    };
+  }
+
+  return {
+    getLane(kind: UiOverlayLaneKind): UiOverlayLaneSnapshot {
+      if (kind !== "presence") {
+        return unavailable(kind, "presence lane source only handles kind='presence'");
+      }
+      return readPresenceLane();
+    },
+    subscribeLane(
+      kind: UiOverlayLaneKind,
+      listener: UiListener<UiOverlayLaneSnapshot>,
+    ): UiUnsubscribe {
+      if (kind !== "presence") {
+        throw new Error(`presence lane source only handles kind='presence'; got "${kind}"`);
+      }
+      const onChange = (): void => {
+        listener(readPresenceLane());
+      };
+      options.awareness.on("change", onChange);
+      return () => {
+        options.awareness.off("change", onChange);
+      };
+    },
+  };
+}

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

@@ -54,6 +54,7 @@ import type {
   ChromePosture,
   GeometryRect,
   OverlayAnchorQuery,
+  PageResidencySnapshot,
   UiOverlayLaneKind,
   UiOverlayLaneSnapshot,
   UiController,
@@ -113,6 +114,13 @@ export interface ShellUiControllerDeps {
    * dpr / container-resize. Returns unsubscribe.
    */
   readonly subscribeViewport?: (listener: UiListener<ViewportState>) => UiUnsubscribe;
+  /** PE2 page-residency policy read. */
+  readonly getPageResidency?: (pageIndex: number) => PageResidencySnapshot;
+  /** PE2 page-residency subscription channel. */
+  readonly subscribePageResidency?: (
+    pageIndex: number,
+    listener: UiListener<PageResidencySnapshot>,
+  ) => UiUnsubscribe;
   /**
    * Overlay invalidation stream — fires when geometry invalidation overlaps
    * an attached overlay query (U7). Typically delegated to the render
@@ -154,6 +162,8 @@ export function makeShellUiControllerFactory(
       ...(deps.subscribeChrome ? { subscribeChrome: deps.subscribeChrome } : {}),
       ...(deps.getViewport ? { getViewport: deps.getViewport } : {}),
       ...(deps.subscribeViewport ? { subscribeViewport: deps.subscribeViewport } : {}),
+      ...(deps.getPageResidency ? { getPageResidency: deps.getPageResidency } : {}),
+      ...(deps.subscribePageResidency ? { subscribePageResidency: deps.subscribePageResidency } : {}),
       ...(deps.subscribeOverlays ? { subscribeOverlays: deps.subscribeOverlays } : {}),
       ...(deps.getOverlayLane ? { getOverlayLane: deps.getOverlayLane } : {}),
       ...(deps.subscribeOverlayLane ? { subscribeOverlayLane: deps.subscribeOverlayLane } : {}),