@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/ui-tailwind/chrome/resolve-target-kind.ts

@@ -0,0 +1,226 @@
+/**
+ * resolveTargetKind — resolve a `contextmenu` event target to one or more
+ * `TargetKind` values so the shared editor-action-registry can return the
+ * correct action set.
+ *
+ * Per DESIGN-EDITOR.md §6.4, right-click + inline "More…" + command
+ * palette must read from the same registry.  To do that they need a
+ * consistent way to identify the clicked target.  The bridge hook
+ * (Phase C.β) hands us a raw `EventTarget | null`; this helper walks to
+ * the nearest Element and inspects the real `data-*` attributes the
+ * editor emits + a few tag-based fallbacks.
+ *
+ * Marker contract — the attributes / tags checked here MUST stay in
+ * sync with what the decoration renderers emit.  Every marker cited
+ * below has a `grep -rn` anchor you can verify against:
+ *
+ *   - comment-anchor  → `data-comment-id`
+ *     emitted at `src/ui-tailwind/editor-surface/pm-decorations.ts:399`
+ *     and `src/ui-tailwind/editor-surface/tw-segment-view.tsx:97`;
+ *     consumed by `pm-contextual-ui.ts:15`.
+ *   - suggestion      → `data-revision-id`
+ *     emitted at `pm-decorations.ts:421/438/463/484`; consumed by
+ *     `pm-contextual-ui.ts:21`.
+ *   - scope-anchor    → `data-workflow-scope-id` OR `data-scope-id`
+ *     emitted at `pm-decorations.ts:518/531`, the rail layer, and
+ *     scope cards.
+ *   - object          → `data-object-id` OR `data-object-selection`
+ *     emitted at `chrome-overlay/tw-object-selection-overlay.tsx:106-107`.
+ *   - image           → `<img>` tag OR `data-floating-image-id`
+ *     (page-stack/tw-floating-image-layer.tsx:189) OR
+ *     `data-preview-media-id` (pm-schema.ts inline images).
+ *   - table-cell      → `<td>` / `<th>` tag.
+ *   - hyperlink       → `<a>` tag.
+ *   - opaque-block    → `data-block-kind="opaque"`
+ *     added to `TwOpaqueBlock` in Phase D.5 as the explicit marker.
+ *
+ * Multiple kinds can apply — a table cell that contains a hyperlink
+ * returns both `table-cell` and `hyperlink`.  Caller merges the
+ * resulting action sets.  Always includes `"plain-text"` as a baseline
+ * so clipboard (cut/copy/paste) remains available.
+ *
+ * Perf discipline: synchronous DOM traversal, but only fires on
+ * user-initiated `contextmenu` events — never on the edit path
+ * (invariant 7).  No `getBoundingClientRect` / `offsetTop` reads.
+ */
+
+import type { TargetKind } from "./editor-action-registry";
+
+/**
+ * Duck-typed Node.nodeType values so this module doesn't depend on
+ * the `Node` / `Element` browser globals (the pm-command-bridge test
+ * fixtures run in bare node where those globals aren't installed).
+ */
+const NODE_TYPE_ELEMENT = 1;
+
+/**
+ * Cast an `EventTarget` to the nearest containing `Element`.  Text
+ * nodes return their parent; null / non-Node targets return null.
+ * Duck-typed so tests without DOM globals still work.
+ */
+function toElement(target: EventTarget | null): Element | null {
+  if (!target) return null;
+  const node = target as Partial<Node> & Partial<Element>;
+  if (typeof node.nodeType !== "number") return null;
+  if (node.nodeType === NODE_TYPE_ELEMENT) return target as Element;
+  return node.parentElement ?? null;
+}
+
+/**
+ * Check whether `el` OR any ancestor (up to `root` if provided) has
+ * any of the listed attributes set (with a non-empty value).
+ */
+function hasAncestorAttribute(
+  el: Element,
+  attributeNames: readonly string[],
+  root: Element | undefined,
+): boolean {
+  let cursor: Element | null = el;
+  while (cursor) {
+    for (const attr of attributeNames) {
+      if (cursor.hasAttribute?.(attr)) {
+        const value = cursor.getAttribute(attr);
+        // Empty-attr markers (like `data-object-selection=""`) count as
+        // present — hasAttribute returns true for empty strings.  Only
+        // filter explicitly null, which shouldn't happen but guards
+        // against duck-typed test doubles.
+        if (value !== null) return true;
+      }
+    }
+    if (cursor === root) return false;
+    cursor = cursor.parentElement;
+  }
+  return false;
+}
+
+/**
+ * Check whether `el` OR any ancestor has a given tag name.
+ */
+function hasAncestorTag(
+  el: Element,
+  tagName: string,
+  root: Element | undefined,
+): boolean {
+  const upper = tagName.toUpperCase();
+  let cursor: Element | null = el;
+  while (cursor) {
+    if (cursor.tagName === upper) return true;
+    if (cursor === root) return false;
+    cursor = cursor.parentElement;
+  }
+  return false;
+}
+
+/**
+ * Check whether `el` OR any ancestor has a given attribute whose value
+ * matches `expected`.  Used for the `data-block-kind="opaque"` marker
+ * where an attribute with the wrong value (e.g. `data-block-kind="code"`)
+ * should NOT classify as opaque.
+ */
+function hasAncestorAttributeValue(
+  el: Element,
+  attribute: string,
+  expected: string,
+  root: Element | undefined,
+): boolean {
+  let cursor: Element | null = el;
+  while (cursor) {
+    if (cursor.getAttribute?.(attribute) === expected) return true;
+    if (cursor === root) return false;
+    cursor = cursor.parentElement;
+  }
+  return false;
+}
+
+export interface ResolveTargetKindOptions {
+  /**
+   * Optional root — traversal stops here so a right-click inside the
+   * editor surface doesn't walk out into the shell header / rail.
+   * Typically the editor DOM root.
+   */
+  readonly root?: Element;
+}
+
+/**
+ * Return every target kind that applies to the given DOM target,
+ * always including `"plain-text"` as a fallback so clipboard actions
+ * are available.  Order is stable: more specific kinds come before
+ * `"plain-text"`.
+ */
+export function resolveTargetKind(
+  target: EventTarget | null,
+  options: ResolveTargetKindOptions = {},
+): readonly TargetKind[] {
+  const kinds: TargetKind[] = [];
+  const el = toElement(target);
+
+  if (el) {
+    const { root } = options;
+
+    // Tag-based checks — an <a> is unambiguously a hyperlink, etc.
+    if (hasAncestorTag(el, "a", root)) kinds.push("hyperlink");
+    if (hasAncestorTag(el, "img", root)) {
+      kinds.push("image");
+    }
+    if (hasAncestorTag(el, "td", root) || hasAncestorTag(el, "th", root)) {
+      kinds.push("table-cell");
+    }
+
+    // Real `data-*` markers — see the module header for emitter citations.
+
+    // Comment decorations — pm-decorations.ts:399 + tw-segment-view.tsx:97.
+    if (hasAncestorAttribute(el, ["data-comment-id"], root)) {
+      kinds.push("comment-anchor");
+    }
+
+    // Revision decorations — pm-decorations.ts:421/438/463/484.
+    if (hasAncestorAttribute(el, ["data-revision-id"], root)) {
+      kinds.push("suggestion");
+    }
+
+    // Workflow scope — pm-decorations.ts:518/531 + chrome-overlay cards.
+    if (
+      hasAncestorAttribute(
+        el,
+        ["data-workflow-scope-id", "data-scope-id"],
+        root,
+      )
+    ) {
+      kinds.push("scope-anchor");
+    }
+
+    // Object selection overlay — chrome-overlay/tw-object-selection-overlay.tsx.
+    if (
+      hasAncestorAttribute(el, ["data-object-id", "data-object-selection"], root)
+    ) {
+      kinds.push("object");
+    }
+
+    // Inline + floating image markers.  The <img> tag above covers plain
+    // images; these cover floating overlays and PM-schema preview nodes.
+    if (
+      !kinds.includes("image") &&
+      hasAncestorAttribute(
+        el,
+        ["data-floating-image-id", "data-preview-media-id"],
+        root,
+      )
+    ) {
+      kinds.push("image");
+    }
+
+    // Opaque / preserved block — TwOpaqueBlock emits data-block-kind="opaque"
+    // (Phase D.5 addition).  Value-matched so data-block-kind="code" etc.
+    // doesn't classify as opaque.
+    if (hasAncestorAttributeValue(el, "data-block-kind", "opaque", root)) {
+      kinds.push("opaque-block");
+    }
+  }
+
+  // Plain-text baseline so clipboard remains available regardless of
+  // target.  Placed last so specific kinds dominate when the menu
+  // builder dedupes actions by id.
+  if (!kinds.includes("plain-text")) kinds.push("plain-text");
+
+  return kinds;
+}

package/src/ui-tailwind/chrome/tw-alert-banner.tsx

@@ -10,6 +10,14 @@ export interface TwAlertBannerProps {
   snapshot: RuntimeRenderSnapshot;
   preserveOnlyCount: number;
   workflowBlockedReasons?: WorkflowBlockedCommandReason[];
+  /**
+   * Phase E.4 — optional handoff to the rail `health` tab.  When supplied
+   * the banner renders a "Show detail" chip the user can click to reveal
+   * full diagnostics in the management rail.  Hosts typically wire this
+   * to the chrome-host controller's `openRailTab("health")`.  Omitting
+   * the prop preserves the signal-only banner.
+   */
+  onShowDetail?: () => void;
 }
 
 /**
@@ -31,10 +39,11 @@ interface BannerRender {
   icon: ReactNode;
   message: ReactNode;
   testid: string;
+  onShowDetail?: () => void;
 }
 
 function renderBanner(variant: BannerRender): React.ReactElement {
-  const { severity, icon, message, testid } = variant;
+  const { severity, icon, message, testid, onShowDetail } = variant;
   const toneClass =
     severity === "error"
       ? "bg-[var(--color-semantic-error-soft)] text-[var(--color-semantic-error)]"
@@ -52,7 +61,17 @@ function renderBanner(variant: BannerRender): React.ReactElement {
       ].join(" ")}
     >
       {icon}
-      <span>{message}</span>
+      <span className="flex-1">{message}</span>
+      {onShowDetail ? (
+        <button
+          type="button"
+          data-testid="tw-alert-banner__show-detail"
+          onClick={onShowDetail}
+          className="shrink-0 underline underline-offset-2 hover:no-underline focus-visible:outline-none focus-visible:shadow-[var(--shadow-focus)] rounded-[var(--radius-sm)]"
+        >
+          Show detail
+        </button>
+      ) : null}
     </div>
   );
 }
@@ -60,9 +79,21 @@ function renderBanner(variant: BannerRender): React.ReactElement {
 export function TwAlertBanner(
   props: TwAlertBannerProps,
 ): React.ReactElement | null {
-  const { snapshot, preserveOnlyCount, workflowBlockedReasons = [] } = props;
+  const {
+    snapshot,
+    preserveOnlyCount,
+    workflowBlockedReasons = [],
+    onShowDetail,
+  } = props;
 
-  // 1. Fatal runtime error — highest precedence.
+  const showDetailProp: Pick<BannerRender, "onShowDetail"> = onShowDetail
+    ? { onShowDetail }
+    : {};
+
+  // 1. Fatal runtime error — highest precedence.  The rail's health tab
+  // is unlikely to have actionable detail for a session-level failure
+  // (the runtime may not even be mountable), so suppress `onShowDetail`
+  // on this variant — §6.17 fatal-error row is informational only.
   if (snapshot.fatalError) {
     return renderBanner({
       severity: "error",
@@ -85,6 +116,7 @@ export function TwAlertBanner(
         </>
       ),
       testid: "tw-alert-banner__block-export",
+      ...showDetailProp,
     });
   }
 
@@ -105,6 +137,7 @@ export function TwAlertBanner(
         </>
       ),
       testid: "tw-alert-banner__workflow-blocked",
+      ...showDetailProp,
     });
   }
 
@@ -122,6 +155,7 @@ export function TwAlertBanner(
         </>
       ),
       testid: "tw-alert-banner__preserve-only",
+      ...showDetailProp,
     });
   }
 

package/src/ui-tailwind/chrome/tw-context-band.tsx

@@ -0,0 +1,125 @@
+/**
+ * TwContextBand — the composition-level context band that carries mode-
+ * owned actions (see docs/plans/chrome-composition-audit.md §2.5,
+ * DESIGN-EDITOR.md §6.3).
+ *
+ * Before this phase: role-specific actions (review prev/next, workflow
+ * claim/skip, markup-display toggle) lived inline inside `TwToolbar` as a
+ * center segment.  The audit flags this as `RC-2`: the workspace row
+ * looked substantially the same across modes, which broke the
+ * "chrome materially changes by mode" principle.
+ *
+ * This component is the visual frame: a distinct band with its own
+ * background, border-top/bottom, mode-aware eyebrow, and padding.  Its
+ * children are whatever the mode owner decides to render inside:
+ *   - review mode  → review prev/next + accept/reject + markup selector
+ *   - workflow mode → scope prev/next + claim/skip/complete
+ *   - edit mode    → (filled in by Phase D — paragraph style + compact
+ *                     formatting cluster)
+ *   - more mode    → diagnostics links + command search affordance
+ *
+ * Phase B.3 moves the band OUT of the toolbar so the workspace row is:
+ *   [ toolbar left cluster ] · [ context band ] · [ toolbar right cluster ]
+ *
+ * Perf discipline (CLAUDE.md §Performance Invariants):
+ *   - Pure presentational component; no DOM reads, no runtime calls.
+ *   - No state.  Re-renders only when props change.
+ *   - No new geometry reads on the edit path (invariant 7).
+ */
+
+import React from "react";
+
+import type { EditorChromeMode } from "../../api/v3/ui/chrome-composition";
+
+export interface TwContextBandProps {
+  /**
+   * Composition mode per `ChromeComposition.mode`.  Drives the eyebrow
+   * label and the accent tint.
+   */
+  mode: EditorChromeMode;
+  /**
+   * Band contents.  Phase B.3 passes `<TwRoleActionRegion />` here for
+   * review/workflow modes.  Edit mode passes formatting cluster (Phase D).
+   */
+  children?: React.ReactNode;
+  /**
+   * Optional custom eyebrow label.  Defaults to the uppercased mode name.
+   * Hosts that want a scope-specific label (e.g. "REVIEW · §4.2 Claims")
+   * pass it through this prop; Phase B.3 wires it from the composition.
+   */
+  eyebrow?: string;
+  className?: string;
+}
+
+/**
+ * Default eyebrow copy per mode — uppercase per designsystem.md §4.1
+ * text.xs tracking 0.1em convention.  Kept short so the band's horizontal
+ * budget goes to the action content, not the label.
+ */
+const DEFAULT_EYEBROW: Record<EditorChromeMode, string> = {
+  edit: "Edit",
+  review: "Review",
+  workflow: "Workflow",
+  more: "More",
+};
+
+/**
+ * Accent tint classes per mode.  Review and workflow get a quiet
+ * `color.accent.soft` tint so the band visually differs from the
+ * neutral toolbar clusters flanking it; edit mode stays neutral per
+ * DESIGN-EDITOR.md §3 ("Edit mode receives chrome to normal density,
+ * no review emphasis").
+ *
+ * "more" mode stays neutral (`bg-chrome`) because the More posture
+ * opens diagnostics / compatibility drawers — the emphasis belongs on
+ * those drawers, not on the band itself.  Keeping the band quiet in
+ * More mode matches designsystem.md §2.1 principle 2 (quiet
+ * precision) and prevents two simultaneous emphasis signals.
+ */
+const MODE_TINT_CLASS: Record<EditorChromeMode, string> = {
+  edit: "bg-chrome",
+  review: "bg-accent-soft",
+  workflow: "bg-accent-soft",
+  more: "bg-chrome",
+};
+
+export function TwContextBand(props: TwContextBandProps): React.JSX.Element {
+  const eyebrow = props.eyebrow ?? DEFAULT_EYEBROW[props.mode];
+
+  const classes = [
+    // Layout — flex row, fixed height family matches designsystem.md §4.2
+    // space.10 (40px).  Horizontal padding ~12px per §6.2 cluster gap.
+    "flex items-center gap-3 h-10 px-3",
+    // Borders top + bottom so the band has clear start + end boundaries
+    // within the workspace row (audit §2.5 requires "clear start and end
+    // boundaries").
+    "border-y border-subtle",
+    // Mode-aware tint.  Quiet precision (§2.1 principle 2): low-saturation
+    // accent-soft for review/workflow so the mode is legible but not loud.
+    MODE_TINT_CLASS[props.mode],
+    props.className ?? "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <div
+      className={classes}
+      role="group"
+      aria-label={`${eyebrow} actions`}
+      data-testid="context-band"
+      data-mode={props.mode}
+      data-context-band-owner={props.mode}
+    >
+      <span
+        className="text-xs font-semibold uppercase tracking-[0.1em] text-tertiary select-none"
+        data-testid="context-band-eyebrow"
+      >
+        {eyebrow}
+      </span>
+      <div className="flex items-center gap-1 flex-1 min-w-0">
+        {props.children}
+      </div>
+    </div>
+  );
+}

package/src/ui-tailwind/chrome/tw-context-menu-portal.tsx

@@ -0,0 +1,248 @@
+/**
+ * TwContextMenuPortal — positioned portal wrapper that mounts a
+ * `TwContextMenu` at a given client (x, y) coordinate and handles
+ * outside-click + Escape dismissal.
+ *
+ * This is the composition-level mount point consumed by Phase C.γ.3
+ * inside `TwReviewWorkspace`.  It owns:
+ *   - viewport-clamped positioning (so the menu never renders off
+ *     the edge of the visible area)
+ *   - outside-click dismissal via a document-level listener
+ *   - Escape dismissal
+ *   - focus-return contract (caller supplies `returnFocusTo` — typically
+ *     the editor surface DOM node)
+ *
+ * It does NOT own target-kind resolution, menu-entry building, or
+ * action dispatch — those live in `resolve-target-kind.ts`,
+ * `build-context-menu-entries.ts`, and `editor-action-registry.ts`
+ * respectively, so the single-registry invariant (DESIGN-EDITOR.md
+ * §6.4) stays intact.
+ *
+ * Perf discipline (CLAUDE.md §Performance Invariants):
+ *   - Listeners attach on mount, detach on unmount.  No polling,
+ *     no rAF.  Dismissal latency is the native browser event loop.
+ *   - No DOM geometry reads on the edit path (invariant 7).
+ *   - Positioning uses `position: fixed` + direct client coordinates
+ *     — no `getBoundingClientRect` on mount.  The only layout read
+ *     is a post-mount clamp (read-once, inside requestAnimationFrame).
+ */
+
+import React, { useCallback, useEffect, useLayoutEffect, useRef } from "react";
+import { createPortal } from "react-dom";
+
+import {
+  type LocalSurfaceKind,
+  useLocalSurfaceArbiterState,
+} from "./local-surface-arbiter";
+import {
+  TwContextMenu,
+  type ContextMenuContext,
+  type ContextMenuEntry,
+} from "./tw-context-menu";
+
+/**
+ * Map a `LocalSurfaceKind` to the `ContextMenuContext` flag it should
+ * raise so the menu's dedupe filter (`filterContextMenuEntries`) can
+ * suppress the matching group. Used to project the arbiter state
+ * (active + pinned slots) into the dedupe context — Chrome Closure
+ * Pass · Task 2 (designsystem.md §6.24): the menu **must always
+ * open** on right-click; the arbiter's role is filtering content,
+ * not preempting visibility.
+ */
+function projectArbiterKindToContext(
+  kind: LocalSurfaceKind | null,
+  ctx: ContextMenuContext,
+): ContextMenuContext {
+  if (!kind) return ctx;
+  switch (kind) {
+    case "selection-format":
+      return { ...ctx, selectionToolbarVisible: true };
+    case "suggestion-card":
+      return { ...ctx, suggestionCardVisible: true };
+    case "comment-preview":
+      return { ...ctx, commentCardVisible: true };
+    case "scope-card":
+    case "blocked-card":
+    case "workflow-card":
+    case "context-menu":
+      // These have no dedicated dedupe flag — the menu's group set
+      // does not duplicate scope/blocked/workflow content today.
+      return ctx;
+  }
+}
+
+export interface TwContextMenuPortalProps {
+  /**
+   * When falsy the portal renders nothing.  Typically driven by the
+   * host's contextmenu-request state.
+   */
+  open: boolean;
+  /** Client coordinates at which to anchor the menu's top-left corner. */
+  clientX: number;
+  clientY: number;
+  /** Entries to render (already built via `buildContextMenuEntries`). */
+  entries: ContextMenuEntry[];
+  /** Optional dedupe context passed through to TwContextMenu. */
+  context?: Partial<ContextMenuContext>;
+  /** Optional platform hint for shortcut rendering. */
+  platform?: "mac" | "win";
+  /** Invoked on Escape / outside-click / row-select. */
+  onDismiss: () => void;
+  /**
+   * Element to return focus to on dismissal.  Typically the PM editor
+   * surface.  Skipped if null/undefined.
+   */
+  returnFocusTo?: HTMLElement | null;
+  /** Optional aria-label override for the menu container. */
+  "aria-label"?: string;
+}
+
+/**
+ * Minimum viewport margin — matches the selection-toolbar clamp in
+ * designsystem.md §6.4 (1.5 rem ≈ 24 px).
+ */
+const VIEWPORT_MARGIN = 24;
+
+export function TwContextMenuPortal(
+  props: TwContextMenuPortalProps,
+): React.JSX.Element | null {
+  const {
+    open,
+    clientX,
+    clientY,
+    entries,
+    context,
+    platform,
+    onDismiss,
+    returnFocusTo,
+  } = props;
+
+  const menuRef = useRef<HTMLDivElement | null>(null);
+
+  // Escape + outside-click dismissal.
+  useEffect(() => {
+    if (!open) return;
+    const onKeyDown = (ev: KeyboardEvent) => {
+      if (ev.key === "Escape") {
+        ev.preventDefault();
+        onDismiss();
+      }
+    };
+    const onPointerDown = (ev: MouseEvent) => {
+      const menu = menuRef.current;
+      if (!menu) return;
+      const target = ev.target;
+      if (target instanceof Node && menu.contains(target)) return;
+      onDismiss();
+    };
+    document.addEventListener("keydown", onKeyDown);
+    document.addEventListener("mousedown", onPointerDown);
+    return () => {
+      document.removeEventListener("keydown", onKeyDown);
+      document.removeEventListener("mousedown", onPointerDown);
+    };
+  }, [open, onDismiss]);
+
+  // Focus-return on close.  Fires only on the open → closed edge.
+  const wasOpenRef = useRef(false);
+  useEffect(() => {
+    if (wasOpenRef.current && !open && returnFocusTo) {
+      returnFocusTo.focus();
+    }
+    wasOpenRef.current = open;
+  }, [open, returnFocusTo]);
+
+  // B2 fix — positioning is owned ENTIRELY by this layoutEffect; React
+  // does not set `left`/`top` via the style prop, so re-renders can't
+  // clobber the clamped coordinates.  The layoutEffect writes initial
+  // placement + clamp on mount and on any prop change that would move
+  // the menu.  Single layout read per pass; no polling, no rAF loop.
+  useLayoutEffect(() => {
+    if (!open) return;
+    const menu = menuRef.current;
+    if (!menu) return;
+    // Apply raw coordinates first so getBoundingClientRect measures the
+    // menu at its intended anchor; then clamp if that would overflow.
+    menu.style.left = `${clientX}px`;
+    menu.style.top = `${clientY}px`;
+
+    const rect = menu.getBoundingClientRect();
+    const viewportWidth = window.innerWidth;
+    const viewportHeight = window.innerHeight;
+
+    let left = clientX;
+    let top = clientY;
+
+    if (left + rect.width > viewportWidth - VIEWPORT_MARGIN) {
+      left = Math.max(VIEWPORT_MARGIN, viewportWidth - VIEWPORT_MARGIN - rect.width);
+    }
+    if (top + rect.height > viewportHeight - VIEWPORT_MARGIN) {
+      top = Math.max(VIEWPORT_MARGIN, viewportHeight - VIEWPORT_MARGIN - rect.height);
+    }
+
+    if (left !== clientX) menu.style.left = `${left}px`;
+    if (top !== clientY) menu.style.top = `${top}px`;
+  }, [open, clientX, clientY, entries]);
+
+  const wrappedDismiss = useCallback(() => {
+    onDismiss();
+  }, [onDismiss]);
+
+  // Chrome Closure Pass · Task 2 (designsystem.md §6.24) — the
+  // context menu must always open on right-click. The pre-Task-2
+  // arbiter gate (`useLocalSurfaceRequest({kind:"context-menu", …})`)
+  // preempted the menu whenever a higher-priority local surface was
+  // visible, which made right-click silently disappear in normal
+  // contextual states. Replace the gate with a content-filter: read
+  // arbiter state (active + pinned) and project it into the dedupe
+  // `ContextMenuContext` so `filterContextMenuEntries` drops only the
+  // groups already represented by visible chrome — the menu itself
+  // stays open.
+  const arbiterState = useLocalSurfaceArbiterState();
+  const dedupeContext: ContextMenuContext = projectArbiterKindToContext(
+    arbiterState.activeKind,
+    projectArbiterKindToContext(arbiterState.pinnedKind, {
+      selectionToolbarVisible: false,
+      suggestionCardVisible: false,
+      commentCardVisible: false,
+      tableToolbarVisible: false,
+      ...context,
+    }),
+  );
+
+  if (!open) return null;
+
+  const content = (
+    <div
+      ref={menuRef}
+      // left/top intentionally absent — set imperatively by the
+      // layoutEffect above so React re-renders don't clobber the clamp.
+      style={{
+        position: "fixed",
+        zIndex: 1000,
+      }}
+      onClick={(ev) => {
+        // Any click on a menu row should dismiss — the row's onSelect
+        // already fires the action before bubbling.  Guard against
+        // separators / non-item clicks so we don't dismiss on noise
+        // inside the menu chrome.
+        const target = ev.target as HTMLElement | null;
+        if (target?.closest('[role="menuitem"]')) {
+          wrappedDismiss();
+        }
+      }}
+    >
+      <TwContextMenu
+        entries={entries}
+        context={dedupeContext}
+        {...(platform ? { platform } : {})}
+        {...(props["aria-label"] ? { "aria-label": props["aria-label"] } : {})}
+        data-testid="tw-context-menu-portal"
+      />
+    </div>
+  );
+
+  // Portal into document.body so the menu escapes any overflow:hidden
+  // ancestors in the editor layout.
+  return createPortal(content, document.body);
+}