@beyondwork/docx-react-component 1.0.92 → 1.0.94

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.92",
+  "version": "1.0.94",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [

package/src/api/v3/ui/_types.ts

@@ -25,8 +25,12 @@
 
 import type {
   OverlayKind,
+  ScopeCardModel,
   ScopeBundle,
+  ScopeRailSnapshot,
   SelectionSnapshot,
+  SemanticScope,
+  SemanticScopeKind,
   WorkflowMarkupMode,
 } from "../../public-types.ts";
 import type { GeometryRect } from "../../../runtime/geometry/geometry-types.ts";
@@ -549,11 +553,31 @@ export interface ApiV3UiDebug {
   detach(): void;
 }
 
+export interface UiScopeListFilter {
+  readonly kind?: SemanticScopeKind;
+  readonly limit?: number;
+}
+
+export interface UiScopeRailOptions {
+  /**
+   * Narrow the snapshot to a single page index. Omit to span every page
+   * the runtime's page graph knows about.
+   */
+  readonly pageIndex?: number;
+}
+
 /**
- * Scope seam — mounted-path scope-bundle reads. MVP surface unblocked
- * by L07's `compileScopeBundleById` handle primitive (2026-04-23).
+ * Scope seam — mounted-path scope reads. Uses handle-backed compiled
+ * projections so chrome surfaces do not reach directly into workflow
+ * facets for list, card, rail, or bundle data.
  */
 export interface ApiV3UiScope {
+  /** Enumerate compiled semantic scopes, optionally narrowed by kind/limit. */
+  list(filter?: UiScopeListFilter): readonly SemanticScope[];
+  /** Read the scope-card projection for a single scope id. */
+  card(scopeId: string): ScopeCardModel | null;
+  /** Read scope-rail segments across the document or a single page. */
+  rail(options?: UiScopeRailOptions): ScopeRailSnapshot;
   /**
    * Read the full `ScopeBundle` for a scope by id. Returns `null` when
    * the scope does not enumerate today (handle drift, synthetic scope,

package/src/api/v3/ui/index.ts

@@ -21,6 +21,8 @@ export type {
   UiBinding,
   UiListener,
   UiUnsubscribe,
+  UiScopeListFilter,
+  UiScopeRailOptions,
   ViewportState,
   ScrollTarget,
   ScrollTargetBehavior,

package/src/ui-tailwind/chrome/tw-display-mode-selector.tsx

@@ -13,14 +13,15 @@
  * names sees the right option highlighted without code changes.
  */
 
-import React, { useState } from "react";
-import * as Popover from "@radix-ui/react-popover";
+import React, { useLayoutEffect, useRef, useState, type CSSProperties } from "react";
+import { createPortal } from "react-dom";
 import { ChevronDown, Eye, EyeOff, Highlighter, Scroll } from "lucide-react";
 
 import {
   normalizeMarkupDisplay,
   type MarkupDisplay,
 } from "../../ui/headless/comment-decoration-model";
+import { preserveEditorSelectionMouseDown } from "../../ui/headless/preserve-editor-selection";
 
 export type DisplayMode = "all-markup" | "simple-markup" | "no-markup" | "original";
 
@@ -67,70 +68,136 @@ const MODES: readonly ModeEntry[] = [
 
 export function TwDisplayModeSelector(props: TwDisplayModeSelectorProps): React.ReactElement {
   const [open, setOpen] = useState(false);
+  const triggerRef = useRef<HTMLButtonElement>(null);
   const canonical = normalizeMarkupDisplay(props.value);
   const activeEntry = MODES.find((m) => m.mode === canonical) ?? MODES[0]!;
 
   return (
-    <Popover.Root open={open} onOpenChange={setOpen}>
-      <Popover.Trigger asChild>
+    <>
         <button
+          ref={triggerRef}
           type="button"
           disabled={props.disabled}
           data-testid={props["data-testid"] ?? "display-mode-selector-trigger"}
           aria-label={`Display mode: ${activeEntry.label}`}
-          className="inline-flex items-center gap-1.5 rounded-md px-2 py-1 text-[11px] font-medium text-primary hover:bg-surface focus-visible:outline-none focus-visible:bg-surface disabled:opacity-50"
+          aria-expanded={open}
+          aria-haspopup="menu"
+          onMouseDown={preserveEditorSelectionMouseDown}
+          onClick={(event) => {
+            event.preventDefault();
+            setOpen((value) => !value);
+          }}
+          className={[
+            "inline-flex items-center gap-1.5 rounded-md px-2 py-1 text-[11px] font-medium text-primary",
+            "hover:bg-surface focus-visible:outline-none focus-visible:bg-surface disabled:opacity-50",
+            open ? "bg-canvas text-accent ring-1 ring-accent/30 shadow-sm" : "",
+          ].join(" ")}
         >
           <activeEntry.icon className="h-3.5 w-3.5 text-tertiary" />
           <span>{activeEntry.label}</span>
           <ChevronDown className="h-3.5 w-3.5 text-tertiary" />
         </button>
-      </Popover.Trigger>
-      <Popover.Portal>
-        <Popover.Content
-          className="z-50 w-[260px] rounded-lg bg-canvas p-1 shadow-lg ring-1 ring-border"
-          sideOffset={8}
-          align="end"
-          data-testid="display-mode-selector-content"
-        >
+      <DisplayModePortalMenu anchorRef={triggerRef} open={open}>
           <div className="mb-1 px-2 py-1 text-[10px] font-semibold uppercase tracking-[0.12em] text-tertiary">
             Display mode
           </div>
           {MODES.map((entry) => {
             const isActive = entry.mode === canonical;
             return (
-              <Popover.Close key={entry.mode} asChild>
-                <button
-                  type="button"
-                  role="menuitemradio"
-                  aria-checked={isActive}
-                  onClick={() => {
-                    props.onChange(entry.mode);
-                  }}
-                  className="flex w-full items-start gap-2 rounded-md px-2 py-1.5 text-left text-[11px] transition-colors hover:bg-surface focus-visible:outline-none focus-visible:bg-surface"
-                  data-testid={`display-mode-option-${entry.mode}`}
-                  data-mode={entry.mode}
-                  data-active={isActive ? "true" : undefined}
-                >
-                  <entry.icon
-                    className={[
-                      "mt-0.5 h-3.5 w-3.5 shrink-0",
-                      isActive ? "text-accent" : "text-tertiary",
-                    ].join(" ")}
-                  />
-                  <span className="flex flex-col">
-                    <span className={`font-medium ${isActive ? "text-accent" : "text-primary"}`}>
-                      {entry.label}
-                    </span>
-                    <span className="text-[10px] text-secondary">{entry.hint}</span>
+              <button
+                key={entry.mode}
+                type="button"
+                role="menuitemradio"
+                aria-checked={isActive}
+                onClick={() => {
+                  props.onChange(entry.mode);
+                  setOpen(false);
+                }}
+                className="flex w-full items-start gap-2 rounded-md px-2 py-1.5 text-left text-[11px] transition-colors hover:bg-surface focus-visible:outline-none focus-visible:bg-surface"
+                data-testid={`display-mode-option-${entry.mode}`}
+                data-mode={entry.mode}
+                data-active={isActive ? "true" : undefined}
+              >
+                <entry.icon
+                  className={[
+                    "mt-0.5 h-3.5 w-3.5 shrink-0",
+                    isActive ? "text-accent" : "text-tertiary",
+                  ].join(" ")}
+                />
+                <span className="flex flex-col">
+                  <span className={`font-medium ${isActive ? "text-accent" : "text-primary"}`}>
+                    {entry.label}
                   </span>
-                </button>
-              </Popover.Close>
+                  <span className="text-[10px] text-secondary">{entry.hint}</span>
+                </span>
+              </button>
             );
           })}
-        </Popover.Content>
-      </Popover.Portal>
-    </Popover.Root>
+      </DisplayModePortalMenu>
+    </>
+  );
+}
+
+function DisplayModePortalMenu(props: {
+  anchorRef: React.RefObject<HTMLButtonElement | null>;
+  children: React.ReactNode;
+  open: boolean;
+}): React.ReactPortal | null {
+  const style = useDisplayModePortalPosition(props.anchorRef, props.open);
+  const body = props.anchorRef.current?.ownerDocument?.body;
+  if (!props.open || !body) return null;
+  return createPortal(
+    <div
+      className="z-50 w-[260px] rounded-lg bg-canvas p-1 shadow-lg ring-1 ring-border"
+      data-testid="display-mode-selector-content"
+      style={style}
+    >
+      {props.children}
+    </div>,
+    body,
   );
 }
 
+function useDisplayModePortalPosition(
+  anchorRef: React.RefObject<HTMLButtonElement | null>,
+  open: boolean,
+): CSSProperties {
+  const [style, setStyle] = useState<CSSProperties>({
+    left: 8,
+    position: "fixed",
+    top: 8,
+    zIndex: 50,
+  });
+
+  useLayoutEffect(() => {
+    if (!open) return;
+    const anchor = anchorRef.current;
+    const ownerWindow = anchor?.ownerDocument?.defaultView;
+    if (!anchor || !ownerWindow) return;
+    const update = () => {
+      const rect = anchor.getBoundingClientRect();
+      const width = 260;
+      const left = Math.min(
+        Math.max(8, rect.right - width),
+        Math.max(8, (ownerWindow.innerWidth || width + 16) - width - 8),
+      );
+      setStyle({
+        left,
+        position: "fixed",
+        top: Math.max(8, rect.bottom + 8),
+        zIndex: 50,
+      });
+    };
+    update();
+    ownerWindow.addEventListener("resize", update);
+    ownerWindow.addEventListener("scroll", update, true);
+    return () => {
+      ownerWindow.removeEventListener("resize", update);
+      ownerWindow.removeEventListener("scroll", update, true);
+    };
+  }, [anchorRef, open]);
+
+  return style;
+}
+
 export default TwDisplayModeSelector;

package/src/ui-tailwind/chrome-overlay/tw-scope-card-layer.tsx

@@ -25,6 +25,7 @@ import {
 } from "./chrome-overlay-projector";
 import { TwScopeCard } from "./tw-scope-card";
 import { useLocalSurfaceRequest } from "../chrome/local-surface-arbiter";
+import { useUiApi } from "../ui-api-context";
 import type {
   EditorRole,
   ScopeCardModel,
@@ -46,12 +47,14 @@ export interface TwScopeCardLayerProps {
    */
   facet: WordReviewEditorLayoutFacet;
   /**
-   * Workflow facet — canonical source of scope card models
-   * (`runtime.workflow.getAllScopeCardModels()`). `null` is treated as
-   * "no cards".
+   * Workflow facet — fallback source for no-provider paths. Mounted
+   * editor surfaces read scope cards through `api.ui.scope.card(...)`.
+   * `null` is treated as "no cards".
    */
   workflowFacet: WorkflowFacet | null;
   activeScopeId: string | null;
+  /** Scope ids currently visible under the Workflow rail layer filters. */
+  visibleScopeIds?: ReadonlySet<string>;
   onClose: () => void;
   onModeChange: (scopeId: string, mode: WorkflowScopeMode) => void;
   onIssueAction: (
@@ -91,6 +94,7 @@ export const TwScopeCardLayer: React.FC<TwScopeCardLayerProps> = ({
   facet,
   workflowFacet,
   activeScopeId,
+  visibleScopeIds,
   onClose,
   onModeChange,
   onIssueAction,
@@ -104,6 +108,7 @@ export const TwScopeCardLayer: React.FC<TwScopeCardLayerProps> = ({
   "data-testid": testId,
 }) => {
   const [pinnedScopeId, setPinnedScopeId] = React.useState<string | null>(null);
+  const ui = useUiApi();
 
   // If the layer's close handler fires, also clear any pin so the
   // next stripe click starts from a clean state.
@@ -116,14 +121,27 @@ export const TwScopeCardLayer: React.FC<TwScopeCardLayerProps> = ({
     setPinnedScopeId((current) => (current === scopeId ? null : scopeId));
   }, []);
 
+  const getWorkflowScopeCardModel = React.useCallback(
+    (scopeId: string): ScopeCardModel | null =>
+      workflowFacet?.getAllScopeCardModels().find((m) => m.scopeId === scopeId) ??
+      null,
+    [workflowFacet],
+  );
+
+  const getVisibleScopeCardModel = React.useCallback(
+    (scopeId: string | null): ScopeCardModel | null => {
+      if (!scopeId) return null;
+      if (visibleScopeIds && !visibleScopeIds.has(scopeId)) return null;
+      if (ui) return ui.scope.card(scopeId);
+      return getWorkflowScopeCardModel(scopeId);
+    },
+    [getWorkflowScopeCardModel, ui, visibleScopeIds],
+  );
+
   // The effective scope is the pinned one if it still resolves to a
   // model, else the active one.  When a pinned scope disappears
   // (e.g. the host cleared the overlay), drop the pin.
-  const models = workflowFacet?.getAllScopeCardModels() ?? [];
-
-  const pinnedModel = pinnedScopeId
-    ? models.find((m) => m.scopeId === pinnedScopeId) ?? null
-    : null;
+  const pinnedModel = getVisibleScopeCardModel(pinnedScopeId);
 
   // R2.b — when a pinned scope disappears from the model list (e.g. the
   // host cleared the overlay), drop the pin. Must run in an effect, not
@@ -132,10 +150,10 @@ export const TwScopeCardLayer: React.FC<TwScopeCardLayerProps> = ({
   // exceeded" in React 18 concurrent mode where renders are retried
   // before commit.
   React.useEffect(() => {
-    if (pinnedScopeId && !models.find((m) => m.scopeId === pinnedScopeId)) {
+    if (pinnedScopeId && !pinnedModel) {
       setPinnedScopeId(null);
     }
-  }, [pinnedScopeId, models]);
+  }, [pinnedScopeId, pinnedModel]);
 
   const effectiveScopeId = pinnedModel ? pinnedScopeId : activeScopeId;
   const isPinnedEffective = pinnedScopeId !== null && pinnedScopeId === effectiveScopeId;
@@ -157,8 +175,7 @@ export const TwScopeCardLayer: React.FC<TwScopeCardLayerProps> = ({
   );
 
   if (!effectiveScopeId) return null;
-  const model: ScopeCardModel | undefined =
-    pinnedModel ?? models.find((m) => m.scopeId === effectiveScopeId);
+  const model = pinnedModel ?? getVisibleScopeCardModel(effectiveScopeId);
   if (!model) return null;
   if (!isArbiterActive) return null;
 

package/src/ui-tailwind/toolbar/tw-role-action-region.tsx

@@ -13,8 +13,8 @@
  * traversal + claim/skip/complete.
  */
 
-import React, { useState } from "react";
-import * as Popover from "@radix-ui/react-popover";
+import React, { useLayoutEffect, useRef, useState, type CSSProperties } from "react";
+import { createPortal } from "react-dom";
 import * as Toggle from "@radix-ui/react-toggle";
 import * as Tooltip from "@radix-ui/react-tooltip";
 import {
@@ -433,38 +433,100 @@ function RoleActionOverflow({
   props,
 }: RoleActionOverflowProps): React.JSX.Element {
   const [open, setOpen] = useState(false);
+  const triggerRef = useRef<HTMLButtonElement>(null);
 
   return (
-    <Popover.Root open={open} onOpenChange={setOpen}>
-      <Popover.Trigger asChild>
+    <>
         <button
+          ref={triggerRef}
           type="button"
           aria-label="More role actions"
           aria-expanded={open}
+          aria-haspopup="menu"
           onMouseDown={preserveEditorSelectionMouseDown}
+          onClick={(event) => {
+            event.preventDefault();
+            setOpen((value) => !value);
+          }}
           title="More role actions"
-          className="inline-flex h-6 w-6 items-center justify-center rounded-md border border-border bg-canvas text-primary transition-colors hover:bg-surface outline-none focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas"
+          className={`inline-flex h-6 w-6 items-center justify-center rounded-md border border-border bg-canvas text-primary transition-colors hover:bg-surface outline-none focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas ${
+            open ? "text-accent ring-1 ring-accent/30 shadow-sm" : ""
+          }`}
           data-testid="role-action-overflow-trigger"
         >
           <MoreHorizontal className="h-3.5 w-3.5 text-tertiary" aria-hidden="true" />
         </button>
-      </Popover.Trigger>
-      <Popover.Portal>
-        <Popover.Content
-          className="z-50 w-[220px] rounded-lg bg-canvas p-1 shadow-lg ring-1 ring-border"
-          sideOffset={8}
-          align="start"
-          data-testid="role-action-overflow-content"
-        >
+      <RoleActionPortalMenu anchorRef={triggerRef} open={open}>
           {ids.map((id) => (
             <OverflowAction key={id} id={id} props={props} onClose={() => setOpen(false)} />
           ))}
-        </Popover.Content>
-      </Popover.Portal>
-    </Popover.Root>
+      </RoleActionPortalMenu>
+    </>
+  );
+}
+
+function RoleActionPortalMenu(props: {
+  anchorRef: React.RefObject<HTMLButtonElement | null>;
+  children: React.ReactNode;
+  open: boolean;
+}): React.ReactPortal | null {
+  const style = useRoleActionPortalPosition(props.anchorRef, props.open);
+  const body = props.anchorRef.current?.ownerDocument?.body;
+  if (!props.open || !body) return null;
+  return createPortal(
+    <div
+      className="z-50 w-[220px] rounded-lg bg-canvas p-1 shadow-lg ring-1 ring-border"
+      data-testid="role-action-overflow-content"
+      style={style}
+    >
+      {props.children}
+    </div>,
+    body,
   );
 }
 
+function useRoleActionPortalPosition(
+  anchorRef: React.RefObject<HTMLButtonElement | null>,
+  open: boolean,
+): CSSProperties {
+  const [style, setStyle] = useState<CSSProperties>({
+    left: 8,
+    position: "fixed",
+    top: 8,
+    zIndex: 50,
+  });
+
+  useLayoutEffect(() => {
+    if (!open) return;
+    const anchor = anchorRef.current;
+    const ownerWindow = anchor?.ownerDocument?.defaultView;
+    if (!anchor || !ownerWindow) return;
+    const update = () => {
+      const rect = anchor.getBoundingClientRect();
+      const width = 220;
+      const left = Math.min(
+        Math.max(8, rect.left),
+        Math.max(8, (ownerWindow.innerWidth || width + 16) - width - 8),
+      );
+      setStyle({
+        left,
+        position: "fixed",
+        top: Math.max(8, rect.bottom + 8),
+        zIndex: 50,
+      });
+    };
+    update();
+    ownerWindow.addEventListener("resize", update);
+    ownerWindow.addEventListener("scroll", update, true);
+    return () => {
+      ownerWindow.removeEventListener("resize", update);
+      ownerWindow.removeEventListener("scroll", update, true);
+    };
+  }, [anchorRef, open]);
+
+  return style;
+}
+
 function OverflowAction(arg: {
   id: ToolbarChromeItemId;
   props: TwRoleActionRegionProps;

package/src/ui-tailwind/toolbar/tw-toolbar-icon-button.tsx

@@ -27,6 +27,8 @@ export interface TwToolbarIconButtonProps {
    * vs. Windows however they like.
    */
   shortcut?: string;
+  /** Explanation surfaced when the button is disabled by selection/mode state. */
+  disabledReason?: string;
   onClick?: () => void;
 }
 
@@ -42,7 +44,9 @@ export function TwToolbarIconButton(props: TwToolbarIconButtonProps) {
           aria-label={props.label}
           aria-pressed={props.active ?? undefined}
           data-active={props.active ? "true" : undefined}
+          data-disabled-reason={props.disabled && props.disabledReason ? props.disabledReason : undefined}
           disabled={props.disabled}
+          title={props.disabled && props.disabledReason ? `Not available: ${props.disabledReason}` : undefined}
           onMouseDown={preserveEditorSelectionMouseDown}
           onClick={props.onClick}
           className={[