@beyondwork/docx-react-component 1.0.105 → 1.0.108

package/src/ui-tailwind/chrome/layer-debug-contracts.ts

@@ -0,0 +1,208 @@
+export type LayerDebugPaneId =
+  | "01"
+  | "02"
+  | "03"
+  | "04"
+  | "05"
+  | "06"
+  | "07"
+  | "08"
+  | "09"
+  | "10"
+  | "11";
+
+export type LayerDebugSnippet = {
+  label: string;
+  expression: string;
+};
+
+export type LayerDebugPaneDefinition = {
+  id: LayerDebugPaneId;
+  label: string;
+  owner: string;
+  focus: string;
+  snippets: readonly LayerDebugSnippet[];
+  routed: readonly string[];
+};
+
+export const LAYER_DEBUG_PANES: readonly LayerDebugPaneDefinition[] = [
+  {
+    id: "01",
+    label: "Package / session",
+    owner: "Layer 01",
+    focus: "Source package posture, session lifecycle, export and validation proof signals.",
+    snippets: [
+      { label: "Runtime view", expression: "ref?.getViewState?.()" },
+      { label: "Compatibility", expression: "ref?.getCompatibilityReport?.()" },
+      { label: "Navigation", expression: "ref?.getDocumentNavigationSnapshot?.()" },
+    ],
+    routed: [
+      "Durable source/session ids, load revision, and export ids live in the harness session client.",
+      "Package ownership and reconstitution internals remain Layer 01-owned.",
+    ],
+  },
+  {
+    id: "02",
+    label: "Canonical document",
+    owner: "Layer 02",
+    focus: "Canonical review state projected from comments, revisions, suggestions, and compatibility.",
+    snippets: [
+      { label: "Comments", expression: "ref?.getCommentSidebarSnapshot?.()" },
+      { label: "Tracked changes", expression: "ref?.getTrackedChangesSnapshot?.()" },
+      { label: "Suggestions", expression: "ref?.getSuggestionsSnapshot?.()" },
+    ],
+    routed: [
+      "Canonical block tree summaries are Layer 02-owned and should not be inferred from rendered DOM.",
+    ],
+  },
+  {
+    id: "03",
+    label: "Formatting semantics",
+    owner: "Layer 03",
+    focus: "Inline, paragraph, style catalog, and formatting-state readbacks.",
+    snippets: [
+      { label: "Formatting state", expression: "ref?.getFormattingState?.()" },
+      { label: "Style catalog", expression: "ref?.getStyleCatalog?.()" },
+      { label: "View mode", expression: "ref?.getViewState?.().documentMode" },
+    ],
+    routed: [
+      "Formatting provenance and cascade explanations are Layer 03-owned.",
+    ],
+  },
+  {
+    id: "04",
+    label: "Layout semantics",
+    owner: "Layer 04",
+    focus: "Page, section, story, note, region, and navigation readbacks.",
+    snippets: [
+      { label: "Navigation", expression: "ref?.getDocumentNavigationSnapshot?.()" },
+      { label: "View state", expression: "ref?.getViewState?.()" },
+      { label: "Active story", expression: "ref?.getViewState?.().activeStory" },
+    ],
+    routed: [
+      "Section geometry, headers/footers, and twip layout internals are Layer 04-owned.",
+    ],
+  },
+  {
+    id: "05",
+    label: "Geometry projection",
+    owner: "Layer 05",
+    focus: "Selection range, object frame, caret, measurement, and page-region projection.",
+    snippets: [
+      { label: "Selection", expression: "ref?.getViewState?.().selection" },
+      { label: "Measurement", expression: "ref?.getViewState?.().measurement" },
+      { label: "Object frame", expression: "ref?.getViewState?.().activeObjectFrame" },
+    ],
+    routed: [
+      "BBox/page-local geometry indexes and object handle ledgers are Layer 05-owned.",
+    ],
+  },
+  {
+    id: "06",
+    label: "Workflow review",
+    owner: "Layer 06",
+    focus: "Review queues, suggestions, blocked reasons, and workflow guard posture.",
+    snippets: [
+      { label: "Guard", expression: "ref?.getInteractionGuardSnapshot?.()" },
+      { label: "Suggestions", expression: "ref?.getSuggestionsSnapshot?.()" },
+      { label: "Comments", expression: "ref?.getCommentSidebarSnapshot?.()" },
+    ],
+    routed: [
+      "Workflow session mutation persistence and policy inputs are harness/Layer 06 integration-owned.",
+    ],
+  },
+  {
+    id: "07",
+    label: "Runtime API",
+    owner: "Layer 07",
+    focus: "Public ref snapshots, context analytics, runtime events, and API readback shape.",
+    snippets: [
+      { label: "Selection context", expression: "ref?.getRuntimeContextAnalytics?.()" },
+      { label: "Document context", expression: "ref?.getRuntimeContextAnalytics?.({ scopeKind: 'document' })" },
+      { label: "View state", expression: "ref?.getViewState?.()" },
+    ],
+    routed: [
+      "Command traces and v3 UxResponse event tails are Layer 07/debug-infra-owned.",
+    ],
+  },
+  {
+    id: "08",
+    label: "Semantic scopes",
+    owner: "Layer 08",
+    focus: "Workflow scopes, markup, metadata, candidates, and scope-derived context.",
+    snippets: [
+      { label: "Scope snapshot", expression: "ref?.getWorkflowScopeSnapshot?.()" },
+      { label: "Query scopes", expression: "ref?.queryScopes?.({ includeHidden: true, includeInvisible: true })" },
+      { label: "Workflow markup", expression: "ref?.getWorkflowMarkupSnapshot?.()" },
+    ],
+    routed: [
+      "Compiler replacement planning and semantic scope normalization remain Layer 08-owned.",
+    ],
+  },
+  {
+    id: "09",
+    label: "AI API",
+    owner: "Layer 09",
+    focus: "Agent/AI action context, runtime analytics, next actions, and unavailable provenance.",
+    snippets: [
+      { label: "Document analytics", expression: "ref?.getRuntimeContextAnalytics?.({ scopeKind: 'document' })" },
+      { label: "Workflow analytics", expression: "ref?.getRuntimeContextAnalytics?.({ scopeKind: 'workflow_scope', scopeId: ref?.getInteractionGuardSnapshot?.()?.matchedScopeId })" },
+      { label: "Available scopes", expression: "ref?.queryScopes?.({ includeHidden: true, includeInvisible: true })" },
+    ],
+    routed: [
+      "AI audit references and action policy payloads are Layer 09-owned.",
+    ],
+  },
+  {
+    id: "10",
+    label: "UI API",
+    owner: "Layer 10",
+    focus: "UI-facing state snapshots, selection posture, formatting controls, and style catalog.",
+    snippets: [
+      { label: "View state", expression: "ref?.getViewState?.()" },
+      { label: "Formatting state", expression: "ref?.getFormattingState?.()" },
+      { label: "Style catalog", expression: "ref?.getStyleCatalog?.()" },
+    ],
+    routed: [
+      "UI API command-surface contracts and chrome composition policy are Layer 10/chrome-owned.",
+    ],
+  },
+  {
+    id: "11",
+    label: "Presentation surfaces",
+    owner: "Layer 11",
+    focus: "Mounted surface posture, review presentation, compatibility, and navigation readbacks.",
+    snippets: [
+      { label: "Navigation", expression: "ref?.getDocumentNavigationSnapshot?.()" },
+      { label: "Review surface", expression: "({ comments: ref?.getCommentSidebarSnapshot?.(), changes: ref?.getTrackedChangesSnapshot?.() })" },
+      { label: "Compatibility", expression: "ref?.getCompatibilityReport?.()" },
+    ],
+    routed: [
+      "Visual screenshots, surface inventory, and presentation composition remain Layer 11/chrome-owned.",
+    ],
+  },
+] as const;
+
+export function getLayerDebugPane(id: LayerDebugPaneId): LayerDebugPaneDefinition {
+  return LAYER_DEBUG_PANES.find((pane) => pane.id === id) ?? LAYER_DEBUG_PANES[0];
+}
+
+export function getLayerDebugShortcutLabel(id: LayerDebugPaneId): string {
+  if (id === "10") return "Alt+0";
+  if (id === "11") return "Alt+-";
+  return `Alt+${Number(id)}`;
+}
+
+export function getLayerDebugIdFromShortcut(
+  event: Pick<KeyboardEvent, "altKey" | "ctrlKey" | "metaKey" | "shiftKey" | "key">,
+): LayerDebugPaneId | null {
+  if (!event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) {
+    return null;
+  }
+  if (/^[1-9]$/.test(event.key)) {
+    return `0${event.key}` as LayerDebugPaneId;
+  }
+  if (event.key === "0") return "10";
+  if (event.key === "-") return "11";
+  return null;
+}

package/src/ui-tailwind/chrome/resolve-target-kind.ts

@@ -33,6 +33,9 @@
  *   - hyperlink       → `<a>` tag.
  *   - opaque-block    → `data-block-kind="opaque"`
  *     added to `TwOpaqueBlock` in Phase D.5 as the explicit marker.
+ *   - template-slot   → `data-node-type="sdt_block"` OR
+ *     `data-block-kind="sdt"` / `data-sdt-type`
+ *     emitted by the PM/page-stack SDT renderers.
  *
  * Multiple kinds can apply — a table cell that contains a hyperlink
  * returns both `table-cell` and `hyperlink`.  Caller merges the
@@ -215,6 +218,16 @@ export function resolveTargetKind(
     if (hasAncestorAttributeValue(el, "data-block-kind", "opaque", root)) {
       kinds.push("opaque-block");
     }
+
+    // SDT / content-control template slots.  These are user-facing chrome
+    // affordances only; import/export/model truth stays with the lower layers.
+    if (
+      hasAncestorAttributeValue(el, "data-node-type", "sdt_block", root) ||
+      hasAncestorAttributeValue(el, "data-block-kind", "sdt", root) ||
+      hasAncestorAttribute(el, ["data-sdt-type"], root)
+    ) {
+      if (!kinds.includes("template-slot")) kinds.push("template-slot");
+    }
   }
 
   // Plain-text baseline so clipboard remains available regardless of

package/src/ui-tailwind/chrome/tw-alert-banner.tsx

@@ -18,6 +18,12 @@ export interface TwAlertBannerProps {
    * the prop preserves the signal-only banner.
    */
   onShowDetail?: () => void;
+  /**
+   * Opaque/preserve-only diagnostics are debug/operator UX. Default
+   * product chrome keeps them silent because the document content is
+   * preserved for export, not actionable for the reader.
+   */
+  showPreservationDiagnostics?: boolean;
 }
 
 /**
@@ -25,7 +31,8 @@ export interface TwAlertBannerProps {
  *
  * Lane 6b §6b.S5 contract:
  *   (1) ONE banner at a time, highest severity wins.
- *   (2) Precedence: fatalError > blockExport > workflowBlocked > preserveOnly.
+ *   (2) Precedence: fatalError > blockExport > workflowBlocked; preserveOnly
+ *       is debug/operator-only via `showPreservationDiagnostics`.
  *   (3) Severity tones bind Lane 6a `--color-semantic-*` tokens — no legacy
  *       `bg-danger-soft` / `bg-warning-soft` / `bg-amber-50` class names.
  *   (4) Error (fatal / blockExport)  → `--color-semantic-error(-soft)`
@@ -84,6 +91,7 @@ export function TwAlertBanner(
     preserveOnlyCount,
     workflowBlockedReasons = [],
     onShowDetail,
+    showPreservationDiagnostics = false,
   } = props;
 
   const showDetailProp: Pick<BannerRender, "onShowDetail"> = onShowDetail
@@ -143,8 +151,8 @@ export function TwAlertBanner(
     });
   }
 
-  // 4. Preserve-only features — lowest precedence warning.
-  if (preserveOnlyCount > 0) {
+  // 4. Preserve-only features — debug/operator-only warning.
+  if (showPreservationDiagnostics && preserveOnlyCount > 0) {
     return renderBanner({
       severity: "warning",
       icon: (

package/src/ui-tailwind/chrome/tw-command-palette.tsx

@@ -72,6 +72,30 @@ interface FlatItem extends CommandPaletteItem {
   groupLabel: string;
 }
 
+function firstEnabledIndex(items: readonly FlatItem[]): number {
+  return items.findIndex((item) => !item.disabled);
+}
+
+function nextEnabledIndex(
+  items: readonly FlatItem[],
+  currentIndex: number,
+  direction: 1 | -1,
+): number {
+  if (items.length === 0) return 0;
+  const start =
+    currentIndex >= 0 && currentIndex < items.length
+      ? currentIndex
+      : direction > 0
+        ? -1
+        : 0;
+  for (let offset = 1; offset <= items.length; offset += 1) {
+    const index = (start + direction * offset + items.length) % items.length;
+    if (!items[index]?.disabled) return index;
+  }
+  const first = firstEnabledIndex(items);
+  return first >= 0 ? first : 0;
+}
+
 /**
  * Fuzzy matcher — returns `true` if the needle matches the haystack as
  * substring OR as a character subsequence.  Cheap, deterministic, and
@@ -145,8 +169,16 @@ export function TwCommandPalette(
 
   // Keep activeIndex inside the filtered result range.
   useEffect(() => {
-    if (activeIndex >= flat.length) setActiveIndex(flat.length > 0 ? 0 : 0);
-  }, [activeIndex, flat.length]);
+    if (flat.length === 0) {
+      if (activeIndex !== 0) setActiveIndex(0);
+      return;
+    }
+    const active = flat[activeIndex];
+    if (!active || active.disabled) {
+      const firstEnabled = firstEnabledIndex(flat);
+      setActiveIndex(firstEnabled >= 0 ? firstEnabled : 0);
+    }
+  }, [activeIndex, flat]);
 
   const close = useCallback(() => onOpenChange(false), [onOpenChange]);
 
@@ -169,14 +201,12 @@ export function TwCommandPalette(
       }
       if (event.key === "ArrowDown") {
         event.preventDefault();
-        setActiveIndex((i) => (flat.length === 0 ? 0 : (i + 1) % flat.length));
+        setActiveIndex((i) => nextEnabledIndex(flat, i, 1));
         return;
       }
       if (event.key === "ArrowUp") {
         event.preventDefault();
-        setActiveIndex((i) =>
-          flat.length === 0 ? 0 : (i - 1 + flat.length) % flat.length,
-        );
+        setActiveIndex((i) => nextEnabledIndex(flat, i, -1));
         return;
       }
       if (event.key === "Enter") {

package/src/ui-tailwind/chrome/tw-context-menu.tsx

@@ -46,6 +46,8 @@ export interface ContextMenuItem {
   id: string;
   /** Display label. */
   label: string;
+  /** Optional explanation, used for disabled product-signpost rows. */
+  description?: string;
   /** Optional icon element rendered left of the label. */
   icon?: React.ReactNode;
   /** Shortcut key sequence shown right-aligned via TwShortcutHint. */
@@ -210,13 +212,16 @@ interface ContextMenuRowProps {
 }
 
 function ContextMenuRow({ item, platform }: ContextMenuRowProps): React.JSX.Element {
-  const { label, icon, shortcut, disabled, onSelect } = item;
+  const { label, description, icon, shortcut, disabled, onSelect } = item;
+  const disabledExplanation = disabled && description ? description : undefined;
 
   return (
     <button
       role="menuitem"
       data-testid={`context-menu-item-${item.id}`}
       disabled={disabled}
+      title={disabledExplanation}
+      data-disabled-reason={disabledExplanation}
       onClick={disabled ? undefined : onSelect}
       className={[
         "flex items-center justify-between h-[30px] w-full px-3",

package/src/ui-tailwind/chrome/tw-display-mode-selector.tsx

@@ -13,15 +13,14 @@
  * names sees the right option highlighted without code changes.
  */
 
-import React, { useLayoutEffect, useRef, useState, type CSSProperties } from "react";
-import { createPortal } from "react-dom";
+import React, { useState } from "react";
+import * as Popover from "@radix-ui/react-popover";
 import { ChevronDown, Eye, EyeOff, Highlighter, Scroll } from "lucide-react";
 
 import {
   normalizeMarkupDisplay,
   type MarkupDisplay,
 } from "../../ui/headless/comment-decoration-model";
-import { preserveEditorSelectionMouseDown } from "../../ui/headless/preserve-editor-selection";
 
 export type DisplayMode = "all-markup" | "simple-markup" | "no-markup" | "original";
 
@@ -68,136 +67,70 @@ const MODES: readonly ModeEntry[] = [
 
 export function TwDisplayModeSelector(props: TwDisplayModeSelectorProps): React.ReactElement {
   const [open, setOpen] = useState(false);
-  const triggerRef = useRef<HTMLButtonElement>(null);
   const canonical = normalizeMarkupDisplay(props.value);
   const activeEntry = MODES.find((m) => m.mode === canonical) ?? MODES[0]!;
 
   return (
-    <>
+    <Popover.Root open={open} onOpenChange={setOpen}>
+      <Popover.Trigger asChild>
         <button
-          ref={triggerRef}
           type="button"
           disabled={props.disabled}
           data-testid={props["data-testid"] ?? "display-mode-selector-trigger"}
           aria-label={`Display mode: ${activeEntry.label}`}
-          aria-expanded={open}
-          aria-haspopup="menu"
-          onMouseDown={preserveEditorSelectionMouseDown}
-          onClick={(event) => {
-            event.preventDefault();
-            setOpen((value) => !value);
-          }}
-          className={[
-            "inline-flex items-center gap-1.5 rounded-md px-2 py-1 text-[11px] font-medium text-primary",
-            "hover:bg-surface focus-visible:outline-none focus-visible:bg-surface disabled:opacity-50",
-            open ? "bg-canvas text-accent ring-1 ring-accent/30 shadow-sm" : "",
-          ].join(" ")}
+          className="inline-flex items-center gap-1.5 rounded-md px-2 py-1 text-[11px] font-medium text-primary hover:bg-surface focus-visible:outline-none focus-visible:bg-surface disabled:opacity-50"
         >
           <activeEntry.icon className="h-3.5 w-3.5 text-tertiary" />
           <span>{activeEntry.label}</span>
           <ChevronDown className="h-3.5 w-3.5 text-tertiary" />
         </button>
-      <DisplayModePortalMenu anchorRef={triggerRef} open={open}>
+      </Popover.Trigger>
+      <Popover.Portal>
+        <Popover.Content
+          className="z-50 w-[260px] rounded-lg bg-canvas p-1 shadow-lg ring-1 ring-border"
+          sideOffset={8}
+          align="end"
+          data-testid="display-mode-selector-content"
+        >
           <div className="mb-1 px-2 py-1 text-[10px] font-semibold uppercase tracking-[0.12em] text-tertiary">
             Display mode
           </div>
           {MODES.map((entry) => {
             const isActive = entry.mode === canonical;
             return (
-              <button
-                key={entry.mode}
-                type="button"
-                role="menuitemradio"
-                aria-checked={isActive}
-                onClick={() => {
-                  props.onChange(entry.mode);
-                  setOpen(false);
-                }}
-                className="flex w-full items-start gap-2 rounded-md px-2 py-1.5 text-left text-[11px] transition-colors hover:bg-surface focus-visible:outline-none focus-visible:bg-surface"
-                data-testid={`display-mode-option-${entry.mode}`}
-                data-mode={entry.mode}
-                data-active={isActive ? "true" : undefined}
-              >
-                <entry.icon
-                  className={[
-                    "mt-0.5 h-3.5 w-3.5 shrink-0",
-                    isActive ? "text-accent" : "text-tertiary",
-                  ].join(" ")}
-                />
-                <span className="flex flex-col">
-                  <span className={`font-medium ${isActive ? "text-accent" : "text-primary"}`}>
-                    {entry.label}
+              <Popover.Close key={entry.mode} asChild>
+                <button
+                  type="button"
+                  role="menuitemradio"
+                  aria-checked={isActive}
+                  onClick={() => {
+                    props.onChange(entry.mode);
+                  }}
+                  className="flex w-full items-start gap-2 rounded-md px-2 py-1.5 text-left text-[11px] transition-colors hover:bg-surface focus-visible:outline-none focus-visible:bg-surface"
+                  data-testid={`display-mode-option-${entry.mode}`}
+                  data-mode={entry.mode}
+                  data-active={isActive ? "true" : undefined}
+                >
+                  <entry.icon
+                    className={[
+                      "mt-0.5 h-3.5 w-3.5 shrink-0",
+                      isActive ? "text-accent" : "text-tertiary",
+                    ].join(" ")}
+                  />
+                  <span className="flex flex-col">
+                    <span className={`font-medium ${isActive ? "text-accent" : "text-primary"}`}>
+                      {entry.label}
+                    </span>
+                    <span className="text-[10px] text-secondary">{entry.hint}</span>
                   </span>
-                  <span className="text-[10px] text-secondary">{entry.hint}</span>
-                </span>
-              </button>
+                </button>
+              </Popover.Close>
             );
           })}
-      </DisplayModePortalMenu>
-    </>
-  );
-}
-
-function DisplayModePortalMenu(props: {
-  anchorRef: React.RefObject<HTMLButtonElement | null>;
-  children: React.ReactNode;
-  open: boolean;
-}): React.ReactPortal | null {
-  const style = useDisplayModePortalPosition(props.anchorRef, props.open);
-  const body = props.anchorRef.current?.ownerDocument?.body;
-  if (!props.open || !body) return null;
-  return createPortal(
-    <div
-      className="z-50 w-[260px] rounded-lg bg-canvas p-1 shadow-lg ring-1 ring-border"
-      data-testid="display-mode-selector-content"
-      style={style}
-    >
-      {props.children}
-    </div>,
-    body,
+        </Popover.Content>
+      </Popover.Portal>
+    </Popover.Root>
   );
 }
 
-function useDisplayModePortalPosition(
-  anchorRef: React.RefObject<HTMLButtonElement | null>,
-  open: boolean,
-): CSSProperties {
-  const [style, setStyle] = useState<CSSProperties>({
-    left: 8,
-    position: "fixed",
-    top: 8,
-    zIndex: 50,
-  });
-
-  useLayoutEffect(() => {
-    if (!open) return;
-    const anchor = anchorRef.current;
-    const ownerWindow = anchor?.ownerDocument?.defaultView;
-    if (!anchor || !ownerWindow) return;
-    const update = () => {
-      const rect = anchor.getBoundingClientRect();
-      const width = 260;
-      const left = Math.min(
-        Math.max(8, rect.right - width),
-        Math.max(8, (ownerWindow.innerWidth || width + 16) - width - 8),
-      );
-      setStyle({
-        left,
-        position: "fixed",
-        top: Math.max(8, rect.bottom + 8),
-        zIndex: 50,
-      });
-    };
-    update();
-    ownerWindow.addEventListener("resize", update);
-    ownerWindow.addEventListener("scroll", update, true);
-    return () => {
-      ownerWindow.removeEventListener("resize", update);
-      ownerWindow.removeEventListener("scroll", update, true);
-    };
-  }, [anchorRef, open]);
-
-  return style;
-}
-
 export default TwDisplayModeSelector;

package/src/ui-tailwind/chrome/tw-inline-find-bar.tsx

@@ -16,6 +16,16 @@ export interface TwInlineFindBarProps {
 export function TwInlineFindBar(props: TwInlineFindBarProps): 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.";
 
   React.useEffect(() => {
     inputRef.current?.focus();
@@ -26,6 +36,7 @@ export function TwInlineFindBar(props: TwInlineFindBarProps): React.JSX.Element
     <div
       className="pointer-events-auto flex w-[min(420px,calc(100vw-2rem))] items-center gap-2 rounded-2xl border border-[color:color-mix(in_srgb,var(--color-accent-primary)_28%,var(--color-border-subtle))] bg-[color:color-mix(in_srgb,var(--color-bg-canvas)_94%,white)] px-2.5 py-2 shadow-[0_18px_50px_rgba(20,31,29,0.18)]"
       data-testid="inline-find-bar"
+      data-result-state={resultState}
       role="search"
       aria-label="Find in document"
     >
@@ -33,6 +44,7 @@ export function TwInlineFindBar(props: TwInlineFindBarProps): React.JSX.Element
       <input
         ref={inputRef}
         aria-label="Find text"
+        aria-describedby="inline-find-bar-status"
         className="min-w-0 flex-1 bg-transparent px-1 text-[13px] font-medium text-primary outline-none placeholder:text-tertiary"
         placeholder="Find in document"
         type="search"
@@ -55,19 +67,24 @@ export function TwInlineFindBar(props: TwInlineFindBarProps): React.JSX.Element
         }}
       />
       <span
-        className="min-w-[56px] rounded-full bg-[color:color-mix(in_srgb,var(--color-accent-primary)_10%,transparent)] px-2 py-1 text-center text-[11px] font-semibold tabular-nums text-accent"
+        id="inline-find-bar-status"
+        data-testid="inline-find-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"
       >
-        {props.query.trim()
-          ? hasResults
-            ? `${props.activeIndex + 1}/${props.resultCount}`
-            : "0/0"
-          : "Find"}
+        {statusLabel}
       </span>
       <button
         type="button"
         aria-label="Previous match"
+        aria-keyshortcuts="Shift+Enter"
         disabled={!hasResults}
+        title={hasResults ? "Previous match (Shift+Enter)" : navDisabledReason}
+        data-testid="inline-find-bar-previous"
         className="inline-flex h-7 w-7 items-center justify-center rounded-full text-secondary transition-colors hover:bg-hover disabled:cursor-not-allowed disabled:opacity-35"
         onMouseDown={preserveEditorSelectionMouseDown}
         onClick={props.onPrevious}
@@ -77,7 +94,10 @@ export function TwInlineFindBar(props: TwInlineFindBarProps): React.JSX.Element
       <button
         type="button"
         aria-label="Next match"
+        aria-keyshortcuts="Enter"
         disabled={!hasResults}
+        title={hasResults ? "Next match (Enter)" : navDisabledReason}
+        data-testid="inline-find-bar-next"
         className="inline-flex h-7 w-7 items-center justify-center rounded-full text-secondary transition-colors hover:bg-hover disabled:cursor-not-allowed disabled:opacity-35"
         onMouseDown={preserveEditorSelectionMouseDown}
         onClick={props.onNext}