@plannotator/ui 0.53.1 → 0.55.0

package/components/CodeSnippetPreview.tsx

@@ -0,0 +1,174 @@
+import React, { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { ensureHighlight, highlightToHtml } from "../utils/codeHighlight";
+import { useFenceTheme } from "../hooks/useFenceTheme";
+
+/**
+ * The floating code window a code-file reference opens on hover: a few lines
+ * of one file, syntax highlighted, with line numbers. Portalled to the body
+ * and positioned under (or above) its anchor.
+ *
+ * Used by plan / annotate code-file links (`CodeFileLink` in InlineMarkdown,
+ * the exact range only) and by code review's Call Flow locations
+ * (`CallFlowTreeView`, with `contextLines` around the target).
+ */
+
+/** Lines highlighted above the shown ones so a range opening inside a block comment or string tokenises as one. */
+const HIGHLIGHT_LEAD_IN_LINES = 40;
+/** Gap kept between the window and the viewport edge. */
+const VIEWPORT_MARGIN = 8;
+
+/** The highlighter language for a file path, by extension; undefined renders plain text. */
+export function codeSnippetLanguage(filepath: string): string | undefined {
+  const ext = filepath.split('.').pop()?.toLowerCase();
+  const map: Record<string, string> = {
+    ts: 'typescript', tsx: 'typescript', js: 'javascript', jsx: 'javascript',
+    mts: 'typescript', cts: 'typescript', mjs: 'javascript', cjs: 'javascript',
+    py: 'python', rb: 'ruby', rs: 'rust', go: 'go', java: 'java',
+    css: 'css', scss: 'scss', json: 'json', yml: 'yaml', yaml: 'yaml',
+    sql: 'sql', sh: 'bash', bash: 'bash', zsh: 'bash', md: 'markdown',
+    html: 'html', xml: 'xml', toml: 'toml', swift: 'swift', kt: 'kotlin',
+    lua: 'lua', c: 'c', h: 'c', cpp: 'cpp', hpp: 'cpp', cs: 'csharp',
+    scala: 'scala', dart: 'dart', ex: 'elixir', exs: 'elixir', zig: 'zig',
+    vue: 'vue', svelte: 'svelte', astro: 'astro', php: 'php',
+  };
+  return ext ? map[ext] : undefined;
+}
+
+export interface CodeSnippetPreviewProps {
+  anchorEl: HTMLElement | null;
+  /** The whole file; the preview slices the lines it shows. */
+  contents: string;
+  filepath: string;
+  /** One-based first line of the target range. */
+  line: number;
+  lineEnd?: number;
+  /** Lines shown above and below the target range, the target rows marked. 0 (default) shows the range alone. */
+  contextLines?: number;
+  /** Header label; defaults to the file's basename. */
+  title?: string;
+  /** Called when the page or a scroller scrolls: the window is placed once and would drift from its anchor. */
+  onDismiss?: () => void;
+  onMouseEnter?: () => void;
+  onMouseLeave?: () => void;
+}
+
+export const CodeSnippetPreview: React.FC<CodeSnippetPreviewProps> = ({
+  anchorEl,
+  contents,
+  filepath,
+  line,
+  lineEnd,
+  contextLines = 0,
+  title,
+  onDismiss,
+  onMouseEnter,
+  onMouseLeave,
+}) => {
+  const allLines = contents.split('\n');
+  const targetStart = Math.max(0, line - 1);
+  const targetEnd = Math.min(allLines.length, lineEnd ?? line);
+  const start = Math.max(0, targetStart - contextLines);
+  const end = Math.min(allLines.length, targetEnd + contextLines);
+  const snippet = allLines.slice(start, end).join('\n');
+  // Highlight from a little earlier than the first shown line: a range that
+  // starts inside a block comment or template literal would otherwise colour
+  // that text as code.
+  const highlightStart = Math.max(0, start - HIGHLIGHT_LEAD_IN_LINES);
+  const highlightSource = allLines.slice(highlightStart, end).join('\n');
+  const marksTarget = contextLines > 0;
+
+  const fenceTheme = useFenceTheme();
+  // Bumped once the grammar is attached, to re-run the memo below with the
+  // highlighter warm. Until then the snippet renders as plain text — no
+  // auto-detection, and an unknown extension simply stays plain.
+  const [highlighterGeneration, setHighlighterGeneration] = useState(0);
+  const lang = codeSnippetLanguage(filepath);
+
+  useEffect(() => {
+    if (!lang) return;
+    let cancelled = false;
+    void ensureHighlight(lang, fenceTheme).then((ok) => {
+      if (ok && !cancelled) setHighlighterGeneration((n) => n + 1);
+    });
+    return () => { cancelled = true; };
+  }, [lang, fenceTheme]);
+
+  useEffect(() => {
+    if (!onDismiss) return;
+    const dismiss = () => onDismiss();
+    window.addEventListener('scroll', dismiss, { capture: true, passive: true });
+    return () => window.removeEventListener('scroll', dismiss, { capture: true });
+  }, [onDismiss]);
+
+  const highlightedLines = useMemo(() => {
+    // Highlight the snippet as one unit so multi-line constructs (block
+    // comments, template literals) tokenise correctly, then split back into
+    // rows: the highlighter joins lines with "\n" and never emits one inside a
+    // span, so the split is exact.
+    const html = lang ? highlightToHtml(highlightSource, lang, fenceTheme) : null;
+    if (html !== null) return html.split('\n').slice(start - highlightStart);
+    return snippet.split('\n').map(text =>
+      text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;'));
+    // highlighterGeneration is the "grammar just became available" signal.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [snippet, highlightSource, start, highlightStart, lang, fenceTheme, highlighterGeneration]);
+
+  // Clamp against the window's rendered width (it sizes to its longest line,
+  // up to its max width) so a wide snippet never runs off the right edge.
+  const windowRef = useRef<HTMLDivElement | null>(null);
+  const [renderedWidth, setRenderedWidth] = useState<number | null>(null);
+  useLayoutEffect(() => {
+    const width = windowRef.current?.offsetWidth ?? null;
+    if (width !== renderedWidth) setRenderedWidth(width);
+  });
+
+  if (!anchorEl) return null;
+
+  const rect = anchorEl.getBoundingClientRect();
+  const spaceBelow = window.innerHeight - rect.bottom;
+  const showAbove = spaceBelow < 200 && rect.top > spaceBelow;
+  const top = showAbove ? undefined : rect.bottom + 4;
+  const bottom = showAbove ? window.innerHeight - rect.top + 4 : undefined;
+  const left = Math.max(VIEWPORT_MARGIN, Math.min(rect.left, window.innerWidth - (renderedWidth ?? 520) - VIEWPORT_MARGIN));
+
+  return createPortal(
+    <div
+      ref={windowRef}
+      className="code-snippet-preview-window fixed z-[9999] rounded-lg border border-border bg-card shadow-xl flex flex-col"
+      style={{ top, bottom, left, maxWidth: `min(600px, calc(100vw - ${VIEWPORT_MARGIN * 2}px))`, maxHeight: '300px' }}
+      data-code-snippet-preview={filepath}
+      onMouseEnter={onMouseEnter}
+      onMouseLeave={onMouseLeave}
+    >
+      <div className="px-3 py-1.5 border-b border-border/50 text-[10px] text-muted-foreground font-mono flex items-center justify-between gap-4 flex-shrink-0">
+        <span>{title ?? filepath.split('/').pop()}</span>
+        <span className="opacity-60">{lineEnd && lineEnd !== line ? `lines ${line}–${lineEnd}` : `line ${line}`}</span>
+      </div>
+      <div className="code-snippet-preview overflow-auto text-[12px] leading-5 min-h-0" style={{ padding: 0, background: 'var(--code-bg, #1e293b)' }}>
+        <table className="border-collapse w-full">
+          <tbody>
+            {snippet.split('\n').map((_, i) => {
+              const index = start + i;
+              const target = marksTarget && index >= targetStart && index < targetEnd;
+              return (
+                <tr
+                  key={index}
+                  className={target ? 'bg-primary/15' : 'hover:bg-white/5'}
+                  data-target-line={target ? 'true' : undefined}
+                >
+                  <td className={`select-none text-right pr-3 pl-3 py-0 align-top font-mono w-8 whitespace-nowrap ${target ? 'text-primary' : 'text-muted-foreground/40'}`} style={{ userSelect: 'none' }}>{index + 1}</td>
+                  <td
+                    className="font-mono pr-3 py-0 whitespace-pre"
+                    dangerouslySetInnerHTML={{ __html: highlightedLines[i] ?? '' }}
+                  />
+                </tr>
+              );
+            })}
+          </tbody>
+        </table>
+      </div>
+    </div>,
+    document.body,
+  );
+};

package/components/CommentPopover.tsx

@@ -5,6 +5,8 @@ import { AttachmentsButton } from './AttachmentsButton';
 import { useDraggable } from '../hooks/useDraggable';
 import { SparklesIcon } from './SparklesIcon';
 import { hasUnsavedCommentContent } from '../utils/commentContent';
+import { isCommentSubmitKey } from '../utils/commentSubmitKey';
+import { useConfigValue } from '../config/useConfig';
 import { useSkillReferenceAutocomplete } from '../hooks/useSkillReferenceAutocomplete';
 import { HumanOnlySkillNotice, SkillReferenceMenu } from './SkillReferenceMenu';
 import { ComposerTokenTextarea, type ComposerMentionChips } from './ComposerTokenTextarea';
@@ -119,6 +121,20 @@ interface CommentPopoverProps {
   /** Opt-in composer yield while shift-selecting: 'near' fades the composer,
    *  'over' makes it near-invisible and click-through. Undefined → no-op. */
   yieldState?: CommentPopoverYieldState;
+  /** Opt-in: the header's text in place of the quoted `contextText` (an image
+   *  region's "Region 3 · 356 × 486 px"). Absent → the quote, as always. */
+  headerText?: string;
+  /** Opt-in: `side` opens the popover beside the anchor (right, else left),
+   *  falling back to below/above when neither side has room (an image region
+   *  in the image viewer). Absent → below/above, as always. */
+  placement?: 'below' | 'side';
+  /** Opt-in: the stacking level, for a composer over a surface that is
+   *  itself above the page (the image viewer is z-200). Absent → 100. */
+  zIndex?: number;
+  /** Opt-out: `false` mounts the composer without taking focus (an HTML
+   *  pin's composer shown again when its hidden target returns, so focus
+   *  stays where the person is). Absent → focuses on mount, as always. */
+  autoFocus?: boolean;
 }
 
 const MAX_POPOVER_WIDTH = 384;
@@ -151,7 +167,19 @@ interface CommentPopoverPosition {
 export function computeCommentPopoverPosition(
   anchorRect: Pick<DOMRect, 'top' | 'right' | 'bottom' | 'left' | 'width'>,
   bounds: VisibleViewportBounds,
+  placement: 'below' | 'side' = 'below',
 ): CommentPopoverPosition {
+  if (placement === 'side') {
+    const width = Math.min(MAX_POPOVER_WIDTH, bounds.width);
+    const right = anchorRect.right + GAP * 1.75;
+    const left = anchorRect.left - GAP * 1.75 - width;
+    const sideLeft = right + width <= bounds.right ? right : left >= bounds.left ? left : null;
+    if (sideLeft !== null) {
+      const top = Math.max(bounds.top, Math.min(anchorRect.top, bounds.bottom - 280));
+      const maxHeight = Math.max(0, bounds.bottom - top);
+      if (maxHeight >= 280) return { top, left: sideLeft, flipAbove: false, width, maxHeight, requiresExpanded: false };
+    }
+  }
   const spaceBelow = Math.max(0, bounds.bottom - anchorRect.bottom - GAP);
   const spaceAbove = Math.max(0, anchorRect.top - bounds.top - GAP);
   const flipAbove = spaceBelow < 280 && spaceAbove > spaceBelow;
@@ -199,6 +227,10 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
   refocusToken,
   captureStrayKeys = false,
   yieldState,
+  headerText,
+  placement = 'below',
+  zIndex,
+  autoFocus = true,
 }) => {
   const visibleBounds = useVisibleViewportBounds(16);
   const coarsePointer = hasPrimaryCoarsePointer();
@@ -266,7 +298,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
     const update = () => {
       const rect = anchorEl?.getBoundingClientRect() ?? anchorRect;
       if (!rect) return;
-      const nextPosition = computeCommentPopoverPosition(rect, visibleBounds);
+      const nextPosition = computeCommentPopoverPosition(rect, visibleBounds, placement);
       if (nextPosition.requiresExpanded) {
         setDialogIsForced(true);
         setMode('dialog');
@@ -280,7 +312,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
     return () => {
       window.removeEventListener('scroll', update, true);
     };
-  }, [anchorEl, anchorRect, mode, visibleBounds, wasDragged]);
+  }, [anchorEl, anchorRect, mode, visibleBounds, wasDragged, placement]);
 
   // Surface a "jump back" arrow when an open popover scrolls out of view.
   // Re-measures whenever the popover repositions (position updates every scroll
@@ -307,7 +339,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
   // renders after `position` is measured, and WebKit fires 0ms timers ahead of
   // that commit, so an effect keyed on mode alone can run before the textarea
   // exists and never focus it (e.g. in WKWebView hosts like Glimpse).
-  const shouldAutoFocus = !coarsePointer || initialText.length > 0 || isGlobal;
+  const shouldAutoFocus = autoFocus && (!coarsePointer || initialText.length > 0 || isGlobal);
   const focusOnMountRef = useCallback((el: HTMLTextAreaElement | null) => {
     textareaRef.current = el;
     if (!el || !shouldAutoFocus) return;
@@ -322,13 +354,13 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
   // summon the software keyboard), but hardware-keyboard users still need a
   // coherent focus target and Escape dismissal.
   useEffect(() => {
-    if (mode !== 'dialog' || shouldAutoFocus) return;
+    if (mode !== 'dialog' || shouldAutoFocus || !autoFocus) return;
     const timer = setTimeout(() => {
       if (!popoverRef.current?.isConnected) return;
       popoverRef.current.focus({ preventScroll: true });
     }, 0);
     return () => clearTimeout(timer);
-  }, [mode, shouldAutoFocus]);
+  }, [autoFocus, mode, shouldAutoFocus]);
 
   const restoreOpeningFocus = useCallback(() => {
     const target = openingFocusRef.current;
@@ -561,6 +593,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
   const composerListboxOpen = skillAc.menu !== null || mentionAc.menu !== null;
   const activeComposerOptionId = activeSkillOptionId ?? activeMentionOptionId;
 
+  const enterSavesComment = useConfigValue('enterSavesComment');
   const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
     if (skillAc.onKeyDown(e)) return;
     if (mentionAc.onKeyDown(e)) return;
@@ -577,17 +610,17 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
       }
       return;
     }
-    if (e.key === 'Enter' && (e.metaKey || e.ctrlKey) && !e.nativeEvent.isComposing) {
+    if (isCommentSubmitKey(e, enterSavesComment)) {
       e.preventDefault();
       handleSubmit();
     }
   };
 
-  const headerLabel = isGlobal
+  const headerLabel = headerText ?? (isGlobal
     ? 'Global Comment'
     : contextText
       ? `"${contextText.length > 50 ? contextText.slice(0, 50) + '...' : contextText}"`
-      : 'Comment';
+      : 'Comment');
 
   const canSubmit =
     hasUnsavedContent ||
@@ -630,6 +663,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
       <div
         data-comment-popover="true"
         className="pn-visible-viewport-overlay z-[100] flex items-center justify-center"
+        style={zIndex !== undefined ? { zIndex } : undefined}
       >
         {/* Backdrop */}
         <button
@@ -797,6 +831,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
       className={`fixed z-[100] bg-popover border border-border rounded-xl shadow-2xl flex flex-col${yieldClass}`}
       style={dragPosition
         ? {
+            ...(zIndex !== undefined ? { zIndex } : {}),
             top: dragPosition.top,
             left: dragPosition.left,
             width: position.width,
@@ -804,6 +839,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
             overflowY: showsSkillMenu ? 'visible' : 'auto',
           }
         : {
+            ...(zIndex !== undefined ? { zIndex } : {}),
             top: position.top,
             left: position.left,
             width: position.width,

package/components/DecisionControl.tsx

@@ -8,6 +8,7 @@ import { ConfirmDialog, type ConfirmDialogProps } from './ConfirmDialog';
 import { useDismissablePopover } from '../hooks/useDismissablePopover';
 import { useCompactTouchLayout } from '../hooks/useIsMobile';
 import { cn } from '../lib/utils';
+import { isCommentSubmitKey } from '../utils/commentSubmitKey';
 import type {
   DecisionActionId,
   DecisionComposer,
@@ -57,6 +58,16 @@ export interface DecisionControlProps {
   dismissOnIframeFocus?: boolean;
   /** Confirm surface override; defaults to the ui ConfirmDialog. */
   confirmDialog?: React.ComponentType<ConfirmDialogProps>;
+  /**
+   * Rows rendered under the decisions, inside the same menu (#1057: plan
+   * review's "After approval, switch to" agent picker and Claude Code's
+   * permission-mode line). Not decisions: they never close the menu by
+   * themselves. Interactive rows use `role="menuitem"` or
+   * `role="menuitemradio"` so the arrow keys reach them. Absent: the menu is
+   * the decisions alone, exactly as before. A function receives
+   * `closeMenu`, for a row that leaves the menu (e.g. one opening Settings).
+   */
+  menuFooter?: React.ReactNode | ((api: { closeMenu: () => void }) => React.ReactNode);
 }
 
 const NOTE_MAX_HEIGHT_PX = 144;
@@ -98,6 +109,14 @@ export interface DecisionNoteFieldProps {
   placeholder?: string;
   disabled?: boolean;
   autoFocus?: boolean;
+  /**
+   * The field is a COMMENT composer (the review sidebar's "+ General
+   * comment"), so the "Enter saves a comment" setting applies: pass its value
+   * and a plain Enter also submits (Shift+Enter stays a new line). Default
+   * false: in the decision control's own composer a note rides a decision,
+   * and only Mod+Enter fires it.
+   */
+  enterSubmits?: boolean;
 }
 
 /**
@@ -114,6 +133,7 @@ export const DecisionNoteField: React.FC<DecisionNoteFieldProps> = ({
   placeholder = 'Add a note...',
   disabled = false,
   autoFocus = true,
+  enterSubmits = false,
 }) => {
   const ref = useAutoGrow(text);
 
@@ -132,15 +152,15 @@ export const DecisionNoteField: React.FC<DecisionNoteFieldProps> = ({
         onCancel();
         return;
       }
-      if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
+      if (enterSubmits ? isCommentSubmitKey(event, true) : event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
         event.preventDefault();
         event.stopPropagation();
         if (!disabled) onSubmit();
       }
-      // Plain Enter falls through: the field is multi-line and Enter's job is
-      // a newline.
+      // Otherwise plain Enter falls through: the field is multi-line and
+      // Enter's job is a newline.
     },
-    [disabled, onCancel, onSubmit],
+    [disabled, enterSubmits, onCancel, onSubmit],
   );
 
   return (
@@ -255,6 +275,7 @@ export const DecisionControl: React.FC<DecisionControlProps> = ({
   labelBreakpoint = 'md',
   dismissOnIframeFocus = false,
   confirmDialog,
+  menuFooter,
 }) => {
   const rootRef = useRef<HTMLDivElement>(null);
   const popoverRef = useRef<HTMLDivElement>(null);
@@ -402,7 +423,9 @@ export const DecisionControl: React.FC<DecisionControlProps> = ({
       const keys = ['ArrowDown', 'ArrowUp', 'Home', 'End'];
       if (!keys.includes(event.key)) return;
       const items = Array.from(
-        popoverRef.current?.querySelectorAll<HTMLButtonElement>('[role="menuitem"]:not(:disabled)') ?? [],
+        popoverRef.current?.querySelectorAll<HTMLButtonElement>(
+          '[role="menuitem"]:not(:disabled), [role="menuitemradio"]:not(:disabled)',
+        ) ?? [],
       );
       if (items.length === 0) return;
       event.preventDefault();
@@ -548,6 +571,9 @@ export const DecisionControl: React.FC<DecisionControlProps> = ({
                   />
                 </React.Fragment>
               ))}
+              {typeof menuFooter === 'function'
+                ? menuFooter({ closeMenu: () => closePopover() })
+                : menuFooter}
             </div>
           ) : activeItem?.composer ? (
             <div className="p-2">

package/components/DeferredMarkdownContentsRail.tsx

@@ -0,0 +1,38 @@
+// Moved from the Workspaces app's DeferredMarkdownContentsRail with its
+// contents rail (MarkdownContentsRail, approved 2026-10-03). Port: the props
+// are the rail's own (`MarkdownContentsRailProps`), passed through.
+
+import { lazy, Suspense, useEffect, useState } from 'react';
+
+import type { MarkdownContentsRailProps } from './MarkdownContentsRail';
+
+const MarkdownContentsRail = lazy(() =>
+  import('./MarkdownContentsRail').then((module) => ({
+    default: module.MarkdownContentsRail,
+  })),
+);
+
+export function scheduleMarkdownContentsRail(callback: () => void): () => void {
+  if (typeof window.requestIdleCallback === 'function') {
+    const handle = window.requestIdleCallback(callback, { timeout: 2000 });
+    return () => window.cancelIdleCallback(handle);
+  }
+  const handle = window.setTimeout(callback, 0);
+  return () => window.clearTimeout(handle);
+}
+
+/** Load the reading aid after the document is interactive, never in the
+ * critical document-paint path. The timeout still guarantees it appears on
+ * a busy page; Safari and tests use the zero-delay fallback. */
+export function DeferredMarkdownContentsRail(props: MarkdownContentsRailProps) {
+  const [ready, setReady] = useState(false);
+
+  useEffect(() => scheduleMarkdownContentsRail(() => setReady(true)), []);
+
+  if (!ready) return null;
+  return (
+    <Suspense fallback={null}>
+      <MarkdownContentsRail {...props} />
+    </Suspense>
+  );
+}

package/components/DiagramBlock.tsx

@@ -16,6 +16,7 @@ import { svgContentSize } from './diagram/svgContentSize';
 import type { DiagramComment, DiagramCreateComment } from './diagram/useDiagramComments';
 import type { DiagramRenderState } from './diagram/useDiagramRender';
 import { useTheme } from './ThemeProvider';
+import { LazyBlockBoundary } from './LazyBlockBoundary';
 
 /**
  * A diagram fence in the document: the fence's language picks the engine
@@ -345,7 +346,7 @@ export const DiagramBlock: React.FC<DiagramBlockProps & { kind: DiagramKind }> =
           appears in a node label) can never wrap a <mark> inside the svg. */}
       <div ref={rootRef} className="annotation-exclude my-5 group relative" data-block-id={block.id} data-pinpoint-ignore="" data-diagram-block={kind}>
         {svgReady && !showSource && (
-          <div data-print-hide="" className="absolute top-2 right-2 z-10 flex items-center gap-1 opacity-0 group-hover:opacity-100 focus-within:opacity-100 transition-opacity">
+          <div data-print-hide="" className="absolute top-2 right-2 z-10 flex items-center gap-1 opacity-0 group-hover:opacity-100 focus-within:opacity-100 [@media(hover:none)]:opacity-100 transition-opacity">
             <button
               type="button"
               onClick={() => setShowSource(true)}
@@ -404,17 +405,21 @@ export const DiagramBlock: React.FC<DiagramBlockProps & { kind: DiagramKind }> =
         )}
       </div>
       {isExpanded && svgReady && typeof document !== 'undefined' && (
-        <Suspense fallback={null}>
-          <DiagramPopout
-            {...viewerProps}
-            open
-            onClose={() => setIsExpanded(false)}
-            title={`${label} diagram`}
-            renderId={`${kind}-${block.id}-popout`}
-            onAskAI={handlePopoutAskAI}
-            dataAttributes={{ 'data-block-id': block.id }}
-          />
-        </Suspense>
+        // A popout chunk that cannot load leaves the inline diagram as it is
+        // and says so under it.
+        <LazyBlockBoundary fallback={(notice) => <div className="mb-5">{notice}</div>}>
+          <Suspense fallback={null}>
+            <DiagramPopout
+              {...viewerProps}
+              open
+              onClose={() => setIsExpanded(false)}
+              title={`${label} diagram`}
+              renderId={`${kind}-${block.id}-popout`}
+              onAskAI={handlePopoutAskAI}
+              dataAttributes={{ 'data-block-id': block.id }}
+            />
+          </Suspense>
+        </LazyBlockBoundary>
       )}
     </>
   );

package/components/DiffFileTree.tsx

@@ -11,12 +11,13 @@ export type { DiffFileTreeFile, DiffFileTreeNode, DiffFileTreeStatus } from '../
 export type { DiffFileTreeDefaultExpanded } from '../hooks/useDiffFileTreeExpansion';
 
 /*
- * The diff file tree's presentational parts. Plannotator's code review renders
- * its tree rows from the atoms below (folder row, file-row content, change
- * letter, +/- counts, indentation), adding its review-only decorations
- * (viewed/stage controls, annotation badge, context menu) around them; the
- * `DiffFileTree` component at the bottom is the read-only, embeddable tree a
- * host drops beside its own diff list.
+ * The diff file tree's presentational parts: the atoms below (folder row,
+ * file-row content, change letter, +/- counts, indentation) for a host's own
+ * rows, and the `DiffFileTree` component at the bottom, the read-only,
+ * embeddable tree a host drops beside its own diff list. Plannotator's code
+ * review shares `ChangeTypeLetter` and `diffFileTreeIndent` (its All files
+ * tree) but draws its own Changes rows since its aligned sidebar (see
+ * HANDOFF.md § "Diff file tree").
  */
 
 /** Left padding of a row at `depth` (px). */

package/components/DocumentContents.tsx

@@ -0,0 +1,74 @@
+import { useLayoutEffect, useMemo, useRef } from 'react';
+import type { Annotation, Block } from '../types';
+import { CONTENTS_RAIL_MAX_LEVEL, tocHeadings } from '../utils/annotationHelpers';
+import { useHeadingScrollSpy } from '../hooks/useHeadingScrollSpy';
+import { TableOfContents } from './TableOfContents';
+
+interface DocumentContentsProps {
+  blocks: Block[];
+  annotations: Annotation[];
+  /**
+   * The element the document scrolls in. The current heading is read from it
+   * and a click scrolls it. `null` until it has mounted.
+   */
+  scrollViewport: HTMLElement | null;
+  /** Called with the heading's block id after a click (a sheet closes itself here). */
+  onNavigate?: (blockId: string) => void;
+  className?: string;
+}
+
+/**
+ * A document's Contents list for a host without plan review's sidebar, on the
+ * contents rail's surface (the Inbox's sheet, where the rail yields): the same
+ * `TableOfContents` (click to scroll, the current heading highlighted) with
+ * the rail's headings (levels 1 to 4) and the rail's scroll math
+ * (`useHeadingScrollSpy`), so the list and the rail never disagree. It draws
+ * no chrome; the host places it and titles it.
+ *
+ * The host mounts it afresh (a sheet that opens), often mid-document: the
+ * current heading is read at once. The marked entry is kept in view inside the
+ * list's own scroll box (a sheet).
+ */
+export function DocumentContents({ blocks, annotations, scrollViewport, onNavigate, className = '' }: DocumentContentsProps) {
+  const headingIds = useMemo(
+    () => tocHeadings(blocks, CONTENTS_RAIL_MAX_LEVEL).map((heading) => heading.id),
+    [blocks],
+  );
+  const activeId = useHeadingScrollSpy(scrollViewport, headingIds);
+
+  const wrapRef = useRef<HTMLDivElement>(null);
+  useLayoutEffect(() => {
+    const item = wrapRef.current?.querySelector<HTMLElement>('[aria-current="location"]');
+    if (item) revealInList(item);
+  }, [activeId]);
+
+  return (
+    <div ref={wrapRef} style={{ display: 'contents' }}>
+      <TableOfContents
+        blocks={blocks}
+        annotations={annotations}
+        activeId={activeId}
+        onNavigate={onNavigate ?? noop}
+        scrollViewport={scrollViewport}
+        maxLevel={CONTENTS_RAIL_MAX_LEVEL}
+        className={className}
+      />
+    </div>
+  );
+}
+
+/**
+ * Scroll the list's own scroll box (the nearest ancestor that scrolls) just
+ * enough to show `item`, at once. Never the page or the document behind it.
+ */
+function revealInList(item: HTMLElement) {
+  let box = item.parentElement;
+  while (box && !/(auto|scroll)/.test(getComputedStyle(box).overflowY)) box = box.parentElement;
+  if (!box || box.scrollHeight <= box.clientHeight) return;
+  const area = box.getBoundingClientRect();
+  const rect = item.getBoundingClientRect();
+  if (rect.top < area.top) box.scrollTop -= area.top - rect.top;
+  else if (rect.bottom > area.bottom) box.scrollTop += Math.min(rect.bottom - area.bottom, rect.top - area.top);
+}
+
+function noop() {}

package/components/EditorAnnotationCard.tsx

@@ -42,7 +42,7 @@ export const EditorAnnotationCard: React.FC<EditorAnnotationCardProps> = ({ anno
         {onDelete && (
           <button
             onClick={(e) => { e.stopPropagation(); onDelete(); }}
-            className="ml-auto relative rounded-md p-1.5 text-muted-foreground transition-colors before:absolute before:-inset-1.5 before:content-[''] opacity-0 group-hover:opacity-100 [@media(hover:none)]:opacity-100 hover:text-destructive"
+            className="ml-auto relative rounded-md p-1.5 text-muted-foreground transition-colors before:absolute before:-inset-1.5 before:content-[''] opacity-0 group-hover:opacity-100 group-focus-within:opacity-100 [@media(hover:none)]:opacity-100 hover:text-destructive"
             title="Delete annotation"
           >
             <svg className="w-3 h-3" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>