@beyondwork/docx-react-component 1.0.91 → 1.0.93

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.91",
+  "version": "1.0.93",
   "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/WordReviewEditor.tsx

@@ -138,6 +138,7 @@ import {
   type TwProseMirrorSurfaceRef,
 } from "../ui-tailwind/editor-surface/tw-prosemirror-surface";
 import { TwInlineFindBar } from "../ui-tailwind/chrome/tw-inline-find-bar";
+import { PAGE_CHROME_DEFAULTS } from "../ui-tailwind/editor-surface/pm-page-break-decorations.ts";
 import type { MediaPreviewDescriptor } from "../ui-tailwind/editor-surface/pm-state-from-snapshot";
 import {
   incrementInvalidationCounter,
@@ -3753,7 +3754,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         geometryFacet={activeRuntime.geometry}
         pageChromeHeaderBandPx={isPageWorkspace ? 32 : 0}
         pageChromeFooterBandPx={isPageWorkspace ? 32 : 0}
-        pageChromeInterGapPx={isPageWorkspace ? 24 : 16}
+        pageChromeInterGapPx={PAGE_CHROME_DEFAULTS.interGapPx}
         onOpenHeaderStoryForPage={(pageIndex: number) =>
           openStoryForPage(activeRuntime, pageIndex, "header")
         }

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/editor-surface/tw-prosemirror-surface.tsx

@@ -340,7 +340,7 @@ export interface TwProseMirrorSurfaceProps {
   pageChromeHeaderBandPx?: number;
   /** Height in px of each page's footer band. Default 32. */
   pageChromeFooterBandPx?: number;
-  /** Visible vertical gap between adjacent pages. Default 24 for page mode. */
+  /** Visible vertical gap between adjacent pages. Default 48 to match the render kernel. */
   pageChromeInterGapPx?: number;
   /**
    * Revision counter; incremented by the host to trigger a decoration