@beyondwork/docx-react-component 1.0.57 → 1.0.59

package/src/ui/WordReviewEditor.tsx

@@ -44,6 +44,7 @@ import type {
   SectionLayoutPatch,
   SectionPageNumberingPatch,
   SearchOptions,
+  SetSelectionOptions,
   SearchResultSnapshot,
   SelectionSnapshot as PublicSelectionSnapshot,
   SuggestionEntrySnapshot,
@@ -76,6 +77,7 @@ import type {
   ZoomLevel,
 } from "../api/public-types";
 import { MetadataResolverMissingError } from "../api/public-types";
+import { buildRefProjections } from "../api/internal/build-ref-projections.ts";
 import { readHarnessDebugPortsFlag } from "../internal/harness-debug-ports.ts";
 import type { ScopeMetadataResolver } from "../api/scope-metadata-resolver-types.ts";
 import {
@@ -151,7 +153,7 @@ import {
 } from "../io/source-package-provenance.ts";
 import { readOpcPackage } from "../io/opc/package-reader.ts";
 import { deriveCapabilities } from "../runtime/session-capabilities";
-import { searchDocument } from "../runtime/document-search.ts";
+import { findTextMatches, searchDocument } from "../runtime/document-search.ts";
 import {
   resolveCurrentContextAnalyticsQuery,
   runtimeContextAnalyticsSnapshotsEqual,
@@ -189,6 +191,7 @@ import type {
   SuggestionCardModel,
 } from "./headless/selection-toolbar-model";
 import { resolveActiveSelectionTool } from "./headless/selection-tool-resolver";
+import { resolveSelectionToolRegistry } from "./headless/chrome-registry";
 import { type EditorCommandBag, useCommandBag } from "./editor-command-bag.ts";
 import {
   resolveHeadingShortcutStyleId,
@@ -566,7 +569,16 @@ export function __createWordReviewEditorRefBridge(
   // Pending-conflict queue for this bridge instance.  Keyed by conflictKey(...).
   const pendingConflicts = new Map<string, PendingConflict>();
 
-  return {
+  // v2.0.0 Track D — purpose-grouped projections dispatch via this holder
+  // so they stay in lockstep with the ref even if a rebuild is triggered.
+  const refHolder: { current: WordReviewEditorRef | null } = { current: null };
+  const projections = buildRefProjections(() => {
+    const r = refHolder.current;
+    if (!r) throw new Error("ref projection used before ref initialization");
+    return r;
+  });
+
+  const refValue: WordReviewEditorRef = {
     focus: () => runtime.focus(),
     blur: () => runtime.blur(),
     undo: () => runtime.undo(),
@@ -595,6 +607,12 @@ export function __createWordReviewEditorRefBridge(
     addScope: (params) => runtime.addScope(params),
     getScope: (scopeId) => runtime.getScope(scopeId),
     removeScope: (scopeId) => runtime.removeScope(scopeId),
+    addInvisibleScope: (params) => runtime.addInvisibleScope(params),
+    setScopeVisibility: (scopeId, visibility) => runtime.setScopeVisibility(scopeId, visibility),
+    getScopeVisibility: (scopeId) => runtime.getScopeVisibility(scopeId),
+    setScopeChromeVisibility: (state) => runtime.setScopeChromeVisibility(state),
+    getScopeChromeVisibility: () => runtime.getScopeChromeVisibility(),
+    subscribeToScopeQuery: (filter, callback) => runtime.subscribeToScopeQuery(filter, callback),
     acceptChange: (changeId) => runtime.acceptChange(changeId),
     rejectChange: (changeId) => runtime.rejectChange(changeId),
     acceptAllChanges: () => runtime.acceptAllChanges(),
@@ -760,7 +778,7 @@ export function __createWordReviewEditorRefBridge(
     clearSearch: () => {
       mountedSurface?.clearSearch();
     },
-    setSelection: (selection) => {
+    setSelection: (selection, _options?: SetSelectionOptions) => {
       applyRuntimeSelection(
         runtime,
         normalizeRequestedSelection(runtime.getRenderSnapshot(), selection),
@@ -909,6 +927,36 @@ export function __createWordReviewEditorRefBridge(
     getWorkflowMetadataSnapshot: () => {
       return clonePublicValue(runtime.getWorkflowMetadataSnapshot());
     },
+    queryScopes: (filter) => {
+      return clonePublicValue(runtime.queryScopes(filter));
+    },
+    findScopesAt: (position, options) => {
+      return clonePublicValue(runtime.findScopesAt(position, options));
+    },
+    findScopesIntersecting: (range, options) => {
+      return clonePublicValue(runtime.findScopesIntersecting(range, options));
+    },
+    findFirstText: (query, opts) => {
+      const hits = findTextMatchesForRuntime(runtime, query, opts);
+      return hits.length > 0 ? (hits[0] ?? null) : null;
+    },
+    findAllText: (query, opts) => {
+      return findTextMatchesForRuntime(runtime, query, opts);
+    },
+    selectFirstText: (query, opts) => {
+      const hits = findTextMatchesForRuntime(runtime, query, opts);
+      if (hits.length === 0) return false;
+      applyRuntimeSelection(runtime, createSelectionFromAnchor(hits[0]!));
+      return true;
+    },
+    selectAllText: (query, opts) => {
+      const hits = findTextMatchesForRuntime(runtime, query, opts);
+      if (hits.length === 0) return 0;
+      applyRuntimeSelection(runtime, createSelectionFromAnchor(hits[0]!));
+      return hits.length;
+    },
+    findTextWithStyle: (query, filter, opts) => runtime.findTextWithStyle(query, filter, opts),
+    selectTextWithStyle: (query, filter, opts) => runtime.selectTextWithStyle(query, filter, opts),
     // P17 — metadata persistence toggle + convert methods.
     setMetadataPersistenceMode: (mode) => {
       if (mode === "external" && !(options?.resolverRef?.current ?? null)) {
@@ -1112,7 +1160,10 @@ export function __createWordReviewEditorRefBridge(
     replaceWorkflowMarkupText: (markupId, text) => {
       runtime.replaceWorkflowMarkupText(markupId, text);
     },
+    ...projections,
   };
+  refHolder.current = refValue;
+  return refValue;
 }
 
 export function __applyRuntimeTextCommand(
@@ -1126,6 +1177,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
   function WordReviewEditor(props, ref) {
     const {
       currentUser,
+      shellHeader,
       ydoc,
       awareness,
       hostAdapter,
@@ -1163,6 +1215,8 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       suggestionsEnabled = false,
       showReviewPanel = true,
       chromeVisibility,
+      density,
+      customSelectionTools,
     } = props;
 
     const [activeRailTab, setActiveRailTab] = useState<ReviewRailTab>("comments");
@@ -1190,6 +1244,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       new Map<string, { choice: string; mergedValue?: Record<string, unknown> }>(),
     );
     const metadataConflictPendingRef = useRef(new Map<string, PendingConflict>());
+    const suppressNextAwarenessPublishRef = useRef(false);
     const {
       runtime,
       loadError,
@@ -1444,6 +1499,21 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       activeRuntime.setDocumentMode(suggestionsEnabled ? "suggesting" : "editing");
     }, [activeRuntime, suggestionsEnabled]);
 
+    // design-close-chrome Phase 2 — density contract (designsystem §4.2).
+    // When the `density` prop is supplied, drive the root `data-density`
+    // attribute that powers the `--space-density-multiplier` cascade in
+    // `tokens.css`.  When the prop is omitted, leave the attribute alone
+    // so the host (or `useDensity()`) retains control — the prop is
+    // strictly an opt-in override, mirroring React's controlled vs.
+    // uncontrolled input pattern.  On unmount the attribute is left in
+    // place so a subsequent host-managed setter (e.g. the density picker
+    // in the shell view menu) can persist without a flicker.
+    useEffect(() => {
+      if (density === undefined) return;
+      if (typeof document === "undefined") return;
+      document.documentElement.dataset.density = density;
+    }, [density]);
+
     const markCurrentSectionForReview = useCallback((input?: {
       sectionIndex?: number;
       label?: string;
@@ -1540,14 +1610,18 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         return;
       }
 
-      setLocalCursorState(awareness, {
-        userId: currentUser.userId,
-        displayName: currentUser.displayName,
-        color: getCursorColorForUser(currentUser.userId),
-        anchor: snapshot.selection.anchor,
-        head: snapshot.selection.head,
-        storyTarget: snapshot.activeStory,
-      });
+      if (suppressNextAwarenessPublishRef.current) {
+        suppressNextAwarenessPublishRef.current = false;
+      } else {
+        setLocalCursorState(awareness, {
+          userId: currentUser.userId,
+          displayName: currentUser.displayName,
+          color: getCursorColorForUser(currentUser.userId),
+          anchor: snapshot.selection.anchor,
+          head: snapshot.selection.head,
+          storyTarget: snapshot.activeStory,
+        });
+      }
     }, [
       awareness,
       currentUser.displayName,
@@ -1572,7 +1646,17 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
 
     useImperativeHandle(
       ref,
-      () => ({
+      () => {
+        // v2.0.0 Track D — projections dispatch through a holder so they
+        // always point at the freshly-built ref on every
+        // useImperativeHandle re-run.
+        const refHolder: { current: WordReviewEditorRef | null } = { current: null };
+        const projections = buildRefProjections(() => {
+          const r = refHolder.current;
+          if (!r) throw new Error("ref projection used before ref initialization");
+          return r;
+        });
+        const refValue: WordReviewEditorRef = ({
         focus: () => activeRuntime.focus(),
         blur: () => activeRuntime.blur(),
         undo: () => activeRuntime.undo(),
@@ -1607,6 +1691,12 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         addScope: (params) => activeRuntime.addScope(params),
         getScope: (scopeId) => activeRuntime.getScope(scopeId),
         removeScope: (scopeId) => activeRuntime.removeScope(scopeId),
+        addInvisibleScope: (params) => activeRuntime.addInvisibleScope(params),
+        setScopeVisibility: (scopeId, visibility) => activeRuntime.setScopeVisibility(scopeId, visibility),
+        getScopeVisibility: (scopeId) => activeRuntime.getScopeVisibility(scopeId),
+        setScopeChromeVisibility: (state) => activeRuntime.setScopeChromeVisibility(state),
+        getScopeChromeVisibility: () => activeRuntime.getScopeChromeVisibility(),
+        subscribeToScopeQuery: (filter, callback) => activeRuntime.subscribeToScopeQuery(filter, callback),
         acceptChange: (changeId) => activeRuntime.acceptChange(changeId),
         rejectChange: (changeId) => activeRuntime.rejectChange(changeId),
         acceptAllChanges: () => activeRuntime.acceptAllChanges(),
@@ -1821,11 +1911,22 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         clearSearch: () => {
           surfaceRef.current?.clearSearch();
         },
-        setSelection: (selection) => {
-          applyRuntimeSelection(
-            activeRuntime,
-            normalizeRequestedSelection(activeRuntime.getRenderSnapshot(), selection),
-          );
+        setSelection: (selection, options?: SetSelectionOptions) => {
+          const snap = activeRuntime.getRenderSnapshot();
+          const normalized = normalizeRequestedSelection(snap, selection);
+          if (options?.silent) {
+            // Only suppress awareness publish if the selection will actually change.
+            // If positions are identical the cursor-state useEffect won't re-run,
+            // which would leave the flag set and silently suppress the next real
+            // selection change (stale-flag bug).
+            if (
+              normalized.anchor !== snap.selection.anchor ||
+              normalized.head !== snap.selection.head
+            ) {
+              suppressNextAwarenessPublishRef.current = true;
+            }
+          }
+          applyRuntimeSelection(activeRuntime, normalized);
         },
         scrollToRevision: (revisionId: string) => {
           const revision = activeRuntime.getRenderSnapshot().trackedChanges.revisions.find(
@@ -1976,6 +2077,36 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         getWorkflowMetadataSnapshot: () => {
           return clonePublicValue(activeRuntime.getWorkflowMetadataSnapshot());
         },
+        queryScopes: (filter) => {
+          return clonePublicValue(activeRuntime.queryScopes(filter));
+        },
+        findScopesAt: (position, options) => {
+          return clonePublicValue(activeRuntime.findScopesAt(position, options));
+        },
+        findScopesIntersecting: (range, options) => {
+          return clonePublicValue(activeRuntime.findScopesIntersecting(range, options));
+        },
+        findFirstText: (query, opts) => {
+          const hits = findTextMatchesForRuntime(activeRuntime, query, opts);
+          return hits.length > 0 ? (hits[0] ?? null) : null;
+        },
+        findAllText: (query, opts) => {
+          return findTextMatchesForRuntime(activeRuntime, query, opts);
+        },
+        selectFirstText: (query, opts) => {
+          const hits = findTextMatchesForRuntime(activeRuntime, query, opts);
+          if (hits.length === 0) return false;
+          applyRuntimeSelection(activeRuntime, createSelectionFromAnchor(hits[0]!));
+          return true;
+        },
+        selectAllText: (query, opts) => {
+          const hits = findTextMatchesForRuntime(activeRuntime, query, opts);
+          if (hits.length === 0) return 0;
+          applyRuntimeSelection(activeRuntime, createSelectionFromAnchor(hits[0]!));
+          return hits.length;
+        },
+        findTextWithStyle: (query, filter, opts) => activeRuntime.findTextWithStyle(query, filter, opts),
+        selectTextWithStyle: (query, filter, opts) => activeRuntime.selectTextWithStyle(query, filter, opts),
         // P17 — metadata persistence toggle + convert methods.
         setMetadataPersistenceMode: (mode) => {
           if (mode === "external" && scopeMetadataResolverRef.current === null) {
@@ -2170,7 +2301,11 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         replaceWorkflowMarkupText: (markupId, text) => {
           activeRuntime.replaceWorkflowMarkupText(markupId, text);
         },
-      }),
+        ...projections,
+      }) as WordReviewEditorRef;
+        refHolder.current = refValue;
+        return refValue;
+      },
       [
         activeRuntime,
         clearReviewSectionMarkById,
@@ -2484,29 +2619,40 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       suggestionsSnapshot,
       viewState.activeStory,
     ]);
-    const activeSelectionTool = resolveActiveSelectionTool({
-      snapshot,
-      viewState,
-      capabilities,
-      documentNavigation,
-      styleCatalog,
-      formattingState,
-      workflowScopeSnapshot,
-      interactionGuardSnapshot,
-      workflowMarkupSnapshot: workflowMarkupSnapshot ?? undefined,
-      suggestionsSnapshot,
-      activeRevisionId,
-      activeCommentId: snapshot.comments.activeCommentId,
-      activeCommentThread,
-      activeTableContext,
-      activeImageContext,
-      activeObjectContext,
-      activeListContext: viewState.activeListContext,
-      preferListStructureContext: viewState.workspaceMode === "page",
-      addCommentDisabledReason,
-      suppressedSuggestionRevisionId,
-      scopedChromePolicy,
-    });
+    // R9 — host may supply custom selection-tool registry entries; merge
+    // with the default before resolving.  The merger is a pure function
+    // returning the canonical default array by reference when `custom`
+    // is empty, so the typical no-custom case is a single identity call.
+    const selectionToolRegistry = useMemo(
+      () => resolveSelectionToolRegistry(customSelectionTools),
+      [customSelectionTools],
+    );
+    const activeSelectionTool = resolveActiveSelectionTool(
+      {
+        snapshot,
+        viewState,
+        capabilities,
+        documentNavigation,
+        styleCatalog,
+        formattingState,
+        workflowScopeSnapshot,
+        interactionGuardSnapshot,
+        workflowMarkupSnapshot: workflowMarkupSnapshot ?? undefined,
+        suggestionsSnapshot,
+        activeRevisionId,
+        activeCommentId: snapshot.comments.activeCommentId,
+        activeCommentThread,
+        activeTableContext,
+        activeImageContext,
+        activeObjectContext,
+        activeListContext: viewState.activeListContext,
+        preferListStructureContext: viewState.workspaceMode === "page",
+        addCommentDisabledReason,
+        suppressedSuggestionRevisionId,
+        scopedChromePolicy,
+      },
+      selectionToolRegistry,
+    );
     const selectionToolbarSelectionKey = useMemo(
       () =>
         createSelectionToolbarSelectionKey(
@@ -3237,6 +3383,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         )}
         visuallyHiddenStyles={VISUALLY_HIDDEN_STYLES}
         onShellKeyDownCapture={handleShellKeyDownCapture}
+        shellHeader={shellHeader}
         viewState={viewState}
         markupDisplay={liveMarkupDisplay}
         currentUserId={currentUser.userId}
@@ -3339,6 +3486,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         onScopeRejectSuggestionGroup={(payload) => {
           applySuggestionGroupAction(activeRuntime, payload.groupId, "reject");
         }}
+        onDeselectObject={() => activeRuntime.deselectObject()}
         onScopeAskAgent={(payload) => {
           // Resolve the scope's anchor + story from the facet's card
           // model so the agent request carries the canonical range.
@@ -3393,13 +3541,28 @@ function applySuggestionGroupAction(
 ): void {
   const snapshot = runtime.getSuggestionsSnapshot();
   const group = snapshot.groups?.find((entry) => entry.groupId === groupId);
-  if (!group) return;
+  const op = action === "accept" ? "acceptSuggestionGroup" : "rejectSuggestionGroup";
+  if (!group) {
+    runtime.emitTransientWarning({
+      warningId: `suggestion-group-unknown-${groupId}-${Date.now()}`,
+      code: "review_target_not_found",
+      severity: "info",
+      message: `${op}("${groupId}") skipped: unknown groupId.`,
+      source: "review",
+      details: { op, targetId: groupId, reason: "group_unknown" },
+    });
+    return;
+  }
   const byId = new Map(
     snapshot.suggestions.map((entry) => [entry.suggestionId, entry]),
   );
+  const skippedSuggestions: string[] = [];
   for (const suggestionId of group.suggestionIds) {
     const suggestion = byId.get(suggestionId);
-    if (!suggestion) continue;
+    if (!suggestion) {
+      skippedSuggestions.push(suggestionId);
+      continue;
+    }
     for (const changeId of suggestion.changeIds) {
       if (action === "accept") {
         runtime.acceptChange(changeId);
@@ -3408,6 +3571,21 @@ function applySuggestionGroupAction(
       }
     }
   }
+  if (skippedSuggestions.length > 0) {
+    runtime.emitTransientWarning({
+      warningId: `suggestion-group-stale-${groupId}-${Date.now()}`,
+      code: "review_target_not_found",
+      severity: "info",
+      message: `${op}("${groupId}") partially skipped: ${skippedSuggestions.length} suggestion(s) no longer in snapshot.`,
+      source: "review",
+      details: {
+        op,
+        targetId: groupId,
+        reason: "suggestion_stale",
+        skippedSuggestionIds: skippedSuggestions,
+      },
+    });
+  }
 }
 
 function applyRuntimeFormattingOperation(
@@ -4980,12 +5158,34 @@ function applyRuntimeDeleteComment(
   commentId: string,
 ): void {
   const snapshot = runtime.getRenderSnapshot();
-  if (!snapshot.isReady || snapshot.readOnly || snapshot.fatalError) {
+  // Pre-ready / fatal states stay silent: the host called too early, and
+  // there is no meaningful document yet to signal against. Emitting a
+  // warning here would only add noise to load-time error handling.
+  if (!snapshot.isReady || snapshot.fatalError) {
+    return;
+  }
+  if (snapshot.readOnly) {
+    runtime.emitTransientWarning({
+      warningId: `delete-comment-readonly-${commentId}-${Date.now()}`,
+      code: "review_target_not_found",
+      severity: "info",
+      message: `deleteComment("${commentId}") skipped: editor is read-only.`,
+      source: "review",
+      details: { op: "deleteComment", targetId: commentId, reason: "read_only" },
+    });
     return;
   }
 
   const sessionState = runtime.getSessionState();
   if (!sessionState.canonicalDocument.review.comments[commentId]) {
+    runtime.emitTransientWarning({
+      warningId: `delete-comment-unknown-${commentId}-${Date.now()}`,
+      code: "review_target_not_found",
+      severity: "info",
+      message: `deleteComment("${commentId}") skipped: unknown commentId.`,
+      source: "review",
+      details: { op: "deleteComment", targetId: commentId, reason: "comment_unknown" },
+    });
     return;
   }
 
@@ -5056,6 +5256,20 @@ function clonePublicValue<T>(value: T): T {
   return structuredClone(value);
 }
 
+function findTextMatchesForRuntime(
+  runtime: WordReviewEditorRuntime,
+  query: string,
+  options: SearchOptions | undefined,
+): EditorAnchorProjection[] {
+  const snapshot = runtime.getRenderSnapshot();
+  return findTextMatches(
+    runtime.getSessionState().canonicalDocument,
+    snapshot.selection,
+    query,
+    options ?? {},
+  );
+}
+
 /**
  * Open the correct header/footer story for a specific page.  The page's
  * resolved `stories.header` / `stories.footer` already carries the

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

@@ -1015,6 +1015,7 @@ function createLoadingRuntimeBridge(input: {
     subscribe: () => () => undefined,
     subscribeToEvents: () => () => undefined,
     emitBlockedCommand: () => undefined,
+    emitTransientWarning: () => undefined,
     getRenderSnapshot: () => {
       const progressive = input.progressiveSurfaceRef?.current;
       if (progressive == null) return input.snapshot;
@@ -1154,6 +1155,9 @@ function createLoadingRuntimeBridge(input: {
       definitions: [],
       entries: [],
     }),
+    queryScopes: () => [],
+    findScopesAt: () => [],
+    findScopesIntersecting: () => [],
     setHostAnnotationOverlay: () => undefined,
     clearHostAnnotationOverlay: () => undefined,
     getHostAnnotationSnapshot: () => ({
@@ -1183,6 +1187,15 @@ function createLoadingRuntimeBridge(input: {
     resetPerfCounters: () => undefined,
     setVisibleBlockRange: () => undefined,
     requestViewportRefresh: () => undefined,
+    addInvisibleScope: () => ({ scopeId: "", anchor: { kind: "range", from: 0, to: 0, assoc: { start: -1, end: 1 } } }),
+    setScopeVisibility: () => undefined,
+    getScopeVisibility: () => "visible" as const,
+    setScopeChromeVisibility: () => undefined,
+    getScopeChromeVisibility: () => ({ mode: "all" as const }),
+    subscribeToScopeQuery: (_filter, _callback) => () => undefined,
+    findAllText: () => [],
+    findTextWithStyle: () => [],
+    selectTextWithStyle: () => 0,
   };
 }
 

package/src/ui/editor-shell-view.tsx

@@ -82,6 +82,7 @@ export interface EditorShellViewProps {
   selectionToolAnchor?: SelectionToolAnchor | null;
   documentNavigation?: DocumentNavigationSnapshot;
   commands: EditorCommandBag;
+  shellHeader?: ReactNode;
   document: ReactNode;
   onAddCommentFromSelection?: () => void;
   onAddCommentFromSuggestion?: () => void;
@@ -126,6 +127,8 @@ export interface EditorShellViewProps {
   }) => void;
   /** K2 — forwarded from workspace to WordReviewEditor. */
   onScopeAskAgent?: (payload: { scopeId: string }) => void;
+  /** N6 — deselects the currently grabbed object; wired to runtime.deselectObject(). */
+  onDeselectObject?: () => void;
 }
 
 export function EditorShellView(props: EditorShellViewProps) {
@@ -154,7 +157,7 @@ export function EditorShellView(props: EditorShellViewProps) {
       aria-describedby={`${accessibilityInstructionsId} ${accessibilityStatusId}${
         diagnosticsModeMessage ? ` ${accessibilityAlertId}` : ""
       }`}
-      className="wre-editor relative h-full"
+      className="wre-editor wre-editor-root relative h-full"
       onKeyDownCapture={onShellKeyDownCapture}
     >
       <p id={accessibilityInstructionsId} style={visuallyHiddenStyles}>

package/src/ui/headless/chrome-registry.ts

@@ -102,6 +102,59 @@ export const SELECTION_TOOL_REGISTRY: ReadonlyArray<SelectionToolRegistryEntry>
   { id: "blocked-explainer", surfaces: ["selection-tool"], group: "blocked", precedence: 60 },
 ];
 
+/**
+ * R10 — options for `resolveSelectionToolRegistry`.
+ *
+ * `remove` lets a host suppress a default kind entirely (the dedicated
+ * builder for that kind is skipped at resolve time).  Used together
+ * with `custom` when the host wants to both add a new precedence and
+ * silence an existing one.
+ */
+export interface ResolveSelectionToolRegistryOptions {
+  remove?: ReadonlyArray<SelectionToolRegistryEntry["id"]>;
+}
+
+/**
+ * Merge host-supplied selection-tool entries with the default registry.
+ *
+ * design-close-chrome Phase 4 / designsystem §6 extensibility.  Pure
+ * function — callers supply `custom` as a stable array (memoize in
+ * React), this returns a fresh, precedence-sorted copy that the
+ * resolver can iterate.  Dedupe rule: host entries win on id collision
+ * (they override default precedence for that id).  When `options.remove`
+ * lists ids, those are filtered out of the default set before merging.
+ *
+ * Note: as of this Phase, the resolver builder matrix (see
+ * `buildSelectionToolFromRegistryEntry` in `selection-tool-resolver.ts`)
+ * still only understands the built-in `SelectionToolKind` union.
+ * Widening that union to accept host render functions is a downstream
+ * change coordinated with Lane 8 API ergonomics; the merger is shipped
+ * first so callers can depend on the final shape while the renderer
+ * catches up.
+ */
+export function resolveSelectionToolRegistry(
+  custom?: ReadonlyArray<SelectionToolRegistryEntry>,
+  options?: ResolveSelectionToolRegistryOptions,
+): ReadonlyArray<SelectionToolRegistryEntry> {
+  const remove = options?.remove;
+  const hasCustom = custom && custom.length > 0;
+  const hasRemove = remove && remove.length > 0;
+  if (!hasCustom && !hasRemove) return SELECTION_TOOL_REGISTRY;
+  const removed = new Set(remove ?? []);
+  const byId = new Map<SelectionToolRegistryEntry["id"], SelectionToolRegistryEntry>();
+  for (const entry of SELECTION_TOOL_REGISTRY) {
+    if (removed.has(entry.id)) continue;
+    byId.set(entry.id, entry);
+  }
+  for (const entry of custom ?? []) {
+    // Host entries are NOT filtered by `remove` — callers can always
+    // install an entry they meant to keep even when a matching default
+    // would otherwise have been suppressed.
+    byId.set(entry.id, entry);
+  }
+  return [...byId.values()].sort((a, b) => a.precedence - b.precedence);
+}
+
 export const TOOLBAR_CHROME_REGISTRY: ReadonlyArray<ToolbarChromeRegistryEntry> = [
   {
     id: "history",

package/src/ui/headless/selection-tool-resolver.ts

@@ -23,10 +23,20 @@ import {
 } from "./chrome-registry";
 import { shouldRenderSelectionToolKind } from "./scoped-chrome-policy";
 
+/**
+ * Resolve the active selection tool for `input`.
+ *
+ * `registry` defaults to the canonical `SELECTION_TOOL_REGISTRY`.  Hosts
+ * that want to reorder or shadow default precedences pass in the result
+ * of `resolveSelectionToolRegistry(props.customSelectionTools, options)`.
+ * Entries iterate in the order provided — callers are responsible for
+ * supplying a precedence-sorted array.
+ */
 export function resolveActiveSelectionTool(
   input: SelectionToolResolverInput,
+  registry: ReadonlyArray<SelectionToolRegistryEntry> = SELECTION_TOOL_REGISTRY,
 ): ActiveSelectionToolModel | null {
-  for (const entry of SELECTION_TOOL_REGISTRY) {
+  for (const entry of registry) {
     if (!shouldRenderSelectionToolKind(input.scopedChromePolicy, entry.id)) {
       continue;
     }

package/src/ui-tailwind/chrome/chrome-preset-model.ts

@@ -1,4 +1,5 @@
 import type {
+  EditorRole,
   WordReviewEditorChromeOptions,
   WordReviewEditorChromePreset,
   WordReviewEditorChromeVisibility,
@@ -21,6 +22,7 @@ export function resolveChromePreset(
 export function resolveChromePresetOptions(
   chromePreset: WordReviewEditorChromePreset,
   overrides?: Partial<WordReviewEditorChromeOptions>,
+  editorRole?: EditorRole,
 ): WordReviewEditorChromeOptions {
   const defaults: Record<WordReviewEditorChromePreset, WordReviewEditorChromeOptions> = {
     selection: {
@@ -73,10 +75,21 @@ export function resolveChromePresetOptions(
 
   return {
     ...defaults[chromePreset],
+    ...resolveRoleAdjustments(editorRole),
     ...overrides,
   };
 }
 
+function resolveRoleAdjustments(role: EditorRole | undefined): Partial<WordReviewEditorChromeOptions> {
+  if (role === "editor") {
+    return { showReviewRail: false, showReviewQueueBar: false };
+  }
+  if (role === "workflow") {
+    return { showReviewQueueBar: false };
+  }
+  return {};
+}
+
 export function resolveChromeVisibilityForPreset(input: {
   chromePreset: WordReviewEditorChromePreset;
   chromeOptions?: Partial<WordReviewEditorChromeOptions>;