@beyondwork/docx-react-component 1.0.41 → 1.0.42

package/src/api/public-types.ts

@@ -3,6 +3,19 @@ import type { CanonicalParagraphFormatting, CanonicalRunFormatting } from "../mo
 import type { WordReviewEditorLayoutFacet } from "../runtime/layout/public-facet.ts";
 import type { RenderFrameRect } from "../runtime/render/index.ts";
 import type { ScopeRailPosture } from "../runtime/workflow-rail-segments.ts";
+import type {
+  MetadataPersistenceMode,
+  ScopeMetadataPersistence,
+  ScopeMetadataResolver,
+  ScopeMetadataStorageRef,
+} from "./scope-metadata-resolver-types.ts";
+
+export type {
+  MetadataPersistenceMode,
+  ScopeMetadataPersistence,
+  ScopeMetadataResolver,
+  ScopeMetadataStorageRef,
+};
 
 export type { CanonicalParagraphFormatting, CanonicalRunFormatting };
 
@@ -360,6 +373,38 @@ export interface SuggestionEntrySnapshot {
   preserveOnlyReason?: string;
   excerpt?: string;
   detail?: string;
+  /**
+   * R3 — scope-card-overlay P2. When present, links this entry to a
+   * `SuggestionGroup` via `SuggestionsSnapshot.groups[].groupId`.
+   * A single issue may fan out to multiple suggestions via the group.
+   */
+  groupId?: string;
+  /**
+   * R3 — origin of the suggestion's rationale (used by the card's
+   * suggestion row for attribution hints).
+   */
+  rationaleSource?: "playbook" | "agent" | "host" | "user";
+  /**
+   * R3 — tier within a preferred/fallback_1/fallback_2/escalate_only
+   * ladder.  Hosts render this as the chip label in the scope card.
+   */
+  tier?: "preferred" | "fallback_1" | "fallback_2" | "escalate_only";
+}
+
+/**
+ * R3 — scope-card-overlay P2.  Groups `SuggestionEntrySnapshot`
+ * entries under a single issue so the scope card exposes atomic
+ * accept/reject actions.  One issue → N suggestions → N revisions on
+ * accept, committed as a single runtime transaction.
+ */
+export interface SuggestionGroup {
+  groupId: string;
+  issueId?: string;
+  ruleId?: string;
+  rationale?: string;
+  severity?: IssueSeverity;
+  tier?: "preferred" | "fallback_1" | "fallback_2" | "escalate_only";
+  suggestionIds: string[];
 }
 
 export interface SuggestionsSnapshot {
@@ -371,6 +416,8 @@ export interface SuggestionsSnapshot {
   rejectedSuggestionIds: string[];
   detachedSuggestionIds: string[];
   suggestions: SuggestionEntrySnapshot[];
+  /** R3 — optional groups keying into `suggestions` by `groupId`. */
+  groups?: SuggestionGroup[];
 }
 
 export type FormattingAlignment = "left" | "center" | "right" | "justify";
@@ -1622,12 +1669,31 @@ export interface WorkflowScope {
   domain?: "legal" | "commercial" | "finance" | "other";
   metadataRefs?: string[];
   metadata?: WorkflowScopeMetadataField[];
+  /**
+   * Schema 1.1 — override the overlay default for this scope.
+   * `"inherit"` defers to the overlay; absent is equivalent to
+   * `"inherit"`.
+   */
+  metadataPersistence?: ScopeMetadataPersistence;
 }
 
 export interface WorkflowScopeMetadataField {
   key: string;
   valueType?: "string" | "number" | "boolean" | "json";
   value?: string | number | boolean | Record<string, unknown>;
+  /**
+   * Schema 1.1 — per-field override. Resolution order:
+   * field > scope > overlay > "internal" default.
+   */
+  metadataPersistence?: ScopeMetadataPersistence;
+  storageRef?: ScopeMetadataStorageRef;
+  /**
+   * Schema 1.1 — monotonically-increasing version hint.  Internal-mode
+   * writes bump this; external-mode writes read it from the
+   * resolver's `publish` result.  Used by readers to detect divergence
+   * between embedded and resolver-returned values.
+   */
+  metadataVersion?: number;
 }
 
 export interface WorkflowWorkItem {
@@ -1645,6 +1711,12 @@ export interface WorkflowOverlay {
   scopes: WorkflowScope[];
   workItems?: WorkflowWorkItem[];
   activeWorkItemId?: string | null;
+  /**
+   * Schema 1.1 — overlay-level default for metadata persistence. When
+   * absent, readers treat as `"internal"`. Per-scope / per-entry /
+   * per-field overrides can opt in or out of the default.
+   */
+  metadataPersistence?: MetadataPersistenceMode;
 }
 
 export type WorkflowMetadataPersistence =
@@ -1670,6 +1742,23 @@ export interface WorkflowMetadataEntry {
   value?: Record<string, unknown>;
   scopeId?: string;
   workItemId?: string;
+  /**
+   * Schema 1.1 — per-entry override. `"inherit"` (or absent) defers
+   * to the effective scope or overlay default.
+   */
+  metadataPersistence?: ScopeMetadataPersistence;
+  /**
+   * Schema 1.1 — opaque host reference when effective persistence
+   * resolves to `"external"`. Absent when inline.
+   */
+  storageRef?: ScopeMetadataStorageRef;
+  /**
+   * Schema 1.1 — monotonically-increasing version hint.  Internal-mode
+   * writes bump this; external-mode writes read it from the
+   * resolver's `publish` result.  Used by readers to detect divergence
+   * between embedded and resolver-returned values.
+   */
+  metadataVersion?: number;
 }
 
 export interface WorkflowMetadataSnapshot {
@@ -1748,6 +1837,41 @@ export type ScopeIssueAction =
   | "escalate"
   | "acknowledge";
 
+// ---------------------------------------------------------------------------
+// K1-light — review-action audit trail (scope-card-overlay P2)
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonical metadata id for append-only review actions.  Hosts push
+ * one `WorkflowMetadataEntry` per review decision; the scope card's
+ * timeline reads entries whose value matches the attached issue.
+ *
+ * Round-trip through `src/io/ooxml/workflow-payload.ts` lands with a
+ * later K1 phase; for P2 the entries live in the session snapshot.
+ */
+export const REVIEW_ACTION_METADATA_ID =
+  "workflow.metadata.review_action" as const;
+
+export type ReviewActionKind =
+  | "include"
+  | "edit"
+  | "discard"
+  | "escalate"
+  | "acknowledge"
+  | "resolve"
+  | "waive";
+
+export interface ReviewActionMetadataValue {
+  reviewActionId: string;
+  action: ReviewActionKind;
+  actor: string;
+  actorRole: IssueOwner | "agent";
+  issueId?: string;
+  suggestedRedlineId?: string;
+  payload?: Record<string, unknown>;
+  createdAt: string;
+}
+
 /**
  * Scope card projection consumed by the chrome overlay's card layer.
  * Joins a `WorkflowScope` with its attached issue metadata (R2),
@@ -1765,11 +1889,19 @@ export interface ScopeCardModel {
   label: string;
   primaryAnchorRect: RenderFrameRect | null;
   issue?: IssueMetadataValue;
-  /** R3 suggestion groups attached to the scope. P2 populates; P1 = []. */
+  /** Id-only lookup; `suggestionGroups` holds the full entries. */
   suggestionGroupIds: readonly string[];
-  /** K1 review-action count for the scope's issue. P2 populates; P1 = 0. */
+  /** R3 — full group entries attached to the scope's issue. */
+  suggestionGroups: readonly SuggestionGroup[];
+  /** K1 — count of review actions attached to the scope's issue. */
   reviewActionCount: number;
-  /** K2 agent-pending flag (overlapping WorkflowCandidateRange source:"ai"). P2 populates; P1 = false. */
+  /** K1 — newest-first review-action entries for the card timeline. */
+  reviewActions: readonly ReviewActionMetadataValue[];
+  /**
+   * K2 — true when a `WorkflowCandidateRange` with `source: "ai"`
+   * overlaps the scope.  Drives the rail-layer's agent-pending
+   * shimmer.
+   */
   agentPending: boolean;
 }
 
@@ -1863,6 +1995,25 @@ export interface WorkflowMetadataMarkup extends WorkflowMarkupBase {
   value?: Record<string, unknown>;
   scopeId?: string;
   workItemId?: string;
+  /**
+   * Schema 1.1 — mirrors `WorkflowMetadataEntry.metadataPersistence`.
+   * Lets the card layer detect external entries without re-consulting the
+   * entry snapshot.  `"external"` means the inline `value` is empty and the
+   * real value lives in the host rowstore; `"internal"` (or absent) means
+   * `value` is the authoritative copy.
+   */
+  metadataPersistence?: ScopeMetadataPersistence;
+  /**
+   * Schema 1.1 — opaque host reference when `metadataPersistence === "external"`.
+   * Passed verbatim to `ScopeMetadataResolver.resolve`; the editor never
+   * parses this string.
+   */
+  storageRef?: ScopeMetadataStorageRef;
+  /**
+   * Schema 1.1 — monotonically-increasing version hint.  Used by readers to
+   * detect divergence between the embedded value and the resolver-returned one.
+   */
+  metadataVersion?: number;
 }
 
 export interface WorkflowCommentMarkup extends WorkflowMarkupBase {
@@ -2314,6 +2465,61 @@ export type WordReviewEditorEvent =
       scopeId: string;
       issueId: string;
       action: ScopeIssueAction;
+    }
+  | {
+      /**
+       * K2 — scope card "Ask review agent" was clicked.  Host routes
+       * the request to the CCEP contract review agent (or equivalent)
+       * with the scope's anchor + story + surrounding text; when the
+       * agent responds, the host pushes an issue + suggestion group
+       * through the existing R2/R3 paths and clears any
+       * `WorkflowCandidateRange` it used as the pending marker.
+       */
+      type: "agent-on-selection-requested";
+      documentId: string;
+      requestId: string;
+      scopeId?: string;
+      anchor: EditorAnchorProjection;
+      storyTarget?: EditorStoryTarget;
+      selectionText: string;
+      surroundingText?: string;
+      reviewSessionId?: string;
+    }
+  | {
+      type: "metadata_persistence_mode_changed";
+      documentId: string;
+      mode: MetadataPersistenceMode;
+    }
+  | {
+      /**
+       * Emitted when a per-scope persistence override changes. `scopeId`
+       * is `"*"` when `setAllScopesMetadataPersistence` fires the event.
+       */
+      type: "scope_metadata_persistence_changed";
+      documentId: string;
+      scopeId: string;
+      persistence: ScopeMetadataPersistence;
+    }
+  | {
+      /**
+       * Emitted when the editor detects divergence between the
+       * docx-embedded value / version and the resolver-returned
+       * value / version.  Host resolves via `resolveMetadataConflict`.
+       */
+      type: "metadata_conflict_detected";
+      documentId: string;
+      scopeId?: string;
+      entryId?: string;
+      fieldKey?: string;
+      embedded: {
+        value?: Record<string, unknown>;
+        version?: number;
+      } | null;
+      external: {
+        value?: Record<string, unknown>;
+        version?: number;
+      } | null;
+      defaultPolicy: MetadataConflictPolicy;
     };
 
 export interface LoadResult {
@@ -2385,6 +2591,16 @@ export interface WordReviewEditorRef {
   rejectChange(changeId: string): void;
   acceptAllChanges(): void;
   rejectAllChanges(): void;
+  /**
+   * R3 — scope-card-overlay P2.  Accept every `changeId` attached to
+   * the group's `suggestionIds` as a single logical action.  The
+   * runtime batches the individual `acceptChange` calls inside one
+   * commit boundary so the group lands atomically.  No-op when the
+   * group id is not present in the current `SuggestionsSnapshot`.
+   */
+  acceptSuggestionGroup(groupId: string): void;
+  /** R3 — rejects every member of the group. */
+  rejectSuggestionGroup(groupId: string): void;
   exportDocx(options?: ExportDocxOptions): Promise<ExportResult>;
   getSessionState(): EditorSessionState;
   getSnapshot(): PersistedEditorSnapshot;
@@ -2495,6 +2711,62 @@ export interface WordReviewEditorRef {
   setWorkflowMetadataEntries(entries: WorkflowMetadataEntry[]): void;
   clearWorkflowMetadataEntries(): void;
   getWorkflowMetadataSnapshot(): WorkflowMetadataSnapshot;
+  /**
+   * Schema 1.1 — set the overlay default for metadata persistence.
+   * Author-only per collab-master-plan §7 role-gating matrix;
+   * observers / reviewers receive `command_blocked` with
+   * `collab_role_restricted`. Throws `MetadataResolverMissingError`
+   * synchronously when called with `"external"` before a resolver has
+   * been registered via `setScopeMetadataResolver`.
+   */
+  setMetadataPersistenceMode(mode: MetadataPersistenceMode): void;
+  getMetadataPersistenceMode(): MetadataPersistenceMode;
+  /**
+   * Toggle a single scope's persistence override. Reviewers may toggle
+   * scopes they own (`workItemId` matches their active work item);
+   * authors may toggle any scope.
+   */
+  setScopeMetadataPersistence(
+    scopeId: string,
+    persistence: ScopeMetadataPersistence,
+  ): void;
+  getScopeMetadataPersistence(scopeId: string): ScopeMetadataPersistence;
+  /**
+   * Bulk toggle — apply `persistence` to every scope in the active
+   * overlay. Author-only. `"inherit"` clears all per-scope overrides so
+   * scopes fall back to the overlay default.
+   */
+  setAllScopesMetadataPersistence(persistence: ScopeMetadataPersistence): void;
+  /**
+   * Register (or clear) the host-supplied resolver. Must be set before
+   * any external-mode operation; if absent, switching to `"external"`
+   * throws `MetadataResolverMissingError` synchronously.
+   */
+  setScopeMetadataResolver(resolver: ScopeMetadataResolver | null): void;
+  /**
+   * Resolve a pending `metadata_conflict_detected` event.  The host
+   * picks a `choice` and the editor writes the chosen value back
+   * through the normal overlay-mutation path + re-sign.
+   */
+  resolveMetadataConflict(input: ResolveMetadataConflictInput): void;
+  /**
+   * Migrate external-mode entries on the listed scopes back to
+   * internal: for each entry / field whose effective persistence is
+   * `"external"`, call `resolver.resolve(ref)`, inline the returned
+   * value, clear `storageRef`, preserve `metadataVersion` as a hint.
+   * Call this before exporting a docx outside the resolver's reach
+   * (e.g., sending to an external supplier).
+   */
+  convertScopesToInternal(scopeIds: string[]): Promise<void>;
+  /**
+   * Migrate internal-mode entries on the listed scopes to external:
+   * for each entry / field whose effective persistence is
+   * `"internal"`, call `resolver.publish(...)`, set `storageRef` +
+   * `metadataVersion` from the return value, clear the inline body.
+   * Throws `MetadataResolverMissingError` when no resolver is
+   * registered.
+   */
+  convertScopesToExternal(scopeIds: string[]): Promise<void>;
   setHostAnnotationOverlay(overlay: HostAnnotationOverlay): void;
   clearHostAnnotationOverlay(): void;
   getHostAnnotationSnapshot(): HostAnnotationSnapshot;
@@ -2547,7 +2819,8 @@ export type WordReviewEditorChromePreset =
   | "simple"
   | "advanced"
   | "review"
-  | "workflow";
+  | "workflow"
+  | "collab";
 
 export interface WordReviewEditorChromeOptions {
   /**
@@ -2566,6 +2839,26 @@ export interface WordReviewEditorChromeOptions {
    */
   showSectionTagAction: boolean;
   showReviewRail: boolean;
+  /**
+   * Collab preset (P9a). When `true` the chrome mounts the collab
+   * top nav: presence strip, role + audience chips, tamper banner,
+   * negotiation action bar, and send-to-supplier button. Requires a
+   * `CollabSession` to be wired via the host; the components are
+   * defensive and render empty / disabled when the session is
+   * absent or detached.
+   */
+  showCollabTopNav?: boolean;
+  /** Collab preset (P9b) — presence strip sub-visibility flag. */
+  showCollabPresenceStrip?: boolean;
+  /** Collab preset (P9c) — role + audience chips. */
+  showCollabRoleChip?: boolean;
+  showCollabAudienceChip?: boolean;
+  /** Collab preset (P9d) — metadata-tamper banner. */
+  showCollabTamperBanner?: boolean;
+  /** Collab preset (P9e) — per-state negotiation action bar. */
+  showCollabNegotiationActionBar?: boolean;
+  /** Collab preset (P9f) — "Send to supplier" button + modal. */
+  showCollabSendToSupplier?: boolean;
 }
 
 export interface WordReviewEditorProps {
@@ -2670,3 +2963,53 @@ export interface TextCommandAck {
   /** Tag touches the runtime applied so the lane can redraw decorations without a PM rebuild. */
   scopeTagTouches?: readonly ScopeTagTouch[];
 }
+
+// ---------------------------------------------------------------------------
+// Schema 1.1 — metadata-persistence conflict types (P17 Task 3b)
+// ---------------------------------------------------------------------------
+
+/**
+ * How the host wants `metadata_conflict_detected` events resolved by
+ * default.  `"prompt"` means the host handles each event manually
+ * (e.g., show a dialog); the other three let the editor compute a
+ * default choice and suggest it in the event's `defaultPolicy` field.
+ */
+export type MetadataConflictPolicy =
+  | "prefer-embedded"
+  | "prefer-external"
+  | "prefer-latest"
+  | "prompt";
+
+/**
+ * Input shape for `WordReviewEditorRef.resolveMetadataConflict`.
+ * At least one of `scopeId` / `entryId` / `fieldKey` MUST be set — it
+ * identifies which pending conflict to resolve.  `choice` is the
+ * host's final decision; `mergedValue` is only consulted when
+ * `choice === "merge"`.
+ */
+export interface ResolveMetadataConflictInput {
+  scopeId?: string;
+  entryId?: string;
+  fieldKey?: string;
+  choice: "embedded" | "external" | "merge";
+  mergedValue?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Schema 1.1 — metadata-persistence errors (P17)
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown synchronously when a caller switches to `"external"` persistence
+ * mode before registering a host resolver via `setScopeMetadataResolver`.
+ * Follows the fail-closed policy in collab-master-plan §1.6.
+ */
+export class MetadataResolverMissingError extends Error {
+  constructor() {
+    super(
+      "setMetadataPersistenceMode('external') requires a resolver — call " +
+        "setScopeMetadataResolver(...) first.",
+    );
+    this.name = "MetadataResolverMissingError";
+  }
+}

package/src/api/scope-metadata-resolver-types.ts

@@ -0,0 +1,88 @@
+/**
+ * Metadata persistence mode — overlay-level default.
+ *
+ * - `"internal"`: every entry / field is inlined in the bw:workflowPayload
+ *   XML body. Self-contained docx; no host callback required.
+ * - `"external"`: entries / fields are stored by reference via a host-owned
+ *   ScopeMetadataResolver; the docx carries only a `storageRef` string.
+ *
+ * Unknown values → preserve-only (spec §8.2). Readers must never silently
+ * coerce to a known value.
+ */
+export type MetadataPersistenceMode = "internal" | "external";
+
+/**
+ * Per-scope / per-entry / per-field override. `"inherit"` defers to the
+ * parent (entry inherits scope; scope inherits overlay; overlay inherits
+ * the default `"internal"`).
+ */
+export type ScopeMetadataPersistence = "internal" | "external" | "inherit";
+
+/**
+ * Opaque host-owned reference for externally-stored metadata values. The
+ * editor never parses this string — it is passed verbatim to the
+ * resolver. Host examples:
+ *
+ *   "clm-workblock-row:wb-123:row-42:v-3"
+ *   "https://rowstore.internal/metadata/abc"
+ *   "s3://bucket/tenant-1/scope-metadata/e91a.json"
+ */
+export type ScopeMetadataStorageRef = string;
+
+/**
+ * Host-supplied resolver. The editor calls `resolve` whenever it needs
+ * the actual value of an external entry / field; it calls `publish` when
+ * toggling a scope / entry from `"internal"` to `"external"` and needs
+ * to hand the current inline value off to the host's store.
+ *
+ * All methods are async so the host can make network calls. An
+ * `undefined` return from `resolve` signals a missing or revoked ref;
+ * the editor surfaces this as a non-fatal warning and renders the entry
+ * as detached in the scope card. `undefined` (rather than `null`)
+ * matches the shipped `ExternalCustodyResolver.restore` convention (P7).
+ *
+ * `delete` is optional — hosts that don't need cleanup on toggle may
+ * omit it. The editor only calls it when transitioning a scope from
+ * `"external"` back to `"internal"` (hand the value back inline, then
+ * release the ref).
+ */
+export interface ScopeMetadataResolver {
+  /**
+   * Fetch the value for an opaque storageRef.  Returns `undefined`
+   * when the ref is unknown or revoked — the editor surfaces this as
+   * a non-fatal warning and renders the entry as detached in the
+   * scope card.  `version` (when present) is the rowstore's current
+   * version; the editor compares it against the docx's embedded
+   * `metadataVersion` hint and emits `metadata_conflict_detected` on
+   * mismatch.  Matches the `ExternalCustodyResolver.restore`
+   * convention (P7) — prefer `undefined` over `null` for consistency.
+   */
+  resolve(ref: ScopeMetadataStorageRef): Promise<
+    | { value: Record<string, unknown>; version?: number }
+    | undefined
+  >;
+
+  /**
+   * Publish an inline value to the host store.  `expectedVersion`
+   * (when set) enables optimistic concurrency: the host rejects the
+   * write if the stored row has advanced past the expected version,
+   * throwing a host-defined error that the editor surfaces via
+   * `metadata_conflict_detected`.
+   *
+   * Returns the opaque ref plus the version the store recorded for
+   * this write.  The editor embeds this version on the XML element.
+   */
+  publish(input: {
+    scopeId: string;
+    metadataId: string;
+    entryId?: string;
+    fieldKey?: string;
+    value: Record<string, unknown>;
+    expectedVersion?: number;
+  }): Promise<{
+    ref: ScopeMetadataStorageRef;
+    version: number;
+  }>;
+
+  delete?(ref: ScopeMetadataStorageRef): Promise<void>;
+}

package/src/core/commands/formatting-commands.ts

@@ -188,7 +188,7 @@ type ToggleFormattingMark =
   | "strikethrough"
   | "superscript"
   | "subscript";
-type FormattingOperation =
+export type FormattingOperation =
   | { type: "toggle"; mark: ToggleFormattingMark }
   | { type: "set-font-family"; fontFamily: string | null }
   | { type: "set-font-size"; size: number | null }