@beyondwork/docx-react-component 1.0.41 → 1.0.43

package/src/runtime/workflow-markup.ts

@@ -22,28 +22,32 @@ import type {
   WorkflowCommentMarkup,
 } from "../api/public-types";
 import { MAIN_STORY_TARGET } from "../core/selection/mapping.ts";
-import { searchSurfaceBlocks } from "../core/search/search-text.ts";
+import {
+  projectSurfaceText,
+  searchProjectedSurfaceText,
+} from "../core/search/search-text.ts";
 import { describeOpaqueFragment, isBlockedImportFeatureKey } from "../preservation/store.ts";
 import type { CanonicalDocumentEnvelope } from "../core/state/editor-state.ts";
 
-export function collectWorkflowMarkupSnapshot(input: {
-  renderSnapshot: RuntimeRenderSnapshot;
-  fieldSnapshot: FieldSnapshot;
-  protectionSnapshot: ProtectionSnapshot;
-  preservation: CanonicalDocumentEnvelope["preservation"];
-  workflowMetadataSnapshot?: WorkflowMetadataSnapshot;
-}): WorkflowMarkupSnapshot {
+/**
+ * Surface-derived markup (highlights + block-level opaque fragments).
+ *
+ * Pure function of `(surface, preservation)` — extracted from
+ * `collectWorkflowMarkupSnapshot` so callers can cache the expensive walk
+ * separately from the cheap reference-equal inputs (metadata, comments,
+ * revisions, protected ranges).
+ */
+export function collectWorkflowSurfaceMarkup(
+  surface: RuntimeRenderSnapshot["surface"],
+  preservation: CanonicalDocumentEnvelope["preservation"],
+): { highlights: WorkflowHighlightMarkup[]; opaqueFragments: WorkflowOpaqueFragmentMarkup[] } {
   const highlights: WorkflowHighlightMarkup[] = [];
-  const metadata = collectWorkflowMetadataMarkup(input.workflowMetadataSnapshot);
-  const fields: WorkflowFieldMarkup[] = [];
   const opaqueFragments: WorkflowOpaqueFragmentMarkup[] = [];
-  const surface = input.renderSnapshot.surface;
-
   if (surface) {
     collectSurfaceMarkup(
       surface.blocks,
       MAIN_STORY_TARGET,
-      input.preservation,
+      preservation,
       highlights,
       opaqueFragments,
     );
@@ -51,16 +55,55 @@ export function collectWorkflowMarkupSnapshot(input: {
       collectSurfaceMarkup(
         story.blocks,
         story.target,
-        input.preservation,
+        preservation,
         highlights,
         opaqueFragments,
       );
     }
+  }
+  return { highlights, opaqueFragments };
+}
 
+export function collectWorkflowMarkupSnapshot(input: {
+  renderSnapshot: RuntimeRenderSnapshot;
+  fieldSnapshot: FieldSnapshot;
+  protectionSnapshot: ProtectionSnapshot;
+  preservation: CanonicalDocumentEnvelope["preservation"];
+  workflowMetadataSnapshot?: WorkflowMetadataSnapshot;
+  surfaceMarkupCache?: {
+    highlights: WorkflowHighlightMarkup[];
+    opaqueFragments: WorkflowOpaqueFragmentMarkup[];
+  };
+  perfStage?: (name: string, durationMs: number) => void;
+}): WorkflowMarkupSnapshot {
+  const perf = input.perfStage;
+  const stageStart = perf ? () => performance.now() : () => 0;
+  const stageEnd = perf ? (name: string, t0: number) => perf(name, performance.now() - t0) : () => {};
+
+  const tMeta = stageStart();
+  const metadata = collectWorkflowMetadataMarkup(input.workflowMetadataSnapshot);
+  stageEnd("metadata", tMeta);
+
+  const fields: WorkflowFieldMarkup[] = [];
+  const surface = input.renderSnapshot.surface;
+
+  const tSurface = stageStart();
+  const surfaceMarkup = input.surfaceMarkupCache ??
+    collectWorkflowSurfaceMarkup(surface, input.preservation);
+  const highlights = surfaceMarkup.highlights.slice();
+  const opaqueFragments = surfaceMarkup.opaqueFragments.slice();
+  stageEnd("surface", tSurface);
+
+  if (surface) {
+    const tFields = stageStart();
     fields.push(...collectFieldMarkup(surface, input.fieldSnapshot));
+    stageEnd("fields", tFields);
   }
+  const tOpaqueRest = stageStart();
   opaqueFragments.push(...collectOpaqueFragmentMarkup(input.preservation, opaqueFragments));
+  stageEnd("opaqueRest", tOpaqueRest);
 
+  const tCommentsEtc = stageStart();
   const comments = input.renderSnapshot.comments.threads.map((thread): WorkflowCommentMarkup => ({
     markupId: `comment:${thread.commentId}`,
     kind: "comment",
@@ -113,6 +156,8 @@ export function collectWorkflowMarkupSnapshot(input: {
       }),
     );
 
+  stageEnd("commentsEtc", tCommentsEtc);
+
   const items: WorkflowMarkupItem[] = [
     ...highlights,
     ...metadata,
@@ -168,6 +213,15 @@ function collectWorkflowMetadataMarkup(
       value: entry.value,
       scopeId: entry.scopeId,
       workItemId: entry.workItemId,
+      // Schema 1.1 — copy external-mode fields through so card-layer code
+      // can detect external entries without re-consulting the entry snapshot.
+      ...(entry.metadataPersistence !== undefined
+        ? { metadataPersistence: entry.metadataPersistence }
+        : {}),
+      ...(entry.storageRef !== undefined ? { storageRef: entry.storageRef } : {}),
+      ...(entry.metadataVersion !== undefined
+        ? { metadataVersion: entry.metadataVersion }
+        : {}),
     } satisfies WorkflowMetadataMarkup];
   });
 }
@@ -294,11 +348,21 @@ function collectFieldMarkup(
     return [];
   }
 
+  // L7 Phase 1.5: project each story's text once up-front. The prior code
+  // called searchSurfaceBlocks per field, which re-projected the entire
+  // surface on every invocation. For the CCEP large-tables fixture this
+  // was ~220 ms per commit. Hoisting the projection out of the per-field
+  // loop collapses that to a single projection per story.
   const stories = [
-    { blocks: surface.blocks, storyTarget: MAIN_STORY_TARGET },
+    {
+      blocks: surface.blocks,
+      storyTarget: MAIN_STORY_TARGET,
+      projection: projectSurfaceText(surface.blocks),
+    },
     ...surface.secondaryStories.map((story) => ({
       blocks: story.blocks,
       storyTarget: story.target,
+      projection: projectSurfaceText(story.blocks),
     })),
   ];
 
@@ -309,7 +373,7 @@ function collectFieldMarkup(
     }
 
     for (const story of stories) {
-      const matches = searchSurfaceBlocks(story.blocks, displayText, { limit: 2 });
+      const matches = searchProjectedSurfaceText(story.projection, displayText, { limit: 2 });
       if (matches.length === 1) {
         const match = matches[0]!;
         return [

package/src/runtime/workflow-rail-segments.ts

@@ -16,14 +16,18 @@ import type {
   EditorAnchorProjection,
   EditorStoryTarget,
   IssueMetadataValue,
+  ReviewActionMetadataValue,
   ScopeCardModel,
+  ScopeMetadataResolver,
+  SuggestionGroup,
+  SuggestionsSnapshot,
   WorkflowBlockedCommandReason,
   WorkflowCandidateRange,
   WorkflowLockedZone,
   WorkflowMetadataMarkup,
   WorkflowScope,
 } from "../api/public-types";
-import { ISSUE_METADATA_ID } from "../api/public-types";
+import { ISSUE_METADATA_ID, REVIEW_ACTION_METADATA_ID } from "../api/public-types";
 import { MAIN_STORY_TARGET, storyTargetsEqual } from "../core/selection/mapping.ts";
 import type { RuntimePageGraph } from "./layout/page-graph.ts";
 import type {
@@ -316,6 +320,41 @@ export interface AttachScopeCardModelInput {
    * rects — chrome consumers fall back to on-render positioning.
    */
   anchorIndex?: RenderAnchorIndex | null;
+  /**
+   * R3 — suggestion snapshot. Groups whose `issueId` matches the
+   * scope's issue attach as `ScopeCardModel.suggestionGroups`; their
+   * ids land in `suggestionGroupIds` as a convenience for consumers
+   * that want a flat lookup.
+   */
+  suggestions?: SuggestionsSnapshot | null;
+  /**
+   * K1-light — review-action markup. Entries with
+   * `metadataId === REVIEW_ACTION_METADATA_ID` whose coerced value's
+   * `issueId` matches the scope's issue attach newest-first as
+   * `ScopeCardModel.reviewActions`.
+   */
+  reviewActionMetadata?: readonly WorkflowMetadataMarkup[];
+  /**
+   * K2 — candidate ranges. Any entry with `source: "ai"` whose
+   * offset range overlaps the segment flips `agentPending` to true.
+   */
+  candidates?: readonly WorkflowCandidateRange[];
+  /**
+   * Pre-resolved external metadata values, keyed by entryId.  When an
+   * entry in `metadata` or `reviewActionMetadata` has
+   * `metadataPersistence === "external"` and its inline `value` is
+   * undefined, this map supplies the resolved value (fetched by the caller
+   * via `ScopeMetadataResolver.resolve`).
+   *
+   * Entries absent from the map render as if the metadata had no value —
+   * the card still shows the scope but drops the issue row, consistent with
+   * how malformed metadata is handled today.
+   *
+   * NOTE: The facet's `getAllScopeCardModels()` does NOT populate this.
+   * Callers that need resolved values build the map via
+   * `buildExternalResolutions()` and call `attachScopeCardModel()` directly.
+   */
+  externalResolutions?: ReadonlyMap<string, { value: Record<string, unknown>; version?: number }>;
 }
 
 /**
@@ -361,11 +400,23 @@ export function attachScopeCardModel(
       segment.scopeId,
       workItemId,
       input.metadata,
+      input.externalResolutions,
     );
     const primaryAnchorRect = input.anchorIndex
       ? input.anchorIndex.bySelection(segment.fromOffset, segment.toOffset)
       : null;
 
+    const suggestionGroups = resolveSuggestionGroupsForIssue(
+      issue?.issueId,
+      input.suggestions,
+    );
+    const reviewActions = resolveReviewActionsForIssue(
+      issue?.issueId,
+      input.reviewActionMetadata,
+      input.externalResolutions,
+    );
+    const agentPending = resolveAgentPending(segment, input.candidates);
+
     models.push({
       scopeId: segment.scopeId,
       ...(workItemId ? { workItemId } : {}),
@@ -373,19 +424,103 @@ export function attachScopeCardModel(
       posture: segment.posture,
       primaryAnchorRect,
       ...(issue ? { issue } : {}),
-      suggestionGroupIds: [],
-      reviewActionCount: 0,
-      agentPending: false,
+      suggestionGroupIds: suggestionGroups.map((group) => group.groupId),
+      suggestionGroups,
+      reviewActionCount: reviewActions.length,
+      reviewActions,
+      agentPending,
     });
   }
 
   return models;
 }
 
+function resolveSuggestionGroupsForIssue(
+  issueId: string | undefined,
+  suggestions: SuggestionsSnapshot | null | undefined,
+): SuggestionGroup[] {
+  if (!issueId || !suggestions?.groups) return [];
+  return suggestions.groups.filter((group) => group.issueId === issueId);
+}
+
+function resolveReviewActionsForIssue(
+  issueId: string | undefined,
+  metadata: readonly WorkflowMetadataMarkup[] | undefined,
+  externalResolutions?: ReadonlyMap<string, { value: Record<string, unknown>; version?: number }>,
+): ReviewActionMetadataValue[] {
+  if (!issueId || !metadata || metadata.length === 0) return [];
+  const result: ReviewActionMetadataValue[] = [];
+  for (const entry of metadata) {
+    if (entry.metadataId !== REVIEW_ACTION_METADATA_ID) continue;
+    const coerced = coerceReviewActionValue(effectiveMetadataValue(entry, externalResolutions));
+    if (!coerced) continue;
+    if (coerced.issueId !== issueId) continue;
+    result.push(coerced);
+  }
+  // Newest-first by createdAt ISO string (lexicographic for 8601 UTC).
+  result.sort((a, b) => (a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0));
+  return result;
+}
+
+function coerceReviewActionValue(
+  value: unknown,
+): ReviewActionMetadataValue | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const candidate = value as Partial<ReviewActionMetadataValue>;
+  if (
+    typeof candidate.reviewActionId !== "string" ||
+    typeof candidate.action !== "string" ||
+    typeof candidate.actor !== "string" ||
+    typeof candidate.actorRole !== "string" ||
+    typeof candidate.createdAt !== "string"
+  ) {
+    return undefined;
+  }
+  return candidate as ReviewActionMetadataValue;
+}
+
+function resolveAgentPending(
+  segment: ScopeRailSegment,
+  candidates: readonly WorkflowCandidateRange[] | undefined,
+): boolean {
+  if (!candidates || candidates.length === 0) return false;
+  for (const candidate of candidates) {
+    if (candidate.source !== "ai") continue;
+    const range = anchorToRuntimeRange(candidate.anchor);
+    if (!range) continue;
+    // Strict-half-open overlap: [from, to).
+    if (range.to > segment.fromOffset && range.from < segment.toOffset) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Return the effective value for a metadata markup entry.  For
+ * internal-mode entries (or entries with an inline value), returns
+ * `entry.value` directly.  For external-mode entries whose inline
+ * `value` is undefined, looks up the resolved value from the
+ * caller-supplied `externalResolutions` map keyed by `entryId`.
+ *
+ * Returns `undefined` when no value is available — callers treat this the
+ * same as malformed metadata and drop the card row silently.
+ */
+function effectiveMetadataValue(
+  entry: WorkflowMetadataMarkup,
+  externalResolutions?: ReadonlyMap<string, { value: Record<string, unknown>; version?: number }>,
+): Record<string, unknown> | undefined {
+  if (entry.value !== undefined) return entry.value;
+  // External-mode entry — inline body is empty. Look up the resolved value.
+  const resolved = externalResolutions?.get(entry.entryId);
+  return resolved?.value;
+}
+
 function resolveIssueForScope(
   scopeId: string,
   workItemId: string | undefined,
   metadata: readonly WorkflowMetadataMarkup[] | undefined,
+  externalResolutions?: ReadonlyMap<string, { value: Record<string, unknown>; version?: number }>,
 ): IssueMetadataValue | undefined {
   if (!metadata || metadata.length === 0) return undefined;
   for (const entry of metadata) {
@@ -397,7 +532,7 @@ function resolveIssueForScope(
     const matchesScope =
       entry.scopeId !== undefined && entry.scopeId === scopeId;
     if (!matchesWorkItem && !matchesScope) continue;
-    const coerced = coerceIssueValue(entry.value);
+    const coerced = coerceIssueValue(effectiveMetadataValue(entry, externalResolutions));
     if (coerced) return coerced;
   }
   return undefined;
@@ -426,3 +561,107 @@ function coerceIssueValue(
   }
   return candidate as IssueMetadataValue;
 }
+
+// ---------------------------------------------------------------------------
+// buildExternalResolutions — caller utility for pre-resolving external refs
+// ---------------------------------------------------------------------------
+
+/**
+ * Structured result from `buildExternalResolutions`.  Callers that previously
+ * consumed the return value as a `Map` directly must now destructure `.resolutions`.
+ */
+export interface BuildExternalResolutionsResult {
+  /**
+   * Resolved values keyed by `entryId`.  Suitable for passing into
+   * `AttachScopeCardModelInput.externalResolutions`.
+   */
+  resolutions: Map<string, { value: Record<string, unknown>; version?: number }>;
+  /**
+   * Detected version mismatches.  Non-empty only when the caller passes
+   * `detectConflicts: true`.  Each record includes both sides' value +
+   * version so the caller can emit a `metadata_conflict_detected` event.
+   */
+  conflicts: Array<{
+    scopeId?: string;
+    entryId?: string;
+    embedded: { value?: Record<string, unknown>; version?: number } | null;
+    external: { value?: Record<string, unknown>; version?: number } | null;
+  }>;
+}
+
+/**
+ * Pre-resolve every external-mode metadata entry's value via the supplied
+ * resolver.  The returned `resolutions` map is suitable for passing into
+ * `AttachScopeCardModelInput.externalResolutions`.
+ *
+ * Internal-mode entries (where `entry.value` is already inline) are skipped.
+ * When the resolver returns `undefined` for a ref (unknown or revoked), the
+ * `entryId` is omitted from the map; the scope card then renders without that
+ * value.
+ *
+ * Both `metadata` and `reviewActionMetadata` arrays are walked so review-action
+ * rows stored externally are resolved alongside issue entries.
+ *
+ * When `detectConflicts` is `true`, the helper compares each entry's embedded
+ * `metadataVersion` against the resolver-returned version.  Any mismatch is
+ * recorded in the returned `conflicts` array.
+ *
+ * NOTE: This helper is intentionally async so callers can `await` it in the
+ * React layer before passing the map to the synchronous `attachScopeCardModel`.
+ * The layout facet's `getAllScopeCardModels()` does NOT call this — it is a
+ * React-layer concern where async is normal.
+ */
+export async function buildExternalResolutions(input: {
+  metadata: readonly WorkflowMetadataMarkup[];
+  reviewActionMetadata?: readonly WorkflowMetadataMarkup[];
+  resolver: ScopeMetadataResolver;
+  /**
+   * When `true`, the helper compares each external entry's embedded
+   * `metadataVersion` against the resolver-returned version and records a
+   * conflict for every mismatch.  Absent / `false` → `conflicts` is always
+   * empty (backwards-compatible default).
+   */
+  detectConflicts?: boolean;
+}): Promise<BuildExternalResolutionsResult> {
+  const externalEntries = [
+    ...input.metadata,
+    ...(input.reviewActionMetadata ?? []),
+  ].filter(
+    (entry) =>
+      entry.metadataPersistence === "external" &&
+      entry.value === undefined &&
+      entry.storageRef !== undefined,
+  );
+
+  const results = await Promise.all(
+    externalEntries.map(async (entry) => {
+      const resolved = await input.resolver.resolve(entry.storageRef!);
+      return resolved ? { entry, resolved } : null;
+    }),
+  );
+
+  const resolutions = new Map<string, { value: Record<string, unknown>; version?: number }>();
+  const conflicts: BuildExternalResolutionsResult["conflicts"] = [];
+
+  for (const row of results) {
+    if (!row) continue;
+    resolutions.set(row.entry.entryId, row.resolved);
+
+    if (
+      input.detectConflicts &&
+      row.entry.metadataVersion !== undefined &&
+      row.resolved.version !== undefined &&
+      row.entry.metadataVersion !== row.resolved.version
+    ) {
+      conflicts.push({
+        scopeId: row.entry.scopeId,
+        entryId: row.entry.entryId,
+        // External entries have no inline value — embedded side carries only version
+        embedded: { version: row.entry.metadataVersion },
+        external: { value: row.resolved.value, version: row.resolved.version },
+      });
+    }
+  }
+
+  return { resolutions, conflicts };
+}