@thaut/claude-ide 0.0.0-stage → 1.0.0

package/web/src/agent-history-flow.test.ts

@@ -0,0 +1,191 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { QueryClient, QueryObserver } from "@tanstack/react-query";
+import { agentMetadataQuery, agentResponseModel, agentTranscriptParents, backgroundAgentToolUseId, resolveSubagent } from "./agent-history-flow.ts";
+import type { AgentTask, BgTask, LiveEvent, SdkMessageLike } from "@shared/protocol.ts";
+import { currentAgentTask } from "@shared/agent-tasks.ts";
+import { buildItems } from "./transcript.ts";
+import { boundSession } from "./message-cache.ts";
+import { mergeSnapshot, type SessionLive } from "./live-merge.ts";
+
+test("current agent run is independent of late update order and its terminal status", () => {
+  const old: AgentTask = { taskId: "stable", toolUseId: "old", runId: "run-1", status: "completed", model: "old-model" };
+  const current: AgentTask = { taskId: "stable", toolUseId: "new", runId: "run-2", status: "running", model: "new-model" };
+  const partial: AgentTask = { taskId: "stable", toolUseId: "no-run", status: "running" };
+  const other: AgentTask = { taskId: "sibling", toolUseId: "sibling", runId: "run-9", status: "running" };
+  const task: BgTask = { id: "stable", type: "local_agent", description: "agent", status: "running" };
+  for (const tasks of [[old, current, partial, other], [current, partial, other, old], [partial, current, old]]) {
+    assert.equal(currentAgentTask(tasks, "stable"), current);
+    assert.equal(backgroundAgentToolUseId(task, tasks), "new");
+    const completed = { ...current, status: "completed" as const };
+    assert.equal(currentAgentTask([completed, old, partial], "stable"), completed, "a finished new run cannot fall back to an older one");
+  }
+  assert.equal(currentAgentTask([old], "missing"), undefined);
+  assert.equal(currentAgentTask([partial, { ...partial, toolUseId: "last" }], "stable")?.toolUseId, "last", "legacy events without run IDs retain the arrival-order fallback");
+});
+
+test("resumed traces retain preceding live messages against an unchanged partial history window", () => {
+  const agent = { agentId: "stable", toolUseId: "original" };
+  const tasks: AgentTask[] = [
+    { taskId: "stable", toolUseId: "previous", runId: "run-1", status: "completed" },
+    { taskId: "stable", toolUseId: "current", runId: "run-2", status: "running" },
+    { taskId: "nested", parentToolUseId: "current", toolUseId: "nested", status: "running" },
+    { taskId: "sibling", toolUseId: "sibling", status: "running" },
+  ];
+  const parents = agentTranscriptParents("current", tasks, agent);
+  assert.deepEqual([...parents], ["current", "original", "previous"]);
+  assert.deepEqual([...agentTranscriptParents("current", tasks)], ["current"], "unresolved routes never guess a transcript owner");
+  const message = (uuid: string, parent: string | null): SdkMessageLike => ({ type: "assistant", uuid, parent_tool_use_id: parent, message: { id: uuid, content: [{ type: "text", text: uuid }] } });
+  const saved = message("saved", null), old = message("old-live", "previous"), resumed = message("new-live", "current");
+  const history = [saved];
+  const events: LiveEvent[] = [saved, old, resumed, message("main", null), message("nested", "nested"), message("sibling", "sibling")].map((m) => ({ k: "sdk", m }));
+  const options = { parent: "current", parents };
+  assert.deepEqual(buildItems(history, events, options).map((item) => item.key), ["saved:0", "old-live:0", "new-live:0"]);
+  assert.deepEqual(buildItems([saved, old], events, options).map((item) => item.key), ["saved:0", "old-live:0", "new-live:0"], "history/live overlap renders once");
+  assert.deepEqual(buildItems(history, [], options).map((item) => item.key), ["saved:0"], "historical browsing admits no live frames");
+  assert.deepEqual(history, [saved], "resuming neither replaces nor extends the selected history window");
+});
+
+test("retained invocation owners outlive status eviction and view unmount, then leave with their messages", () => {
+  const agent = { agentId: "stable", toolUseId: "spawn" };
+  const old: LiveEvent = { k: "sdk", m: { type: "assistant", uuid: "old", parent_tool_use_id: "resume-1", message: { content: [{ type: "text", text: "older live" }] } } };
+  const next: LiveEvent = { k: "delta", msgId: "new", index: 0, kind: "text", text: "current live", parent: "resume-2" };
+  const tasks: AgentTask[] = [
+    { taskId: "stable", toolUseId: "resume-1", status: "completed" },
+    { taskId: "stable", toolUseId: "resume-2", status: "running" },
+    { taskId: "nested", toolUseId: "nested", parentToolUseId: "resume-2", status: "running" },
+  ];
+  let session: SessionLive = boundSession({ seq: 1, resetCount: 0, events: [old, next], snapshot: { state: "running", pending: [], crons: [], tasks: [], agentTasks: tasks, planMode: false } });
+  session = boundSession({ ...session, snapshot: { ...session.snapshot, agentTasks: tasks.slice(1) } });
+  const reopened = agentTranscriptParents("resume-2", session.snapshot.agentTasks!, agent, session.agentOwners);
+  assert.equal(reopened.has("resume-1"), true);
+  assert.equal(reopened.has("nested"), false);
+  assert.deepEqual(buildItems(undefined, session.events, { parent: "resume-2", parents: reopened }).map((item) => item.kind === "text" ? item.text : item.kind), ["older live", "current live"]);
+  session = boundSession({ ...session, events: [next] });
+  assert.equal(session.agentOwners?.["resume-1"], undefined, "released messages release their owner map entries");
+  const reset = mergeSnapshot(session, { epoch: "new", seq: 0, reset: true, historyRevision: "new-branch", live: { ...session.snapshot, agentTasks: [] }, events: [] });
+  assert.deepEqual(reset.agentOwners, {}, "branch/replay reset does not retain a second ownership history");
+});
+
+test("a fresh browser recovers attribution directly from replay after task metadata eviction", () => {
+  const replay: LiveEvent = { k: "sdk", agentId: "stable", m: { type: "assistant", uuid: "old", parent_tool_use_id: "old-owner", message: { content: [{ type: "text", text: "old live" }] } } };
+  const session = mergeSnapshot(undefined, { epoch: "e", seq: 9, reset: true, live: { state: "idle", pending: [], crons: [], tasks: [], agentTasks: [], planMode: false }, events: [{ seq: 9, ev: replay }] });
+  const parents = agentTranscriptParents("current", [], { agentId: "stable", toolUseId: "spawn" }, session.agentOwners);
+  assert.equal(parents.has("old-owner"), true);
+});
+
+test("resumed SendMessage calls resolve the original transcript through the stable agent task ID", () => {
+  const original = { agentId: "stable-agent", toolUseId: "original-Agent-call", description: "Plan multilingual project site" };
+  const other = { agentId: "other-agent", toolUseId: "other-Agent-call", description: original.description };
+  const agents = [other, original];
+  assert.equal(resolveSubagent(agents, original.toolUseId), original);
+  assert.equal(resolveSubagent(agents, "resume-SendMessage-call", original.agentId), original);
+  assert.equal(resolveSubagent(agents, "resume-SendMessage-call", undefined, original.agentId), original, "saved URL works after live task eviction or restart");
+  assert.equal(resolveSubagent(agents, "resume-SendMessage-call", original.agentId, other.agentId), original);
+  assert.equal(resolveSubagent(agents, "resume-SendMessage-call", "missing-agent", other.agentId), undefined, "a conflicting URL cannot replace a known live identity");
+  assert.equal(resolveSubagent(agents, "resume-SendMessage-call"), undefined, "descriptions do not establish identity");
+  assert.equal(resolveSubagent(agents, "resume-SendMessage-call", undefined, "missing-agent"), undefined, "URL hints must name an available transcript");
+});
+
+test("agent model comes from its latest real response, isolated from parent and nested agents", () => {
+  const response = (parent: string | null, model: unknown, extra = {}): LiveEvent => ({ k: "sdk", m: { type: "assistant", parent_tool_use_id: parent, message: { model }, ...extra } });
+  const events = [response("selected", "first-model"), response(null, "main-model"), response("other", "other-model"),
+    response("selected", " latest-model "), response("nested", "nested-model"), response("selected", "<synthetic>"),
+    response("selected", "error-model", { error: "failed" }), response("selected", "aborted-model", { aborted: true }),
+    response("selected", "  "), response("selected", 123)];
+  assert.equal(agentResponseModel("selected", events), "latest-model");
+  assert.equal(agentResponseModel("missing", events), undefined);
+  assert.equal(agentResponseModel("selected", [{ k: "sdk", m: { type: "user", parent_tool_use_id: "selected", message: { model: "not-an-assistant" } } }]), undefined);
+});
+
+test("agent model supports stream starts and saved history without guessing from settings", () => {
+  const saved: SdkMessageLike[] = [
+    { type: "assistant", message: { model: "saved-model" } },
+    { type: "assistant", parent_tool_use_id: "nested", message: { model: "nested-model" } },
+    { type: "assistant", message: { model: "<synthetic>" } },
+  ];
+  assert.equal(agentResponseModel("selected", [], saved), "saved-model");
+  const start: LiveEvent = { k: "sdk", m: { type: "stream_event", parent_tool_use_id: "selected", event: { type: "message_start", message: { model: "live-model" } } } };
+  assert.equal(agentResponseModel("selected", [start], saved), "live-model");
+  assert.equal(agentResponseModel("selected", [{ k: "settings", model: "main-setting", planMode: false }], saved), "saved-model");
+  assert.equal(agentResponseModel("selected", [{ k: "sdk", m: { type: "stream_event", parent_tool_use_id: "selected", event: { type: "message_delta", message: { model: "invalid" } } } }], saved), "saved-model");
+});
+
+test("background agent trace resolves exact task/tool identities for active and completed tasks", () => {
+  const task: BgTask = { id: "background-task-id", type: "local_agent", description: "same description", status: "running" };
+  const agents: AgentTask[] = [
+    { toolUseId: "other-tool", taskId: "other-task", description: task.description, status: "running" },
+    { toolUseId: "correct-tool", taskId: task.id, status: "running" },
+  ];
+  assert.equal(backgroundAgentToolUseId(task, agents), "correct-tool");
+  assert.equal(backgroundAgentToolUseId({ ...task, status: "completed" }, agents.map((agent) => ({ ...agent, status: "completed" }))), "correct-tool");
+  assert.equal(backgroundAgentToolUseId(task, agents, [{ agentId: task.id, toolUseId: "stale-tool" }]), "correct-tool", "explicit live relation takes precedence");
+  assert.equal(backgroundAgentToolUseId(task, [...agents, { toolUseId: "resumed-tool", taskId: task.id, status: "running" }]), "resumed-tool", "resumed task uses its most recently updated relation");
+});
+
+test("saved subagent metadata resolves missing live relations without guessing from descriptions", () => {
+  const task: BgTask = { id: "agent-file-id", type: "local_agent", description: "same description", status: "completed" };
+  const metadata = [{ agentId: "other-agent", toolUseId: "wrong-tool", description: task.description }, { agentId: task.id, toolUseId: "saved-tool" }];
+  assert.equal(backgroundAgentToolUseId(task, [], metadata), "saved-tool");
+  assert.equal(backgroundAgentToolUseId(task, [], metadata.slice(0, 1)), undefined);
+  assert.equal(backgroundAgentToolUseId(task, [], [{ agentId: task.id }]), undefined, "a task ID cannot be used as a tool-call route");
+  assert.equal(backgroundAgentToolUseId({ ...task, type: "local_bash" }, [], metadata), undefined);
+});
+
+test("Stop-hook subagent summaries resolve the same trace as stream local_agent tasks", () => {
+  const task: BgTask = { id: "agent-id", type: "subagent", description: "Plan multilingual project site", status: "running" };
+  const live: AgentTask[] = [{ taskId: task.id, toolUseId: "spawn-tool", status: "running" }];
+  const saved = [{ agentId: task.id, toolUseId: "saved-spawn-tool" }];
+  for (const type of ["subagent", "local_agent"]) {
+    assert.equal(backgroundAgentToolUseId({ ...task, type }, live), "spawn-tool");
+    assert.equal(backgroundAgentToolUseId({ ...task, type, status: "completed" }, [], saved), "saved-spawn-tool");
+  }
+  for (const type of ["shell", "local_bash", "monitor", "workflow"]) {
+    assert.equal(backgroundAgentToolUseId({ ...task, type }, live, saved), undefined);
+  }
+});
+
+test("CACHE-013 failed status refresh retains the selected source through retry", async () => {
+  const client = new QueryClient({ defaultOptions: { queries: { retry: false, gcTime: Infinity, staleTime: Infinity } } });
+  const metadata = [{ agentId: "a", toolUseId: "t" }];
+  const options = agentMetadataQuery("p", "s", async () => metadata);
+  client.setQueryData(options.queryKey, metadata);
+  const observer = new QueryObserver(client, options);
+  const states: { status: string; source?: string }[] = [];
+  const unsub = observer.subscribe((result) => states.push({ status: result.status, source: result.data?.[0]?.agentId }));
+  try {
+    observer.setOptions(agentMetadataQuery("p", "s", async () => { throw new Error("offline"); }));
+    await observer.refetch();
+    assert.equal(observer.getCurrentResult().status, "error");
+    assert.equal(observer.getCurrentResult().data?.[0]?.agentId, "a");
+    observer.setOptions(options);
+    await observer.refetch();
+    assert.equal(observer.getCurrentResult().status, "success");
+    assert.ok(states.some((state) => state.status === "error"));
+    assert.ok(states.every((state) => state.source === "a"));
+    // A successful, authoritative removal is distinct from a refresh failure.
+    observer.setOptions(agentMetadataQuery("p", "s", async () => []));
+    await observer.refetch();
+    assert.deepEqual(observer.getCurrentResult().data, []);
+  } finally { unsub(); observer.destroy(); client.clear(); }
+});
+
+test("metadata never carries a prior source across a project or session boundary", async () => {
+  for (const [pid, sid] of [["other-project", "s"], ["p", "other-session"]]) {
+    const client = new QueryClient({ defaultOptions: { queries: { retry: false, gcTime: Infinity, staleTime: Infinity } } });
+    const metadata = [{ agentId: "a", toolUseId: "t" }];
+    const initial = agentMetadataQuery("p", "s", async () => metadata);
+    client.setQueryData(initial.queryKey, metadata);
+    const observer = new QueryObserver(client, initial);
+    const unsub = observer.subscribe(() => {});
+    try {
+      let finish!: (value: typeof metadata) => void;
+      observer.setOptions(agentMetadataQuery(pid!, sid!, () => new Promise<typeof metadata>((resolve) => { finish = resolve; })));
+      assert.equal(observer.getCurrentResult().isPending, true);
+      assert.equal(observer.getCurrentResult().data, undefined);
+      finish([]);
+      await observer.refetch();
+      assert.deepEqual(observer.getCurrentResult().data, []);
+    } finally { unsub(); observer.destroy(); client.clear(); }
+  }
+});

package/web/src/agent-history-flow.ts

@@ -0,0 +1,58 @@
+import type { AgentTask, BgTask, LiveEvent, SdkMessageLike } from "@shared/protocol.ts";
+import { responseModel } from "@shared/agent-model.ts";
+import { isSubagentTaskType } from "@shared/task-types.ts";
+import { currentAgentTask } from "@shared/agent-tasks.ts";
+
+export type SubagentInfo = { agentId: string; toolUseId?: string; agentType?: string; description?: string };
+
+/** Status changes refresh the same metadata cache, so a failed refresh cannot
+ * temporarily erase the selected history source. Never share it across routes. */
+export function agentMetadataQuery<T>(projectId: string, sessionId: string, queryFn: () => Promise<T>) {
+  return { queryKey: ["subagents", projectId, sessionId] as const, queryFn };
+}
+
+/** A resumed agent uses a new SendMessage tool ID, but keeps its task/file ID. */
+export function resolveSubagent(agents: readonly SubagentInfo[], toolUseId: string, taskId?: string, savedAgentId?: string): SubagentInfo | undefined {
+  const original = agents.find((agent) => agent.toolUseId === toolUseId);
+  if (original) return original;
+  // A known live identity takes precedence over any saved URL hint.
+  const agentId = taskId ?? savedAgentId;
+  return agentId ? agents.find((agent) => agent.agentId === agentId) : undefined;
+}
+
+/** Background task IDs are not tool-call IDs. Prefer the explicit live relation;
+ * saved agent metadata also resolves tasks whose live relation was not retained. */
+export function backgroundAgentToolUseId(task: BgTask, tasks: readonly AgentTask[], agents: readonly SubagentInfo[] = []): string | undefined {
+  if (!isSubagentTaskType(task.type)) return undefined;
+  return currentAgentTask(tasks, task.id)?.toolUseId
+    || agents.find((agent) => agent.agentId === task.id)?.toolUseId || undefined;
+}
+
+/** A single transcript file survives multiple Agent/SendMessage invocations.
+ * Keep their exact owners, without admitting sibling or nested agent traffic. */
+export function agentTranscriptParents(toolUseId: string, tasks: readonly AgentTask[], agent?: SubagentInfo, owners: Readonly<Record<string, string>> = {}): ReadonlySet<string> {
+  const parents = new Set([toolUseId]);
+  if (agent) {
+    if (agent.toolUseId) parents.add(agent.toolUseId);
+    for (const task of tasks) if (task.taskId === agent.agentId) parents.add(task.toolUseId);
+    for (const [owner, agentId] of Object.entries(owners)) if (agentId === agent.agentId) parents.add(owner);
+  }
+  return parents;
+}
+
+/** Only inspect this agent's live frames or its own selected history file. */
+export function agentResponseModel(toolUseId: string, events: readonly LiveEvent[], history: readonly SdkMessageLike[] = []): string | undefined {
+  for (let i = events.length - 1; i >= 0; i--) {
+    const event = events[i]!;
+    if (event.k !== "sdk" || event.m.parent_tool_use_id !== toolUseId) continue;
+    const model = responseModel(event.m);
+    if (model) return model;
+  }
+  for (let i = history.length - 1; i >= 0; i--) {
+    const message = history[i]!;
+    if (message.parent_tool_use_id && message.parent_tool_use_id !== toolUseId) continue;
+    const model = responseModel(message);
+    if (model) return model;
+  }
+  return undefined;
+}

package/web/src/agent-owners.ts

@@ -0,0 +1,30 @@
+import type { AgentTask, LiveEvent } from "@shared/protocol.ts";
+
+/** Task status is capped separately from transcript replay. Keep exact owner
+ * identities with the cached transcript, including across component unmounts. */
+export function mergeAgentOwners(previous: Readonly<Record<string, string>> = {}, events: readonly LiveEvent[], tasks: readonly AgentTask[] = []): Record<string, string> {
+  const owners = { ...previous };
+  const remember = (tasks: readonly AgentTask[]) => {
+    for (const task of tasks) if (task.taskId) owners[task.toolUseId] = task.taskId;
+  };
+  for (const event of events) {
+    const parent = event.k === "sdk" ? event.m.parent_tool_use_id : event.k === "delta" ? event.parent : undefined;
+    if ((event.k === "sdk" || event.k === "delta") && event.agentId && parent) owners[parent] = event.agentId;
+    if (event.k === "agent_tasks") remember(event.tasks);
+    else if (event.k === "sdk" && event.m.type === "system" && event.m.subtype?.startsWith("task_")
+      && typeof event.m.tool_use_id === "string" && typeof event.m.task_id === "string") owners[event.m.tool_use_id] = event.m.task_id;
+  }
+  remember(tasks);
+  return owners;
+}
+
+/** At most one scalar relation per retained owner or current task. Eviction and
+ * branch reset release it with its messages, rather than growing a second log. */
+export function retainAgentOwners(owners: Readonly<Record<string, string>>, events: readonly LiveEvent[], tasks: readonly AgentTask[] = []): Record<string, string> {
+  const retained = new Set(tasks.map((task) => task.toolUseId));
+  for (const event of events) {
+    const parent = event.k === "sdk" ? event.m.parent_tool_use_id : event.k === "delta" ? event.parent : undefined;
+    if (parent) retained.add(parent);
+  }
+  return Object.fromEntries(Object.entries(owners).filter(([owner]) => retained.has(owner)));
+}

package/web/src/annotation-selection.test.ts

@@ -0,0 +1,36 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { annotationMenuPosition, fileSelectionText } from "./annotation-selection.ts";
+
+test("source selections preserve multiline text, blank lines and tabs without DOM newline nodes", () => {
+  assert.deepEqual(fileSelectionText("const first = 1;\n\n\tconst second = 2;\n", { line: 0, column: 6 }, { line: 2, column: 13 }), {
+    quote: "first = 1;\n\n\tconst second",
+    startLine: 1,
+    endLine: 3,
+  });
+});
+
+test("source selections retain original CRLF delimiters and exclude CSS line numbers", () => {
+  assert.deepEqual(fileSelectionText("alpha\r\nbeta\r\ngamma", { line: 0, column: 2 }, { line: 1, column: 2 }), {
+    quote: "pha\r\nbe",
+    startLine: 1,
+    endLine: 2,
+  });
+});
+
+test("a selection ending at the next line boundary reports only included lines", () => {
+  assert.deepEqual(fileSelectionText("one\ntwo\nthree", { line: 0, column: 0 }, { line: 2, column: 0 }), {
+    quote: "one\ntwo\n",
+    startLine: 1,
+    endLine: 2,
+  });
+  assert.equal(fileSelectionText("one", { line: 0, column: 1 }, { line: 0, column: 1 }), null);
+});
+
+test("annotation menu stays inside a shifted mobile visual viewport", () => {
+  const viewport = { left: 20, top: 100, width: 320, height: 300 };
+  assert.deepEqual(annotationMenuPosition({ left: -10, right: 10, top: 370, bottom: 390 }, viewport), { width: 112, left: 28, top: 322 });
+  const position = annotationMenuPosition({ left: 330, right: 350, top: 105, bottom: 120 }, viewport);
+  assert.equal(position.left, 220);
+  assert.equal(position.top, 128);
+});

package/web/src/annotation-selection.ts

@@ -0,0 +1,123 @@
+import type { AnnotationSource } from "./annotations.ts";
+
+export type AnnotationSelection = {
+  source: AnnotationSource;
+  quote: string;
+  rect: { left: number; right: number; top: number; bottom: number };
+};
+
+type FilePoint = { line: number; column: number };
+
+/** DOM source lines have no newline nodes. Slice the original file so CRLF, tabs and blank lines survive. */
+export function fileSelectionText(content: string, start: FilePoint, end: FilePoint) {
+  const lines = content.split("\n");
+  const starts = [0];
+  for (let i = 0; i < lines.length - 1; i++) starts.push(starts[i]! + lines[i]!.length + 1);
+  const offset = (point: FilePoint) => {
+    const line = Math.max(0, Math.min(lines.length - 1, point.line));
+    const visibleLength = lines[line]!.replace(/\r$/, "").length;
+    return starts[line]! + Math.max(0, Math.min(visibleLength, point.column));
+  };
+  const from = offset(start);
+  const to = offset(end);
+  if (from >= to) return null;
+  // An end boundary at the start of the next line does not include that line's contents.
+  const lastLine = end.column === 0 && end.line > start.line ? end.line - 1 : end.line;
+  return { quote: content.slice(from, to), startLine: start.line + 1, endLine: lastLine + 1 };
+}
+
+const EXCLUDED = 'button, input, textarea, select, option, [role="button"], [role="menu"], [role="dialog"], [contenteditable]:not([contenteditable="false"]), [data-annotation-exclude], [data-line-number], .line-number, [data-testid="show-all"], [aria-hidden="true"], script, style';
+
+function elementFor(node: Node): Element | null {
+  return node.nodeType === 1 ? node as Element : node.parentElement;
+}
+
+function allowedRange(root: HTMLElement, range: Range) {
+  if (!root.contains(range.startContainer) || !root.contains(range.endContainer)) return false;
+  if (elementFor(range.startContainer)?.closest(EXCLUDED) || elementFor(range.endContainer)?.closest(EXCLUDED)) return false;
+  // Endpoints alone are insufficient: a selection can pass through a toolbar between paragraphs.
+  for (const control of root.querySelectorAll(EXCLUDED)) {
+    if (range.intersectsNode(control)) return false;
+  }
+  return true;
+}
+
+function filePoint(code: Element, lines: Element[], node: Node, offset: number): FilePoint | null {
+  const line = elementFor(node)?.closest(".line");
+  if (line && line.parentElement === code) {
+    const index = lines.indexOf(line);
+    if (index < 0) return null;
+    const prefix = code.ownerDocument.createRange();
+    prefix.selectNodeContents(line);
+    prefix.setEnd(node, offset);
+    return { line: index, column: prefix.toString().length };
+  }
+  // Browsers also express a selection boundary between two line elements on <code> itself.
+  if (node === code) {
+    const next = code.childNodes[offset];
+    if (next) {
+      const index = lines.findIndex((candidate) => candidate === next || candidate.contains(next));
+      if (index >= 0) return { line: index, column: 0 };
+    }
+    if (offset === code.childNodes.length && lines.length) {
+      return { line: lines.length - 1, column: lines.at(-1)!.textContent?.length ?? 0 };
+    }
+  }
+  return null;
+}
+
+/** Only plain data leaves this function; callers never retain a live Range or DOM selection. */
+export function captureAnnotationSelection(
+  root: HTMLElement,
+  selection: Selection | null,
+  context: { sessionId?: string; agentToolUseId?: string; filePath?: string; fileContent?: string },
+): AnnotationSelection | null {
+  if (!selection || selection.isCollapsed || selection.rangeCount !== 1) return null;
+  const range = selection.getRangeAt(0);
+  if (!allowedRange(root, range)) return null;
+  let source: AnnotationSource;
+  let quote: string;
+  if (context.filePath !== undefined) {
+    const code = elementFor(range.startContainer)?.closest(".code-view code");
+    if (!code || !root.contains(code) || !code.contains(range.endContainer)) return null;
+    const lines = [...code.children].filter((element) => element.classList.contains("line"));
+    const start = filePoint(code, lines, range.startContainer, range.startOffset);
+    const end = filePoint(code, lines, range.endContainer, range.endOffset);
+    if (!start || !end) return null;
+    const content = context.fileContent ?? lines.map((line) => line.textContent ?? "").join("\n");
+    const captured = fileSelectionText(content, start, end);
+    if (!captured) return null;
+    quote = captured.quote;
+    source = { kind: "file", path: context.filePath, startLine: captured.startLine, endLine: captured.endLine };
+  } else {
+    if (!context.sessionId) return null;
+    const first = elementFor(range.startContainer)?.closest<HTMLElement>("[data-annotation-item]");
+    const last = elementFor(range.endContainer)?.closest<HTMLElement>("[data-annotation-item]");
+    const itemKey = first?.dataset.annotationItem;
+    if (!first || !itemKey || first !== last || !root.contains(first)) return null;
+    quote = selection.toString();
+    source = { kind: "message", sessionId: context.sessionId, itemKey, ...(context.agentToolUseId ? { agentToolUseId: context.agentToolUseId } : {}) };
+  }
+  if (!quote.trim()) return null;
+  const rect = range.getBoundingClientRect();
+  if (!rect.width && !rect.height) return null;
+  return { source, quote, rect: { left: rect.left, right: rect.right, top: rect.top, bottom: rect.bottom } };
+}
+
+export function annotationMenuPosition(
+  rect: AnnotationSelection["rect"],
+  viewport: { left: number; top: number; width: number; height: number },
+) {
+  const width = Math.min(112, Math.max(0, viewport.width - 16));
+  const height = 40;
+  const minLeft = viewport.left + 8;
+  const minTop = viewport.top + 8;
+  const maxLeft = Math.max(minLeft, viewport.left + viewport.width - width - 8);
+  const maxTop = Math.max(minTop, viewport.top + viewport.height - height - 8);
+  const below = rect.bottom + 8;
+  return {
+    width,
+    left: Math.max(minLeft, Math.min(maxLeft, (rect.left + rect.right - width) / 2)),
+    top: Math.max(minTop, Math.min(maxTop, below + height > viewport.top + viewport.height - 8 ? rect.top - height - 8 : below)),
+  };
+}