@plannotator/ui 0.51.0 → 0.52.0

package/types.ts

@@ -453,6 +453,12 @@ export interface AIQuestion {
     /** Agent-facing identity of the selected element(s) (raw-HTML / live-app
      *  pinpoints): sent with the question, never shown in the chat. */
     detail?: string;
+    /** 1-based source lines of a text selection in a markdown document (the
+     *  enclosing block's span, or first to last block for a selection over
+     *  several). `buildDefaultPrompt` appends them to the `Source:` line
+     *  (`, line 41` / `, lines 41–44`). Optional: absent prints no lines. */
+    lineStart?: number;
+    lineEnd?: number;
   };
   /** undefined = general question (no file scope) */
   filePath?: string;

package/utils/parser.ts

@@ -4,6 +4,7 @@ import { resolveReplyParents } from '@plannotator/core/annotation-threads';
 import { diagramAnchorLocationLine, parseDiagramAnchor } from '@plannotator/core/diagram-anchor';
 import {
   formatQuestionAnswerLines,
+  formatQuestionAnswerText,
   formatQuestionAnswersSection,
   indexQuestionBlocks,
   parseQuestionAnswer,
@@ -774,14 +775,19 @@ const isElementPlaceholderQuote = (text: unknown): boolean =>
  *  element instead (`Feedback on the <nav> element — "Primary"`); every other
  *  annotation keeps the quote line exactly as before. */
 const commentHeadingLine = (ann: any): string => {
+  const element = elementSubject(ann);
+  return element ? `Feedback on ${element}` : `Feedback on: "${ann.originalText}"`;
+};
+
+/** `the <nav> element — "Primary"` for a text-less pinpoint whose quote is
+ *  the bridge's placeholder; null for every other annotation. */
+const elementSubject = (ann: any): string | null => {
   const context = ann?.elementContext;
-  if (context && typeof context.tag === 'string' && isElementPlaceholderQuote(ann.originalText)) {
-    const tag = safeInline(context.tag, 32);
-    const name = context.name ? safeInline(context.name, 120) : '';
-    const file = elementSourceFileName(context);
-    return `Feedback on the <${tag}> element${name ? ` — "${name}"` : ''}${file && file !== name ? ` (${file})` : ''}`;
-  }
-  return `Feedback on: "${ann.originalText}"`;
+  if (!context || typeof context.tag !== 'string' || !isElementPlaceholderQuote(ann.originalText)) return null;
+  const tag = safeInline(context.tag, 32);
+  const name = context.name ? safeInline(context.name, 120) : '';
+  const file = elementSourceFileName(context);
+  return `the <${tag}> element${name ? ` — "${name}"` : ''}${file && file !== name ? ` (${file})` : ''}`;
 };
 
 /** The file a media element shows, so two nameless images read differently in a heading:
@@ -1031,6 +1037,29 @@ const lineLabelForAnnotation = (blocks: Block[], ann: any): string | null => {
   return `lines ${block.startLine}–${end}`;
 };
 
+/** The source lines a text selection covers, for an Ask AI question
+ *  (`AIQuestion.scope.lineStart` / `lineEnd`). `blockIds` are the blocks the
+ *  selection touches; the range runs from the first block's start line to
+ *  the last block's end line, so a selection inside one block names exactly
+ *  the span its annotation would export (`(line 41)` / `(lines 41–44)`).
+ *  Blocks without a line (diff blocks, unknown ids) are skipped; `null` when
+ *  none is left. */
+export const selectionSourceLines = (
+  blocks: readonly Block[],
+  blockIds: readonly string[],
+): { lineStart: number; lineEnd: number } | null => {
+  let lineStart = Infinity;
+  let lineEnd = -Infinity;
+  for (const id of blockIds) {
+    if (id.startsWith('diff-block-')) continue;
+    const block = blocks.find(b => b.id === id);
+    if (!block || typeof block.startLine !== 'number' || block.startLine < 1) continue;
+    lineStart = Math.min(lineStart, block.startLine);
+    lineEnd = Math.max(lineEnd, blockEndLine(block), block.startLine);
+  }
+  return Number.isFinite(lineStart) ? { lineStart, lineEnd } : null;
+};
+
 /** Separate valid question answers from ordinary feedback. A row whose
  *  `questionAnswer` fails validation stays ordinary feedback (its one-line
  *  text still reads), so nothing is ever dropped. */
@@ -1493,6 +1522,119 @@ export const exportCodeFileAnnotations = (annotations: CodeAnnotation[]): string
   return output;
 };
 
+/** What `formatDraftAnnotationsForAsk` lists: the same collections the
+ *  feedback export reads, before the reviewer submits them. */
+export interface DraftAnnotationsForAsk {
+  /** The session's own document (plan, file, message). */
+  annotations: readonly Annotation[];
+  blocks?: Block[];
+  globalAttachments?: readonly ImageAttachment[];
+  /** Every other document holding drafts, by path. */
+  documents?: ReadonlyMap<string, LinkedDocAnnotationEntry>;
+  codeAnnotations?: readonly CodeAnnotation[];
+  editorAnnotations?: readonly EditorAnnotation[];
+}
+
+const MAX_ASK_DRAFT_ENTRIES = 60;
+const ASK_DRAFT_QUOTE_CHARS = 160;
+const ASK_DRAFT_TEXT_CHARS = 1000;
+
+/**
+ * The reviewer's UNSUBMITTED annotations as a plain list, for an "Ask this
+ * session" question (#1748). It is deliberately not the feedback export: no
+ * title, no "I've reviewed this … and have N pieces of feedback", no numbered
+ * "Feedback on" headings, no injected skill instructions. The session that
+ * reads it is the agent the review is for, so a draft must read as something
+ * the reviewer is still writing, not as a request. The server wraps the list
+ * in a read-only frame (`SESSION_ASK_DRAFTS_LABEL`); this function only lists.
+ *
+ * One line per draft (`Draft 2 (line 14): comment on "…" — …`), numbered in
+ * document order so a question can say "draft 2"; every page-, file- or
+ * reviewer-supplied string is collapsed to one line and capped. Empty string
+ * when there are no drafts.
+ */
+export const formatDraftAnnotationsForAsk = (input: DraftAnnotationsForAsk): string => {
+  type Row = { ann: any; where: string | null };
+  const rows: Row[] = [];
+  const placeOf = (blocks: Block[] | undefined, ann: any): string | null => {
+    if (ann.diffContext) return 'in the version diff';
+    return blocks ? lineLabelForAnnotation(blocks, ann) : null;
+  };
+  for (const ann of sortAnnotationsInDocumentOrder([...input.annotations], input.blocks)) {
+    rows.push({ ann, where: placeOf(input.blocks, ann) });
+  }
+  for (const [path, doc] of input.documents ?? []) {
+    for (const ann of sortAnnotationsInDocumentOrder([...doc.annotations], doc.blocks)) {
+      const line = placeOf(doc.blocks, ann);
+      rows.push({ ann, where: line ? `${safeInline(path, 300)}, ${line}` : safeInline(path, 300) });
+    }
+  }
+
+  const numbers = new Map<string, number>();
+  rows.forEach((row, index) => {
+    if (typeof row.ann?.id === 'string') numbers.set(row.ann.id, index + 1);
+  });
+  const replyParents = resolveReplyParents(rows.map((row) => row.ann));
+  const quote = (value: unknown) => `"${safeInline(value, ASK_DRAFT_QUOTE_CHARS)}"`;
+  const text = (value: unknown) => safeInline(value, ASK_DRAFT_TEXT_CHARS);
+  const imageList = (list: readonly ImageAttachment[]): string =>
+    list.map((img) => `[${safeInline(img?.name, 80)}] ${safeInline(img?.path, 300)}`).join(', ');
+  const images = (list: unknown): string =>
+    Array.isArray(list) && list.length > 0 ? ` (attached: ${imageList(list)})` : '';
+
+  const lines: string[] = [];
+  rows.forEach(({ ann, where }, index) => {
+    const parent = replyParents.get(ann.id);
+    const parentNumber = parent ? numbers.get(parent) : undefined;
+    const head = `Draft ${index + 1}${where ? ` (${where})` : ''}:`;
+    const from = ann.source ? ` (from ${safeInline(ann.source, 60)})` : '';
+    const answer = ann.questionAnswer == null ? null : parseQuestionAnswer(ann.questionAnswer);
+    let body: string;
+    if (answer) {
+      body = `answer to the question ${quote(answer.prompt)} — ${text(formatQuestionAnswerText(answer))}`;
+    } else if (parentNumber !== undefined) {
+      body = `reply to draft ${parentNumber} — ${text(ann.text)}`;
+    } else if (ann.type === 'DELETION') {
+      body = `suggests removing ${quote(ann.originalText)}`;
+    } else if (ann.type === 'GLOBAL_COMMENT') {
+      body = `general note — ${text(ann.text)}`;
+    } else {
+      const subject = elementSubject(ann) ?? quote(ann.originalText);
+      const anchor = ann.diagramAnchor === undefined ? null : parseDiagramAnchor(ann.diagramAnchor);
+      const target = anchor ? `${subject} [${safeInline(diagramAnchorLocationLine(anchor), 300)}]` : subject;
+      body = ann.isQuickLabel
+        ? `label ${quote(ann.text)} on ${target}`
+        : `comment on ${target} — ${text(ann.text)}`;
+    }
+    lines.push(`${head} ${body}${from}${images(ann.images)}`);
+  });
+
+  let next = rows.length;
+  for (const ann of input.codeAnnotations ?? []) {
+    next += 1;
+    const range = ann.lineStart === ann.lineEnd ? `line ${ann.lineStart}` : `lines ${ann.lineStart}–${ann.lineEnd}`;
+    const on = ann.originalCode ? ` on ${quote(ann.originalCode)}` : '';
+    lines.push(`Draft ${next} (${safeInline(ann.filePath, 300)}, ${range}): comment${on} — ${text(ann.text)}${ann.source ? ` (from ${safeInline(ann.source, 60)})` : ''}${images(ann.images)}`);
+  }
+  for (const ann of input.editorAnnotations ?? []) {
+    next += 1;
+    const range = ann.lineStart === ann.lineEnd ? `line ${ann.lineStart}` : `lines ${ann.lineStart}–${ann.lineEnd}`;
+    lines.push(`Draft ${next} (${safeInline(ann.filePath, 300)}, ${range}): comment on ${quote(ann.selectedText)} — ${text(ann.comment)}`);
+  }
+
+  const shown = lines.slice(0, MAX_ASK_DRAFT_ENTRIES);
+  if (lines.length > shown.length) shown.push(`… and ${lines.length - shown.length} more draft annotations`);
+
+  const attachments = input.globalAttachments ?? [];
+  if (attachments.length > 0) shown.push(`Reference images: ${imageList(attachments)}`);
+  for (const [path, doc] of input.documents ?? []) {
+    if (doc.globalAttachments.length > 0) {
+      shown.push(`Reference images (${safeInline(path, 300)}): ${imageList(doc.globalAttachments)}`);
+    }
+  }
+  return shown.join('\n');
+};
+
 export interface MessageAnnotationEntry {
   messageId: string;
   text: string;

package/utils/quickLabels.ts

@@ -76,6 +76,86 @@ export function resetQuickLabels(): void {
   storage.removeItem(STORAGE_KEY);
 }
 
+/**
+ * The Alt/⌥ digit that applies the label at list position `index`: "1".."9"
+ * for the first nine, "0" for the tenth, null past it. Position is the whole
+ * contract — the pickers, the toolbar and the Settings key hints all read it
+ * from here, so reordering the list (Settings → Labels) is what remaps keys.
+ */
+export function quickLabelShortcutDigit(index: number): string | null {
+  if (!Number.isInteger(index) || index < 0 || index > 9) return null;
+  return index === 9 ? '0' : String(index + 1);
+}
+
+/** Inverse of {@link quickLabelShortcutDigit}: list position for a digit key. */
+export function quickLabelIndexForDigit(digit: number): number {
+  return digit === 0 ? 9 : digit - 1;
+}
+
+/**
+ * Return a copy of `labels` with the entry at `from` moved to `to`. The moved
+ * label keeps every field (emoji, text, colour, tip). Out-of-range indices
+ * return an unchanged copy.
+ */
+export function moveQuickLabel<T>(labels: readonly T[], from: number, to: number): T[] {
+  const next = labels.slice();
+  if (from === to || from < 0 || to < 0 || from >= next.length || to >= next.length) return next;
+  const [moved] = next.splice(from, 1);
+  next.splice(to, 0, moved);
+  return next;
+}
+
+/** Longest single emoji we accept (ZWJ family sequences run ~11 code points). */
+const MAX_EMOJI_LENGTH = 32;
+const PICTOGRAPHIC = /\p{Extended_Pictographic}/u;
+const FLAG = /^\p{Regional_Indicator}{2}$/u;
+const KEYCAP = /^[0-9#*]️?⃣$/u;
+const WHITESPACE_OR_CONTROL = /[\s\p{Cc}]/u;
+
+function splitGraphemes(value: string): string[] {
+  const Segmenter = (Intl as { Segmenter?: typeof Intl.Segmenter }).Segmenter;
+  if (Segmenter) {
+    return Array.from(new Segmenter(undefined, { granularity: 'grapheme' }).segment(value), (s) => s.segment);
+  }
+  // No grapheme segmentation: treat the whole string as one candidate and let
+  // the emoji check decide. Every browser Plannotator supports has it.
+  return value ? [value] : [];
+}
+
+/**
+ * Validate a quick-label emoji: exactly one emoji grapheme (pictographic
+ * symbol, ZWJ sequence, skin-tone variant, flag or keycap), surrounding
+ * whitespace ignored. Returns the emoji, or null when the input is empty,
+ * more than one character, or not an emoji.
+ */
+export function parseQuickLabelEmoji(input: string): string | null {
+  const value = input.trim();
+  if (!value || value.length > MAX_EMOJI_LENGTH) return null;
+  const graphemes = splitGraphemes(value);
+  if (graphemes.length !== 1) return null;
+  const [g] = graphemes;
+  if (WHITESPACE_OR_CONTROL.test(g)) return null;
+  if (FLAG.test(g) || KEYCAP.test(g) || PICTOGRAPHIC.test(g)) return g;
+  return null;
+}
+
+/**
+ * The emoji a person meant by editing an emoji field that held `current`.
+ * Accepts a field holding just the new emoji, and also the field after a new
+ * emoji was typed or picked BESIDE the old one (the caret was not on a
+ * selection): the old one is set aside once. Null when the field does not
+ * name exactly one emoji.
+ */
+export function emojiFromFieldInput(value: string, current: string): string | null {
+  const graphemes = splitGraphemes(value.trim()).filter((g) => !/^\s+$/u.test(g));
+  if (graphemes.length === 1) return parseQuickLabelEmoji(graphemes[0]);
+  if (graphemes.length === 2) {
+    const at = graphemes.indexOf(current);
+    if (at >= 0) return parseQuickLabelEmoji(graphemes[1 - at]);
+  }
+  return null;
+}
+
 /** Find a configured label whose "emoji text" matches an annotation's text field */
 export function findLabelByText(annotationText: string): QuickLabel | undefined {
   return getQuickLabels().find(l => `${l.emoji} ${l.text}` === annotationText);

package/utils/serverSession.ts

@@ -0,0 +1,85 @@
+/**
+ * Client half of the stale-tab guard (packages/core/server-session.ts).
+ *
+ * The tab keeps the `serverSession` nonce the server advertised on its first
+ * payload (`/api/plan`, `/api/diff`) and echoes it on every decision it posts.
+ * A server that does not recognize it (a NEW Plannotator session that took
+ * over the same port) answers `409 { code: "session_mismatch" }`; the tab then
+ * shows the reload prompt (`ServerSessionReplacedBanner`) instead of treating
+ * the refusal as an ordinary failure.
+ *
+ * Module state on purpose: one tab talks to one server, and every decision
+ * path (plan approve/deny, annotate feedback/approve/exit, review
+ * feedback/exit) reads the same value without threading it through props.
+ */
+
+import { useSyncExternalStore } from 'react';
+import { SERVER_SESSION_FIELD, SERVER_SESSION_MISMATCH_CODE } from '@plannotator/core/server-session';
+
+let nonce: string | null = null;
+let replaced = false;
+const listeners = new Set<() => void>();
+
+/** Adopt the nonce a payload advertised (absent from an older server: no guard). */
+export function adoptServerSession(value: unknown): void {
+  if (typeof value === 'string' && value) nonce = value;
+}
+
+/** The nonce this tab holds, or null when the server never advertised one. */
+export function currentServerSession(): string | null {
+  return nonce;
+}
+
+/** A decision body with the nonce added (unchanged when none is held). */
+export function withServerSession<T extends object>(body: T): T & { serverSession?: string } {
+  return nonce ? { ...body, [SERVER_SESSION_FIELD]: nonce } : body;
+}
+
+/** A decision URL with the nonce as a query parameter (exit posts carry no body). */
+export function withServerSessionQuery(url: string): string {
+  if (!nonce) return url;
+  return `${url}${url.includes('?') ? '&' : '?'}${SERVER_SESSION_FIELD}=${encodeURIComponent(nonce)}`;
+}
+
+/** Whether a decision response is the server's session-mismatch refusal. Records it when it is. */
+export async function noteServerSessionMismatch(res: Response): Promise<boolean> {
+  if (res.status !== 409) return false;
+  let code: unknown;
+  try {
+    code = ((await res.clone().json()) as { code?: unknown } | null)?.code;
+  } catch {
+    return false;
+  }
+  if (code !== SERVER_SESSION_MISMATCH_CODE) return false;
+  markServerSessionReplaced();
+  return true;
+}
+
+export function markServerSessionReplaced(): void {
+  if (replaced) return;
+  replaced = true;
+  for (const listener of listeners) listener();
+}
+
+export function isServerSessionReplaced(): boolean {
+  return replaced;
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** React: true once a decision was refused because this tab's server was replaced. */
+export function useServerSessionReplaced(): boolean {
+  return useSyncExternalStore(subscribe, isServerSessionReplaced, isServerSessionReplaced);
+}
+
+/** Tests only: forget the nonce and the replaced flag. */
+export function __resetServerSessionForTests(): void {
+  nonce = null;
+  replaced = false;
+  for (const listener of listeners) listener();
+}