@beyondwork/docx-react-component 1.0.48 → 1.0.50

package/README.md

@@ -224,17 +224,25 @@ The CCEP corpus is kept on `main` as a maintainer-safe smoke-doc source set for
 
 Engineering work is organized into 9 lanes (5 active now + 2 later polish + 2 final) — full plan index, status, and worktree map at [`docs/plans/README.md`](docs/plans/README.md). Each lane has a single self-contained doc at `docs/plans/lane-N-<name>.md`:
 
-| Lane | Mission | Status |
-|---|---|---|
-| 1. [**Editing Foundation**](docs/plans/lane-1-editing-foundation.md) | Close I1–I6 + ship the SelectionLayer / EditLayer / StructureLayer / SurfaceLayer split | active |
-| 2. [**Render Performance**](docs/plans/lane-2-render-performance.md) | <32 ms typing P50 + <1 s cold-open on 200-page CCEP; never stuck on loading | active |
-| 3. [**Layout Engine + OOXML Fidelity**](docs/plans/lane-3-layout-engine-ooxml-fidelity.md) | Land P9 anchor-index + P10 incremental relayout + drain O2/O3/O4 round-trip + tables/TOC/page numbers/front pages/image structures | active |
-| 4. [**Collab + CLM/Vallor Integration**](docs/plans/lane-4-collab-clm-vallor.md) | Promote collab plumbing → first-class user mode; wire Sunday CLM × React E2E demo | active |
-| 5. [**Charts (independent)**](docs/plans/lane-5-charts.md) | Move charts from preserve-only opaque preview to Word-accurate native rendering (Stages 1–7) | active |
-| 6. [**Visual Chrome / Layout Polish**](docs/plans/lane-6-visual-chrome-layout-polish.md) | True-to-Word visuals: discrete paper cards, native page chrome, float-wrap, validation bar | LATER |
-| 7. [**Bugs / Gaps / Cross-cutting**](docs/plans/lane-7-bugs-gaps-cross-cutting.md) | Drain V#/O#/X# register; trigger-gated work; infrastructure hardening | LATER |
-| 8. [**API Ergonomics / Errors / Backwards Compatibility**](docs/plans/lane-8-api-ergonomics.md) | Refactor `docs/reference/public-api.md` end-to-end with groups + per-code error catalog + ergonomics fixes; maintain backwards compat | LATER (Tracks A+C shipped 2026-04-19) |
-| 9. [**Shipping**](docs/plans/lane-9-shipping.md) | Production-readiness: API freeze, semver discipline, changelog, telemetry, customer migration guides, doc completeness audit | FINAL |
+**Progress snapshot — 2026-04-19 (post PR #189 + #190 + #191 + #192 merged to `main`; Lane 3 split into 3a + 3b on 2026-04-19 deep evening):**
+
+| # | Lane | % to goal | Status summary |
+|---|---|---|---|
+| 1 | [**Editing Foundation**](docs/plans/lane-1-editing-foundation.md) | **65%** | I1–I6 + I3 widening + I4 + S1 + X3 + I8 shipped; I2B / I7 / R.1–R.5 backlog |
+| 2 | [**Render Performance**](docs/plans/lane-2-render-performance.md) | **85%** | All Phases 1.x + 2.2 + 2.4b + 2.5 (A+B) + 2.9 shipped; Tasks 2.1 / 2.3 left |
+| 3a | [**Layout & Render Engine**](docs/plans/lane-3a-layout-render-engine.md) | **45%** | P1–P6 + P8 + P14.a/b/e shipped; P9 (now unblocked) + P10 + P11 + P12 + P14.c/d backlog |
+| 3b | [**OOXML Fidelity & Round-Trip**](docs/plans/lane-3b-ooxml-fidelity.md) | **55%** | V1 + O3 + O4 + O2 (all 4 slices) + V7 closed; 🚨 O8 + L2.c + V6 + V2a/b/c + R3–R5 backlog |
+| 4 | [**Collab + CLM/Vallor**](docs/plans/lane-4-collab-clm-vallor.md) | **80%** | P1–P14 + all P11 sub-bullets + P12 + perf-parity + P13 A/B/C shipped; P15 / P16 / P17 left |
+| 5 | [**Charts (independent)**](docs/plans/lane-5-charts.md) | **30%** | Stages 0–2 shipped (parsers + theme); Stages 3–7 (SVG renderers + pixel-diff) left |
+| 6 | [**Visual Chrome / Layout Polish**](docs/plans/lane-6-visual-chrome-layout-polish.md) | **0%** | LATER — activates after Lane 3b V2c + Lane 2 Phase 2.2 ship; discrete paper cards, native chrome, float-wrap, validation bar |
+| 7a | [**Visual Fidelity Register**](docs/plans/lane-7a-visual-fidelity-register.md) | **0%** | LATER (gated on 6a+6b) — V5 covers, V6 REF/PAGEREF, V7 cascade audit |
+| 7b | [**Revision & Redline Completion**](docs/plans/lane-7b-revision-redline-completion.md) | **0%** | LATER (gated on 6a+6b) — 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+6b) — 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+6b) — harness-crash-hardening, fastload activation, worktree consolidation |
+| 8 | [**API Ergonomics / Errors / BC**](docs/plans/lane-8-api-ergonomics.md) | **40%** | LATER — Tracks A+C shipped (error catalog + ergonomics fixes); Tracks B+D+E + public-api.md end-to-end refactor remain |
+| 9 | [**Shipping (v2.0.0)**](docs/plans/lane-9-shipping.md) | **0%** | FINAL — API freeze, semver discipline, changelog, telemetry, customer migration guides, doc completeness audit |
+
+**Aggregate v2.0.0 readiness:** ~70% — long poles are Lane 3 O8 + P9/P10, Lane 4 P15/P16/P17, Lane 1 R.1–R.5, Lane 5 Stage 4 SVG renderers (Lane 5 ships on independent v2.x cadence). Detailed task-completeness factor + per-lane backlog inventory in [`docs/plans/coordination-prompt.md`](docs/plans/coordination-prompt.md).
 
 ### Technical Wiki
 

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.48",
+  "version": "1.0.50",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
-  "packageManager": "pnpm@10.30.3",
   "type": "module",
   "sideEffects": [
     "**/*.css"
@@ -93,35 +92,6 @@
     "./ui-tailwind/theme/editor-theme.css": "./src/ui-tailwind/theme/editor-theme.css"
   },
   "types": "./src/index.ts",
-  "scripts": {
-    "build": "tsup",
-    "test": "bash scripts/run-workspace-tests.sh",
-    "test:repo": "node scripts/ci-check-layout-engine-version.mjs && node scripts/run-repo-tests.mjs core",
-    "test:repo:all": "node scripts/run-repo-tests.mjs all",
-    "test:repo:optional": "node scripts/run-repo-tests.mjs optional",
-    "test:repo:browser-ui": "node scripts/run-repo-tests.mjs browser-ui",
-    "test:wcag-audit": "node scripts/run-repo-tests.mjs wcag-audit",
-    "test:harness": "pnpm --filter @docx-react-component/react-word-editor-harness test",
-    "test:visual": "VISUAL_SMOKE_PROFILE=bare pnpm exec playwright test --project=chromium",
-    "test:visual:chrome": "VISUAL_SMOKE_PROFILE=chrome-cycle pnpm exec playwright test --project=chromium",
-    "visual:list-runs": "node scripts/visual-smoke-list-runs.mjs",
-    "mcp:visual-smoke": "node scripts/visual-smoke-mcp.mjs",
-    "lint": "pnpm run lint:no-authored-js && pnpm run lint:docs-contracts && pnpm run lint:tsgo && pnpm run lint:tsgo:harness",
-    "lint:docs-contracts": "bash scripts/check-reference-load-contract.sh",
-    "lint:no-authored-js": "bash scripts/check-no-authored-js.sh",
-    "lint:tsgo": "tsgo --noEmit -p tsconfig.build.json",
-    "lint:tsgo:harness": "pnpm --filter @docx-react-component/react-word-editor-harness lint:tsgo",
-    "context7:api-check": "bash scripts/context7-export-env.sh run bash scripts/context7-api-check.sh",
-    "wave:doctor": "bash scripts/context7-export-env.sh run pnpm exec wave doctor --json",
-    "wave:dry-run": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main --dry-run --no-dashboard",
-    "wave:launch": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main",
-    "wave:launch:managed": "bash scripts/wave-launch.sh",
-    "wave:status": "bash scripts/wave-status.sh",
-    "wave:watch": "bash scripts/wave-watch.sh --follow",
-    "wave:dashboard:current": "bash scripts/wave-dashboard-attach.sh current",
-    "wave:dashboard:global": "bash scripts/wave-dashboard-attach.sh global",
-    "harness:dev": "pnpm --filter @docx-react-component/react-word-editor-harness dev"
-  },
   "keywords": [
     "docx",
     "word",
@@ -205,14 +175,33 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.30"
   },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild",
-      "sharp"
-    ],
-    "overrides": {
-      "react": "19.2.4",
-      "react-dom": "19.2.4"
-    }
+  "scripts": {
+    "build": "tsup",
+    "test": "bash scripts/run-workspace-tests.sh",
+    "test:repo": "node scripts/ci-check-layout-engine-version.mjs && node scripts/run-repo-tests.mjs core",
+    "test:repo:all": "node scripts/run-repo-tests.mjs all",
+    "test:repo:optional": "node scripts/run-repo-tests.mjs optional",
+    "test:repo:browser-ui": "node scripts/run-repo-tests.mjs browser-ui",
+    "test:wcag-audit": "node scripts/run-repo-tests.mjs wcag-audit",
+    "test:harness": "pnpm --filter @docx-react-component/react-word-editor-harness test",
+    "test:visual": "VISUAL_SMOKE_PROFILE=bare pnpm exec playwright test --project=chromium",
+    "test:visual:chrome": "VISUAL_SMOKE_PROFILE=chrome-cycle pnpm exec playwright test --project=chromium",
+    "visual:list-runs": "node scripts/visual-smoke-list-runs.mjs",
+    "mcp:visual-smoke": "node scripts/visual-smoke-mcp.mjs",
+    "lint": "pnpm run lint:no-authored-js && pnpm run lint:docs-contracts && pnpm run lint:tsgo && pnpm run lint:tsgo:harness",
+    "lint:docs-contracts": "bash scripts/check-reference-load-contract.sh",
+    "lint:no-authored-js": "bash scripts/check-no-authored-js.sh",
+    "lint:tsgo": "tsgo --noEmit -p tsconfig.build.json",
+    "lint:tsgo:harness": "pnpm --filter @docx-react-component/react-word-editor-harness lint:tsgo",
+    "context7:api-check": "bash scripts/context7-export-env.sh run bash scripts/context7-api-check.sh",
+    "wave:doctor": "bash scripts/context7-export-env.sh run pnpm exec wave doctor --json",
+    "wave:dry-run": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main --dry-run --no-dashboard",
+    "wave:launch": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main",
+    "wave:launch:managed": "bash scripts/wave-launch.sh",
+    "wave:status": "bash scripts/wave-status.sh",
+    "wave:watch": "bash scripts/wave-watch.sh --follow",
+    "wave:dashboard:current": "bash scripts/wave-dashboard-attach.sh current",
+    "wave:dashboard:global": "bash scripts/wave-dashboard-attach.sh global",
+    "harness:dev": "pnpm --filter @docx-react-component/react-word-editor-harness dev"
   }
-}
+}

package/src/api/public-types.ts

@@ -1,8 +1,10 @@
 import type { PersistedEditorSnapshot as RuntimePersistedEditorSnapshot } from "../core/state/editor-state.ts";
-import type { CanonicalParagraphFormatting, CanonicalRunFormatting } from "../model/canonical-document.ts";
+import type { HarnessDebugPorts } from "../internal/harness-debug-ports.ts";
+import type { BlockNode, CanonicalParagraphFormatting, CanonicalRunFormatting, TextMark } from "../model/canonical-document.ts";
 import type { WordReviewEditorLayoutFacet } from "../runtime/layout/public-facet.ts";
 import type { RenderFrameRect } from "../runtime/render/index.ts";
 import type { ScopeRailPosture } from "../runtime/workflow-rail-segments.ts";
+import type { SharedWorkflowState } from "../runtime/collab/workflow-shared.ts";
 import type {
   MetadataPersistenceMode,
   ScopeMetadataPersistence,
@@ -46,6 +48,7 @@ export type {
 };
 
 export type { CanonicalParagraphFormatting, CanonicalRunFormatting };
+export type { SharedWorkflowState };
 
 export type {
   WordReviewEditorLayoutFacet,
@@ -750,6 +753,36 @@ export interface InsertImageOptions {
   altText?: string;
 }
 
+/** Re-export canonical `TextMark` so hosts can construct explicit-mode directives for I7 `replaceText`. */
+export type { TextMark };
+
+/**
+ * I2 Tier B Slice 1 — a block-level payload for `insertFragment` and the paste
+ * parsers that will drive it in later slices. Carries zero or more canonical
+ * block nodes (paragraphs, tables, SDTs, etc.); a host that constructs one
+ * directly is responsible for the blocks being well-formed per the canonical
+ * schema. The HTML / Word-clipboard parsers (Slices 2+3) will produce these.
+ */
+export interface CanonicalDocumentFragment {
+  blocks: BlockNode[];
+}
+
+/**
+ * I7 — `replaceText` / `text.insert` formatting directive.
+ *
+ * - `paragraph-default` (default): inserted text carries no run marks; the paragraph-level
+ *   cascade applies. Pre-I7 behavior.
+ * - `match-replaced-range`: walk text units within the replaced range; if all share the
+ *   same marks, apply them to the inserted text. Mixed ranges fall back to
+ *   `paragraph-default`. For collapsed (empty) ranges the marks of the run immediately
+ *   left of the caret are used (Word-matching behavior).
+ * - `explicit`: apply the caller-supplied `marks` verbatim.
+ */
+export type TextFormattingDirective =
+  | { mode: "paragraph-default" }
+  | { mode: "match-replaced-range" }
+  | { mode: "explicit"; marks: TextMark[] };
+
 export type SurfaceTextMark =
   | "bold"
   | "italic"
@@ -1685,6 +1718,16 @@ export interface AddCommentParams {
   anchor?: EditorAnchorProjection;
   body?: string;
   authorId?: string;
+  /**
+   * I8 — When `true`, anchors that would be rejected with reason
+   * `comment_anchor_table_adjacent` are auto-snapped to the enclosing
+   * paragraph boundaries before the comment is created. Defaults to
+   * `false` for back-compat. Removed once Lane 3 §O8 lands the deep
+   * serializer fix and mid-run-near-table anchors no longer need
+   * mitigation — the option stays useful for hosts that prefer
+   * boundary-aligned comments regardless.
+   */
+  snapToSafeBoundary?: boolean;
 }
 
 export interface AddCommentResult {
@@ -2007,6 +2050,7 @@ export interface WorkflowBlockedCommandReason {
   code:
     | "outside_workflow_scope"
     | "workflow_comment_only"
+    | "workflow_round_locked"
     | "workflow_view_only"
     | "workflow_preserve_only"
     | "workflow_blocked_import"
@@ -2881,7 +2925,19 @@ export interface WordReviewEditorRef {
   isDirty(): boolean;
   getFormattingState(): FormattingStateSnapshot;
   getStyleCatalog(): StyleCatalogSnapshot;
-  replaceText(text: string, target?: EditorAnchorProjection): void;
+  replaceText(
+    text: string,
+    target?: EditorAnchorProjection,
+    formatting?: TextFormattingDirective,
+  ): void;
+  /**
+   * I2 Tier B Slice 1 — splice a canonical block-level fragment at the target
+   * anchor (or at the current selection when omitted). Empty fragment = no-op.
+   * Baseline semantic: split the caret paragraph and insert fragment blocks
+   * between the halves; range selections are deleted first. Future slices will
+   * add merge-intent + richer caret placement as paste parsers come online.
+   */
+  insertFragment(fragment: CanonicalDocumentFragment, target?: EditorAnchorProjection): void;
   toggleBulletedList(): void;
   toggleNumberedList(): void;
   toggleBold(): void;
@@ -2969,6 +3025,7 @@ export interface WordReviewEditorRef {
   setImageFrame(mediaId: string, offsets: { horizontalOffsetEmu?: number; verticalOffsetEmu?: number }): void;
   setWorkflowOverlay(overlay: WorkflowOverlay): void;
   clearWorkflowOverlay(): void;
+  setSharedWorkflowState(state: SharedWorkflowState | null): void;
   getWorkflowScopeSnapshot(): WorkflowScopeSnapshot | null;
   getInteractionGuardSnapshot(): InteractionGuardSnapshot;
   getWorkflowMarkupSnapshot(): WorkflowMarkupSnapshot;
@@ -3208,20 +3265,54 @@ export interface WordReviewEditorProps {
   chromeOptions?: Partial<WordReviewEditorChromeOptions>;
   markupDisplay?: "clean" | "simple" | "all";
   /**
-   * Harness/debug-only preview toggle for preserve-only features
-   * (charts, SmartArt, shapes, WordArt, VML rendered as typed atoms;
-   * the "N preserve-only features detected" banner; lock-callouts).
+   * @internal HARNESS-ONLY debug-ports token.
+   *
+   * **Do not set this from downstream consumer code.** This prop
+   * replaces the former `showUnsupportedObjectPreviews?: boolean`
+   * toggle, which regressed to `true` three times through merges
+   * (PRs #124, #131, #160) and leaked preserve-only preview chrome
+   * (charts, SmartArt, shapes, WordArt, VML, "N preserve-only
+   * features detected" banner, lock-callouts) into consumer apps.
+   *
+   * A valid value is only obtainable from the internal module
+   * `src/internal/harness-debug-ports.ts` via
+   * `__createHarnessDebugPorts()`. That module is deliberately **not
+   * listed in `package.json#exports`**, so downstream consumers
+   * cannot import it through any public subpath. The token type is
+   * branded with a module-local `unique symbol`, so downstream
+   * callers cannot construct a value structurally either — any
+   * attempt to set this prop from outside the in-repo harness will
+   * produce a TypeScript error.
    *
-   * MUST default to `false`. Consumer hosts MUST NOT hard-code `true` —
-   * this is a dev opt-in gated by the harness dev drawer's
-   * `debugMode && showUnsupportedObjectPreviews` AND-gate. Flipping the
-   * default or dropping the AND-gate is a regression that has landed
-   * three times (PRs #124, #131, #160); the invariant is locked by
+   * At runtime, even a successfully-constructed token is
+   * gated by `globalThis.__DOCX_REACT_COMPONENT_HARNESS__ === true`,
+   * which only the harness sets via `__markHarnessEnvironment()`.
+   * The permissions field (`unsupportedObjectPreviews`) is forced
+   * to `false` outside the harness environment regardless of input.
+   *
+   * Invariant locked at
    * `test/ui/unsupported-previews-invariant.test.ts`.
+   */
+  __harnessDebugPorts?: HarnessDebugPorts;
+  /**
+   * Declarative policy for showing preserve-only previews
+   * (charts, SmartArt, shapes, WordArt, VML) and the
+   * "N preserve-only features detected" banner. Orthogonal to the
+   * harness-only `__harnessDebugPorts` token: hosts can opt into
+   * previews without a harness environment.
+   *
+   * - `"never"` — previews are hidden (default).
+   * - `"review-only"` — previews show when `reviewMode === "review"`
+   *   and hide when `reviewMode === "editing"`.
+   * - `"always"` — previews show in every review mode.
+   *
+   * Effective visibility rule:
+   *   `policy === "always"` OR
+   *   (`policy === "review-only"` AND `reviewMode === "review"`)
    *
-   * @default false
+   * @default "never"
    */
-  showUnsupportedObjectPreviews?: boolean;
+  unsupportedPreviewsPolicy?: "never" | "review-only" | "always";
   showReviewPanel?: boolean;
   chromeVisibility?: Partial<WordReviewEditorChromeVisibility>;
   hostAdapter?: EditorHostAdapter;

package/src/core/commands/index.ts

@@ -49,7 +49,9 @@ import type {
   RuntimeRenderSnapshot,
   SectionBreakType,
   SectionLayoutPatch,
+  CanonicalDocumentFragment,
   SectionPageNumberingPatch,
+  TextFormattingDirective,
   WorkflowMetadataDefinition,
   WorkflowMetadataEntry,
   WorkflowOverlay,
@@ -87,6 +89,7 @@ import {
   setHeaderFooterLinkAtSectionIndex,
 } from "./section-layout-commands.ts";
 import { insertPageBreak, insertTable } from "./text-commands.ts";
+import { applyFragmentInsert } from "../../runtime/structure-ops/fragment-insert.ts";
 import type { TableSelectionDescriptor } from "../../runtime/table-commands.ts";
 
 export type ContentChildrenPatch =
@@ -136,6 +139,13 @@ export type EditorCommand =
   | {
       type: "text.insert";
       text: string;
+      /**
+       * I7 — optional directive controlling which character-level marks the inserted
+       * text carries. Defaults to `{ mode: "paragraph-default" }` (today's behavior:
+       * no inherited run marks). See `src/api/public-types.ts` `TextFormattingDirective`
+       * for semantics.
+       */
+      formatting?: TextFormattingDirective;
       origin?: CommandOrigin;
     }
   | {
@@ -162,6 +172,16 @@ export type EditorCommand =
       type: "paragraph.split";
       origin?: CommandOrigin;
     }
+  | {
+      /**
+       * I2 Tier B Slice 1 — splice a `CanonicalDocumentFragment` at the current
+       * selection. Baseline semantic: split the caret paragraph and insert
+       * fragment blocks between the halves; range selections are deleted first.
+       */
+      type: "fragment.insert";
+      fragment: CanonicalDocumentFragment;
+      origin?: CommandOrigin;
+    }
   | {
       type: "runtime.set-read-only";
       readOnly: boolean;
@@ -556,7 +576,7 @@ export function executeEditorCommand(
         : undefined;
       if (suggestingResult) return suggestingResult;
       return applyTextCommand(state, context.timestamp, (document, selection) =>
-        insertText(document, selection, command.text, context),
+        insertText(document, selection, command.text, context, command.formatting),
       );
     }
     case "text.delete-backward": {
@@ -623,6 +643,15 @@ export function executeEditorCommand(
       return applyTextCommand(state, context.timestamp, (document, selection) =>
         splitParagraph(document, selection, context),
       );
+    case "fragment.insert": {
+      // I2 Tier B Slice 1 — route through the structure-ops splicer. 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,
+      });
+      return buildDocumentReplaceTransaction(state, context, result);
+    }
     case "runtime.set-read-only":
       return createTransaction(
         {

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

@@ -1,4 +1,4 @@
-import type { InsertTableOptions } from "../../api/public-types";
+import type { InsertTableOptions, TextFormattingDirective } from "../../api/public-types";
 import type {
   DocumentRootNode,
   ParagraphNode,
@@ -126,6 +126,7 @@ export function insertText(
   selection: SelectionSnapshot,
   text: string,
   context: TextCommandContext,
+  formatting?: TextFormattingDirective,
 ): TextTransactionResult {
   return applyTextTransaction(
     document,
@@ -138,6 +139,7 @@ export function insertText(
           text,
         },
       ],
+      formatting,
     },
     context,
   );

package/src/core/selection/anchor-conversion.ts

@@ -0,0 +1,112 @@
+/**
+ * Canonical boundary between the internal `EditorAnchorProjection` shape
+ * (`src/core/selection/mapping.ts` — `{ kind: "range", range: DocRange,
+ * assoc }`) and the public `EditorAnchorProjection` shape
+ * (`src/api/public-types.ts` — `{ kind: "range", from, to, assoc }`).
+ *
+ * Two shapes stay split intentionally: the internal shape uses `DocRange`
+ * so mapping helpers compose ranges independently of assoc semantics;
+ * the public shape is flat so host consumers can destructure without
+ * reaching through a nested `range` member.
+ *
+ * Every conversion MUST go through this module. Every creation of a
+ * public-shape anchor MUST go through this module. A regression test
+ * in `test/api/anchor-boundary-invariants.test.ts` enforces the "no
+ * ad-hoc helpers outside this file" rule.
+ */
+
+import type { EditorAnchorProjection as PublicEditorAnchorProjection } from "../../api/public-types";
+import {
+  DEFAULT_BOUNDARY_ASSOC,
+  createDetachedAnchor,
+  createNodeAnchor,
+  createRangeAnchor,
+  normalizeRange,
+  type DocRange,
+  type EditorAnchorProjection as InternalEditorAnchorProjection,
+} from "./mapping.ts";
+
+/**
+ * Default boundary-associativity used by public-shape range anchors
+ * when the caller does not provide one. Matches the inline default the
+ * three ad-hoc `createPublicRangeAnchor` helpers all used before this
+ * module existed (`{ start: -1, end: 1 }` — the "outward-biased"
+ * selection).
+ */
+export const DEFAULT_PUBLIC_ASSOC: { start: -1 | 1; end: -1 | 1 } = {
+  start: -1,
+  end: 1,
+};
+
+type PublicRangeAssoc = { start: -1 | 1; end: -1 | 1 };
+
+export function createPublicRangeAnchor(
+  from: number,
+  to: number,
+  assoc: PublicRangeAssoc = DEFAULT_PUBLIC_ASSOC,
+): PublicEditorAnchorProjection {
+  const range = normalizeRange({ from, to });
+  return {
+    kind: "range",
+    from: range.from,
+    to: range.to,
+    assoc,
+  };
+}
+
+export function createPublicNodeAnchor(
+  at: number,
+  assoc: -1 | 1 = 1,
+): PublicEditorAnchorProjection {
+  return { kind: "node", at, assoc };
+}
+
+export function createPublicDetachedAnchor(
+  lastKnownRange: DocRange,
+  reason: "deleted" | "invalidatedByStructureChange" | "importAmbiguity",
+): PublicEditorAnchorProjection {
+  return {
+    kind: "detached",
+    lastKnownRange: normalizeRange(lastKnownRange),
+    reason,
+  };
+}
+
+export function toPublicAnchorProjection(
+  anchor: InternalEditorAnchorProjection,
+): PublicEditorAnchorProjection {
+  switch (anchor.kind) {
+    case "range":
+      return {
+        kind: "range",
+        from: anchor.range.from,
+        to: anchor.range.to,
+        assoc: anchor.assoc,
+      };
+    case "node":
+      return { kind: "node", at: anchor.at, assoc: anchor.assoc };
+    case "detached":
+      return {
+        kind: "detached",
+        lastKnownRange: anchor.lastKnownRange,
+        reason: anchor.reason,
+      };
+  }
+}
+
+export function toInternalAnchorProjection(
+  anchor: PublicEditorAnchorProjection,
+): InternalEditorAnchorProjection {
+  switch (anchor.kind) {
+    case "range":
+      return createRangeAnchor(
+        anchor.from,
+        anchor.to,
+        anchor.assoc ?? DEFAULT_BOUNDARY_ASSOC,
+      );
+    case "node":
+      return createNodeAnchor(anchor.at, anchor.assoc);
+    case "detached":
+      return createDetachedAnchor(anchor.lastKnownRange, anchor.reason);
+  }
+}

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

@@ -103,20 +103,125 @@ export function rangeStaysWithinSingleParagraph(
   return true;
 }
 
+/**
+ * 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.
+ */
+export const TABLE_ADJACENT_WINDOW = 1;
+
+export type CommentAnchorRejectionReason =
+  | "invalid_comment_anchor"
+  | "comment_anchor_table_adjacent";
+
 export function canCreateDocxCommentAnchor(
   content: unknown,
   anchor: ReviewAnchor,
 ): boolean {
+  return commentAnchorRejectionReason(content, anchor) === null;
+}
+
+export function commentAnchorRejectionReason(
+  content: unknown,
+  anchor: ReviewAnchor,
+): CommentAnchorRejectionReason | null {
   if (anchor.kind !== "range") {
-    return false;
+    return "invalid_comment_anchor";
   }
 
   const normalized = normalizeRange(anchor.range);
   if (normalized.from === normalized.to) {
-    return false;
+    return "invalid_comment_anchor";
+  }
+
+  if (!rangeStaysWithinCommentableStory(content, normalized)) {
+    return "invalid_comment_anchor";
+  }
+
+  if (rangeLandsMidRunNearTableBoundary(content, normalized)) {
+    return "comment_anchor_table_adjacent";
   }
 
-  return rangeStaysWithinCommentableStory(content, normalized);
+  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).
+ */
+export function snapCommentAnchorAwayFromTable(
+  content: unknown,
+  anchor: ReviewAnchor,
+): ReviewAnchor | null {
+  if (anchor.kind !== "range") return null;
+
+  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;
+
+  const surfaceBlocks = readSurfaceBlocks(content);
+  if (!surfaceBlocks) return null;
+
+  const fromOwner = findContainingParagraphForEndpoint(surfaceBlocks, normalized.from, "start");
+  const toOwner = findContainingParagraphForEndpoint(surfaceBlocks, normalized.to, "end");
+  if (!fromOwner || !toOwner) return null;
+
+  const snappedFrom = normalized.from > fromOwner.from && normalized.from < fromOwner.to
+    ? fromOwner.from
+    : normalized.from;
+  const snappedTo = normalized.to > toOwner.from && normalized.to < toOwner.to
+    ? toOwner.to
+    : normalized.to;
+
+  if (snappedFrom === snappedTo) return null;
+
+  const snapped = createRangeAnchor(snappedFrom, snappedTo);
+  return canCreateDocxCommentAnchor(content, snapped) ? snapped : null;
+}
+
+function rangeLandsMidRunNearTableBoundary(
+  content: unknown,
+  range: DocRange,
+): boolean {
+  const surfaceBlocks = readSurfaceBlocks(content);
+  if (!surfaceBlocks) return false;
+
+  const tableBlocks = surfaceBlocks.filter((block) => block.kind === "table");
+  if (tableBlocks.length === 0) return false;
+
+  const fromOwner = findContainingParagraphForEndpoint(surfaceBlocks, range.from, "start");
+  const toOwner = findContainingParagraphForEndpoint(surfaceBlocks, range.to, "end");
+  if (!fromOwner || !toOwner) return false;
+
+  const fromMidRun = range.from > fromOwner.from && range.from < fromOwner.to;
+  const toMidRun = range.to > toOwner.from && range.to < toOwner.to;
+  if (!fromMidRun && !toMidRun) return false;
+
+  const fromAdjacent = fromMidRun && paragraphIsTableAdjacent(fromOwner, tableBlocks);
+  const toAdjacent = toMidRun && paragraphIsTableAdjacent(toOwner, tableBlocks);
+  return fromAdjacent || toAdjacent;
+}
+
+function paragraphIsTableAdjacent(
+  paragraph: FlattenedSurfaceBlock,
+  tableBlocks: readonly FlattenedSurfaceBlock[],
+): boolean {
+  return tableBlocks.some((table) => {
+    if (table.tableId !== null && table.tableId === paragraph.tableId) {
+      // Skip: a table block at the same cell scope would be a
+      // descendant of the paragraph's containing cell, not a sibling.
+      return false;
+    }
+    const leftGap = Math.abs(paragraph.from - table.to);
+    const rightGap = Math.abs(paragraph.to - table.from);
+    return leftGap <= TABLE_ADJACENT_WINDOW || rightGap <= TABLE_ADJACENT_WINDOW;
+  });
 }
 
 export function rangeStaysWithinCommentableStory(