@beyondwork/docx-react-component 1.0.67 → 1.0.70

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

@@ -4,6 +4,7 @@ import type {
   ActiveListContext,
   DocumentNavigationSnapshot,
   EditorError,
+  EditorRole,
   FormattingStateSnapshot,
   InteractionGuardSnapshot,
   ReviewQueueSnapshot,
@@ -17,7 +18,7 @@ import type {
   WorkspaceMode,
   ZoomLevel,
 } from "../api/public-types.ts";
-import type { SessionCapabilities } from "../runtime/session-capabilities.ts";
+import type { SessionCapabilities } from "../api/public-types.ts";
 import type { MarkupDisplay } from "./headless/comment-decoration-model.ts";
 import type {
   ActiveSelectionToolModel,
@@ -62,9 +63,31 @@ export interface EditorShellViewProps {
    * document column and the review rail's Workflow tab can read segments.
    */
   layoutFacet?: import("../runtime/layout/index.ts").WordReviewEditorLayoutFacet;
+  /**
+   * Layer-05 geometry facet (`runtime.geometry`). Passed through to
+   * `TwReviewWorkspace` which forwards it to the chrome overlay
+   * consumers (scope-rail, table-grip, object-selection, page-break
+   * decorations) for render-frame + zoom access. Migrated from
+   * `layoutFacet.getRenderFrame` / `.getRenderZoom` in refactor/05
+   * cross-lane-coord §8.4.
+   */
+  geometryFacet?: import("../runtime/geometry/index.ts").GeometryFacet;
+  /**
+   * Layer-06 workflow facet — canonical source of scope rail segments +
+   * scope card models. Passed through to `TwReviewWorkspace` which
+   * forwards it to the chrome overlay + scope-card hook. Layer-06
+   * Slice 4 made this the owning seam; the layout facet no longer
+   * exposes rail/card data.
+   */
+  workflowFacet?: import("../runtime/workflow/rail/types.ts").WorkflowFacet;
   interactionGuardSnapshot?: InteractionGuardSnapshot;
   chromePreset?: WordReviewEditorChromePreset;
   chromeOptions?: Partial<WordReviewEditorChromeOptions>;
+  editorActionHost?: import("../ui-tailwind/chrome/editor-action-registry.ts").EditorActionHostCallbacks;
+  chromeControllerRef?: React.Ref<
+    import("../ui-tailwind/chrome/tw-workspace-chrome-host.tsx").TwWorkspaceChromeHostController
+  >;
+  commandPaletteDisabled?: boolean;
   /** P9g — live collab session for the `"collab"` chrome preset's top nav. */
   collabSession?: import("../runtime/collab-session.ts").CollabSession;
   collabTransportStatus?: import("../api/awareness-identity-types.ts").TransportStatus;
@@ -84,6 +107,12 @@ export interface EditorShellViewProps {
   documentNavigation?: DocumentNavigationSnapshot;
   commands: EditorCommandBag;
   shellHeader?: ReactNode;
+  /**
+   * Forwarded to `TwReviewWorkspace` so the default `<TwShellHeader />` wires
+   * its mode tabs back to `runtime.setEditorRole`.  Without this handler the
+   * shell-header mode tabs are decorative (U1 regression).
+   */
+  onEditorRoleChange?: (role: EditorRole) => void;
   document: ReactNode;
   onAddCommentFromSelection?: () => void;
   onAddCommentFromSuggestion?: () => void;

package/src/ui/editor-surface-controller.tsx

@@ -2,8 +2,11 @@ import React, { forwardRef } from "react";
 
 import type {
   DocumentNavigationSnapshot,
+  EditorStoryTarget,
   EditorUser,
   RuntimeRenderSnapshot,
+  SearchOptions,
+  SearchResultSnapshot,
   SelectionSnapshot,
   WorkflowBlockedCommandReason,
   WorkflowCandidateRange,
@@ -11,7 +14,8 @@ import type {
   WorkflowMetadataMarkup,
   WorkflowScope,
 } from "../api/public-types.ts";
-import type { CanonicalDocumentEnvelope } from "../core/state/editor-state.ts";
+import type { TableSelectionDescriptor } from "../api/v3/runtime/table.ts";
+import type { CanonicalDocumentEnvelope } from "../api/public-types.ts";
 import type { MarkupDisplay } from "./headless/comment-decoration-model.ts";
 import type { SelectionToolbarAnchor } from "./headless/selection-toolbar-model.ts";
 import type { ActiveSelectionToolModel } from "./headless/selection-tool-types.ts";
@@ -52,6 +56,34 @@ export interface EditorSurfaceControllerProps {
   onUndo?: () => void;
   onRedo?: () => void;
   onBlockedInput?: (command: "paste" | "drop", message: string) => void;
+  /**
+   * refactor/11 Slice 5 — forwarded to the PM bridge so rich-paste
+   * parsing no longer lives inside `src/ui-tailwind/editor-surface/**`.
+   * See `pm-command-bridge.ts` §`PasteFragmentParserAdapter`.
+   */
+  pasteFragmentParser?: import("../ui-tailwind/editor-surface/pm-command-bridge.ts").PasteFragmentParserAdapter;
+  /**
+   * §4.8 — forwarded to `TwProseMirrorSurface`. Threaded from the host's
+   * `api.runtime.search.searchDocument` at WordReviewEditor so L11
+   * presentation no longer imports `src/runtime/document-search.ts`
+   * directly.
+   */
+  runtimeSearchDocument?: (
+    document: import("../api/public-types.ts").CanonicalDocumentEnvelope,
+    selection: SelectionSnapshot,
+    activeStory: EditorStoryTarget,
+    navigation: DocumentNavigationSnapshot,
+    query: string,
+    options?: SearchOptions,
+  ) => SearchResultSnapshot[];
+  /**
+   * §4.8 — forwarded to `TwProseMirrorSurface`. Threaded from
+   * `api.runtime.table.getSelectionDescriptor` so L11 presentation no
+   * longer imports `src/runtime/table-commands.ts` directly.
+   */
+  runtimeGetTableSelectionDescriptor?: (
+    state: import("prosemirror-state").EditorState,
+  ) => TableSelectionDescriptor | null;
   onPasteApplied?: (meta: {
     segmentCount: number;
     charCount: number;
@@ -70,12 +102,28 @@ export interface EditorSurfaceControllerProps {
     command: import("../ui-tailwind/editor-surface/fast-text-edit-lane.ts").LaneRuntimeCommand,
   ) => import("../api/public-types.ts").TextCommandAck;
   layoutFacet?: import("../runtime/layout/index.ts").WordReviewEditorLayoutFacet;
+  /**
+   * Geometry facet forwarded to `TwProseMirrorSurface` for page-break
+   * decoration build path (refactor/05 cross-lane-coord §8.4).
+   */
+  geometryFacet?: import("../runtime/geometry/index.ts").GeometryFacet;
   pageChromeHeaderBandPx?: number;
   pageChromeFooterBandPx?: number;
   pageChromeInterGapPx?: number;
   pageBreakRevision?: number;
   onOpenHeaderStoryForPage?: (pageIndex: number) => void;
   onOpenFooterStoryForPage?: (pageIndex: number) => void;
+  /**
+   * Phase C.γ / §3.1 — right-click composition hook.  Forwarded verbatim
+   * to `TwProseMirrorSurface.onContextMenuRequested`; the PM command
+   * bridge suppresses the browser-native menu when wired so the host
+   * can mount `TwContextMenu` at the returned coordinates.
+   */
+  onContextMenuRequested?: (event: {
+    clientX: number;
+    clientY: number;
+    target: EventTarget | null;
+  }) => void;
 }
 
 export const EditorSurfaceController = forwardRef<

package/src/ui/headless/revision-decoration-model.ts

@@ -146,6 +146,89 @@ export function getRevisionRangeState(
   };
 }
 
+/**
+ * Shape of the per-segment `revisionDisplay` authoritative flags
+ * shipped by L03 formatting-semantics (see
+ * `SurfaceInlineSegment.revisionDisplay` in `src/api/public-types.ts`).
+ * Re-declared here to keep this helper a pure consumer of the public
+ * surface; the structural identity with the canonical type is enforced
+ * by `test/runtime/formatting/production-boundary.test.ts`.
+ */
+export interface RevisionDisplayFlags {
+  markupMode: "clean" | "simple" | "all";
+  hidden?: boolean;
+  strikethrough?: boolean;
+  insertionUnderline?: boolean;
+  deemphasize?: boolean;
+  authorColor?: string;
+}
+
+/**
+ * Track B (cross-layer-coord-11 §3.1 / handoff §4 Track B / §5.2) —
+ * derive a revision-decoration CSS class from L03's authoritative
+ * `SurfaceInlineSegment.revisionDisplay` flags.
+ *
+ * Consumers that have access to the live surface-segment stream (e.g.
+ * `pm-decorations.ts` when threaded through Task B's integration
+ * follow-up) should call this helper instead of
+ * `getRevisionHighlightClass` — which reads the review-store
+ * `RevisionDecorationModel` + the `markupDisplay` prop as a side
+ * channel, re-deriving decisions L03 has already made. When the
+ * segment carries `revisionDisplay`, this helper reads the derived
+ * flags directly and emits the matching Tailwind class bundle. No
+ * markup-mode conditional is re-evaluated here: L03 already encoded
+ * the mode-specific derivation in `markupMode` + the visual flags.
+ *
+ * Returns `""` when no display flags apply (no revision at this
+ * segment) or when the caller should suppress rendering (the caller
+ * handles `hidden` by not rendering the span at all — this helper
+ * does not emit a `hidden` class to avoid double-suppression).
+ */
+export function buildClassFromRevisionDisplay(
+  display: RevisionDisplayFlags | undefined,
+): string {
+  if (!display) return "";
+  if (display.hidden) return "";
+
+  const parts: string[] = [];
+
+  // Insertion underline (simple / all markup, insertion kind).
+  if (display.insertionUnderline) {
+    // Matches the underline visual used in the review-store path for
+    // "simple-markup" insertions; keeps the two paths producing the
+    // same class bundle so a mid-flight migration does not produce a
+    // visual diff.
+    parts.push(
+      "underline decoration-insert/60 decoration-1 underline-offset-2 text-primary",
+    );
+  }
+
+  // Strikethrough (deletion kind, simple or all markup).
+  if (display.strikethrough) {
+    parts.push("text-danger line-through decoration-danger/80 decoration-1");
+  }
+
+  // De-emphasize (e.g. inactive revision in all-markup; reviewer
+  // observer mode). Lighter body tone, no underline/strikethrough on
+  // its own — the caller composes them.
+  if (display.deemphasize && !display.strikethrough) {
+    parts.push("text-secondary");
+  }
+
+  // Surface the author palette color as a CSS variable the renderer
+  // can pick up via `var(--wre-revision-author)`. Consumer stylesheet
+  // composes this into ring/underline color when the palette slot is
+  // known. Absent when the segment has no resolved author color
+  // (anonymous revisions or pre-author-color import paths).
+  //
+  // The inline style path is handled by the caller (Tailwind classes
+  // cannot carry runtime-dynamic colors); this helper just emits the
+  // class bundle. Callers that need the author color render it
+  // separately via `display.authorColor`.
+
+  return parts.join(" ");
+}
+
 export function getRevisionHighlightClass(
   model: RevisionDecorationModel | undefined,
   from: number,

package/src/{ui-tailwind/chrome → ui/headless}/role-action-sets.ts

@@ -13,7 +13,7 @@
  */
 
 import type { EditorRole } from "../../api/public-types";
-import type { ToolbarChromeItemId } from "../../ui/headless/chrome-registry";
+import type { ToolbarChromeItemId } from "./chrome-registry";
 
 /**
  * Ordered role-action ids.  Each array covers the *role-primary* actions

package/src/ui/headless/scoped-chrome-policy.ts

@@ -5,13 +5,13 @@ import type {
   WorkflowScopeSnapshot,
   WordReviewEditorChromePreset,
 } from "../../api/public-types";
-import type { SessionCapabilities } from "../../runtime/session-capabilities";
+import type { SessionCapabilities } from "../../api/public-types";
 import {
   TOOLBAR_CHROME_REGISTRY,
   type ToolbarChromeItemId,
   type ToolbarChromePlacement,
 } from "./chrome-registry";
-import { ROLE_ACTION_SETS } from "../../ui-tailwind/chrome/role-action-sets";
+import { ROLE_ACTION_SETS } from "./role-action-sets";
 import type { SelectionToolKind } from "./selection-tool-types";
 
 export interface ToolbarChromeItemPolicy {

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

@@ -4,7 +4,7 @@ import type {
   RuntimeRenderSnapshot,
   StyleCatalogSnapshot,
 } from "../../api/public-types";
-import type { SessionCapabilities } from "../../runtime/session-capabilities";
+import type { SessionCapabilities } from "../../api/public-types";
 import type { ScopedChromePolicy } from "./scoped-chrome-policy";
 import type { SelectionToolResolverContext } from "./selection-tool-types";
 

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

@@ -5,7 +5,7 @@ import type {
   TrackedChangeEntrySnapshot,
   WorkflowScopeSnapshot,
 } from "../../api/public-types";
-import { storyTargetsEqual } from "../../core/selection/mapping";
+import { storyTargetsEqual } from "../../api/public-types";
 import type { SelectionToolResolverInput } from "./selection-tool-context";
 import type {
   ActiveSelectionToolModel,

package/src/ui/runtime-shortcut-dispatch.ts

@@ -43,7 +43,30 @@ export type ShellShortcutResolution =
   | { kind: "dismiss-selection-toolbar" }
   | { kind: "toggle-formatting"; mark: "bold" | "italic" | "underline" }
   | { kind: "add-comment" }
-  | { kind: "set-heading-level"; level: 1 | 2 | 3 };
+  | { kind: "set-heading-level"; level: 1 | 2 | 3 }
+  /**
+   * Phase C.γ.5 — composition-level shortcuts.
+   * These surface at the shell level because they target
+   * composition-owned surfaces (context menu, rail, scope navigation)
+   * rather than a document edit.
+   *   - `open-context-menu` fires on Shift+F10 and delegates to the
+   *     workspace controller to mount `TwContextMenu` at the caret.
+   *     `fromKeyboard: true` signals to the consumer that coords must
+   *     be resolved from the caret position (via the existing
+   *     `tw-selection-anchor-resolver` helper) rather than from the
+   *     event — keyboard events don't carry clientX/clientY.  Phase
+   *     D.5 shortcut-gap fix.
+   *   - `focus-rail` fires on Ctrl/Cmd+Shift+R and routes focus into
+   *     the active rail tab (DESIGN-EDITOR.md §8).
+   *   - `navigate-scope` fires on Alt+Up / Alt+Down for workflow
+   *     scope traversal (DESIGN-EDITOR.md §8, supersedes the
+   *     currently-planned Ctrl/Cmd+Up/Down pair after review found
+   *     those bindings already conflict with macOS scroll-to-top/
+   *     bottom defaults).
+   */
+  | { kind: "open-context-menu"; fromKeyboard: true }
+  | { kind: "focus-rail" }
+  | { kind: "navigate-scope"; direction: 1 | -1 };
 
 export type SurfaceShortcutResolution =
   | { kind: "none" }
@@ -159,6 +182,28 @@ export function resolveShellShortcut(
     return { kind: "delegate", shortcut: "last-edit" };
   }
 
+  // Phase C.γ.5 — composition shortcuts.  These resolve regardless of
+  // `selectionToolbarVisible` so keyboard access is consistent across
+  // floating-surface states.  The Ctrl+K / Cmd+K palette shortcut is
+  // owned by TwCommandPaletteMount (a global window listener); it is
+  // NOT routed here because the palette needs to intercept the key
+  // before any per-surface dispatch.
+  if (key === "f10" && input.shiftKey && !input.ctrlKey && !input.metaKey && !input.altKey) {
+    return { kind: "open-context-menu", fromKeyboard: true };
+  }
+  if (
+    (input.ctrlKey || input.metaKey) &&
+    input.shiftKey &&
+    !input.altKey &&
+    key === "r"
+  ) {
+    return { kind: "focus-rail" };
+  }
+  if (input.altKey && !input.ctrlKey && !input.metaKey && !input.shiftKey) {
+    if (key === "arrowup") return { kind: "navigate-scope", direction: -1 };
+    if (key === "arrowdown") return { kind: "navigate-scope", direction: 1 };
+  }
+
   return { kind: "none" };
 }
 

package/src/ui/ui-controller-factory.ts

@@ -0,0 +1,221 @@
+/**
+ * Shell-side `UiControllerFactory` implementation (refactor/11 Slice 4 consumer
+ * wiring — the counterpart to refactor/10 Slice 10's `UiApiProvider`).
+ *
+ * The factory is what turns `createApiV3(handle, { ui: factory })` into an
+ * `api.ui` with real method paths. When no hook is supplied, a UI API method
+ * that depends on one throws a configuration-clear error (per `_types.ts`
+ * `UiController` docstrings) rather than silently no-oping.
+ *
+ * Three entry points:
+ *
+ *   1. `shellUiControllerFactory` — zero-deps default. Used by the lazy
+ *      `refValue.getApiV3()` path and any non-mounted caller (SSR, harness)
+ *      that doesn't have shell state available. Produces a controller with
+ *      an empty bridge + no hooks wired; UI API methods that require a
+ *      hook throw or return `null`.
+ *
+ *   2. `createShellUiControllerFactory(bridge)` — narrow builder that wires
+ *      the DS-C1 selection-anchor bridge only (refactor/11 Slice DS-C1).
+ *      Back-compat entry for shell code that hasn't adopted the wider
+ *      deps shape. Equivalent to `makeShellUiControllerFactory({
+ *        getOverlayAnchor: bridge-backed })`.
+ *
+ *   3. `makeShellUiControllerFactory(deps)` — full deps builder used by the
+ *      mounted `WordReviewEditor.tsx` render path. `deps` is a narrow record
+ *      of shell-side getters + subscribers + an optional overlay-anchor
+ *      resolver. Only the keys the shell populates land on the controller;
+ *      everything else stays absent.
+ *
+ * Design: the shell populates hooks one consumer at a time.
+ *
+ *   - `getHostPosture` + `getPinnedSurfaces` are wired on the mounted path
+ *     today because `useWorkspaceComposition` + `ui.chrome.getPosture`
+ *     need them (refactor/10 Task 1).
+ *
+ *   - `getOverlayAnchor` for `kind:"selection"` is wired via the bridge
+ *     populated by `use-shell-selection-anchor-bridge.ts` (DS-C1).
+ *     Non-selection kinds already resolve through `handle.geometry.*`
+ *     inside `src/api/v3/ui/overlays.ts`; the controller hook returns
+ *     `null` for them so the API keeps delegating to the geometry facet.
+ *
+ *   - `subscribe*` hooks are kept deps-optional — they serve non-React
+ *     consumers (Playwright, window-debug) and land when those surfaces
+ *     come online.
+ *
+ * Per U4 in `docs/architecture/10-ui-api.md`: `getOverlayAnchor` MUST
+ * return `null` (never fall back to DOM) when the bridge is unpopulated.
+ * `ui.overlays.getAnchor` already encodes this contract.
+ */
+
+import type {
+  ChromeHostPosture,
+  ChromeSurface,
+  ChromePosture,
+  GeometryRect,
+  OverlayAnchorQuery,
+  UiController,
+  UiControllerFactory,
+  UiListener,
+  UiUnsubscribe,
+  ViewportState,
+} from "../api/v3/ui/_types.ts";
+import type {
+  WordReviewEditorChromeOptions,
+  WordReviewEditorChromePreset,
+} from "../api/public-types.ts";
+import { resolveChromeVisibilityForPreset } from "../api/v3/ui/chrome-preset-model.ts";
+import type { ShellOverlayAnchorBridge } from "../shell/overlay-anchor-bridge.ts";
+import { createShellOverlayAnchorBridge } from "../shell/overlay-anchor-bridge.ts";
+
+let nextControllerId = 0;
+
+/**
+ * Deps the shell provides to `makeShellUiControllerFactory`. Every field
+ * is optional — the builder wires only the hooks that are supplied. Missing
+ * hooks map to `undefined` on the controller, which lets L10 produce a
+ * configuration-clear error when a consumer calls an un-wired method.
+ */
+export interface ShellUiControllerDeps {
+  /**
+   * Current host-provided posture slice — reviewMode / markupDisplay /
+   * debugMode / chromePreset. MUST read through a live ref so the factory
+   * closure returns current render state, not stale construction-time state.
+   */
+  readonly getHostPosture?: () => ChromeHostPosture | undefined;
+  /**
+   * Pinned-surface enumeration. Typically computed from
+   * `resolveChromeVisibilityForPreset` against the current preset + options.
+   */
+  readonly getPinnedSurfaces?: () => readonly ChromeSurface[];
+  /**
+   * Overlay anchor resolver (DS-C1 selection-anchor bridge). Returns
+   * `null` when the bridge is unpopulated or the query kind doesn't map.
+   */
+  readonly getOverlayAnchor?: (query: OverlayAnchorQuery) => GeometryRect | null;
+  /**
+   * Posture-change stream. Fires when any of the inputs to `ChromePosture`
+   * change — reviewMode / markupDisplay / debugMode / chromePreset (host),
+   * effectiveMode / blockedReasons / documentMode / readOnly (runtime).
+   * Returns an unsubscribe function.
+   *
+   * React-based consumers re-read on render and typically don't need this;
+   * the hook exists for non-React consumers (Playwright drivers, debug
+   * service) that hold an `api.ui` across time.
+   */
+  readonly subscribeChrome?: (listener: UiListener<ChromePosture>) => UiUnsubscribe;
+  /** Container-dim-measured viewport snapshot. */
+  readonly getViewport?: () => ViewportState;
+  /**
+   * Viewport change stream — rAF-coalesced per U7. Fires on scroll / zoom /
+   * dpr / container-resize. Returns unsubscribe.
+   */
+  readonly subscribeViewport?: (listener: UiListener<ViewportState>) => UiUnsubscribe;
+  /**
+   * Overlay invalidation stream — fires when geometry invalidation overlaps
+   * an attached overlay query (U7). Typically delegated to the render
+   * kernel's per-frame invalidation bus.
+   */
+  readonly subscribeOverlays?: (
+    listener: UiListener<OverlayAnchorQuery>,
+  ) => UiUnsubscribe;
+}
+
+/**
+ * Build a `UiControllerFactory` closing over `deps`. Each call of the
+ * returned factory produces a fresh controller with a unique id — the UI
+ * API's session family uses the id to distinguish bindings (useful for
+ * debug logs + multi-instance isolation tests).
+ *
+ * Only the deps that were supplied are forwarded to the controller; `undefined`
+ * deps produce an absent controller hook (the documented contract for
+ * "not wired").
+ */
+export function makeShellUiControllerFactory(
+  deps: ShellUiControllerDeps = {},
+): UiControllerFactory {
+  return () => {
+    nextControllerId += 1;
+    const controller: UiController = {
+      kind: "runtime-direct",
+      id: `wre-shell-${nextControllerId}`,
+      ...(deps.getHostPosture ? { getHostPosture: deps.getHostPosture } : {}),
+      ...(deps.getPinnedSurfaces ? { getPinnedSurfaces: deps.getPinnedSurfaces } : {}),
+      ...(deps.getOverlayAnchor ? { getOverlayAnchor: deps.getOverlayAnchor } : {}),
+      ...(deps.subscribeChrome ? { subscribeChrome: deps.subscribeChrome } : {}),
+      ...(deps.getViewport ? { getViewport: deps.getViewport } : {}),
+      ...(deps.subscribeViewport ? { subscribeViewport: deps.subscribeViewport } : {}),
+      ...(deps.subscribeOverlays ? { subscribeOverlays: deps.subscribeOverlays } : {}),
+    };
+    return controller;
+  };
+}
+
+/**
+ * Narrow builder — wires the DS-C1 overlay-anchor bridge only (refactor/11
+ * Slice 4). Back-compat entry for shell code that hasn't adopted the
+ * wider `ShellUiControllerDeps` shape. Equivalent to calling
+ * `makeShellUiControllerFactory({ getOverlayAnchor: bridge-backed })`.
+ *
+ * Identity of the returned factory is stable across renders so long as
+ * `bridge` identity is stable (create the bridge with
+ * `useRef(createShellOverlayAnchorBridge()).current`).
+ */
+export function createShellUiControllerFactory(
+  bridge: ShellOverlayAnchorBridge,
+): UiControllerFactory {
+  return makeShellUiControllerFactory({
+    getOverlayAnchor: (query: OverlayAnchorQuery) => {
+      if (query.kind === "selection") {
+        return bridge.getSelectionAnchor?.() ?? null;
+      }
+      return null;
+    },
+  });
+}
+
+/**
+ * Zero-deps default factory. Back-compat with callers that don't have
+ * shell state available (the lazy `refValue.getApiV3()` path, SSR, harness
+ * constructors). Produces a minimal controller backed by an empty bridge;
+ * `ui.overlays.getAnchor({kind:"selection"})` returns `null` honoring U4.
+ */
+export const shellUiControllerFactory: UiControllerFactory =
+  createShellUiControllerFactory(createShellOverlayAnchorBridge());
+
+/**
+ * Translate the host-facing preset + options into the `ChromeSurface[]`
+ * list `ui.chrome.getPinnedSurfaces()` returns. Pure — suitable for a
+ * getter closure inside a `ShellUiControllerDeps`. Uses the L10-owned
+ * `resolveChromeVisibilityForPreset` helper (relocated in Slice 8) so
+ * the mapping stays inside the UI API layer and nothing has to reimport
+ * the L11 shim.
+ *
+ * Enumeration scope (review M5 2026-04-22): only `toolbar` + `rail`
+ * surfaces are emitted today — those are the shell's pinnable workspace
+ * surfaces. The `ChromeSurfaceKind` union also includes `sidebar`,
+ * `command-palette`, `context-menu`, `top-nav`; those are not
+ * preset-driven pinned surfaces in the current shell. When consumer
+ * work needs them enumerated (e.g. `command-palette` pinning), extend
+ * this helper — the `ChromeSurface` shape already supports it.
+ */
+export function deriveShellPinnedSurfaces(
+  chromePreset: WordReviewEditorChromePreset,
+  chromeOptions: Partial<WordReviewEditorChromeOptions> | undefined,
+): readonly ChromeSurface[] {
+  const visibility = resolveChromeVisibilityForPreset({
+    chromePreset,
+    chromeOptions,
+  });
+  const surfaces: ChromeSurface[] = [];
+  if (visibility.toolbar) {
+    surfaces.push({ kind: "toolbar", id: "workspace-toolbar", visible: true, pinned: true });
+  }
+  if (visibility.reviewRail) {
+    surfaces.push({ kind: "rail", id: "review-rail", visible: true, pinned: true });
+  }
+  // `pageChrome` is a structural canvas adornment rather than a
+  // dismissible surface; it's not enumerated here per §U5.b — page
+  // presence is part of ChromeComposition, not ChromeSurface.
+  return surfaces;
+}

package/src/ui-tailwind/chart/ChartSurface.tsx

@@ -22,8 +22,8 @@
  */
 
 import React from "react";
-import type { ChartModel } from "../../io/ooxml/chart/types.ts";
-import type { ResolvedTheme } from "../../model/canonical-document.ts";
+import type { ChartModel } from "../../api/public-types.ts";
+import type { ResolvedTheme } from "../../api/public-types.ts";
 import { layoutPlotArea, CHROME_PAINTED_DEFAULT, type PlotAreaLayout } from "./layout/plot-area.ts";
 import { AreaChart } from "./render/area.tsx";
 import { BarColumnChart } from "./render/bar-column.tsx";

package/src/ui-tailwind/chart/layout/legend-layout.ts

@@ -26,7 +26,7 @@
  */
 
 import type { Rect } from "./plot-area.ts";
-import type { ResolvedTheme } from "../../../model/canonical-document.ts";
+import type { ResolvedTheme } from "../../../api/public-types.ts";
 import { measureText } from "../render/font-metrics.ts";
 
 // ---------------------------------------------------------------------------

package/src/ui-tailwind/chart/layout/plot-area.ts

@@ -20,8 +20,8 @@
  * signature is unchanged.
  */
 
-import type { ChartModel } from "../../../io/ooxml/chart/types.ts";
-import type { ResolvedTheme } from "../../../model/canonical-document.ts";
+import type { ChartModel } from "../../../api/public-types.ts";
+import type { ResolvedTheme } from "../../../api/public-types.ts";
 import { measureText } from "../render/font-metrics.ts";
 import { formatNumber } from "../render/number-format.ts";
 import {

package/src/ui-tailwind/chart/layout/title-layout.ts

@@ -23,7 +23,7 @@
  */
 
 import type { Rect } from "./plot-area.ts";
-import type { ResolvedTheme } from "../../../model/canonical-document.ts";
+import type { ResolvedTheme } from "../../../api/public-types.ts";
 import { measureText } from "../render/font-metrics.ts";
 
 // ---------------------------------------------------------------------------

package/src/ui-tailwind/chart/render/area.tsx

@@ -22,12 +22,12 @@
  */
 
 import React from "react";
-import { composeSeriesColor } from "../../../io/ooxml/chart/compose-series-color.ts";
+import { composeSeriesColor } from "../../../api/v3/runtime/chart.ts";
 import type {
   AreaChartModel,
   Series,
-} from "../../../io/ooxml/chart/types.ts";
-import type { ResolvedTheme } from "../../../model/canonical-document.ts";
+} from "../../../api/public-types.ts";
+import type { ResolvedTheme } from "../../../api/public-types.ts";
 import type { PlotAreaLayout } from "../layout/plot-area.ts";
 import { useProgressiveCount } from "./progressive-render.ts";
 

package/src/ui-tailwind/chart/render/bar-column.tsx

@@ -26,13 +26,13 @@
  */
 
 import React from "react";
-import { composeSeriesColor } from "../../../io/ooxml/chart/compose-series-color.ts";
+import { composeSeriesColor } from "../../../api/v3/runtime/chart.ts";
 import type {
   BarChartModel,
   DataPointOverride,
   Series,
-} from "../../../io/ooxml/chart/types.ts";
-import type { ResolvedTheme } from "../../../model/canonical-document.ts";
+} from "../../../api/public-types.ts";
+import type { ResolvedTheme } from "../../../api/public-types.ts";
 import type { PlotAreaLayout } from "../layout/plot-area.ts";
 import { resolveFill, DefsRegistry } from "./svg-primitives.ts";
 import { useProgressiveCount } from "./progressive-render.ts";

package/src/ui-tailwind/chart/render/bubble.tsx

@@ -10,12 +10,12 @@
  */
 
 import React from "react";
-import { composeSeriesColor } from "../../../io/ooxml/chart/compose-series-color.ts";
+import { composeSeriesColor } from "../../../api/v3/runtime/chart.ts";
 import type {
   BubbleChartModel,
   BubbleSeries,
-} from "../../../io/ooxml/chart/types.ts";
-import type { ResolvedTheme } from "../../../model/canonical-document.ts";
+} from "../../../api/public-types.ts";
+import type { ResolvedTheme } from "../../../api/public-types.ts";
 import type { PlotAreaLayout } from "../layout/plot-area.ts";
 
 // ---------------------------------------------------------------------------