@thaut/claude-ide 0.0.0-stage → 1.0.0

package/web/src/annotations.test.ts

@@ -0,0 +1,279 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { clearDraft, editDraft, restoreRewindDraft, setDraft, useDrafts } from "./drafts.ts";
+import type { AnnotationSource, DraftAnnotation } from "./annotations.ts";
+
+type Annotations = typeof import("./annotations.ts");
+const storageKey = "cide.annotations.v1";
+let moduleId = 0;
+function memoryStorage() {
+  const values = new Map<string, string>();
+  const failures: { read?: Error; write?: Error } = {};
+  return {
+    values,
+    failures,
+    getItem(key: string) {
+      if (failures.read) throw failures.read;
+      return values.get(key) ?? null;
+    },
+    setItem(key: string, value: string) {
+      if (failures.write) throw failures.write;
+      values.set(key, value);
+    },
+    removeItem(key: string) { values.delete(key); },
+  };
+}
+function installStorage(storage: ReturnType<typeof memoryStorage> | undefined) {
+  Object.defineProperty(globalThis, "localStorage", { value: storage, configurable: true });
+}
+async function reload(): Promise<Annotations> {
+  // A fresh module models a browser refresh without adding a product reset API.
+  return import(`./annotations.ts?annotations-test=${++moduleId}`);
+}
+function input(index = 0, source: AnnotationSource = { kind: "file", path: `src/file-${index}.ts`, startLine: 2, endLine: 4 }) {
+  return { projectId: "project-a", targetSessionId: "session-a", source, quote: `quoted text ${index}`, comment: `comment ${index}` };
+}
+
+test("SSR import is safe and browser initialization hydrates once", async () => {
+  installStorage(undefined);
+  const annotations = await reload();
+  assert.deepEqual(annotations.useAnnotations.getState(), { items: [], mode: false, recentSessions: {} });
+  const storage = memoryStorage();
+  storage.values.set(storageKey, JSON.stringify({ version: 1, items: [], mode: true, recentSessions: { p: "s" } }));
+  installStorage(storage);
+  annotations.ensureAnnotationsLoaded();
+  assert.equal(annotations.useAnnotations.getState().mode, true);
+  assert.deepEqual(annotations.useAnnotations.getState().recentSessions, { p: "s" });
+  storage.values.set(storageKey, JSON.stringify({ version: 1, items: [], mode: false, recentSessions: {} }));
+  annotations.ensureAnnotationsLoaded();
+  assert.equal(annotations.useAnnotations.getState().mode, true, "repeated initialization cannot replace active state");
+});
+
+test("navigation and module reload preserve every annotation, mode, and project target", async () => {
+  const storage = memoryStorage();
+  installStorage(storage);
+  const annotations = await reload();
+  for (let index = 0; index < 128; index++) {
+    const source: AnnotationSource = index % 2
+      ? { kind: "message", sessionId: "source-session", itemKey: `item:${index}`, agentToolUseId: "agent-tool" }
+      : { kind: "file", path: `文件/${index}.tsx`, startLine: 1, endLine: 2 };
+    annotations.addAnnotation({ ...input(index, source), targetSessionId: index % 3 ? "session-a" : "session-b", quote: "第一行\n\nlast line\n" });
+  }
+  annotations.setAnnotationMode(true);
+  annotations.rememberAnnotationSession("project-a", "session-b");
+  annotations.rememberAnnotationSession("project-b", "session-c");
+  const before = annotations.useAnnotations.getState();
+  assert.equal(before.items.length, 128, "annotations have no cache-size eviction");
+  assert.equal(annotations.snapshotAnnotations("other-project", "session-a").length, 0);
+  assert.equal(annotations.snapshotAnnotations("project-a", "session-b").length, 43);
+  // Navigating away and back changes the visible slice, never the backing cards.
+  annotations.snapshotAnnotations("project-b", "session-c");
+  assert.equal(annotations.snapshotAnnotations("project-a", "session-a").length, 85);
+  const restored = await reload();
+  assert.deepEqual(restored.useAnnotations.getState().items, before.items);
+  assert.equal(restored.useAnnotations.getState().mode, true);
+  assert.deepEqual(restored.useAnnotations.getState().recentSessions, { "project-a": "session-b", "project-b": "session-c" });
+});
+
+test("draft clearing, rewind, and draft store replacement cannot remove annotation data", async () => {
+  const storage = memoryStorage();
+  installStorage(storage);
+  const annotations = await reload();
+  const item = annotations.addAnnotation(input());
+  const persisted = storage.values.get(storageKey);
+  editDraft("session-a", { text: "draft" });
+  clearDraft("session-a");
+  setDraft("session-a", "rewound", "rewind-a");
+  restoreRewindDraft("session-a", "older", "rewind-b");
+  useDrafts.setState({ drafts: {} });
+  assert.deepEqual(annotations.snapshotAnnotations("project-a", "session-a"), [item]);
+  assert.equal(storage.values.get(storageKey), persisted);
+  assert.notEqual(storageKey, "cide.draft.session-a");
+});
+
+test("successful send consumes exact snapshots while preserving later edits and additions", async () => {
+  installStorage(memoryStorage());
+  const annotations = await reload();
+  const unchanged = annotations.addAnnotation(input(0));
+  const changed = annotations.addAnnotation(input(1));
+  const deleted = annotations.addAnnotation(input(2));
+  const otherSession = annotations.addAnnotation({ ...input(3), targetSessionId: "session-b" });
+  const submitted = annotations.snapshotAnnotations("project-a", "session-a");
+  annotations.updateAnnotation(changed.id, "newer edit");
+  annotations.updateAnnotation(changed.id, changed.comment);
+  annotations.deleteAnnotation(deleted.id);
+  const added = annotations.addAnnotation(input(4));
+  annotations.consumeAnnotations(submitted);
+  const remaining = annotations.useAnnotations.getState().items;
+  assert.equal(remaining.some((item) => item.id === unchanged.id), false);
+  assert.equal(remaining.some((item) => item.id === deleted.id), false);
+  assert.deepEqual(remaining.map((item) => item.id), [changed.id, otherSession.id, added.id]);
+  assert.equal(remaining[0].revision, 3, "an edit remains newer even after restoring its submitted text");
+  annotations.consumeAnnotations(submitted);
+  assert.equal(annotations.useAnnotations.getState().items.length, 3, "a duplicate acknowledgement is harmless");
+  const restored = await reload();
+  assert.deepEqual(restored.useAnnotations.getState().items, remaining);
+});
+
+test("submission consumption obeys the same preservation property across interleaved edits", async () => {
+  installStorage(memoryStorage());
+  const annotations = await reload();
+  for (let round = 0; round < 32; round++) {
+    annotations.useAnnotations.setState({ items: [] });
+    const submittedItems = Array.from({ length: 8 }, (_, index) => annotations.addAnnotation(input(index)));
+    const snapshot = annotations.snapshotAnnotations("project-a", "session-a");
+    const survivors = new Set<string>();
+    submittedItems.forEach((item, index) => {
+      if ((round >> (index % 5)) & 1) {
+        annotations.updateAnnotation(item.id, `edited ${round}/${index}`);
+        survivors.add(item.id);
+      }
+      if ((round + index) % 7 === 0) {
+        annotations.deleteAnnotation(item.id);
+        survivors.delete(item.id);
+      }
+    });
+    for (let index = 0; index < round % 4; index++) survivors.add(annotations.addAnnotation(input(index + 8)).id);
+    annotations.consumeAnnotations(snapshot);
+    assert.deepEqual(new Set(annotations.useAnnotations.getState().items.map((item) => item.id)), survivors, `round ${round}`);
+  }
+});
+
+test("returned cards and snapshots do not alias mutable source data", async () => {
+  installStorage(memoryStorage());
+  const annotations = await reload();
+  const original = input();
+  const created = annotations.addAnnotation(original);
+  if (original.source.kind === "file") original.source.path = "mutated input";
+  if (created.source.kind === "file") created.source.path = "mutated return value";
+  const snapshot = annotations.snapshotAnnotations("project-a", "session-a");
+  snapshot[0].comment = "mutated snapshot";
+  if (snapshot[0].source.kind === "file") snapshot[0].source.path = "mutated snapshot source";
+  const current = annotations.useAnnotations.getState().items[0];
+  assert.equal(current.source.kind === "file" && current.source.path, "src/file-0.ts");
+  assert.equal(current.comment, "comment 0");
+});
+
+test("serialization preserves normal text, quote blank lines, Unicode, and comments", async () => {
+  installStorage(memoryStorage());
+  const annotations = await reload();
+  const file = annotations.addAnnotation({ ...input(), source: { kind: "file", path: "文件/实现.ts" }, quote: "\nα\n\n  z  \n", comment: "说明🙂\nsecond comment line" });
+  const message = annotations.addAnnotation({ ...input(1), source: { kind: "message", sessionId: "origin", itemKey: "uuid:2", agentToolUseId: "agent-1" }, quote: "first\r\nsecond", comment: "Fix this" });
+  assert.equal(annotations.formatAnnotatedMessage("normal text\n ", [file, message]),
+    "normal text\n \n\nUser comments on File 文件/实现.ts:\n> \n> α\n> \n>   z  \n> \n\n说明🙂\nsecond comment line\n\nUser comments:\n> first\r\n> second\n\nFix this");
+  assert.equal(annotations.formatAnnotatedMessage("!command\n", []), "!command\n");
+  assert.equal(annotations.formatAnnotatedMessage("", [{ ...file, quote: "", comment: "" }]), "User comments on File 文件/实现.ts:\n> \n\n");
+});
+
+test("message annotation context is independent of client identifiers while stored source metadata survives", async () => {
+  installStorage(memoryStorage());
+  const annotations = await reload();
+  const source: AnnotationSource = { kind: "message", sessionId: "source-session-id", itemKey: "1f385b18-1ed1-463c-96a9-7300c3e3f367:0", agentToolUseId: "agent-tool-id" };
+  const item = annotations.addAnnotation({ ...input(0, source), quote: "你要过滤后的音频，还是目标人的文字？", comment: "直接给文字最好。" });
+  const expected = "User comments:\n> 你要过滤后的音频，还是目标人的文字？\n\n直接给文字最好。";
+  assert.equal(annotations.formatAnnotatedMessage("", [item]), expected);
+  assert.equal(annotations.formatAnnotatedMessage("", [{ ...item, id: "other-card", projectId: "other-project", targetSessionId: "other-session", source: { kind: "message", sessionId: "other-source", itemKey: "other-message:9" } }]), expected);
+  const restored = await reload();
+  const saved = restored.snapshotAnnotations("project-a", "session-a");
+  assert.deepEqual(saved[0].source, source, "client selection metadata stays available after reload");
+  assert.equal(restored.formatAnnotatedMessage("", saved), expected, "previously stored drafts use the new serialization too");
+});
+
+test("attached annotations prevent leading slash or shell text from dispatching as SDK commands", async () => {
+  installStorage(memoryStorage());
+  const annotations = await reload();
+  const item = annotations.addAnnotation(input());
+  assert.equal(annotations.formatAnnotatedMessage("/clear", [item]),
+    "User message:\n/clear\n\nUser comments on File src/file-0.ts:\n> quoted text 0\n\ncomment 0");
+  assert.equal(annotations.formatAnnotatedMessage(" \n!echo hello", [item]),
+    "User message:\n \n!echo hello\n\nUser comments on File src/file-0.ts:\n> quoted text 0\n\ncomment 0");
+  assert.equal(annotations.formatAnnotatedMessage("/clear", []), "/clear");
+});
+
+test("invalid stored data reports an error without crashing or modifying storage", async () => {
+  const valid: DraftAnnotation = { ...input(), id: "saved", revision: 1, createdAt: 1, updatedAt: 2 };
+  const cases: unknown[] = [
+    null,
+    { version: 2, items: [valid], mode: false, recentSessions: {} },
+    { version: 1, items: null, mode: false, recentSessions: {} },
+    { version: 1, items: [{ ...valid, source: { kind: "file", path: "a", startLine: -1 } }], mode: false, recentSessions: {} },
+    { version: 1, items: [{ ...valid, revision: 0 }], mode: false, recentSessions: {} },
+    { version: 1, items: [valid, valid], mode: false, recentSessions: {} },
+    { version: 1, items: [valid], mode: false, recentSessions: { project: 42 } },
+  ];
+  for (const value of cases) {
+    const storage = memoryStorage();
+    const serialized = JSON.stringify(value);
+    storage.values.set(storageKey, serialized);
+    installStorage(storage);
+    const annotations = await reload();
+    assert.equal(annotations.useAnnotations.getState().items.length, 0);
+    assert.match(annotations.useAnnotations.getState().storageError ?? "", /格式或版本无效/);
+    annotations.rememberAnnotationSession("project-a", "session-b");
+    annotations.setAnnotationMode(true);
+    const added = annotations.addAnnotation(input(5));
+    annotations.updateAnnotation(added.id, "still in memory");
+    assert.match(annotations.useAnnotations.getState().storageError ?? "", /原数据已保留/);
+    assert.equal(storage.values.get(storageKey), serialized);
+  }
+  const storage = memoryStorage();
+  storage.values.set(storageKey, "{broken-json");
+  installStorage(storage);
+  const annotations = await reload();
+  assert.match(annotations.useAnnotations.getState().storageError ?? "", /无法读取已保存的批注/);
+  assert.equal(storage.values.get(storageKey), "{broken-json");
+});
+
+test("a storage read failure cannot overwrite previously saved cards after an automatic visit", async () => {
+  const storage = memoryStorage();
+  const saved: DraftAnnotation = { ...input(), id: "saved", revision: 1, createdAt: 1, updatedAt: 2 };
+  const persisted = JSON.stringify({ version: 1, items: [saved], mode: false, recentSessions: {} });
+  storage.values.set(storageKey, persisted);
+  storage.failures.read = new Error("read denied");
+  installStorage(storage);
+  const annotations = await reload();
+  assert.match(annotations.useAnnotations.getState().storageError ?? "", /read denied/);
+  delete storage.failures.read;
+  annotations.rememberAnnotationSession("project-a", "session-a");
+  annotations.setAnnotationMode(true);
+  annotations.addAnnotation(input(1));
+  assert.equal(annotations.useAnnotations.getState().items.length, 1, "new cards still work in memory");
+  assert.match(annotations.useAnnotations.getState().storageError ?? "", /原数据已保留/);
+  assert.equal(storage.values.get(storageKey), persisted);
+});
+
+test("storage write failures are visible while edits remain usable and later saves recover", async () => {
+  const storage = memoryStorage();
+  installStorage(storage);
+  const annotations = await reload();
+  const first = annotations.addAnnotation(input());
+  const persisted = storage.values.get(storageKey);
+  storage.failures.write = new Error("quota exceeded");
+  annotations.updateAnnotation(first.id, "unsaved update");
+  const second = annotations.addAnnotation(input(1));
+  assert.match(annotations.useAnnotations.getState().storageError ?? "", /quota exceeded/);
+  assert.equal(annotations.useAnnotations.getState().items[0].comment, "unsaved update");
+  assert.equal(annotations.useAnnotations.getState().items.length, 2);
+  assert.equal(storage.values.get(storageKey), persisted, "a failed write leaves previously saved data intact");
+  delete storage.failures.write;
+  annotations.setAnnotationMode(true);
+  assert.equal(annotations.useAnnotations.getState().storageError, undefined);
+  const restored = await reload();
+  assert.deepEqual(restored.useAnnotations.getState().items.map((item) => item.id), [first.id, second.id]);
+  assert.equal(restored.useAnnotations.getState().items[0].comment, "unsaved update");
+});
+
+test("storage becoming available never replaces edits made while it was unavailable", async () => {
+  installStorage(undefined);
+  const annotations = await reload();
+  const created = annotations.addAnnotation(input());
+  assert.match(annotations.useAnnotations.getState().storageError ?? "", /浏览器存储不可用/);
+  const storage = memoryStorage();
+  storage.values.set(storageKey, JSON.stringify({ version: 1, items: [], mode: true, recentSessions: {} }));
+  installStorage(storage);
+  annotations.ensureAnnotationsLoaded();
+  assert.deepEqual(annotations.useAnnotations.getState().items, [created]);
+  annotations.setAnnotationMode(true);
+  const restored = await reload();
+  assert.deepEqual(restored.useAnnotations.getState().items, [created]);
+});

package/web/src/annotations.ts

@@ -0,0 +1,191 @@
+import { create } from "zustand";
+
+export type AnnotationSource =
+  | { kind: "file"; path: string; startLine?: number; endLine?: number }
+  | { kind: "message"; sessionId: string; itemKey: string; agentToolUseId?: string };
+
+export type DraftAnnotation = {
+  id: string;
+  projectId: string;
+  targetSessionId: string;
+  source: AnnotationSource;
+  quote: string;
+  comment: string;
+  revision: number;
+  createdAt: number;
+  updatedAt: number;
+};
+
+type AnnotationState = {
+  items: DraftAnnotation[];
+  mode: boolean;
+  recentSessions: Record<string, string>;
+  storageError?: string;
+};
+type SavedAnnotations = Pick<AnnotationState, "items" | "mode" | "recentSessions"> & { version: 1 };
+
+// This namespace deliberately has no relationship to composer drafts or message caches.
+export const ANNOTATIONS_STORAGE_KEY = "cide.annotations.v1";
+export const useAnnotations = create<AnnotationState>(() => ({ items: [], mode: false, recentSessions: {} }));
+let loaded = false;
+let loadFailed = false;
+let fallbackId = 0;
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function nonempty(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+function line(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function source(value: unknown): value is AnnotationSource {
+  if (!record(value)) return false;
+  if (value.kind === "file") {
+    return nonempty(value.path)
+      && (value.startLine === undefined || line(value.startLine))
+      && (value.endLine === undefined || line(value.endLine))
+      && (value.startLine === undefined || value.endLine === undefined || value.endLine >= value.startLine);
+  }
+  return value.kind === "message" && nonempty(value.sessionId) && nonempty(value.itemKey)
+    && (value.agentToolUseId === undefined || nonempty(value.agentToolUseId));
+}
+function annotation(value: unknown): value is DraftAnnotation {
+  return record(value) && nonempty(value.id) && nonempty(value.projectId) && nonempty(value.targetSessionId)
+    && source(value.source) && typeof value.quote === "string" && typeof value.comment === "string"
+    && typeof value.revision === "number" && Number.isSafeInteger(value.revision) && value.revision > 0
+    && typeof value.createdAt === "number" && Number.isFinite(value.createdAt) && value.createdAt >= 0
+    && typeof value.updatedAt === "number" && Number.isFinite(value.updatedAt) && value.updatedAt >= value.createdAt;
+}
+function savedAnnotations(value: unknown): value is SavedAnnotations {
+  if (!record(value) || value.version !== 1 || !Array.isArray(value.items)
+    || !value.items.every(annotation) || typeof value.mode !== "boolean" || !record(value.recentSessions)
+    || !Object.values(value.recentSessions).every(nonempty)) return false;
+  return new Set(value.items.map((item) => item.id)).size === value.items.length;
+}
+function copy(item: DraftAnnotation): DraftAnnotation {
+  return { ...item, source: { ...item.source } };
+}
+function errorMessage(action: "load" | "save", error: unknown): string {
+  const detail = error instanceof Error ? error.message : String(error);
+  return action === "load"
+    ? `无法读取已保存的批注。原数据已保留，本次修改仅保存在内存中。${detail}`
+    : `批注未能保存，当前修改仅保存在内存中。${detail}`;
+}
+
+/** Safe at module import without browser storage; subsequent browser calls hydrate once. */
+export function ensureAnnotationsLoaded(): void {
+  if (loaded) return;
+  try {
+    if (typeof localStorage === "undefined") return;
+    const serialized = localStorage.getItem(ANNOTATIONS_STORAGE_KEY);
+    loaded = true;
+    if (serialized === null) return;
+    const saved: unknown = JSON.parse(serialized);
+    if (!savedAnnotations(saved)) throw new Error("保存的批注数据格式或版本无效。");
+    useAnnotations.setState({
+      items: saved.items.map(copy),
+      mode: saved.mode,
+      recentSessions: { ...saved.recentSessions },
+      storageError: undefined,
+    });
+  } catch (error) {
+    loaded = true;
+    loadFailed = true;
+    useAnnotations.setState({ storageError: errorMessage("load", error) });
+  }
+}
+
+function persist(): void {
+  // Once an edit exists, later storage availability must not overwrite it by hydrating.
+  loaded = true;
+  // A visit can update recents or mode. It must never replace unreadable saved cards.
+  if (loadFailed) return;
+  const { items, mode, recentSessions } = useAnnotations.getState();
+  try {
+    if (typeof localStorage === "undefined") throw new Error("浏览器存储不可用。");
+    const saved: SavedAnnotations = { version: 1, items, mode, recentSessions };
+    localStorage.setItem(ANNOTATIONS_STORAGE_KEY, JSON.stringify(saved));
+    useAnnotations.setState({ storageError: undefined });
+  } catch (error) {
+    // The in-memory edit is retained and the UI can explain why it is not saved.
+    useAnnotations.setState({ storageError: errorMessage("save", error) });
+  }
+}
+
+export function addAnnotation(input: Omit<DraftAnnotation, "id" | "revision" | "createdAt" | "updatedAt">): DraftAnnotation {
+  ensureAnnotationsLoaded();
+  const now = Date.now();
+  const id = globalThis.crypto?.randomUUID?.() ?? `annotation-${now}-${++fallbackId}-${Math.random().toString(36).slice(2)}`;
+  const item: DraftAnnotation = { ...input, source: { ...input.source }, id, revision: 1, createdAt: now, updatedAt: now };
+  useAnnotations.setState((state) => ({ items: [...state.items, item] }));
+  persist();
+  return copy(item);
+}
+
+export function updateAnnotation(id: string, comment: string): void {
+  ensureAnnotationsLoaded();
+  const item = useAnnotations.getState().items.find((candidate) => candidate.id === id);
+  if (!item || item.comment === comment) return;
+  useAnnotations.setState((state) => ({
+    items: state.items.map((candidate) => candidate.id === id
+      ? { ...candidate, comment, revision: candidate.revision + 1, updatedAt: Math.max(Date.now(), candidate.updatedAt) }
+      : candidate),
+  }));
+  persist();
+}
+
+export function deleteAnnotation(id: string): void {
+  ensureAnnotationsLoaded();
+  const items = useAnnotations.getState().items;
+  if (!items.some((item) => item.id === id)) return;
+  useAnnotations.setState({ items: items.filter((item) => item.id !== id) });
+  persist();
+}
+
+export function setAnnotationMode(mode: boolean): void {
+  ensureAnnotationsLoaded();
+  useAnnotations.setState({ mode });
+  persist();
+}
+
+export function rememberAnnotationSession(projectId: string, sessionId: string): void {
+  ensureAnnotationsLoaded();
+  useAnnotations.setState((state) => ({ recentSessions: { ...state.recentSessions, [projectId]: sessionId } }));
+  persist();
+}
+
+/** A detached submission snapshot cannot change while the composer is dispatching. */
+export function snapshotAnnotations(projectId: string, sessionId: string): DraftAnnotation[] {
+  ensureAnnotationsLoaded();
+  return useAnnotations.getState().items
+    .filter((item) => item.projectId === projectId && item.targetSessionId === sessionId)
+    .map(copy);
+}
+
+/** Remove only the submitted revisions; new cards and edits belong to the next send. */
+export function consumeAnnotations(snapshot: readonly DraftAnnotation[]): void {
+  ensureAnnotationsLoaded();
+  const revisions = new Map(snapshot.map((item) => [item.id, item.revision]));
+  const items = useAnnotations.getState().items;
+  const remaining = items.filter((item) => revisions.get(item.id) !== item.revision);
+  if (remaining.length === items.length) return;
+  useAnnotations.setState({ items: remaining });
+  persist();
+}
+
+export function formatAnnotatedMessage(text: string, items: readonly DraftAnnotation[]): string {
+  if (!items.length) return text;
+  const comments = items.map((item) => {
+    // Message keys locate the selection in the client; they are not model context.
+    const heading = item.source.kind === "file" ? `User comments on File ${item.source.path}:` : "User comments:";
+    const quote = item.quote.split("\n").map((line) => `> ${line}`).join("\n");
+    return `${heading}\n${quote}\n\n${item.comment}`;
+  });
+  // The SDK also recognizes leading commands inside ordinary send messages.
+  const normalText = /^[!/]/.test(text.trimStart()) ? `User message:\n${text}` : text;
+  return (normalText ? [normalText, ...comments] : comments).join("\n\n");
+}
+
+ensureAnnotationsLoaded();

package/web/src/api.ts

@@ -0,0 +1,27 @@
+import { invalidateAuth } from "./auth-events.ts";
+
+export class ApiError extends Error {
+  constructor(public status: number, message: string) {
+    super(message);
+  }
+}
+
+/** Shared by JSON requests and multipart uploads, before any response-body parsing. */
+export async function authFetch(path: string, init?: RequestInit): Promise<Response> {
+  const res = await fetch(path, { ...init, credentials: "same-origin" });
+  // A wrong login password is a form error, not the expiry of an existing login.
+  if (res.status === 401 && path.split("?")[0] !== "/api/login") invalidateAuth();
+  return res;
+}
+
+export async function api<T>(path: string, init?: RequestInit & { json?: unknown }): Promise<T> {
+  const { json, ...rest } = init ?? {};
+  const res = await authFetch(path, {
+    ...rest,
+    headers: { ...(json !== undefined ? { "content-type": "application/json" } : {}), ...rest.headers },
+    body: json !== undefined ? JSON.stringify(json) : rest.body,
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new ApiError(res.status, (data as { error?: string }).error ?? res.statusText);
+  return data as T;
+}

package/web/src/auth-events.ts

@@ -0,0 +1,11 @@
+// Transport-independent signal: importing the REST client must not start browser live state.
+const listeners = new Set<() => void>();
+
+export function onAuthInvalidated(listener: () => void) {
+  listeners.add(listener);
+  return () => { listeners.delete(listener); };
+}
+
+export function invalidateAuth() {
+  for (const listener of listeners) listener();
+}

package/web/src/auth-lifecycle.test.ts

@@ -0,0 +1,105 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { api, ApiError, authFetch } from "./api.ts";
+import { invalidateAuth, onAuthInvalidated } from "./auth-events.ts";
+
+test("REST and multipart 401 signal expiry while login errors remain form errors", async () => {
+  const originalFetch = globalThis.fetch;
+  let invalidations = 0;
+  const unsubscribe = onAuthInvalidated(() => { invalidations++; });
+  globalThis.fetch = async () => Response.json({ error: "密码不正确" }, { status: 401 });
+  try {
+    await assert.rejects(api("/api/login", { method: "POST", json: { password: "test-only" } }), (error: unknown) => error instanceof ApiError && error.status === 401 && error.message === "密码不正确");
+    assert.equal(invalidations, 0);
+    await assert.rejects(api("/api/projects"), (error: unknown) => error instanceof ApiError && error.status === 401);
+    assert.equal(invalidations, 1);
+    // Uploads use the same transport; expiry is signalled before parsing any JSON.
+    globalThis.fetch = async () => new Response("unauthorized", { status: 401 });
+    const response = await authFetch("/api/projects/p/files/upload", { method: "POST", body: new FormData() });
+    assert.equal(response.status, 401);
+    assert.equal(invalidations, 2);
+    assert.equal(await response.text(), "unauthorized");
+  } finally { unsubscribe(); globalThis.fetch = originalFetch; }
+});
+
+test("expiry stops reconnects and discards offline and blocked commands before login resumes", async () => {
+  const originalFetch = globalThis.fetch;
+  const originalDocument = Object.getOwnPropertyDescriptor(globalThis, "document");
+  const originalLocation = Object.getOwnPropertyDescriptor(globalThis, "location");
+  const originalSocket = Object.getOwnPropertyDescriptor(globalThis, "WebSocket");
+  const sockets: Socket[] = [];
+  const visibilityListeners: (() => void)[] = [];
+  class Socket {
+    static OPEN = 1;
+    static CONNECTING = 0;
+    readyState = 0;
+    sent: string[] = [];
+    onopen?: () => void;
+    onclose?: (event: { code: number }) => void;
+    constructor(_url: string) { sockets.push(this); }
+    send(message: string) { this.sent.push(message); }
+    open() { this.readyState = 1; this.onopen?.(); }
+    close(code = 1000) { this.readyState = 3; this.onclose?.({ code }); }
+  }
+  Object.defineProperty(globalThis, "document", { configurable: true, value: { querySelector: () => null, visibilityState: "visible", addEventListener: (_type: string, listener: () => void) => visibilityListeners.push(listener) } });
+  Object.defineProperty(globalThis, "location", { configurable: true, value: { protocol: "http:", host: "test.invalid" } });
+  Object.defineProperty(globalThis, "WebSocket", { configurable: true, value: Socket });
+  const { startLive, sendClient, useLive } = await import("./live.ts");
+  const { queryClient } = await import("./queryClient.ts");
+  const command = { t: "interrupt" as const, sessionId: "test-session" };
+  const commands = (socket: Socket) => socket.sent.map((message) => JSON.parse(message)).filter((message) => message.t === "interrupt");
+  try {
+    queryClient.setQueryData(["auth"], { authed: true });
+    startLive();
+    const first = sockets.at(-1)!;
+    first.open();
+    first.close(); // Ordinary network loss schedules a reconnect.
+    sendClient(command); // Queued while offline.
+    globalThis.fetch = async () => Response.json({ error: "unauthorized" }, { status: 401 });
+    await assert.rejects(api("/api/projects"), ApiError);
+    assert.equal(useLive.getState().connected, false);
+    assert.deepEqual(queryClient.getQueryData(["auth"]), { authed: false });
+    sendClient(command); // Must not accumulate after expiry.
+    for (const listener of visibilityListeners) listener();
+    await new Promise((resolve) => setTimeout(resolve, 550));
+    assert.equal(sockets.length, 1, "neither retry timer nor visibility may reconnect");
+
+    startLive(); // A successful login confirmed by App restores live transport.
+    const second = sockets.at(-1)!;
+    second.open();
+    assert.deepEqual(commands(second), [], "REST expiry discarded both old queues");
+    sendClient(command);
+    assert.equal(commands(second).length, 1, "new authenticated commands work");
+    second.close();
+    sendClient(command);
+    startLive();
+    const denied = sockets.at(-1)!;
+    denied.close(4401);
+    sendClient(command);
+    assert.deepEqual(queryClient.getQueryData(["auth"]), { authed: false });
+    const count = sockets.length;
+    for (const listener of visibilityListeners) listener();
+    assert.equal(sockets.length, count);
+    startLive();
+    const restored = sockets.at(-1)!;
+    restored.open();
+    assert.deepEqual(commands(restored), [], "WS expiry discarded both old queues");
+
+    // A REST expiry must also close a currently OPEN socket. Late callbacks are inert.
+    await assert.rejects(api("/api/projects"), ApiError);
+    assert.equal(restored.readyState, 3);
+    const beforeLateCallback = restored.sent.length;
+    restored.onopen?.();
+    restored.onclose?.({ code: 1000 });
+    assert.equal(restored.sent.length, beforeLateCallback);
+    assert.equal(useLive.getState().connected, false);
+  } finally {
+    invalidateAuth();
+    queryClient.clear();
+    globalThis.fetch = originalFetch;
+    for (const [name, descriptor] of [["document", originalDocument], ["location", originalLocation], ["WebSocket", originalSocket]] as const) {
+      if (descriptor) Object.defineProperty(globalThis, name, descriptor);
+      else Reflect.deleteProperty(globalThis, name);
+    }
+  }
+});

package/web/src/clipboard.ts

@@ -0,0 +1,32 @@
+/** Copy text; plain-http LAN pages have no clipboard API, so fall back to a hidden textarea. */
+export async function copyText(text: string): Promise<void> {
+  try {
+    await navigator.clipboard.writeText(text);
+  } catch {
+    const focused = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    const selection = window.getSelection();
+    const ranges = selection ? Array.from({ length: selection.rangeCount }, (_, index) => selection.getRangeAt(index).cloneRange()) : [];
+    const ta = document.createElement("textarea");
+    ta.value = text;
+    ta.readOnly = true;
+    ta.style.position = "fixed";
+    ta.style.top = "0";
+    ta.style.left = "0";
+    ta.style.fontSize = "16px";
+    ta.style.opacity = "0";
+    document.body.appendChild(ta);
+    try {
+      ta.focus({ preventScroll: true });
+      ta.select();
+      ta.setSelectionRange(0, text.length);
+      if (!document.execCommand("copy")) throw new Error("复制失败，请检查浏览器的剪贴板权限或手动复制。");
+    } finally {
+      ta.remove();
+      focused?.focus({ preventScroll: true });
+      if (selection && ranges.every((range) => range.startContainer.isConnected && range.endContainer.isConnected)) {
+        selection.removeAllRanges();
+        ranges.forEach((range) => selection.addRange(range));
+      }
+    }
+  }
+}