@beyondwork/docx-react-component 1.0.56 → 1.0.58

package/README.md

@@ -238,7 +238,7 @@ Engineering work is organized into 9 lanes (5 active now + 2 later polish + 2 fi
 | 6b | [**Shell & Workspace Chrome**](docs/plans/lane-6b-shell-workspace-chrome.md) | **~15%** | Gated on 6a.S1+S2 — shell header + toolbar + status + alert banner + unsaved modal + collab chrome restyle; mode-dock decommission; TwCommandPalette |
 | 6c | [**Context & Review Surfaces**](docs/plans/lane-6c-context-review-surfaces.md) | **~15%** | Gated on 6a.S1+S2 — selection toolbar + suggestion card + rail + scope + context toolbars + health panel restyle; TwCommentPreview / TwEmptyState / TwShortcutHint |
 | 6d | [**Visual Fidelity**](docs/plans/lane-6d-visual-fidelity.md) | **~20%** | Gated on 6a.S1+S2 + external-lane deps — L8 A/B/C shipped; L8 Phase D + P11 overlays + P7 + P12 + P14 next |
-| 7a | [**Visual Fidelity Register**](docs/plans/lane-7a-visual-fidelity-register.md) | **0%** | LATER (gated on 6a–6d) — V5 covers, V6 REF/PAGEREF, V7 cascade audit |
+| 7a | [**Visual Fidelity Register**](docs/plans/lane-7a-visual-fidelity-register.md) | **✅ 100%** | CLOSED — V5 covers (`6f8869b7`), V6 REF/PAGEREF baseline via CO3 + contract pin (`99b66a1f`), V7 × CO1 5-combo cascade audit (`df315488`) |
 | 7b | [**Revision & Redline Completion**](docs/plans/lane-7b-revision-redline-completion.md) | **0%** | LATER (gated on 6a–6d) — X4.a/b structural table revisions, X5 ffData, move-pairing |
 | 7c | [**Preservation & Format Coverage**](docs/plans/lane-7c-preservation-format-coverage.md) | **0%** | LATER (gated on 6a–6d) — O6 Strict, OLE preserve-only, picture-SDT, w14/kern/VML defer |
 | 7d | [**Platform Hardening & Hygiene**](docs/plans/lane-7d-platform-hardening-hygiene.md) | **0%** | LATER (gated on 6a–6d) — harness-crash-hardening, fastload activation, worktree consolidation |

package/package.json

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

package/src/api/public-types.ts

@@ -482,6 +482,12 @@ export interface SearchOptions {
   matchCase?: boolean;
   wholeWord?: boolean;
   limit?: number;
+  /** Phase C §C3 — treat `query` as a JS regex pattern (compiled with `u` flag). */
+  regex?: boolean;
+  /** Phase C §C3 — restrict results to positions inside this scopeId's marker range. */
+  inScope?: string;
+  /** Phase C §C3 — restrict results to a specific story target (default: main). */
+  inStory?: EditorStoryTarget;
 }
 
 export interface SearchResultSnapshot {
@@ -717,11 +723,17 @@ export type SnapshotRefreshChangeKind =
   | "structure"
   | "checkpoint";
 
+export interface TocRefreshTrigger {
+  headingContentChanged: boolean;
+  headingStructureChanged: boolean;
+}
+
 export interface SnapshotRefreshHints {
   invalidate: SnapshotRefreshInvalidateTarget[];
   staleTargets: SnapshotRefreshStaleTarget[];
   changeKinds: SnapshotRefreshChangeKind[];
   checkpointType?: "session" | "snapshot" | "export";
+  tocRefreshTrigger?: TocRefreshTrigger;
 }
 
 export interface StyleCatalogEntrySnapshot {
@@ -798,6 +810,51 @@ export type SurfaceTextMark =
   | "smallCaps"
   | "allCaps";
 
+/**
+ * V2c.4 / V2c.5 — DrawingFrame anchor geometry projected onto image + shape
+ * segments. Mirrors the canonical `AnchorGeometry` shape (defined in
+ * `src/model/canonical-document.ts`) with the fields chrome consumers need
+ * for float-wrap (Lane 6d N9), object-selection chrome (N6), and frame
+ * positioning. EMU values are kept verbatim — converters that need px
+ * apply 9525 EMU = 1 px at 96 dpi.
+ */
+export interface SurfaceDrawingAnchor {
+  display: "inline" | "floating";
+  wrapMode: "none" | "square" | "tight" | "through" | "topAndBottom";
+  extent: { widthEmu: number; heightEmu: number };
+  positionH?: { relativeFrom: string; align?: string; offset?: number };
+  positionV?: { relativeFrom: string; align?: string; offset?: number };
+  distMargins?: { top?: number; bottom?: number; left?: number; right?: number };
+  relativeHeight?: number;
+  behindDoc?: boolean;
+  layoutInCell?: boolean;
+  allowOverlap?: boolean;
+  simplePos?: boolean;
+  /** docPr.id / .name / .descr — used for accessibility chrome and selection labels. */
+  docPr?: { id: string; name?: string; descr?: string };
+}
+
+/**
+ * V2c.4 — Picture-effect data (crop, rotation, flip, preset clip geometry).
+ * `srcRect` percentages match OOXML's `a:srcRect` semantics: 0 = no crop,
+ * 100 000 = fully cropped from that edge.  `rotation` is in 60 000ths of a
+ * degree (OOXML `a:xfrm a:rot`).
+ */
+export interface SurfacePictureEffects {
+  srcRect?: { top: number; bottom: number; left: number; right: number };
+  rotation?: number;
+  flipH?: boolean;
+  flipV?: boolean;
+  presetGeom?: string;
+  stretch?: boolean;
+  /** N11.b — a:softEdge feather radius in EMU. Maps to CSS `filter: blur(R)`. */
+  softEdgeRadius?: number;
+  /** N11.b — a:outerShdw drop shadow. `blurRad`/`dist` in EMU; `dir` in 60000ths of a degree. */
+  outerShadow?: { blurRad: number; dist: number; dir: number; color: string; colorType: "srgbClr" | "schemeClr" };
+  /** N11.b — a:glow ambient glow. `radius` in EMU. */
+  glow?: { radius: number; color: string; colorType: "srgbClr" | "schemeClr" };
+}
+
 export type SurfaceInlineSegment =
   | {
       segmentId: string;
@@ -836,6 +893,19 @@ export type SurfaceInlineSegment =
       state: "editable" | "missing";
       display?: "inline" | "floating";
       detail?: string;
+      /**
+       * V2c.4 — DrawingFrame anchor geometry surfaced for Lane 6d float-wrap
+       * (P7) and chrome consumers. Present only when the canonical model
+       * carries non-trivial anchor metadata; inline pictures with default
+       * positioning omit it so the simple-image path stays cheap.
+       */
+      anchor?: SurfaceDrawingAnchor;
+      /**
+       * V2c.4 — Picture-effect data (crop, rotation, flip, preset geometry).
+       * Absent when none of the underlying `PictureContent` effect fields
+       * are set, so consumers can fast-path image rendering when undefined.
+       */
+      pictureEffects?: SurfacePictureEffects;
     }
   | {
       segmentId: string;
@@ -886,6 +956,44 @@ export type SurfaceInlineSegment =
       instruction: string;
       refreshStatus: FieldRefreshStatus;
       label: string;
+    }
+  | {
+      /**
+       * V2c.5 — DrawingFrame shape segment.  Replaces the `complex_preview`
+       * fallback that used to swallow `wps:wsp` shapes.  Carries the
+       * geometry preset, fill/line, optional textbox flag + first-paragraph
+       * preview, and (for floating shapes) anchor geometry.  Lane 6d's N10
+       * shape rendering consumes this segment.
+       */
+      segmentId: string;
+      kind: "shape";
+      from: number;
+      to: number;
+      label: string;
+      detail: string;
+      anchor?: SurfaceDrawingAnchor;
+      geometry?: string;
+      fill?:
+        | { kind: "solid"; color: string; colorType: "srgbClr" | "schemeClr" }
+        | { kind: "none" }
+        | {
+            kind: "gradient";
+            stops: Array<{ pos: number; color: string; colorType: "srgbClr" | "schemeClr" }>;
+            direction:
+              | { kind: "linear"; angle: number; scaled?: boolean }
+              | { kind: "path"; path: "circle" | "rect" | "shape" };
+            rotWithShape?: boolean;
+          }
+        | {
+            kind: "pattern";
+            preset: string;
+            fg?: { color: string; colorType: "srgbClr" | "schemeClr" };
+            bg?: { color: string; colorType: "srgbClr" | "schemeClr" };
+          };
+      line?: { color?: string; widthEmu?: number; noLine?: boolean };
+      isTextBox?: boolean;
+      /** First-paragraph plain-text preview when `isTextBox` is true. */
+      txbxText?: string;
     };
 
 export interface SurfaceTableCellSnapshot {
@@ -1716,6 +1824,8 @@ export interface RuntimeRenderSnapshot {
   commandState: CommandStateSnapshot;
   surface?: EditorSurfaceSnapshot;
   protectionSnapshot: ProtectionSnapshot;
+  /** R.3 — stable id of the currently grabbed image/shape, or null. Populated from grab state so chrome overlays re-render on selectObject/deselectObject. */
+  grabbedObjectId?: string | null;
 }
 
 export interface EditorSessionState {
@@ -1946,6 +2056,67 @@ export interface WorkflowMetadataSnapshot {
   entries: WorkflowMetadataEntry[];
 }
 
+// ---------------------------------------------------------------------------
+// Phase C — host-side scope query surface (§C1, §C2)
+// ---------------------------------------------------------------------------
+
+/**
+ * §C1 — Filter passed to `queryScopes` / `findScopesAt` /
+ * `findScopesIntersecting`. All fields are optional and AND'd together.
+ * Snapshot-based; never triggers runtime mutation.
+ */
+export interface ScopeQueryFilter {
+  /** Match only scopes attached to any of these work items. */
+  workItemIds?: string[];
+  /** Match only scopes in one of these modes. */
+  modes?: WorkflowScopeMode[];
+  /** Match only scopes whose `domain` is one of these. */
+  domains?: Array<NonNullable<WorkflowScope["domain"]>>;
+  /**
+   * Match scopes that carry at least one entry with this `metadataId`.
+   * Uses the runtime `WorkflowMetadataSnapshot` joined by `entry.scopeId`.
+   */
+  metadataId?: string;
+  /**
+   * Match scopes that carry at least one entry whose `value` passes the
+   * predicate. Entries with no `value` are skipped.
+   */
+  hasValue?: (value: Record<string, unknown>, entry: WorkflowMetadataEntry) => boolean;
+  /** Label prefix (case-insensitive). */
+  labelPrefix?: string;
+  /**
+   * Story target filter. Defaults to `{ kind: "main" }` when omitted. Pass
+   * `"*"` for any story.
+   */
+  storyTarget?: EditorStoryTarget | "*";
+  /** Max result count. Undefined = no cap. */
+  limit?: number;
+  /**
+   * §C8 — include scopes with `visibility: "hidden"`. Default: false.
+   * Accepted but has no effect until §C8 adds the `visibility` field.
+   */
+  includeHidden?: boolean;
+  /**
+   * §C8 — include scopes with `visibility: "invisible"`. Default: false.
+   * Accepted but has no effect until §C8 adds the `visibility` field.
+   */
+  includeInvisible?: boolean;
+}
+
+/**
+ * §C1 — One result from `queryScopes`. Joins the scope record with the
+ * metadata entries that point at it and the resolved work item (when
+ * `scope.workItemId` matches one in the overlay).
+ */
+export interface ScopeQueryResult {
+  /** Scope record from the overlay. */
+  scope: WorkflowScope;
+  /** Metadata entries whose `entry.scopeId === scope.scopeId`. */
+  entries: WorkflowMetadataEntry[];
+  /** Resolved work item when `scope.workItemId` is set and present. */
+  workItem: WorkflowWorkItem | null;
+}
+
 // ---------------------------------------------------------------------------
 // R2 — issue metadata (scope-card-overlay P1)
 // ---------------------------------------------------------------------------
@@ -2563,6 +2734,12 @@ export type WordReviewEditorEvent =
       documentId: string;
       activeStory: EditorStoryTarget;
     }
+  | {
+      type: "toc_auto_refreshed";
+      documentId: string;
+      entryCount: number;
+      trigger: TocRefreshTrigger;
+    }
   | {
       type: "warning_added";
       documentId: string;
@@ -3060,6 +3237,61 @@ export interface WordReviewEditorRef {
    * add merge-intent + richer caret placement as paste parsers come online.
    */
   insertFragment(fragment: CanonicalDocumentFragment, target?: EditorAnchorProjection): void;
+  /**
+   * I2 Tier B Slice 4b — serialize `target` (or the current selection) to a
+   * `CanonicalDocumentFragment` and store it in the editor's internal
+   * clipboard buffer. No document mutation.
+   */
+  copy(target?: EditorAnchorProjection): void;
+  /**
+   * I2 Tier B Slice 4b — `copy(target)` + delete the range.
+   */
+  cut(target?: EditorAnchorProjection): void;
+  /**
+   * I2 Tier B Slice 4b — return the last fragment written by `cut` / `copy`,
+   * or `null` if none has been captured yet. Hosts pair this with
+   * `insertFragment` to implement paste while Slice 4b's async-Clipboard-API
+   * write lands with Slice 5.
+   */
+  getClipboardBuffer(): CanonicalDocumentFragment | null;
+  /**
+   * v5 close-out — return the current clipboard buffer serialized to the
+   * wire formats browsers/Word accept, or `null` when no clipboard op has
+   * been performed. Hosts use this inside their own DOM `copy`/`cut` event
+   * handler to feed `navigator.clipboard.write` (the editor does not
+   * install the DOM handler itself).
+   */
+  getClipboardWireFormats(): { wordml: string; html: string; plainText: string } | null;
+  /**
+   * R.3 ObjectGrabLayer — grab an inline / floating object (image, shape)
+   * by its stable id. Single-select; replaces any previously grabbed
+   * object. Lane 6 P11 chrome reads the grab state to paint handles.
+   */
+  selectObject(objectId: string): void;
+  /**
+   * R.3 — release the grabbed object, if any. Safe to call when nothing
+   * is grabbed.
+   */
+  deselectObject(): void;
+  /**
+   * R.3 — return the grabbed object's id, or `null` when nothing is
+   * grabbed.
+   */
+  getGrabbedObject(): string | null;
+  /**
+   * R.5.a — open an action bracket. Hosts wrap compound edits (paste,
+   * cut+paste, agent suggestion-apply) so snapshot emission + collab
+   * broadcast + undo grouping see them as a single action.
+   *
+   * Phase 1: opt-in. Existing commands do not auto-bracket. Hosts that
+   * want single-undo paste call `startAction("paste")` →
+   * `insertFragment(fragment)` → `endAction()`.
+   */
+  startAction(name: string): void;
+  /** R.5.a — close one level of action bracketing. Unbalanced calls are no-ops. */
+  endAction(): void;
+  /** R.5.a — `true` when the runtime is inside one or more action brackets. */
+  isInAction(): boolean;
   toggleBulletedList(): void;
   toggleNumberedList(): void;
   toggleBold(): void;
@@ -3169,6 +3401,86 @@ export interface WordReviewEditorRef {
   setWorkflowMetadataEntries(entries: WorkflowMetadataEntry[]): void;
   clearWorkflowMetadataEntries(): void;
   getWorkflowMetadataSnapshot(): WorkflowMetadataSnapshot;
+  /**
+   * Phase C §C1 — filter + project the current workflow overlay into a
+   * scope-joined view. Reads a snapshot of the current overlay + metadata
+   * entries + work items; no mutation. Results are sorted by start-marker
+   * document position, tie-broken by `scopeId` ascending.
+   *
+   * Defaults: `storyTarget` = `{ kind: "main" }` (pass `"*"` for any
+   * story); `includeHidden` / `includeInvisible` default to `false`
+   * (§C8 additive — accepted today but no-ops until `visibility` lands).
+   *
+   * Returns `[]` when no workflow overlay has been set.
+   */
+  queryScopes(filter?: ScopeQueryFilter): ScopeQueryResult[];
+  /**
+   * Phase C §C2 — every scope whose marker range contains `position.from`
+   * (end-inclusive), ordered outermost → innermost. Pass a zero-length
+   * range (`from === to`) for a point query. Returns the full
+   * `ScopeQueryResult` (scope + entries + workItem) so results compose
+   * directly with `setSelection`, `addScope`, `getLocationForAnchor`.
+   *
+   * Companion to `getInteractionGuardSnapshot().matchedScopeId` — that
+   * API returns the innermost-only match; this one returns the whole
+   * enclosing stack.
+   */
+  findScopesAt(
+    position: EditorAnchorProjection,
+    options?: { includeHidden?: boolean; includeInvisible?: boolean },
+  ): ScopeQueryResult[];
+  /**
+   * Phase C §C2 — every scope whose marker range intersects `range`
+   * (accepts a range anchor; non-range anchors yield `[]`). Default
+   * `mode: "overlap"` matches any intersection including touching
+   * endpoints; `mode: "contain"` requires the scope's entire range to
+   * sit within `range`. Deterministic order by start-marker position.
+   */
+  findScopesIntersecting(
+    range: EditorAnchorProjection,
+    options?: {
+      includeHidden?: boolean;
+      includeInvisible?: boolean;
+      mode?: "overlap" | "contain";
+    },
+  ): ScopeQueryResult[];
+  /**
+   * Phase C §C3 — find the first text match in the document.
+   * Supports `regex`, `inScope`, `inStory` options.
+   * Throws `EditorApiError({ code: "search_invalid_regex" })` synchronously
+   * when `options.regex === true` and `query` is not a valid regex pattern.
+   * Returns `null` when no match is found.
+   */
+  findFirstText(
+    query: string,
+    options?: SearchOptions,
+  ): EditorAnchorProjection | null;
+  /**
+   * Phase C §C3 — find all text matches in the document.
+   * Same options and error contract as `findFirstText`.
+   * Returns `[]` when no matches are found.
+   */
+  findAllText(
+    query: string,
+    options?: SearchOptions,
+  ): EditorAnchorProjection[];
+  /**
+   * Phase C §C3 — find first text match and select it. Returns `true` if a
+   * match was found (and selection updated), `false` otherwise.
+   */
+  selectFirstText(
+    query: string,
+    options?: SearchOptions,
+  ): boolean;
+  /**
+   * Phase C §C3 — select first text match and return the total match count.
+   * Returns `0` when no matches are found. Multi-range selection deferred
+   * to Lane 1 shipping `SelectionSnapshot.multi`.
+   */
+  selectAllText(
+    query: string,
+    options?: SearchOptions,
+  ): number;
   /**
    * Schema 1.1 — set the overlay default for metadata persistence.
    * Author-only per collab-master-plan §7 role-gating matrix;
@@ -3706,6 +4018,24 @@ export interface ResolveMetadataConflictInput {
 }
 
 // ---------------------------------------------------------------------------
+// Phase C §C3 — generic editor API error
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown synchronously by query methods when the caller passes an invalid
+ * argument. The `code` field identifies the specific failure:
+ * - `"search_invalid_regex"` — `options.regex === true` and `query` is not
+ *   a valid JavaScript regular expression pattern.
+ */
+export class EditorApiError extends Error {
+  readonly code: string;
+  constructor(params: { code: string; message?: string }) {
+    super(params.message ?? `EditorApiError: ${params.code}`);
+    this.name = "EditorApiError";
+    this.code = params.code;
+  }
+}
+
 // Schema 1.1 — metadata-persistence errors (P17)
 // ---------------------------------------------------------------------------
 

package/src/compare/diff-engine.ts

@@ -522,6 +522,7 @@ function getInlineLength(node: InlineNode): number {
     case "shape":
     case "wordart":
     case "vml_shape":
+    case "drawing_frame":
       return 1;
   }
 }
@@ -581,6 +582,8 @@ function getInlineDisplayText(node: InlineNode): string {
       return node.text;
     case "vml_shape":
       return node.text ?? "[VML Shape]";
+    case "drawing_frame":
+      return node.content.type === "picture" ? "[Image]" : "[Drawing]";
   }
 }
 

package/src/core/commands/formatting-commands.ts

@@ -1040,6 +1040,7 @@ function inlineNodeLength(node: InlineNode): number {
     case "shape":
     case "wordart":
     case "vml_shape":
+    case "drawing_frame":
       return 1;
     case "field":
       return node.children.reduce<number>(

package/src/core/commands/index.ts

@@ -89,7 +89,8 @@ import {
   setHeaderFooterLinkAtSectionIndex,
 } from "./section-layout-commands.ts";
 import { insertPageBreak, insertTable } from "./text-commands.ts";
-import { applyFragmentInsert } from "../../runtime/structure-ops/fragment-insert.ts";
+import { editLayer } from "../../runtime/edit-ops/index.ts";
+import { structureLayer } from "../../runtime/structure-ops/index.ts";
 import type { TableSelectionDescriptor } from "../../runtime/table-commands.ts";
 
 export type ContentChildrenPatch =
@@ -575,8 +576,10 @@ export function executeEditorCommand(
         ? applySuggestingInsert(state, command.text, context)
         : undefined;
       if (suggestingResult) return suggestingResult;
+      // R.2 — dispatch via the named EditLayer entry point so the seam is the
+      // single site where R.5.a/b hooks will attach.
       return applyTextCommand(state, context.timestamp, (document, selection) =>
-        insertText(document, selection, command.text, context, command.formatting),
+        editLayer.applyTextInsert(document, selection, command.text, context, command.formatting),
       );
     }
     case "text.delete-backward": {
@@ -585,7 +588,7 @@ export function executeEditorCommand(
         : undefined;
       if (suggestingResult) return suggestingResult;
       return applyTextCommand(state, context.timestamp, (document, selection) =>
-        deleteSelectionOrBackward(document, selection, context),
+        editLayer.applyDeleteBackward(document, selection, context),
       );
     }
     case "text.delete-forward": {
@@ -594,7 +597,7 @@ export function executeEditorCommand(
         : undefined;
       if (suggestingResult) return suggestingResult;
       return applyTextCommand(state, context.timestamp, (document, selection) =>
-        deleteSelectionOrForward(document, selection, context),
+        editLayer.applyDeleteForward(document, selection, context),
       );
     }
     case "text.insert-tab": {
@@ -603,7 +606,7 @@ export function executeEditorCommand(
         : undefined;
       if (suggestingResult) return suggestingResult;
       return applyTextCommand(state, context.timestamp, (document, selection) =>
-        insertTab(document, selection, context),
+        editLayer.applyInsertTab(document, selection, context),
       );
     }
     case "text.outdent-tab": {
@@ -632,7 +635,7 @@ export function executeEditorCommand(
         : undefined;
       if (suggestingResult) return suggestingResult;
       return applyTextCommand(state, context.timestamp, (document, selection) =>
-        insertHardBreak(document, selection, context),
+        editLayer.applyInsertHardBreak(document, selection, context),
       );
     }
     case "paragraph.split":
@@ -641,15 +644,18 @@ export function executeEditorCommand(
         if (suggestingResult) return suggestingResult;
       }
       return applyTextCommand(state, context.timestamp, (document, selection) =>
-        splitParagraph(document, selection, context),
+        editLayer.applySplitParagraph(document, selection, context),
       );
     case "fragment.insert": {
-      // I2 Tier B Slice 1 — route through the structure-ops splicer. No
+      // I2 Tier B Slice 1 + R.3 — route through the StructureLayer seam. No
       // suggesting-mode branch yet; fragment insertion always lands as a direct
       // edit. Future slices will gate behind track-changes when a fixture needs it.
-      const result = applyFragmentInsert(state.document, state.selection, command.fragment, {
-        timestamp: context.timestamp,
-      });
+      const result = structureLayer.applyFragmentInsert(
+        state.document,
+        state.selection,
+        command.fragment,
+        { timestamp: context.timestamp },
+      );
       return buildDocumentReplaceTransaction(state, context, result);
     }
     case "runtime.set-read-only":

package/src/core/selection/mapping.ts

@@ -31,7 +31,24 @@ export interface DetachedAnchor {
   reason: "deleted" | "invalidatedByStructureChange" | "importAmbiguity";
 }
 
-export type EditorAnchorProjection = RangeAnchor | NodeAnchor | DetachedAnchor;
+/**
+ * Internal representation of an anchor projection — uses `DocRange` so
+ * mapping helpers compose ranges independently of assoc semantics. The
+ * public-facing shape lives at `src/api/public-types.ts` (same simple name
+ * `EditorAnchorProjection`) and is flat (`{ kind: "range", from, to, assoc }`).
+ * Conversion between the two goes through `src/core/selection/anchor-conversion.ts`.
+ */
+export type InternalEditorAnchorProjection = RangeAnchor | NodeAnchor | DetachedAnchor;
+
+/**
+ * @deprecated X3 Phase 5 — prefer `InternalEditorAnchorProjection` to avoid
+ * name-collision with the public `EditorAnchorProjection` from
+ * `src/api/public-types.ts`. Internal call-sites have migrated (via
+ * `import type { EditorAnchorProjection as InternalEditorAnchorProjection }`
+ * aliasing in `document-runtime.ts`). This alias stays for one release cycle
+ * so third-party internal consumers don't break. Remove in v2.1+.
+ */
+export type EditorAnchorProjection = InternalEditorAnchorProjection;
 
 export interface MappingStep {
   from: Position;

package/src/core/selection/review-anchors.ts

@@ -104,17 +104,22 @@ export function rangeStaysWithinSingleParagraph(
 }
 
 /**
- * I8 — "mid-run-near-table" guard. Comment anchors whose endpoints
- * land strictly inside a paragraph that sits adjacent to a table
- * block are rejected: the serializer's per-paragraph offset walker
- * (Lane 3 §O8) produces invalid OOXML for these anchors. Removed
- * once O8 ships.
+ * Width of the paragraph-to-table proximity window used by
+ * `snapCommentAnchorAwayFromTable` to decide when to nudge endpoints to
+ * paragraph boundaries. Originally the I8 rejection threshold before Lane 3b
+ * §O8 shipped; now used only by the (opt-in) snap helper for hosts that
+ * prefer clean anchors.
  */
 export const TABLE_ADJACENT_WINDOW = 1;
 
-export type CommentAnchorRejectionReason =
-  | "invalid_comment_anchor"
-  | "comment_anchor_table_adjacent";
+/**
+ * I8 guard removal (post-O8) — the `comment_anchor_table_adjacent` rejection
+ * reason has been retired now that Lane 3b §O8 fixed the serializer's
+ * per-paragraph offset walker. The type alias remains as a deprecated union
+ * stub so existing host code that narrows on it keeps compiling; new code
+ * should simply check against `"invalid_comment_anchor"`.
+ */
+export type CommentAnchorRejectionReason = "invalid_comment_anchor";
 
 export function canCreateDocxCommentAnchor(
   content: unknown,
@@ -140,17 +145,18 @@ export function commentAnchorRejectionReason(
     return "invalid_comment_anchor";
   }
 
-  if (rangeLandsMidRunNearTableBoundary(content, normalized)) {
-    return "comment_anchor_table_adjacent";
-  }
-
+  // I8 branch removed — mid-run-near-table anchors now serialize cleanly
+  // via Lane 3b §O8's `walkInlineNodeForBoundaries` fix.
   return null;
 }
 
 /**
- * I8.3 — Snap a rejected mid-run-near-table anchor to paragraph
- * boundaries so downstream serialization stays safe. Returns `null`
- * if the anchor cannot be rescued (e.g. crosses an opaque block).
+ * Snap a mid-run-near-table anchor to paragraph boundaries when a host opts
+ * into `snapToSafeBoundary`. Originally a defensive workaround for the pre-O8
+ * serializer bug; now a boundary-preference convenience for hosts that dislike
+ * mid-run comment anchors on principle. Returns `null` if the anchor cannot
+ * be rescued (e.g. crosses an opaque block); returns the input unchanged if
+ * it doesn't need snapping.
  */
 export function snapCommentAnchorAwayFromTable(
   content: unknown,
@@ -161,9 +167,14 @@ export function snapCommentAnchorAwayFromTable(
   const normalized = normalizeRange(anchor.range);
   if (normalized.from === normalized.to) return null;
 
-  const reason = commentAnchorRejectionReason(content, anchor);
-  if (reason === null) return anchor;
-  if (reason !== "comment_anchor_table_adjacent") return null;
+  // If the anchor is already flagged invalid for other reasons (crosses an
+  // opaque block, etc.) we can't rescue it by snapping.
+  if (commentAnchorRejectionReason(content, anchor) !== null) return null;
+
+  // Detect mid-run-near-table via structural check directly (independent of
+  // rejection reason — the rejection branch is gone post-O8). If the anchor
+  // doesn't need snapping, pass it through unchanged.
+  if (!rangeLandsMidRunNearTableBoundary(content, normalized)) return anchor;
 
   const surfaceBlocks = readSurfaceBlocks(content);
   if (!surfaceBlocks) return null;