@beyondwork/docx-react-component 1.0.59 → 1.0.61

package/src/runtime/document-runtime.ts

@@ -23,6 +23,7 @@ import type {
   AddCommentResult,
   AddScopeParams,
   AddScopeResult,
+  ClearHighlightOptions,
   CommentSidebarSnapshot,
   CommentSidebarThreadSnapshot,
   CompatibilityReport,
@@ -150,6 +151,7 @@ import {
   findScopesIntersecting,
   resolveScope,
 } from "./scope-resolver.ts";
+import { buildDiagnosticFromLegacyWarningCode } from "./diagnostics/build-diagnostic.ts";
 import {
   projectScopeQueryResults,
   queryScopes as runQueryScopes,
@@ -158,6 +160,7 @@ import {
   insertScopeMarkers,
   removeScopeMarkers,
 } from "../core/commands/add-scope.ts";
+import { applyFormattingOperationToDocument } from "../core/commands/formatting-commands.ts";
 import { buildCompatibilityReport } from "../validation/compatibility-engine.ts";
 import { mergeCompatibilityReports } from "../validation/compatibility-report.ts";
 import { createEditorSurfaceSnapshot } from "./surface-projection.ts";
@@ -480,6 +483,22 @@ export interface DocumentRuntime {
   rejectChange(changeId: string): void;
   acceptAllChanges(): void;
   rejectAllChanges(): void;
+  /**
+   * Clears the highlight (background color) on a range in the currently
+   * active story. The caller's selection is NOT moved.
+   *
+   * When `options.range` is omitted, the current document selection is used.
+   *
+   * Tracked-changes / suggesting mode is honored: in suggesting mode the
+   * clear is recorded as an `rPrChange` property-change suggestion when the
+   * resolved range is a single bounded text segment, and is reported via
+   * `command_blocked` when the range spans multiple segments.
+   *
+   * When `options.expandToFullHighlight` is `true`, the resolved range is
+   * grown outward before clearing to cover the entire contiguous highlighted
+   * span it touches. Expansion stops at paragraph and table-cell boundaries.
+   */
+  clearHighlight(options?: ClearHighlightOptions): void;
   openStory(target: EditorStoryTarget): boolean;
   closeStory(): void;
   getActiveStory(): EditorStoryTarget;
@@ -872,6 +891,7 @@ export function createDocumentRuntime(
     options.initialSessionState?.workflowMetadata?.entries
     ?? options.initialSnapshot?.workflowMetadata?.entries
     ?? [];
+  let markerBackedScopeIds = new Set<string>();
   let hostAnnotationOverlay: HostAnnotationOverlay | null = null;
   // §C7 — local view-state for scope chrome visibility; never collab-replicated.
   let scopeChromeVisibilityState: ScopeChromeVisibilityState = { mode: "all" };
@@ -909,6 +929,32 @@ export function createDocumentRuntime(
   storySelections.set(storyTargetKey(MAIN_STORY_TARGET), state.selection);
   lastHeadingFingerprint = computeHeadingFingerprint(state.document);
 
+  function syncMarkerBackedScopeIds(
+    document: CanonicalDocumentEnvelope,
+    overlay: WorkflowOverlay | null,
+  ): void {
+    const presentScopeIds = new Set(collectScopeLocations(document).keys());
+    if (!overlay) {
+      markerBackedScopeIds = presentScopeIds;
+      return;
+    }
+    const overlayScopeIds = new Set(overlay.scopes.map((scope) => scope.scopeId));
+    const next = new Set<string>();
+    for (const scopeId of markerBackedScopeIds) {
+      if (overlayScopeIds.has(scopeId)) {
+        next.add(scopeId);
+      }
+    }
+    for (const scopeId of presentScopeIds) {
+      if (overlayScopeIds.has(scopeId)) {
+        next.add(scopeId);
+      }
+    }
+    markerBackedScopeIds = next;
+  }
+
+  syncMarkerBackedScopeIds(state.document, workflowOverlay);
+
   // Runtime-owned paginated layout engine (Phase 1+ of the layout facet work).
   // The engine caches graph + resolved-formatting + fragment mapper keyed on
   // (content, styles, subParts).  It is the single internal source of truth
@@ -1924,19 +1970,37 @@ export function createDocumentRuntime(
         return scope;
       }
       const location = locations.get(scope.scopeId);
+      const isMarkerBacked = markerBackedScopeIds.has(scope.scopeId);
+      let nextAnchor: EditorAnchorProjection | null = null;
       if (
-        !location ||
-        location.startPos === undefined ||
-        location.endPos === undefined
+        location &&
+        location.startPos !== undefined &&
+        location.endPos !== undefined
       ) {
+        nextAnchor = {
+          kind: "range",
+          from: Math.min(location.startPos, location.endPos),
+          to: Math.max(location.startPos, location.endPos),
+          assoc: { start: -1, end: 1 },
+        };
+      } else if (isMarkerBacked) {
+        const lastKnownRange =
+          scope.anchor.kind === "range"
+            ? { from: scope.anchor.from, to: scope.anchor.to }
+            : scope.anchor.kind === "node"
+              ? { from: scope.anchor.at, to: scope.anchor.at }
+              : scope.anchor.lastKnownRange;
+        nextAnchor = {
+          kind: "detached",
+          reason:
+            location && (location.startPos !== undefined || location.endPos !== undefined)
+              ? "deleted"
+              : "invalidatedByStructureChange",
+          lastKnownRange,
+        };
+      } else {
         return scope;
       }
-      const nextAnchor: EditorAnchorProjection = {
-        kind: "range",
-        from: Math.min(location.startPos, location.endPos),
-        to: Math.max(location.startPos, location.endPos),
-        assoc: { start: -1, end: 1 },
-      };
       if (workflowAnchorsEqual(scope.anchor, nextAnchor)) {
         return scope;
       }
@@ -1966,6 +2030,161 @@ export function createDocumentRuntime(
     return normalizeWorkflowOverlayForDocument(state.document, workflowOverlay);
   }
 
+  function buildWarningSignature(warning: InternalEditorWarning): string {
+    return JSON.stringify({
+      code: warning.code,
+      severity: warning.severity,
+      message: warning.message,
+      source: warning.source,
+      featureEntryId: warning.featureEntryId ?? null,
+      details: warning.details ?? null,
+      affectedAnchor: warning.affectedAnchor ?? null,
+    });
+  }
+
+  function mergeDetachedWorkflowScopeWarnings(
+    overlay: WorkflowOverlay | null,
+    existingWarnings: readonly InternalEditorWarning[],
+  ): {
+    nextWarnings: InternalEditorWarning[];
+    added: InternalEditorWarning[];
+    cleared: Array<{ warningId: string; code: InternalEditorWarning["code"] }>;
+  } {
+    const detachedScopesById = new Map<string, WorkflowScope>();
+    for (const scope of overlay?.scopes ?? []) {
+      if (scope.anchor.kind === "detached") {
+        detachedScopesById.set(scope.scopeId, scope);
+      }
+    }
+
+    const retainedWarnings = existingWarnings.filter(
+      (warning) => warning.code !== "workflow_scope_invalidated",
+    );
+    const existingDetachedWarnings = existingWarnings.filter(
+      (warning) => warning.code === "workflow_scope_invalidated",
+    );
+    const existingById = new Map(
+      existingDetachedWarnings.map((warning) => [warning.warningId, warning] as const),
+    );
+    const desiredById = new Map(
+      [...detachedScopesById.values()].map((scope) => {
+        const warning = createInvalidatedWorkflowScopeWarning(scope);
+        return [warning.warningId, warning] as const;
+      }),
+    );
+
+    const added: InternalEditorWarning[] = [];
+    const cleared: Array<{ warningId: string; code: InternalEditorWarning["code"] }> = [];
+
+    for (const [warningId, existingWarning] of existingById) {
+      const desiredWarning = desiredById.get(warningId);
+      if (!desiredWarning) {
+        cleared.push({ warningId, code: existingWarning.code });
+        continue;
+      }
+      if (buildWarningSignature(existingWarning) !== buildWarningSignature(desiredWarning)) {
+        cleared.push({ warningId, code: existingWarning.code });
+        added.push(desiredWarning);
+      }
+    }
+
+    for (const [warningId, desiredWarning] of desiredById) {
+      if (!existingById.has(warningId)) {
+        added.push(desiredWarning);
+      }
+    }
+
+    return {
+      nextWarnings: [...retainedWarnings, ...desiredById.values()],
+      added,
+      cleared,
+    };
+  }
+
+  function createInvalidatedWorkflowScopeWarning(
+    scope: WorkflowScope,
+  ): InternalEditorWarning {
+    const anchor = scope.anchor.kind === "detached" ? scope.anchor : null;
+    const subject = scope.label
+      ? `Workflow scope "${scope.label}" (${scope.scopeId})`
+      : `Workflow scope ${scope.scopeId}`;
+    const reasonPhrase =
+      anchor?.reason === "deleted"
+        ? "its anchored text was deleted"
+        : anchor?.reason === "invalidatedByStructureChange"
+          ? "document structure changed around it"
+          : "its anchor could not be resolved unambiguously";
+    const modePhrase =
+      scope.mode === "view"
+        ? "read-only enforcement"
+        : `${scope.mode} enforcement`;
+
+    return {
+      warningId: `warning:workflow-scope-invalidated:${scope.scopeId}`,
+      code: "workflow_scope_invalidated",
+      severity: "warning",
+      message: `${subject} was invalidated because ${reasonPhrase}. Reapply the scope before relying on ${modePhrase}.`,
+      source: "runtime",
+      affectedAnchor: anchor ? toInternalAnchorProjection(anchor) : undefined,
+      diagnostic: buildDiagnosticFromLegacyWarningCode("workflow_scope_invalidated", {
+        diagnosticId: `warning-diag:workflow-scope-invalidated:${scope.scopeId}`,
+        technical: {
+          message: `${subject} lost its trusted anchor and is now detached.`,
+          source: "runtime",
+        },
+        details: {
+          scopeId: scope.scopeId,
+          label: scope.label,
+          mode: scope.mode,
+          reason: anchor?.reason,
+          lastKnownRange: anchor?.lastKnownRange,
+          storyTarget: scope.storyTarget,
+          reapplySuggested: true,
+        },
+        affectedAnchor: anchor ? scope.anchor : undefined,
+        llmMetadata: {
+          userSummary: `${subject} is no longer attached to trusted document content. Reapply the scope before relying on it.`,
+          remediation: {
+            kind: "fallback",
+            suggestion:
+              "Locate the intended text using warning.details.scopeId and warning.details.lastKnownRange, then call addScope again for the repaired range.",
+          },
+          recoveryClass: "requires-input",
+          echoedInput: {
+            scopeId: scope.scopeId,
+            lastKnownRange: anchor?.lastKnownRange,
+          },
+        },
+      }),
+      details: {
+        scopeId: scope.scopeId,
+        label: scope.label,
+        mode: scope.mode,
+        reason: anchor?.reason,
+        lastKnownRange: anchor?.lastKnownRange,
+        storyTarget: scope.storyTarget,
+        reapplySuggested: true,
+        actionabilityNote:
+          "Resolve the intended text again, then reapply the scope; the previous anchor is no longer trusted.",
+      },
+    };
+  }
+
+  function syncDetachedWorkflowScopeWarningsInState(): {
+    added: InternalEditorWarning[];
+    cleared: Array<{ warningId: string; code: InternalEditorWarning["code"] }>;
+  } {
+    const { nextWarnings, added, cleared } = mergeDetachedWorkflowScopeWarnings(
+      getNormalizedWorkflowOverlay(),
+      state.warnings,
+    );
+    if (added.length === 0 && cleared.length === 0) {
+      return { added, cleared };
+    }
+    state = { ...state, warnings: nextWarnings };
+    return { added, cleared };
+  }
+
   function deriveWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null {
     const normalizedWorkflowOverlay = getNormalizedWorkflowOverlay();
     if (!normalizedWorkflowOverlay) return null;
@@ -2529,6 +2748,7 @@ export function createDocumentRuntime(
     return snapshot;
   }
 
+  syncDetachedWorkflowScopeWarningsInState();
   let cachedRenderSnapshot = refreshRenderSnapshot();
 
   emit({
@@ -3351,17 +3571,29 @@ export function createDocumentRuntime(
       });
 
       if (params.persistence && params.persistence !== "runtime-only") {
+        const requestedMetadata = params.metadata ?? {};
+        const entryPersistence =
+          requestedMetadata.metadataPersistence ??
+          (params.persistence === "session" ? "external" : "internal");
         const entry: WorkflowMetadataEntry = {
-          entryId: `scope-metadata-${scopeId}`,
-          metadataId: "workflow.scope",
+          entryId: requestedMetadata.entryId ?? `scope-metadata-${scopeId}`,
+          metadataId: requestedMetadata.metadataId ?? "workflow.scope",
           anchor: publicAnchor,
+          ...(params.storyTarget ? { storyTarget: params.storyTarget } : {}),
           scopeId,
-          value:
-            params.persistence === "document-metadata"
-              ? { ...(params.metadata?.value ?? {}), label: params.label }
-              : params.metadata?.value,
-          metadataPersistence:
-            params.persistence === "session" ? "external" : "internal",
+          ...(requestedMetadata.workItemId ? { workItemId: requestedMetadata.workItemId } : {}),
+          ...(requestedMetadata.value !== undefined
+            ? { value: requestedMetadata.value }
+            : params.persistence === "document-metadata" && params.label
+              ? { value: { label: params.label } }
+              : {}),
+          metadataPersistence: entryPersistence,
+          ...(requestedMetadata.storageRef !== undefined
+            ? { storageRef: requestedMetadata.storageRef }
+            : {}),
+          ...(requestedMetadata.metadataVersion !== undefined
+            ? { metadataVersion: requestedMetadata.metadataVersion }
+            : {}),
         };
         this.dispatch({
           type: "workflow.set-metadata-entries",
@@ -3491,6 +3723,143 @@ export function createDocumentRuntime(
         origin: createOrigin("api", clock()),
       });
     },
+    clearHighlight(options) {
+      const resolvedRange = resolveClearHighlightRange(
+        options?.range,
+        state.selection,
+      );
+      if (!resolvedRange) {
+        return;
+      }
+      if (viewState.documentMode === "viewing") {
+        this.emitBlockedCommand("clearHighlight", [{
+          code: "document_viewing_mode",
+          message: "Cannot clear highlight in viewing mode.",
+        }]);
+        return;
+      }
+
+      const surfaceBlocks = getActiveStorySurfaceBlocks();
+      if (!surfaceBlocks) {
+        return;
+      }
+
+      const inputFrom = Math.min(resolvedRange.from, resolvedRange.to);
+      const inputTo = Math.max(resolvedRange.from, resolvedRange.to);
+      let targetFrom = inputFrom;
+      let targetTo = inputTo;
+      if (options?.expandToFullHighlight === true) {
+        const expanded = expandRangeToHighlightExtent(
+          surfaceBlocks,
+          inputFrom,
+          inputTo,
+        );
+        targetFrom = expanded.from;
+        targetTo = expanded.to;
+      }
+      if (targetFrom === targetTo) {
+        return;
+      }
+
+      const activeStoryDocument =
+        activeStory.kind === "main"
+          ? state.document
+          : {
+              ...state.document,
+              content: {
+                type: "doc" as const,
+                children: [...getStoryBlocks(state.document, activeStory)],
+              },
+            };
+      const syntheticSnapshot: RuntimeRenderSnapshot = {
+        ...cachedRenderSnapshot,
+        ...(activeStory.kind === "main" ? {} : { activeStory: MAIN_STORY_TARGET }),
+        selection: {
+          anchor: targetFrom,
+          head: targetTo,
+          isCollapsed: false,
+          activeRange: {
+            kind: "range",
+            from: targetFrom,
+            to: targetTo,
+            assoc: { start: -1, end: 1 },
+          },
+        },
+      };
+
+      const suggesting =
+        getEffectiveDocumentMode(state.selection) === "suggesting";
+      if (suggesting) {
+        if (activeStory.kind !== "main") {
+          this.emitBlockedCommand("clearHighlight", [{
+            code: "suggesting_unsupported",
+            message: `"clearHighlight" is not supported in suggesting mode for this story.`,
+          }]);
+          return;
+        }
+        const segment = findSingleSelectedTextSegment(syntheticSnapshot);
+        if (!segment) {
+          this.emitBlockedCommand("clearHighlight", [{
+            code: "suggesting_unsupported",
+            message: `"clearHighlight" requires one bounded text segment in suggesting mode.`,
+          }]);
+          return;
+        }
+        const beforeXml = buildRunPropertyBeforeXml(segment);
+        const mutation = applyFormattingOperationToDocument(
+          activeStoryDocument,
+          syntheticSnapshot,
+          { type: "set-highlight-color", color: null },
+        );
+        if (!mutation.changed) {
+          return;
+        }
+        const timestamp = clock();
+        const nextDocument = appendPropertyChangeSuggestion(
+          mutation.document,
+          { from: segment.from, to: segment.to },
+          {
+            originalRevisionType: "rPrChange",
+            xmlTag: "rPrChange",
+            beforeXml,
+            semanticKind: "formatting-change",
+            storyTarget: activeStory,
+            authorId: defaultAuthorId ?? undefined,
+          },
+          timestamp,
+        );
+        this.dispatch({
+          type: "document.replace",
+          document: nextDocument,
+          mapping: createEmptyMapping(),
+          origin: createOrigin("api", timestamp),
+        });
+        return;
+      }
+
+      const result = applyFormattingOperationToDocument(
+        activeStoryDocument,
+        syntheticSnapshot,
+        { type: "set-highlight-color", color: null },
+      );
+      if (!result.changed) {
+        return;
+      }
+      const nextDocument =
+        activeStory.kind === "main"
+          ? result.document
+          : replaceStoryBlocks(
+              state.document,
+              activeStory,
+              result.document.content.children,
+            );
+      this.dispatch({
+        type: "document.replace",
+        document: nextDocument,
+        mapping: createEmptyMapping(),
+        origin: createOrigin("api", clock()),
+      });
+    },
     openStory(target) {
       const normalizedTarget =
         target.kind === "header" || target.kind === "footer"
@@ -3601,6 +3970,7 @@ export function createDocumentRuntime(
         collection,
         collectSectionPropertiesInOrder(state.document),
         state.document,
+        state.document.subParts?.settings,
       );
     },
     layout: layoutFacet,
@@ -3951,16 +4321,42 @@ export function createDocumentRuntime(
           overlay: workflowOverlay,
           entries: workflowMetadataEntries,
           document: state.document,
+          markerBackedScopeIds,
         },
         filter,
       );
     },
     subscribeToScopeQuery(filter, callback) {
+      const buildAnchorKey = (anchor: EditorAnchorProjection): string => {
+        switch (anchor.kind) {
+          case "range":
+            return `range:${anchor.from}:${anchor.to}:${anchor.assoc.start}:${anchor.assoc.end}`;
+          case "node":
+            return `node:${anchor.at}`;
+          case "detached":
+            return `detached:${anchor.reason}:${anchor.lastKnownRange.from}:${anchor.lastKnownRange.to}`;
+          default:
+            return "unknown";
+        }
+      };
+
       const buildKey = (results: ScopeQueryResult[]) =>
         results
           .map(
             (r) =>
-              `${r.scope.scopeId}:${r.scope.version ?? 0}:${r.scope.visibility ?? "visible"}`,
+              [
+                r.scope.scopeId,
+                r.scope.version ?? 0,
+                r.scope.visibility ?? "visible",
+                buildAnchorKey(r.scope.anchor),
+                r.workItem?.workItemId ?? "",
+                r.entries
+                  .map(
+                    (entry) =>
+                      `${entry.entryId}:${entry.metadataVersion ?? 0}:${buildAnchorKey(entry.anchor)}`,
+                  )
+                  .join("|"),
+              ].join(":"),
           )
           .join(",");
 
@@ -4027,7 +4423,12 @@ export function createDocumentRuntime(
       if (pos === null) return [];
       const hits = findAllScopesAt(state.document, pos);
       return projectScopeQueryResults(
-        { overlay: workflowOverlay, entries: workflowMetadataEntries, document: state.document },
+        {
+          overlay: workflowOverlay,
+          entries: workflowMetadataEntries,
+          document: state.document,
+          markerBackedScopeIds,
+        },
         hits.map((h) => h.scopeId),
         options,
       );
@@ -4036,7 +4437,12 @@ export function createDocumentRuntime(
       if (range.kind !== "range") return [];
       const hits = findScopesIntersecting(state.document, range.from, range.to, options?.mode);
       return projectScopeQueryResults(
-        { overlay: workflowOverlay, entries: workflowMetadataEntries, document: state.document },
+        {
+          overlay: workflowOverlay,
+          entries: workflowMetadataEntries,
+          document: state.document,
+          markerBackedScopeIds,
+        },
         hits.map((h) => h.scopeId),
         options,
       );
@@ -4249,6 +4655,8 @@ export function createDocumentRuntime(
     state = finalizeState(transaction.nextState, transaction.markDirty, clock());
     perfCounters.increment("commit.finalizeState.us", Math.round((performance.now() - tFinalize0) * 1000));
     storySelections.set(storyTargetKey(activeStory), state.selection);
+    syncMarkerBackedScopeIds(state.document, workflowOverlay);
+    const detachedWorkflowScopeWarnings = syncDetachedWorkflowScopeWarningsInState();
 
     const tInvalidate0 = performance.now();
     if (transaction.markDirty && transaction.mapping.steps.length > 0) {
@@ -4319,7 +4727,20 @@ export function createDocumentRuntime(
     perfCounters.increment("commit.refresh.us", Math.round((performance.now() - tRefresh0) * 1000));
 
     const tNotify0 = performance.now();
-    notify(previous, state, transaction);
+    notify(previous, state, {
+      ...transaction,
+      effects: {
+        ...transaction.effects,
+        warningsAdded: [
+          ...transaction.effects.warningsAdded,
+          ...detachedWorkflowScopeWarnings.added,
+        ],
+        warningsCleared: [
+          ...transaction.effects.warningsCleared,
+          ...detachedWorkflowScopeWarnings.cleared,
+        ],
+      },
+    });
     perfCounters.increment("commit.notify.us", Math.round((performance.now() - tNotify0) * 1000));
     perfCounters.increment("commit.total.us", Math.round((performance.now() - tApply0) * 1000));
   }
@@ -4948,10 +5369,18 @@ export function createDocumentRuntime(
   function applyRuntimeStateOverlayCommand(
     command: RuntimeStateOverlayCommand,
   ): void {
+    let detachedWorkflowScopeWarnings:
+      | {
+          added: InternalEditorWarning[];
+          cleared: Array<{ warningId: string; code: InternalEditorWarning["code"] }>;
+        }
+      | null = null;
     switch (command.type) {
       case "workflow.set-overlay": {
         workflowOverlay = structuredClone(command.overlay);
+        syncMarkerBackedScopeIds(state.document, workflowOverlay);
         cachedNormalizedWorkflowOverlay = undefined;
+        detachedWorkflowScopeWarnings = syncDetachedWorkflowScopeWarningsInState();
         cachedRenderSnapshot = refreshRenderSnapshot();
         const snapshot = deriveWorkflowScopeSnapshot()!;
         emit({
@@ -4970,7 +5399,9 @@ export function createDocumentRuntime(
       }
       case "workflow.clear-overlay": {
         workflowOverlay = null;
+        syncMarkerBackedScopeIds(state.document, workflowOverlay);
         cachedNormalizedWorkflowOverlay = undefined;
+        detachedWorkflowScopeWarnings = syncDetachedWorkflowScopeWarningsInState();
         cachedRenderSnapshot = refreshRenderSnapshot();
         emit({
           type: "workflow_active_work_item_changed",
@@ -5045,6 +5476,25 @@ export function createDocumentRuntime(
         break;
       }
     }
+    if (detachedWorkflowScopeWarnings) {
+      for (const warning of detachedWorkflowScopeWarnings.added) {
+        const publicWarning = toPublicWarning(warning);
+        emit({
+          type: "warning_added",
+          documentId: state.documentId,
+          warning: publicWarning,
+        });
+        options.onWarning?.(publicWarning);
+      }
+      for (const cleared of detachedWorkflowScopeWarnings.cleared) {
+        emit({
+          type: "warning_cleared",
+          documentId: state.documentId,
+          warningId: cleared.warningId,
+          code: cleared.code,
+        });
+      }
+    }
     for (const listener of listeners) {
       listener();
     }
@@ -5533,11 +5983,42 @@ function toPublicCompatibilityFeatureEntry(
 }
 
 function toPublicWarning(warning: InternalEditorWarning): EditorWarning {
+  const diagnostic =
+    warning.diagnostic ??
+    (() => {
+      switch (warning.code) {
+        case "unsupported_ooxml_preserved":
+        case "unsupported_ooxml_locked":
+        case "import_normalized":
+        case "export_roundtrip_risk":
+        case "comment_anchor_detached":
+        case "revision_anchor_detached":
+        case "workflow_scope_invalidated":
+        case "large_document_degraded":
+        case "font_substitution":
+        case "image_missing":
+          return buildDiagnosticFromLegacyWarningCode(warning.code, {
+            diagnosticId: `warning-diag:${warning.warningId}`,
+            emittedAt: new Date(0).toISOString(),
+            technical: {
+              message: warning.message,
+              source: warning.source,
+            },
+            details: warning.details,
+            affectedAnchor: warning.affectedAnchor
+              ? toPublicAnchorProjection(warning.affectedAnchor)
+              : undefined,
+          });
+        default:
+          return undefined;
+      }
+    })();
   return {
     ...warning,
     affectedAnchor: warning.affectedAnchor
       ? toPublicAnchorProjection(warning.affectedAnchor)
       : undefined,
+    diagnostic,
   };
 }
 
@@ -7143,3 +7624,271 @@ async function upgradeMeasurementProvider(
     // fall through — the empirical backend remains in place
   }
 }
+
+function rangesOverlap(
+  leftFrom: number,
+  leftTo: number,
+  rightFrom: number,
+  rightTo: number,
+): boolean {
+  return leftFrom < rightTo && rightFrom < leftTo;
+}
+
+function resolveClearHighlightRange(
+  inputRange: EditorAnchorProjection | undefined,
+  selection: import("../core/state/editor-state.ts").SelectionSnapshot,
+): { from: number; to: number } | null {
+  if (inputRange !== undefined) {
+    if (inputRange.kind !== "range") return null;
+    return { from: inputRange.from, to: inputRange.to };
+  }
+  const active = selection.activeRange;
+  if (active.kind !== "range") return null;
+  return { from: active.range.from, to: active.range.to };
+}
+
+function expandRangeToHighlightExtent(
+  blocks: readonly SurfaceBlockSnapshot[],
+  inputFrom: number,
+  inputTo: number,
+): { from: number; to: number } {
+  let from = inputFrom;
+  let to = inputTo;
+  forEachParagraphBlock(blocks, (paragraph) => {
+    if (!rangesOverlap(from, to, paragraph.from, paragraph.to)) {
+      return;
+    }
+    const textSegments = paragraph.segments.filter(
+      (segment): segment is Extract<SurfaceInlineSegment, { kind: "text" }> =>
+        segment.kind === "text",
+    );
+    const expanded = expandRangeWithinParagraph(textSegments, inputFrom, inputTo);
+    if (expanded.from < from) from = expanded.from;
+    if (expanded.to > to) to = expanded.to;
+  });
+  return { from, to };
+}
+
+function expandRangeWithinParagraph(
+  segments: Array<Extract<SurfaceInlineSegment, { kind: "text" }>>,
+  inputFrom: number,
+  inputTo: number,
+): { from: number; to: number } {
+  let from = inputFrom;
+  let to = inputTo;
+  let touchedLeftIndex = -1;
+  let touchedRightIndex = -1;
+  for (let i = 0; i < segments.length; i += 1) {
+    const segment = segments[i]!;
+    if (!isHighlightedSegment(segment)) continue;
+    if (rangesOverlap(inputFrom, inputTo, segment.from, segment.to)) {
+      if (touchedLeftIndex === -1) touchedLeftIndex = i;
+      touchedRightIndex = i;
+    }
+  }
+  if (touchedLeftIndex === -1) {
+    return { from, to };
+  }
+  for (let i = touchedLeftIndex; i >= 0; i -= 1) {
+    const segment = segments[i]!;
+    if (!isHighlightedSegment(segment)) break;
+    if (segment.to < from) break;
+    if (segment.from < from) from = segment.from;
+  }
+  for (let i = touchedRightIndex; i < segments.length; i += 1) {
+    const segment = segments[i]!;
+    if (!isHighlightedSegment(segment)) break;
+    if (segment.from > to) break;
+    if (segment.to > to) to = segment.to;
+  }
+  return { from, to };
+}
+
+function isHighlightedSegment(
+  segment: Extract<SurfaceInlineSegment, { kind: "text" }>,
+): boolean {
+  const bg = segment.markAttrs?.backgroundColor;
+  return typeof bg === "string" && bg.length > 0;
+}
+
+function forEachParagraphBlock(
+  blocks: readonly SurfaceBlockSnapshot[],
+  visit: (paragraph: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>) => void,
+): void {
+  for (const block of blocks) {
+    if (block.kind === "paragraph") {
+      visit(block);
+      continue;
+    }
+    if (block.kind === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          forEachParagraphBlock(cell.content, visit);
+        }
+      }
+      continue;
+    }
+    if (block.kind === "sdt_block") {
+      forEachParagraphBlock(block.children, visit);
+    }
+  }
+}
+
+function findSingleSelectedTextSegment(
+  snapshot: Pick<RuntimeRenderSnapshot, "surface" | "selection">,
+): Extract<SurfaceInlineSegment, { kind: "text" }> | null {
+  if (
+    !snapshot.surface ||
+    snapshot.selection.activeRange.kind !== "range" ||
+    snapshot.selection.isCollapsed
+  ) {
+    return null;
+  }
+  const selectionFrom = Math.min(snapshot.selection.anchor, snapshot.selection.head);
+  const selectionTo = Math.max(snapshot.selection.anchor, snapshot.selection.head);
+  const segments = collectSelectedTextSegments(
+    snapshot.surface.blocks,
+    selectionFrom,
+    selectionTo,
+  );
+  if (segments.length !== 1) {
+    return null;
+  }
+  const [segment] = segments;
+  if (!segment || segment.from !== selectionFrom || segment.to !== selectionTo) {
+    return null;
+  }
+  return segment;
+}
+
+function collectSelectedTextSegments(
+  blocks: readonly SurfaceBlockSnapshot[],
+  selectionFrom: number,
+  selectionTo: number,
+  output: Array<Extract<SurfaceInlineSegment, { kind: "text" }>> = [],
+): Array<Extract<SurfaceInlineSegment, { kind: "text" }>> {
+  for (const block of blocks) {
+    if (block.kind === "paragraph") {
+      for (const segment of block.segments) {
+        if (
+          segment.kind === "text" &&
+          rangesOverlap(selectionFrom, selectionTo, segment.from, segment.to)
+        ) {
+          output.push(segment);
+        }
+      }
+      continue;
+    }
+    if (block.kind === "table") {
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          collectSelectedTextSegments(cell.content, selectionFrom, selectionTo, output);
+        }
+      }
+      continue;
+    }
+    if (block.kind === "sdt_block") {
+      collectSelectedTextSegments(block.children, selectionFrom, selectionTo, output);
+    }
+  }
+  return output;
+}
+
+function buildRunPropertyBeforeXml(
+  segment: Extract<SurfaceInlineSegment, { kind: "text" }>,
+): string {
+  const parts: string[] = [];
+  const marks = new Set(segment.marks ?? []);
+  if (marks.has("bold")) parts.push("<w:b/>");
+  if (marks.has("italic")) parts.push("<w:i/>");
+  if (marks.has("underline")) parts.push("<w:u w:val=\"single\"/>");
+  if (marks.has("strikethrough")) parts.push("<w:strike/>");
+  if (marks.has("superscript")) parts.push("<w:vertAlign w:val=\"superscript\"/>");
+  if (marks.has("subscript")) parts.push("<w:vertAlign w:val=\"subscript\"/>");
+  if (segment.markAttrs?.fontFamily) {
+    parts.push(
+      `<w:rFonts w:ascii="${escapeAttributeXml(segment.markAttrs.fontFamily)}" w:hAnsi="${escapeAttributeXml(segment.markAttrs.fontFamily)}"/>`,
+    );
+  }
+  if (segment.markAttrs?.fontSize !== undefined) {
+    parts.push(`<w:sz w:val="${segment.markAttrs.fontSize}"/>`);
+  }
+  if (segment.markAttrs?.textColor) {
+    parts.push(`<w:color w:val="${escapeAttributeXml(segment.markAttrs.textColor)}"/>`);
+  }
+  if (segment.markAttrs?.backgroundColor) {
+    parts.push(
+      `<w:shd w:val="clear" w:color="auto" w:fill="${escapeAttributeXml(segment.markAttrs.backgroundColor)}"/>`,
+    );
+  }
+  return `<w:rPr>${parts.join("")}</w:rPr>`;
+}
+
+function escapeAttributeXml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function appendPropertyChangeSuggestion(
+  document: CanonicalDocumentEnvelope,
+  anchor: { from: number; to: number },
+  input: {
+    originalRevisionType: "rPrChange" | "pPrChange";
+    xmlTag: "rPrChange" | "pPrChange";
+    beforeXml: string;
+    semanticKind: "formatting-change" | "paragraph-property-change";
+    storyTarget: EditorStoryTarget;
+    authorId?: string;
+  },
+  timestamp: string,
+): CanonicalDocumentEnvelope {
+  const existing = document.review.revisions;
+  const changeId = createRuntimeSuggestionChangeId(existing, timestamp);
+  const resolvedAuthorId = input.authorId ?? "unknown";
+  return {
+    ...document,
+    review: {
+      ...document.review,
+      revisions: {
+        ...existing,
+        [changeId]: {
+          changeId,
+          kind: "property-change",
+          anchor: createRangeAnchor(anchor.from, anchor.to, { start: 1, end: -1 }),
+          authorId: resolvedAuthorId,
+          createdAt: timestamp,
+          warningIds: [],
+          metadata: {
+            source: "runtime",
+            storyTarget: input.storyTarget,
+            suggestionId: changeId,
+            semanticKind: input.semanticKind,
+            originalRevisionType: input.originalRevisionType,
+            propertyChangeData: {
+              xmlTag: input.xmlTag,
+              beforeXml: input.beforeXml,
+            },
+          },
+          status: "open",
+        },
+      },
+    },
+  };
+}
+
+function createRuntimeSuggestionChangeId(
+  existing: CanonicalDocumentEnvelope["review"]["revisions"],
+  timestamp: string,
+): string {
+  const base = `change-${timestamp.replace(/[^0-9]/gu, "")}`;
+  let counter = Object.keys(existing).length + 1;
+  let candidate = `${base}-p${counter}`;
+  while (existing[candidate]) {
+    counter += 1;
+    candidate = `${base}-p${counter}`;
+  }
+  return candidate;
+}