@beyondwork/docx-react-component 1.0.49 → 1.0.50

package/README.md

@@ -235,7 +235,10 @@ Engineering work is organized into 9 lanes (5 active now + 2 later polish + 2 fi
 | 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 |
-| 7 | [**Bugs / Gaps / Cross-cutting**](docs/plans/lane-7-bugs-gaps-cross-cutting.md) | **0%** | LATER — drain V#/O#/X# register, trigger-gated work, infrastructure hardening |
+| 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 |
 

package/package.json

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

@@ -1,6 +1,6 @@
 import type { PersistedEditorSnapshot as RuntimePersistedEditorSnapshot } from "../core/state/editor-state.ts";
 import type { HarnessDebugPorts } from "../internal/harness-debug-ports.ts";
-import type { CanonicalParagraphFormatting, CanonicalRunFormatting, TextMark } from "../model/canonical-document.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";
@@ -756,6 +756,17 @@ export interface InsertImageOptions {
 /** 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.
  *
@@ -2919,6 +2930,14 @@ export interface WordReviewEditorRef {
     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;

package/src/core/commands/index.ts

@@ -49,6 +49,7 @@ import type {
   RuntimeRenderSnapshot,
   SectionBreakType,
   SectionLayoutPatch,
+  CanonicalDocumentFragment,
   SectionPageNumberingPatch,
   TextFormattingDirective,
   WorkflowMetadataDefinition,
@@ -88,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 =
@@ -170,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;
@@ -631,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/io/export/serialize-comments.ts

@@ -760,11 +760,56 @@ function walkInlineNodeForBoundaries(
       return;
     }
     case "t": {
-      const text = node.children
-        .filter((child): child is XmlTextNode => child.type === "text")
-        .map((child) => child.text)
-        .join("");
-      setCursor(getCursor() + Array.from(text).length);
+      // O8 fix: emit a boundary entry for every interior code-point position
+      // so comment anchors landing mid-run resolve to a real source byte
+      // offset instead of silently dropping into skippedCommentIds. The walk
+      // advances through the raw XML source between each text child's start
+      // and end, treating XML entities (& < > " ' &#N;
+      // &#xN;) as a single code point whose byte cursor skips the whole
+      // entity. Surrogate pairs collapse to one code point to match
+      // Array.from(text).iteration used by the existing cursor math.
+      let cursor = getCursor();
+      for (const child of node.children) {
+        if (child.type !== "text") {
+          continue;
+        }
+        let byte = child.start;
+        const end = child.end;
+        while (byte < end) {
+          if (!boundaries.has(cursor)) {
+            // Preserve the outer <w:r>-entry at runStart: it maps cursor to
+            // node.start (between runs, a valid insertion point), whereas the
+            // interior byte here would point inside <w:t> where inserting
+            // commentRangeStart/End would corrupt the text node.
+            boundaries.set(cursor, byte);
+          }
+          const ch = sourceXml.charCodeAt(byte);
+          if (ch === 0x26 /* & */) {
+            const semi = sourceXml.indexOf(";", byte + 1);
+            if (semi !== -1 && semi < end) {
+              byte = semi + 1;
+            } else {
+              byte += 1;
+            }
+          } else if (ch >= 0xd800 && ch <= 0xdbff && byte + 1 < end) {
+            // High surrogate followed by low surrogate = 1 code point / 2 units.
+            byte += 2;
+          } else {
+            byte += 1;
+          }
+          cursor += 1;
+        }
+        // Trailing boundary: map the cursor immediately after the last
+        // character to the byte just before </w:t>, so an anchor at the right
+        // edge of this text node resolves inside the run. The outer <w:r>
+        // close will overwrite nothing here because it runs after the inner
+        // walk and uses boundaries.set (last-write-wins is fine: node.end
+        // points to the same logical insertion point between runs).
+        if (!boundaries.has(cursor)) {
+          boundaries.set(cursor, end);
+        }
+      }
+      setCursor(cursor);
       return;
     }
     case "tab":

package/src/io/paste/word-clipboard.ts

@@ -0,0 +1,114 @@
+/**
+ * I2 Tier B Slice 2 — Office-clipboard / WordprocessingML paste parser.
+ *
+ * Adapts the authoritative `parseMainDocumentXml` → `normalizeParsedTextDocument`
+ * pipeline to a clipboard-paste payload. Inputs from the browser clipboard under
+ * the Office MIME types (`application/x-docx-fragment`,
+ * `application/vnd.ms-word.wordprocessingml.paste`) arrive either as:
+ *
+ *   - a full `<w:document><w:body>…</w:body></w:document>` wrapper, or
+ *   - a bare `<w:body>…</w:body>` fragment.
+ *
+ * This adapter auto-wraps the bare form, runs the full parse + normalize, and
+ * returns the resulting canonical `BlockNode`s as a `CanonicalDocumentFragment`.
+ * Errors (XML parse failure, missing body) are returned as a structured result
+ * instead of thrown, so `pm-command-bridge.ts` `handlePaste` can gracefully fall
+ * through to HTML or plain-text Tier A.
+ */
+
+import type { CanonicalDocumentFragment } from "../../api/public-types.ts";
+import type { DocumentRootNode } from "../../model/canonical-document.ts";
+import { parseMainDocumentXml } from "../ooxml/parse-main-document.ts";
+import { normalizeParsedTextDocument } from "../normalize/normalize-text.ts";
+import { serializeMainDocument } from "../export/serialize-main-document.ts";
+
+export type ParseCanonicalFragmentResult =
+  | { ok: true; fragment: CanonicalDocumentFragment }
+  | { ok: false; reason: string };
+
+const WORD_NS = `xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"`;
+
+export function parseCanonicalFragmentFromWordML(xml: string): ParseCanonicalFragmentResult {
+  if (typeof xml !== "string" || xml.length === 0) {
+    return { ok: false, reason: "empty WordML payload" };
+  }
+
+  const prepared = ensureDocumentShell(xml);
+
+  try {
+    const parsed = parseMainDocumentXml(prepared);
+    const normalized = normalizeParsedTextDocument(parsed);
+    return {
+      ok: true,
+      fragment: { blocks: normalized.content.children },
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      reason: error instanceof Error ? error.message : "unknown WordML parse error",
+    };
+  }
+}
+
+/**
+ * Normalize the incoming clipboard payload into a full `<w:document><w:body>…`
+ * shell. Handles three shapes:
+ *
+ *   1. Already-wrapped `<w:document>…</w:document>` → pass-through with the XML
+ *      declaration normalized.
+ *   2. Bare `<w:body>…</w:body>` — wrap in `<w:document>…</w:document>`.
+ *   3. Any other fragment — wrap the whole input in `<w:document><w:body>…`.
+ *
+ * Namespace hygiene: if the input lacks the `xmlns:w` declaration on whatever
+ * outer element survives, it's added to the outer `<w:document>` wrapper.
+ */
+function ensureDocumentShell(xml: string): string {
+  const trimmed = xml.trim();
+  const withoutDecl = trimmed.replace(/^<\?xml[^?]*\?>/, "").trim();
+
+  const hasDocumentWrapper = /^<w:document[\s>]/i.test(withoutDecl);
+  if (hasDocumentWrapper) {
+    return ensureXmlDecl(trimmed);
+  }
+
+  const hasBodyWrapper = /^<w:body[\s>]/i.test(withoutDecl);
+  const inner = hasBodyWrapper ? withoutDecl : `<w:body>${withoutDecl}</w:body>`;
+
+  const wrapped = `<w:document ${WORD_NS}>${stripRedundantNs(inner)}</w:document>`;
+  return ensureXmlDecl(wrapped);
+}
+
+function ensureXmlDecl(xml: string): string {
+  if (/^\s*<\?xml/.test(xml)) return xml;
+  return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>${xml}`;
+}
+
+/**
+ * Strip `xmlns:w="…"` from the first child element so the outer
+ * `<w:document>` declaration is the single authoritative binding. The XML
+ * parser accepts both, but removing the duplicate keeps output clean.
+ */
+function stripRedundantNs(xml: string): string {
+  return xml.replace(/\s+xmlns:w="[^"]*"/, "");
+}
+
+/**
+ * I2 Tier B Slice 4a — inverse of `parseCanonicalFragmentFromWordML`. Produces
+ * a full `<w:document><w:body>…</w:body></w:document>` payload suitable for
+ * writing to the system clipboard under the Office MIME types, or for exchange
+ * with agents that expect WordML.
+ *
+ * Implementation reuses the authoritative `serializeMainDocument` pipeline by
+ * wrapping `fragment.blocks` in a synthetic `DocumentRootNode`. The output is
+ * the full document XML — parsers (browsers, Word, our own Slice 2 adapter)
+ * accept the full envelope, so there's no need to strip it down to a bare
+ * `<w:body>` fragment.
+ */
+export function serializeFragmentToWordML(fragment: CanonicalDocumentFragment): string {
+  const root: DocumentRootNode = {
+    type: "doc",
+    children: fragment.blocks,
+  };
+  const serialized = serializeMainDocument(root);
+  return serialized.documentXml;
+}

package/src/runtime/document-runtime.ts

@@ -30,6 +30,7 @@ import type {
   DocumentTextToken,
   EditorSessionState,
   EditorAnchorProjection,
+  CanonicalDocumentFragment,
   TextFormattingDirective,
   EditorError,
   EditorStoryTarget,
@@ -266,7 +267,8 @@ export type ActiveStoryTextCommand =
   | Extract<EditorCommand, { type: "text.insert-tab" }>
   | Extract<EditorCommand, { type: "text.outdent-tab" }>
   | Extract<EditorCommand, { type: "text.insert-hard-break" }>
-  | Extract<EditorCommand, { type: "paragraph.split" }>;
+  | Extract<EditorCommand, { type: "paragraph.split" }>
+  | Extract<EditorCommand, { type: "fragment.insert" }>;
 
 export interface DocumentRuntime {
   subscribe(listener: () => void): Unsubscribe;
@@ -275,6 +277,7 @@ export interface DocumentRuntime {
   getCanonicalDocument(): CanonicalDocumentEnvelope;
   getSourcePackage(): EditorSessionState["sourcePackage"] | undefined;
   replaceText(text: string, target?: EditorAnchorProjection, formatting?: TextFormattingDirective): void;
+  insertFragment(fragment: CanonicalDocumentFragment, target?: EditorAnchorProjection): void;
   applyActiveStoryTextCommand(command: ActiveStoryTextCommand): TextCommandAck;
   dispatch(command: EditorCommand): void;
   /**
@@ -2314,6 +2317,26 @@ export function createDocumentRuntime(
         emitError(toRuntimeError(error));
       }
     },
+    insertFragment(fragment, target) {
+      // I2 Tier B Slice 1 — dispatch `fragment.insert` against the active story. The
+      // runtime command handler routes into `applyFragmentInsert` (structure-ops).
+      try {
+        const timestamp = clock();
+        applyTextCommandInActiveStory(
+          {
+            type: "fragment.insert",
+            fragment,
+            origin: createOrigin("api", timestamp),
+          },
+          {
+            selection: target ? createSelectionFromPublicAnchor(target) : state.selection,
+            blockedCommandName: "insertFragment",
+          },
+        );
+      } catch (error) {
+        emitError(toRuntimeError(error));
+      }
+    },
     applyActiveStoryTextCommand(command) {
       try {
         return applyTextCommandInActiveStory(command);

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

@@ -42,8 +42,18 @@
  *       file under `src/runtime/layout/**` changed. Safe to treat
  *       versions 3, 4, and 5 as cache-compatible if a migration ever
  *       needs to collapse them.
+ *   6 — Lane 3a P9 Phase A. `RenderAnchorIndex` gains three chrome-kind
+ *       resolvers (`byScopeId`, `byCommentId`, `byRevisionId`) sourced
+ *       from the resolved `DecorationIndex`, and `buildAnchorIndex`
+ *       runs in two phases inside the render kernel so the final index
+ *       carries decoration-aware lookups. No cached-geometry change;
+ *       consumers (Lane 1 R.1 SelectionLayer, Lane 6 P11 chrome rails)
+ *       can now query one unified API instead of reaching into
+ *       `frame.decorationIndex`. Cache envelopes from version 5 are
+ *       invalidated on load because the anchor-index public shape
+ *       changed even though pixel geometry did not.
  */
-export const LAYOUT_ENGINE_VERSION = 5 as const;
+export const LAYOUT_ENGINE_VERSION = 6 as const;
 
 /**
  * Serialization schema version for the LayCache payload (the cache envelope

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

@@ -1824,22 +1824,15 @@ function resolveAnchorRects(
       return rect ? [rect] : [];
     }
     case "scope-id": {
-      const id = String(query.value);
-      return frame.decorationIndex.workflow
-        .filter((decoration) => decoration.refId === id)
-        .map((decoration) => decoration.frame);
+      return frame.anchorIndex.byScopeId(String(query.value));
     }
     case "comment-id": {
-      const id = String(query.value);
-      return frame.decorationIndex.comments
-        .filter((decoration) => decoration.refId === id)
-        .map((decoration) => decoration.frame);
+      const rect = frame.anchorIndex.byCommentId(String(query.value));
+      return rect ? [rect] : [];
     }
     case "revision-id": {
-      const id = String(query.value);
-      return frame.decorationIndex.revisions
-        .filter((decoration) => decoration.refId === id)
-        .map((decoration) => decoration.frame);
+      const rect = frame.anchorIndex.byRevisionId(String(query.value));
+      return rect ? [rect] : [];
     }
     default: {
       const exhaustive: never = query.kind;

package/src/runtime/render/render-frame-types.ts

@@ -230,6 +230,20 @@ export interface RenderAnchorIndex {
     tableBlockId: string,
     rowIndex: number,
   ): RenderFrameRect | null;
+  /**
+   * Chrome-kind resolvers (P9 Phase A). Read against the frame's
+   * `decorationIndex` so chrome surfaces (scope rails, comment balloons,
+   * revision margin bars, Lane 1 R.1 SelectionLayer) query one unified
+   * API instead of reaching into `frame.decorationIndex` directly.
+   *
+   * `byScopeId` returns every rect because a single workflow scope may
+   * cover multiple pages (one `RenderBlockDecoration` per page); chrome
+   * rails read the list. `byCommentId` and `byRevisionId` return a single
+   * rect — `resolveDecorationIndex` emits one entry per thread/revision.
+   */
+  byScopeId(scopeId: string): readonly RenderFrameRect[];
+  byCommentId(commentId: string): RenderFrameRect | null;
+  byRevisionId(revisionId: string): RenderFrameRect | null;
 }
 
 // ---------------------------------------------------------------------------

package/src/runtime/render/render-kernel.ts

@@ -192,7 +192,16 @@ export function createRenderKernel(input: CreateRenderKernelInput): RenderKernel
     }
 
     const pendingDeltas = input.getPendingOpDeltas?.() ?? [];
-    const anchorIndex = buildAnchorIndex(renderPages, pendingDeltas, zoom.pxPerTwip);
+    // P9 Phase A — two-phase anchor-index build. The decoration resolver
+    // reads the anchor index to map runtime ranges to frame rects; the
+    // final anchor index then exposes chrome-kind resolvers that read
+    // back from the resolved decoration index. Rebuilding the index with
+    // the resolved decoration data avoids a post-hoc mutation seam.
+    const baseAnchorIndex = buildAnchorIndex(
+      renderPages,
+      pendingDeltas,
+      zoom.pxPerTwip,
+    );
     const includeDecorations = options?.includeDecorations ?? true;
     const sources = input.getDecorationSources?.();
     const hasSources =
@@ -205,8 +214,14 @@ export function createRenderKernel(input: CreateRenderKernelInput): RenderKernel
     const decorationIndex: DecorationIndex = !includeDecorations
       ? EMPTY_DECORATION_INDEX
       : hasSources
-        ? resolveDecorationIndex({ anchorIndex, ...sources })
+        ? resolveDecorationIndex({ anchorIndex: baseAnchorIndex, ...sources })
         : buildDecorationIndex(renderPages);
+    const anchorIndex = buildAnchorIndex(
+      renderPages,
+      pendingDeltas,
+      zoom.pxPerTwip,
+      decorationIndex,
+    );
 
     // Revision: keyed off the engine's current page graph so repeated reads
     // at the same revision return the same cached frame.  We derive it
@@ -634,6 +649,7 @@ function buildAnchorIndex(
   pages: readonly RenderPage[],
   pendingDeltas: readonly PendingOpDelta[] = [],
   pxPerTwip = 1,
+  decorationIndex: DecorationIndex = EMPTY_DECORATION_INDEX,
 ): RenderAnchorIndex {
   const byRuntimeOffset = new Map<number, RenderFrameRect>();
   const byFragmentId = new Map<string, RenderFrameRect>();
@@ -739,6 +755,28 @@ function buildAnchorIndex(
     byTableRowEdge(tableBlockId, rowIndex) {
       return tableRowEdges.get(`${tableBlockId}:${rowIndex}`) ?? null;
     },
+    // P9 Phase A — chrome-kind resolvers sourced from the resolved
+    // decoration index. Empty by default (the initial frame build passes
+    // `EMPTY_DECORATION_INDEX` until decoration resolution runs); the
+    // kernel re-invokes `buildAnchorIndex` with the resolved index so the
+    // final anchor index carries chrome-aware lookups.
+    byScopeId(scopeId) {
+      return decorationIndex.workflow
+        .filter((decoration) => decoration.refId === scopeId)
+        .map((decoration) => decoration.frame);
+    },
+    byCommentId(commentId) {
+      const match = decorationIndex.comments.find(
+        (decoration) => decoration.refId === commentId,
+      );
+      return match?.frame ?? null;
+    },
+    byRevisionId(revisionId) {
+      const match = decorationIndex.revisions.find(
+        (decoration) => decoration.refId === revisionId,
+      );
+      return match?.frame ?? null;
+    },
   };
 }
 

package/src/runtime/structure-ops/fragment-insert.ts

@@ -0,0 +1,134 @@
+/**
+ * Slice 1 of the I2 Tier B rich-paste sub-plan (`docs/plans/lane-1-i2-tier-b-rich-paste.md`).
+ *
+ * `applyFragmentInsert` is the canonical splicer for `CanonicalDocumentFragment` —
+ * the block-level payload that the HTML and Word-clipboard paste parsers (Slices 2+3)
+ * will produce. Slice 1 ships the shape and a baseline "split-and-splice" semantic
+ * without any parser in front of it, so the public `insertFragment` method can be
+ * driven directly from tests + future hosts.
+ *
+ * Baseline semantics:
+ *   1. Empty fragment → no-op (no revisionToken bump).
+ *   2. Range selection → the range is deleted first via `applyTextTransaction`, then
+ *      the caret is the range start.
+ *   3. Caret paragraph is split via `splitParagraph`; fragment blocks are spliced
+ *      between the two halves. Empty halves at document boundaries are preserved —
+ *      callers can trim them if desired.
+ *
+ * What Slice 1 deliberately does NOT do:
+ *   - Merge-intent (pre-Slice-1 drafts had `firstParagraphMergeIntent` on the type).
+ *     Merge semantics will land in a follow-up slice once we have a paste fixture
+ *     that demonstrates the need.
+ *   - Fragment insertion inside table cells beyond the trivial case. Table-cell
+ *     splicing is currently best-effort: the target paragraph within the cell is
+ *     split, but cross-cell fragments are rejected as a no-op.
+ *   - Comment/revision remapping across the fragment boundary — the splicer returns
+ *     an empty mapping; follow-up slices will produce richer mappings.
+ */
+
+import type { CanonicalDocumentFragment } from "../../api/public-types.ts";
+import {
+  type CanonicalDocumentEnvelope,
+  type SelectionSnapshot,
+  createSelectionSnapshot,
+} from "../../core/state/editor-state.ts";
+import { applyTextTransaction } from "../../core/state/text-transaction.ts";
+import { splitParagraph, type TextCommandContext } from "../../core/commands/text-commands.ts";
+import { resolveParagraphScope, type StructuralMutationResult } from "../../core/commands/structural-helpers.ts";
+import type { BlockNode, DocumentRootNode, ParagraphNode } from "../../model/canonical-document.ts";
+import { createEmptyMapping } from "../../core/selection/mapping.ts";
+
+export function applyFragmentInsert(
+  document: CanonicalDocumentEnvelope,
+  selection: SelectionSnapshot,
+  fragment: CanonicalDocumentFragment,
+  context: TextCommandContext,
+): StructuralMutationResult {
+  if (fragment.blocks.length === 0) {
+    return {
+      changed: false,
+      document,
+      selection,
+    };
+  }
+
+  // Collapse any range selection by first deleting the selected content. The
+  // resulting caret is at `min(anchor, head)`.
+  let workingDocument = document;
+  let workingSelection = selection;
+  if (selection.anchor !== selection.head) {
+    const collapseResult = applyTextTransaction(
+      workingDocument,
+      workingSelection,
+      { type: "replace", insertion: [] },
+      context,
+    );
+    workingDocument = collapseResult.document;
+    workingSelection = collapseResult.selection;
+  }
+
+  // Split the caret paragraph; the fragment blocks go between the two halves.
+  const splitResult = splitParagraph(workingDocument, workingSelection, context);
+  const splitRoot = splitResult.document.content;
+  if (!splitRoot || splitRoot.type !== "doc") {
+    return {
+      changed: false,
+      document,
+      selection,
+    };
+  }
+
+  // Locate the split boundary by re-resolving the paragraph scope against the
+  // pre-split snapshot. The right-half index = scope.blockIndex + 1.
+  const scope = resolveParagraphScope(workingDocument, workingSelection);
+  if (!scope || scope.kind !== "top-level") {
+    // Table-cell fragment insert is out of scope for Slice 1.
+    return {
+      changed: false,
+      document,
+      selection,
+    };
+  }
+
+  const rightHalfIndex = scope.blockIndex + 1;
+  const splicedChildren: BlockNode[] = [
+    ...splitRoot.children.slice(0, rightHalfIndex),
+    ...fragment.blocks.map((block) => cloneBlock(block)),
+    ...splitRoot.children.slice(rightHalfIndex),
+  ];
+
+  const nextRoot: DocumentRootNode = {
+    ...splitRoot,
+    children: splicedChildren,
+  };
+
+  const nextDocument: CanonicalDocumentEnvelope = {
+    ...splitResult.document,
+    updatedAt: context.timestamp,
+    content: nextRoot,
+  };
+
+  // Caret lands at the end of the last fragment block. For Slice 1 we approximate
+  // this with a collapsed selection at position 0 of the new document — richer
+  // caret placement follows once parsers drive this.
+  const nextSelection = createSelectionSnapshot(0, 0);
+
+  return {
+    changed: true,
+    document: nextDocument,
+    selection: nextSelection,
+    mapping: createEmptyMapping(),
+  };
+}
+
+function cloneBlock(block: BlockNode): BlockNode {
+  // Slice 1 uses a structural clone; no need to deep-clone formatting attrs since
+  // fragment blocks are presumed freshly minted by the caller.
+  if (block.type === "paragraph") {
+    return {
+      ...block,
+      children: block.children.map((child) => ({ ...child })),
+    } as ParagraphNode;
+  }
+  return JSON.parse(JSON.stringify(block)) as BlockNode;
+}

package/src/ui/WordReviewEditor.tsx

@@ -486,7 +486,8 @@ export function __createWordReviewEditorRefBridge(
     blur: () => runtime.blur(),
     undo: () => runtime.undo(),
     redo: () => runtime.redo(),
-    replaceText: (text, target) => runtime.replaceText(text, target),
+    replaceText: (text, target, formatting) => runtime.replaceText(text, target, formatting),
+    insertFragment: (fragment, target) => runtime.insertFragment(fragment, target),
     addComment: (params) => runtime.addComment(params),
     openComment: (commentId) => runtime.openComment(commentId),
     resolveComment: (commentId) => runtime.resolveComment(commentId),
@@ -1476,7 +1477,8 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         blur: () => activeRuntime.blur(),
         undo: () => activeRuntime.undo(),
         redo: () => activeRuntime.redo(),
-        replaceText: (text, target) => activeRuntime.replaceText(text, target),
+        replaceText: (text, target, formatting) => activeRuntime.replaceText(text, target, formatting),
+        insertFragment: (fragment, target) => activeRuntime.insertFragment(fragment, target),
         addComment: (params) =>
           activeRuntime.addComment({
             ...params,

package/src/ui/editor-runtime-boundary.ts

@@ -912,6 +912,7 @@ function createLoadingRuntimeBridge(input: {
     getCanonicalDocument: () => input.sessionState.canonicalDocument,
     getSourcePackage: () => input.sessionState.sourcePackage,
     replaceText: () => undefined,
+    insertFragment: () => undefined,
     applyActiveStoryTextCommand: () => ({
       kind: "rejected",
       newRevisionToken: "",

package/src/ui-tailwind/editor-surface/pm-command-bridge.ts

@@ -11,8 +11,29 @@ import {
   extractPlainTextSegments,
   type PastePlainSegment,
 } from "./paste-plain-text";
+import { parseCanonicalFragmentFromWordML } from "../../io/paste/word-clipboard";
 import type { PositionMap } from "./pm-position-map";
 
+/**
+ * I2 Tier B Slice 2 — MIME types Word + the browser use for WordprocessingML
+ * clipboard payloads. The first one is the legacy MS-Office HTML-embedded
+ * format; the second is the native Word clipboard type. Browsers expose both
+ * under `ClipboardEvent.clipboardData.getData(mime)`.
+ */
+const WORDML_MIMES = [
+  "application/x-docx-fragment",
+  "application/vnd.ms-word.wordprocessingml.paste",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+] as const;
+
+function readWordMLPayload(clipboard: DataTransfer): string | null {
+  for (const mime of WORDML_MIMES) {
+    const value = clipboard.getData(mime);
+    if (value && value.trim().length > 0) return value;
+  }
+  return null;
+}
+
 /**
  * Callback subset used by paste / drop dispatch. Exported so tests can
  * record dispatch order without constructing the full
@@ -93,6 +114,18 @@ export interface CommandBridgeCallbacks extends SelectionSyncCallbacks {
     charCount: number;
     source: "paste" | "drop";
   }) => void;
+  /**
+   * I2 Tier B Slice 2 — optional. Fires when the paste handler detects an
+   * Office-clipboard WordprocessingML payload and parses it successfully into
+   * a canonical fragment. The host is responsible for dispatching
+   * `runtime.insertFragment(fragment)`; the bridge does not reach into the
+   * runtime directly so this plumbing stays consistent with the Tier A
+   * plain-text callback pattern.
+   */
+  onPasteFragment?: (meta: {
+    fragment: import("../../api/public-types.ts").CanonicalDocumentFragment;
+    source: "wordml";
+  }) => void;
   /**
    * Optional. Fires on `compositionstart` (true) and `compositionend`
    * (false). The surface forwards this to the predicted lane's session
@@ -195,11 +228,17 @@ export function createCommandBridgePlugins(
         return true; // Block PM from processing
       },
 
-      // Plain-text paste: extract text/plain from the clipboard and
-      // dispatch through the runtime-owned callbacks that typing uses.
-      // Rich paste (HTML, Office clipboard) stays blocked — hosts that
-      // listen for onBlockedInput still get notified when a non-plain-
-      // text payload arrives. See docs/plans/editor-paste-drop.md.
+      // I2 paste handler — Tier B (WordML) preferred, Tier A (plain) fallback.
+      //
+      // Preference order per `docs/plans/lane-1-i2-tier-b-rich-paste.md`:
+      //   1. Office-clipboard WordprocessingML payload if the host wired
+      //      `onPasteFragment` AND the clipboard carries the MIME. Parsed via
+      //      `parseCanonicalFragmentFromWordML`.
+      //   2. Plain text via `extractPlainTextSegments` (Tier A).
+      //   3. `onBlockedInput` for HTML-only / empty payloads.
+      //
+      // Rich-paste fallback on parse failure or missing host callback: fall
+      // through to Tier A so the user isn't left with a silent no-op.
       handlePaste(_view, event) {
         if (isComposing) return true;
         const clipboard = event.clipboardData;
@@ -207,6 +246,22 @@ export function createCommandBridgePlugins(
           callbacks.onBlockedInput?.("paste", "Clipboard data was not available.");
           return true;
         }
+
+        // Tier B: WordprocessingML
+        if (callbacks.onPasteFragment) {
+          const wordml = readWordMLPayload(clipboard);
+          if (wordml) {
+            const parsed = parseCanonicalFragmentFromWordML(wordml);
+            if (parsed.ok && parsed.fragment.blocks.length > 0) {
+              callbacks.onPasteFragment({ fragment: parsed.fragment, source: "wordml" });
+              return true;
+            }
+            // Parse failed or empty — fall through to plain-text so the paste
+            // still does something (defensive against malformed clipboard payloads).
+          }
+        }
+
+        // Tier A: plain text
         const plain = clipboard.getData("text/plain");
         if (!plain) {
           callbacks.onBlockedInput?.(