@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/ui-tailwind/review-workspace/use-scope-card-state.ts

@@ -0,0 +1,170 @@
+import { useCallback, useEffect, useState } from "react";
+
+import type {
+  EditorAnchorProjection,
+  ScopeIssueAction,
+  WorkflowScopeMode,
+} from "../../api/public-types.ts";
+import {
+  cycleScopeIndex,
+  shouldHandleScopeNavKey,
+} from "../chrome-overlay/scope-keyboard-cycle";
+
+export interface UseScopeCardStateOptions {
+  layoutFacet?: import("../../runtime/layout/index.ts").WordReviewEditorLayoutFacet;
+  /**
+   * Layer-06 workflow facet — canonical source of scope card models.
+   * Required by the keyboard-nav loop + Ask-agent handler after Slice 4
+   * rail-seam inversion removed those methods from `layoutFacet`.
+   */
+  workflowFacet?: import("../../runtime/workflow/rail/types.ts").WorkflowFacet;
+  onScopeModeChangeRequested?: (payload: {
+    scopeId: string;
+    mode: WorkflowScopeMode;
+  }) => void;
+  onScopeIssueActionRequested?: (payload: {
+    scopeId: string;
+    issueId: string;
+    action: ScopeIssueAction;
+  }) => void;
+  onScopeAcceptSuggestionGroup?: (payload: {
+    scopeId: string;
+    groupId: string;
+  }) => void;
+  onScopeRejectSuggestionGroup?: (payload: {
+    scopeId: string;
+    groupId: string;
+  }) => void;
+  onScopeAskAgent?: (payload: {
+    scopeId: string;
+    anchor?: EditorAnchorProjection;
+  }) => void;
+}
+
+export interface ScopeCardState {
+  activeScopeId: string | null;
+  handleScopeStripeClick: (segment: { scopeId: string }) => void;
+  handleScopeCardClose: () => void;
+  handleScopeCardModeChange: (scopeId: string, mode: WorkflowScopeMode) => void;
+  handleScopeCardIssueAction: (
+    scopeId: string,
+    issueId: string,
+    action: ScopeIssueAction,
+  ) => void;
+  handleScopeCardAcceptSuggestionGroup: (scopeId: string, groupId: string) => void;
+  handleScopeCardRejectSuggestionGroup: (scopeId: string, groupId: string) => void;
+  handleScopeCardAskAgent: (scopeId: string) => void;
+}
+
+/**
+ * Scope-card open/close state + keyboard navigation + all scope-card
+ * callback handlers. Extracted from `tw-review-workspace.tsx`.
+ *
+ * The card closes on click-outside, Escape, or a repeat click on its
+ * stripe. J / K cycle the active scope in document order; Enter opens
+ * the first scope when none is active (P3d). Pure helpers
+ * `shouldHandleScopeNavKey` + `cycleScopeIndex` back the keyboard
+ * logic so it remains unit-testable without a workspace mount.
+ */
+export function useScopeCardState(options: UseScopeCardStateOptions): ScopeCardState {
+  const {
+    layoutFacet,
+    workflowFacet,
+    onScopeModeChangeRequested,
+    onScopeIssueActionRequested,
+    onScopeAcceptSuggestionGroup,
+    onScopeRejectSuggestionGroup,
+    onScopeAskAgent,
+  } = options;
+  void layoutFacet;
+
+  const [activeScopeId, setActiveScopeId] = useState<string | null>(null);
+
+  const handleScopeStripeClick = useCallback(
+    (segment: { scopeId: string }) => {
+      setActiveScopeId((current) =>
+        current === segment.scopeId ? null : segment.scopeId,
+      );
+    },
+    [],
+  );
+
+  const handleScopeCardClose = useCallback(() => {
+    setActiveScopeId(null);
+  }, []);
+
+  useEffect(() => {
+    if (!workflowFacet) {
+      return undefined;
+    }
+    const onKey = (event: KeyboardEvent) => {
+      if (!shouldHandleScopeNavKey(event)) return;
+      const models = workflowFacet.getAllScopeCardModels();
+      if (models.length === 0) return;
+      const ids = models.map((model) => model.scopeId);
+      const key = event.key.toLowerCase();
+      if (key === "enter") {
+        if (!activeScopeId) {
+          setActiveScopeId(ids[0] ?? null);
+          event.preventDefault();
+        }
+        return;
+      }
+      const direction: 1 | -1 = key === "j" ? 1 : -1;
+      const next = cycleScopeIndex(activeScopeId, ids, direction);
+      setActiveScopeId(next);
+      event.preventDefault();
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [workflowFacet, activeScopeId]);
+
+  const handleScopeCardModeChange = useCallback(
+    (scopeId: string, mode: WorkflowScopeMode) => {
+      onScopeModeChangeRequested?.({ scopeId, mode });
+    },
+    [onScopeModeChangeRequested],
+  );
+
+  const handleScopeCardIssueAction = useCallback(
+    (scopeId: string, issueId: string, action: ScopeIssueAction) => {
+      onScopeIssueActionRequested?.({ scopeId, issueId, action });
+    },
+    [onScopeIssueActionRequested],
+  );
+
+  const handleScopeCardAcceptSuggestionGroup = useCallback(
+    (scopeId: string, groupId: string) => {
+      onScopeAcceptSuggestionGroup?.({ scopeId, groupId });
+    },
+    [onScopeAcceptSuggestionGroup],
+  );
+
+  const handleScopeCardRejectSuggestionGroup = useCallback(
+    (scopeId: string, groupId: string) => {
+      onScopeRejectSuggestionGroup?.({ scopeId, groupId });
+    },
+    [onScopeRejectSuggestionGroup],
+  );
+
+  const handleScopeCardAskAgent = useCallback(
+    (scopeId: string) => {
+      const cardModel = workflowFacet
+        ?.getAllScopeCardModels()
+        .find((m) => m.scopeId === scopeId);
+      onScopeAskAgent?.({ scopeId, anchor: cardModel?.anchor });
+    },
+    [onScopeAskAgent, workflowFacet],
+  );
+
+  return {
+    activeScopeId,
+    handleScopeStripeClick,
+    handleScopeCardClose,
+    handleScopeCardModeChange,
+    handleScopeCardIssueAction,
+    handleScopeCardAcceptSuggestionGroup,
+    handleScopeCardRejectSuggestionGroup,
+    handleScopeCardAskAgent,
+  };
+}

package/src/ui-tailwind/review-workspace/use-scroll-root-capture.ts

@@ -0,0 +1,28 @@
+import { useEffect, useRef, useState, type RefObject } from "react";
+
+export interface ScrollRootCapture {
+  scrollRootRef: RefObject<HTMLDivElement | null>;
+  pageStackScrollRoot: HTMLElement | null;
+}
+
+/**
+ * P8.11 — capture the scroll-root DOM element on mount so the chrome
+ * overlay's `TwPageStackChromeLayer` can measure per-page rects and
+ * observe DOM mutations. `scrollRootRef` is attached to the existing
+ * `[data-wre-scroll-root]` container; rely on a mount effect rather
+ * than a ref callback so render-time state stays cheap. The
+ * comparison guard in the effect keeps `setPageStackScrollRoot` from
+ * firing every commit.
+ */
+export function useScrollRootCapture(): ScrollRootCapture {
+  const scrollRootRef = useRef<HTMLDivElement | null>(null);
+  const [pageStackScrollRoot, setPageStackScrollRoot] = useState<HTMLElement | null>(null);
+
+  useEffect(() => {
+    if (scrollRootRef.current !== pageStackScrollRoot) {
+      setPageStackScrollRoot(scrollRootRef.current);
+    }
+  });
+
+  return { scrollRootRef, pageStackScrollRoot };
+}

package/src/ui-tailwind/review-workspace/use-selection-toolbar-placement.ts

@@ -0,0 +1,113 @@
+import { useMemo, type RefObject } from "react";
+
+import type { EditorViewStateSnapshot } from "../../api/public-types";
+import type {
+  ActiveSelectionToolModel,
+  SelectionToolAnchor,
+} from "../../ui/headless/selection-tool-types";
+import { resolveSelectionToolPlacement } from "../chrome/tw-selection-tool-placement";
+import { useUiApi } from "../ui-api-context";
+
+import { resolveSelectionToolbarPlacement } from "./selection-toolbar-placement.ts";
+
+export interface UseSelectionToolbarPlacementOptions {
+  gatedSelectionTool: ActiveSelectionToolModel | null;
+  selection: EditorViewStateSnapshot["selection"];
+  selectionToolAnchor: SelectionToolAnchor | null | undefined;
+  zoomScale: number;
+  renderFrameRevision: number;
+  selectionToolbarRootRef: RefObject<HTMLDivElement | null>;
+}
+
+/**
+ * Compute placement for the floating selection toolbar.
+ *
+ * Resolution order (flicker-remediation 2026-04-22):
+ *
+ *   1. Legacy `resolveSelectionToolbarPlacement` driven by the
+ *      host-supplied `selectionToolAnchor` prop + the toolbar root's
+ *      `getBoundingClientRect()`. This path correctly handles
+ *      viewport-to-container translation + zoom scaling. It was the
+ *      original pre-DS-C1 path, is demonstrably correct, and is
+ *      populated every render by the shell — so it does not race with
+ *      bridge publication order.
+ *
+ *   2. `ui.overlays.getAnchor({ kind: "selection" })` fallback when
+ *      the host hasn't populated `selectionToolAnchor`. The UI API
+ *      returns a frame-local rect; projecting it into container-local
+ *      coordinates is a documented TODO (the bridge rect's
+ *      `space: "frame"` is tracked but not yet translated in this
+ *      placement path). Until that projection lands, this branch is
+ *      best-effort for consumers that don't supply the legacy prop —
+ *      e.g. future headless / Playwright drivers.
+ *
+ * DS-C1 (designsystem.md §8.8.1 "Selection toolbar" row) still routes
+ * anchor READS through the UI API in principle; the shell bridge
+ * (`useShellSelectionAnchorBridge`) continues publishing tool-aware
+ * rects so `ui.overlays.getAnchor({ kind: "selection" })` returns a
+ * meaningful rect for the debug service, Playwright, and the UI-API
+ * consumer tests. The placement hook's priority change is strictly a
+ * flicker-remediation concession: same source of truth, correct
+ * coordinate space.
+ *
+ * The memo re-runs when the geometry facet bumps `renderFrameRevision`
+ * so placement tracks new rects without a separate subscription here.
+ */
+export function useSelectionToolbarPlacement(
+  options: UseSelectionToolbarPlacementOptions,
+): ReturnType<typeof resolveSelectionToolbarPlacement> {
+  const {
+    gatedSelectionTool,
+    selection,
+    selectionToolAnchor,
+    zoomScale,
+    renderFrameRevision,
+    selectionToolbarRootRef,
+  } = options;
+  const ui = useUiApi();
+
+  return useMemo(() => {
+    // Primary: legacy DOM-anchor path. Correct coord space; no bridge
+    // timing dependency.
+    const legacy = resolveSelectionToolbarPlacement(
+      selectionToolAnchor,
+      selectionToolbarRootRef.current,
+      zoomScale,
+    );
+    if (legacy) return legacy;
+
+    // Fallback: UI API anchor for consumers that don't populate
+    // `selectionToolAnchor`. Coord-space projection TODO — the bridge
+    // rect is frame-local, `resolveSelectionToolPlacement` assumes
+    // container-local. Best-effort until projection lands.
+    if (ui && gatedSelectionTool) {
+      const anchorRect = ui.overlays.getAnchor({ kind: "selection" });
+      if (anchorRect && selectionToolbarRootRef.current) {
+        const containerRect =
+          selectionToolbarRootRef.current.getBoundingClientRect();
+        const result = resolveSelectionToolPlacement({
+          anchor: {
+            leftPx: anchorRect.leftPx,
+            topPx: anchorRect.topPx,
+            widthPx: anchorRect.widthPx,
+            heightPx: anchorRect.heightPx,
+          },
+          container: {
+            widthPx: containerRect.width,
+            heightPx: containerRect.height,
+          },
+        });
+        if (result) return result;
+      }
+    }
+    return null;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    ui,
+    selectionToolAnchor,
+    gatedSelectionTool,
+    selection,
+    zoomScale,
+    renderFrameRevision,
+  ]);
+}

package/src/ui-tailwind/review-workspace/use-shell-selection-anchor-bridge.ts

@@ -0,0 +1,120 @@
+/**
+ * Shell-side writer for the overlay-anchor bridge (DS-C1).
+ *
+ * Publishes a `getSelectionAnchor` closure on every render so that
+ * `ui.overlays.getAnchor({ kind: "selection" })` returns the current
+ * selection rect without re-creating the UI API or the controller.
+ *
+ * Pairs with `src/shell/overlay-anchor-bridge.ts` +
+ * `src/ui/ui-controller-factory.ts` + `OverlayAnchorBridgeProvider`.
+ * When no bridge provider is mounted (headless / tests), this hook is
+ * a no-op.
+ *
+ * The resolver is written during render (not from an effect) so
+ * readers that call `ui.overlays.getAnchor({ kind: "selection" })`
+ * inside the same render pass — specifically
+ * `useSelectionToolbarPlacement` — see the current-render inputs, not
+ * the previous render's. The bridge itself is a mutable ref-box; the
+ * write is idempotent and free of React-scheduling hazards.
+ *
+ * A `useEffect` cleanup runs on unmount to clear the bridge so the
+ * controller returns `null` (U4) after the tree tears down. The
+ * cleanup only fires on unmount (empty deps), never on re-render,
+ * because we rewrite the resolver on every render and React would
+ * otherwise clobber a live resolver mid-render.
+ */
+
+import { useEffect, useRef } from "react";
+
+import type { GeometryRect } from "../../api/v3/ui/_types.ts";
+import type {
+  EditorViewStateSnapshot,
+  GeometryFacet,
+} from "../../api/public-types";
+import type { ActiveSelectionToolModel } from "../../ui/headless/selection-tool-types";
+import type { ShellOverlayAnchorBridge } from "../../shell/overlay-anchor-bridge.ts";
+import { resolveSelectionAnchor } from "../chrome/tw-selection-anchor-resolver";
+import { useOverlayAnchorBridge } from "../overlay-anchor-bridge-context.tsx";
+
+export interface UseShellSelectionAnchorBridgeOptions {
+  /** Runtime geometry facet — kernel source for render-frame rects. */
+  geometryFacet?: GeometryFacet;
+  /** Current selection snapshot from the runtime view-state. */
+  selection: EditorViewStateSnapshot["selection"];
+  /** Current active (gated) selection tool. */
+  gatedSelectionTool: ActiveSelectionToolModel | null;
+  /**
+   * Bumps when the geometry facet emits a new render frame; the
+   * publication runs during render anyway, so this field is carried
+   * for API symmetry with the consumer hook (placement) whose memo
+   * tracks it.
+   */
+  renderFrameRevision: number;
+}
+
+/**
+ * Publishes `bridge.getSelectionAnchor` synchronously during render.
+ * Consumers read through `ui.overlays.getAnchor({ kind: "selection" })`
+ * in the same render pass and see the current-render inputs.
+ */
+export function useShellSelectionAnchorBridge(
+  options: UseShellSelectionAnchorBridgeOptions,
+): void {
+  const bridge = useOverlayAnchorBridge();
+  const { geometryFacet, selection, gatedSelectionTool } = options;
+
+  // Synchronous write during render. Mutating a ref-box here is safe:
+  // the bridge is not React state, the write is idempotent, and the
+  // bridge identity is stable across renders (the controller closed
+  // over the same object at API construction).
+  if (bridge) {
+    bridge.getSelectionAnchor = () => {
+      if (!geometryFacet) return null;
+      const anchor = resolveSelectionAnchor({
+        geometryFacet,
+        selection,
+        tool: gatedSelectionTool,
+      });
+      if (!anchor) return null;
+      // `resolveSelectionAnchor` returns kernel-frame-local px. Tag as
+      // `frame` space so overlay consumers project through the same
+      // transform L05 uses for id-keyed anchors.
+      return {
+        leftPx: anchor.leftPx,
+        topPx: anchor.topPx,
+        widthPx: anchor.widthPx,
+        heightPx: anchor.heightPx,
+        space: "frame",
+      } satisfies GeometryRect;
+    };
+  }
+
+  // Clear on true unmount only. We track the bridge identity through
+  // a ref so the cleanup closure refers to the bridge that was live
+  // at cleanup time — not the bridge captured on the first render.
+  // This also guards the React StrictMode double-mount path: the
+  // post-mount cleanup previously nulled the resolver the render
+  // body had just written (StrictMode fires cleanup after the first
+  // mount, then re-mounts; without the ref guard the second mount
+  // would not re-run the render body and the resolver would stay
+  // null until the next render). The render-body assignment above
+  // runs every commit, so the ref write here never shadows a newer
+  // resolver unless `bridge` itself has changed identity.
+  const liveBridgeRef = useRef(bridge);
+  liveBridgeRef.current = bridge;
+  useEffect(() => {
+    return () => {
+      const current = liveBridgeRef.current;
+      if (current) {
+        current.getSelectionAnchor = null;
+      }
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+}
+
+/**
+ * Re-exported for consumers that want to peek at the bridge directly
+ * (tests, evidence runners). Not used by the placement hook.
+ */
+export type { ShellOverlayAnchorBridge };

package/src/ui-tailwind/review-workspace/use-status-bar-page-facts.ts

@@ -0,0 +1,55 @@
+import { useMemo } from "react";
+
+import type {
+  PublicMeasurementFidelity,
+  RuntimeRenderSnapshot,
+} from "../../api/public-types.ts";
+
+export interface StatusBarPageFacts {
+  displayPageNumber: number | null;
+  pageCount: number | null;
+  measurementFidelity: PublicMeasurementFidelity | undefined;
+}
+
+export interface UseStatusBarPageFactsOptions {
+  layoutFacet?: import("../../runtime/layout/index.ts").WordReviewEditorLayoutFacet;
+  selectionPosition: number;
+  activeStory: RuntimeRenderSnapshot["activeStory"];
+  renderFrameRevision: number;
+}
+
+/**
+ * P5b — status-bar facts derived from the layout facet so the
+ * Page-N-of-M display + measurement-fidelity badge ("E" / "C" / "C+F")
+ * refresh on every layout-affecting facet event. `renderFrameRevision`
+ * (bumped by `useLayoutFacetRenderSignal`) drives the memo; no separate
+ * subscription here.
+ */
+export function useStatusBarPageFacts(
+  options: UseStatusBarPageFactsOptions,
+): StatusBarPageFacts {
+  const { layoutFacet, selectionPosition, activeStory, renderFrameRevision } = options;
+
+  return useMemo(() => {
+    const facet = layoutFacet;
+    if (!facet) {
+      return {
+        displayPageNumber: null,
+        pageCount: null,
+        measurementFidelity: undefined,
+      };
+    }
+    const pageRef = facet.getPageForOffset(selectionPosition, activeStory);
+    const displayPageNumber =
+      pageRef !== null && typeof pageRef.pageIndex === "number"
+        ? facet.getDisplayPageNumber(pageRef.pageIndex) ?? pageRef.pageIndex + 1
+        : null;
+    const pageCount = facet.getPageCount();
+    return {
+      displayPageNumber,
+      pageCount,
+      measurementFidelity: facet.getMeasurementFidelity(),
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [layoutFacet, selectionPosition, activeStory, renderFrameRevision]);
+}

package/src/ui-tailwind/review-workspace/use-viewport-dimensions.ts

@@ -0,0 +1,43 @@
+import { useEffect, useState } from "react";
+
+import { readViewportHeight, readViewportWidth } from "./page-shell-metrics.ts";
+
+export interface ViewportDimensions {
+  viewportWidth: number | undefined;
+  viewportHeight: number | undefined;
+}
+
+/**
+ * Live window-dimension hook with SSR-safe initial read + `resize` listener.
+ * Extracted from `tw-review-workspace.tsx` so the viewport state is
+ * addressable on its own. The hook does not read DOM during a mutation;
+ * `readViewportWidth` / `readViewportHeight` return `undefined` under
+ * SSR, matching the prior inline behavior.
+ */
+export function useViewportDimensions(): ViewportDimensions {
+  const [viewportWidth, setViewportWidth] = useState<number | undefined>(
+    () => readViewportWidth(),
+  );
+  const [viewportHeight, setViewportHeight] = useState<number | undefined>(
+    () => readViewportHeight(),
+  );
+
+  useEffect(() => {
+    if (typeof window === "undefined") {
+      return;
+    }
+
+    const updateViewport = () => {
+      setViewportWidth(readViewportWidth());
+      setViewportHeight(readViewportHeight());
+    };
+
+    updateViewport();
+    window.addEventListener("resize", updateViewport);
+    return () => {
+      window.removeEventListener("resize", updateViewport);
+    };
+  }, []);
+
+  return { viewportWidth, viewportHeight };
+}

package/src/ui-tailwind/review-workspace/use-workspace-arbiter.ts

@@ -0,0 +1,25 @@
+import { useRef } from "react";
+
+import {
+  createLocalSurfaceArbiter,
+  type LocalSurfaceArbiter,
+} from "../chrome/local-surface-arbiter";
+
+/**
+ * Phase F.2 — per-workspace local-surface arbiter. Every floating
+ * surface inside the workspace (selection toolbar, scope card,
+ * suggestion card, context menu, comment preview) requests through this
+ * shared instance.
+ *
+ * Stable identity via `useRef` — the arbiter is an event-emitter with
+ * its own internal state, so recreating it per render would drop active
+ * requests. Consumers read it through the `LocalSurfaceArbiterContext`
+ * provider mounted in the workspace return tree.
+ */
+export function useWorkspaceArbiter(): LocalSurfaceArbiter {
+  const ref = useRef<LocalSurfaceArbiter | null>(null);
+  if (ref.current === null) {
+    ref.current = createLocalSurfaceArbiter();
+  }
+  return ref.current;
+}

package/src/ui-tailwind/review-workspace/use-workspace-composition.ts

@@ -0,0 +1,86 @@
+import { useMemo } from "react";
+
+import {
+  resolveChromeComposition,
+  type ChromeCompositionInput,
+} from "../../api/v3/ui";
+import { useUiApi } from "../ui-api-context";
+
+export type UseWorkspaceCompositionOptions = Pick<
+  ChromeCompositionInput,
+  | "chromePreset"
+  | "chromeOptions"
+  | "reviewMode"
+  | "role"
+  | "markupDisplay"
+  | "diagnosticsSignal"
+>;
+
+/**
+ * Memoized hook that returns the chrome composition for the workspace.
+ *
+ * When a `UiApiProvider` wraps the tree, this hook calls
+ * `ui.chrome.getComposition(input)` — the architectural path per
+ * architecture 10 §U5.b and designsystem §8.3 (the UI API owns
+ * composition decisions). When no provider is present, the hook falls
+ * back to `resolveChromeComposition` (the same function the UI API
+ * wraps) — so headless paths, the React harness, and tests behave
+ * identically without needing to mount a provider.
+ *
+ * The underlying function lives in layer 10 (`src/api/v3/ui/chrome-
+ * composition.ts`); the L11 re-export shim at
+ * `src/ui-tailwind/chrome/chrome-composition-model.ts` exists for other
+ * consumers mid-migration. This hook is the first mounted consumer to
+ * source from L10 directly (refactor/10 Slice 10).
+ *
+ * Memoization (perf invariant #4): `TwReviewWorkspace` re-renders on
+ * every PM transaction (`view.updateState()` wholesale replace in the
+ * inverted-truth architecture). `resolveChromeComposition` allocates
+ * new Sets + arrays on each call; `useMemo` keeps downstream
+ * `React.memo` consumers stable across commits.
+ *
+ * **Caller contract**: every option value passed into this hook MUST be
+ * referentially stable across renders that don't intend to trigger a
+ * re-composition — the memo's dep list compares by identity. In
+ * particular, `diagnosticsSignal` (built each render by
+ * `useDiagnosticsSignal`) and `chromeOptions` (host prop) must already
+ * be memoized by their source; passing a freshly-allocated object here
+ * thrashes the memo and cascades through every `React.memo` consumer
+ * downstream. Review M6 (2026-04-22) flagged this as a silent perf
+ * regression risk.
+ *
+ * `readOnly` is intentionally omitted from the option set: the
+ * composition seam is independent of read-only posture today; Phase E
+ * threads it through the interactionGuardSnapshot wiring once the rail
+ * owns the full posture composition.
+ */
+export function useWorkspaceComposition(
+  options: UseWorkspaceCompositionOptions,
+): ReturnType<typeof resolveChromeComposition> {
+  const ui = useUiApi();
+  const {
+    chromePreset,
+    chromeOptions,
+    reviewMode,
+    role,
+    markupDisplay,
+    diagnosticsSignal,
+  } = options;
+
+  return useMemo(
+    () => {
+      const input: ChromeCompositionInput = {
+        chromePreset,
+        chromeOptions,
+        reviewMode,
+        role,
+        markupDisplay,
+        diagnosticsSignal,
+      };
+      return ui
+        ? ui.chrome.getComposition(input)
+        : resolveChromeComposition(input);
+    },
+    [ui, chromePreset, chromeOptions, reviewMode, role, markupDisplay, diagnosticsSignal],
+  );
+}