@beyondwork/docx-react-component 1.0.41 → 1.0.43

package/src/api/public-types.ts

@@ -3,6 +3,47 @@ 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";
+import type {
+  EditorStateNamespace,
+  EditorStateLocation,
+  EditorStateResolveErrorMode,
+  EditorStatePolicyEntry,
+  EditorStatePolicy,
+  EditorStateStorageRef,
+  EditorStateBlob,
+  EditorStateResolver,
+  EditorStatePersister,
+  EditorStatePolicyMigration,
+  EditorStatePartLoadFailure,
+  EditorStatePartPersistFailure,
+} from "./editor-state-types.ts";
+
+export type {
+  MetadataPersistenceMode,
+  ScopeMetadataPersistence,
+  ScopeMetadataResolver,
+  ScopeMetadataStorageRef,
+};
+export type {
+  EditorStateNamespace,
+  EditorStateLocation,
+  EditorStateResolveErrorMode,
+  EditorStatePolicyEntry,
+  EditorStatePolicy,
+  EditorStateStorageRef,
+  EditorStateBlob,
+  EditorStateResolver,
+  EditorStatePersister,
+  EditorStatePolicyMigration,
+  EditorStatePartLoadFailure,
+  EditorStatePartPersistFailure,
+};
 
 export type { CanonicalParagraphFormatting, CanonicalRunFormatting };
 
@@ -21,6 +62,8 @@ export type {
   PublicPageRegion,
   PublicPageRegions,
   PublicPageSpan,
+  PublicRegionBlock,
+  PublicRegionKind,
   PublicResolvedPageStories,
   PublicResolvedParagraphFormatting,
   PublicResolvedRunFormatting,
@@ -360,6 +403,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 +446,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";
@@ -706,7 +783,7 @@ export type SurfaceInlineSegment =
         textColor?: string;
       };
       hyperlinkHref?: string;
-      /** Cascaded run formatting for this text segment (docDefaults → paragraph style chain → character style → direct). Added in Task 11. TODO Task 15: wire up from resolveEffectiveRunFormatting in surface-projection. */
+      /** Cascaded run formatting for this text segment (docDefaults → paragraph style chain → character style → direct). Populated in `src/runtime/surface-projection.ts` via `resolveEffectiveRunFormatting`. Present only when the resolved cascade has at least one field. */
       resolvedRunFormatting?: CanonicalRunFormatting;
     }
   | {
@@ -740,6 +817,14 @@ export type SurfaceInlineSegment =
       blockedReasonCode?: "workflow_preserve_only" | "workflow_blocked_import";
       presentation?: "inline-chip" | "quiet-marker" | "text-box" | "checkbox";
       displayText?: string;
+      /**
+       * For chart/SmartArt/WordArt/VML opaque inlines, the media-catalog id
+       * of the preview bitmap extracted from `mc:Fallback` (when Word cached
+       * one). Resolved by the surface into a blob URL and rendered by the
+       * corresponding PM atom so reviewers see the chart picture instead of
+       * a text badge. Absent when the object has no cached fallback image.
+       */
+      previewMediaId?: string;
       state: "locked-preserve-only";
     }
   | {
@@ -1622,12 +1707,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 +1749,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 +1780,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 +1875,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 +1927,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 +2033,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 {
@@ -2148,6 +2337,25 @@ export interface AutosaveConfig {
   debounceMs?: number;
 }
 
+/**
+ * Fired after a plain-text paste or drop has been dispatched through
+ * the runtime-owned input callbacks. Rich-text paste (HTML, Office
+ * clipboard) does NOT produce this event — those payloads still fire
+ * `onBlockedInput` with a distinguishing message.
+ *
+ * See `docs/plans/editor-paste-drop.md` for the full semantics.
+ */
+export interface WordReviewEditorPasteEvent {
+  type: "paste_applied";
+  documentId: string;
+  /** Count of segments dispatched across text + split + hard_break. */
+  segmentCount: number;
+  /** Total character count across all text segments in the payload. */
+  charCount: number;
+  /** Whether the event originated from a paste or a drop. */
+  source: "paste" | "drop";
+}
+
 export type WordReviewEditorEvent =
   | {
       type: "ready";
@@ -2291,6 +2499,7 @@ export type WordReviewEditorEvent =
       command: string;
       reasons: WorkflowBlockedCommandReason[];
     }
+  | WordReviewEditorPasteEvent
   | {
       /**
        * Scope card mode selector fired a mode change. Host relays to the
@@ -2314,8 +2523,137 @@ 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;
+    }
+  | {
+      /**
+       * Schema 1.2 — emitted when a keyed namespace fails to resolve
+       * during load.  Subsystem fallback behavior is per `onResolveError`
+       * policy.
+       */
+      type: "editor_state_part_load_failed";
+      documentId: string;
+      failure: EditorStatePartLoadFailure;
+    }
+  | {
+      /**
+       * Schema 1.2 — emitted when a debounced persist call fails.
+       * The editor retains the dirty snapshot for retry.
+       */
+      type: "editor_state_part_persist_failed";
+      documentId: string;
+      failure: EditorStatePartPersistFailure;
+    }
+  | {
+      /**
+       * Schema 1.2 — emitted when the saved location in a docx differs
+       * from the current host policy; the current policy wins and the
+       * next serialize honors it.
+       */
+      type: "editor_state_policy_migrated";
+      documentId: string;
+      migration: EditorStatePolicyMigration;
+    }
+  | {
+      /**
+       * Schema 1.2 — emitted when an unknown namespace is encountered
+       * in the payload (forward-compat warning; preserved opaquely).
+       */
+      type: "editor_state_unknown_namespace";
+      documentId: string;
+      namespace: string;
+    }
+  | {
+      /**
+       * Emitted once per load-pipeline stage when the staged loader is
+       * active. Purely observational — hosts can render a progress chip
+       * or ignore entirely. See `docs/plans/fastload.md` for the stage
+       * ordering contract.
+       */
+      type: "load-stage";
+      documentId: string;
+      stage: LoadStage;
+      durationMs: number;
+    }
+  | {
+      /**
+       * Emitted once sub-parts (headers, footers, footnotes, endnotes,
+       * theme, settings) have finished their post-ready idle hydration.
+       * Before this event fires, `canonicalDocument.subParts.*` may be
+       * empty arrays / defaults; after it fires, they carry the parsed
+       * values. Calling `ensureSubPartsHydrated` eagerly forces
+       * hydration synchronously.
+       */
+      type: "subparts-hydrated";
+      documentId: string;
     };
 
+/**
+ * Ordered list of stages emitted by the staged load pipeline. The
+ * skeleton-ready stage corresponds to the `ready` event firing.
+ */
+export type LoadStage =
+  | "opc"
+  | "body"
+  | "styles-numbering-comments"
+  | "skeleton-ready"
+  | "subparts"
+  | "compatibility";
+
 export interface LoadResult {
   source?: ExternalDocumentSource;
 }
@@ -2385,6 +2723,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 +2843,91 @@ 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>;
+  /**
+   * Schema 1.2 — editor-state persistence channel.  Configures which
+   * subsystems persist in-document / rowstore / key-only.  Each call
+   * merges into the current policy map.  Mismatched locations with an
+   * already-loaded docx fire `editor_state_policy_migrated` and
+   * schedule the next serialize to honor the new location.
+   */
+  configureEditorStatePolicy(policy: EditorStatePolicy): void;
+  /**
+   * Register the host's pull-resolver.  Required before the editor
+   * loads a 1.2 docx whose policy includes any keyed location.
+   */
+  registerEditorStateResolver(resolver: EditorStateResolver): void;
+  /**
+   * Register the host's persister.  Required before any subsystem
+   * mutation under keyed policy fires a debounced persist.
+   */
+  registerEditorStatePersister(persister: EditorStatePersister): void;
+  /**
+   * Return the entry key currently associated with a namespace under
+   * keyed policy, or undefined when the namespace is in-document /
+   * key not yet assigned.
+   */
+  getEditorStateKey(namespace: EditorStateNamespace): string | undefined;
+  /**
+   * Re-attempt any persists that failed since the last successful
+   * write.  Pass a namespace to scope the retry; omit to retry all.
+   */
+  retryPendingPersist(namespace?: EditorStateNamespace): Promise<void>;
   setHostAnnotationOverlay(overlay: HostAnnotationOverlay): void;
   clearHostAnnotationOverlay(): void;
   getHostAnnotationSnapshot(): HostAnnotationSnapshot;
@@ -2547,7 +2980,8 @@ export type WordReviewEditorChromePreset =
   | "simple"
   | "advanced"
   | "review"
-  | "workflow";
+  | "workflow"
+  | "collab";
 
 export interface WordReviewEditorChromeOptions {
   /**
@@ -2566,6 +3000,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 {
@@ -2573,6 +3027,38 @@ export interface WordReviewEditorProps {
   currentUser: EditorUser;
   ydoc?: import('yjs').Doc;
   awareness?: import("y-protocols/awareness").Awareness;
+  /**
+   * Optional collab session built via `createCollabSession(...)`. When
+   * set, the `"collab"` chrome preset mounts the top nav (presence
+   * strip, role + audience chips, tamper banner, negotiation action
+   * bar, send-to-supplier button). P9a–f components are pure
+   * presentational; this prop is what wires them to live state. Pass
+   * `undefined` to keep the chrome in non-collab mode even when
+   * `chromePreset === "collab"`.
+   */
+  collabSession?: import("../runtime/collab-session.ts").CollabSession;
+  /**
+   * Transport status signal for the presence strip + role chip (P9b /
+   * P9c). Optional — defaults to "offline" when omitted.
+   */
+  collabTransportStatus?: "connected" | "syncing" | "offline";
+  /**
+   * Identifier for the currently-focused comment, used by the collab
+   * top nav's audience chip + negotiation action bar (P9c / P9e). The
+   * host derives this from its own selection / rail-focus signal.
+   */
+  activeCommentId?: string;
+  /**
+   * Baseline metadata for the send-to-supplier flow (P9f). Required
+   * to enable the button; when omitted, the button stays present but
+   * the confirmation modal becomes a no-op pass-through.
+   */
+  collabSendBaseline?: {
+    originDocumentId: string;
+    originPayloadId: string;
+    originContentHash: string;
+    payloadXml: string;
+  };
   initialDocx?: Uint8Array | ArrayBuffer;
   initialSessionState?: EditorSessionState;
   initialSnapshot?: PersistedEditorSnapshot;
@@ -2670,3 +3156,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";
+  }
+}