@beyondwork/docx-react-component 1.0.105 → 1.0.108

package/src/ui-tailwind/chrome/tw-navigation-command-bar.tsx

@@ -0,0 +1,328 @@
+import * as React from "react";
+import { ChevronDown, ChevronUp, Rows3, Search, Target, X } from "lucide-react";
+
+import { preserveEditorSelectionMouseDown } from "../../ui/headless/preserve-editor-selection";
+
+export type NavigationCommandMode = "find" | "replace" | "go-to";
+export type NavigationSearchScope = "main" | "story" | "scope";
+
+export interface NavigationSearchScopeOption {
+  id: NavigationSearchScope;
+  label: string;
+  disabled?: boolean;
+  disabledReason?: string;
+}
+
+export interface NavigationGoToItem {
+  id: string;
+  label: string;
+  detail?: string;
+}
+
+export interface NavigationGoToGroup {
+  id: string;
+  label: string;
+  emptyLabel: string;
+  items: readonly NavigationGoToItem[];
+}
+
+export interface TwNavigationCommandBarProps {
+  mode: NavigationCommandMode;
+  query: string;
+  replacement: string;
+  activeIndex: number;
+  resultCount: number;
+  searchScope: NavigationSearchScope;
+  searchScopes: readonly NavigationSearchScopeOption[];
+  goToGroups: readonly NavigationGoToGroup[];
+  activeGoToGroupId: string;
+  onModeChange: (mode: NavigationCommandMode) => void;
+  onQueryChange: (query: string) => void;
+  onReplacementChange: (replacement: string) => void;
+  onSearchScopeChange: (scope: NavigationSearchScope) => void;
+  onPrevious: () => void;
+  onNext: () => void;
+  onReplaceCurrent: () => void;
+  onGoToGroupChange: (groupId: string) => void;
+  onGoToTarget: (groupId: string, itemId: string) => void;
+  onClose: () => void;
+}
+
+const MODE_ITEMS: ReadonlyArray<{
+  id: NavigationCommandMode;
+  label: string;
+  shortcut: string;
+}> = [
+  { id: "find", label: "Find", shortcut: "Ctrl+F" },
+  { id: "replace", label: "Replace", shortcut: "Ctrl+H" },
+  { id: "go-to", label: "Go to", shortcut: "Ctrl+G" },
+];
+
+export function TwNavigationCommandBar(
+  props: TwNavigationCommandBarProps,
+): React.JSX.Element {
+  const inputRef = React.useRef<HTMLInputElement | null>(null);
+  const hasResults = props.resultCount > 0;
+  const hasQuery = props.query.trim().length > 0;
+  const resultState = hasQuery ? (hasResults ? "matches" : "empty") : "idle";
+  const statusLabel = hasQuery
+    ? hasResults
+      ? `${props.activeIndex + 1}/${props.resultCount}`
+      : "No results"
+    : "Find";
+  const navDisabledReason = hasQuery
+    ? "No matches to navigate."
+    : "Enter a query to navigate matches.";
+  const activeGroup =
+    props.goToGroups.find((group) => group.id === props.activeGoToGroupId) ??
+    props.goToGroups[0] ??
+    null;
+
+  React.useEffect(() => {
+    if (props.mode === "go-to") return;
+    inputRef.current?.focus();
+    inputRef.current?.select();
+  }, [props.mode]);
+
+  const handleRootKeyDown = React.useCallback(
+    (event: React.KeyboardEvent<HTMLDivElement>) => {
+      if (event.key !== "Escape") return;
+      event.preventDefault();
+      props.onClose();
+    },
+    [props.onClose],
+  );
+
+  return (
+    <div
+      className="pointer-events-auto flex w-[min(560px,calc(100vw-2rem))] flex-col gap-2 rounded-lg border border-[color:color-mix(in_srgb,var(--color-accent-primary)_26%,var(--color-border-subtle))] bg-[color:color-mix(in_srgb,var(--color-bg-canvas)_96%,white)] p-2 shadow-[var(--shadow-float)]"
+      data-testid="navigation-command-bar"
+      data-mode={props.mode}
+      data-result-state={resultState}
+      role="search"
+      aria-label="Document navigation"
+      onKeyDown={handleRootKeyDown}
+    >
+      <div className="flex items-center gap-2">
+        <div className="inline-flex rounded-md bg-surface p-0.5" role="tablist" aria-label="Navigation mode">
+          {MODE_ITEMS.map((item) => {
+            const selected = item.id === props.mode;
+            return (
+              <button
+                key={item.id}
+                type="button"
+                role="tab"
+                aria-selected={selected}
+                title={`${item.label} (${item.shortcut})`}
+                data-testid={`navigation-command-bar-mode-${item.id}`}
+                onMouseDown={preserveEditorSelectionMouseDown}
+                onClick={() => props.onModeChange(item.id)}
+                className={[
+                  "inline-flex h-7 items-center gap-1 rounded px-2 text-[11px] font-semibold transition-colors focus-visible:outline-none focus-visible:shadow-[var(--shadow-focus)]",
+                  selected
+                    ? "bg-canvas text-primary shadow-sm ring-1 ring-border"
+                    : "text-secondary hover:bg-hover hover:text-primary",
+                ].join(" ")}
+              >
+                {item.label}
+              </button>
+            );
+          })}
+        </div>
+        <button
+          type="button"
+          aria-label="Close navigation"
+          className="ml-auto inline-flex h-7 w-7 items-center justify-center rounded-md text-tertiary transition-colors hover:bg-hover hover:text-primary focus-visible:outline-none focus-visible:shadow-[var(--shadow-focus)]"
+          onMouseDown={preserveEditorSelectionMouseDown}
+          onClick={props.onClose}
+        >
+          <X className="h-4 w-4" aria-hidden="true" />
+        </button>
+      </div>
+
+      {props.mode === "go-to" ? (
+        <div className="grid gap-2" data-testid="navigation-command-bar-go-to">
+          <div className="flex flex-wrap gap-1">
+            {props.goToGroups.map((group) => {
+              const selected = group.id === activeGroup?.id;
+              return (
+                <button
+                  key={group.id}
+                  type="button"
+                  aria-pressed={selected}
+                  onMouseDown={preserveEditorSelectionMouseDown}
+                  onClick={() => props.onGoToGroupChange(group.id)}
+                  className={[
+                    "inline-flex h-7 items-center gap-1 rounded-md border px-2 text-[11px] font-medium transition-colors focus-visible:outline-none focus-visible:shadow-[var(--shadow-focus)]",
+                    selected
+                      ? "border-[var(--color-border-accent)] bg-[var(--color-accent-soft)] text-[var(--color-accent-primary)]"
+                      : "border-border bg-canvas text-secondary hover:bg-hover hover:text-primary",
+                  ].join(" ")}
+                >
+                  <Target className="h-3 w-3" aria-hidden="true" />
+                  {group.label}
+                  <span className="text-[10px] text-tertiary">{group.items.length}</span>
+                </button>
+              );
+            })}
+          </div>
+          <div className="max-h-64 overflow-auto rounded-md border border-border bg-canvas p-1">
+            {activeGroup && activeGroup.items.length > 0 ? (
+              activeGroup.items.map((item) => (
+                <button
+                  key={item.id}
+                  type="button"
+                  className="flex w-full items-start gap-2 rounded-md px-2 py-1.5 text-left text-[12px] transition-colors hover:bg-surface focus-visible:bg-surface focus-visible:outline-none focus-visible:shadow-[var(--shadow-focus)]"
+                  onMouseDown={preserveEditorSelectionMouseDown}
+                  onClick={() => props.onGoToTarget(activeGroup.id, item.id)}
+                >
+                  <Rows3 className="mt-0.5 h-3.5 w-3.5 shrink-0 text-secondary" aria-hidden="true" />
+                  <span className="min-w-0">
+                    <span className="block truncate font-medium text-primary">{item.label}</span>
+                    {item.detail ? (
+                      <span className="block truncate text-[11px] text-secondary">{item.detail}</span>
+                    ) : null}
+                  </span>
+                </button>
+              ))
+            ) : (
+              <div className="px-2 py-3 text-[12px] text-secondary">
+                {activeGroup?.emptyLabel ?? "No navigation targets available."}
+              </div>
+            )}
+          </div>
+        </div>
+      ) : (
+        <div className="grid gap-2" data-testid="navigation-command-bar-search">
+          <div className="flex items-center gap-2">
+            <Search className="h-4 w-4 shrink-0 text-accent" aria-hidden="true" />
+            <input
+              ref={inputRef}
+              aria-label={props.mode === "replace" ? "Find text to replace" : "Find text"}
+              aria-describedby="navigation-command-bar-status"
+              className="min-w-0 flex-1 bg-transparent px-1 text-[13px] font-medium text-primary outline-none placeholder:text-tertiary"
+              placeholder={props.mode === "replace" ? "Find text to replace" : "Find in document"}
+              type="search"
+              value={props.query}
+              onChange={(event) => props.onQueryChange(event.currentTarget.value)}
+              onKeyDown={(event) => {
+                if (event.key === "Escape") {
+                  event.preventDefault();
+                  event.stopPropagation();
+                  props.onClose();
+                  return;
+                }
+                if (event.key === "Enter") {
+                  event.preventDefault();
+                  if (event.shiftKey) {
+                    props.onPrevious();
+                  } else {
+                    props.onNext();
+                  }
+                }
+              }}
+            />
+            <span
+              id="navigation-command-bar-status"
+              data-testid="navigation-command-bar-status"
+              className={`min-w-[72px] rounded-full px-2 py-1 text-center text-[11px] font-semibold tabular-nums ${
+                resultState === "empty"
+                  ? "bg-[var(--color-semantic-warning-soft)] text-[var(--color-semantic-warning)]"
+                  : "bg-[color:color-mix(in_srgb,var(--color-accent-primary)_10%,transparent)] text-accent"
+              }`}
+              aria-live="polite"
+            >
+              {statusLabel}
+            </span>
+            <IconButton
+              label="Previous match"
+              shortcut="Shift+Enter"
+              disabled={!hasResults}
+              title={hasResults ? "Previous match (Shift+Enter)" : navDisabledReason}
+              onClick={props.onPrevious}
+            >
+              <ChevronUp className="h-4 w-4" aria-hidden="true" />
+            </IconButton>
+            <IconButton
+              label="Next match"
+              shortcut="Enter"
+              disabled={!hasResults}
+              title={hasResults ? "Next match (Enter)" : navDisabledReason}
+              onClick={props.onNext}
+            >
+              <ChevronDown className="h-4 w-4" aria-hidden="true" />
+            </IconButton>
+          </div>
+          <div className="flex flex-wrap items-center gap-1">
+            {props.searchScopes.map((scope) => (
+              <button
+                key={scope.id}
+                type="button"
+                aria-pressed={props.searchScope === scope.id}
+                disabled={scope.disabled}
+                title={scope.disabled ? scope.disabledReason : undefined}
+                onMouseDown={preserveEditorSelectionMouseDown}
+                onClick={() => props.onSearchScopeChange(scope.id)}
+                className={[
+                  "inline-flex h-6 items-center rounded-md border px-2 text-[10px] font-semibold transition-colors focus-visible:outline-none focus-visible:shadow-[var(--shadow-focus)] disabled:cursor-not-allowed disabled:opacity-40",
+                  props.searchScope === scope.id
+                    ? "border-[var(--color-border-accent)] bg-[var(--color-accent-soft)] text-[var(--color-accent-primary)]"
+                    : "border-border bg-canvas text-secondary hover:bg-hover hover:text-primary",
+                ].join(" ")}
+              >
+                {scope.label}
+              </button>
+            ))}
+          </div>
+          {props.mode === "replace" ? (
+            <div className="flex items-center gap-2 border-t border-border/70 pt-2">
+              <input
+                aria-label="Replacement text"
+                className="min-w-0 flex-1 rounded-md border border-border bg-canvas px-2 py-1.5 text-[13px] text-primary outline-none placeholder:text-tertiary focus-visible:shadow-[var(--shadow-focus)]"
+                placeholder="Replace with"
+                value={props.replacement}
+                onChange={(event) => props.onReplacementChange(event.currentTarget.value)}
+              />
+              <button
+                type="button"
+                disabled={!hasResults}
+                title={hasResults ? "Replace current match" : navDisabledReason}
+                onMouseDown={preserveEditorSelectionMouseDown}
+                onClick={props.onReplaceCurrent}
+                className="inline-flex h-8 items-center rounded-md bg-[var(--color-accent-primary)] px-3 text-[12px] font-semibold text-[var(--color-text-inverse)] transition-colors hover:bg-[var(--color-accent-primary-hover)] focus-visible:outline-none focus-visible:shadow-[var(--shadow-focus)] disabled:cursor-not-allowed disabled:opacity-40"
+              >
+                Replace
+              </button>
+            </div>
+          ) : null}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function IconButton(props: {
+  label: string;
+  shortcut: string;
+  disabled?: boolean;
+  title?: string;
+  children: React.ReactNode;
+  onClick: () => void;
+}): React.JSX.Element {
+  return (
+    <button
+      type="button"
+      aria-label={props.label}
+      aria-keyshortcuts={props.shortcut}
+      disabled={props.disabled}
+      title={props.title}
+      className="inline-flex h-7 w-7 items-center justify-center rounded-md text-secondary transition-colors hover:bg-hover focus-visible:outline-none focus-visible:shadow-[var(--shadow-focus)] disabled:cursor-not-allowed disabled:opacity-35"
+      onMouseDown={preserveEditorSelectionMouseDown}
+      onClick={props.onClick}
+    >
+      {props.children}
+    </button>
+  );
+}
+
+export default TwNavigationCommandBar;

package/src/ui-tailwind/chrome/tw-object-context-toolbar.tsx

@@ -3,6 +3,8 @@ import type { ActiveObjectContext } from "../../ui/headless/selection-tool-types
 
 export interface TwObjectContextToolbarProps {
   activeObject: ActiveObjectContext;
+  /** Debug/operator-only preserve/export detail. Hidden in product chrome. */
+  showPreservationDiagnostics?: boolean;
 }
 
 function InfoIcon(props: { className?: string; "aria-hidden"?: boolean }) {
@@ -40,10 +42,12 @@ export function TwObjectContextToolbar(props: TwObjectContextToolbarProps) {
       <span className="rounded-full bg-surface px-1.5 py-0.5 text-[9px] font-medium uppercase tracking-[0.1em] text-secondary">
         {props.activeObject.display}
       </span>
-      <div className="inline-flex items-center gap-1.5">
-        <InfoIcon className="h-3.5 w-3.5 text-[var(--color-semantic-info)]" aria-hidden={true} />
-        <span className="text-[11px] text-[var(--color-text-secondary)]">Shape preserved for export — opens in Word.</span>
-      </div>
+      {props.showPreservationDiagnostics ? (
+        <div className="inline-flex items-center gap-1.5">
+          <InfoIcon className="h-3.5 w-3.5 text-[var(--color-semantic-info)]" aria-hidden={true} />
+          <span className="text-[11px] text-[var(--color-text-secondary)]">Shape preserved for export — opens in Word.</span>
+        </div>
+      ) : null}
     </div>
   );
 }

package/src/ui-tailwind/chrome/tw-runtime-repl-dialog.tsx

@@ -6,6 +6,13 @@ import React, {
 } from "react";
 
 import type { WordReviewEditorRef } from "../../api/public-types";
+import {
+  LAYER_DEBUG_PANES,
+  getLayerDebugIdFromShortcut,
+  getLayerDebugPane,
+  getLayerDebugShortcutLabel,
+  type LayerDebugPaneId,
+} from "./layer-debug-contracts";
 
 /**
  * Opaque runtime handle for the REPL. The REPL hands the value to
@@ -55,6 +62,7 @@ export function TwRuntimeReplDialog(props: TwRuntimeReplDialogProps): React.JSX.
   const [open, setOpen] = useState(false);
   const [input, setInput] = useState("");
   const [entries, setEntries] = useState<readonly ReplEntry[]>([]);
+  const [activeLayerId, setActiveLayerId] = useState<LayerDebugPaneId>("01");
   const [history, setHistory] = useState<readonly string[]>(() =>
     loadPersistedHistory(),
   );
@@ -73,10 +81,25 @@ export function TwRuntimeReplDialog(props: TwRuntimeReplDialogProps): React.JSX.
     });
   }, []);
 
+  const loadSnippet = useCallback((expression: string) => {
+    setInput(expression);
+    setHistoryIndex(null);
+    requestAnimationFrame(() => textareaRef.current?.focus());
+  }, []);
+
   useEffect(() => {
     if (disabled) return;
     if (typeof window === "undefined") return;
     const handler = (event: KeyboardEvent): void => {
+      if (openRef.current) {
+        const layerId = getLayerDebugIdFromShortcut(event);
+        if (layerId) {
+          event.preventDefault();
+          event.stopPropagation();
+          setActiveLayerId(layerId);
+          return;
+        }
+      }
       if (!isReplToggleShortcut(event)) return;
       event.preventDefault();
       event.stopPropagation();
@@ -208,6 +231,8 @@ export function TwRuntimeReplDialog(props: TwRuntimeReplDialogProps): React.JSX.
 
   if (!open) return null;
 
+  const activeLayer = getLayerDebugPane(activeLayerId);
+
   return (
     <div
       className="fixed inset-0 z-50 flex items-start justify-center pt-[10vh]"
@@ -281,6 +306,105 @@ export function TwRuntimeReplDialog(props: TwRuntimeReplDialogProps): React.JSX.
           </div>
         </div>
 
+        <section
+          className="border-b border-[var(--color-border-subtle)] px-4 py-3"
+          data-testid="tw-runtime-repl__layer-view"
+        >
+          <div className="flex flex-wrap items-start justify-between gap-3">
+            <div>
+              <p className="text-[10px] font-semibold uppercase tracking-[0.14em] text-[var(--color-text-tertiary)]">
+                Agent layer view
+              </p>
+              <p className="mt-1 text-sm font-medium text-[var(--color-text-primary)]">
+                {activeLayer.owner} - {activeLayer.label}
+              </p>
+              <p className="mt-1 text-xs leading-5 text-[var(--color-text-secondary)]">
+                {activeLayer.focus}
+              </p>
+            </div>
+            <label className="space-y-1 text-[10px] font-semibold uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]">
+              <span className="block">Layer</span>
+              <select
+                className="min-w-[13rem] rounded-[var(--radius-sm)] bg-[var(--color-bg-muted)] px-2 py-1.5 text-xs font-medium normal-case tracking-normal text-[var(--color-text-primary)] ring-1 ring-[var(--color-border-subtle)]"
+                data-testid="tw-runtime-repl__layer-select"
+                onChange={(event) =>
+                  setActiveLayerId(event.currentTarget.value as LayerDebugPaneId)
+                }
+                value={activeLayerId}
+              >
+                {LAYER_DEBUG_PANES.map((pane) => (
+                  <option key={pane.id} value={pane.id}>
+                    L{pane.id} - {pane.label}
+                  </option>
+                ))}
+              </select>
+            </label>
+          </div>
+
+          <div
+            className="mt-3 flex gap-1 overflow-x-auto pb-1"
+            data-testid="tw-runtime-repl__layer-nav"
+          >
+            {LAYER_DEBUG_PANES.map((pane) => {
+              const active = pane.id === activeLayerId;
+              return (
+                <button
+                  className={[
+                    "shrink-0 rounded-[var(--radius-sm)] px-2 py-1 text-[11px] font-medium",
+                    "transition-colors duration-[var(--motion-fast)]",
+                    active
+                      ? "bg-[var(--color-bg-selected)] text-[var(--color-text-primary)] ring-1 ring-[var(--color-border-strong)]"
+                      : "bg-[var(--color-bg-muted)] text-[var(--color-text-secondary)] hover:bg-[var(--color-bg-hover)] hover:text-[var(--color-text-primary)]",
+                  ].join(" ")}
+                  data-testid={`tw-runtime-repl__layer-option-${pane.id}`}
+                  key={pane.id}
+                  onClick={() => setActiveLayerId(pane.id)}
+                  type="button"
+                >
+                  L{pane.id}
+                  <span className="ml-1 text-[10px] opacity-70">
+                    {getLayerDebugShortcutLabel(pane.id)}
+                  </span>
+                </button>
+              );
+            })}
+          </div>
+
+          <div
+            className="mt-3 grid gap-2"
+            data-testid="tw-runtime-repl__layer-snippets"
+          >
+            {activeLayer.snippets.map((snippet) => (
+              <button
+                className="rounded-[var(--radius-sm)] bg-[var(--color-bg-muted)] px-2 py-2 text-left font-mono text-[11px] leading-5 text-[var(--color-text-primary)] ring-1 ring-[var(--color-border-subtle)] transition-colors duration-[var(--motion-fast)] hover:bg-[var(--color-bg-hover)]"
+                data-testid={`tw-runtime-repl__layer-snippet-${slugify(snippet.label)}`}
+                key={snippet.label}
+                onClick={() => loadSnippet(snippet.expression)}
+                type="button"
+              >
+                <span className="block font-sans text-[10px] font-semibold uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]">
+                  {snippet.label}
+                </span>
+                {snippet.expression}
+              </button>
+            ))}
+          </div>
+
+          <details
+            className="mt-3 rounded-[var(--radius-sm)] bg-[var(--color-bg-muted)] px-2 py-2 text-xs text-[var(--color-text-secondary)] ring-1 ring-[var(--color-border-subtle)]"
+            data-testid="tw-runtime-repl__layer-routed"
+          >
+            <summary className="cursor-pointer text-[11px] font-medium text-[var(--color-text-primary)]">
+              Routed data gaps
+            </summary>
+            <ul className="mt-2 space-y-1 leading-5">
+              {activeLayer.routed.map((item) => (
+                <li key={item}>{item}</li>
+              ))}
+            </ul>
+          </details>
+        </section>
+
         <div
           ref={outputRef}
           className="max-h-[50vh] min-h-[160px] overflow-y-auto px-4 py-3 font-mono text-xs leading-relaxed text-[var(--color-text-primary)]"
@@ -365,7 +489,7 @@ export function TwRuntimeReplDialog(props: TwRuntimeReplDialogProps): React.JSX.
             ].join(" ")}
           />
           <div className="mt-1.5 flex items-center justify-between text-[10px] text-[var(--color-text-tertiary)]">
-            <span>Enter to evaluate · Shift+Enter for newline · ↑/↓ history · Esc to close</span>
+            <span>Enter to evaluate · Shift+Enter newline · ↑/↓ history · Alt+1..9/0/- layers · Esc close</span>
             <span>{entries.length > 0 ? `${entries.length} entries` : ""}</span>
           </div>
         </div>
@@ -374,6 +498,10 @@ export function TwRuntimeReplDialog(props: TwRuntimeReplDialogProps): React.JSX.
   );
 }
 
+function slugify(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
 export function isReplToggleShortcut(event: KeyboardEvent): boolean {
   const isP =
     event.code === "KeyP" ||

package/src/ui-tailwind/chrome/tw-selection-tool-host.tsx

@@ -27,6 +27,11 @@ export interface SelectionToolPlacement {
 
 export interface TwSelectionToolHostProps {
   tool: ActiveSelectionToolModel | null;
+  /**
+   * Stable identity for the current selection. When omitted, the host
+   * falls back to the tool preview key for direct component consumers.
+   */
+  selectionKey?: string | null;
   contextAnalytics?: RuntimeContextAnalyticsSnapshot | null;
   placement: SelectionToolPlacement | null;
   /**
@@ -76,6 +81,7 @@ export interface TwSelectionToolHostProps {
   onSetTableAlignment?: (alignment: "left" | "center" | "right") => void;
   onSetCellVerticalAlign?: (align: "top" | "center" | "bottom") => void;
   onOpenTableMore?: (coords: { clientX: number; clientY: number }) => void;
+  showPreservationDiagnostics?: boolean;
 }
 
 /**
@@ -84,12 +90,17 @@ export interface TwSelectionToolHostProps {
  * previewText so that a new selection (which produces a new previewText)
  * resets the timer.  Pure re-renders with the same selection do not reset.
  */
-function useDwellDensity(tool: ActiveSelectionToolModel | null): "micro" | "full" {
+function useDwellDensity(
+  tool: ActiveSelectionToolModel | null,
+  selectionKeyOverride?: string | null,
+): "micro" | "full" {
   // Derive a stable selection key from the tool.  For formatting-inline we
   // use the previewText (reflects selected content).  For other kinds we use
-  // a fixed sentinel so they never reset mid-render.
+  // a fixed sentinel so they never reset mid-render. Mounted callers pass
+  // the actual anchor/head identity so directional drag selections reset even
+  // when they cover the same preview text.
   const selectionKey = tool
-    ? `${tool.kind}:${tool.previewText ?? "none"}`
+    ? `${tool.kind}:${selectionKeyOverride ?? tool.previewText ?? "none"}`
     : null;
   const [density, setDensity] = useState<"micro" | "full">("micro");
 
@@ -111,7 +122,7 @@ function useDwellDensity(tool: ActiveSelectionToolModel | null): "micro" | "full
 }
 
 export function TwSelectionToolHost(props: TwSelectionToolHostProps) {
-  const density = useDwellDensity(props.tool);
+  const density = useDwellDensity(props.tool, props.selectionKey);
   const { onChromePinChange } = props;
 
   // Phase F.2 — gate the selection tool on the shared local-surface
@@ -162,6 +173,8 @@ export function TwSelectionToolHost(props: TwSelectionToolHostProps) {
 
   const overlayTestId = getOverlayTestId(props.tool.kind, Boolean(props.placement));
   const toolContent = renderTool(props, props.tool, density);
+  const shouldRenderContextAnalytics =
+    props.tool.kind !== "blocked-explainer" && Boolean(props.contextAnalytics);
   const content = toolContent ? (
     <div
       ref={props.rootRef}
@@ -169,7 +182,7 @@ export function TwSelectionToolHost(props: TwSelectionToolHostProps) {
       onBlurCapture={props.onBlurCapture}
       className="flex flex-col gap-1.5"
     >
-      {props.contextAnalytics ? (
+      {shouldRenderContextAnalytics ? (
         <TwContextAnalyticsSummary
           snapshot={props.contextAnalytics}
           compact
@@ -301,6 +314,7 @@ function renderTool(
           onSetTableAlignment={props.onSetTableAlignment}
           onSetCellVerticalAlign={props.onSetCellVerticalAlign}
           onOpenTableMore={props.onOpenTableMore}
+          showPreservationDiagnostics={props.showPreservationDiagnostics}
         />
       );
     case "comment-thread":

package/src/ui-tailwind/chrome/tw-selection-tool-structure.tsx

@@ -36,6 +36,7 @@ export interface TwSelectionToolStructureProps {
   onSetTableAlignment?: (alignment: "left" | "center" | "right") => void;
   onSetCellVerticalAlign?: (align: "top" | "center" | "bottom") => void;
   onOpenTableMore?: (coords: { clientX: number; clientY: number }) => void;
+  showPreservationDiagnostics?: boolean;
 }
 
 export function TwSelectionToolStructure(props: TwSelectionToolStructureProps) {
@@ -53,7 +54,10 @@ export function TwSelectionToolStructure(props: TwSelectionToolStructureProps) {
       // Shapes and text boxes are shipped as informational-only structure tools
       // until there is a real runtime-backed object mutation path.
       return props.model.activeObject ? (
-        <TwObjectContextToolbar activeObject={props.model.activeObject} />
+        <TwObjectContextToolbar
+          activeObject={props.model.activeObject}
+          showPreservationDiagnostics={props.showPreservationDiagnostics}
+        />
       ) : null;
     case "table":
       return (