@plannotator/ui 0.50.0 → 0.52.0

package/components/html-viewer/useHtmlAnnotation.ts

@@ -477,8 +477,8 @@ export function useHtmlAnnotation({
   flashDraftTarget: (key: string) => void;
   /** Bumped after every target add/remove so the composer can refocus its textarea. */
   composerFocusToken: number;
-  /** Composer one-click "Looks good": submits the hardcoded positive label
-   *  with the same anchor and multi-select targets a typed comment would carry. */
+  /** Composer one-click 👍: submits the hardcoded positive label with the
+   *  same anchor and multi-select targets a typed comment would carry. */
   handleCommentLooksGood: () => void;
   /** Ids this module minted for locally created annotations (create-mark),
    *  for the unanchored union: a minted id the host never listed is a
@@ -910,8 +910,14 @@ export function useHtmlAnnotation({
     [getOrCreateAnchor],
   );
 
-  const handleCommentSubmit = useCallback(
-    (comment: string, images?: ImageAttachment[], mentions?: readonly string[]) => {
+  // One commit path for everything the pinpoint composer submits (a typed
+  // comment or the one-click 👍), so both carry the same anchor, element
+  // context and multi-select targets.
+  const commitComposerDraft = useCallback(
+    (
+      body: Pick<Annotation, "text"> &
+        Partial<Pick<Annotation, "images" | "mentions" | "isQuickLabel" | "quickLabelTip">>,
+    ) => {
       if (!enabledRef.current) return;
       // Prefer the text captured when the popover opened — it can't be clobbered by
       // a later selection change or clear while the user is composing the comment.
@@ -939,14 +945,10 @@ export function useHtmlAnnotation({
         startOffset: 0,
         endOffset: 0,
         type: AnnotationType.COMMENT,
-        text: comment,
         originalText: text,
         author: getIdentity(),
         createdA: Date.now(),
-        images,
-        // Host capability: present only when a mentionSource was supplied AND
-        // a token survived, so a comment without one is unchanged.
-        ...(mentions && mentions.length > 0 ? { mentions } : {}),
+        ...body,
         htmlAnchor: pendingAnchorRef.current ?? undefined,
         elementContext: pendingContextRef.current ?? undefined,
         htmlAdditionalTargets: additionalTargets,
@@ -961,53 +963,32 @@ export function useHtmlAnnotation({
     [post],
   );
 
-  // The composer's one-click "Looks good" (the restored thumbs-up for
-  // comment-only surfaces, where pinpoint clicks land straight in the
-  // composer and never see the selection toolbar). Mirrors
-  // handleCommentSubmit — same anchor, same multi-select targets — but
-  // emits the hardcoded positive label instead of typed prose.
-  const handleCommentLooksGood = useCallback(() => {
-    if (!enabledRef.current) return;
-    const text = commentPopoverRef.current?.selectedText || pendingTextRef.current;
-    if (!text) return;
-
-    const targets = draftTargetsRef.current;
-    const additionalTargets: HtmlAnnotationTarget[] | undefined =
-      targets.length > 1
-        ? targets.slice(1, 1 + maxTargetsRef.current).map((t) => ({
-            label: t.label,
-            text: t.text,
-            anchor: t.anchor ?? undefined,
-            ...(t.context ? { context: t.context } : {}),
-          }))
-        : undefined;
-
-    const id = nextHtmlAnnId();
-    mintedIdsRef.current.add(id);
-    post({ type: `${PREFIX}create-mark`, id, annotationType: "comment" });
-    onAddRef.current?.({
-      id,
-      blockId: "",
-      startOffset: 0,
-      endOffset: 0,
-      type: AnnotationType.COMMENT,
-      text: THUMBS_UP_LABEL.text,
-      originalText: text,
-      isQuickLabel: true,
-      quickLabelTip: THUMBS_UP_LABEL.tip,
-      author: getIdentity(),
-      createdA: Date.now(),
-      htmlAnchor: pendingAnchorRef.current ?? undefined,
-      elementContext: pendingContextRef.current ?? undefined,
-      htmlAdditionalTargets: additionalTargets,
-    });
+  const handleCommentSubmit = useCallback(
+    (comment: string, images?: ImageAttachment[], mentions?: readonly string[]) =>
+      commitComposerDraft({
+        text: comment,
+        images,
+        // Host capability: present only when a mentionSource was supplied AND
+        // a token survived, so a comment without one is unchanged.
+        ...(mentions && mentions.length > 0 ? { mentions } : {}),
+      }),
+    [commitComposerDraft],
+  );
 
-    setCommentPopover(null);
-    setDraftTargets([]);
-    pendingTextRef.current = "";
-    pendingAnchorRef.current = null;
-    pendingContextRef.current = null;
-  }, [post]);
+  // The composer's one-click 👍. A pinpoint click opens this composer
+  // directly and never shows the selection toolbar, so without it a reviewer
+  // could not mark an element "looks good" in one click. Emits the same
+  // hardcoded positive label as the toolbar's 👍 (the only label comment-only
+  // surfaces may create), on the pinned element(s).
+  const handleCommentLooksGood = useCallback(
+    () =>
+      commitComposerDraft({
+        text: THUMBS_UP_LABEL.text,
+        isQuickLabel: true,
+        quickLabelTip: THUMBS_UP_LABEL.tip,
+      }),
+    [commitComposerDraft],
+  );
 
   const handleCommentClose = useCallback(() => {
     post({ type: `${PREFIX}cancel-selection` });

package/components/settings/QuickLabelsTab.tsx

@@ -0,0 +1,378 @@
+import React, { useLayoutEffect, useRef, useState } from 'react';
+import { isMac, isWindows, altKey } from '../../utils/platform';
+import {
+  type QuickLabel,
+  DEFAULT_QUICK_LABELS,
+  LABEL_COLOR_MAP,
+  emojiFromFieldInput,
+  getLabelColors,
+  getQuickLabels,
+  moveQuickLabel,
+  quickLabelShortcutDigit,
+  resetQuickLabels,
+  saveQuickLabels,
+} from '../../utils/quickLabels';
+
+/** Most labels the tab lets a person keep (only the first ten get a key). */
+const MAX_QUICK_LABELS = 12;
+
+/**
+ * One editable row. `key` is a session-only identity, never persisted: the
+ * saved shape stays exactly `QuickLabel[]`. A label's `id` cannot serve here —
+ * it is re-derived from the text on every keystroke and two labels with the
+ * same text share it — and position cannot either, because moving a row must
+ * not move the open tip editor, an emoji draft, or focus onto a neighbour
+ * (the #829 bug class, #1736).
+ */
+interface QuickLabelRow {
+  key: string;
+  label: QuickLabel;
+}
+
+let rowKeySeq = 0;
+const nextRowKey = () => `quick-label-row-${++rowKeySeq}`;
+const toRows = (labels: readonly QuickLabel[]): QuickLabelRow[] =>
+  labels.map((label) => ({ key: nextRowKey(), label }));
+
+const shortcutHint = (digit: string) => `${altKey}${isMac ? '' : '+'}${digit}`;
+const shortcutWords = (digit: string) => `${isMac ? 'Option' : 'Alt'}+${digit}`;
+const labelName = (label: QuickLabel) => label.text.trim() || 'label';
+
+const EMOJI_HINT = isMac
+  ? 'Enter one emoji. Control-Command-Space opens the emoji picker.'
+  : isWindows
+    ? 'Enter one emoji. Windows+period opens the emoji picker.'
+    : 'Enter one emoji.';
+
+const ChevronIcon: React.FC<{ up: boolean }> = ({ up }) => (
+  <svg className="w-3 h-3" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2} aria-hidden="true">
+    <path strokeLinecap="round" strokeLinejoin="round" d={up ? 'M5 15l7-7 7 7' : 'M19 9l-7 7-7-7'} />
+  </svg>
+);
+
+/** Settings → Labels: the Quick Labels editor (plan review and annotate). */
+export const QuickLabelsTab: React.FC = () => {
+  const [rows, setRows] = useState<QuickLabelRow[]>(() => toRows(getQuickLabels()));
+  const [editingTipKey, setEditingTipKey] = useState<string | null>(null);
+  const [editingTipValue, setEditingTipValue] = useState('');
+  /** Emoji fields whose current text is not (yet) one emoji, by row key. */
+  const [emojiDrafts, setEmojiDrafts] = useState<Record<string, string>>({});
+  const [announcement, setAnnouncement] = useState('');
+  const listRef = useRef<HTMLDivElement>(null);
+  const pendingFocus = useRef<{ key: string; target: 'up' | 'down' | 'text' } | null>(null);
+
+  const commit = (next: QuickLabelRow[]) => {
+    setRows(next);
+    saveQuickLabels(next.map((row) => row.label));
+  };
+
+  const updateLabel = (key: string, patch: Partial<QuickLabel>) => {
+    commit(rows.map((row) => (row.key === key ? { ...row, label: { ...row.label, ...patch } } : row)));
+  };
+
+  const setEmojiDraft = (key: string, value: string | null) => {
+    setEmojiDrafts((drafts) => {
+      if (value === null) {
+        if (!(key in drafts)) return drafts;
+        const { [key]: _dropped, ...rest } = drafts;
+        return rest;
+      }
+      return { ...drafts, [key]: value };
+    });
+  };
+
+  const move = (index: number, delta: -1 | 1) => {
+    const to = index + delta;
+    if (to < 0 || to >= rows.length) return;
+    const row = rows[index];
+    commit(moveQuickLabel(rows, index, to));
+    pendingFocus.current = { key: row.key, target: delta < 0 ? 'up' : 'down' };
+    const digit = quickLabelShortcutDigit(to);
+    setAnnouncement(
+      `Moved ${labelName(row.label)} to position ${to + 1} of ${rows.length}, ${digit ? shortcutWords(digit) : 'no shortcut key'}.`,
+    );
+  };
+
+  // Moving a row re-orders DOM nodes, which can drop focus from the button
+  // that was pressed; put it back on the same row's button so repeated
+  // presses keep walking the same label. At either end the pressed button is
+  // disabled, so focus goes to the other direction instead.
+  useLayoutEffect(() => {
+    const pending = pendingFocus.current;
+    if (!pending) return;
+    pendingFocus.current = null;
+    const row = listRef.current?.querySelector<HTMLElement>(`[data-quick-label-row="${pending.key}"]`);
+    if (!row) return;
+    if (pending.target === 'text') {
+      const input = row.querySelector<HTMLInputElement>('[data-quick-label-text]');
+      input?.focus();
+      input?.select();
+      return;
+    }
+    const other = pending.target === 'up' ? 'down' : 'up';
+    const wanted = row.querySelector<HTMLButtonElement>(`[data-quick-label-move="${pending.target}"]`);
+    const fallback = row.querySelector<HTMLButtonElement>(`[data-quick-label-move="${other}"]`);
+    (wanted && !wanted.disabled ? wanted : fallback)?.focus();
+  }, [rows]);
+
+  const saveTip = (key: string) => {
+    updateLabel(key, { tip: editingTipValue || undefined });
+    setEditingTipKey(null);
+  };
+
+  return (
+    <>
+      <div className="flex items-center justify-between">
+        <div>
+          <div className="text-sm font-medium flex items-center gap-2">Quick Labels</div>
+          <div className="text-xs text-muted-foreground">
+            Preset annotations for one-click feedback
+          </div>
+        </div>
+        <button
+          onClick={() => {
+            resetQuickLabels();
+            setRows(toRows(DEFAULT_QUICK_LABELS));
+            setEditingTipKey(null);
+            setEmojiDrafts({});
+          }}
+          className="text-[10px] text-muted-foreground hover:text-foreground transition-colors"
+        >
+          Reset to defaults
+        </button>
+      </div>
+
+      <style>{`
+        @keyframes tip-slide-open {
+          from { opacity: 0; transform: translateY(-4px); }
+          to   { opacity: 1; transform: translateY(0); }
+        }
+      `}</style>
+      <div ref={listRef} className="space-y-1.5">
+        {rows.map((row, index) => {
+          const { key, label } = row;
+          const colors = getLabelColors(label.color);
+          const hasTip = !!label.tip;
+          const isEditingTip = editingTipKey === key;
+          const digit = quickLabelShortcutDigit(index);
+          const name = labelName(label);
+          const emojiDraft = emojiDrafts[key];
+          const emojiInvalid = emojiDraft !== undefined;
+          const emojiErrorId = `${key}-emoji-error`;
+          return (
+            <div
+              key={key}
+              data-quick-label-row={key}
+              className="rounded-lg overflow-hidden"
+              style={{ backgroundColor: colors.bg }}
+            >
+              {/* Main row. On a narrow dialog the controls after the text
+                  field wrap onto a second line instead of being clipped by
+                  the row's overflow-hidden. */}
+              <div className="flex flex-wrap items-center gap-2 p-2">
+                <input
+                  type="text"
+                  data-quick-label-emoji
+                  value={emojiDraft ?? label.emoji}
+                  aria-label={`Emoji for ${name}`}
+                  aria-invalid={emojiInvalid || undefined}
+                  aria-describedby={emojiInvalid ? emojiErrorId : undefined}
+                  title="Change emoji"
+                  autoComplete="off"
+                  spellCheck={false}
+                  onFocus={(e) => e.target.select()}
+                  onChange={(e) => {
+                    const picked = emojiFromFieldInput(e.target.value, label.emoji);
+                    if (!picked) {
+                      setEmojiDraft(key, e.target.value);
+                      return;
+                    }
+                    setEmojiDraft(key, null);
+                    if (picked !== label.emoji) updateLabel(key, { emoji: picked });
+                  }}
+                  onBlur={() => setEmojiDraft(key, null)}
+                  onKeyDown={(e) => {
+                    if (e.key === 'Escape' && emojiInvalid) {
+                      e.preventDefault();
+                      e.stopPropagation();
+                      setEmojiDraft(key, null);
+                    }
+                  }}
+                  className="w-8 py-1 bg-background/80 rounded text-sm text-center leading-none focus:outline-none focus:ring-1 focus:ring-primary/50 flex-shrink-0"
+                  style={emojiInvalid ? { boxShadow: '0 0 0 1px var(--destructive)' } : undefined}
+                />
+                <input
+                  type="text"
+                  data-quick-label-text
+                  value={label.text}
+                  aria-label={`Label text, position ${index + 1}`}
+                  onChange={(e) => {
+                    updateLabel(key, {
+                      text: e.target.value,
+                      id: e.target.value.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, ''),
+                    });
+                  }}
+                  className="flex-1 min-w-0 px-2 py-1 bg-background/80 rounded text-xs focus:outline-none focus:ring-1 focus:ring-primary/50"
+                  // The basis is what makes the controls wrap: a row that
+                  // cannot give the text this much room moves them below.
+                  style={{ flexBasis: '8rem' }}
+                />
+                <div className="flex items-center gap-2 ml-auto">
+                  {/* Tip indicator button */}
+                  <button
+                    data-quick-label-tip-toggle
+                    onClick={() => {
+                      if (isEditingTip) {
+                        setEditingTipKey(null);
+                      } else {
+                        setEditingTipKey(key);
+                        setEditingTipValue(label.tip || '');
+                      }
+                    }}
+                    className={`relative p-1 rounded transition-all flex-shrink-0 ${
+                      hasTip
+                        ? 'bg-foreground/10 text-foreground/70 hover:text-foreground border border-foreground/15'
+                        : 'text-muted-foreground/30 hover:text-muted-foreground/60 border border-dashed border-muted-foreground/20 hover:border-muted-foreground/40'
+                    }`}
+                    title={hasTip ? `Tip: ${label.tip}` : 'Add AI instruction tip'}
+                  >
+                    <svg className="w-3 h-3" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+                      <path strokeLinecap="round" strokeLinejoin="round" d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" />
+                    </svg>
+                    {hasTip && (
+                      <span className="absolute -top-0.5 -right-0.5 w-1.5 h-1.5 rounded-full bg-foreground/50" />
+                    )}
+                  </button>
+                  <select
+                    value={label.color}
+                    aria-label={`Colour for ${name}`}
+                    onChange={(e) => updateLabel(key, { color: e.target.value })}
+                    className="px-1.5 py-1 bg-background/80 rounded text-[10px] focus:outline-none focus:ring-1 focus:ring-primary/50"
+                  >
+                    {Object.keys(LABEL_COLOR_MAP).map(c => (
+                      <option key={c} value={c}>{c}</option>
+                    ))}
+                  </select>
+                  <span
+                    data-quick-label-shortcut
+                    // Hidden below sm: touch devices that narrow rarely have an Alt key.
+                    className="hidden sm:block text-[10px] text-muted-foreground/50 font-mono w-8 text-center flex-shrink-0"
+                  >
+                    {digit ? shortcutHint(digit) : ''}
+                  </span>
+                  {/* Reorder: position decides which Alt/⌥ digit applies the label. */}
+                  <button
+                    type="button"
+                    data-quick-label-move="up"
+                    disabled={index === 0}
+                    onClick={() => move(index, -1)}
+                    aria-label={`Move ${name} up`}
+                    title="Move up"
+                    className="p-1 rounded text-muted-foreground hover:text-foreground transition-colors flex-shrink-0 disabled:opacity-30 disabled:pointer-events-none"
+                  >
+                    <ChevronIcon up />
+                  </button>
+                  <button
+                    type="button"
+                    data-quick-label-move="down"
+                    disabled={index === rows.length - 1}
+                    onClick={() => move(index, 1)}
+                    aria-label={`Move ${name} down`}
+                    title="Move down"
+                    className="p-1 rounded text-muted-foreground hover:text-foreground transition-colors flex-shrink-0 disabled:opacity-30 disabled:pointer-events-none"
+                  >
+                    <ChevronIcon up={false} />
+                  </button>
+                  <button
+                    onClick={() => {
+                      commit(rows.filter((r) => r.key !== key));
+                      setEmojiDraft(key, null);
+                      if (editingTipKey === key) setEditingTipKey(null);
+                    }}
+                    aria-label={`Remove ${name}`}
+                    className="p-1 rounded hover:bg-destructive/10 text-muted-foreground hover:text-destructive transition-colors flex-shrink-0"
+                    title="Remove label"
+                  >
+                    <svg className="w-3 h-3" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+                      <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
+                    </svg>
+                  </button>
+                </div>
+              </div>
+              {emojiInvalid && (
+                <div id={emojiErrorId} className="px-2 pb-2 text-[10px] text-destructive">
+                  {EMOJI_HINT}
+                </div>
+              )}
+              {/* Tip editor — slides open below the row */}
+              {isEditingTip && (
+                <div
+                  className="flex items-center gap-1.5 px-2 pb-2 pt-0"
+                  style={{ animation: 'tip-slide-open 0.15s ease-out' }}
+                >
+                  <svg className="w-3 h-3 text-muted-foreground/40 flex-shrink-0 ml-6" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5}>
+                    <path strokeLinecap="round" strokeLinejoin="round" d="M17 8l4 4m0 0l-4 4m4-4H3" />
+                  </svg>
+                  <input
+                    type="text"
+                    data-quick-label-tip
+                    value={editingTipValue}
+                    aria-label={`AI instruction tip for ${name}`}
+                    onChange={(e) => setEditingTipValue(e.target.value)}
+                    onKeyDown={(e) => {
+                      if (e.key === 'Enter') saveTip(key);
+                      if (e.key === 'Escape') {
+                        e.preventDefault();
+                        e.stopPropagation();
+                        setEditingTipKey(null);
+                      }
+                    }}
+                    placeholder="AI instruction tip..."
+                    className="flex-1 px-2 py-1 bg-background/60 rounded text-[10px] text-muted-foreground placeholder:text-muted-foreground/30 focus:outline-none focus:ring-1 focus:ring-primary/50"
+                    autoFocus
+                    onFocus={(e) => { e.target.setSelectionRange(0, 0); e.target.scrollLeft = 0; }}
+                  />
+                  <button
+                    onClick={() => saveTip(key)}
+                    className="p-1 rounded text-muted-foreground/50 hover:text-green-500 hover:bg-green-500/10 transition-colors flex-shrink-0"
+                    title="Save tip"
+                  >
+                    <svg className="w-3 h-3" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2.5}>
+                      <path strokeLinecap="round" strokeLinejoin="round" d="M5 13l4 4L19 7" />
+                    </svg>
+                  </button>
+                </div>
+              )}
+            </div>
+          );
+        })}
+      </div>
+      <div role="status" aria-live="polite" className="sr-only">{announcement}</div>
+
+      {rows.length < MAX_QUICK_LABELS && (
+        <button
+          onClick={() => {
+            const row: QuickLabelRow = {
+              key: nextRowKey(),
+              label: {
+                id: `custom-${Date.now()}`,
+                emoji: '📌',
+                text: 'New label',
+                color: 'blue',
+              },
+            };
+            commit([...rows, row]);
+            pendingFocus.current = { key: row.key, target: 'text' };
+          }}
+          className="w-full py-1.5 text-xs text-muted-foreground hover:text-foreground border border-dashed border-border rounded-lg hover:border-foreground/30 transition-colors"
+        >
+          + Add label
+        </button>
+      )}
+
+      <div className="text-[10px] text-muted-foreground/70">
+        Use {shortcutHint('1')} through {shortcutHint('0')} when the annotation toolbar is visible to apply a label instantly. The order of the list decides the key; use the arrows to move a label, and click its emoji to change it.
+      </div>
+    </>
+  );
+};

package/hooks/useAIChat.ts

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import type { AIContext } from '@plannotator/core';
 import type { AIQuestion, AIResponse } from '../types';
 import { generateId } from '../utils/generateId';
+import { SESSION_ASK_ERROR_CODES } from '../utils/aiProvider';
 
 export interface AIChatEntry {
   question: AIQuestion;
@@ -45,8 +46,33 @@ export interface AskAIParams {
   /** "Ask this session" only: what to do when the host session is busy
    *  ("wait" = ask when it finishes, "interrupt" = stop its turn and ask now). */
   busyPolicy?: 'wait' | 'interrupt';
+  /** "Ask this session" only: the reviewer's CURRENT unsubmitted annotations
+   *  as a plain list (`formatDraftAnnotationsForAsk`; '' when there are none).
+   *  The hook sends it only when it differs from what this session last
+   *  received, and the server frames it as read-only context, never as
+   *  feedback (#1748). Leave unset for every other provider. */
+  draftAnnotations?: string;
 }
 
+/** What to send as `draftAnnotations` for one question: the list when this
+ *  session has not received it yet, '' once to clear drafts it saw earlier,
+ *  nothing when it already has the current list. */
+export function draftAnnotationsToSend(
+  delivered: { sessionId: string; text: string } | null,
+  sessionId: string,
+  current: string | undefined,
+): string | undefined {
+  if (current === undefined) return undefined;
+  const seen = delivered?.sessionId === sessionId ? delivered.text : '';
+  return current === seen ? undefined : current;
+}
+
+/** `draftAnnotationsToSend` key for "Ask this session": one host session per page. */
+const BRIDGE_DRAFTS_KEY = 'session-bridge';
+
+/** Stream messages that show the session received the question. */
+const DELIVERED_MESSAGE_TYPES = new Set(['text_delta', 'text', 'tool_use', 'tool_result', 'result']);
+
 /** Overrides for re-asking a question that ended in a busy/gone/blocked answer. */
 export interface AIRetryOptions {
   busyPolicy?: 'wait' | 'interrupt';
@@ -65,6 +91,16 @@ interface UseAIChatOptions {
   threadTitle?: string;
 }
 
+/** `line 41` / `lines 41–44` (the export's spelling) for a selection's
+ *  source lines; `null` when the scope carries no valid line. */
+function selectionLinesLabel(lineStart: unknown, lineEnd: unknown): string | null {
+  if (typeof lineStart !== 'number' || !Number.isInteger(lineStart) || lineStart < 1) return null;
+  const end = typeof lineEnd === 'number' && Number.isInteger(lineEnd) && lineEnd > lineStart
+    ? lineEnd
+    : lineStart;
+  return end === lineStart ? `line ${lineStart}` : `lines ${lineStart}–${end}`;
+}
+
 export function buildDefaultPrompt(params: AskAIParams): string {
   // The "changes under review" context (and any other preamble) leads the
   // message, so the agent is oriented to the live view before the question and
@@ -89,9 +125,12 @@ export function buildDefaultPrompt(params: AskAIParams): string {
 
     if (params.scope?.kind === 'selection') {
       const label = params.scope.label ? `Re: ${params.scope.label}` : 'Re: selected text';
-      const source = params.scope.sourcePath ? `\nSource: ${params.scope.sourcePath}` : '';
+      const lines = selectionLinesLabel(params.scope.lineStart, params.scope.lineEnd);
+      const sourceParts = [params.scope.sourcePath, lines].filter(Boolean);
+      const source = sourceParts.length > 0 ? `\nSource: ${sourceParts.join(', ')}` : '';
       const selection = params.scope.text ? `\n\nSelected text:\n\`\`\`\n${params.scope.text}\n\`\`\`` : '';
-      return `${label}${source}${selection}\n\n${params.prompt}`;
+      const detail = params.scope.detail?.trim() ? `\n\nSelected element:\n${params.scope.detail.trim()}` : '';
+      return `${label}${source}${selection}${detail}\n\n${params.prompt}`;
     }
 
     // General question (no explicit file/line/selection): tell the agent what the
@@ -289,9 +328,17 @@ export function useAIChat({
     return safeAbort(sessionId);
   }, []);
 
-  // The params each question was asked with, so a busy/gone answer can be
-  // re-asked ("Ask when it finishes", "Ask a separate AI instead").
+  // The params each question was asked with, so a busy answer can be
+  // re-asked ("Ask when it finishes", "Interrupt and ask now").
   const paramsByQuestionRef = useRef(new Map<string, AskAIParams>());
+  // The draft list the agent session last RECEIVED, so an unchanged list is
+  // not pasted into it again on every question. Kept for the page, not per
+  // Plannotator AI session: every Ask AI session (a new thread, a document
+  // switch in a folder or bundle) reaches the SAME host agent session through
+  // the bridge, which keeps what it already read. Per AI session, a new thread
+  // re-sent the whole list, and drafts cleared after one never reached the
+  // session as cleared.
+  const deliveredDraftsRef = useRef<{ sessionId: string; text: string } | null>(null);
 
   const ask = useCallback(async (params: AskAIParams, askOptions?: { providerId?: string }) => {
     if (abortRef.current) {
@@ -350,11 +397,21 @@ export function useAIChat({
       }
 
       const fullPrompt = buildPrompt(params);
+      const drafts = draftAnnotationsToSend(deliveredDraftsRef.current, BRIDGE_DRAFTS_KEY, params.draftAnnotations);
+      // Recorded once the session shows it received the question, so a busy,
+      // gone or failed ask sends the list again next time.
+      const markDraftsDelivered = (msg: { type?: unknown; code?: unknown }) => {
+        if (drafts === undefined) return;
+        const received = DELIVERED_MESSAGE_TYPES.has(String(msg.type))
+          || (msg.type === 'error' && msg.code === SESSION_ASK_ERROR_CODES.takenOver);
+        if (received) deliveredDraftsRef.current = { sessionId: BRIDGE_DRAFTS_KEY, text: drafts };
+      };
       const res = await aiTransport.query({
         sessionId: sid,
         prompt: fullPrompt,
         ...(params.contextUpdate && { contextUpdate: params.contextUpdate }),
         ...(params.busyPolicy && { busyPolicy: params.busyPolicy }),
+        ...(drafts !== undefined && { draftAnnotations: drafts }),
       }, controller.signal);
 
       if (!res.ok || !res.body) {
@@ -381,6 +438,7 @@ export function useAIChat({
 
           try {
             const msg = JSON.parse(data);
+            markDraftsDelivered(msg);
 
             if (msg.type === 'text_delta') {
               updateMessages(prev =>
@@ -420,6 +478,25 @@ export function useAIChat({
                 description: msg.description,
                 toolUseId: msg.toolUseId,
               }]);
+            } else if (msg.type === 'error' && msg.code === SESSION_ASK_ERROR_CODES.takenOver) {
+              // "Ask this session": the person typed into the session while it
+              // answered. The answer so far stands; the reason is a note under
+              // it, not an error that would replace it.
+              updateMessages(prev =>
+                prev.map(m =>
+                  m.question.id === questionId
+                    ? {
+                        ...m,
+                        response: {
+                          ...m.response,
+                          notice: typeof msg.error === 'string' ? msg.error : undefined,
+                          ...(m.response.status && { status: undefined }),
+                          isStreaming: false,
+                        },
+                      }
+                    : m
+                )
+              );
             } else if (msg.type === 'error') {
               updateMessages(prev =>
                 prev.map(m =>
@@ -498,8 +575,8 @@ export function useAIChat({
 
   /**
    * Re-ask an earlier question in place of its answer: the busy-session choice
-   * ("Ask when it finishes" / "Interrupt and ask now") and the fallback to a
-   * separate AI after "Ask this session" reports the session gone or blocked.
+   * ("Ask when it finishes" / "Interrupt and ask now"). `providerId` re-asks
+   * on another provider for hosts that offer one.
    */
   const retry = useCallback((questionId: string, options: AIRetryOptions = {}) => {
     const original = paramsByQuestionRef.current.get(questionId);