@beyondwork/docx-react-component 1.0.66 → 1.0.69

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

@@ -0,0 +1,186 @@
+/**
+ * Phase Q — Debug overlay.
+ *
+ * Full-screen tabbed panel shown when
+ * `WordReviewEditorProps.debugMode === "full"`.  Renders the top bar
+ * (reused from `tw-debug-top-bar.tsx`) + three content panes:
+ *
+ *   - **Inspector** — pretty-prints the bound `DebugInspectorSnapshot`
+ *     (canonical / layout / geometry / scope / review / diagnostics
+ *     JSON, same shape the Railway debug service renders).
+ *   - **Events** — tail of the last N events on the `api`, `render`,
+ *     `command`, `commit`, `collab`, `layout` channels the runtime
+ *     projector ships (`DebugBus`).  Populated on arrival via the
+ *     `events` prop.
+ *   - **REPL** — stub in this slice.  Operators type into the textarea
+ *     and the host-provided `onReplEval` receives the source.  Full
+ *     in-scope `api` / `runtime` / `debug` handles land in the Phase Q
+ *     follow-up alongside localStorage history.
+ *
+ * Slice 7 ships the visible scaffolding + the visibility invariant;
+ * the REPL evaluator + the deeper event-tail filters are follow-up
+ * work tracked under the refactor/11 plan.
+ */
+
+import React, { useState } from "react";
+
+import { TwDebugTopBar, type TwDebugTopBarProps } from "./tw-debug-top-bar.tsx";
+
+type DebugOverlayTab = "inspector" | "events" | "repl";
+
+export interface TwDebugOverlayProps {
+  sessionId: string | null;
+  snapshot: TwDebugTopBarProps["snapshot"];
+  /**
+   * Raw `DebugInspectorSnapshot` the host wired through
+   * `ui.debug.attach()`.  Rendered as pretty-printed JSON in the
+   * Inspector pane.  Large snapshots are clipped to the first 16 KB
+   * to keep the DOM responsive.
+   */
+  inspectorJson?: unknown;
+  /**
+   * Ring-buffered events flowing through the runtime's `DebugBus`.
+   * Each entry is rendered as `channel · kind · t` with a collapsible
+   * details row for the payload.
+   */
+  events?: ReadonlyArray<{
+    readonly channel: string;
+    readonly kind: string;
+    readonly t: number;
+    readonly payload?: unknown;
+  }>;
+  /** Invoked when the operator submits text from the REPL pane. */
+  onReplEval?: (source: string) => void;
+  /** Collapses the overlay back to `"top-bar"` mode. */
+  onCollapse?: () => void;
+}
+
+const MAX_INSPECTOR_BYTES = 16 * 1024;
+
+function formatInspector(json: unknown): string {
+  if (json === undefined || json === null) return "(no snapshot bound)";
+  try {
+    const s = JSON.stringify(json, null, 2);
+    if (s.length > MAX_INSPECTOR_BYTES) {
+      return `${s.slice(0, MAX_INSPECTOR_BYTES)}\n… [clipped ${s.length - MAX_INSPECTOR_BYTES} bytes]`;
+    }
+    return s;
+  } catch (err) {
+    return `(snapshot serialization failed: ${(err as Error).message})`;
+  }
+}
+
+export function TwDebugOverlay(props: TwDebugOverlayProps): React.ReactElement {
+  const [tab, setTab] = useState<DebugOverlayTab>("inspector");
+  const [replInput, setReplInput] = useState("");
+
+  const tabBtn = (id: DebugOverlayTab, label: string) => (
+    <button
+      key={id}
+      type="button"
+      onClick={() => setTab(id)}
+      data-state={tab === id ? "active" : "inactive"}
+      data-testid={`tw-debug-overlay__tab-${id}`}
+      className={`inline-flex h-6 items-center rounded-[var(--radius-sm)] px-2 text-[11px] font-medium transition-colors ${
+        tab === id
+          ? "bg-[var(--color-accent-primary)]/12 text-[var(--color-accent-primary)]"
+          : "text-[var(--color-text-secondary)] hover:bg-[var(--color-bg-hover)] hover:text-[var(--color-text-primary)]"
+      }`}
+    >
+      {label}
+    </button>
+  );
+
+  return (
+    <div
+      className="fixed bottom-0 left-0 right-0 z-40 flex max-h-[48vh] flex-col border-t border-[var(--color-border-subtle)] bg-[var(--color-bg-canvas)] shadow-[var(--shadow-float)]"
+      data-testid="tw-debug-overlay"
+      data-debug-mode="full"
+      role="region"
+      aria-label="Editor debug overlay"
+    >
+      <TwDebugTopBar
+        sessionId={props.sessionId}
+        snapshot={props.snapshot}
+        {...(props.onCollapse ? { onExpand: props.onCollapse } : {})}
+      />
+      <div
+        className="flex shrink-0 items-center gap-1 border-b border-[var(--color-border-subtle)] bg-[var(--color-bg-chrome)]/80 px-3 py-1"
+        role="tablist"
+        aria-label="Debug panes"
+      >
+        {tabBtn("inspector", "Inspector")}
+        {tabBtn("events", "Events")}
+        {tabBtn("repl", "REPL")}
+      </div>
+      <div
+        className="flex-1 overflow-auto px-3 py-2 text-[11px]"
+        data-testid={`tw-debug-overlay__pane-${tab}`}
+      >
+        {tab === "inspector" ? (
+          <pre className="whitespace-pre-wrap font-mono text-[11px] leading-[1.45] text-[var(--color-text-primary)]">
+            {formatInspector(props.inspectorJson)}
+          </pre>
+        ) : null}
+        {tab === "events" ? (
+          <ul className="flex flex-col gap-0.5 font-mono text-[10px] text-[var(--color-text-secondary)]">
+            {(props.events ?? []).length === 0 ? (
+              <li className="italic text-[var(--color-text-tertiary)]">
+                (no events — wire `ui.debug.attach()` with a DebugBus listener)
+              </li>
+            ) : (
+              props.events!.slice(-200).map((e, i) => (
+                <li
+                  key={`${e.t}-${i}`}
+                  className="border-b border-[var(--color-border-subtle)]/60 py-0.5"
+                >
+                  <span className="text-[var(--color-accent-primary)]">{e.channel}</span>
+                  {" · "}
+                  <span className="text-[var(--color-text-primary)]">{e.kind}</span>
+                  {" · "}
+                  <span className="text-[var(--color-text-tertiary)]">
+                    t={Math.round(e.t)}
+                  </span>
+                </li>
+              ))
+            )}
+          </ul>
+        ) : null}
+        {tab === "repl" ? (
+          <form
+            onSubmit={(ev) => {
+              ev.preventDefault();
+              if (replInput.trim().length === 0) return;
+              props.onReplEval?.(replInput);
+              setReplInput("");
+            }}
+            className="flex flex-col gap-2"
+          >
+            <textarea
+              value={replInput}
+              onChange={(ev) => setReplInput(ev.target.value)}
+              placeholder="// Phase Q REPL — follow-up slice will provide in-scope `api` / `runtime` / `debug` handles + localStorage history."
+              className="min-h-[120px] w-full resize-y rounded-[var(--radius-sm)] border border-[var(--color-border-default)] bg-[var(--color-bg-muted)] px-2 py-1 font-mono text-[11px] text-[var(--color-text-primary)] outline-none focus-visible:border-[var(--color-accent-primary)]"
+              data-testid="tw-debug-overlay__repl-input"
+            />
+            <div className="flex items-center justify-between">
+              <span className="text-[10px] text-[var(--color-text-tertiary)]">
+                {props.onReplEval
+                  ? "Submit (Enter or click Run) invokes the host's onReplEval."
+                  : "Host has not wired onReplEval — input is inert."}
+              </span>
+              <button
+                type="submit"
+                disabled={!props.onReplEval || replInput.trim().length === 0}
+                className="inline-flex h-6 items-center rounded-[var(--radius-sm)] bg-[var(--color-accent-primary)] px-3 text-[11px] font-semibold text-[var(--color-text-on-accent)] transition-colors hover:bg-[var(--color-accent-primary-hover)] disabled:opacity-40"
+                data-testid="tw-debug-overlay__repl-submit"
+              >
+                Run
+              </button>
+            </div>
+          </form>
+        ) : null}
+      </div>
+    </div>
+  );
+}

package/src/ui-tailwind/debug/tw-debug-presentation.tsx

@@ -0,0 +1,80 @@
+/**
+ * Phase Q — DebugMode router.
+ *
+ * Single mount point `WordReviewEditor.tsx` consumes.  Picks between
+ * the minimal top-bar, the full overlay, or nothing depending on the
+ * public `debugMode` prop.  Keeping the router in one file means the
+ * invariant test + CI guard can target a single surface.
+ *
+ * Data flow (consumers wire through `ui.debug.attach()` per refactor/10
+ * Slice 5):
+ *
+ *   host → `ui.debug.attach({ id, channels })` →
+ *           controller.attachDebug(session) →
+ *             { sessionId, snapshot, events } → this component
+ *
+ * Slice 7 ships the visibility scaffold; the full REPL + event-tail
+ * wiring to `runtime.debug.bus` + `DebugInspectorSnapshot` lives in a
+ * follow-up (see `src/ui-tailwind/debug/README.md`).
+ */
+
+import React from "react";
+
+import type { DebugMode } from "../../api/public-types.ts";
+import { TwDebugTopBar, type TwDebugTopBarProps } from "./tw-debug-top-bar.tsx";
+import { TwDebugOverlay, type TwDebugOverlayProps } from "./tw-debug-overlay.tsx";
+
+export interface TwDebugPresentationProps {
+  mode: DebugMode;
+  /**
+   * Debug session id — mirrors what the host passed into
+   * `ui.debug.attach({ id })`.  `null` when no attachment is active.
+   */
+  sessionId?: string | null;
+  snapshot?: TwDebugTopBarProps["snapshot"];
+  inspectorJson?: TwDebugOverlayProps["inspectorJson"];
+  events?: TwDebugOverlayProps["events"];
+  onReplEval?: TwDebugOverlayProps["onReplEval"];
+  /**
+   * Optional override for the mode toggle — host supplies when it
+   * owns the `debugMode` state (e.g. harness with a keyboard shortcut).
+   */
+  onModeChange?: (next: DebugMode) => void;
+}
+
+export function TwDebugPresentation(
+  props: TwDebugPresentationProps,
+): React.ReactElement | null {
+  if (props.mode === "off") return null;
+
+  const sessionId = props.sessionId ?? null;
+  const snapshot = props.snapshot ?? null;
+
+  if (props.mode === "top-bar") {
+    return (
+      <TwDebugTopBar
+        sessionId={sessionId}
+        snapshot={snapshot}
+        {...(props.onModeChange
+          ? { onExpand: () => props.onModeChange!("full") }
+          : {})}
+      />
+    );
+  }
+
+  // mode === "full"
+  return (
+    <TwDebugOverlay
+      sessionId={sessionId}
+      snapshot={snapshot}
+      {...(props.inspectorJson !== undefined
+        ? { inspectorJson: props.inspectorJson }
+        : {})}
+      {...(props.events ? { events: props.events } : {})}
+      {...(props.onReplEval ? { onReplEval: props.onReplEval } : {})}
+      {...(props.onModeChange
+        ? { onCollapse: () => props.onModeChange!("top-bar") }
+        : {})}
+    />
+  );
+}

package/src/ui-tailwind/debug/tw-debug-top-bar.tsx

@@ -0,0 +1,83 @@
+/**
+ * Phase Q — Debug top bar.
+ *
+ * Minimal always-on status strip shown when
+ * `WordReviewEditorProps.debugMode === "top-bar"` (or as the header of
+ * the "full" overlay).  Renders the bound debug session id + a small
+ * set of counters derived from the `DebugInspectorSnapshot` the host
+ * supplies through `ui.debug.attach()` wiring.
+ *
+ * Slice 7 ships the minimal surface; the REPL + event-tail panes live
+ * in `tw-debug-overlay.tsx` (full mode only).  Future telemetry (scope
+ * count, invalidation counter, channel activity) plugs in through
+ * `snapshot` without changing the public prop.
+ */
+
+import React from "react";
+
+export interface TwDebugTopBarProps {
+  /**
+   * The debug-session id the host passed into `ui.debug.attach()`.
+   * Shown verbatim so operators can correlate with Railway debug-
+   * service logs.  `null` when no attachment is active.
+   */
+  sessionId: string | null;
+  /**
+   * Lightweight counters sourced from `DebugInspectorSnapshot`.
+   * `null` means no snapshot has flowed yet.
+   */
+  snapshot: {
+    readonly scopeCount?: number;
+    readonly blockCount?: number;
+    readonly revisionToken?: string;
+  } | null;
+  /**
+   * Optional click handler — the harness can use this to toggle
+   * between `"top-bar"` and `"full"` modes.
+   */
+  onExpand?: () => void;
+}
+
+export function TwDebugTopBar(props: TwDebugTopBarProps): React.ReactElement {
+  const pill = (label: string, value: string | number | undefined | null) =>
+    value === undefined || value === null ? null : (
+      <span
+        key={label}
+        className="inline-flex items-center gap-1 rounded-[var(--radius-sm)] bg-[var(--color-bg-muted)] px-2 py-0.5 text-[10px] font-medium text-[var(--color-text-secondary)]"
+        data-testid={`tw-debug-top-bar__${label.toLowerCase().replace(/\s+/g, "-")}`}
+      >
+        <span className="text-[var(--color-text-tertiary)]">{label}</span>
+        <span className="font-mono text-[var(--color-text-primary)]">{value}</span>
+      </span>
+    );
+
+  return (
+    <div
+      className="flex h-7 shrink-0 items-center gap-2 border-b border-[var(--color-border-subtle)] bg-[var(--color-bg-chrome)]/95 px-3 text-[11px] backdrop-blur-sm"
+      data-testid="tw-debug-top-bar"
+      data-debug-mode="top-bar"
+      role="status"
+      aria-label="Editor debug status bar"
+    >
+      <span className="font-semibold uppercase tracking-[0.14em] text-[var(--color-text-tertiary)]">
+        Debug
+      </span>
+      {pill("session", props.sessionId ?? "(detached)")}
+      {pill("scopes", props.snapshot?.scopeCount)}
+      {pill("blocks", props.snapshot?.blockCount)}
+      {props.snapshot?.revisionToken
+        ? pill("rev", props.snapshot.revisionToken.slice(0, 8))
+        : null}
+      {props.onExpand ? (
+        <button
+          type="button"
+          onClick={props.onExpand}
+          className="ml-auto inline-flex h-5 items-center rounded-[var(--radius-sm)] px-1.5 text-[10px] font-medium text-[var(--color-text-secondary)] transition-colors hover:bg-[var(--color-bg-hover)] hover:text-[var(--color-text-primary)]"
+          data-testid="tw-debug-top-bar__expand"
+        >
+          Expand ▾
+        </button>
+      ) : null}
+    </div>
+  );
+}

package/src/ui-tailwind/editor-surface/chart-node-view.tsx

@@ -17,7 +17,7 @@ import { createRoot, type Root } from "react-dom/client";
 import type { Node as PMNode } from "prosemirror-model";
 import type { NodeViewConstructor } from "prosemirror-view";
 import { ChartSurface } from "../chart/ChartSurface.tsx";
-import { chartModelStore } from "../../runtime/chart/chart-model-store.ts";
+import { getChartModel } from "../../api/v3/runtime/chart.ts";
 
 const DEFAULT_WIDTH = 576;
 const DEFAULT_HEIGHT = 336;
@@ -55,7 +55,7 @@ class ChartNodeViewInstance {
       return;
     }
 
-    const entry = chartModelStore.get(parsedChartId);
+    const entry = getChartModel(parsedChartId);
     if (!entry) {
       this._unmountRoot();
       return;

package/src/ui-tailwind/editor-surface/float-wrap-resolver.ts

@@ -18,7 +18,7 @@
  */
 
 import type { SurfaceDrawingAnchor } from "../../api/public-types";
-import { EMU_PER_PX } from "../../runtime/units";
+import { EMU_PER_PX } from "../../api/public-types";
 
 export interface FloatWrapStyle {
   /** CSS `float` value when the anchor wraps inline text. */

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

@@ -12,8 +12,6 @@ import {
   extractPlainTextSegments,
   type PastePlainSegment,
 } from "./paste-plain-text";
-import { parseCanonicalFragmentFromWordML } from "../../io/paste/word-clipboard";
-import { parseCanonicalFragmentFromHtml } from "../../io/paste/html-clipboard";
 import type { PositionMap } from "./pm-position-map";
 
 /**
@@ -243,6 +241,83 @@ export interface CommandBridgeCallbacks extends SelectionSyncCallbacks {
    * lands. When absent, the legacy "block all docChanged" behavior applies.
    */
   gate?: Plugin;
+  /**
+   * Phase C.β — right-click composition hook.
+   *
+   * When wired, fires on `contextmenu` DOM events with the event
+   * coordinates + target; the bridge suppresses the browser-native menu
+   * so the host can mount `TwContextMenu` at the returned coordinates.
+   *
+   * When NOT wired, the bridge leaves the native menu alone so
+   * integrators that haven't opted in retain browser-default behavior
+   * (back-compat).
+   *
+   * Shape deliberately minimal — the host resolves target kind from the
+   * target DOM node, queries the `editor-action-registry`, and renders
+   * the resulting `TwContextMenu`.  The bridge does not import the
+   * registry directly — this preserves the three-actor split (bridge
+   * is surface-layer; registry + composition are chrome-layer).
+   */
+  onContextMenuRequested?: (event: ContextMenuRequestEvent) => void;
+}
+
+export interface ContextMenuRequestEvent {
+  readonly clientX: number;
+  readonly clientY: number;
+  /**
+   * The native `event.target`.  Typically an Element (PM-rendered span,
+   * table cell, image, etc.) but can be a Text node or null.  Callers
+   * must walk to the nearest Element and apply their own target-kind
+   * resolver — see the Phase C.γ `resolveTargetKind(el)` helper once
+   * it ships, or use `target instanceof Element ? target.closest(…) : null`
+   * in the interim.
+   */
+  readonly target: EventTarget | null;
+}
+
+/**
+ * Pure helper used by the bridge's `handleDOMEvents.contextmenu` hook.
+ * Returns `true` when the native menu should be suppressed (i.e. the
+ * host wired a callback); `false` when the bridge lets browser default
+ * take over.
+ *
+ * Exception handling: if the host's callback throws, the error is
+ * logged and the helper returns `false` so PM/browser fall back to
+ * native behavior.  `event.preventDefault()` is called BEFORE the
+ * handler fires (the contract is "host owns the menu now"), but if
+ * the handler throws we still propagate `false` so PM does not
+ * double-suppress — the user at minimum gets no menu rather than a
+ * silent no-op cascade.
+ *
+ * Exported so unit tests can exercise the contextmenu dispatch path
+ * without standing up a full EditorView (the prosemirror-tables
+ * columnResizing plugin requires a tables-aware schema that's
+ * overkill for this contract).
+ */
+export function applyContextMenuEvent(
+  callbacks: CommandBridgeCallbacks,
+  event: MouseEvent,
+): boolean {
+  const handler = callbacks.onContextMenuRequested;
+  if (!handler) return false;
+  try {
+    event.preventDefault();
+    handler({
+      clientX: event.clientX,
+      clientY: event.clientY,
+      target: event.target,
+    });
+    return true;
+  } catch (err) {
+    // Log so integrators can debug; do not re-throw (throwing from a
+    // PM handleDOMEvents returns a truthy value that tells PM the
+    // event was handled, which would then cause PM to swallow it).
+    // Surface `false` so the user still gets native menu as fallback
+    // rather than a silent empty overlay.
+    // eslint-disable-next-line no-console
+    console.error("[pm-command-bridge] onContextMenuRequested threw:", err);
+    return false;
+  }
 }
 
 const bridgeKey = new PluginKey("command-bridge");
@@ -281,9 +356,45 @@ export function createSelectionSyncPlugin(
   });
 }
 
+/**
+ * Result shape from the paste-parser adapters — mirrors the native
+ * `parseCanonicalFragmentFromWordML` / `parseCanonicalFragmentFromHtml`
+ * return so callers don't have to re-map.
+ */
+export type PasteFragmentParseResult =
+  | {
+      readonly ok: true;
+      readonly fragment: import("../../api/public-types.ts").CanonicalDocumentFragment;
+    }
+  | { readonly ok: false; readonly reason?: string };
+
+/**
+ * Host-supplied adapter that turns raw WordML / HTML clipboard payloads
+ * into a `CanonicalDocumentFragment`.  Refactor/11 Slice 5 retires the
+ * PM bridge's direct `io/paste/**` imports: the bridge emits the raw
+ * payload + mime type, the host parses, and fires the resulting
+ * `onPasteFragment` callback.  Hosts that don't supply the adapter fall
+ * through to Tier A plain-text paste, as if `onPasteFragment` was not
+ * wired.
+ */
+export interface PasteFragmentParserAdapter {
+  parseWordML(wordml: string): PasteFragmentParseResult;
+  parseHtml(html: string): PasteFragmentParseResult;
+}
+
 export interface CommandBridgePluginOptions {
   /** P6: when true, omit prosemirror-tables columnResizing() — chrome overlay grips take over. */
   useChromeColumnResizing?: boolean;
+  /**
+   * Slice 5 retirement seam — host-supplied parser adapter for rich
+   * paste (WordML + HTML).  When absent, the bridge does NOT parse
+   * rich clipboard payloads; they fall through to plain-text paste or
+   * `onBlockedInput`.  `WordReviewEditor.tsx` supplies the adapter
+   * wrapping `io/paste/word-clipboard` + `io/paste/html-clipboard`;
+   * headless consumers can plug their own (or omit it to accept
+   * plain-text-only paste).
+   */
+  pasteFragmentParser?: PasteFragmentParserAdapter;
 }
 
 export function createCommandBridgePlugins(
@@ -363,6 +474,13 @@ export function createCommandBridgePlugins(
           dragSourceRange = null;
           return false;
         },
+        // Phase C.β — right-click composition hook.  Returns true to
+        // block the native menu only when the host has wired a callback,
+        // so integrators that haven't opted in still get browser-native
+        // behavior (back-compat).
+        contextmenu(_view, event) {
+          return applyContextMenuEvent(callbacks, event as MouseEvent);
+        },
       },
       handleTextInput(_view, _from, _to, text) {
         if (isComposing) {
@@ -374,7 +492,7 @@ export function createCommandBridgePlugins(
 
       // I2 paste handler — Tier B (WordML) preferred, Tier A (plain) fallback.
       //
-      // Preference order per `docs/plans/lane-1-i2-tier-b-rich-paste.md`:
+      // Preference order per `CLAUDE.md (lane status table)`:
       //   1. Office-clipboard WordprocessingML payload if the host wired
       //      `onPasteFragment` AND the clipboard carries the MIME. Parsed via
       //      `parseCanonicalFragmentFromWordML`.
@@ -417,10 +535,15 @@ export function createCommandBridgePlugins(
         }
 
         // Tier B: WordprocessingML (highest fidelity when available)
-        if (callbacks.onPasteFragment) {
+        // Slice 5 — the bridge no longer imports `io/paste/**` directly;
+        // callers inject `pasteFragmentParser` so rich-paste parsing
+        // lives in the shell (or the host).  Without the adapter, rich
+        // paste falls through to plain text (same as before when
+        // `onPasteFragment` was not wired).
+        if (callbacks.onPasteFragment && options?.pasteFragmentParser) {
           const wordml = readWordMLPayload(clipboard);
           if (wordml) {
-            const parsed = parseCanonicalFragmentFromWordML(wordml);
+            const parsed = options.pasteFragmentParser.parseWordML(wordml);
             if (parsed.ok && parsed.fragment.blocks.length > 0) {
               callbacks.onPasteFragment({ fragment: parsed.fragment, source: "wordml" });
               return true;
@@ -431,10 +554,10 @@ export function createCommandBridgePlugins(
         }
 
         // Tier B: HTML (Google Docs, Word web, Outlook-lite)
-        if (callbacks.onPasteFragment) {
+        if (callbacks.onPasteFragment && options?.pasteFragmentParser) {
           const htmlPayload = clipboard.getData("text/html");
           if (htmlPayload && htmlPayload.trim().length > 0) {
-            const parsed = parseCanonicalFragmentFromHtml(htmlPayload);
+            const parsed = options.pasteFragmentParser.parseHtml(htmlPayload);
             if (parsed.ok && parsed.fragment.blocks.length > 0) {
               callbacks.onPasteFragment({ fragment: parsed.fragment, source: "html" });
               return true;
@@ -479,11 +602,13 @@ export function createCommandBridgePlugins(
           return true;
         }
 
-        // Tier B drop: WordprocessingML fragment
-        if (callbacks.onDropFragment) {
+        // Tier B drop: WordprocessingML fragment — uses the host-
+        // supplied parser adapter (Slice 5 retirement); absent adapter
+        // falls through to plain text.
+        if (callbacks.onDropFragment && options?.pasteFragmentParser) {
           const wordml = readWordMLPayload(dt);
           if (wordml) {
-            const parsed = parseCanonicalFragmentFromWordML(wordml);
+            const parsed = options.pasteFragmentParser.parseWordML(wordml);
             if (parsed.ok && parsed.fragment.blocks.length > 0) {
               const ctrlModifier = Boolean(dragEvent.ctrlKey || dragEvent.metaKey);
               const effect = ctrlModifier ? "copy" : "move";

package/src/ui-tailwind/editor-surface/pm-decorations.ts

@@ -2,8 +2,14 @@ import { Decoration, DecorationSet } from "prosemirror-view";
 
 import type { CommentDecorationModel } from "../../ui/headless/comment-decoration-model";
 import { getCommentHighlightClass, type MarkupDisplay } from "../../ui/headless/comment-decoration-model";
-import type { RevisionDecorationModel } from "../../ui/headless/revision-decoration-model";
-import { getRevisionHighlightClass } from "../../ui/headless/revision-decoration-model";
+import type {
+  RevisionDecorationModel,
+  RevisionDisplayFlags,
+} from "../../ui/headless/revision-decoration-model";
+import {
+  buildClassFromRevisionDisplay,
+  getRevisionHighlightClass,
+} from "../../ui/headless/revision-decoration-model";
 import type {
   EditorAnchorProjection,
   EditorStoryTarget,
@@ -13,7 +19,7 @@ import type {
   WorkflowMetadataMarkup,
   WorkflowScope,
 } from "../../api/public-types";
-import { MAIN_STORY_TARGET, storyTargetsEqual } from "../../core/selection/mapping.ts";
+import { MAIN_STORY_TARGET, storyTargetsEqual } from "../../api/public-types.ts";
 import type { PositionMap } from "./pm-position-map";
 import type { Node as PMNode } from "prosemirror-model";
 
@@ -313,6 +319,14 @@ export function buildDecorations(
   activeWorkflowWorkItemIdOrScopeIds?: string | null | readonly string[],
   activeWorkflowScopeIdsOrMetadata?: readonly string[] | readonly WorkflowMetadataMarkup[],
   workflowMetadata?: readonly WorkflowMetadataMarkup[],
+  // §4.3 — Track B integration. When the caller threads an offset →
+  // `SurfaceInlineSegment.revisionDisplay` map (pre-computed from
+  // `snapshot.surfaceInlineSegments`), the revision-decoration loop
+  // reads the L03-authoritative display flags instead of re-deriving
+  // from the review-store side channel via `getRevisionHighlightClass`.
+  // Consumers without a live surface-segment stream (headless / legacy
+  // callers) omit this argument and keep the pre-Track-B behavior.
+  revisionDisplayByOffset?: ReadonlyMap<number, RevisionDisplayFlags>,
 ): DecorationSet {
   const isStoryTarget = (value: unknown): value is EditorStoryTarget =>
     Boolean(value) &&
@@ -408,10 +422,17 @@ export function buildDecorations(
   // Visual styling (underlines, colors) only applies when showTrackedChanges is on.
   if (revisionModel) {
     for (const rev of revisionModel.revisions) {
-      // Always hide deletions in clean mode (final-text semantics).
-      // This is the critical behavior: "hide tracked changes" must show
-      // the document as if accepted, not show deleted text as kept text.
-      if (markupDisplay === "clean" && rev.kind === "deletion") {
+      // §4.4 — L03's `revisionDisplay.hidden` is the authoritative hide
+      // signal when the caller threads the offset map. When absent, fall
+      // back to the pre-L03 `markupDisplay === "clean" && deletion` rule
+      // so legacy / headless callers keep their final-text semantics.
+      const revDisplayFlags = revisionDisplayByOffset?.get(rev.from);
+      const hideAsDeletion =
+        rev.kind === "deletion" &&
+        (revDisplayFlags
+          ? revDisplayFlags.hidden === true
+          : markupDisplay === "clean");
+      if (hideAsDeletion) {
         const cleanPmFrom = positionMap.runtimeToPm(rev.from);
         const cleanPmTo = positionMap.runtimeToPm(rev.to);
         if (cleanPmFrom < cleanPmTo) {
@@ -470,12 +491,18 @@ export function buildDecorations(
       // Skip normal markup styling when tracked changes display is off
       if (!showTrackedChanges) continue;
 
-      const cls = getRevisionHighlightClass(
-        revisionModel,
-        rev.from,
-        rev.to,
-        markupDisplay,
-      );
+      // §4.3 — prefer L03's authoritative `revisionDisplay` flags when
+      // the caller threads the offset map; otherwise fall through to the
+      // review-store side-channel class helper.
+      const displayFlags = revisionDisplayByOffset?.get(rev.from);
+      const cls = displayFlags
+        ? buildClassFromRevisionDisplay(displayFlags)
+        : getRevisionHighlightClass(
+            revisionModel,
+            rev.from,
+            rev.to,
+            markupDisplay,
+          );
       if (!cls) continue;
 
       decorations.push(