@plannotator/ui 0.28.0 → 0.29.1

package/components/CommentPopover.tsx

@@ -6,6 +6,9 @@ import { submitHint } from '../utils/platform';
 import { useDraggable } from '../hooks/useDraggable';
 import { SparklesIcon } from './SparklesIcon';
 import { hasUnsavedCommentContent } from '../utils/commentContent';
+import { useSkillReferenceAutocomplete } from '../hooks/useSkillReferenceAutocomplete';
+import { HumanOnlySkillNotice, SkillReferenceMenu } from './SkillReferenceMenu';
+import type { SkillReferenceToken } from '../utils/skillReferences';
 
 export interface CommentAskAIContext {
   kind: 'general' | 'selection';
@@ -19,6 +22,18 @@ export type CommentAskAIHandler = (
   context: CommentAskAIContext,
 ) => boolean | void | Promise<boolean | void>;
 
+/** One selected target of a multi-target draft comment (HTML pinpoint multi-select). */
+export interface CommentTargetChip {
+  key: string;
+  /** Semantic label (hover-label cascade), e.g. "Button" / "rowchip". */
+  label?: string;
+  /** Short text excerpt of the target element. */
+  excerpt: string;
+}
+
+/** Composer-yield stage while the user is shift-selecting (see composerYield.ts). */
+export type CommentPopoverYieldState = 'none' | 'near' | 'over';
+
 interface CommentPopoverProps {
   /** Element to anchor the popover near (re-reads position on scroll) */
   anchorEl?: HTMLElement;
@@ -46,6 +61,24 @@ interface CommentPopoverProps {
   onAskAI?: CommentAskAIHandler;
   askAIContext?: CommentAskAIContext;
   askAIDisabled?: boolean;
+  /** Opt-in: `/` and `$` skill-reference autocomplete (document UI surfaces). Off by default. */
+  skillReferences?: boolean;
+  /** Opt-in (HTML multi-select): selected targets rendered as horizontally
+   *  scrollable chips above the textarea. Absent → byte-identical composer. */
+  targetChips?: CommentTargetChip[];
+  /** Remove a chip's target while composing. */
+  onRemoveTargetChip?: (key: string) => void;
+  /** Chip hover — host flashes the corresponding element in the page. */
+  onHoverTargetChip?: (key: string) => void;
+  /** Opt-in: bump to return focus to the textarea (after a shift-click add/remove). */
+  refocusToken?: number;
+  /** Opt-in: while open, a window-level printable keydown that would otherwise
+   *  go nowhere (focus on <body>) routes into the textarea, so the first
+   *  keystroke after a shift-click is never lost. */
+  captureStrayKeys?: boolean;
+  /** Opt-in composer yield while shift-selecting: 'near' fades the composer,
+   *  'over' makes it near-invisible and click-through. Undefined → no-op. */
+  yieldState?: CommentPopoverYieldState;
 }
 
 const MAX_POPOVER_WIDTH = 384;
@@ -96,6 +129,13 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
   onAskAI,
   askAIContext,
   askAIDisabled = false,
+  skillReferences = false,
+  targetChips,
+  onRemoveTargetChip,
+  onHoverTargetChip,
+  refocusToken,
+  captureStrayKeys = false,
+  yieldState,
 }) => {
   const [mode, setMode] = useState<'popover' | 'dialog'>('popover');
   const initialDraft = draftKey ? draftStore.get(draftKey) : undefined;
@@ -167,17 +207,20 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
     anchorEl?.scrollIntoView({ block: 'center', behavior: 'smooth' });
   }, [anchorEl]);
 
-  // Focus textarea on mount and mode changes
-  useEffect(() => {
-    const id = setTimeout(() => {
-      const el = textareaRef.current;
-      if (el) {
-        el.focus();
-        el.selectionStart = el.selectionEnd = el.value.length;
-      }
+  // Focus the textarea when it mounts (initial open and popover/dialog switches).
+  // A ref callback rather than a mount effect: in popover mode the textarea only
+  // 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 focusOnMountRef = useCallback((el: HTMLTextAreaElement | null) => {
+    textareaRef.current = el;
+    if (!el) return;
+    setTimeout(() => {
+      if (!el.isConnected) return;
+      el.focus();
+      el.selectionStart = el.selectionEnd = el.value.length;
     }, 0);
-    return () => clearTimeout(id);
-  }, [mode]);
+  }, []);
 
   // Click-outside for popover mode
   useEffect(() => {
@@ -198,6 +241,107 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
     return () => document.removeEventListener('pointerdown', handlePointerDown, true);
   }, [mode, onClose]);
 
+  // Focus choreography (multi-select): after a shift-click adds/removes a
+  // target, focus returns to the textarea so typing continues uninterrupted.
+  // Focus only — the caret stays wherever the user left it mid-edit.
+  const refocusSeenRef = useRef(refocusToken);
+  useEffect(() => {
+    if (refocusToken === undefined || refocusToken === refocusSeenRef.current) return;
+    refocusSeenRef.current = refocusToken;
+    textareaRef.current?.focus();
+  }, [refocusToken]);
+
+  // First-keystroke guard: while the draft is open, a printable keydown that
+  // lands nowhere (focus fell back to <body> after an iframe interaction)
+  // routes into the textarea instead of vanishing. Runs in capture phase so
+  // it claims the key before the app's shortcut dispatcher; the character
+  // lands at the textarea's remembered caret. Note that preventDefault here
+  // does not stop the dispatcher (it deliberately ignores defaultPrevented,
+  // see shortcuts/runtime.ts) — this guard is only safe because the
+  // plan-review scopes bind no bare printable single key. Any future single-
+  // key binding on this surface must be reconciled with this handler.
+  useEffect(() => {
+    if (!captureStrayKeys) return;
+    const handler = (e: KeyboardEvent) => {
+      if (e.metaKey || e.ctrlKey || e.altKey) return;
+      if (!e.key || e.key.length !== 1) return;
+      const target = e.target;
+      const strayed =
+        target === null
+        || target === document.body
+        || target === document.documentElement;
+      if (!strayed) return;
+      const el = textareaRef.current;
+      if (!el || document.activeElement === el) return;
+      e.preventDefault();
+      const key = e.key;
+      const start = el.selectionStart ?? el.value.length;
+      const end = el.selectionEnd ?? start;
+      setText((prev) => prev.slice(0, start) + key + prev.slice(end));
+      el.focus();
+      requestAnimationFrame(() => {
+        el.selectionStart = el.selectionEnd = start + 1;
+      });
+    };
+    window.addEventListener('keydown', handler, true);
+    return () => window.removeEventListener('keydown', handler, true);
+  }, [captureStrayKeys]);
+
+  // Composer yield (multi-select): fade near the pointer, click-through over
+  // it. Class-driven so prefers-reduced-motion can kill the transition.
+  const yieldClass = yieldState === undefined
+    ? ''
+    : ` pn-composer-yieldable${yieldState === 'over' ? ' pn-composer-yield-over' : yieldState === 'near' ? ' pn-composer-yield-near' : ''}`;
+  const yieldStyleBlock = yieldState === undefined ? null : (
+    <style>{`
+      .pn-composer-yieldable { transition: opacity 180ms ease; }
+      @media (prefers-reduced-motion: reduce) {
+        .pn-composer-yieldable { transition: none; }
+      }
+      .pn-composer-yield-near { opacity: 0.4; }
+      .pn-composer-yield-over { opacity: 0.05; pointer-events: none; }
+    `}</style>
+  );
+
+  // Selected-target chips (multi-select): horizontally scrollable, primary
+  // first; each removable while composing.
+  const chipsRow = targetChips && targetChips.length > 0 ? (
+    <div
+      data-target-chips="true"
+      className="flex items-center gap-1.5 px-3 pt-2 overflow-x-auto whitespace-nowrap"
+    >
+      {targetChips.map((chip, i) => (
+        <span
+          key={chip.key}
+          data-target-chip={chip.key}
+          data-target-chip-primary={i === 0 ? 'true' : undefined}
+          onMouseEnter={() => onHoverTargetChip?.(chip.key)}
+          className={`inline-flex items-center gap-1 shrink-0 max-w-[180px] rounded-full border px-2 py-0.5 text-[10px] ${
+            i === 0
+              ? 'border-primary/50 bg-primary/10 text-foreground'
+              : 'border-border bg-muted/50 text-muted-foreground'
+          }`}
+        >
+          <span className="font-semibold text-primary">{chip.label || 'Element'}</span>
+          <span className="truncate">{chip.excerpt}</span>
+          {onRemoveTargetChip && (
+            <button
+              type="button"
+              data-target-chip-remove={chip.key}
+              onClick={() => onRemoveTargetChip(chip.key)}
+              title="Remove this target"
+              className="shrink-0 rounded-full p-0.5 hover:bg-muted text-muted-foreground hover:text-foreground transition-colors"
+            >
+              <svg className="w-2.5 h-2.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2.5}>
+                <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
+              </svg>
+            </button>
+          )}
+        </span>
+      ))}
+    </div>
+  ) : null;
+
   const handleSubmit = useCallback(() => {
     const canSubmitEmpty = allowEmptySubmit && initialText.trim().length > 0;
     if (hasUnsavedContent || canSubmitEmpty) {
@@ -232,7 +376,15 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
     onClose();
   }, [allowImages, askAIContext, contextText, draftKey, isGlobal, onAskAI, onClose, onDraftChange, text]);
 
+  const skillAc = useSkillReferenceAutocomplete({
+    text,
+    setText,
+    textareaRef,
+    enabled: skillReferences,
+  });
+
   const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    if (skillAc.onKeyDown(e)) return;
     if (e.key === 'Escape') {
       e.stopPropagation();
       if (mode === 'dialog') {
@@ -266,6 +418,10 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
         <div className="absolute inset-0 bg-background/80 backdrop-blur-sm" />
 
         {/* Dialog card */}
+        {/* The expanded dialog deliberately does not yield: it is an explicit
+            full-screen compose surface, and its backdrop wrapper (which carries
+            data-comment-popover) spans the viewport, so proximity is
+            meaningless there. */}
         <div
           ref={popoverRef}
           className="relative w-full max-w-xl bg-popover border border-border rounded-xl shadow-2xl flex flex-col"
@@ -304,32 +460,42 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
             </div>
           </div>
 
+          {chipsRow}
+
           {/* Textarea */}
-          <div className="px-4 py-3 flex-1">
-            <textarea
-              ref={textareaRef}
+          <div className="relative px-4 py-3 flex-1">
+            {skillAc.menu && (
+              <SkillReferenceMenu
+                items={skillAc.menu.items}
+                activeIndex={skillAc.menu.activeIndex}
+                onSelect={skillAc.select}
+              />
+            )}
+            <ComposerTextarea
+              textareaRef={focusOnMountRef}
               value={text}
-              onChange={(e) => setText(e.target.value)}
+              onChange={(e) => { setText(e.target.value); skillAc.onSelect(); }}
               onKeyDown={handleKeyDown}
+              onSelectCaret={skillAc.onSelect}
               placeholder={isGlobal ? 'Add a global comment...' : 'Add a comment...'}
-              className="w-full bg-transparent text-sm placeholder:text-muted-foreground resize-none focus:outline-none min-h-48 max-h-96 px-1 py-0.5"
-              style={{ fieldSizing: 'content' } as React.CSSProperties}
+              sizeClassName="min-h-48 max-h-96"
+              skillReferences={skillReferences}
+              tokens={skillAc.referenceTokens}
             />
+            <HumanOnlySkillNotice skills={skillAc.humanOnlyReferences} />
           </div>
 
-          {/* Footer */}
-          <div className="flex items-center justify-between px-4 py-3 border-t border-border/50">
-            <div className="flex items-center gap-2">
-              {allowImages && (
-                <AttachmentsButton
-                  images={images}
-                  onAdd={(img) => setImages((prev) => [...prev, img])}
-                  onRemove={(path) => setImages((prev) => prev.filter((i) => i.path !== path))}
-                  variant="inline"
-                />
-              )}
-            </div>
-            <div className="flex items-center gap-3">
+          {/* Footer — DOM order sets tab order (Save first); row-reverse keeps the visual layout unchanged */}
+          <div className="flex flex-row-reverse items-center justify-between px-4 py-3 border-t border-border/50">
+            <div className="flex flex-row-reverse items-center gap-3">
+              <button
+                onClick={handleSubmit}
+                disabled={!canSubmit}
+                className="px-3 py-1.5 text-xs font-medium rounded-md bg-primary text-primary-foreground hover:opacity-90 disabled:opacity-50 disabled:cursor-not-allowed transition-opacity"
+              >
+                {isGlobal ? 'Add' : 'Save'}
+              </button>
+              <span className="text-[10px] text-muted-foreground">{submitHint}</span>
               {onAskAI && (
                 <button
                   onClick={handleAskAI}
@@ -341,14 +507,16 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
                   Ask AI
                 </button>
               )}
-              <span className="text-[10px] text-muted-foreground">{submitHint}</span>
-              <button
-                onClick={handleSubmit}
-                disabled={!canSubmit}
-                className="px-3 py-1.5 text-xs font-medium rounded-md bg-primary text-primary-foreground hover:opacity-90 disabled:opacity-50 disabled:cursor-not-allowed transition-opacity"
-              >
-                {isGlobal ? 'Add' : 'Save'}
-              </button>
+            </div>
+            <div className="flex items-center gap-2">
+              {allowImages && (
+                <AttachmentsButton
+                  images={images}
+                  onAdd={(img) => setImages((prev) => [...prev, img])}
+                  onRemove={(path) => setImages((prev) => prev.filter((i) => i.path !== path))}
+                  variant="inline"
+                />
+              )}
             </div>
           </div>
         </div>
@@ -377,7 +545,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
       <div
         ref={popoverRef}
         data-comment-popover="true"
-      className="fixed z-[100] bg-popover border border-border rounded-xl shadow-2xl flex flex-col"
+      className={`fixed z-[100] bg-popover border border-border rounded-xl shadow-2xl flex flex-col${yieldClass}`}
       style={dragPosition
         ? { top: dragPosition.top, left: dragPosition.left, width: position.width }
         : {
@@ -402,6 +570,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
           to { opacity: 1; transform: translateY(-100%); }
         }
       `}</style>
+      {yieldStyleBlock}
 
       {/* Header (draggable) */}
       <div className="flex items-center justify-between px-3 py-2 border-b border-border/50" {...dragHandleProps}>
@@ -426,32 +595,42 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
         </div>
       </div>
 
+      {chipsRow}
+
       {/* Textarea */}
-      <div className="px-3 py-2">
-        <textarea
-          ref={textareaRef}
+      <div className="relative px-3 py-2">
+        {skillAc.menu && (
+          <SkillReferenceMenu
+            items={skillAc.menu.items}
+            activeIndex={skillAc.menu.activeIndex}
+            onSelect={skillAc.select}
+          />
+        )}
+        <ComposerTextarea
+          textareaRef={focusOnMountRef}
           value={text}
-          onChange={(e) => setText(e.target.value)}
+          onChange={(e) => { setText(e.target.value); skillAc.onSelect(); }}
           onKeyDown={handleKeyDown}
+          onSelectCaret={skillAc.onSelect}
           placeholder={isGlobal ? 'Add a global comment...' : 'Add a comment...'}
-          className="w-full bg-transparent text-sm placeholder:text-muted-foreground resize-none focus:outline-none max-h-64 min-h-[4.5rem] px-1 py-0.5"
-          style={{ fieldSizing: 'content' } as React.CSSProperties}
+          sizeClassName="max-h-64 min-h-[4.5rem]"
+          skillReferences={skillReferences}
+          tokens={skillAc.referenceTokens}
         />
+        <HumanOnlySkillNotice skills={skillAc.humanOnlyReferences} />
       </div>
 
-      {/* Footer */}
-      <div className="flex items-center justify-between px-3 py-2 border-t border-border/50">
-        <div className="flex items-center gap-2">
-          {allowImages && (
-            <AttachmentsButton
-              images={images}
-              onAdd={(img) => setImages((prev) => [...prev, img])}
-              onRemove={(path) => setImages((prev) => prev.filter((i) => i.path !== path))}
-              variant="inline"
-            />
-          )}
-        </div>
-        <div className="flex items-center gap-3">
+      {/* Footer — same DOM-order/row-reverse pattern as the dialog footer above */}
+      <div className="flex flex-row-reverse items-center justify-between px-3 py-2 border-t border-border/50">
+        <div className="flex flex-row-reverse items-center gap-3">
+          <button
+            onClick={handleSubmit}
+            disabled={!canSubmit}
+            className="px-3 py-1.5 text-xs font-medium rounded-md bg-primary text-primary-foreground hover:opacity-90 disabled:opacity-50 disabled:cursor-not-allowed transition-opacity"
+          >
+            {isGlobal ? 'Add' : 'Save'}
+          </button>
+          <span className="text-[10px] text-muted-foreground">{submitHint}</span>
           {onAskAI && (
             <button
               onClick={handleAskAI}
@@ -463,14 +642,16 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
               Ask AI
             </button>
           )}
-          <span className="text-[10px] text-muted-foreground">{submitHint}</span>
-          <button
-            onClick={handleSubmit}
-            disabled={!canSubmit}
-            className="px-3 py-1.5 text-xs font-medium rounded-md bg-primary text-primary-foreground hover:opacity-90 disabled:opacity-50 disabled:cursor-not-allowed transition-opacity"
-          >
-            {isGlobal ? 'Add' : 'Save'}
-          </button>
+        </div>
+        <div className="flex items-center gap-2">
+          {allowImages && (
+            <AttachmentsButton
+              images={images}
+              onAdd={(img) => setImages((prev) => [...prev, img])}
+              onRemove={(path) => setImages((prev) => prev.filter((i) => i.path !== path))}
+              variant="inline"
+            />
+          )}
         </div>
       </div>
       </div>
@@ -479,6 +660,151 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
   );
 };
 
+// ---------------------------------------------------------------------------
+// Composer textarea with skill-reference token highlighting
+// ---------------------------------------------------------------------------
+
+/** Classes shared by the textarea and its highlight mirror — font, size,
+ * and box metrics MUST stay identical or the overlay drifts out of alignment. */
+const COMPOSER_TEXT_CLASSES = 'w-full bg-transparent text-sm px-1 py-0.5';
+
+interface ComposerTextareaProps {
+  value: string;
+  onChange: (e: React.ChangeEvent<HTMLTextAreaElement>) => void;
+  onKeyDown: (e: React.KeyboardEvent<HTMLTextAreaElement>) => void;
+  /** Caret observer (skill autocomplete). */
+  onSelectCaret: () => void;
+  placeholder: string;
+  /** Mode-specific min/max height classes. */
+  sizeClassName: string;
+  textareaRef: (el: HTMLTextAreaElement | null) => void;
+  /** Positioned skill-reference occurrences to highlight. */
+  tokens: SkillReferenceToken[];
+  /** Off → render the plain pre-feature textarea, byte-for-byte. */
+  skillReferences: boolean;
+}
+
+/**
+ * The composer's textarea. With `skillReferences` off this is exactly the
+ * pre-feature `<textarea>`; with it on, inserted skill-reference tokens are
+ * highlighted via a mirrored, aria-hidden overlay rendered BEHIND a
+ * transparent-text textarea (a textarea cannot style substrings). The overlay
+ * shares the exact font/padding/wrapping metrics and mirrors scroll position,
+ * and token spans change ONLY color/background (never font or weight), so the
+ * glyphs the browser lays out in the textarea and the glyphs the overlay
+ * paints coincide. During IME composition the overlay hides and the textarea
+ * text becomes visible again (`.pn-ref-composing`), keeping native
+ * composition rendering (underlines, candidate highlights) intact.
+ */
+const ComposerTextarea: React.FC<ComposerTextareaProps> = ({
+  value,
+  onChange,
+  onKeyDown,
+  onSelectCaret,
+  placeholder,
+  sizeClassName,
+  textareaRef,
+  tokens,
+  skillReferences,
+}) => {
+  const overlayRef = useRef<HTMLDivElement>(null);
+  const [composing, setComposing] = useState(false);
+
+  const syncScroll = useCallback((el: HTMLTextAreaElement) => {
+    const overlay = overlayRef.current;
+    if (!overlay) return;
+    overlay.scrollTop = el.scrollTop;
+    overlay.scrollLeft = el.scrollLeft;
+  }, []);
+
+  const innerRef = useRef<HTMLTextAreaElement | null>(null);
+  const attachRef = useCallback(
+    (el: HTMLTextAreaElement | null) => {
+      innerRef.current = el;
+      textareaRef(el);
+    },
+    [textareaRef],
+  );
+
+  // Keep the mirror aligned when the value changes without a scroll event
+  // (e.g. programmatic insertion moving the caret into a scrolled region).
+  useEffect(() => {
+    if (innerRef.current) syncScroll(innerRef.current);
+  }, [value, syncScroll]);
+
+  if (!skillReferences) {
+    return (
+      <textarea
+        ref={attachRef}
+        value={value}
+        onChange={onChange}
+        onKeyDown={onKeyDown}
+        onSelect={onSelectCaret}
+        placeholder={placeholder}
+        className={`${COMPOSER_TEXT_CLASSES} placeholder:text-muted-foreground resize-none focus:outline-none ${sizeClassName}`}
+        style={{ fieldSizing: 'content' } as React.CSSProperties}
+      />
+    );
+  }
+
+  const segments: React.ReactNode[] = [];
+  let pos = 0;
+  tokens.forEach((token, i) => {
+    if (token.start < pos || token.end > value.length) return; // stale tokens for a different value
+    if (token.start > pos) segments.push(value.slice(pos, token.start));
+    // Human-only tokens carry a quiet dotted underline as their inline marker
+    // (text-decoration never affects glyph layout, so overlay alignment is
+    // safe). The accessible explanation lives in HumanOnlySkillNotice below
+    // the textarea — this overlay is aria-hidden.
+    segments.push(
+      <span
+        key={`${token.start}-${i}`}
+        data-skill-ref-token={token.entry.name}
+        data-skill-ref-human-only={token.entry.humanOnly ? 'true' : undefined}
+        className={`text-primary bg-primary/10 rounded-[3px] ${
+          token.entry.humanOnly
+            ? 'underline decoration-dotted decoration-primary/60 underline-offset-2'
+            : ''
+        }`}
+      >
+        {value.slice(token.start, token.end)}
+      </span>,
+    );
+    pos = token.end;
+  });
+  segments.push(value.slice(pos));
+
+  return (
+    <div className="relative">
+      <div
+        ref={overlayRef}
+        aria-hidden="true"
+        data-skill-ref-overlay="true"
+        className={`${COMPOSER_TEXT_CLASSES} ${sizeClassName} pointer-events-none absolute inset-0 overflow-hidden whitespace-pre-wrap break-words`}
+        style={composing ? { visibility: 'hidden' } : undefined}
+      >
+        {segments}
+        {'\n'}
+      </div>
+      <textarea
+        ref={attachRef}
+        value={value}
+        onChange={onChange}
+        onKeyDown={onKeyDown}
+        onSelect={onSelectCaret}
+        onScroll={(e) => syncScroll(e.currentTarget)}
+        onCompositionStart={() => setComposing(true)}
+        onCompositionEnd={() => setComposing(false)}
+        placeholder={placeholder}
+        className={`${COMPOSER_TEXT_CLASSES} placeholder:text-muted-foreground resize-none focus:outline-none relative pn-ref-input ${
+          composing ? 'pn-ref-composing' : ''
+        } ${sizeClassName}`}
+        style={{ fieldSizing: 'content' } as React.CSSProperties}
+      />
+    </div>
+  );
+};
+
 // Icons
 
 const ChevronUpIcon = () => (

package/components/DocBadges.tsx

@@ -5,9 +5,13 @@
  *   - layout="column": original location at the top-left of the plan card (absolute)
  *   - layout="row":   inside the sticky header lane when the user scrolls
  *
- * In row layout, the demo badge and linked-doc breadcrumb are dropped — the
- * sticky lane hides entirely in linked-doc mode, and the demo badge is purely
- * decorative top-of-doc context.
+ * In row layout, the demo badge and linked-doc breadcrumb are dropped —
+ * everything else is decorative top-of-doc context except the plan-diff
+ * badge, which is NOT suppressed by linkedDocInfo: `planDiffStats`/
+ * `hasPreviousVersion` already arrive pre-scoped to whichever document is
+ * currently active (root, or a folder/linked doc with its own diff
+ * baseline), so it renders in linked-doc mode exactly when that document
+ * actually has a previous version to diff against.
  */
 
 import React from 'react';
@@ -31,6 +35,11 @@ export interface DocBadgesProps {
   isPlanDiffActive?: boolean;
   hasPreviousVersion?: boolean;
   onPlanDiffToggle?: () => void;
+  /** Baseline suffix + tooltip for the plan-diff badge — annotate/folder
+   *  sessions pass "since last review" so the badge's numbers read against
+   *  the right baseline. See PlanDiffBadge. Plan review passes nothing. */
+  planDiffBaselineLabel?: string;
+  planDiffBaselineTooltip?: string;
   showDemoBadge?: boolean;
   archiveInfo?: { status: 'approved' | 'denied' | 'unknown'; timestamp: string; title: string } | null;
   linkedDocInfo?: LinkedDocBadgeInfo | null;
@@ -50,6 +59,8 @@ export const DocBadges: React.FC<DocBadgesProps> = ({
   isPlanDiffActive,
   hasPreviousVersion,
   onPlanDiffToggle,
+  planDiffBaselineLabel,
+  planDiffBaselineTooltip,
   showDemoBadge,
   archiveInfo,
   linkedDocInfo,
@@ -64,10 +75,12 @@ export const DocBadges: React.FC<DocBadgesProps> = ({
   ) : null;
 
   // In row layout, only PlanDiffBadge (when it has stats to show) and
-  // archiveInfo actually render — everything else is hidden. Check what
-  // will truly produce visible output to avoid an empty wrapper div.
+  // archiveInfo (outside linked-doc mode) actually render — everything else
+  // is hidden. Check what will truly produce visible output to avoid an
+  // empty wrapper div. PlanDiffBadge is not linkedDocInfo-gated — see the
+  // header comment.
   const anything = isRow
-    ? (!linkedDocInfo && ((hasPreviousVersion && planDiffStats) || archiveInfo))
+    ? (hasPreviousVersion && planDiffStats) || (archiveInfo && !linkedDocInfo)
     : repoInfo || hasPreviousVersion || showDemoBadge || linkedDocInfo || archiveInfo || sourceInfo || canOpenInApp;
   if (!anything) return null;
 
@@ -78,10 +91,6 @@ export const DocBadges: React.FC<DocBadgesProps> = ({
 
   return (
     <div className={outerClass}>
-      {/* Open-in-app normally renders inline (to the right) within the source /
-          linked-doc rows below. This standalone fallback only fires when there
-          is no file row to attach to. Hidden in the sticky row and for URLs. */}
-      {!isRow && canOpenInApp && !sourceInfo && !linkedDocInfo && openInButton}
       {/* Row layout (sticky lane) omits repo/branch to keep the bar compact —
           they'd otherwise push the container wide enough to visually extend
           under the action buttons. Plan-diff badge still renders below. */}
@@ -104,9 +113,16 @@ export const DocBadges: React.FC<DocBadgesProps> = ({
               <span className="truncate">{repoInfo.branch}</span>
             </span>
           )}
+          {/* Markdown/text annotate sessions have no separate source badge, so
+              keep the open-in control attached to the repository context. */}
+          {canOpenInApp && !sourceInfo && openInButton}
         </div>
       )}
 
+      {/* Non-repository files still need an open-in entry when there is no
+          source or linked-document row to attach it to. */}
+      {!isRow && canOpenInApp && !repoInfo && !sourceInfo && !linkedDocInfo && openInButton}
+
       {sourceInfo && !linkedDocInfo && !isRow && (
         <div className="flex items-center gap-1">
           <span
@@ -121,12 +137,14 @@ export const DocBadges: React.FC<DocBadgesProps> = ({
         </div>
       )}
 
-      {onPlanDiffToggle && !linkedDocInfo && (
+      {onPlanDiffToggle && (
         <PlanDiffBadge
           stats={planDiffStats ?? null}
           isActive={isPlanDiffActive ?? false}
           onToggle={onPlanDiffToggle}
           hasPreviousVersion={hasPreviousVersion ?? false}
+          baselineLabel={planDiffBaselineLabel}
+          baselineTooltip={planDiffBaselineTooltip}
         />
       )}