@beyondwork/docx-react-component 1.0.74 → 1.0.76

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.74",
+  "version": "1.0.76",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [

package/src/api/public-types.ts

@@ -5625,6 +5625,13 @@ export interface ShortcutDelegationContext {
   selectionRange: SelectionSnapshot;
 }
 
+/**
+ * Resolver contract (`resolveChromeVisibilityForPreset`): every field on
+ * this interface is REQUIRED — no `| undefined`, no optional sugar. Each
+ * preset's default-visibility block (`src/api/v3/ui/chrome-preset-model.ts`)
+ * MUST set every field. If you add a new surface visibility flag, add it
+ * here AND to all preset default blocks in the same commit.
+ */
 export interface WordReviewEditorChromeVisibility {
   toolbar: boolean;
   alerts: boolean;

package/src/api/v3/runtime/workflow.ts

@@ -11,12 +11,16 @@
 import type { RuntimeApiHandle } from "../_runtime-handle.ts";
 import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
 import type {
+  EditorStoryTarget,
   OverlayKind,
   OverlayVisibilityPolicy,
   WorkflowMarkupModePolicy,
 } from "../../public-types.ts";
 import { emitUxResponse } from "../_ux-response.ts";
-import { createScopeFromBlockId } from "../../../runtime/workflow/scope-writer.ts";
+import {
+  createScopeFromAnchor,
+  createScopeFromBlockId,
+} from "../../../runtime/workflow/scope-writer.ts";
 import { attachScopeMetadata } from "../../../runtime/workflow/metadata-writer.ts";
 import {
   DEFAULT_REGISTRY_ENTRIES,
@@ -113,6 +117,59 @@ export interface CreateScopeResult {
   readonly status: "created" | "block-not-found";
 }
 
+/**
+ * Input for `createScopeFromAnchor` — sub-block marker-backed scope.
+ *
+ * Use this variant when the scope must bracket a range *within* a block
+ * (a phrase inside a paragraph) or across blocks (a selection that
+ * spans paragraph boundaries). For whole-block scopes, prefer
+ * `createScope({blockId})` — it stays block-aligned after edits at the
+ * block boundary.
+ *
+ * The `from`/`to` positions are consumed **once** at creation. After
+ * this call returns, use the returned `scopeId` as the reference. Do
+ * not cache, store, or reuse the positions — they are positional
+ * queries (KI-P9), valid only in the document state they were captured
+ * in. The scope itself is marker-backed and travels with its bracketed
+ * content through any number of subsequent edits.
+ */
+export interface CreateScopeFromAnchorInput {
+  readonly anchor: {
+    /** Zero-based surface offset, inclusive. Must be `>= 0`. */
+    readonly from: number;
+    /** Zero-based surface offset, exclusive of the marker slot. Must be `>= from` and `<= storyLength`. */
+    readonly to: number;
+    /** Non-main-body story (footnote / header / endnote). Defaults to `{kind:"main"}`. */
+    readonly storyTarget?: EditorStoryTarget;
+  };
+  readonly mode?: "edit" | "suggest" | "comment" | "view";
+  readonly label?: string;
+  readonly assoc?: { readonly start: -1 | 1; readonly end: -1 | 1 };
+  readonly stableRefHint?:
+    | "scope-id"
+    | "bookmark"
+    | "semantic-path"
+    | "runtime-handle";
+}
+
+export type CreateScopeFromAnchorResult =
+  | { readonly scopeId: string; readonly status: "created" }
+  | {
+      readonly scopeId: "";
+      readonly status: "range-invalid";
+      readonly reason:
+        | "from-negative"
+        | "to-less-than-from"
+        | "range-exceeds-story-length";
+      readonly from: number;
+      readonly to: number;
+      readonly storyLength: number;
+      /** Agent-actionable single-sentence explanation. Safe to surface to LLM tool replies as-is. */
+      readonly message: string;
+      /** Machine-routable next-step hint (`"clamp-from-to-zero"` / `"swap-from-and-to"` / `"clamp-to-to-storyLength-or-pick-a-different-range"`). */
+      readonly nextStep: string;
+    };
+
 export const createScopeMetadata: ApiV3FnMetadata = {
   name: "runtime.workflow.createScope",
   status: "live-with-adapter",
@@ -129,6 +186,32 @@ export const createScopeMetadata: ApiV3FnMetadata = {
   rwdReference: "§Runtime API § runtime.workflow.createScope",
 };
 
+export const createScopeFromAnchorMetadata: ApiV3FnMetadata = {
+  name: "runtime.workflow.createScopeFromAnchor",
+  status: "live-with-adapter",
+  sourceLayer: "workflow-review",
+  liveEvidence: {
+    runnerTest: "test/api/v3/workflow-create-scope-from-anchor-live.test.ts",
+    commit: "pending",
+  },
+  uxIntent: {
+    uiVisible: true,
+    expectsUxResponse: "scope-created",
+    expectedDelta:
+      "rail shows new scope chip for the sub-block range; editor surface refreshes with inline markers planted at from/to",
+  },
+  agentMetadata: {
+    readOrMutate: "mutate",
+    boundedScope: "selection",
+    auditCategory: "scope-creation",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "customXml",
+  broadcastsVia: "crdt",
+  rwdReference:
+    "§Runtime API § runtime.workflow.createScopeFromAnchor. Companion to createScope({blockId}) for sub-block ranges. Consumes from/to once to plant inline scope_marker_start/end; the returned scopeId is the durable reference (KI-P9).",
+};
+
 export interface AttachMetadataInput {
   readonly scopeId: string;
   readonly metadataId: string;
@@ -411,6 +494,52 @@ export function createWorkflowFamily(runtime: RuntimeApiHandle) {
       return { scopeId: adapterResult.scopeId, status: "created" };
     },
 
+    createScopeFromAnchor(
+      input: CreateScopeFromAnchorInput,
+    ): CreateScopeFromAnchorResult {
+      // @endStateApi — live-with-adapter. Delegates to the layer-06
+      // scope-writer with the anchor range passed through directly.
+      // Bounds are validated against the story length; out-of-bounds
+      // ranges return a typed `range-invalid` discriminator rather than
+      // inventing a scopeId.
+      const adapterResult = createScopeFromAnchor(runtime, {
+        anchor: input.anchor,
+        mode: input.mode,
+        label: input.label,
+        ...(input.assoc ? { assoc: input.assoc } : {}),
+        ...(input.stableRefHint
+          ? { stableRefHint: input.stableRefHint }
+          : {}),
+      });
+      emitUxResponse(runtime, {
+        apiFn: createScopeFromAnchorMetadata.name,
+        intent: createScopeFromAnchorMetadata.uxIntent.expectedDelta ?? "",
+        mockOrLive: "live",
+        uiVisible: true,
+        expectedDelta: createScopeFromAnchorMetadata.uxIntent.expectedDelta,
+        actualDelta:
+          adapterResult.status === "created"
+            ? {
+                kind: "inline-change",
+                payload: { scopeId: adapterResult.scopeId },
+              }
+            : undefined,
+      });
+      if (adapterResult.status !== "created") {
+        return {
+          scopeId: "",
+          status: "range-invalid",
+          reason: adapterResult.reason,
+          from: adapterResult.from,
+          to: adapterResult.to,
+          storyLength: adapterResult.storyLength,
+          message: adapterResult.message,
+          nextStep: adapterResult.nextStep,
+        };
+      }
+      return { scopeId: adapterResult.scopeId, status: "created" };
+    },
+
     getVisibilityPolicy(kind: OverlayKind): OverlayVisibilityPolicy | null {
       // @endStateApi — live. Class-A policy read; composition with
       // class-C local preference lives in L10 (`ui.overlays.getVisibility`).

package/src/io/ooxml/parse-headers-footers.ts

@@ -17,6 +17,7 @@ import { resolveHighlightColor } from "./highlight-colors.ts";
 import type { ParseDrawingOpts } from "./parse-drawing.ts";
 import { parseFFDataFromFldChar } from "./parse-ffdata.ts";
 import { classifyFieldInstruction } from "./parse-fields.ts";
+import { isSafeTableFieldInstruction } from "./table-opaque-preservation.ts";
 import { parseXmlWithOffsets as parseXml } from "./xml-parser.ts";
 import { localName, readStringAttr } from "./xml-attr-helpers.ts";
 import {
@@ -1018,8 +1019,12 @@ function containsRiskyElement(element: XmlElementNode): boolean {
       const instruction =
         readStringAttr(child, "w:instr") ??
         extractTextContent(child);
-      const classification = classifyFieldInstruction(instruction);
-      if (!isSafeSecondaryStoryFieldFamily(classification.family)) {
+      // Coord-01 §11 unification (2026-04-24): the field-safety check
+      // is delegated to the shared `isSafeTableFieldInstruction` helper
+      // so body-direct + secondary-story tables apply the same
+      // allowlist. Legacy form fields (FORMTEXT/FORMCHECKBOX/
+      // FORMDROPDOWN) now pass here just like in main-story tables.
+      if (!isSafeTableFieldInstruction(instruction)) {
         return true;
       }
       continue;
@@ -1041,17 +1046,6 @@ function containsRiskyElement(element: XmlElementNode): boolean {
   return false;
 }
 
-function isSafeSecondaryStoryFieldFamily(family: string): boolean {
-  return (
-    family === "REF" ||
-    family === "PAGEREF" ||
-    family === "NOTEREF" ||
-    family === "TOC" ||
-    family === "PAGE" ||
-    family === "NUMPAGES"
-  );
-}
-
 function parseSimpleTableElement(
   tblElement: XmlElementNode,
   sourceXml: string,

package/src/io/ooxml/parse-main-document.ts

@@ -41,6 +41,7 @@ import { parseShapeXml, parseVmlXml } from "./parse-shapes.ts";
 import { parseObject } from "./parse-object.ts";
 import { parseDrawingFrame } from "./parse-drawing.ts";
 import { readFrameProperties } from "./parse-paragraph-formatting.ts";
+import { tableRequiresOpaquePreservation } from "./table-opaque-preservation.ts";
 import { classifyFieldInstruction } from "./parse-fields.ts";
 import { parseFFDataFromFldChar } from "./parse-ffdata.ts";
 import { resolveHighlightColor } from "./highlight-colors.ts";
@@ -2020,37 +2021,12 @@ function readCellCnfStyle(node: XmlElementNode): string | undefined {
  * Tables matching this check stay opaque until the respective features
  * are implemented in the table editing path.
  */
-function tableRequiresOpaquePreservation(rawXml: string): boolean {
-  // Safe table-local content now includes hyperlinks, bookmarks, comments,
-  // nested tables, floating images, VML preview atoms, and bounded field
-  // families already owned by the current field slice. Risky table-local
-  // semantics still fail closed to preserve-only.
-  if (/<w:(ins|del|rPrChange|pPrChange|tblPrChange|trPrChange|tcPrChange|sectPrChange|cellIns|cellDel|cellMerge|smartTag)\b/.test(rawXml)) {
-    return true;
-  }
-
-  const simpleInstructions = [...rawXml.matchAll(/\bw:instr="([^"]*)"/g)].map((match) => match[1] ?? "");
-  const complexInstructions = extractComplexFieldInstructions(rawXml);
-  for (const instruction of [...simpleInstructions, ...complexInstructions]) {
-    const classification = classifyFieldInstruction(instruction);
-    if (!isSafeMainStoryTableFieldFamily(classification.family)) {
-      return true;
-    }
-  }
-
-  return false;
-}
-
-function isSafeMainStoryTableFieldFamily(family: string): boolean {
-  return (
-    family === "REF" ||
-    family === "PAGEREF" ||
-    family === "NOTEREF" ||
-    family === "TOC" ||
-    family === "PAGE" ||
-    family === "NUMPAGES"
-  );
-}
+// `tableRequiresOpaquePreservation` now lives in
+// `src/io/ooxml/table-opaque-preservation.ts` as a shared helper used by
+// `parse-main-document.ts`, `parse-headers-footers.ts`, and
+// `parse-footnotes.ts`. Unified 2026-04-24 per coord-01 §11 to stop the
+// three parsers from drifting out of alignment. The top-of-file import
+// `tableRequiresOpaquePreservation` points at that module.
 
 function extractComplexFieldInstructions(rawXml: string): string[] {
   const tokenPattern =

package/src/io/ooxml/table-opaque-preservation.ts

@@ -0,0 +1,171 @@
+/**
+ * Unified table-opaque-preservation predicate — shared across
+ * `parse-main-document.ts`, `parse-headers-footers.ts`, and
+ * `parse-footnotes.ts` so the three parsers agree on which tables can
+ * be promoted to the typed `TableNode` shape and which must fall back
+ * to `opaque_block` for lossless rawXml round-trip.
+ *
+ * ## History
+ *
+ * Before this module existed, each of the three parsers maintained its
+ * own divergent allowlist. That divergence drove the coord-01 §11
+ * finding (2026-04-24): legacy form fields (`FORMTEXT`,
+ * `FORMCHECKBOX`, `FORMDROPDOWN`) classify as `UNKNOWN` under
+ * `FIELD_FAMILY_PATTERN` (which targets data-field families), so both
+ * the main-story and secondary-story table predicates rejected them
+ * even though the body-direct paragraph parser path (via
+ * `parseFFDataFromFldChar`) handles them correctly. The result was
+ * 58 cell paragraphs lost on APS Short Form because 2 body-direct
+ * tables flattened to opaque_block; 5 additional footer tables on
+ * the same doc also flatten (those carry `DOCPROPERTY` — a real data
+ * field, distinct from the legacy form-field case).
+ *
+ * ## Contract
+ *
+ * A `<w:tbl>` is "safe to parse as structured" iff NONE of the
+ * following are true:
+ *
+ * 1. **Revision markup.** `<w:ins>`, `<w:del>`, `<w:moveFrom>`,
+ *    `<w:moveTo>`, `<w:rPrChange>`, `<w:pPrChange>`,
+ *    `<w:tblPrChange>`, `<w:trPrChange>`, `<w:tcPrChange>`,
+ *    `<w:sectPrChange>`, `<w:cellIns>`, `<w:cellDel>`,
+ *    `<w:cellMerge>`, `<w:smartTag>`.
+ *    Rationale: tracked-change-aware table editing isn't implemented;
+ *    flattening preserves fidelity until it is.
+ *
+ * 2. **Field instruction outside the safe set.** Scan every
+ *    `w:instr` simple-field attribute + every `<w:instrText>` inside
+ *    a complex field (`<w:fldChar>begin</w:fldChar>...end`) and
+ *    classify via `classifyFieldInstruction`. If the classified
+ *    family isn't in `SAFE_TABLE_FIELD_FAMILIES` AND the instruction
+ *    isn't a legacy form field (`isLegacyFormFieldInstruction`), the
+ *    table flattens. The legacy-form-field short-circuit is the
+ *    coord-01 §11 fix — those tokens are fully supported by the cell
+ *    paragraph parser but classify as `UNKNOWN`.
+ *
+ * Extending this contract is a cross-layer architectural decision:
+ * widening `SAFE_TABLE_FIELD_FAMILIES` lets more tables parse as
+ * structured but commits the edit-command layer (L06/L08) to handle
+ * each field family's cell-level edit semantics. Keep this list
+ * aligned with the field families supported by the runtime
+ * formatting + scope-command pipeline.
+ */
+
+import { classifyFieldInstruction } from "./parse-fields.ts";
+
+/**
+ * Field families safe enough to leave a `<w:tbl>` in structured
+ * canonical form. Widening this set commits L06 / L08 to cell-level
+ * edit semantics for that family — don't expand opportunistically.
+ */
+export const SAFE_TABLE_FIELD_FAMILIES: ReadonlySet<string> = new Set([
+  "REF",
+  "PAGEREF",
+  "NOTEREF",
+  "TOC",
+  "PAGE",
+  "NUMPAGES",
+]);
+
+/**
+ * Revision + structural markup that forces table flattening.
+ */
+const RISKY_TABLE_MARKUP_RE =
+  /<w:(ins|del|moveFrom|moveTo|rPrChange|pPrChange|tblPrChange|trPrChange|tcPrChange|sectPrChange|cellIns|cellDel|cellMerge|smartTag)\b/;
+
+const SIMPLE_FIELD_INSTR_RE = /\bw:instr="([^"]*)"/g;
+
+const COMPLEX_FIELD_TOKEN_RE =
+  /<(?:\w+:)?fldChar\b[^>]*?(?:\w+:)?fldCharType="(begin|separate|end)"[^>]*?(?:\/>|>[\s\S]*?<\/(?:\w+:)?fldChar>)|<(?:\w+:)?instrText\b[^>]*>([\s\S]*?)<\/(?:\w+:)?instrText>/gu;
+
+/**
+ * Decode the minimal set of XML entities that can appear inside an
+ * `instrText` payload. `classifyFieldInstruction` consumes the raw
+ * instruction text, so we normalize `&amp;` / `&quot;` / `&lt;` /
+ * `&gt;` / `&apos;` before handing it off. Matches the pre-existing
+ * behavior in `parse-main-document.ts::extractComplexFieldInstructions`.
+ */
+function decodeXmlEntities(text: string): string {
+  return text
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, "&");
+}
+
+/**
+ * Extract every complex-field instruction (`<w:fldChar
+ * fldCharType="begin">...<w:instrText>...</w:instrText>...</w:fldChar
+ * fldCharType="end">`) as a single concatenated instruction string.
+ * Mirrors `parse-main-document.ts::extractComplexFieldInstructions`.
+ */
+export function extractComplexFieldInstructionsFromRaw(rawXml: string): string[] {
+  const instructions: string[] = [];
+  let active = "";
+  let capturing = false;
+  for (const match of rawXml.matchAll(COMPLEX_FIELD_TOKEN_RE)) {
+    const [, fldCharType, instrText] = match;
+    if (fldCharType === "begin") {
+      active = "";
+      capturing = true;
+      continue;
+    }
+    if (fldCharType === "separate" || fldCharType === "end") {
+      if (capturing && active.trim().length > 0) instructions.push(active);
+      active = "";
+      capturing = false;
+      continue;
+    }
+    if (capturing && instrText !== undefined) active += decodeXmlEntities(instrText);
+  }
+  return instructions;
+}
+
+/**
+ * Legacy form fields (ECMA-376 §17.16.21) — `FORMTEXT`, `FORMCHECKBOX`,
+ * `FORMDROPDOWN`. These are fully supported by the body-direct
+ * paragraph parser via `parseFFDataFromFldChar` but classify as
+ * `UNKNOWN` under `FIELD_FAMILY_PATTERN` (which targets data-field
+ * families like REF / TOC / MERGEFIELD). Short-circuiting them lets
+ * form-field cells stay in structured canonical tables instead of
+ * flattening the entire table to `opaque_block`. Coord-01 §11, 2026-04-24.
+ */
+export function isLegacyFormFieldInstruction(instruction: string): boolean {
+  return /^\s*(FORMTEXT|FORMCHECKBOX|FORMDROPDOWN)\b/i.test(instruction);
+}
+
+/**
+ * Decides whether a single field instruction (either `w:instr`
+ * attribute value or concatenated `instrText` run) is safe for
+ * structured-table parsing. Used by the shared predicate below;
+ * exposed for direct callers (the debug diagnostics script runs
+ * this to classify source instructions alongside the canonical).
+ */
+export function isSafeTableFieldInstruction(instruction: string): boolean {
+  if (isLegacyFormFieldInstruction(instruction)) return true;
+  const family = classifyFieldInstruction(instruction).family;
+  return SAFE_TABLE_FIELD_FAMILIES.has(family);
+}
+
+/**
+ * Shared `<w:tbl>` opaque-preservation predicate. Returns `true`
+ * when the table must fall back to `opaque_block` for lossless
+ * round-trip, `false` when `parseTable` / `parseSimpleTableElement`
+ * can promote it to a structured `TableNode`.
+ *
+ * Callers (`parse-main-document.ts`, `parse-headers-footers.ts`,
+ * `parse-footnotes.ts`) pass the raw XML of the `<w:tbl>` element.
+ */
+export function tableRequiresOpaquePreservation(rawXml: string): boolean {
+  if (RISKY_TABLE_MARKUP_RE.test(rawXml)) return true;
+
+  const simpleInstructions = [...rawXml.matchAll(SIMPLE_FIELD_INSTR_RE)].map(
+    (match) => match[1] ?? "",
+  );
+  const complexInstructions = extractComplexFieldInstructionsFromRaw(rawXml);
+  for (const instruction of [...simpleInstructions, ...complexInstructions]) {
+    if (!isSafeTableFieldInstruction(instruction)) return true;
+  }
+  return false;
+}

package/src/runtime/document-runtime.ts

@@ -1036,6 +1036,9 @@ function normalizeViewportRanges(
   for (let i = 1; i < cleaned.length; i += 1) {
     const next = cleaned[i]!;
     const last = merged[merged.length - 1]!;
+    // Mutation is safe: `last` is a fresh object from the `.map` step above,
+    // not aliased with any caller-provided input. The `Object.freeze` at the
+    // return site only runs after the merge loop finishes.
     if (next.start <= last.end) {
       if (next.end > last.end) last.end = next.end;
     } else {
@@ -1372,6 +1375,17 @@ export function createDocumentRuntime(
     | {
         revisionToken: string;
         activeStoryKey: string;
+        /**
+         * Serialized viewport ranges at build time. A surface snapshot is
+         * only reusable for a subsequent `getCachedSurface` call if the
+         * runtime's current `viewportRangesKey` matches — otherwise the
+         * cached snapshot realizes a different set of blocks as real vs
+         * placeholder-culled than the current runtime state demands.
+         * Pre-refactor/11b this was a (revisionToken, activeStoryKey) key
+         * only, which was silently stale-prone when callers applied new
+         * viewport ranges without also calling `requestViewportRefresh()`.
+         */
+        viewportRangesKey: string;
         snapshot: RuntimeRenderSnapshot["surface"];
       }
     | undefined;
@@ -1533,7 +1547,8 @@ export function createDocumentRuntime(
     if (
       cachedSurface &&
       cachedSurface.revisionToken === state.revisionToken &&
-      cachedSurface.activeStoryKey === activeStoryKey
+      cachedSurface.activeStoryKey === activeStoryKey &&
+      cachedSurface.viewportRangesKey === viewportRangesKey
     ) {
       return cachedSurface.snapshot;
     }
@@ -1549,8 +1564,13 @@ export function createDocumentRuntime(
     cachedSurface = {
       revisionToken: state.revisionToken,
       activeStoryKey,
+      viewportRangesKey,
       snapshot,
     };
+    // Keep the scroll-path fingerprint in lockstep so a subsequent
+    // `maybeRefreshSurfaceForViewport` sees the freshly-built snapshot
+    // and short-circuits instead of paying a redundant projection.
+    cachedSurfaceFingerprint = `${state.revisionToken}|${activeStoryKey}|${viewportRangesKey}|${String(state.selection.anchor)}:${String(state.selection.head)}`;
     return snapshot;
   }
 
@@ -2394,6 +2414,7 @@ export function createDocumentRuntime(
     cachedSurface = {
       revisionToken: state.revisionToken,
       activeStoryKey: storyTargetKey(activeStory),
+      viewportRangesKey,
       snapshot: newSurface,
     };
     cachedRenderSnapshot = {
@@ -2427,6 +2448,12 @@ export function createDocumentRuntime(
 
   function invalidateDerivedRuntimeCaches(): void {
     cachedSurface = undefined;
+    // Keep the scroll-path fingerprint in lockstep with `cachedSurface`.
+    // Otherwise a post-commit `requestViewportRefresh` would compute a new
+    // fingerprint, see it differs from the stale pre-commit value, and
+    // rebuild + broadcast even when the freshly-hydrated `cachedSurface`
+    // already matches — wasted projection + listener fan-out.
+    cachedSurfaceFingerprint = null;
     cachedCompatibility = undefined;
     cachedComments = undefined;
     cachedTrackedChanges = undefined;

package/src/runtime/surface-projection.ts

@@ -106,6 +106,15 @@ export interface SurfaceProjectionOptions {
    * block stays real without realizing the document-scale gap between the
    * two). Callers still supplying the legacy scalar `viewportBlockRange` get
    * wrapped into a single-element array internally.
+   *
+   * **Invariant (caller responsibility):** intervals must be sorted ascending
+   * by `start` and non-overlapping. The projection function itself only
+   * checks membership — it does not sort or merge — so an unsorted input
+   * produces a correct `isInViewport` answer but the snapshot's
+   * `viewportBlockRanges` field carries the unnormalized shape to downstream
+   * consumers (e.g. the surface-build-key serializer). Runtime callers
+   * route through `DocumentRuntime.applyViewportRanges` which normalizes;
+   * if you call `createEditorSurfaceSnapshot` directly, normalize first.
    */
   viewportBlockRanges?: readonly { start: number; end: number }[] | null;
   /** @deprecated use `viewportBlockRanges`. Kept for back-compat; wrapped into a 1-element array when supplied alone. */