@beyondwork/docx-react-component 1.0.106 → 1.0.108

package/src/ui-tailwind/page-stack/tw-page-stack-chrome-layer.tsx

@@ -12,8 +12,8 @@
  * Band placement
  * --------------
  * For each measured page rect the layer emits one
- * `<div data-page-chrome-frame data-page-index={i}>` positioned at the
- * rect's top/height.  Inside the frame, four children conditionally
+ * `<div data-page-chrome-frame data-page-anchor data-page-index={i}>`
+ * positioned at the rect's top/height. Inside the frame, four children conditionally
  * mount:
  *
  *   1. `<TwPageHeaderBand>` — when the page's `regions.header` + the
@@ -73,13 +73,17 @@ import type {
   GeometryFacet,
   WordReviewEditorLayoutFacet,
 } from "../../api/public-types.ts";
+import { buildPageAnchorSelector } from "../../api/v3/_page-anchor-id.ts";
 import {
   measureWidgetsViaOffsetChain,
   measureWidgetsViaBoundingRect,
+  resolvePageOverlayRectsFromUiApi,
   resolvePageOverlayRectsFromGeometry,
   resolvePageOverlayRects,
+  reconcilePageStackRectsWithFlow,
   type PageOverlayRect,
 } from "../chrome-overlay/tw-page-stack-overlay-layer.tsx";
+import { useUiApi } from "../ui-api-context.tsx";
 import { TwEndnoteArea } from "./tw-endnote-area.tsx";
 import { TwPageChromeEntry } from "./tw-page-chrome-entry.tsx";
 import type { TwActiveBandRibbonProps } from "./tw-active-band-ribbon.tsx";
@@ -101,7 +105,7 @@ export interface TwPageStackChromeLayerProps {
   facet: WordReviewEditorLayoutFacet;
   /** Geometry facet — warm-path source of per-page frame rects. */
   geometryFacet?: GeometryFacet;
-  /** Scroll root whose `[data-page-frame-*]` markers drive per-page rects. */
+  /** Scroll root used only by the page-rect cold fallback before geometry is warm. */
   scrollRoot: HTMLElement | null;
   /**
    * Render-frame revision tick incremented on `layout_recomputed`,
@@ -137,7 +141,7 @@ export interface TwPageStackChromeLayerProps {
    * pages whose sequential index falls inside this range (with overscan
    * already applied by the caller). Pages outside the range render a
    * lightweight wrapper `div` carrying the `data-page-chrome-frame` +
-   * `data-page-index` attributes — every position read (portal-slot
+   * shared `data-page-anchor` attributes — every position read (portal-slot
    * query, per-page measurement) continues to resolve deterministically,
    * but the four child React subtrees (Header/Footer/Footnote bands)
    * never mount, eliminating the measured 412 ms Layout + 229 ms
@@ -183,9 +187,29 @@ const TwPageStackChromeLayerInner: React.FC<TwPageStackChromeLayerProps> = ({
   mediaPreviews,
   activeBandRibbonProps,
 }) => {
+  const ui = useUiApi();
+  const resolveUiPageRects = React.useCallback(
+    (pageCount: number): readonly PageOverlayRect[] | null => {
+      if (!ui) return null;
+      const pageIds = Array.from(
+        { length: pageCount },
+        (_, pageIndex) => facet.getPage(pageIndex)?.pageId ?? `page-${pageIndex}`,
+      );
+      return resolvePageOverlayRectsFromUiApi(
+        ui,
+        pageCount,
+        visiblePageIndexRange,
+        pageIds,
+      );
+    },
+    [facet, ui, visiblePageIndexRange],
+  );
+
   const [rects, setRects] = React.useState<readonly PageOverlayRect[]>(() => {
-    if (!geometryFacet) return [];
     const pageCount = facet.getPageCount();
+    const uiRects = resolveUiPageRects(pageCount);
+    if (uiRects !== null) return uiRects;
+    if (!geometryFacet) return [];
     const warm = resolvePageOverlayRectsFromGeometry(
       geometryFacet,
       pageCount,
@@ -206,6 +230,20 @@ const TwPageStackChromeLayerInner: React.FC<TwPageStackChromeLayerProps> = ({
 
   const refreshRectsNow = React.useCallback(() => {
     const pageCount = facet.getPageCount();
+    const reconcileRects = (baseRects: readonly PageOverlayRect[]) =>
+      reconcilePageStackRectsWithFlow({
+        baseRects,
+        pageCount,
+        scrollRoot,
+        originElement: overlayRootRef.current,
+      });
+
+    const uiRects = resolveUiPageRects(pageCount);
+    if (uiRects !== null) {
+      setRects(reconcileRects(uiRects));
+      return;
+    }
+
     if (geometryFacet) {
       const geometryRects = resolvePageOverlayRectsFromGeometry(
         geometryFacet,
@@ -213,7 +251,7 @@ const TwPageStackChromeLayerInner: React.FC<TwPageStackChromeLayerProps> = ({
         visiblePageIndexRange,
       );
       if (geometryRects !== null) {
-        setRects(geometryRects);
+        setRects(reconcileRects(geometryRects));
         return;
       }
     }
@@ -240,29 +278,31 @@ const TwPageStackChromeLayerInner: React.FC<TwPageStackChromeLayerProps> = ({
           : originRect.height > 0
             ? originRect.height
             : scrollRoot.clientHeight;
+      const domRects = resolvePageOverlayRects({
+        widgets,
+        pageCount,
+        scrollHeight,
+        visiblePageIndexRange,
+      });
       setRects(
-        resolvePageOverlayRects({
-          widgets,
-          pageCount,
-          scrollHeight,
-          visiblePageIndexRange,
-        }),
+        reconcileRects(domRects),
       );
     } else {
       const widgets = measureWidgetsViaOffsetChain(scrollRoot, {
         pageCount,
         visiblePageIndexRange,
       });
+      const domRects = resolvePageOverlayRects({
+        widgets,
+        pageCount,
+        scrollHeight: scrollRoot.clientHeight,
+        visiblePageIndexRange,
+      });
       setRects(
-        resolvePageOverlayRects({
-          widgets,
-          pageCount,
-          scrollHeight: scrollRoot.clientHeight,
-          visiblePageIndexRange,
-        }),
+        reconcileRects(domRects),
       );
     }
-  }, [facet, geometryFacet, scrollRoot, visiblePageIndexRange]);
+  }, [facet, geometryFacet, resolveUiPageRects, scrollRoot, visiblePageIndexRange]);
 
   const refreshRects = React.useCallback(() => {
     if (!scrollRoot) {
@@ -384,7 +424,7 @@ const TwPageStackChromeLayerInner: React.FC<TwPageStackChromeLayerProps> = ({
     const pageScopedSelector =
       activeStoryPageIndex == null
         ? null
-        : `[data-pm-portal-slot][data-page-index="${activeStoryPageIndex}"]`;
+        : `${buildPageAnchorSelector(activeStoryPageIndex)} [data-pm-portal-slot]`;
     const activeSlot =
       (pageScopedSelector
         ? overlay?.querySelector<HTMLElement>(pageScopedSelector)

package/src/ui-tailwind/page-stack/tw-region-block-renderer.tsx

@@ -7,12 +7,15 @@ import type {
 import type { MediaPreviewDescriptor } from "../editor-surface/pm-state-from-snapshot.ts";
 import {
   buildMarkerStyle,
+  buildParagraphContentStyle,
   buildParagraphStyle,
   buildSegmentStyle,
-  computeTabWidthsInPoints,
+  buildTabStyle,
+  computeTabRenderInfoBySegment,
   hasStyleEntries,
   headingClassList,
   resolveHeadingLevel,
+  type TabRenderInfo,
 } from "../editor-surface/tw-page-block-view.helpers.ts";
 import { shouldRenderAbsoluteFloatingImageInPageOverlay } from "./floating-image-overlay-model.ts";
 
@@ -61,7 +64,7 @@ function renderSegment(
   seg: SurfaceInlineSegment,
   mediaPreviews: Record<string, MediaPreviewDescriptor>,
   fallbackDisplay: RegionImageFallbackDisplay,
-  tabWidthsPt: Map<string, number>,
+  tabInfoBySegment: Map<string, TabRenderInfo>,
 ): React.ReactNode {
   switch (seg.kind) {
     case "text": {
@@ -77,16 +80,13 @@ function renderSegment(
       );
     }
     case "tab": {
-      const widthPt = tabWidthsPt.get(seg.segmentId);
-      const tabStyle: React.CSSProperties =
-        typeof widthPt === "number"
-          ? { display: "inline-block", width: `${widthPt}pt`, minWidth: "8px" }
-          : { display: "inline-block", width: "32px", minWidth: "8px" };
+      const tabInfo = tabInfoBySegment.get(seg.segmentId);
       return (
         <span
           key={seg.segmentId}
           data-node-type="tab"
-          style={tabStyle}
+          style={buildTabStyle(tabInfo)}
+          title={tabInfo?.align ? `Tab stop · ${tabInfo.align}` : "Tab stop"}
         >
           {"\u00A0"}
         </span>
@@ -248,7 +248,8 @@ function RegionParagraph({
   }
 
   const pStyle = buildParagraphStyle(block);
-  const tabWidthsPt = computeTabWidthsInPoints(block);
+  const tabInfoBySegment = computeTabRenderInfoBySegment(block);
+  const contentStyle = buildParagraphContentStyle(block);
 
   // Numbering prefix span — matches tw-page-block-view so region content that
   // happens to carry numbering (e.g. footnote bodies authored as lists) shows
@@ -312,8 +313,12 @@ function RegionParagraph({
   return (
     <div {...attrs}>
       {prefixSpan}
-      <span className="pm-paragraph-content">
-        {block.segments.map((seg) => renderSegment(seg, mediaPreviews, fallbackDisplay, tabWidthsPt))}
+      <span
+        className="pm-paragraph-content"
+        data-tab-layout={contentStyle ? "right" : undefined}
+        style={contentStyle}
+      >
+        {block.segments.map((seg) => renderSegment(seg, mediaPreviews, fallbackDisplay, tabInfoBySegment))}
       </span>
     </div>
   );

package/src/ui-tailwind/review/tw-health-panel.tsx

@@ -2,17 +2,26 @@ import React from "react";
 import { AlertTriangle, Info, Shield, ShieldAlert, ShieldCheck } from "lucide-react";
 
 import type {
-  CompatibilityFeatureEntry,
   CompatibilityPanelSnapshot,
   EditorWarning,
   WorkflowBlockedCommandReason,
 } from "../../api/public-types";
 import { TwEmptyState } from "../chrome/tw-empty-state";
+import {
+  filterProductCompatibility,
+  filterProductWarnings,
+} from "../review-workspace/diagnostics-visibility.ts";
 
 export interface TwHealthPanelProps {
   compatibility: CompatibilityPanelSnapshot;
   warnings: EditorWarning[];
   blockedReasons?: WorkflowBlockedCommandReason[];
+  /**
+   * Preserve-only / opaque diagnostics are debug/operator-only. Default
+   * product chrome shows export blockers and actionable warnings, not
+   * preservation internals.
+   */
+  showPreservationDiagnostics?: boolean;
 }
 
 type SeverityKey = "error" | "warning" | "info";
@@ -91,7 +100,16 @@ function renderGroup(
 }
 
 export function TwHealthPanel(props: TwHealthPanelProps) {
-  const { compatibility, warnings, blockedReasons = [] } = props;
+  const {
+    blockedReasons = [],
+    showPreservationDiagnostics = false,
+  } = props;
+  const compatibility = showPreservationDiagnostics
+    ? props.compatibility
+    : filterProductCompatibility(props.compatibility);
+  const warnings = showPreservationDiagnostics
+    ? props.warnings
+    : filterProductWarnings(props.warnings);
 
   // Blocked export group: unsupported-fatal entries
   const blockedExportItems: IssueRow[] = compatibility.featureEntries
@@ -111,20 +129,22 @@ export function TwHealthPanel(props: TwHealthPanelProps) {
 
   // Warning group: preserve-only entries + workflow blocked reasons + "warning"-severity EditorWarnings
   const warningItems: IssueRow[] = [
-    ...compatibility.featureEntries
-      .filter((e) => e.featureClass === "preserve-only")
-      .map((e) => ({
-        id: e.featureEntryId,
-        message: e.message,
-        detail: e.featureKey,
-        badge: "preserve-only",
-        icon: (
-          <Shield
-            className="h-4 w-4 shrink-0 mt-0.5"
-            style={{ color: "var(--color-semantic-warning)" }}
-          />
-        ),
-      })),
+    ...(showPreservationDiagnostics
+      ? compatibility.featureEntries
+          .filter((e) => e.featureClass === "preserve-only")
+          .map((e) => ({
+            id: e.featureEntryId,
+            message: e.message,
+            detail: e.featureKey,
+            badge: "preserve-only",
+            icon: (
+              <Shield
+                className="h-4 w-4 shrink-0 mt-0.5"
+                style={{ color: "var(--color-semantic-warning)" }}
+              />
+            ),
+          }))
+      : []),
     ...blockedReasons.map((r, index) => ({
       id: `blocked-reason-${index}`,
       message: r.message,
@@ -186,4 +206,3 @@ export function TwHealthPanel(props: TwHealthPanelProps) {
     </div>
   );
 }
-

package/src/ui-tailwind/review/tw-review-rail.tsx

@@ -31,8 +31,8 @@ import {
  * to a signal-only chip.  When `showHealthTab` is absent the rail retains the
  * shipped three-tab layout for back-compat.
  *
- * The Workflow tab reads `scopeRailSegments` from the runtime facet — that
- * stays the default path.  For hosts that need to override the Workflow card
+ * The Workflow tab reads `scopeRailSegments` from the mounted UI API seam by
+ * default.  For hosts that need to override the Workflow card
  * content (CLM, BW, agent integrations that derive their own model), pass
  * `workflowTab` as a ReactNode and it will replace the built-in projection.
  * Either way policy stays host-side; the runtime rail remains projection-only.
@@ -60,8 +60,8 @@ export interface TwReviewRailProps {
   activeCommentId?: string;
   activeRevisionId?: string;
   /**
-   * Scope rail segments used by the Workflow tab.  Consumers typically
-   * pass `ref.layout.getAllScopeRailSegments()` here.  When omitted the
+   * Scope rail segments used by the Workflow tab.  Mounted consumers pass
+   * `api.ui.scope.rail().segments` through the workspace.  When omitted the
    * Workflow tab renders an empty state (unless `workflowTab` is set).
    */
   scopeRailSegments?: readonly ScopeRailSegment[];
@@ -103,6 +103,8 @@ export interface TwReviewRailProps {
   healthSeverity?: "info" | "warning" | "blocked";
   /** Forwarded to the Health tab's `TwHealthPanel` to surface blocked reasons. */
   workflowBlockedReasons?: WorkflowBlockedCommandReason[];
+  /** Debug/operator-only opt-in for preserve-only / opaque diagnostics. */
+  showPreservationDiagnostics?: boolean;
 
   onActiveTabChange: (tab: ReviewRailTab) => void;
   onOpenComment?: (thread: CommentSidebarThreadSnapshot) => void;
@@ -299,6 +301,7 @@ export function TwReviewRail(props: TwReviewRailProps) {
                 <TwHealthPanel
                   compatibility={props.compatibility}
                   warnings={props.warnings}
+                  showPreservationDiagnostics={props.showPreservationDiagnostics}
                   {...(props.workflowBlockedReasons
                     ? { blockedReasons: props.workflowBlockedReasons }
                     : {})}

package/src/ui-tailwind/review-workspace/diagnostics-visibility.ts

@@ -0,0 +1,44 @@
+import type {
+  CompatibilityFeatureEntry,
+  CompatibilityPanelSnapshot,
+  EditorWarning,
+} from "../../api/public-types.ts";
+
+const DEBUG_ONLY_WARNING_CODES = new Set<EditorWarning["code"]>([
+  "unsupported_ooxml_preserved",
+  "unsupported_ooxml_locked",
+]);
+
+export function isDebugOnlyCompatibilityFeature(
+  entry: CompatibilityFeatureEntry,
+): boolean {
+  return entry.featureClass === "preserve-only";
+}
+
+export function isDebugOnlyWarning(warning: EditorWarning): boolean {
+  return (
+    warning.source === "preservation" ||
+    DEBUG_ONLY_WARNING_CODES.has(warning.code)
+  );
+}
+
+export function filterProductWarnings(
+  warnings: readonly EditorWarning[] | undefined,
+): EditorWarning[] {
+  return (warnings ?? []).filter((warning) => !isDebugOnlyWarning(warning));
+}
+
+export function filterProductCompatibility(
+  compatibility: CompatibilityPanelSnapshot,
+): CompatibilityPanelSnapshot {
+  const featureEntries = compatibility.featureEntries.filter(
+    (entry) => !isDebugOnlyCompatibilityFeature(entry),
+  );
+  if (featureEntries.length === compatibility.featureEntries.length) {
+    return compatibility;
+  }
+  return {
+    ...compatibility,
+    featureEntries,
+  };
+}

package/src/ui-tailwind/review-workspace/page-shell-metrics.ts

@@ -12,6 +12,9 @@ export const FRAME_PX_PER_TWIP_AT_96DPI = 96 / 1440;
 /** Floor on header/footer band heights so empty bands stay clickable. */
 export const MIN_BAND_HEIGHT_PX = 20;
 
+/** Word's default Letter body width: 8.5in page minus 1in margins at 96dpi. */
+export const DEFAULT_CANVAS_BODY_WIDTH_PX = 624;
+
 const FIT_WIDTH_CHROME_RESERVATION_PX = 96;
 const FIT_HEIGHT_CHROME_RESERVATION_PX = 180;
 const MIN_FIT_ZOOM = 0.5;
@@ -22,6 +25,8 @@ export interface PageShellMetrics {
   frameWidthPx?: number;
   /** P2.a — page frame CSS px height = `pageHeight × FRAME_PX_PER_TWIP_AT_96DPI`. */
   frameHeightPx?: number;
+  /** Word body column width after subtracting left/right section margins. */
+  contentWidthPx?: number;
   contentInsetStyle: CSSProperties;
   pageFrameStyle: CSSProperties;
 }
@@ -35,6 +40,7 @@ export function buildPageShellMetrics(
       pageFrameStyle: {},
       frameWidthPx: 0,
       frameHeightPx: 0,
+      contentWidthPx: 0,
     };
   }
 
@@ -43,6 +49,10 @@ export function buildPageShellMetrics(
   const frameHeightPx = Math.round(pageLayout.pageHeight * pxPerTwip);
   const horizontalInsetPx = Math.round(pageLayout.marginLeft * pxPerTwip);
   const horizontalInsetRightPx = Math.round(pageLayout.marginRight * pxPerTwip);
+  const contentWidthPx = Math.max(
+    0,
+    frameWidthPx - horizontalInsetPx - horizontalInsetRightPx,
+  );
 
   return {
     contentInsetStyle: {
@@ -58,6 +68,7 @@ export function buildPageShellMetrics(
     },
     frameWidthPx,
     frameHeightPx,
+    contentWidthPx,
   };
 }
 

package/src/ui-tailwind/review-workspace/tw-review-workspace-rail.tsx

@@ -7,6 +7,8 @@ import { TwReviewRail, type TwReviewRailProps } from "../review/tw-review-rail";
  *
  *   - `docked`  — render the rail inline as a sibling of the document
  *     column (standard desktop width).
+ *   - `overlay` — render the rail over the canvas, so opening the rail never
+ *     shrinks or left-shifts the continuous editor column.
  *   - `drawer`  — render the rail behind a dismiss-overlay button so the
  *     narrow-viewport scrim can close it.
  *   - `hidden`  — render nothing (the parent already decided the rail
@@ -16,7 +18,7 @@ import { TwReviewRail, type TwReviewRailProps } from "../review/tw-review-rail";
  * `rail`; the wrapper owns the `variant` slot so the parent doesn't have
  * to branch twice on posture.
  */
-export type TwReviewWorkspaceRailMode = "docked" | "drawer" | "hidden";
+export type TwReviewWorkspaceRailMode = "docked" | "overlay" | "drawer" | "hidden";
 
 export interface TwReviewWorkspaceRailProps {
   mode: TwReviewWorkspaceRailMode;
@@ -40,6 +42,19 @@ export function TwReviewWorkspaceRail({
     return <TwReviewRail {...rail} />;
   }
 
+  if (mode === "overlay") {
+    return (
+      <div
+        className="pointer-events-none absolute inset-y-0 right-0 z-30 flex justify-end"
+        data-testid="review-rail-overlay"
+      >
+        <div className="pointer-events-auto h-full">
+          <TwReviewRail variant="drawer" {...rail} />
+        </div>
+      </div>
+    );
+  }
+
   return (
     <div
       className="pointer-events-none absolute inset-0 z-30 flex justify-end"

package/src/ui-tailwind/review-workspace/types.ts

@@ -9,6 +9,7 @@ import type {
   EditorViewStateSnapshot,
   FormattingStateSnapshot,
   FormattingAlignment,
+  GeometryFacet,
   HeaderFooterLinkPatch,
   InteractionGuardSnapshot,
   InsertImageOptions,
@@ -17,11 +18,14 @@ import type {
   ReviewQueueSnapshot,
   SectionPageNumberingPatch,
   SectionBreakType,
+  CollabSession,
   StyleCatalogSnapshot,
   TrackedChangeEntrySnapshot,
+  WordReviewEditorLayoutFacet,
   WordReviewEditorChromeOptions,
   WordReviewEditorChromePreset,
   WordReviewEditorChromeVisibility,
+  WorkflowFacet,
   WorkflowScopeSnapshot,
   WorkspaceMode,
   ZoomLevel,
@@ -31,6 +35,10 @@ import type {
   ActiveSelectionToolModel,
   SelectionToolAnchor,
 } from "../../ui/headless/selection-tool-types";
+import type {
+  UiObjectDragSession,
+  UiObjectDragStartInput,
+} from "../../api/v3/ui/_types.ts";
 import type { MarkupDisplay } from "../../ui/headless/comment-decoration-model";
 import type { EditorCommandBag } from "../../ui/editor-command-bag.ts";
 import type { EditorActionHostCallbacks } from "../chrome/editor-action-registry";
@@ -54,7 +62,7 @@ export interface TwReviewWorkspaceProps {
    * supplied, the ChromeOverlay plane (scope rail, workflow dock, etc.)
    * renders over the document column.
    */
-  layoutFacet?: import("../../runtime/layout/index.ts").WordReviewEditorLayoutFacet;
+  layoutFacet?: WordReviewEditorLayoutFacet;
   /**
    * Layer-05 geometry facet (`runtime.geometry`). Required by chrome
    * overlay layers (scope rail, object selection, table grip, page-break
@@ -63,7 +71,7 @@ export interface TwReviewWorkspaceProps {
    * through the now-`@deprecated` `layoutFacet.getRenderFrame` /
    * `.getRenderZoom` methods.
    */
-  geometryFacet?: import("../../runtime/geometry/index.ts").GeometryFacet;
+  geometryFacet?: GeometryFacet;
   /**
    * Layer-06 workflow facet — canonical source of scope rail segments
    * and scope card models (`runtime.workflow`). Required by the scope
@@ -71,19 +79,16 @@ export interface TwReviewWorkspaceProps {
    * removed those methods from `WordReviewEditorLayoutFacet`. When
    * absent, those layers render nothing.
    */
-  workflowFacet?: import("../../runtime/workflow/rail/types.ts").WorkflowFacet;
+  workflowFacet?: WorkflowFacet;
   /**
    * Optional shell header override.  Mounted above the formatting toolbar.
    *
-   * Per docs/plans/chrome-composition-audit.md §2.4 the shell is always
-   * present in default composition.  When this prop is omitted the
-   * workspace mounts a default `<TwShellHeader />` with the 4-mode
-   * switcher (edit / review / workflow / more) so mode authority is
-   * always visible and centralized.
+   * The default product workspace no longer mounts a top mode-strip shell.
+   * Edit / Review / Workflow mode authority lives in the main toolbar.
    *
-   * Hosts that need a custom brand, mode handlers, or primary CTA pass a
+   * Hosts that need a custom brand, actions, or primary CTA pass a
    * pre-assembled `<TwShellHeader />` here; the custom node replaces the
-   * default entirely.
+   * empty default shell entirely.
    */
   shellHeader?: ReactNode;
   /**
@@ -121,7 +126,7 @@ export interface TwReviewWorkspaceProps {
   /**
    * Optional host-provided Workflow-tab override for the review rail.
    * When unset the rail renders the built-in `TwWorkflowTab` sourced from
-   * `layoutFacet.getAllScopeRailSegments()`.
+   * `api.ui.scope.rail()` on mounted paths.
    */
   reviewRailWorkflowTab?: ReactNode;
   reviewRailWorkflowCount?: number;
@@ -136,6 +141,13 @@ export interface TwReviewWorkspaceProps {
     searchLabel?: string;
     helpLabel?: string;
   };
+  /**
+   * Internal debug/operator switch for opaque/preserve-only diagnostics.
+   * Default product chrome must leave this unset so the shipping component
+   * never exposes preservation internals, health badges, or debug detail by
+   * default.
+   */
+  showDebugDiagnostics?: boolean;
   /** Opens the built-in inline find surface from More/Search and command palette. */
   onOpenInlineFind?: () => void;
   document: ReactNode;
@@ -157,7 +169,7 @@ export interface TwReviewWorkspaceProps {
   chromeOptions?: Partial<WordReviewEditorChromeOptions>;
   density?: "compact" | "standard" | "comfortable";
   /** P9g — live collab session for the `"collab"` chrome preset's top nav. */
-  collabSession?: import("../../runtime/collab-session.ts").CollabSession;
+  collabSession?: CollabSession;
   collabTransportStatus?: import("../../api/awareness-identity-types.ts").TransportStatus;
   collabActorId?: string;
   collabSendBaseline?: {
@@ -179,6 +191,8 @@ export interface TwReviewWorkspaceProps {
   }) => void;
   /** N6 — release the grabbed image/shape. Wired to `runtime.deselectObject()` by the host. */
   onDeselectObject?: () => void;
+  /** Object handle drag lifecycle; routed through the mounted UI API seam. */
+  onBeginObjectDrag?: (input: UiObjectDragStartInput) => UiObjectDragSession;
   activeSelectionTool?: ActiveSelectionToolModel | null;
   selectionToolAnchor?: SelectionToolAnchor | null;
   documentNavigation?: DocumentNavigationSnapshot;