@beyondwork/docx-react-component 1.0.78 → 1.0.80

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.78",
+  "version": "1.0.80",
   "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

@@ -1211,6 +1211,18 @@ export type SurfaceInlineSegment =
        * is enforced by `test/runtime/formatting/production-boundary.test.ts`.
        */
       revisionDisplay?: {
+        /**
+         * Identity of the attached revision. Render consumers emit
+         * `data-revision-id` and route sidebar scroll-to-revision off
+         * this field rather than re-deriving from the review store.
+         */
+        revisionId: string;
+        /**
+         * The revision's kind. Mirrors `RevisionRecord.kind` on the
+         * canonical document. Render consumers branch on this (e.g.
+         * widget-bracket placement in suggestions mode).
+         */
+        kind: "insertion" | "deletion" | "formatting" | "move" | "property-change";
         markupMode: "clean" | "simple" | "all";
         hidden?: boolean;
         strikethrough?: boolean;
@@ -1566,6 +1578,22 @@ export type SurfaceBlockSnapshot =
        * See CLAUDE.md (lane status table)
        */
       placeholderSize?: number;
+      /**
+       * Visual height of the block the placeholder stands in for, in twips,
+       * as computed by the L04 paginator against the fully-realized surface.
+       * When present, the PM placeholder emits a fixed-height `<div>` so the
+       * scrollable canvas matches what the realized block will occupy once
+       * it re-enters the viewport — eliminating the "paragraphs jump around
+       * pagination gaps" flicker that plagued culled regions rendered as
+       * single-line ZWSP stubs.
+       *
+       * Populated by `DocumentRuntime.buildRenderSnapshot()` after each
+       * pagination pass; surface-projection itself does not set it (L03 has
+       * no layout data). Consumers that build a surface without a runtime
+       * (tests, plain-text preview) safely leave it `undefined` and fall
+       * back to the `min-height: 20px` behaviour.
+       */
+      placeholderHeightTwips?: number;
       state: "locked-preserve-only" | "placeholder-culled";
     };
 
@@ -2487,9 +2515,40 @@ export interface AddScopeParams {
 }
 
 export interface AddScopeResult {
+  /**
+   * Minted scope id. Empty string (`""`) iff the marker plant failed —
+   * in that case `anchor.kind === "detached"` + `plantStatus.planted`
+   * is `false`. Pre-2026-04-24 a plant failure silently returned a
+   * non-empty scopeId that later resolved to `scope-not-resolvable`;
+   * callers must now check `scopeId.length > 0` (or equivalently
+   * `plantStatus?.planted !== false`) before using the id.
+   */
   scopeId: string;
-  /** Range anchor derived from the just-inserted marker positions. */
+  /** Range anchor derived from the just-inserted marker positions, or a detached placeholder on plant failure. */
   anchor: EditorAnchorProjection;
+  /**
+   * Structured diagnostic for the marker-plant attempt. Omitted on the
+   * happy path for back-compat; populated with `planted: false` + a
+   * typed reason when the plant was refused (non-paragraph target,
+   * out-of-bounds, empty-document). Cross-paragraph ranges plant
+   * successfully as of 2026-04-24 — see the multi-paragraph-scopes
+   * slice. Callers that previously assumed every returned `scopeId`
+   * was live should migrate to checking this field.
+   */
+  plantStatus?: {
+    readonly planted: false;
+    readonly reason:
+      | "non-paragraph-target"
+      | "range-out-of-bounds"
+      | "empty-document";
+    readonly requestedFrom: number;
+    readonly requestedTo: number;
+    /** Present on `non-paragraph-target`. */
+    readonly blockIndex?: number;
+    readonly blockKind?: string;
+    /** Present on `range-out-of-bounds`. */
+    readonly storyLength?: number;
+  };
 }
 
 export interface ExportDocxOptions {

package/src/api/v3/ai/resolve.ts

@@ -1,13 +1,19 @@
 /**
  * @endStateApi v3 — `ai.resolve` family.
  *
- * Slice 3 of refactor/08 graduates `resolveReference` to
- * `live-with-adapter` for the FOUR DETERMINISTIC hint kinds: `scope-id`,
- * `semantic-path`, `offset`, and `range`. Offset / range resolution now
- * honors precise nested-kind ranges (fields, table rows, table cells)
- * via the scope-compiler's specificity tie-breaker — see
- * `docs/architecture/08-semantic-scope-compiler.md` §"Resolve-reference
- * precision" for the specificity table.
+ * Slice 3 of refactor/08 graduated `resolveReference` to
+ * `live-with-adapter`. Post-KI-P9 (2026-04-24) the reference union
+ * carries **three durable reference kinds**: `scope-id`, `semantic-path`,
+ * and `natural-language`. Positional queries (`offset` / `range`) were
+ * split into `queryScopeAtPosition(at)` / `queryScopeInRange(from, to)`
+ * one-shot APIs that return `ScopeHandle | null` directly — the
+ * type-system split prevents a positional hint from being cached or
+ * round-tripped as a reference across a mutation.
+ *
+ * Offset / range lookups still honor precise nested-kind ranges (fields,
+ * table rows, table cells) via the scope-compiler's specificity
+ * tie-breaker — see `docs/architecture/08-semantic-scope-compiler.md`
+ * §"Resolve-reference precision" for the specificity table.
  *
  * The `natural-language` hint remains **partial by design**. The live
  * path is a deterministic substring matcher over:

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

@@ -160,13 +160,17 @@ export type CreateScopeFromAnchorResult =
       readonly reason:
         | "from-negative"
         | "to-less-than-from"
-        | "range-exceeds-story-length";
+        | "range-exceeds-story-length"
+        | "non-paragraph-target"
+        | "empty-document";
       readonly from: number;
       readonly to: number;
       readonly storyLength: number;
+      readonly blockIndex?: number;
+      readonly blockKind?: string;
       /** 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"`). */
+      /** Machine-routable next-step hint. */
       readonly nextStep: string;
     };
 
@@ -533,6 +537,12 @@ export function createWorkflowFamily(runtime: RuntimeApiHandle) {
           from: adapterResult.from,
           to: adapterResult.to,
           storyLength: adapterResult.storyLength,
+          ...(adapterResult.blockIndex !== undefined
+            ? { blockIndex: adapterResult.blockIndex }
+            : {}),
+          ...(adapterResult.blockKind !== undefined
+            ? { blockKind: adapterResult.blockKind }
+            : {}),
           message: adapterResult.message,
           nextStep: adapterResult.nextStep,
         };

package/src/core/commands/add-scope.ts

@@ -7,18 +7,72 @@ import type {
 } from "../../model/canonical-document.ts";
 import type { CanonicalDocumentEnvelope } from "../state/editor-state.ts";
 
-export interface InsertScopeMarkersResult {
-  document: CanonicalDocumentEnvelope;
-  scopeId: string;
-}
+/**
+ * Discriminated return — pre-2026-04-24 this helper silently returned
+ * the input document unchanged on every failure mode, which left
+ * callers holding a minted `scopeId` that referenced nothing in the
+ * canonical tree. `compileScopeById` later returned null and the v3
+ * surface emitted `scope-not-resolvable:<scopeId>` without the caller
+ * knowing whether the scope was ever live. Every non-`"planted"`
+ * status is now typed so callers can discriminate + surface
+ * agent-actionable recovery hints.
+ *
+ * Cross-paragraph ranges are first-class (planted) as of the
+ * 2026-04-24 multi-paragraph-scopes slice. The `cross-paragraph-range`
+ * failure variant no longer exists — markers now span paragraphs.
+ */
+export type InsertScopeMarkersResult =
+  | {
+      readonly status: "planted";
+      readonly document: CanonicalDocumentEnvelope;
+      readonly scopeId: string;
+      /** Absolute span that got planted (after from/to normalization). */
+      readonly plantedRange: { readonly from: number; readonly to: number };
+    }
+  | {
+      readonly status: "non-paragraph-target";
+      readonly scopeId: string;
+      readonly from: number;
+      readonly to: number;
+      readonly blockIndex: number;
+      readonly blockKind: string;
+    }
+  | {
+      readonly status: "range-out-of-bounds";
+      readonly scopeId: string;
+      readonly from: number;
+      readonly to: number;
+      readonly storyLength: number;
+    }
+  | {
+      readonly status: "empty-document";
+      readonly scopeId: string;
+      readonly from: number;
+      readonly to: number;
+    };
 
 /**
- * Pure helper — returns a new CanonicalDocumentEnvelope with a pair of
- * scope-marker inline nodes inserted at the given position range.
+ * Pure helper — returns a discriminated result describing whether a
+ * pair of `scope_marker_start` / `scope_marker_end` inline nodes got
+ * inserted at `[from, to]`.
+ *
+ * Same-paragraph ranges insert both markers into the single owning
+ * paragraph. Cross-paragraph ranges place the start marker inside the
+ * paragraph containing `from` and the end marker inside the paragraph
+ * containing `to`; intermediate top-level blocks (paragraphs, tables,
+ * section breaks) are passed through unmodified and fall inside the
+ * scope by document order.
+ *
+ * Failure modes (all previously silent — pre-2026-04-24):
+ *   - `non-paragraph-target` — either `from` or `to` lands inside a
+ *     non-paragraph block (table / SDT / section_break). Marker
+ *     scopes only plant inside paragraphs.
+ *   - `range-out-of-bounds` — `to` exceeds the main story length.
+ *   - `empty-document` — the document has no root / no children.
  *
- * Supports the common case: `from` and `to` land in the same top-level
- * paragraph. Cross-paragraph ranges are currently a no-op and return the
- * document unchanged — multi-block scopes ship in a follow-up slice.
+ * Each failure variant names the scopeId the caller had minted but
+ * does NOT mutate the document — callers treat it as a hard failure
+ * and must not register the scopeId on the overlay.
  */
 export function insertScopeMarkers(
   document: CanonicalDocumentEnvelope,
@@ -28,59 +82,166 @@ export function insertScopeMarkers(
     to: number;
   },
 ): InsertScopeMarkersResult {
-  const { scopeId, from, to } = params;
+  const { scopeId } = params;
   const root = document.content as DocumentRootNode;
-  if (!root || root.type !== "doc") return { document, scopeId };
+  const normalizedFrom = Math.min(params.from, params.to);
+  const normalizedTo = Math.max(params.from, params.to);
 
-  const normalizedFrom = Math.min(from, to);
-  const normalizedTo = Math.max(from, to);
+  if (!root || root.type !== "doc" || root.children.length === 0) {
+    return {
+      status: "empty-document",
+      scopeId,
+      from: normalizedFrom,
+      to: normalizedTo,
+    };
+  }
 
+  // Pre-pass — locate which block each of `from` and `to` resolves to,
+  // compute story length, and build per-paragraph slot envelopes.
+  // **Invariant:** the cursor arithmetic here MUST match
+  // `src/runtime/scopes/position-map.ts::computeBlockPositions`
+  // (same `inlineLength`, same `+1` per-block boundary). Layer 04
+  // cannot change one walker without the other or cross-paragraph
+  // marker insertion silently drifts vs. enumerated scope ranges.
+  type ParaSlot = { index: number; from: number; to: number };
+  const paraSlots: ParaSlot[] = [];
   let cursor = 0;
-  let inserted = false;
-  const children = root.children.map((block, blockIndex) => {
-    if (inserted) return block;
-    if (block.type !== "paragraph") {
-      cursor += 1;
-      if (blockIndex < root.children.length - 1) cursor += 1;
-      return block;
-    }
-
-    const paragraphFrom = cursor;
-    const paragraphLength = block.children.reduce(
-      (total, child) => total + inlineLength(child as InlineNode),
-      0,
-    );
-    const paragraphTo = paragraphFrom + paragraphLength;
-    cursor = paragraphTo + 1;
+  let fromBlockIndex = -1;
+  let fromBlockKind: string | null = null;
+  let toBlockIndex = -1;
+  let toBlockKind: string | null = null;
+  let storyLength = 0;
 
+  for (let i = 0; i < root.children.length; i += 1) {
+    const block = root.children[i]!;
+    const blockFrom = cursor;
+    let blockLength: number;
+    if (block.type === "paragraph") {
+      blockLength = block.children.reduce(
+        (total, child) => total + inlineLength(child as InlineNode),
+        0,
+      );
+      paraSlots.push({ index: i, from: blockFrom, to: blockFrom + blockLength });
+    } else {
+      blockLength = 1;
+    }
+    const blockTo = blockFrom + blockLength;
     if (
-      normalizedFrom < paragraphFrom ||
-      normalizedTo > paragraphTo ||
-      normalizedFrom > paragraphTo
+      fromBlockIndex === -1 &&
+      normalizedFrom >= blockFrom &&
+      normalizedFrom <= blockTo
     ) {
-      return block;
+      fromBlockIndex = i;
+      fromBlockKind = block.type;
     }
+    if (
+      toBlockIndex === -1 &&
+      normalizedTo >= blockFrom &&
+      normalizedTo <= blockTo
+    ) {
+      toBlockIndex = i;
+      toBlockKind = block.type;
+    }
+    cursor = blockTo;
+    if (i < root.children.length - 1) cursor += 1;
+    storyLength = cursor;
+  }
 
-    inserted = true;
-    const startOffset = normalizedFrom - paragraphFrom;
-    const endOffset = normalizedTo - paragraphFrom;
+  if (normalizedFrom < 0 || normalizedTo > storyLength) {
+    return {
+      status: "range-out-of-bounds",
+      scopeId,
+      from: normalizedFrom,
+      to: normalizedTo,
+      storyLength,
+    };
+  }
+  if (fromBlockIndex === -1 || toBlockIndex === -1) {
+    return {
+      status: "range-out-of-bounds",
+      scopeId,
+      from: normalizedFrom,
+      to: normalizedTo,
+      storyLength,
+    };
+  }
+  if (fromBlockKind !== "paragraph" || toBlockKind !== "paragraph") {
+    // Either endpoint lands on a non-paragraph top-level block
+    // (table / section_break / sdt). Report the first non-paragraph
+    // offender for diagnostic clarity.
+    const nonParaIndex =
+      fromBlockKind !== "paragraph" ? fromBlockIndex : toBlockIndex;
+    const nonParaKind =
+      fromBlockKind !== "paragraph" ? fromBlockKind : toBlockKind;
+    return {
+      status: "non-paragraph-target",
+      scopeId,
+      from: normalizedFrom,
+      to: normalizedTo,
+      blockIndex: nonParaIndex,
+      blockKind: nonParaKind ?? "unknown",
+    };
+  }
+
+  const startSlot = paraSlots.find((s) => s.index === fromBlockIndex)!;
+  const endSlot = paraSlots.find((s) => s.index === toBlockIndex)!;
+
+  // Same-paragraph fast path: inject both markers into one paragraph.
+  // Preserves all existing single-paragraph behaviour byte-for-byte
+  // (regression pin [C9]).
+  if (startSlot.index === endSlot.index) {
     const newChildren = injectMarkersIntoInlineList(
-      block.children as InlineNode[],
+      (root.children[startSlot.index] as ParagraphNode).children as InlineNode[],
       scopeId,
-      startOffset,
-      endOffset,
+      normalizedFrom - startSlot.from,
+      normalizedTo - startSlot.from,
+      "both",
     );
-    return { ...block, children: newChildren } as ParagraphNode;
-  });
+    const children = root.children.map((block, i) =>
+      i === startSlot.index
+        ? ({ ...block, children: newChildren } as ParagraphNode)
+        : block,
+    );
+    return {
+      status: "planted",
+      document: { ...document, content: { ...root, children } },
+      scopeId,
+      plantedRange: { from: normalizedFrom, to: normalizedTo },
+    };
+  }
 
-  if (!inserted) return { document, scopeId };
+  // Cross-paragraph path — start marker goes in the start-bearing
+  // paragraph; end marker goes in the end-bearing paragraph;
+  // intermediate blocks pass through unchanged.
+  const children = root.children.map((block, i) => {
+    if (i === startSlot.index) {
+      const newChildren = injectMarkersIntoInlineList(
+        (block as ParagraphNode).children as InlineNode[],
+        scopeId,
+        normalizedFrom - startSlot.from,
+        Number.POSITIVE_INFINITY,
+        "start-only",
+      );
+      return { ...block, children: newChildren } as ParagraphNode;
+    }
+    if (i === endSlot.index) {
+      const newChildren = injectMarkersIntoInlineList(
+        (block as ParagraphNode).children as InlineNode[],
+        scopeId,
+        Number.NEGATIVE_INFINITY,
+        normalizedTo - endSlot.from,
+        "end-only",
+      );
+      return { ...block, children: newChildren } as ParagraphNode;
+    }
+    return block;
+  });
 
   return {
-    document: {
-      ...document,
-      content: { ...root, children },
-    },
+    status: "planted",
+    document: { ...document, content: { ...root, children } },
     scopeId,
+    plantedRange: { from: normalizedFrom, to: normalizedTo },
   };
 }
 
@@ -146,28 +307,28 @@ function injectMarkersIntoInlineList(
   scopeId: string,
   startOffset: number,
   endOffset: number,
+  mode: "both" | "start-only" | "end-only",
 ): InlineNode[] {
-  const start: ScopeMarkerStartNode = {
-    type: "scope_marker_start",
-    scopeId,
-  };
-  const end: ScopeMarkerEndNode = {
-    type: "scope_marker_end",
-    scopeId,
-  };
+  const start: ScopeMarkerStartNode = { type: "scope_marker_start", scopeId };
+  const end: ScopeMarkerEndNode = { type: "scope_marker_end", scopeId };
+
+  const needStart = mode === "both" || mode === "start-only";
+  const needEnd = mode === "both" || mode === "end-only";
 
   const output: InlineNode[] = [];
   let cursor = 0;
-  let startEmitted = false;
-  let endEmitted = false;
+  let startEmitted = !needStart;
+  let endEmitted = !needEnd;
 
   for (const node of inlines) {
     const length = inlineLength(node);
     const nodeStart = cursor;
     const nodeEnd = cursor + length;
 
-    const startInside = !startEmitted && startOffset >= nodeStart && startOffset <= nodeEnd;
-    const endInside = !endEmitted && endOffset >= nodeStart && endOffset <= nodeEnd;
+    const startInside =
+      needStart && !startEmitted && startOffset >= nodeStart && startOffset <= nodeEnd;
+    const endInside =
+      needEnd && !endEmitted && endOffset >= nodeStart && endOffset <= nodeEnd;
 
     if (!startInside && !endInside) {
       output.push(node);
@@ -175,10 +336,7 @@ function injectMarkersIntoInlineList(
       continue;
     }
 
-    // Currently only text nodes support splitting for an internal cut.
     if (node.type !== "text") {
-      // For non-text nodes, markers land at the node boundary closest to the
-      // target offset — avoids mid-atom splits which would corrupt the node.
       if (startInside && !startEmitted && startOffset <= nodeStart) {
         output.push(start);
         startEmitted = true;
@@ -203,11 +361,7 @@ function injectMarkersIntoInlineList(
     const text = node.text;
     const chars = Array.from(text);
     const marks = node.marks;
-    const pieces: {
-      cut: number;
-      emit: "start" | "end";
-    }[] = [];
-
+    const pieces: { cut: number; emit: "start" | "end" }[] = [];
     if (startInside) pieces.push({ cut: startOffset - nodeStart, emit: "start" });
     if (endInside) pieces.push({ cut: endOffset - nodeStart, emit: "end" });
     pieces.sort((a, b) => a.cut - b.cut || (a.emit === "start" ? -1 : 1));
@@ -243,12 +397,11 @@ function injectMarkersIntoInlineList(
     cursor = nodeEnd;
   }
 
-  // Append markers that were at the very end of the paragraph.
-  if (!startEmitted) {
+  if (needStart && !startEmitted) {
     output.push(start);
     startEmitted = true;
   }
-  if (!endEmitted) {
+  if (needEnd && !endEmitted) {
     output.push(end);
     endEmitted = true;
   }

package/src/runtime/document-runtime.ts

@@ -57,6 +57,7 @@ import type {
   RestoreResult,
   ReviewWorkSnapshot,
   RuntimeContextAnalyticsQuery,
+  EditorSurfaceSnapshot,
   RuntimeContextAnalyticsSnapshot,
   RuntimeRenderSnapshot,
   ScopeTagTouch,
@@ -1561,17 +1562,91 @@ export function createDocumentRuntime(
     });
     recordPerfSample("snapshot.surface");
     incrementInvalidationCounter("runtime.snapshot.surfaceMisses");
+    // Viewport-cull flicker fix — enrich `placeholder-culled` opaque
+    // blocks with the block's known rendered height (twips) so the PM
+    // placeholder emits a fixed-height `<div>` sized to match what the
+    // realized block will occupy once it re-enters the viewport. Without
+    // this, culled stubs render at `min-height: 20px` regardless of their
+    // real visual size; scrolling into a culled region inflates every
+    // block to its real height in succession and drags content below
+    // the scroll pointer (the "paragraphs jump around pagination gaps"
+    // flicker).
+    //
+    // The heights come from L04's page graph, which is already computed
+    // on a FULLY-REALIZED surface inside `layout-engine-instance.ts` —
+    // i.e. pagination is independent of the viewport cull, so every
+    // blockId has an authoritative height regardless of whether its
+    // surface block is real or a placeholder. `getBlockHeightsTwips()`
+    // sums per-block fragments and caches per `graph.revision`.
+    //
+    // No-op on pre-pagination calls (engine not yet ready → empty map)
+    // and on the inert facet.
+    const enrichedSnapshot = enrichCulledPlaceholdersWithHeights(snapshot);
     cachedSurface = {
       revisionToken: state.revisionToken,
       activeStoryKey,
       viewportRangesKey,
-      snapshot,
+      snapshot: enrichedSnapshot,
     };
     // 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;
+    return enrichedSnapshot;
+  }
+
+  function enrichCulledPlaceholdersWithHeights(
+    snapshot: EditorSurfaceSnapshot,
+  ): EditorSurfaceSnapshot {
+    let heights: ReadonlyMap<string, number>;
+    try {
+      heights = layoutFacet.getBlockHeightsTwips();
+    } catch {
+      return snapshot;
+    }
+    if (heights.size === 0) return snapshot;
+    let changed = false;
+    const enrichedBlocks = snapshot.blocks.map((block) => {
+      if (
+        block.kind !== "opaque_block" ||
+        block.state !== "placeholder-culled"
+      ) {
+        return block;
+      }
+      // The culled placeholder's blockId is `placeholder-culled-<index>`;
+      // the underlying ParagraphNode kept its own id which is NOT carried
+      // on the placeholder. Instead, identify the real block by its
+      // `from` offset — surface-projection guarantees `from` on the
+      // placeholder mirrors the real block's `from`, and fragment records
+      // on the page graph record runtime offsets.
+      const realBlockIdFromOffset = resolveBlockIdFromRuntimeOffset(
+        layoutFacet,
+        block.from,
+      );
+      if (!realBlockIdFromOffset) return block;
+      const heightTwips = heights.get(realBlockIdFromOffset);
+      if (typeof heightTwips !== "number" || heightTwips <= 0) return block;
+      changed = true;
+      return { ...block, placeholderHeightTwips: heightTwips };
+    });
+    if (!changed) return snapshot;
+    return { ...snapshot, blocks: enrichedBlocks };
+  }
+
+  function resolveBlockIdFromRuntimeOffset(
+    facet: WordReviewEditorLayoutFacet,
+    runtimeOffset: number,
+  ): string | null {
+    // `getFragmentForOffset` exists on the facet; use it to recover the
+    // real blockId for a given offset without having to walk all
+    // fragments. Returns the fragment whose `[from, to)` contains the
+    // offset, or null.
+    try {
+      const frag = facet.getFragmentForOffset?.(runtimeOffset);
+      return frag?.blockId ?? null;
+    } catch {
+      return null;
+    }
   }
 
   function getCachedFieldSnapshot(document: CanonicalDocumentEnvelope): FieldSnapshot {

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

@@ -110,6 +110,22 @@ export interface EffectiveFieldDisplay {
  * visual vocabulary (CSS class, inline style, decoration).
  */
 export interface RevisionDisplayFlags {
+  /**
+   * The attached revision's id. Enables render consumers to emit
+   * `data-revision-id` + route sidebar scroll-to-revision off the
+   * authoritative L03 flags rather than re-deriving from the review-store
+   * side channel. Present whenever `input.revision !== undefined` drove
+   * flag emission.
+   */
+  readonly revisionId: string;
+  /**
+   * The revision's kind. Mirrors `RevisionRecord.kind` from the canonical
+   * document (`src/model/canonical-document.ts`). Render consumers use
+   * this to branch on insertion/deletion/move/property-change variants
+   * (e.g. widget-bracket placement in suggestions mode) without reading
+   * the review store.
+   */
+  readonly kind: "insertion" | "deletion" | "formatting" | "move" | "property-change";
   readonly markupMode: "clean" | "simple" | "all";
   /** Hide the run entirely (e.g. open deletion in "clean" mode). */
   readonly hidden?: boolean;