@beyondwork/docx-react-component 1.0.48 → 1.0.50

package/src/runtime/theme-color-resolver.ts

@@ -0,0 +1,188 @@
+/**
+ * Resolve a (`<w:color>`-shaped) theme-color reference to a concrete hex
+ * string, applying the `w:themeTint` / `w:themeShade` HSL-luminance
+ * modulation per ECMA-376 §17.18.85 / §17.18.83.
+ *
+ * Usage:
+ *   - The IO layer (`parse-run-formatting.ts`) captures
+ *     `colorThemeSlot` / `colorThemeTint` / `colorThemeShade` on
+ *     `CanonicalRunFormatting` as raw strings (preserved for
+ *     byte-stable round-trip).
+ *   - The render/cascade layer calls `resolveThemeColorHex(rPr, theme)`
+ *     to collapse the reference to the actual hex colour the browser
+ *     should paint. The original fields stay intact so export still
+ *     round-trips the theme reference (not the computed hex).
+ *
+ * Lane 3 L2.c. Mirrors LibreOffice's `Color::ApplyTintOrShade` at
+ * `vendor/libreoffice/include/tools/color.hxx:200-240` (shape only; no
+ * code copied — our implementation is pure TypeScript against the
+ * ECMA-376 formulae).
+ *
+ * **Scope boundary:** this resolver handles the standard tint/shade
+ * pair. Theme-color-mapping (clrSchemeMapping — how "accent1" maps to a
+ * different `<w:clrScheme>` slot in older Word versions) is NOT applied
+ * here — `resolveThemeColor` from `src/io/ooxml/parse-theme.ts` is the
+ * authoritative slot→hex lookup and future work will layer scheme
+ * mapping into it.
+ */
+
+import type { CanonicalRunFormatting, ResolvedTheme } from "../model/canonical-document.ts";
+import { resolveThemeColor } from "../io/ooxml/parse-theme.ts";
+
+/**
+ * Collapse `<w:color>`-style theme-slot + tint + shade references into a
+ * single resolved hex colour. Returns:
+ *   - the raw `colorHex` as-is when it's a direct hex (the theme fields
+ *     are ignored because direct colour wins per ECMA-376 cascade).
+ *   - `"auto"` when the source declared `w:color w:val="auto"` (sentinel
+ *     kept verbatim per our long-standing A.9 round-trip rule).
+ *   - the theme slot's hex — tint/shade applied — when the source
+ *     declared `w:themeColor="accent1"` etc. and the theme is available.
+ *   - `undefined` otherwise (no colour declared, or theme slot absent).
+ */
+export function resolveThemeColorHex(
+  rPr: Pick<
+    CanonicalRunFormatting,
+    "colorHex" | "colorThemeSlot" | "colorThemeTint" | "colorThemeShade"
+  >,
+  theme: ResolvedTheme | undefined,
+): string | undefined {
+  if (rPr.colorHex === "auto") return "auto";
+  if (rPr.colorHex) return rPr.colorHex;
+  if (!rPr.colorThemeSlot) return undefined;
+
+  const baseHex = resolveThemeColor(theme, rPr.colorThemeSlot);
+  if (!baseHex) return undefined;
+
+  return applyThemeTintShade(baseHex, rPr.colorThemeTint, rPr.colorThemeShade);
+}
+
+/**
+ * Apply `w:themeTint` (shift toward white) and/or `w:themeShade` (shift
+ * toward black) to a base hex colour. Pure function.
+ *
+ * Tint/shade are each a 0x00–0xFF hex byte representing a fraction of
+ * 255 (ECMA-376 §17.18.85 / §17.18.83). Only one may be present per
+ * `<w:color>`; when both are omitted, the base hex is returned.
+ *
+ * Formulae (per Microsoft's Word/OOXML guidance mirrored in LibreOffice):
+ *   - tint byte T → frac = T / 255; newL = frac * L + (1 - frac) * 1.0
+ *     (at T=0 the colour becomes pure white; at T=255 it stays unchanged)
+ *   - shade byte S → frac = S / 255; newL = frac * L
+ *     (at S=0 the colour becomes pure black; at S=255 it stays unchanged)
+ *
+ * These are LUMINANCE modulations in the HSL colour space (hue + saturation
+ * preserved). The conversion hex → HSL → hex is the standard 0–1 / 0–360
+ * form.
+ */
+export function applyThemeTintShade(
+  baseHex: string,
+  tint: string | undefined,
+  shade: string | undefined,
+): string {
+  const tintByte = parseHexByte(tint);
+  const shadeByte = parseHexByte(shade);
+  if (tintByte === undefined && shadeByte === undefined) {
+    return baseHex;
+  }
+
+  const rgb = parseHexColor(baseHex);
+  if (!rgb) return baseHex;
+
+  const hsl = rgbToHsl(rgb);
+  let newL = hsl.l;
+  if (tintByte !== undefined) {
+    const frac = tintByte / 255;
+    newL = frac * hsl.l + (1 - frac);
+  } else if (shadeByte !== undefined) {
+    const frac = shadeByte / 255;
+    newL = frac * hsl.l;
+  }
+  newL = Math.max(0, Math.min(1, newL));
+
+  const out = hslToRgb({ h: hsl.h, s: hsl.s, l: newL });
+  return formatHexColor(out);
+}
+
+function parseHexByte(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const n = Number.parseInt(value, 16);
+  if (!Number.isFinite(n)) return undefined;
+  return Math.max(0, Math.min(255, n));
+}
+
+function parseHexColor(hex: string): { r: number; g: number; b: number } | undefined {
+  const normalized = hex.replace(/^#/u, "").trim();
+  if (normalized.length !== 6) return undefined;
+  const n = Number.parseInt(normalized, 16);
+  if (!Number.isFinite(n)) return undefined;
+  return {
+    r: (n >> 16) & 0xff,
+    g: (n >> 8) & 0xff,
+    b: n & 0xff,
+  };
+}
+
+function formatHexColor(rgb: { r: number; g: number; b: number }): string {
+  const to2 = (n: number): string => Math.round(n).toString(16).padStart(2, "0").toUpperCase();
+  return `${to2(rgb.r)}${to2(rgb.g)}${to2(rgb.b)}`;
+}
+
+function rgbToHsl(rgb: { r: number; g: number; b: number }): {
+  h: number;
+  s: number;
+  l: number;
+} {
+  const r = rgb.r / 255;
+  const g = rgb.g / 255;
+  const b = rgb.b / 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  let h = 0;
+  let s = 0;
+  if (max !== min) {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    switch (max) {
+      case r:
+        h = ((g - b) / d + (g < b ? 6 : 0)) * 60;
+        break;
+      case g:
+        h = ((b - r) / d + 2) * 60;
+        break;
+      default:
+        h = ((r - g) / d + 4) * 60;
+    }
+  }
+  return { h, s, l };
+}
+
+function hslToRgb(hsl: { h: number; s: number; l: number }): {
+  r: number;
+  g: number;
+  b: number;
+} {
+  const { h, s, l } = hsl;
+  if (s === 0) {
+    const gray = l * 255;
+    return { r: gray, g: gray, b: gray };
+  }
+  const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+  const p = 2 * l - q;
+  const hueToRgb = (t: number): number => {
+    let tt = t;
+    if (tt < 0) tt += 1;
+    if (tt > 1) tt -= 1;
+    if (tt < 1 / 6) return p + (q - p) * 6 * tt;
+    if (tt < 1 / 2) return q;
+    if (tt < 2 / 3) return p + (q - p) * (2 / 3 - tt) * 6;
+    return p;
+  };
+  const hFrac = h / 360;
+  return {
+    r: hueToRgb(hFrac + 1 / 3) * 255,
+    g: hueToRgb(hFrac) * 255,
+    b: hueToRgb(hFrac - 1 / 3) * 255,
+  };
+}

package/src/runtime/workflow-markup.ts

@@ -22,6 +22,7 @@ import type {
   WorkflowCommentMarkup,
 } from "../api/public-types";
 import { MAIN_STORY_TARGET } from "../core/selection/mapping.ts";
+import { createPublicRangeAnchor } from "../core/selection/anchor-conversion.ts";
 import {
   projectSurfaceText,
   searchProjectedSurfaceText,
@@ -145,7 +146,7 @@ export function collectWorkflowMarkupSnapshot(input: {
         markupId: `protected-range:${range.rangeId}`,
         kind: "protected_range",
         rangeId: range.rangeId,
-        anchor: createRangeAnchor(range.start, range.end),
+        anchor: createPublicRangeAnchor(range.start, range.end),
         storyTarget: MAIN_STORY_TARGET,
         label: `Protected range ${range.rangeId}`,
         excerpt: range.enforcementReason,
@@ -283,7 +284,7 @@ function collectSurfaceMarkup(
       kind: "opaque_fragment",
       fragmentId: block.fragmentId,
       warningId: block.warningId,
-      anchor: createRangeAnchor(block.from, block.to),
+      anchor: createPublicRangeAnchor(block.from, block.to),
       storyTarget,
       label: block.label,
       excerpt: block.detail,
@@ -308,7 +309,7 @@ function collectSegmentMarkup(
     highlights.push({
       markupId: `highlight:${storyTargetKey(storyTarget)}:${segment.from}:${segment.to}:${segment.markAttrs.backgroundColor}`,
       kind: "highlight",
-      anchor: createRangeAnchor(segment.from, segment.to),
+      anchor: createPublicRangeAnchor(segment.from, segment.to),
       storyTarget,
       label: `Highlight ${segment.markAttrs.backgroundColor}`,
       excerpt: segment.text,
@@ -326,7 +327,7 @@ function collectSegmentMarkup(
       kind: "opaque_fragment",
       fragmentId: segment.fragmentId,
       warningId: segment.warningId,
-      anchor: createRangeAnchor(segment.from, segment.to),
+      anchor: createPublicRangeAnchor(segment.from, segment.to),
       storyTarget,
       label: segment.label,
       excerpt: segment.detail,
@@ -380,7 +381,7 @@ function collectFieldMarkup(
           {
             markupId: `field:${field.index}`,
             kind: "field",
-            anchor: createRangeAnchor(match.from, match.to),
+            anchor: createPublicRangeAnchor(match.from, match.to),
             storyTarget: story.storyTarget,
             label: displayText,
             excerpt: field.instruction,
@@ -417,7 +418,7 @@ function collectOpaqueFragmentMarkup(
         kind: "opaque_fragment",
         fragmentId: fragment.fragmentId,
         warningId: fragment.warningId,
-        anchor: createRangeAnchor(fragment.lastKnownRange.from, fragment.lastKnownRange.to),
+        anchor: createPublicRangeAnchor(fragment.lastKnownRange.from, fragment.lastKnownRange.to),
         storyTarget: MAIN_STORY_TARGET,
         label: descriptor.label,
         excerpt: descriptor.detail,
@@ -427,18 +428,6 @@ function collectOpaqueFragmentMarkup(
     });
 }
 
-function createRangeAnchor(from: number, to: number): EditorAnchorProjection {
-  return {
-    kind: "range",
-    from,
-    to,
-    assoc: {
-      start: -1,
-      end: 1,
-    },
-  };
-}
-
 function storyTargetKey(storyTarget: EditorStoryTarget): string {
   switch (storyTarget.kind) {
     case "main":

package/src/ui/WordReviewEditor.tsx

@@ -75,6 +75,7 @@ import type {
   ZoomLevel,
 } from "../api/public-types";
 import { MetadataResolverMissingError } from "../api/public-types";
+import { readHarnessDebugPortsFlag } from "../internal/harness-debug-ports.ts";
 import type { ScopeMetadataResolver } from "../api/scope-metadata-resolver-types.ts";
 import {
   editorSessionStateFromPersistedSnapshot,
@@ -178,6 +179,7 @@ import {
   useRuntimeSnapshotSlice,
   useRuntimeValue,
 } from "./runtime-snapshot-selectors.ts";
+import { computeEffectiveShowUnsupportedPreviews } from "./unsupported-previews-policy.ts";
 import type { MarkupDisplay } from "./headless/comment-decoration-model";
 import { resolveScopedChromePolicy } from "./headless/scoped-chrome-policy";
 import type {
@@ -484,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),
@@ -779,6 +782,9 @@ export function __createWordReviewEditorRefBridge(
     clearWorkflowOverlay: () => {
       runtime.clearWorkflowOverlay();
     },
+    setSharedWorkflowState: (state) => {
+      runtime.setSharedWorkflowState(state === null ? null : clonePublicValue(state));
+    },
     getWorkflowScopeSnapshot: () => {
       return clonePublicValue(runtime.getWorkflowScopeSnapshot());
     },
@@ -1036,7 +1042,8 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       chromePreset,
       chromeOptions,
       markupDisplay,
-      showUnsupportedObjectPreviews = false,
+      __harnessDebugPorts,
+      unsupportedPreviewsPolicy = "never",
       onError,
       onEvent,
       onWarning,
@@ -1470,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,
@@ -1825,6 +1833,9 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         clearWorkflowOverlay: () => {
           activeRuntime.clearWorkflowOverlay();
         },
+        setSharedWorkflowState: (state) => {
+          activeRuntime.setSharedWorkflowState(state === null ? null : clonePublicValue(state));
+        },
         getWorkflowScopeSnapshot: () => {
           return clonePublicValue(activeRuntime.getWorkflowScopeSnapshot());
         },
@@ -2938,6 +2949,13 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       },
     });
 
+    const harnessShowUnsupportedPreviews = readHarnessDebugPortsFlag(__harnessDebugPorts, "unsupportedObjectPreviews");
+    const effectiveShowUnsupportedPreviews = computeEffectiveShowUnsupportedPreviews({
+      harnessShowUnsupportedPreviews,
+      unsupportedPreviewsPolicy,
+      reviewMode,
+    });
+
     const documentElement = (
       <EditorSurfaceController
         ref={surfaceRef}
@@ -2948,7 +2966,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         documentNavigation={documentNavigation}
         reviewMode={reviewMode}
         markupDisplay={liveMarkupDisplay}
-        showUnsupportedObjectPreviews={showUnsupportedObjectPreviews}
+        showUnsupportedObjectPreviews={effectiveShowUnsupportedPreviews}
         activeRevisionId={activeRevisionId}
         activeSelectionToolKind={activeSelectionTool?.kind ?? null}
         showTrackedChanges={showTrackedChanges}

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

@@ -44,6 +44,7 @@ import {
   loadDocxEditorSession,
   loadDocxEditorSessionAsync,
 } from "../io/docx-session.ts";
+import { tryReadLaycacheEnvelope } from "../runtime/prerender/customxml-probe.ts";
 import {
   createLoadScheduler,
   type LoadScheduler,
@@ -79,6 +80,14 @@ export interface ResolvedSource {
    * does the classic synchronous load.
    */
   preloadedDocxSession?: ReturnType<typeof loadDocxEditorSession>;
+  /**
+   * L7 Phase 2.7 — when the editor-runtime-boundary probe finds a
+   * laycache envelope in `/customXml/item1.xml`, its `graph` is stashed
+   * here and forwarded to `createDocumentRuntime` as `seedLayoutCache`.
+   * This is the Plan A (graph-seed) win layered on top of the Plan B
+   * (loader short-circuit) win. Undefined when no envelope is available.
+   */
+  preloadedLaycacheGraph?: import("../runtime/layout/page-graph.ts").RuntimePageGraph;
 }
 
 export interface CreateRuntimeArgs {
@@ -404,6 +413,18 @@ export function useEditorRuntimeBoundary(
         // can paint the skeleton while the rest of the parse finishes.
         // SSR / Node tests fall through to the synchronous load inside
         // `createRuntime`.
+        //
+        // L7 Phase 2.7 — Plan B read-path wiring. Before invoking the
+        // async loader, probe the docx for a laycache envelope stashed
+        // in `/customXml/item1.xml` (shipped by Plan B Slice 2). When the
+        // probe returns a validated envelope, pass it to the loader so
+        // the five expensive parse stages short-circuit against the
+        // cached `canonicalDocument`. Measured win on 138-pp extra-large
+        // CCEP: ~947 ms cold → ~590 ms warm (Δ 376 ms), same delta the
+        // Node-side `prerender-cache.bench.ts` records. Probe is ~20–50 ms;
+        // `tryReadLaycacheEnvelope` returns null on any rejection path
+        // (missing part, stale structural hash, schema mismatch) and the
+        // loader falls through to the full parse.
         if (
           source.initialDocx !== undefined &&
           source.preloadedDocxSession === undefined &&
@@ -411,12 +432,20 @@ export function useEditorRuntimeBoundary(
         ) {
           const scheduler = createLoadScheduler();
           loadSchedulerRef.current = scheduler;
+          const probeResult = await tryReadLaycacheEnvelope(source.initialDocx);
+          if (cancelled) {
+            scheduler.dispose();
+            loadSchedulerRef.current = null;
+            return;
+          }
+          recordPerfSample("loadSession.laycacheProbe");
           const preloaded = await loadDocxEditorSessionAsync({
             documentId,
             sourceLabel: source.sourceLabel,
             bytes: source.initialDocx,
             editorBuild: "dev",
             scheduler,
+            ...(probeResult ? { laycacheEnvelope: probeResult.envelope } : {}),
           });
           if (cancelled) {
             scheduler.dispose();
@@ -424,6 +453,9 @@ export function useEditorRuntimeBoundary(
             return;
           }
           source.preloadedDocxSession = preloaded;
+          if (probeResult) {
+            source.preloadedLaycacheGraph = probeResult.envelope.graph;
+          }
         }
 
         const nextRuntime = createRuntime(
@@ -662,6 +694,9 @@ function createRuntime(
     editorBuild: runtimeSessionState.editorBuild,
     fatalError: docxSession?.fatalError,
     protectionSnapshot: docxSession?.protectionSnapshot,
+    ...(args.source.preloadedLaycacheGraph
+      ? { seedLayoutCache: args.source.preloadedLaycacheGraph }
+      : {}),
     exportDocx: async (sessionState, options) => {
       if (docxSession) {
         return docxSession.exportDocx(sessionState, options);
@@ -877,6 +912,7 @@ function createLoadingRuntimeBridge(input: {
     getCanonicalDocument: () => input.sessionState.canonicalDocument,
     getSourcePackage: () => input.sessionState.sourcePackage,
     replaceText: () => undefined,
+    insertFragment: () => undefined,
     applyActiveStoryTextCommand: () => ({
       kind: "rejected",
       newRevisionToken: "",
@@ -965,6 +1001,7 @@ function createLoadingRuntimeBridge(input: {
       Promise.reject(createLoadingBoundaryError(input.snapshot.documentId, "export")),
     setWorkflowOverlay: () => undefined,
     clearWorkflowOverlay: () => undefined,
+    setSharedWorkflowState: () => undefined,
     getWorkflowOverlay: () => null,
     getWorkflowScopeSnapshot: () => null,
     getInteractionGuardSnapshot: () => ({ effectiveMode: "edit", blockedReasons: [] }),

package/src/ui/headless/selection-helpers.ts

@@ -1,31 +1,22 @@
 import type { SelectionSnapshot } from "../../api/public-types";
+import {
+  createPublicNodeAnchor,
+  createPublicRangeAnchor,
+} from "../../core/selection/anchor-conversion.ts";
 
 /**
  * Headless-UI-side `createSelectionSnapshot` that produces the **public**
- * `EditorAnchorProjection` shape (top-level `from`/`to`). The runtime-facing
- * twin at `src/core/state/editor-state.ts` produces the internal
- * `RangeAnchor` shape (`range: { from, to }`). The two are *not*
- * interchangeable — they serve different type contracts. See the
- * `EditorAnchorProjection` definitions in `src/api/public-types.ts` vs
- * `src/core/selection/mapping.ts`. Do not merge without first unifying
- * those two definitions.
+ * `EditorAnchorProjection` shape via the canonical
+ * `createPublicRangeAnchor` constructor. The runtime-facing twin at
+ * `src/core/state/editor-state.ts` produces the internal `RangeAnchor`
+ * shape (`range: { from, to }`) — the two are not interchangeable.
  */
 export function createSelectionSnapshot(anchor: number, head = anchor): SelectionSnapshot {
-  const from = Math.min(anchor, head);
-  const to = Math.max(anchor, head);
   return {
     anchor,
     head,
     isCollapsed: anchor === head,
-    activeRange: {
-      kind: "range",
-      from,
-      to,
-      assoc: {
-        start: -1,
-        end: 1,
-      },
-    },
+    activeRange: createPublicRangeAnchor(anchor, head),
   };
 }
 
@@ -34,11 +25,7 @@ export function createNodeSelectionSnapshot(at: number, assoc: -1 | 1 = 1): Sele
     anchor: at,
     head: at,
     isCollapsed: true,
-    activeRange: {
-      kind: "node",
-      at,
-      assoc,
-    },
+    activeRange: createPublicNodeAnchor(at, assoc),
   };
 }
 

package/src/ui/unsupported-previews-policy.ts

@@ -0,0 +1,23 @@
+/**
+ * I4 — Effective-visibility rule for preserve-only previews.
+ *
+ * Combines the harness-only opaque-token flag (from
+ * `__harnessDebugPorts`, read via `readHarnessDebugPortsFlag(..., "unsupportedObjectPreviews")`)
+ * with the public sibling `unsupportedPreviewsPolicy` prop (default
+ * `"never"`). The harness token remains unreachable from consumer
+ * apps (see `test/ui/unsupported-previews-invariant.test.ts`).
+ */
+export interface EffectiveShowUnsupportedPreviewsInput {
+  harnessShowUnsupportedPreviews: boolean;
+  unsupportedPreviewsPolicy: "never" | "review-only" | "always";
+  reviewMode: "editing" | "review";
+}
+
+export function computeEffectiveShowUnsupportedPreviews(
+  input: EffectiveShowUnsupportedPreviewsInput,
+): boolean {
+  if (input.harnessShowUnsupportedPreviews === true) return true;
+  if (input.unsupportedPreviewsPolicy === "always") return true;
+  if (input.unsupportedPreviewsPolicy === "review-only" && input.reviewMode === "review") return true;
+  return false;
+}

package/src/ui-tailwind/chrome-overlay/tw-chrome-overlay.tsx

@@ -152,6 +152,14 @@ export interface TwChromeOverlayProps {
    * handle leaves focus-restore as a no-op — DOM reparent still runs.
    */
   pmView?: PmPortalView | null;
+  /**
+   * L7 Phase 2.8 — viewport cull for `TwPageStackChromeLayer`. Sequential
+   * page-index range (plus overscan) that should render full chrome
+   * bands; pages outside the range render empty frame wrappers only.
+   * When omitted, every page's chrome mounts (pre-Phase-2.8 behavior).
+   * See `useVisiblePageIndexRange` in `src/ui-tailwind/page-stack/use-visible-block-range.ts`.
+   */
+  visiblePageIndexRange?: { start: number; end: number } | null;
 }
 
 /**
@@ -188,6 +196,7 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
   onOpenStory,
   pmSurfaceElement,
   pmView,
+  visiblePageIndexRange,
 }) => {
   return (
     <div
@@ -211,6 +220,7 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
           onOpenStory={onOpenStory}
           pmSurfaceElement={pmSurfaceElement}
           pmView={pmView}
+          visiblePageIndexRange={visiblePageIndexRange ?? null}
         />
       ) : null}
       <TwScopeRailLayer

package/src/ui-tailwind/editor-surface/perf-probe.ts

@@ -5,6 +5,7 @@ export type PerfProbeKind =
   | "typing.divergence"
   | "selection"
   | "runtime.create"
+  | "loadSession.laycacheProbe"
   | "snapshot.surface"
   | "snapshot.compatibility"
   | "snapshot.navigation"

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?.(