@plannotator/ui 0.53.1 → 0.54.0

package/components/AnnotationToolbar.tsx

@@ -4,6 +4,7 @@ import { createPortal } from "react-dom";
 import { useDismissOnOutsideAndEscape } from "../hooks/useDismissOnOutsideAndEscape";
 import { type QuickLabel, getQuickLabels, quickLabelIndexForDigit, THUMBS_UP_LABEL } from "../utils/quickLabels";
 import { copyTextToClipboard } from "../utils/clipboard";
+import { copyRichSelection, richCopyOutcomeLabel, type RichCopyOutcome, type RichCopySource } from "../utils/richClipboard";
 import { acquireTypeToCommentCapture } from "../shortcuts/plan-review/annotationMode.shortcuts";
 import { FloatingQuickLabelPicker } from "./FloatingQuickLabelPicker";
 import { FloatingSelectionActionsPicker } from "./SelectionActionsDropdown";
@@ -30,6 +31,12 @@ interface AnnotationToolbarProps {
   onQuickLabel?: (label: QuickLabel) => void;
   /** Text to copy when the button is clicked */
   copyText?: string;
+  /** Builds the captured text selection's sanitized HTML and plain text when
+   *  Copy is pressed (never before). When present, Copy writes text/html plus
+   *  text/plain in one clipboard write (a plain field still pastes plain
+   *  text), and the Copy button shows even where hideCopyButton hides it.
+   *  Absent: Copy copies plain text, exactly as before. No shortcut. */
+  getRichCopy?: () => RichCopySource | Promise<RichCopySource>;
   /** Comment-only surfaces (HTML / live-app viewer): hide the Delete action,
    *  the quick-label picker, and the Alt+digit label shortcuts. A provided
    *  onQuickLabel then renders ONLY the hardcoded 👍 "Looks good" button —
@@ -57,7 +64,7 @@ interface AnnotationToolbarProps {
    * this toolbar. The one-click 👍 is a separate affordance and is unaffected.
    */
   quickLabels?: boolean;
-  /** Hide the copy button (set when a keyboard copy handler exists) */
+  /** Hide the plain copy button (set when a keyboard copy handler exists) */
   hideCopyButton?: boolean;
   /** Close toolbar when element scrolls out of viewport */
   closeOnScrollOut?: boolean;
@@ -79,6 +86,7 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
   selectionActionsIcon,
   quickLabels: quickLabelsEnabled = true,
   copyText,
+  getRichCopy,
   commentOnly = false,
   hideCopyButton = false,
   closeOnScrollOut = false,
@@ -88,6 +96,10 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
 }) => {
   const [position, setPosition] = useState<{ top: number; left?: number; right?: number } | null>(null);
   const [copied, setCopied] = useState(false);
+  const [richCopied, setRichCopied] = useState<RichCopyOutcome | false>(false);
+  const richCopyTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const richCopySelectionRef = useRef({ element, getRichCopy });
+  richCopySelectionRef.current = { element, getRichCopy };
   const [showQuickLabels, setShowQuickLabels] = useState(false);
   const [showSelectionActions, setShowSelectionActions] = useState(false);
   const toolbarRef = useRef<HTMLDivElement>(null);
@@ -107,7 +119,18 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
   const selectionActionsOpen = showSelectionActions && hasSelectionActions;
   const quickLabelsOpen = showQuickLabels && !commentOnly && quickLabelsEnabled;
 
-  useEffect(() => { setCopied(false); }, [element]);
+  useEffect(() => {
+    setCopied(false);
+    setRichCopied(false);
+  }, [element]);
+  useEffect(() => {
+    setRichCopied(false);
+    if (richCopyTimeoutRef.current !== null) clearTimeout(richCopyTimeoutRef.current);
+    richCopyTimeoutRef.current = null;
+  }, [element, getRichCopy]);
+  useEffect(() => () => {
+    if (richCopyTimeoutRef.current !== null) clearTimeout(richCopyTimeoutRef.current);
+  }, []);
 
   const handleCopy = async () => {
     let textToCopy = copyText;
@@ -121,6 +144,24 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
     }
   };
 
+  const handleRichCopy = async () => {
+    setRichCopied(false);
+    const build = getRichCopy;
+    if (!build) return;
+    const fallback = copyText || element.querySelector('code')?.textContent || element.textContent || '';
+    const result = await copyRichSelection(build, fallback);
+    const current = richCopySelectionRef.current;
+    if (current.element !== element || current.getRichCopy !== build) return;
+    if (result) {
+      setRichCopied(result);
+      if (richCopyTimeoutRef.current !== null) clearTimeout(richCopyTimeoutRef.current);
+      richCopyTimeoutRef.current = setTimeout(() => {
+        setRichCopied(false);
+        richCopyTimeoutRef.current = null;
+      }, 1500);
+    }
+  };
+
   // Update position on scroll/resize
   useEffect(() => {
     const updatePosition = () => {
@@ -252,14 +293,28 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
         }
       `}</style>
       <div data-pn-annotation-toolbar-row="true" className="flex items-center p-1 gap-0.5">
-        {!hideCopyButton && (
+        {(!hideCopyButton || getRichCopy) && (
           <>
-            <ToolbarButton
-              onClick={handleCopy}
-              icon={copied ? <CheckIcon /> : <CopyIcon />}
-              label={copied ? "Copied!" : "Copy"}
-              className={copied ? "text-success" : "text-muted-foreground hover:bg-muted hover:text-foreground"}
-            />
+            {getRichCopy ? (
+              // One Copy button: rich text (text/html plus text/plain) where
+              // the host turned rich copy on. "Copied!" for a rich copy; a
+              // plain-text fallback says what went on the clipboard.
+              <ToolbarButton
+                onClick={handleRichCopy}
+                icon={richCopied ? <CheckIcon /> : <CopyIcon />}
+                label={!richCopied ? "Copy"
+                  : richCopied.copied === 'rich' ? "Copied!"
+                  : richCopyOutcomeLabel(richCopied)}
+                className={richCopied ? "text-success" : "text-muted-foreground hover:bg-muted hover:text-foreground"}
+              />
+            ) : (
+              <ToolbarButton
+                onClick={handleCopy}
+                icon={copied ? <CheckIcon /> : <CopyIcon />}
+                label={copied ? "Copied!" : "Copy"}
+                className={copied ? "text-success" : "text-muted-foreground hover:bg-muted hover:text-foreground"}
+              />
+            )}
             <div className="w-px h-5 bg-border mx-0.5" />
           </>
         )}

package/components/ApproveDropdown.tsx

@@ -1,7 +1,8 @@
 import React, { useState, useRef, useCallback } from 'react';
 import type { Agent } from '../hooks/useAgents';
 import { useDismissablePopover } from '../hooks/useDismissablePopover';
-import { getAgentSwitchSettings, saveAgentSwitchSettings, type AgentSwitchSettings } from '../utils/agentSwitch';
+import { agentSwitchTargetLabel, getAgentSwitchDefaults, saveAgentSwitchSettings, type AgentSwitchSettings } from '../utils/agentSwitch';
+import { useConfigValue } from '../config/useConfig';
 
 interface ApproveDropdownProps {
   onApprove: () => void;
@@ -11,12 +12,7 @@ interface ApproveDropdownProps {
 }
 
 function getSelectedLabel(setting: AgentSwitchSettings, agents: Agent[]): string | null {
-  if (setting.switchTo === 'disabled') return null;
-  if (setting.switchTo === 'custom' && setting.customName) {
-    return setting.customName;
-  }
-  const match = agents.find(a => a.id.toLowerCase() === setting.switchTo.toLowerCase());
-  return match?.name ?? setting.switchTo;
+  return agentSwitchTargetLabel(setting, agents);
 }
 
 function isSelected(agentId: string, setting: AgentSwitchSettings): boolean {
@@ -37,7 +33,10 @@ export const ApproveDropdown: React.FC<ApproveDropdownProps> = ({
   disabled = false,
   isLoading = false,
 }) => {
-  const [setting, setSetting] = useState<AgentSwitchSettings>(() => getAgentSwitchSettings('plan'));
+  // Read reactively: config.json's value lands through configStore.init()
+  // once /api/plan answers, which may be after this mounts (#1390).
+  const stored = useConfigValue('agentSwitch');
+  const setting: AgentSwitchSettings = stored ?? getAgentSwitchDefaults('plan');
   const [isOpen, setIsOpen] = useState(false);
   const dropdownRef = useRef<HTMLDivElement>(null);
 
@@ -52,7 +51,6 @@ export const ApproveDropdown: React.FC<ApproveDropdownProps> = ({
   });
 
   const handleSelect = (newSetting: AgentSwitchSettings) => {
-    setSetting(newSetting);
     saveAgentSwitchSettings(newSetting);
     setIsOpen(false);
   };

package/components/AskSessionAnnouncementDialog.tsx

@@ -151,7 +151,7 @@ function DemoPlayer({ reducedMotion }: { readonly reducedMotion: boolean }) {
           data-ask-session-playback={playing ? 'pause' : 'play'}
           className={
             playing
-              ? 'absolute bottom-3 left-3 grid size-9 place-items-center rounded-full border border-border/60 bg-background/70 text-foreground opacity-0 outline-none backdrop-blur-sm transition-opacity motion-reduce:transition-none group-hover:opacity-100 focus-visible:opacity-100 focus-visible:ring-2 focus-visible:ring-primary'
+              ? 'absolute bottom-3 left-3 grid size-9 place-items-center rounded-full border border-border/60 bg-background/70 text-foreground opacity-0 outline-none backdrop-blur-sm transition-opacity motion-reduce:transition-none group-hover:opacity-100 focus-visible:opacity-100 [@media(hover:none)]:opacity-100 focus-visible:ring-2 focus-visible:ring-primary'
               : 'absolute left-1/2 top-1/2 grid size-16 -translate-x-1/2 -translate-y-1/2 place-items-center rounded-full border border-border/60 bg-background/80 text-foreground shadow-lg outline-none backdrop-blur-sm transition-transform motion-reduce:transition-none hover:scale-105 focus-visible:ring-2 focus-visible:ring-primary'
           }
         >

package/components/AttachmentsButton.tsx

@@ -248,7 +248,7 @@ export const AttachmentsButton: React.FC<AttachmentsButtonProps> = ({
             {/* Clear all button on hover */}
             <button
               onClick={handleClearAll}
-              className="absolute -top-1 -right-1 w-3.5 h-3.5 bg-destructive text-destructive-foreground rounded-full opacity-0 group-hover:opacity-100 transition-opacity flex items-center justify-center"
+              className="absolute -top-1 -right-1 w-3.5 h-3.5 bg-destructive text-destructive-foreground rounded-full opacity-0 group-hover:opacity-100 group-focus-within:opacity-100 [@media(hover:none)]:opacity-100 transition-opacity flex items-center justify-center"
             >
               <svg className="w-2 h-2" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={3}>
                 <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />

package/components/BlockRenderer.tsx

@@ -18,9 +18,10 @@ import {
 } from "@plannotator/core/question-block";
 
 /** A question block rendered outside a Viewer's document index (plan diff,
- *  other markdown surfaces): parsed alone, unnumbered. */
-const standaloneQuestion = (block: Block): IndexedQuestion | undefined => {
-  const [indexed] = indexQuestionBlocks([block]);
+ *  other markdown surfaces): parsed alone, unnumbered. Its contract lines
+ *  show as context unless the host asks for them (`questionContractLines`). */
+const standaloneQuestion = (block: Block, contractLines: boolean): IndexedQuestion | undefined => {
+  const [indexed] = indexQuestionBlocks([block], { contractLines });
   return indexed ? { ...indexed, number: 0 } : undefined;
 };
 
@@ -66,7 +67,14 @@ export const BlockRenderer: React.FC<{
   questionStatusLabel?: QuestionBlockProps['statusLabel'];
   /** Host content under a question's prompt (see `QuestionBlock`). */
   renderQuestionBelowPrompt?: QuestionBlockProps['renderBelowPrompt'];
-}> = ({ block, onOpenLinkedDoc, onOpenCodeFile, imageBaseDir, onImageClick, onToggleCheckbox, checkboxOverrides, orderedIndex, githubRepo, repoHost, headingAnchorId, onNavigateAnchor, question, questionTotal, questionAnswer, onAnswerQuestion, onSaveQuestionAnswer, saveQuestionAnswerLabel, renderQuestionFooter, questionDecisionRecording, questionDecisionScope, onToggleQuestionDecisionRecording, onOpenQuestionDecision, questionStatusTag, questionStatusLabel, renderQuestionBelowPrompt }) => {
+  /** Read a standalone question's contract lines into the card (default
+   *  false: context). A `question` the host passes was parsed by the host. */
+  questionContractLines?: boolean;
+  /** Picture choices as tiles (see `QuestionBlock` `pictureChoices`). */
+  questionPictureChoices?: QuestionBlockProps['pictureChoices'];
+  /** A label over each picture tile (see `QuestionBlock` `pictureBadge`). */
+  questionPictureBadge?: QuestionBlockProps['pictureBadge'];
+}> = ({ block, onOpenLinkedDoc, onOpenCodeFile, imageBaseDir, onImageClick, onToggleCheckbox, checkboxOverrides, orderedIndex, githubRepo, repoHost, headingAnchorId, onNavigateAnchor, question, questionTotal, questionAnswer, onAnswerQuestion, onSaveQuestionAnswer, saveQuestionAnswerLabel, renderQuestionFooter, questionDecisionRecording, questionDecisionScope, onToggleQuestionDecisionRecording, onOpenQuestionDecision, questionStatusTag, questionStatusLabel, renderQuestionBelowPrompt, questionContractLines = false, questionPictureChoices, questionPictureBadge }) => {
   switch (block.type) {
     case 'heading': {
       const Tag = `h${block.level || 1}` as React.ElementType;
@@ -133,6 +141,10 @@ export const BlockRenderer: React.FC<{
         <div
           className="flex items-start gap-3 my-1.5"
           data-block-id={block.id}
+          data-rich-list-level={block.level || 0}
+          data-rich-list-kind={block.ordered ? 'ol' : 'ul'}
+          data-rich-list-index={orderedIndex ?? undefined}
+          data-rich-list-checked={isCheckbox ? String(isChecked) : undefined}
           style={{ marginLeft: `${indent}rem` }}
         >
           <ListItemBody
@@ -180,7 +192,7 @@ export const BlockRenderer: React.FC<{
       const kind = block.directiveKind || 'note';
       if (isQuestionDirectiveKind(kind)) {
         // An unparseable question (no prompt) falls through to the callout.
-        const indexed = question ?? standaloneQuestion(block);
+        const indexed = question ?? standaloneQuestion(block, questionContractLines);
         if (indexed) {
           return (
             <QuestionBlock
@@ -199,6 +211,8 @@ export const BlockRenderer: React.FC<{
               statusTag={questionStatusTag}
               statusLabel={questionStatusLabel}
               renderBelowPrompt={renderQuestionBelowPrompt}
+              pictureChoices={questionPictureChoices}
+              pictureBadge={questionPictureBadge}
               onOpenLinkedDoc={onOpenLinkedDoc}
               onOpenCodeFile={onOpenCodeFile}
               imageBaseDir={imageBaseDir}

package/components/CodeFilePopout.tsx

@@ -2,11 +2,14 @@ import React, { useState, useEffect, useMemo, useRef, useCallback } from 'react'
 import { File, type LineAnnotation } from '@pierre/diffs/react';
 import type { SelectedLineRange as PierreSelectedLineRange, LineEventBaseProps } from '@pierre/diffs';
 import { PopoutDialog } from './PopoutDialog';
+import { isCommentSubmitKey } from '../utils/commentSubmitKey';
+import { useConfigValue } from '../config/useConfig';
 import { useTheme } from './ThemeProvider';
 import { CommentPopover } from './CommentPopover';
 import { ImageThumbnail } from './ImageThumbnail';
 import type { CodeAnnotation, ImageAttachment } from '../types';
 import { copyTextToClipboard } from '../utils/clipboard';
+import { whenCodeLineRendered } from '../utils/codeLineScroll';
 
 export interface CodeFileAnnotationInput {
   filePath: string;
@@ -22,6 +25,10 @@ interface CodeFilePopoutProps {
   onClose: () => void;
   filepath: string;
   contents: string;
+  line?: number;
+  lineEnd?: number;
+  /** Changes on every open, so reopening the same file:line scrolls to it again. */
+  revealKey?: number;
   prerenderedHTML?: string;
   error?: string;
   requestedPath?: string;
@@ -145,6 +152,7 @@ const CodeInlineAnnotation: React.FC<{
   const [isEditing, setIsEditing] = useState(false);
   const [editText, setEditText] = useState(annotation.text ?? '');
   const textareaRef = useRef<HTMLTextAreaElement>(null);
+  const enterSavesComment = useConfigValue('enterSavesComment');
 
   useEffect(() => {
     if (!isEditing) setEditText(annotation.text ?? '');
@@ -181,7 +189,17 @@ const CodeInlineAnnotation: React.FC<{
           {lineLabel(annotation.lineStart, annotation.lineEnd)}
         </span>
         {annotation.author && <span className="truncate normal-case">by <bdi>{annotation.author}</bdi></span>}
-        <div className="ml-auto flex items-center gap-1 opacity-0 group-hover:opacity-100 [@media(hover:none)]:opacity-100">
+        {annotation.outsideDiff && (
+          <span
+            className="rounded px-1.5 py-0.5 normal-case font-medium"
+            style={{ background: 'color-mix(in oklab, var(--warning) 18%, transparent)', color: 'var(--warning)' }}
+            data-code-annotation-outside-diff=""
+            title="A comment on lines outside the diff"
+          >
+            not in the diff
+          </span>
+        )}
+        <div className="ml-auto flex items-center gap-1 opacity-0 group-hover:opacity-100 group-focus-within:opacity-100 [@media(hover:none)]:opacity-100">
           {onEdit && !isEditing && (
             <button
               type="button"
@@ -227,7 +245,7 @@ const CodeInlineAnnotation: React.FC<{
                 e.preventDefault();
                 setIsEditing(false);
                 setEditText(annotation.text ?? '');
-              } else if (e.key === 'Enter' && (e.metaKey || e.ctrlKey) && !e.nativeEvent.isComposing) {
+              } else if (isCommentSubmitKey(e, enterSavesComment)) {
                 e.preventDefault();
                 save();
               }
@@ -286,6 +304,10 @@ const CodeInlineAnnotation: React.FC<{
 export interface CodeFileViewProps {
   filepath: string;
   contents: string;
+  line?: number;
+  lineEnd?: number;
+  /** Changes on every open, so reopening the same file:line scrolls to it again. */
+  revealKey?: number;
   prerenderedHTML?: string;
   annotations?: CodeAnnotation[];
   selectedAnnotationId?: string | null;
@@ -301,6 +323,26 @@ export interface CodeFileViewProps {
   lang?: string;
   /** Long lines: `'scroll'` sideways (the default) or `'wrap'` onto the next row, for a minified file. */
   overflow?: 'scroll' | 'wrap';
+  /** CSS added inside the file's shadow root after the theme (a host's line
+   *  marks, e.g. code review's change bars on `[data-column-number="12"]`). */
+  extraCss?: string;
+  /** Scroll this line to the middle and mark it, once per `token` (a jump to
+   *  a definition, a reference or a line). */
+  revealLine?: { line: number; token: number };
+  /** The token under the pointer (`enter` / `leave`) and the last one clicked
+   *  (`click`): a host's "go to definition" looks there. Turning it on wraps
+   *  the file's tokens (Pierre's token transformer). */
+  onTokenTarget?: (kind: 'enter' | 'leave' | 'click', target: CodeFileTokenTarget) => void;
+  /** Cmd/Ctrl-click (or Alt-click) on a token: a host's references. */
+  onTokenNavigate?: (target: CodeFileTokenTarget) => void;
+}
+
+/** A token of a file drawn by `CodeFileView` (Pierre's token event, file mode). */
+export interface CodeFileTokenTarget {
+  tokenText: string;
+  tokenElement: HTMLElement;
+  lineNumber: number;
+  lineCharStart: number;
 }
 
 /**
@@ -312,6 +354,9 @@ export interface CodeFileViewProps {
 export const CodeFileView: React.FC<CodeFileViewProps> = ({
   filepath,
   contents,
+  line,
+  lineEnd,
+  revealKey,
   prerenderedHTML,
   annotations = [],
   selectedAnnotationId,
@@ -323,6 +368,10 @@ export const CodeFileView: React.FC<CodeFileViewProps> = ({
   className = 'flex-1 min-h-0',
   lang,
   overflow = 'scroll',
+  extraCss,
+  revealLine,
+  onTokenTarget,
+  onTokenNavigate,
 }) => {
   const { resolvedMode } = useTheme();
   const mode = resolvedMode ?? 'dark';
@@ -367,6 +416,9 @@ export const CodeFileView: React.FC<CodeFileViewProps> = ({
       }));
   }, [annotations]);
 
+  // The line a host jumped to stays marked until a comment or a selection
+  // takes the mark (or the next jump moves it).
+  const [revealedLine, setRevealedLine] = useState<number | null>(null);
   const selectedLines = useMemo((): PierreSelectedLineRange | null => {
     if (pendingComment) {
       return { start: pendingComment.range.start, end: pendingComment.range.end };
@@ -374,8 +426,49 @@ export const CodeFileView: React.FC<CodeFileViewProps> = ({
     if (selectedCodeAnnotation) {
       return { start: selectedCodeAnnotation.lineStart, end: selectedCodeAnnotation.lineEnd };
     }
+    // A jump (Go to Definition, a reference) marks its line until a comment
+    // or a selection takes the mark; otherwise the host's line, if any.
+    if (revealedLine != null) return { start: revealedLine, end: revealedLine };
+    if (line != null) {
+      return { start: line, end: lineEnd ?? line };
+    }
     return null;
-  }, [pendingComment, selectedCodeAnnotation]);
+  }, [pendingComment, selectedCodeAnnotation, revealedLine, line, lineEnd]);
+
+  useEffect(() => {
+    if (!revealLine) return;
+    setRevealedLine(revealLine.line);
+    // Pierre renders after mount (and again after highlighting): look for the
+    // line for a moment.
+    let frame = 0;
+    let attempts = 0;
+    const find = () => {
+      const root = fileAreaRef.current?.querySelector('diffs-container')?.shadowRoot;
+      const row = root?.querySelector(`[data-line="${revealLine.line}"]`);
+      if (row) {
+        // Vertically only: scrollIntoView would also scroll a long line sideways.
+        let node: Element | null = fileAreaRef.current;
+        while (node) {
+          if (node instanceof HTMLElement && node.scrollHeight > node.clientHeight && /(auto|scroll)/.test(getComputedStyle(node).overflowY)) {
+            const box = node.getBoundingClientRect();
+            const rect = row.getBoundingClientRect();
+            node.scrollTop += rect.top - (box.top + box.height / 2) + rect.height / 2;
+            return;
+          }
+          node = node.parentElement;
+        }
+        row.scrollIntoView({ block: 'center', inline: 'nearest' });
+        return;
+      }
+      attempts += 1;
+      if (attempts < 120) frame = requestAnimationFrame(find);
+    };
+    frame = requestAnimationFrame(find);
+    return () => cancelAnimationFrame(frame);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [revealLine?.token, revealLine?.line]);
+  // Another file drops the mark (cleanups run before the next jump sets one).
+  useEffect(() => () => setRevealedLine(null), [filepath]);
   const effectivePrerenderedHTML = lineAnnotations.length === 0 ? prerenderedHTML : undefined;
 
   useEffect(() => {
@@ -388,6 +481,19 @@ export const CodeFileView: React.FC<CodeFileViewProps> = ({
     return () => clearTimeout(timer);
   }, [selectedAnnotationId, filepath]);
 
+  // Bring the referenced line into view once Pierre has drawn it. Runs again
+  // only when the file or the line changes; a selected comment scrolls itself.
+  const selectedAnnotationIdRef = useRef(selectedAnnotationId);
+  selectedAnnotationIdRef.current = selectedAnnotationId;
+  const lineCount = useMemo(() => contents.split('\n').length, [contents]);
+  useEffect(() => {
+    const area = fileAreaRef.current;
+    if (line == null || !area || selectedAnnotationIdRef.current) return;
+    return whenCodeLineRendered(area, line, (lineEl) => {
+      lineEl.scrollIntoView({ behavior: 'smooth', block: 'center' });
+    }, { lineCount });
+  }, [line, filepath, lineCount, revealKey]);
+
   const openCommentForRange = useCallback((
     range: { start: number; end: number },
     anchorEl?: HTMLElement,
@@ -470,6 +576,28 @@ export const CodeFileView: React.FC<CodeFileViewProps> = ({
     openCommentForRange({ start: range.start, end: range.end }, undefined, lastPointerRectRef.current ?? undefined);
   }, [onAddAnnotation, openCommentForRange]);
 
+  const tokenTargetOf = (props: { tokenText: string; tokenElement: HTMLElement; lineNumber: number; lineCharStart: number }): CodeFileTokenTarget => ({
+    tokenText: props.tokenText,
+    tokenElement: props.tokenElement,
+    lineNumber: props.lineNumber,
+    lineCharStart: props.lineCharStart,
+  });
+  const tokenOptions = onTokenTarget || onTokenNavigate
+    ? {
+        useTokenTransformer: true,
+        onTokenEnter: (props: CodeFileTokenTarget) => onTokenTarget?.('enter', tokenTargetOf(props)),
+        onTokenLeave: (props: CodeFileTokenTarget) => onTokenTarget?.('leave', tokenTargetOf(props)),
+        onTokenClick: (props: CodeFileTokenTarget, event: MouseEvent) => {
+          const target = tokenTargetOf(props);
+          onTokenTarget?.('click', target);
+          if (onTokenNavigate && (event.metaKey || event.ctrlKey || event.altKey)) {
+            suppressLineClickUntilRef.current = Date.now() + 300;
+            onTokenNavigate(target);
+          }
+        },
+      }
+    : {};
+
   const handleLineClick = useCallback((props: LineEventBaseProps & { event: PointerEvent }) => {
     if (!onAddAnnotation) return;
     if (Date.now() < suppressLineClickUntilRef.current) return;
@@ -509,7 +637,7 @@ export const CodeFileView: React.FC<CodeFileViewProps> = ({
           } as React.CSSProperties}
           options={{
             themeType: pierreTheme.type,
-            unsafeCSS: pierreTheme.css,
+            unsafeCSS: extraCss ? `${pierreTheme.css}\n${extraCss}` : pierreTheme.css,
             overflow,
             disableFileHeader: true,
             enableLineSelection: true,
@@ -517,6 +645,7 @@ export const CodeFileView: React.FC<CodeFileViewProps> = ({
             lineHoverHighlight: onAddAnnotation ? 'line' : 'disabled',
             onLineClick: handleLineClick,
             onLineSelectionEnd: handleLineSelectionEnd,
+            ...tokenOptions,
           }}
         />
       </div>
@@ -551,6 +680,9 @@ export const CodeFilePopout: React.FC<CodeFilePopoutProps> = ({
   onClose,
   filepath,
   contents,
+  line,
+  lineEnd,
+  revealKey,
   prerenderedHTML,
   error,
   requestedPath,
@@ -653,6 +785,9 @@ export const CodeFilePopout: React.FC<CodeFilePopoutProps> = ({
       <CodeFileView
         filepath={filepath}
         contents={contents}
+        line={line}
+        lineEnd={lineEnd}
+        revealKey={revealKey}
         prerenderedHTML={prerenderedHTML}
         annotations={annotations}
         selectedAnnotationId={selectedAnnotationId}

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,