@beyondwork/docx-react-component 1.0.72 → 1.0.74

package/src/runtime/document-runtime.ts

@@ -171,7 +171,12 @@ import {
   seedMarkerBackedScopeIds,
   type OverlayStore,
 } from "./workflow/overlay-store.ts";
-import type { RuntimeOperationPlan, ScopeBundle } from "./scopes/semantic-scope-types.ts";
+import type {
+  RuntimeOperationPlan,
+  ScopeBundle,
+  SemanticScope,
+  SemanticScopeKind,
+} from "./scopes/semantic-scope-types.ts";
 import { createScopeCompilerService } from "./scopes/compiler-service.ts";
 import {
   createWorkflowCoordinator,
@@ -527,6 +532,42 @@ export interface DocumentRuntime {
    * handle (e.g. `getScope`).
    */
   compileScopeBundleById(scopeId: string, nowUtc: string): ScopeBundle | null;
+  /**
+   * KI-008 (2026-04-24) — batch enumeration primitive for L10
+   * `ui.scope.list(filter?)`. Returns the compiled `SemanticScope[]`
+   * through the existing `createScopeCompilerService` facade, applies
+   * the optional kind filter + limit over the result, and hands back a
+   * fresh array (callers may sort / splice freely without leaking
+   * into internal compiler state). L10 `src/api/v3/ui/**` can't import
+   * `src/runtime/scopes/**` per its purity guard; this handle method
+   * is the narrow seam through which `ui.scope.list` reaches
+   * enumeration. `ai.listScopes` delegates through the same primitive
+   * so both surfaces project the same identity set.
+   */
+  compileScopeList(filter?: {
+    readonly kind?: SemanticScopeKind;
+    readonly limit?: number;
+  }): readonly SemanticScope[];
+  /**
+   * KI-008 close (2026-04-24) — scopeId-keyed scope-card projection
+   * for L10 `ui.scope.card(scopeId)`. Delegates to
+   * `runtime.workflow.getAllScopeCardModels()` + filters to the
+   * matching scope. Returns `null` when the id doesn't project a
+   * card (not on overlay / no matching segment).
+   */
+  compileScopeCardById(
+    scopeId: string,
+  ): import("../api/public-types.ts").ScopeCardModel | null;
+  /**
+   * KI-008 close (2026-04-24) — scope-rail snapshot for L10
+   * `ui.scope.rail(options?)`. Wraps `getRailSegments(pageIndex)`
+   * (narrowed) or `getAllRailSegments()` (span) into a
+   * `ScopeRailSnapshot` envelope so the UI surface has a stable
+   * shape regardless of page filtering.
+   */
+  compileScopeRailSnapshot(options?: {
+    readonly pageIndex?: number;
+  }): import("../api/public-types.ts").ScopeRailSnapshot;
   /**
    * Debug projector support — readonly view of scope ids the runtime
    * considers marker-backed (present in both `collectScopeLocations(doc)`
@@ -837,6 +878,20 @@ export interface DocumentRuntime {
    * Safe to call at any frequency; identical ranges are a no-op.
    */
   setVisibleBlockRange(range: { start: number; end: number }): void;
+  /**
+   * Multi-interval variant of `setVisibleBlockRange`. The surface projection
+   * treats a block as real if its index falls in ANY of the supplied
+   * intervals. Use this when the editor's visible window and the caret's
+   * page are disjoint on a long document — emit the viewport + the caret's
+   * page as two ranges instead of one merged range so the gap between them
+   * stays virtualized (placeholder-culled) instead of being realized.
+   *
+   * The array is stored by reference; callers are responsible for passing
+   * non-overlapping intervals sorted ascending by `start`. An empty array
+   * is equivalent to passing a single full-document range (legacy
+   * "all-real" behavior). Identical ranges are a no-op.
+   */
+  setVisibleBlockRanges(ranges: readonly { start: number; end: number }[]): void;
   /**
    * Triggers a surface-only refresh that applies the latest visible block range
    * without running the full commit pipeline. Used by scroll handlers.
@@ -959,6 +1014,46 @@ interface HistoryState {
  * stale `items[].anchor` never reaches a consumer. The direct
  * `runtime.getReviewWorkSnapshot()` API does not use this cache.
  */
+/**
+ * Normalize incoming viewport intervals: drop degenerate ranges (end <= start),
+ * sort by `start`, merge overlapping / touching intervals. Returns a frozen
+ * array so callers can't mutate the cached state.
+ *
+ * The sort + merge is important: `refreshSurfaceOnly`'s idempotency key is
+ * a string serialization, so `[{0,5},{100,105}]` and `[{100,105},{0,5}]`
+ * must compare equal; likewise `[{0,5},{4,10}]` and `[{0,10}]` represent
+ * identical realization sets and should key identically.
+ */
+function normalizeViewportRanges(
+  ranges: readonly { start: number; end: number }[],
+): readonly { start: number; end: number }[] {
+  const cleaned = ranges
+    .filter((r) => Number.isFinite(r.start) && Number.isFinite(r.end) && r.end > r.start)
+    .map((r) => ({ start: r.start, end: r.end }));
+  if (cleaned.length === 0) return Object.freeze([]);
+  cleaned.sort((a, b) => a.start - b.start);
+  const merged: { start: number; end: number }[] = [cleaned[0]!];
+  for (let i = 1; i < cleaned.length; i += 1) {
+    const next = cleaned[i]!;
+    const last = merged[merged.length - 1]!;
+    if (next.start <= last.end) {
+      if (next.end > last.end) last.end = next.end;
+    } else {
+      merged.push(next);
+    }
+  }
+  return Object.freeze(merged.map((r) => Object.freeze(r)));
+}
+
+/** Stable serialization of normalized viewport ranges for fingerprinting. */
+function serializeViewportRanges(
+  ranges: readonly { start: number; end: number }[] | null,
+): string {
+  if (ranges === null) return "null";
+  if (ranges.length === 0) return "empty";
+  return ranges.map((r) => `${r.start}:${r.end}`).join("|");
+}
+
 function computeWorkflowMarkupStructuralHash(
   wfMarkup: WorkflowMarkupSnapshot,
 ): string {
@@ -1215,19 +1310,14 @@ export function createDocumentRuntime(
     // so the facet forwards to the runtime method. Forward-reference pattern matches
     // `renderKernelRef` — see that example. See spec-review notes on commit 0b03bfa7.
     setVisibleBlockRange: (range) => {
-      if (
-        viewportBlockRange &&
-        viewportBlockRange.start === range.start &&
-        viewportBlockRange.end === range.end
-      ) {
-        return;
-      }
-      viewportBlockRange = { start: range.start, end: range.end };
-      perfCounters.increment("runtime.viewport.updates");
+      applyViewportRanges([range]);
+    },
+    setVisibleBlockRanges: (ranges) => {
+      applyViewportRanges(ranges);
     },
     requestViewportRefresh: () => {
       perfCounters.increment("runtime.viewport.refreshes");
-      refreshSurfaceOnly();
+      maybeRefreshSurfaceForViewport();
     },
   });
   // D1 — wire the layout-guard warning emitter so `return []` guard sites
@@ -1255,8 +1345,28 @@ export function createDocumentRuntime(
     renderKernel: () => renderKernelRef,
     getCanonicalDocument: () => state.document,
   });
-  // L7 Phase 2 — viewport block range for surface culling.
-  let viewportBlockRange: { start: number; end: number } | null = null;
+  // L7 Phase 2 — viewport block range(s) for surface culling. Multi-interval
+  // canonical state: a block is real if its index falls in ANY interval.
+  // Stored as a frozen, sorted, non-overlapping list so `applyViewportRanges`
+  // can identity-compare for fast no-ops; `null` = "all blocks real" (legacy).
+  let viewportBlockRanges: readonly { start: number; end: number }[] | null = null;
+  /** Serialized fingerprint of the active ranges — used as the idempotency key for `refreshSurfaceOnly`. */
+  let viewportRangesKey: string = serializeViewportRanges(null);
+
+  function applyViewportRanges(
+    incoming: readonly { start: number; end: number }[] | null,
+  ): void {
+    // Normalize: empty array / null both mean "no culling".
+    const normalized =
+      incoming == null || incoming.length === 0
+        ? null
+        : normalizeViewportRanges(incoming);
+    const nextKey = serializeViewportRanges(normalized);
+    if (nextKey === viewportRangesKey) return;
+    viewportBlockRanges = normalized;
+    viewportRangesKey = nextKey;
+    perfCounters.increment("runtime.viewport.updates");
+  }
 
   let cachedSurface:
     | {
@@ -1429,7 +1539,7 @@ export function createDocumentRuntime(
     }
 
     const snapshot = createEditorSurfaceSnapshot(document, state.selection, nextActiveStory, {
-      viewportBlockRange,
+      viewportBlockRanges,
       ...(effectiveMarkupModeProvider
         ? { getEffectiveMarkupMode: effectiveMarkupModeProvider }
         : {}),
@@ -2241,10 +2351,28 @@ export function createDocumentRuntime(
   }
 
   /**
-   * L7 Phase 2 — surface-only refresh triggered by viewport scroll.
-   * Rebuilds only the surface facet (with the current viewportBlockRange) and
-   * splices it into cachedRenderSnapshot. Does NOT rebuild layout, comments,
-   * trackedChanges, or compatibility. Does NOT increment "refresh.all".
+   * Fingerprint over the inputs that the viewport-refresh fast-path knows
+   * about. Used to short-circuit {@link maybeRefreshSurfaceForViewport}
+   * when nothing that affects the scroll-driven projection has changed
+   * since the last build. Scroll handlers fire effectively-identical
+   * requests on every tick (IO coalescing, overscan nudges that don't
+   * flip any page's visible state); without this gate every tick would
+   * rebuild the surface + notify listeners + force PM `view.updateState()`.
+   *
+   * NOT suitable for callers that invalidate external projection inputs
+   * (markup-mode provider, etc.) because those inputs are read at
+   * projection time and are not captured in the fingerprint. Those callers
+   * use {@link refreshSurfaceOnly} directly (unconditional rebuild).
+   */
+  let cachedSurfaceFingerprint: string | null = null;
+
+  /**
+   * L7 Phase 2 — surface-only refresh. Rebuilds the surface facet (with
+   * the current viewportBlockRanges) and splices it into
+   * cachedRenderSnapshot. Does NOT rebuild layout, comments, trackedChanges,
+   * or compatibility. Does NOT increment "refresh.all". Callers that
+   * know an input outside the fingerprint changed (markup-mode provider,
+   * etc.) use this directly.
    */
   function refreshSurfaceOnly(): void {
     const newSurface = createEditorSurfaceSnapshot(
@@ -2252,12 +2380,13 @@ export function createDocumentRuntime(
       state.selection,
       activeStory,
       {
-        viewportBlockRange,
+        viewportBlockRanges,
         ...(effectiveMarkupModeProvider
           ? { getEffectiveMarkupMode: effectiveMarkupModeProvider }
           : {}),
       },
     );
+    cachedSurfaceFingerprint = `${state.revisionToken}|${storyTargetKey(activeStory)}|${viewportRangesKey}|${String(state.selection.anchor)}:${String(state.selection.head)}`;
     // Refresh the cache with the just-built snapshot so a subsequent
     // refreshRenderSnapshot (same revisionToken + activeStoryKey) hits cache.
     // Without this repopulate, the next non-mutation refresh wastes a second
@@ -2277,6 +2406,25 @@ export function createDocumentRuntime(
     }
   }
 
+  /**
+   * Viewport-refresh fast path — short-circuits when the tracked
+   * fingerprint matches, otherwise delegates to {@link refreshSurfaceOnly}.
+   * Used by `requestViewportRefresh` so steady-state scroll doesn't pay
+   * a full projection + listener fan-out on every tick.
+   *
+   * Safe because every external input that can change the projection
+   * output without ticking revisionToken / selection / viewportRanges /
+   * activeStory is wired to call `refreshSurfaceOnly` directly (see
+   * `setEffectiveMarkupModeProvider`, `invalidateForMarkupModeChange`).
+   */
+  function maybeRefreshSurfaceForViewport(): void {
+    const fingerprint = `${state.revisionToken}|${storyTargetKey(activeStory)}|${viewportRangesKey}|${String(state.selection.anchor)}:${String(state.selection.head)}`;
+    if (cachedSurfaceFingerprint === fingerprint && cachedSurface) {
+      return;
+    }
+    refreshSurfaceOnly();
+  }
+
   function invalidateDerivedRuntimeCaches(): void {
     cachedSurface = undefined;
     cachedCompatibility = undefined;
@@ -3289,6 +3437,31 @@ export function createDocumentRuntime(
     compileScopeBundleById(scopeId, nowUtc) {
       return createScopeCompilerService(runtime).compileBundleById(scopeId, nowUtc);
     },
+    compileScopeList(filter) {
+      const all = createScopeCompilerService(runtime).compileAllScopes();
+      const byKind = filter?.kind
+        ? all.filter((s) => s.kind === filter.kind)
+        : all.slice();
+      if (typeof filter?.limit === "number") {
+        return byKind.slice(0, filter.limit);
+      }
+      return byKind;
+    },
+    compileScopeCardById(scopeId) {
+      const cards = workflowCoordinator.getAllScopeCardModels();
+      return cards.find((card) => card.scopeId === scopeId) ?? null;
+    },
+    compileScopeRailSnapshot(options) {
+      const pageIndex = options?.pageIndex;
+      const segments =
+        typeof pageIndex === "number"
+          ? workflowCoordinator.getRailSegments(pageIndex)
+          : workflowCoordinator.getAllRailSegments();
+      return {
+        segments: Object.freeze([...segments]),
+        ...(typeof pageIndex === "number" ? { pageIndex } : {}),
+      };
+    },
     getMarkerBackedScopeIds() {
       return workflowCoordinator.getMarkerBackedScopeIds();
     },
@@ -4219,19 +4392,14 @@ export function createDocumentRuntime(
       perfCounters.reset();
     },
     setVisibleBlockRange(range) {
-      if (
-        viewportBlockRange &&
-        viewportBlockRange.start === range.start &&
-        viewportBlockRange.end === range.end
-      ) {
-        return;
-      }
-      viewportBlockRange = { start: range.start, end: range.end };
-      perfCounters.increment("runtime.viewport.updates");
+      applyViewportRanges([range]);
+    },
+    setVisibleBlockRanges(ranges) {
+      applyViewportRanges(ranges);
     },
     requestViewportRefresh() {
       perfCounters.increment("runtime.viewport.refreshes");
-      refreshSurfaceOnly();
+      maybeRefreshSurfaceForViewport();
     },
   };
 
@@ -5668,8 +5836,8 @@ function semanticallyEqualCommentThreads(
   if (prevAnchor.kind !== nextAnchor.kind) return false;
   if (prevAnchor.kind === "range" && nextAnchor.kind === "range") {
     return (
-      prevAnchor.range.from === nextAnchor.range.from &&
-      prevAnchor.range.to === nextAnchor.range.to
+      prevAnchor.from === nextAnchor.from &&
+      prevAnchor.to === nextAnchor.to
     );
   }
   if (prevAnchor.kind === "node" && nextAnchor.kind === "node") {
@@ -6038,8 +6206,8 @@ function toAnchorBounds(anchor: InternalEditorAnchorProjection): { from: number;
   switch (anchor.kind) {
     case "range":
       return {
-        from: Math.min(anchor.range.from, anchor.range.to),
-        to: Math.max(anchor.range.from, anchor.range.to),
+        from: Math.min(anchor.from, anchor.to),
+        to: Math.max(anchor.from, anchor.to),
       };
     case "node":
       return {
@@ -7212,12 +7380,12 @@ function remapProtectionSnapshot(
           "preserve-only: permission range could not be remapped after runtime edits",
       };
     }
-    if (mapped.range.from !== range.start || mapped.range.to !== range.end) {
+    if (mapped.from !== range.start || mapped.to !== range.end) {
       changed = true;
       return {
         ...range,
-        start: mapped.range.from,
-        end: mapped.range.to,
+        start: mapped.from,
+        end: mapped.to,
       };
     }
     return range;
@@ -7366,7 +7534,7 @@ function resolveClearHighlightRange(
   }
   const active = selection.activeRange;
   if (active.kind !== "range") return null;
-  return { from: active.range.from, to: active.range.to };
+  return { from: active.from, to: active.to };
 }
 
 function expandRangeToHighlightExtent(

package/src/runtime/formatting/formatting-context.ts

@@ -891,7 +891,7 @@ function buildRevisionRangeIndex(
     const anchor = revision.anchor;
     let range: { from: number; to: number } | undefined;
     if (anchor.kind === "range") {
-      range = { from: anchor.range.from, to: anchor.range.to };
+      range = { from: anchor.from, to: anchor.to };
     } else if (anchor.kind === "node") {
       range = { from: anchor.at, to: anchor.at };
     } else {

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

@@ -68,6 +68,7 @@ export function createInertLayoutFacet(): WordReviewEditorLayoutFacet {
     getDirtyFieldFamilies: () => [],
     getFieldDirtinessReport: () => emptyReport,
     setVisibleBlockRange: () => undefined,
+    setVisibleBlockRanges: () => undefined,
     requestViewportRefresh: () => undefined,
     subscribe: (_listener: (event: LayoutFacetEvent) => void) => () => undefined,
   };

package/src/runtime/layout/layout-engine-version.ts

@@ -926,8 +926,37 @@
  *   Cache envelopes from v53 invalidate because any document with
  *   `<w:br w:type="page"/>` (common in CCEP templates with explicit
  *   schedule/appendix boundaries) now paginates differently.
+ *
+ *  55 — coord-04 §1.19.d. L03 (`ca553b1c` 2026-04-23) graduated
+ *   `SurfaceBlockSnapshot.paragraph.frameProperties` from the canonical
+ *   `<w:framePr>` model (L01 parse + L02 domain shape already shipped).
+ *   L04 now honors it: paragraphs carrying out-of-flow frame properties
+ *   (ECMA-376 §17.3.1.11 — `hAnchor` / `vAnchor` / `xAlign` / `yAlign` /
+ *   `xTwips` / `yTwips` positioning with text wrapping around) return
+ *   0 from `measureBlockHeight` so the pagination flow does not
+ *   double-count them. The `dropCap="drop"` / `dropCap="margin"` case
+ *   is excluded — those frame only the initial letter, leaving the
+ *   rest of the paragraph in the main flow. L11 owns the absolute-
+ *   positioned render.
+ *
+ *   CCEP parity-lock corpus unaffected: no body-level `<w:framePr>`
+ *   exists in the 6-doc lock (`EnvelopeAddress` style carries a
+ *   framePr in `EU & Global Consultancy Services Agreement` but is
+ *   never referenced by a paragraph). Change is a forward-looking
+ *   correctness fix for the cross-layer chain now that L01→L02→L03→L04
+ *   all emit/honor framePr end-to-end. Cache envelopes from v54
+ *   invalidate because any future document with a real body framePr
+ *   paginates differently.
+ *
+ *  56 — perf(11b,07) `8d07de1b` multi-range viewport realization.
+ *   `WordReviewEditorLayoutFacet` gained `setVisibleBlockRanges` for
+ *   multi-range viewport realization (paired with coord-07 §2.9
+ *   `runtime.viewport.subscribe`). The contract widened but the
+ *   underlying layout algorithm is unchanged — persisted envelopes
+ *   remain shape-compatible. Bump is defensive so any consumer that
+ *   keyed on the facet contract refreshes the cache.
  */
-export const LAYOUT_ENGINE_VERSION = 54 as const;
+export const LAYOUT_ENGINE_VERSION = 56 as const;
 
 /**
  * Serialization schema version for the LayCache payload (the cache envelope

package/src/runtime/layout/paginated-layout-engine.ts

@@ -988,6 +988,11 @@ function measureBlockHeight(
   const compute = (): number => {
     switch (block.kind) {
       case "paragraph": {
+        // §1.19.d — out-of-flow framed paragraphs (ECMA-376 §17.3.1.11)
+        // contribute 0 to inline flow height; L11 owns the positioned render.
+        if (isOutOfFlowFrame(block.frameProperties)) {
+          return 0;
+        }
         const formatting = resolveBlockFormatting(block, defaultTabInterval, themeFonts);
         if (formatting) {
           // Provider path: sum per-line heights so canvas-backed measurements
@@ -1168,6 +1173,17 @@ export function __resolveCellWidth(
   return resolveCellWidth(gridColumns, startColumn, columnSpan, fallbackColumnWidth, gridScale);
 }
 
+/**
+ * Exposed for coord §1.19.d framePr unit tests; not part of the
+ * stable surface.
+ */
+export function __test_measureBlockHeight(
+  block: SurfaceBlockSnapshot | undefined,
+  columnWidth: number,
+): number {
+  return measureBlockHeight(block, columnWidth);
+}
+
 function resolveCellWidth(
   gridColumns: readonly number[],
   startColumn: number,
@@ -2054,6 +2070,37 @@ function currentPageNoteIds(
   return notes;
 }
 
+/**
+ * OOXML §17.3.1.11 — `<w:framePr>`.
+ *
+ * A paragraph carrying frame properties is rendered as a text frame:
+ * it is positioned relative to the page/margin/text (per `hAnchor` /
+ * `vAnchor` / `xAlign` / `yAlign` / `xTwips` / `yTwips`) and the main
+ * text flow wraps around it (per `wrap`). Consequently the framed
+ * paragraph's height MUST NOT contribute to inline block-height
+ * accounting on the page — otherwise the paginator double-counts the
+ * frame (once as inline block, once as the positioned render).
+ *
+ * The exception is `dropCap` (`drop` / `margin`): the frame wraps
+ * only the initial letter; the rest of the paragraph remains in the
+ * main flow, so the paragraph must continue to contribute its
+ * (non-dropped) height. `dropCap="none"` or absent is a full-frame.
+ *
+ * L11 owns the absolute-positioned render; L04 only needs to keep
+ * the frame out of the flow accounting.
+ */
+function isOutOfFlowFrame(
+  frameProperties:
+    | Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>["frameProperties"]
+    | undefined,
+): boolean {
+  if (!frameProperties) return false;
+  if (frameProperties.dropCap === "drop" || frameProperties.dropCap === "margin") {
+    return false;
+  }
+  return true;
+}
+
 function hasColumnBreak(block: SurfaceBlockSnapshot): boolean {
   return block.kind === "paragraph" && block.segments.some(
     (segment) =>

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

@@ -580,6 +580,18 @@ export interface WordReviewEditorLayoutFacet {
    * identical ranges are a no-op inside the runtime.
    */
   setVisibleBlockRange(range: { start: number; end: number }): void;
+  /**
+   * Multi-interval variant of `setVisibleBlockRange`. Delegates to
+   * `DocumentRuntime.setVisibleBlockRanges`. Use when the editor's
+   * visible viewport and the caret's page are disjoint — emitting the
+   * two ranges separately keeps the gap between them virtualized
+   * instead of being realized as real blocks, which was the dominant
+   * scroll-cost regression on long documents (see the perf wiki
+   * "Viewport realization").
+   */
+  setVisibleBlockRanges(
+    ranges: readonly { start: number; end: number }[],
+  ): void;
   /**
    * Triggers a surface-only refresh applying the latest visible block range.
    * Delegates to `DocumentRuntime.requestViewportRefresh`.
@@ -625,6 +637,9 @@ export interface CreateLayoutFacetInput {
    * (e.g. tests, inert facet, standalone use) both methods are no-ops.
    */
   setVisibleBlockRange?: (range: { start: number; end: number }) => void;
+  setVisibleBlockRanges?: (
+    ranges: readonly { start: number; end: number }[],
+  ) => void;
   requestViewportRefresh?: () => void;
 }
 
@@ -1236,6 +1251,18 @@ export function createLayoutFacet(
       input.setVisibleBlockRange?.(range);
     },
 
+    setVisibleBlockRanges(ranges) {
+      // Prefer the multi-range delegate when the wiring supplies it;
+      // otherwise fall back to the scalar delegate with the first range so
+      // callers that only wire the legacy path still receive something
+      // actionable (degrades to pre-multi-range behavior).
+      if (input.setVisibleBlockRanges) {
+        input.setVisibleBlockRanges(ranges);
+      } else if (input.setVisibleBlockRange && ranges.length > 0) {
+        input.setVisibleBlockRange(ranges[0]!);
+      }
+    },
+
     requestViewportRefresh() {
       input.requestViewportRefresh?.();
     },

package/src/runtime/scopes/action-validation.ts

@@ -111,6 +111,14 @@ export interface ComposeScopeValidationInputs {
    * no blockers / warnings / approval.
    */
   readonly actionId?: AIAction;
+  /**
+   * Caller-opt-in preservation policy. Honored at the preservation step
+   * only — when `opaqueFragments === true`, opaque-fragment findings
+   * downgrade from blockers to warnings (still surfaced on
+   * `validation.warnings` + audit). Other policy flags are advisory
+   * here; the compile step consumes them to drive per-step behavior.
+   */
+  readonly preservePolicy?: ReplacementScope["preserve"];
 }
 
 /**
@@ -240,6 +248,7 @@ function collectGuardVerdict(
 function collectPreservationVerdict(
   inputs: ComposeScopeValidationInputs,
   blockedReasons: string[],
+  warnings: ValidationIssue[],
 ): void {
   const { document, scope, positionMap } = inputs;
   if (!document) return;
@@ -250,10 +259,27 @@ function collectPreservationVerdict(
       ? (pm.markerScopes.get(scope.handle.stableRef.value) ?? null)
       : null;
   const verdict = computePreservationVerdict(document, range, pm);
-  if (!verdict.replaceable) {
-    for (const reason of verdict.reasons) {
-      blockedReasons.push(`preserve:${reason}`);
+  if (verdict.replaceable) return;
+  const opaqueOptIn = inputs.preservePolicy?.opaqueFragments === true;
+  for (const reason of verdict.reasons) {
+    const code = `preserve:${reason}`;
+    // Opt-in downgrade (2026-04-24): opaque-fragment reasons move from
+    // blockers → warnings when the caller opted in via
+    // `preservePolicy.opaqueFragments === true`. Scope-marker-inside
+    // reasons stay as blockers — they'd require the sibling scope to be
+    // destroyed, which is a different kind of safety (scope-identity,
+    // not preserve-only payload). Other preserve reasons keep blocker
+    // semantics until they grow their own opt-in knob.
+    if (opaqueOptIn && reason.startsWith("opaque-fragment:")) {
+      warnings.push({
+        code,
+        message:
+          "Opaque fragment present in target range; caller opted in to preserve — compile will narrow the replace range to text-only.",
+        source: "preserve",
+      });
+      continue;
     }
+    blockedReasons.push(code);
   }
 }
 
@@ -339,7 +365,7 @@ export function composeScopeValidation(
   const warnings: ValidationIssue[] = [];
 
   collectGuardVerdict(inputs.scope, inputs.runtime, blockedReasons, warnings);
-  collectPreservationVerdict(inputs, blockedReasons);
+  collectPreservationVerdict(inputs, blockedReasons, warnings);
   collectCompatibilityVerdict(inputs.runtime, blockedReasons, warnings);
 
   const actionId =

package/src/runtime/scopes/evidence.ts

@@ -38,7 +38,7 @@ import type {
 function anchorRange(anchor: CanonicalAnchor): ScopePositionRange | null {
   switch (anchor.kind) {
     case "range":
-      return { from: anchor.range.from, to: anchor.range.to };
+      return { from: anchor.from, to: anchor.to };
     case "node":
       return { from: anchor.at, to: anchor.at };
     case "detached":

package/src/runtime/scopes/replacement/apply.ts

@@ -147,6 +147,7 @@ export function applyScopeReplacement(
     document: docBefore,
     enumeratedScope: resolvedEnumerated,
     ...(inputs.actionId ? { actionId: inputs.actionId } : {}),
+    ...(proposed.preserve ? { preservePolicy: proposed.preserve } : {}),
   });
 
   if (!verdict.safe) {

package/src/runtime/scopes/review-bundle.ts

@@ -57,7 +57,7 @@ function anchorToRange(
 ): ScopePositionRange | null {
   switch (anchor.kind) {
     case "range":
-      return { from: anchor.range.from, to: anchor.range.to };
+      return { from: anchor.from, to: anchor.to };
     case "node":
       return { from: anchor.at, to: anchor.at };
     case "detached":