@youtyan/code-viewer 0.1.33 → 0.1.35

package/dist/code-viewer.js

@@ -1,115 +1,229 @@
 #!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 
-// web-src/server/preview.ts
+// web-src/server/annotations.ts
 import {
-  closeSync,
-  constants,
-  existsSync as existsSync3,
-  lstatSync as lstatSync4,
+  existsSync,
   mkdirSync,
-  openSync,
-  readFileSync as readFileSync2,
-  realpathSync,
+  readFileSync,
   renameSync,
-  statSync as statSync2,
-  unlinkSync,
-  watch,
   writeFileSync
 } from "node:fs";
-import { homedir } from "node:os";
-import { basename as basename2, dirname as dirname2, extname, join as join5, relative as relative2 } from "node:path";
-
-// web-src/directory-name.ts
-function normalizeNewDirectoryName(name) {
-  if (typeof name !== "string")
+import { join } from "node:path";
+function annotationsFilePath(root) {
+  return join(root, CODE_VIEWER_DIR, ANNOTATIONS_FILE_NAME);
+}
+function emptyAnnotationsState() {
+  return { version: 1, sessions: [] };
+}
+function makeAnnotationId(prefix) {
+  const random = Math.random().toString(36).slice(2, 8);
+  const time = Date.now().toString(36);
+  return `${prefix}-${time}${random}`;
+}
+function normalizeLineRange(raw) {
+  if (!raw || typeof raw !== "object")
+    return;
+  const start = raw.start;
+  const end = raw.end;
+  if (!Number.isInteger(start) || start < 1)
+    return;
+  const endValue = Number.isInteger(end) && end >= start ? end : start;
+  return { start, end: endValue };
+}
+function parseAnnotationLine(raw) {
+  const range = /^(\d+)-(\d+)$/.exec(raw);
+  if (range) {
+    const a = Number(range[1]);
+    const b = Number(range[2]);
+    const start = Math.min(a, b);
+    const end = Math.max(a, b);
+    return start > 0 ? { start, end } : undefined;
+  }
+  const line = Number(raw);
+  return Number.isInteger(line) && line > 0 ? { start: line, end: line } : undefined;
+}
+function normalizeRange(raw) {
+  const from = raw && typeof raw === "object" && typeof raw.from === "string" ? raw.from || "HEAD" : "HEAD";
+  const to = raw && typeof raw === "object" && typeof raw.to === "string" ? raw.to || "worktree" : "worktree";
+  return { from, to };
+}
+function normalizeEntry(raw) {
+  if (!raw || typeof raw !== "object")
     return null;
-  const trimmed = name.trim();
-  if (!trimmed || trimmed.length > 180)
+  const entry = raw;
+  if (typeof entry.id !== "string" || !entry.id)
     return null;
-  if (trimmed.includes("/") || trimmed.includes("\\") || trimmed.includes("\x00") || Array.from(trimmed).some((char) => {
-    const code = char.charCodeAt(0);
-    return code < 32 || code === 127;
-  }))
+  if (typeof entry.path !== "string" || !entry.path)
     return null;
-  if (trimmed === "." || trimmed === ".." || trimmed.toLowerCase() === ".git")
+  if (typeof entry.body !== "string" || !entry.body)
     return null;
-  return trimmed;
-}
-
-// web-src/routes.ts
-var SPA_PATHS = ["/todif", "/todiff", "/file", "/help"];
-var APP_ENTRY_PATHS = ["/", "/index.html"];
-
-// web-src/server/cache.ts
-import { lstatSync } from "node:fs";
-import { join } from "node:path";
-var CACHE_TTL_MS = 1500;
-var MAX_TIMED_CACHE_ENTRIES = 200;
-function cacheFresh(cached, now = Date.now(), ttlMs = CACHE_TTL_MS) {
-  return !!cached && now - cached.storedAt <= ttlMs;
+  const normalized = {
+    id: entry.id,
+    created_at: typeof entry.created_at === "string" ? entry.created_at : "",
+    path: entry.path,
+    range: normalizeRange(entry.range),
+    body: entry.body
+  };
+  const line = normalizeLineRange(entry.line);
+  if (line)
+    normalized.line = line;
+  if (typeof entry.title === "string" && entry.title)
+    normalized.title = entry.title;
+  return normalized;
+}
+function normalizeSession(raw) {
+  if (!raw || typeof raw !== "object")
+    return null;
+  const session = raw;
+  if (typeof session.id !== "string" || !session.id)
+    return null;
+  const entries = Array.isArray(session.entries) ? session.entries.map(normalizeEntry).filter((entry) => entry !== null) : [];
+  return {
+    id: session.id,
+    title: typeof session.title === "string" && session.title ? session.title : "Untitled session",
+    created_at: typeof session.created_at === "string" ? session.created_at : "",
+    entries
+  };
 }
-function setTimedCacheEntry(cache, key, value, now = Date.now(), maxEntries = MAX_TIMED_CACHE_ENTRIES) {
-  cache.set(key, { ...value, storedAt: now });
-  while (cache.size > maxEntries) {
-    const oldest = cache.keys().next().value;
-    if (oldest === undefined)
-      break;
-    cache.delete(oldest);
-  }
+function normalizeAnnotationsState(raw) {
+  if (!raw || typeof raw !== "object")
+    return emptyAnnotationsState();
+  const sessions = raw.sessions;
+  if (!Array.isArray(sessions))
+    return emptyAnnotationsState();
+  return {
+    version: 1,
+    sessions: sessions.map(normalizeSession).filter((session) => session !== null)
+  };
 }
-function worktreeFileSignature(path, cwd) {
+function loadAnnotationsState(root) {
+  const file = annotationsFilePath(root);
+  if (!existsSync(file))
+    return emptyAnnotationsState();
   try {
-    const stats = lstatSync(join(cwd, path));
-    const inode = "ino" in stats ? stats.ino : 0;
-    return `state:file|size:${stats.size}|mtime:${stats.mtimeMs}|ctime:${stats.ctimeMs}|ino:${inode}`;
+    return normalizeAnnotationsState(JSON.parse(readFileSync(file, "utf8")));
   } catch {
-    return "state:missing";
-  }
+    return emptyAnnotationsState();
+  }
+}
+function saveAnnotationsState(root, state) {
+  const dir = join(root, CODE_VIEWER_DIR);
+  mkdirSync(dir, { recursive: true });
+  const file = annotationsFilePath(root);
+  const tmp = `${file}.tmp-${process.pid}`;
+  writeFileSync(tmp, `${JSON.stringify(state, null, 2)}
+`, "utf8");
+  renameSync(tmp, file);
+}
+function startAnnotationSession(state, title, now, id = makeAnnotationId("s")) {
+  const session = {
+    id,
+    title: title.trim().slice(0, ANNOTATION_TITLE_MAX_CHARS) || "Untitled session",
+    created_at: now,
+    entries: []
+  };
+  return {
+    state: { version: 1, sessions: [...state.sessions, session] },
+    session
+  };
 }
-function fileDiffCacheKey(options) {
-  const worktreeTarget = options.range.from === "worktree" || !options.range.to || options.range.to === "worktree";
-  if (options.isUntracked && !worktreeTarget) {
-    throw new Error("untracked file diffs require a worktree range");
+function addAnnotationEntry(state, input, now, makeId = makeAnnotationId) {
+  const path = input.path.replace(/^\/+|\/+$/g, "");
+  if (!path)
+    return { ok: false, error: "path is required" };
+  const body = input.body;
+  if (!body.trim())
+    return { ok: false, error: "body is required" };
+  if (Buffer.byteLength(body, "utf8") > ANNOTATION_BODY_MAX_BYTES)
+    return { ok: false, error: "body is too large" };
+  const line = input.line ? normalizeLineRange(input.line) : undefined;
+  if (input.line && !line)
+    return { ok: false, error: "invalid line" };
+  let sessions = state.sessions;
+  let session;
+  let createdSession = false;
+  if (input.session_id) {
+    session = sessions.find((s) => s.id === input.session_id);
+    if (!session)
+      return { ok: false, error: "session not found" };
+  } else {
+    session = sessions[sessions.length - 1];
   }
-  const signature = worktreeTarget ? `\x00${worktreeFileSignature(options.path, options.cwd)}` : "";
-  if (options.isUntracked) {
-    return `u\x00${options.path}${signature}\x00${options.extras.join("\x00")}`;
+  if (!session) {
+    const started = startAnnotationSession(state, input.session_title || "", now, makeId("s"));
+    sessions = started.state.sessions;
+    session = started.session;
+    createdSession = true;
   }
-  return `t\x00${options.path}\x00${options.oldPath || ""}${signature}\x00${[...options.extras, ...options.args].join("\x00")}`;
+  const entry = {
+    id: makeId("a"),
+    created_at: now,
+    path,
+    range: normalizeRange(input.range),
+    body
+  };
+  if (line)
+    entry.line = line;
+  const title = (input.title || "").trim();
+  if (title)
+    entry.title = title.slice(0, ANNOTATION_TITLE_MAX_CHARS);
+  const updatedSession = {
+    ...session,
+    entries: [...session.entries, entry]
+  };
+  return {
+    ok: true,
+    state: {
+      version: 1,
+      sessions: sessions.map((s) => s.id === updatedSession.id ? updatedSession : s)
+    },
+    session: updatedSession,
+    entry,
+    created_session: createdSession
+  };
 }
-
-// web-src/server/dev-assets.ts
-import { basename } from "node:path";
-function startDevAssetReload(options) {
-  if (!options.enabled)
-    return false;
-  const watched = new Set(options.watchedFiles);
-  const setTimer = options.setTimeoutFn || setTimeout;
-  const clearTimer = options.clearTimeoutFn || clearTimeout;
-  const debounceMs = options.debounceMs ?? 150;
-  let timer = null;
-  options.watch(options.webRoot, { persistent: false }, (_event, filename) => {
-    if (!filename || !watched.has(basename(filename.toString())))
-      return;
-    if (timer)
-      clearTimer(timer);
-    timer = setTimer(() => {
-      timer = null;
-      options.sendReload();
-    }, debounceMs);
-  });
-  return true;
+function deleteAnnotationById(state, id) {
+  for (const session of state.sessions) {
+    if (session.id === id) {
+      return {
+        state: {
+          version: 1,
+          sessions: state.sessions.filter((s) => s.id !== id)
+        },
+        removed: "session"
+      };
+    }
+    if (session.entries.some((entry) => entry.id === id)) {
+      return {
+        state: {
+          version: 1,
+          sessions: state.sessions.map((s) => s.id === session.id ? { ...s, entries: s.entries.filter((e) => e.id !== id) } : s)
+        },
+        removed: "entry"
+      };
+    }
+  }
+  return { state, removed: null };
 }
-
-// web-src/server/git.ts
-import {
-  existsSync,
-  lstatSync as lstatSync2,
-  readdirSync,
-  readFileSync,
-  statSync
-} from "node:fs";
-import { join as join2 } from "node:path";
+var CODE_VIEWER_DIR = ".code-viewer", ANNOTATIONS_FILE_NAME = "annotations.json", ANNOTATION_BODY_MAX_BYTES, ANNOTATION_TITLE_MAX_CHARS = 300;
+var init_annotations = __esm(() => {
+  ANNOTATION_BODY_MAX_BYTES = 64 * 1024;
+});
 
 // web-src/server/runtime.ts
 import { spawn, spawnSync } from "node:child_process";
@@ -275,43 +389,17 @@ async function writeWebResponse(res, response) {
     body.pipe(res);
   });
 }
+var init_runtime = () => {};
 
 // web-src/server/git.ts
-var WORKTREE_RECURSIVE_DEPTH_LIMIT = 32;
-var WORKTREE_RECURSIVE_ENTRY_LIMIT = 50000;
-var DEFAULT_REF_COMMIT_LIMIT = 100;
-var MAX_REF_COMMIT_LIMIT = 500;
-var COMMIT_FORMAT = "%H%x00%s%x00%an%x00%aI";
-var DEFAULT_WORKTREE_OMIT_DIR_NAMES = [
-  "node_modules",
-  ".venv",
-  "venv",
-  ".next",
-  ".nuxt",
-  ".svelte-kit",
-  ".astro",
-  ".vercel",
-  "dist",
-  "build",
-  "out",
-  "target",
-  ".gradle",
-  ".pnpm-store",
-  ".turbo",
-  "__pycache__",
-  ".pytest_cache",
-  ".tox",
-  ".terraform",
-  ".idea",
-  ".vscode",
-  "vendor",
-  ".cache",
-  "coverage",
-  "DerivedData",
-  "Pods",
-  "bin",
-  "obj"
-];
+import {
+  existsSync as existsSync2,
+  lstatSync,
+  readdirSync,
+  readFileSync as readFileSync2,
+  statSync
+} from "node:fs";
+import { join as join2 } from "node:path";
 function run(args, cwd) {
   return runSync(args, cwd);
 }
@@ -583,13 +671,18 @@ function numstatZ(args, cwd) {
   }
   return files;
 }
+function isToolInternalPath(path) {
+  return path.split(/[\\/]+/).some((part) => part.toLowerCase() === ".code-viewer");
+}
 function untracked(cwd, path = "") {
   const args = ["git", "ls-files", "--others", "--exclude-standard"];
   if (path)
     args.push("--", `${path}/`);
   const res = run(args, cwd);
-  return res.code === 0 ? res.stdout.split(`
-`).filter(Boolean) : [];
+  if (res.code !== 0)
+    return [];
+  return res.stdout.split(`
+`).filter(Boolean).filter((entry) => !isToolInternalPath(entry));
 }
 function normalizeTreePath(path) {
   return path.replace(/^\/+|\/+$/g, "");
@@ -607,7 +700,7 @@ function omittedWorktreeDirectoryReason(name, omitDirNames) {
   return omitDirNames.has(name) ? "heavy" : undefined;
 }
 function worktreeEntryFromDirent(base, dir, name, isDirectory, omitDirNames, excludeNames) {
-  if (excludeNames.has(name.toLowerCase()))
+  if (excludeNames.has(name.toLowerCase()) || isToolInternalPath(name))
     return {
       name,
       path: "",
@@ -669,7 +762,7 @@ function worktreeFilesystemEntries(cwd, path, recursive, omitDirNames = DEFAULT_
       return;
     }
     for (const entry of entries) {
-      if (excludeNameSet.has(entry.name.toLowerCase()))
+      if (excludeNameSet.has(entry.name.toLowerCase()) || isToolInternalPath(entry.name))
         continue;
       const entryPath = prefix ? `${prefix}/${entry.name}` : entry.name;
       const full = join2(dir, entry.name);
@@ -704,7 +797,7 @@ function worktreeFilesystemEntries(cwd, path, recursive, omitDirNames = DEFAULT_
 }
 function hasDotGitEntry(dir) {
   try {
-    lstatSync2(join2(dir, ".git"));
+    lstatSync(join2(dir, ".git"));
     return true;
   } catch (err) {
     return !!err && typeof err === "object" && "code" in err && err.code !== "ENOENT";
@@ -774,12 +867,12 @@ function untrackedMeta(cwd) {
     let lines = 0;
     let fileExists = false;
     try {
-      fileExists = existsSync(full) && statSync(full).isFile();
+      fileExists = existsSync2(full) && statSync(full).isFile();
     } catch {
       fileExists = false;
     }
     if (fileExists) {
-      const data = readFileSync(full);
+      const data = readFileSync2(full);
       const probe = data.subarray(0, 8192);
       binary = probe.includes(0);
       if (!binary)
@@ -917,6 +1010,581 @@ function truncateToNHunks(diffText, n, maxLines = Number.POSITIVE_INFINITY) {
     lineTruncated
   };
 }
+var WORKTREE_RECURSIVE_DEPTH_LIMIT = 32, WORKTREE_RECURSIVE_ENTRY_LIMIT = 50000, DEFAULT_REF_COMMIT_LIMIT = 100, MAX_REF_COMMIT_LIMIT = 500, COMMIT_FORMAT = "%H%x00%s%x00%an%x00%aI", DEFAULT_WORKTREE_OMIT_DIR_NAMES;
+var init_git = __esm(() => {
+  init_runtime();
+  DEFAULT_WORKTREE_OMIT_DIR_NAMES = [
+    "node_modules",
+    ".venv",
+    "venv",
+    ".next",
+    ".nuxt",
+    ".svelte-kit",
+    ".astro",
+    ".vercel",
+    "dist",
+    "build",
+    "out",
+    "target",
+    ".gradle",
+    ".pnpm-store",
+    ".turbo",
+    "__pycache__",
+    ".pytest_cache",
+    ".tox",
+    ".terraform",
+    ".idea",
+    ".vscode",
+    "vendor",
+    ".cache",
+    "coverage",
+    "DerivedData",
+    "Pods",
+    "bin",
+    "obj"
+  ];
+});
+
+// web-src/server/server-registry.ts
+import { createHash } from "node:crypto";
+import {
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync3,
+  unlinkSync,
+  writeFileSync as writeFileSync2
+} from "node:fs";
+import { homedir } from "node:os";
+import { join as join3 } from "node:path";
+function registryDir() {
+  return join3(homedir(), ".cache", "code-viewer", "servers");
+}
+function serverRegistryFilePath(root) {
+  const hash = createHash("sha256").update(root).digest("hex").slice(0, 16);
+  return join3(registryDir(), `${hash}.json`);
+}
+function writeServerRegistry(entry) {
+  try {
+    mkdirSync2(registryDir(), { recursive: true });
+    writeFileSync2(serverRegistryFilePath(entry.root), `${JSON.stringify(entry, null, 2)}
+`, "utf8");
+  } catch {}
+}
+function readServerRegistry(root) {
+  const file = serverRegistryFilePath(root);
+  if (!existsSync3(file))
+    return null;
+  try {
+    const raw = JSON.parse(readFileSync3(file, "utf8"));
+    if (!raw || typeof raw !== "object")
+      return null;
+    const entry = raw;
+    if (typeof entry.url !== "string" || !entry.url)
+      return null;
+    return {
+      url: entry.url,
+      pid: typeof entry.pid === "number" ? entry.pid : 0,
+      root: typeof entry.root === "string" ? entry.root : root,
+      started_at: typeof entry.started_at === "string" ? entry.started_at : ""
+    };
+  } catch {
+    return null;
+  }
+}
+function removeServerRegistry(root, pid) {
+  try {
+    const entry = readServerRegistry(root);
+    if (!entry || entry.pid !== pid)
+      return;
+    unlinkSync(serverRegistryFilePath(root));
+  } catch {}
+}
+var init_server_registry = () => {};
+
+// web-src/server/annotate-cli.ts
+var exports_annotate_cli = {};
+__export(exports_annotate_cli, {
+  runAnnotateCli: () => runAnnotateCli,
+  parseAnnotateArgs: () => parseAnnotateArgs,
+  ANNOTATE_HELP: () => ANNOTATE_HELP,
+  ANNOTATE_AGENT_HELP: () => ANNOTATE_AGENT_HELP
+});
+import { readFileSync as readFileSync4, realpathSync } from "node:fs";
+function takeValue(argv, index, flag) {
+  const value = argv[index + 1];
+  if (value === undefined)
+    return { error: `${flag} requires a value` };
+  return { value, next: index + 1 };
+}
+function parseAnnotateArgs(argv) {
+  const rest = [];
+  let cwd;
+  let server;
+  const options = new Map;
+  const flags = new Set;
+  const valueFlags = new Set([
+    "--title",
+    "--file",
+    "--line",
+    "--from",
+    "--to",
+    "--session",
+    "--session-title",
+    "--body",
+    "--body-file"
+  ]);
+  for (let i = 0;i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h")
+      return { ok: true, args: { command: { kind: "help" } } };
+    if (arg === "--cwd" || arg === "--server") {
+      const taken = takeValue(argv, i, arg);
+      if ("error" in taken)
+        return { ok: false, error: taken.error };
+      if (arg === "--cwd")
+        cwd = taken.value;
+      else
+        server = taken.value;
+      i = taken.next;
+    } else if (valueFlags.has(arg)) {
+      const taken = takeValue(argv, i, arg);
+      if ("error" in taken)
+        return { ok: false, error: taken.error };
+      options.set(arg, taken.value);
+      i = taken.next;
+    } else if (arg === "--json") {
+      flags.add(arg);
+    } else if (arg.startsWith("-")) {
+      return { ok: false, error: `unknown option: ${arg}` };
+    } else {
+      rest.push(arg);
+    }
+  }
+  const subcommand = rest[0];
+  if (!subcommand)
+    return { ok: true, args: { command: { kind: "help" } } };
+  if (subcommand === "agent-help") {
+    return { ok: true, args: { command: { kind: "agent-help" } } };
+  }
+  if (subcommand === "start") {
+    return {
+      ok: true,
+      args: {
+        command: { kind: "start", title: options.get("--title") || "" },
+        cwd,
+        server
+      }
+    };
+  }
+  if (subcommand === "add") {
+    const file = options.get("--file");
+    if (!file)
+      return { ok: false, error: "add requires --file <path>" };
+    let line;
+    const rawLine = options.get("--line");
+    if (rawLine !== undefined) {
+      line = parseAnnotationLine(rawLine);
+      if (!line)
+        return { ok: false, error: "--line must be <n> or <n>-<m>" };
+    }
+    const body = options.get("--body");
+    const bodyFile = options.get("--body-file");
+    if (body !== undefined && bodyFile !== undefined)
+      return { ok: false, error: "use either --body or --body-file" };
+    return {
+      ok: true,
+      args: {
+        command: {
+          kind: "add",
+          file,
+          line,
+          from: options.get("--from"),
+          to: options.get("--to"),
+          title: options.get("--title"),
+          session: options.get("--session"),
+          sessionTitle: options.get("--session-title"),
+          body,
+          bodyFile
+        },
+        cwd,
+        server
+      }
+    };
+  }
+  if (subcommand === "list") {
+    return {
+      ok: true,
+      args: {
+        command: { kind: "list", json: flags.has("--json") },
+        cwd,
+        server
+      }
+    };
+  }
+  if (subcommand === "delete") {
+    const id = rest[1];
+    if (!id)
+      return { ok: false, error: "delete requires an id" };
+    return { ok: true, args: { command: { kind: "delete", id }, cwd, server } };
+  }
+  if (subcommand === "clear") {
+    return { ok: true, args: { command: { kind: "clear" }, cwd, server } };
+  }
+  return { ok: false, error: `unknown annotate command: ${subcommand}` };
+}
+async function readStdin() {
+  if (process.stdin.isTTY)
+    return "";
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+function resolveRepoRoot(cwdOption) {
+  const base = cwdOption || process.cwd();
+  try {
+    return repoRoot(base) || realpathSync(base);
+  } catch {
+    console.error(`--cwd must point to an existing directory: ${base}`);
+    process.exit(1);
+  }
+}
+async function serverReachable(serverUrl) {
+  try {
+    const res = await fetch(`${serverUrl}/_annotations`, {
+      signal: AbortSignal.timeout(1500)
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+async function ensureServerUrl(root, override) {
+  if (override) {
+    const url = override.replace(/\/+$/, "");
+    if (await serverReachable(url))
+      return url;
+    console.error(`could not reach the code-viewer server at ${url}.`);
+    process.exit(1);
+  }
+  const registered = readServerRegistry(root);
+  if (registered) {
+    const url = registered.url.replace(/\/+$/, "");
+    if (await serverReachable(url))
+      return url;
+  }
+  console.error(`no running code-viewer server for this repository.
+` + `Start one manually (from ${root}):
+` + "  code-viewer");
+  process.exit(1);
+}
+async function request(serverUrl, method, body) {
+  const url = `${serverUrl}/_annotations`;
+  const origin = new URL(serverUrl).origin;
+  let res;
+  try {
+    res = await fetch(url, {
+      method,
+      headers: method === "POST" ? {
+        "Content-Type": "application/json",
+        Origin: origin,
+        "X-Code-Viewer-Action": "1"
+      } : {},
+      body: body === undefined ? undefined : JSON.stringify(body)
+    });
+  } catch {
+    console.error(`could not reach the code-viewer server at ${serverUrl}.`);
+    process.exit(1);
+  }
+  if (!res.ok) {
+    console.error(`server rejected the request: ${await res.text()}`);
+    process.exit(1);
+  }
+  return res.json();
+}
+function formatLine(line) {
+  if (!line)
+    return "";
+  return line.start === line.end ? `:${line.start}` : `:${line.start}-${line.end}`;
+}
+function printList(state) {
+  if (!state.sessions.length) {
+    console.log("no annotations");
+    return;
+  }
+  for (const session of state.sessions) {
+    console.log(`session ${session.id}  ${session.title}`);
+    session.entries.forEach((entry, index) => {
+      const location = `${entry.path}${formatLine(entry.line)}`;
+      const summary = (entry.title || entry.body).split(`
+`)[0].slice(0, 80);
+      console.log(`  ${index + 1}. [${entry.id}] ${location}  ${summary}`);
+    });
+  }
+}
+async function runAnnotateCli(argv) {
+  const parsed = parseAnnotateArgs(argv);
+  if (parsed.ok === false) {
+    console.error(parsed.error);
+    console.error('Run "code-viewer annotate --help" for usage.');
+    process.exit(1);
+  }
+  const { command, cwd, server } = parsed.args;
+  if (command.kind === "help") {
+    console.log(ANNOTATE_HELP);
+    return;
+  }
+  if (command.kind === "agent-help") {
+    console.log(ANNOTATE_AGENT_HELP);
+    return;
+  }
+  const root = resolveRepoRoot(cwd);
+  const serverUrl = await ensureServerUrl(root, server);
+  if (command.kind === "start") {
+    const result = await request(serverUrl, "POST", {
+      action: "start",
+      title: command.title
+    });
+    console.log(`session ${result.session.id}  ${result.session.title}`);
+    console.error(`view annotations at ${serverUrl}/ with the code annotations panel`);
+    return;
+  }
+  if (command.kind === "add") {
+    let body = command.body;
+    if (body === undefined && command.bodyFile !== undefined) {
+      try {
+        body = readFileSync4(command.bodyFile, "utf8");
+      } catch {
+        console.error(`could not read --body-file: ${command.bodyFile}`);
+        process.exit(1);
+      }
+    }
+    if (body === undefined)
+      body = await readStdin();
+    if (!body.trim()) {
+      console.error("annotation body is empty. Pass --body, --body-file, or pipe stdin.");
+      process.exit(1);
+    }
+    const result = await request(serverUrl, "POST", {
+      action: "add",
+      session_id: command.session,
+      session_title: command.sessionTitle,
+      path: command.file,
+      line: command.line,
+      range: { from: command.from, to: command.to },
+      title: command.title,
+      body
+    });
+    if (result.created_session) {
+      console.error(`created new annotation session ${result.session_id} (${result.session_title || "Untitled session"})`);
+    }
+    console.log(`annotated ${result.entry.path}${formatLine(result.entry.line)} ` + `[${result.entry.id}] in session ${result.session_id} (${result.session_title || "Untitled session"})`);
+    console.error(`view annotations at ${serverUrl}/ with the code annotations panel`);
+    return;
+  }
+  if (command.kind === "list") {
+    const state = await request(serverUrl, "GET");
+    if (command.json)
+      console.log(JSON.stringify(state, null, 2));
+    else
+      printList(state);
+    return;
+  }
+  if (command.kind === "delete") {
+    const result = await request(serverUrl, "POST", {
+      action: "delete",
+      id: command.id
+    });
+    if (!result.removed) {
+      console.error(`no annotation or session with id ${command.id}`);
+      process.exit(1);
+    }
+    console.log(`deleted ${result.removed} ${command.id}`);
+    return;
+  }
+  await request(serverUrl, "POST", { action: "clear" });
+  console.log("cleared all annotations");
+}
+var ANNOTATE_HELP = `code-viewer annotate — attach explanations to code locations
+
+The annotations show up live in the code-viewer browser UI and are stored
+in <repo>/.code-viewer/annotations.json. A running code-viewer server for
+the repository is required: start one with "code-viewer" before using
+annotate (or point at one explicitly with --server).
+
+Run "code-viewer annotate agent-help" for an AI-agent oriented guide
+(workflow, conventions, and pitfalls for writing good walkthroughs).
+
+Usage:
+  code-viewer annotate start [--title <text>]
+  code-viewer annotate add --file <path> [--line <n>|<n>-<m>]
+      [--from <ref>] [--to <ref>] [--title <text>] [--session <id>]
+      [--body <markdown> | --body-file <path>]   (or pipe body via stdin)
+  code-viewer annotate list [--json]
+  code-viewer annotate delete <id>
+  code-viewer annotate clear
+
+Global options:
+  --cwd <dir>      repository to annotate (default: current directory)
+  --server <url>   code-viewer server URL (default: auto-discovered)
+
+Examples:
+  code-viewer annotate start --title "How SSE updates work"
+  code-viewer annotate add --file web-src/server/preview.ts --line 2220-2250 \\
+      --body "This endpoint keeps one SSE stream per browser tab."
+  git diff HEAD~1 | code-viewer annotate add --file src/app.ts --line 10 \\
+      --from HEAD~1 --to worktree --body "The fix moves the guard up here."
+`, ANNOTATE_AGENT_HELP = `code-viewer annotate — agent guide
+
+You are an AI coding agent. Use this tool to walk a human through code in
+their browser: each annotation jumps every open code-viewer tab to a file
+location and renders your explanation directly under the annotated lines.
+
+## When to use
+
+- Explaining a change you just made (per-file, per-hunk commentary)
+- Guiding a code review: point at the risky lines, in reading order
+- Onboarding walkthroughs: "how does feature X flow through the code"
+
+## Requirements
+
+- A code-viewer server must already be running for the repository
+  (the human starts it with: code-viewer). This command never starts one.
+- Run from inside the repository, or pass --cwd <repo>.
+- If "code-viewer" is not on PATH (e.g. the human runs it via npx), invoke
+  every command below as: npx -y @youtyan/code-viewer annotate ...
+
+## Workflow
+
+1. Start a session per walkthrough topic. The title is shown to the human:
+     code-viewer annotate start --title "How the cache invalidation works"
+2. Add annotations in READING ORDER (the order you want the human to
+   follow). Each add without --session appends to the most recent session:
+     code-viewer annotate add --file src/cache.ts --line 120-145 \\
+         --title "Entry point" --body "Writes land here first. ..."
+3. Verify what you posted:
+     code-viewer annotate list
+
+## Conventions for good walkthroughs
+
+- One idea per annotation. Prefer 5-10 focused annotations over 2 huge ones.
+- Always pass --line. Use the smallest range that covers the idea; the
+  body is rendered inline directly under the LAST line of the range.
+- Line numbers must match the "to" side of the range (default: the current
+  worktree state of the file). When annotating a diff against another ref,
+  pass --from/--to and use NEW-side line numbers.
+- The body is Markdown. Code spans, fenced blocks, and links work. Long
+  bodies: use --body-file <path> or pipe via stdin instead of --body.
+- Give every annotation a short --title; it becomes the inline heading.
+- Annotating unchanged code is fine: the viewer auto-expands diff context
+  or falls back to the full source view.
+
+## Sessions
+
+- add (no --session) → appends to the most recent session.
+- annotate start      → begins a NEW session; later adds go there.
+- add --session <id>  → targets a specific session (ids: annotate list).
+- The human can share a walkthrough as a URL; one session = one shareable
+  walkthrough. Do not mix unrelated topics in one session.
+
+## Cleanup
+
+- delete <id> removes one annotation or a whole session by its id.
+- clear removes everything. Ask the human before clearing state you did
+  not create.
+`;
+var init_annotate_cli = __esm(() => {
+  init_annotations();
+  init_git();
+  init_server_registry();
+});
+
+// web-src/directory-name.ts
+function normalizeNewDirectoryName(name) {
+  if (typeof name !== "string")
+    return null;
+  const trimmed = name.trim();
+  if (!trimmed || trimmed.length > 180)
+    return null;
+  if (trimmed.includes("/") || trimmed.includes("\\") || trimmed.includes("\x00") || Array.from(trimmed).some((char) => {
+    const code = char.charCodeAt(0);
+    return code < 32 || code === 127;
+  }))
+    return null;
+  if (trimmed === "." || trimmed === ".." || trimmed.toLowerCase() === ".git")
+    return null;
+  return trimmed;
+}
+
+// web-src/routes.ts
+var SPA_PATHS, APP_ENTRY_PATHS;
+var init_routes = __esm(() => {
+  SPA_PATHS = ["/todif", "/todiff", "/file", "/help"];
+  APP_ENTRY_PATHS = ["/", "/index.html"];
+});
+
+// web-src/server/cache.ts
+import { lstatSync as lstatSync2 } from "node:fs";
+import { join as join4 } from "node:path";
+function cacheFresh(cached, now = Date.now(), ttlMs = CACHE_TTL_MS) {
+  return !!cached && now - cached.storedAt <= ttlMs;
+}
+function setTimedCacheEntry(cache, key, value, now = Date.now(), maxEntries = MAX_TIMED_CACHE_ENTRIES) {
+  cache.set(key, { ...value, storedAt: now });
+  while (cache.size > maxEntries) {
+    const oldest = cache.keys().next().value;
+    if (oldest === undefined)
+      break;
+    cache.delete(oldest);
+  }
+}
+function worktreeFileSignature(path, cwd) {
+  try {
+    const stats = lstatSync2(join4(cwd, path));
+    const inode = "ino" in stats ? stats.ino : 0;
+    return `state:file|size:${stats.size}|mtime:${stats.mtimeMs}|ctime:${stats.ctimeMs}|ino:${inode}`;
+  } catch {
+    return "state:missing";
+  }
+}
+function fileDiffCacheKey(options) {
+  const worktreeTarget = options.range.from === "worktree" || !options.range.to || options.range.to === "worktree";
+  if (options.isUntracked && !worktreeTarget) {
+    throw new Error("untracked file diffs require a worktree range");
+  }
+  const signature = worktreeTarget ? `\x00${worktreeFileSignature(options.path, options.cwd)}` : "";
+  if (options.isUntracked) {
+    return `u\x00${options.path}${signature}\x00${options.extras.join("\x00")}`;
+  }
+  return `t\x00${options.path}\x00${options.oldPath || ""}${signature}\x00${[...options.extras, ...options.args].join("\x00")}`;
+}
+var CACHE_TTL_MS = 1500, MAX_TIMED_CACHE_ENTRIES = 200;
+var init_cache = () => {};
+
+// web-src/server/dev-assets.ts
+import { basename } from "node:path";
+function startDevAssetReload(options) {
+  if (!options.enabled)
+    return false;
+  const watched = new Set(options.watchedFiles);
+  const setTimer = options.setTimeoutFn || setTimeout;
+  const clearTimer = options.clearTimeoutFn || clearTimeout;
+  const debounceMs = options.debounceMs ?? 150;
+  let timer = null;
+  options.watch(options.webRoot, { persistent: false }, (_event, filename) => {
+    if (!filename || !watched.has(basename(filename.toString())))
+      return;
+    if (timer)
+      clearTimer(timer);
+    timer = setTimer(() => {
+      timer = null;
+      options.sendReload();
+    }, debounceMs);
+  });
+  return true;
+}
+var init_dev_assets = () => {};
 
 // web-src/server/range.ts
 function isSameWorktreeRange(range) {
@@ -1130,13 +1798,13 @@ function collectLineRangeFromIndexedText(text, index, start, end) {
 }
 
 // web-src/server/root.ts
-import { existsSync as existsSync2 } from "node:fs";
-import { dirname, join as join3, normalize } from "node:path";
+import { existsSync as existsSync4 } from "node:fs";
+import { dirname, join as join5, normalize } from "node:path";
 import { fileURLToPath } from "node:url";
 function findRoot(start) {
   let current = start;
   for (let i = 0;i < 5; i++) {
-    if (existsSync2(join3(current, "package.json")) && existsSync2(join3(current, "web"))) {
+    if (existsSync4(join5(current, "package.json")) && existsSync4(join5(current, "web"))) {
       return normalize(current);
     }
     const parent = dirname(current);
@@ -1144,16 +1812,14 @@ function findRoot(start) {
       break;
     current = parent;
   }
-  return normalize(join3(start, "..", ".."));
+  return normalize(join5(start, "..", ".."));
 }
-var ROOT = findRoot(dirname(fileURLToPath(import.meta.url)));
+var ROOT;
+var init_root = __esm(() => {
+  ROOT = findRoot(dirname(fileURLToPath(import.meta.url)));
+});
 
 // web-src/server/search.ts
-var GREP_DEFAULT_MAX = 200;
-var GREP_ABSOLUTE_MAX = 500;
-var GREP_MAX_FILE_BYTES = 2 * 1024 * 1024;
-var FILE_SEARCH_ABSOLUTE_MAX = 50000;
-var DEFAULT_EXCLUDE_NAMES = [".DS_Store"];
 function normalizeGrepMax(value) {
   const parsed = Number(value || "");
   if (!Number.isInteger(parsed) || parsed <= 0)
@@ -1165,7 +1831,7 @@ function isSkippableSearchPath(path, omitDirNames = [], excludeNames = []) {
   const excluded = new Set(excludeNames.map((name) => name.toLowerCase()));
   return path.split(/[\\/]+/).some((part) => {
     const lower = part.toLowerCase();
-    return lower === ".git" || omitDirs.has(lower) || excluded.has(lower);
+    return lower === ".git" || lower === ".code-viewer" || omitDirs.has(lower) || excluded.has(lower);
   });
 }
 function fixedStringLineMatches(path, text, query, max) {
@@ -1267,6 +1933,11 @@ function parseGitGrepOutput(stdout, ref, max, omitDirNames = [], excludeNames =
 `);
   return parseRgOutput(normalized, max, omitDirNames, excludeNames);
 }
+var GREP_DEFAULT_MAX = 200, GREP_ABSOLUTE_MAX = 500, GREP_MAX_FILE_BYTES, FILE_SEARCH_ABSOLUTE_MAX = 50000, DEFAULT_EXCLUDE_NAMES;
+var init_search = __esm(() => {
+  GREP_MAX_FILE_BYTES = 2 * 1024 * 1024;
+  DEFAULT_EXCLUDE_NAMES = [".DS_Store"];
+});
 
 // web-src/server/worktree-watcher.ts
 import {
@@ -1274,7 +1945,7 @@ import {
   readdirSync as nodeReaddirSync,
   watch as nodeWatch
 } from "node:fs";
-import { join as join4, relative } from "node:path";
+import { join as join6, relative } from "node:path";
 function normalizeRelativePath(path) {
   return path.replace(/\\/g, "/").replace(/^\/+/, "");
 }
@@ -1357,7 +2028,7 @@ function startWorktreeUpdateWatch(options) {
     for (const entry of entries) {
       if (!entry.isDirectory())
         continue;
-      children.push(join4(dir, entry.name));
+      children.push(join6(dir, entry.name));
     }
     return children;
   };
@@ -1386,10 +2057,10 @@ function startWorktreeUpdateWatch(options) {
           scheduleUpdate();
           return;
         }
-        const changed = normalizeRelativePath(join4(rel, filename.toString()));
+        const changed = normalizeRelativePath(join6(rel, filename.toString()));
         if (ignored(changed))
           return;
-        const fullChangedPath = join4(options.root, changed);
+        const fullChangedPath = join6(options.root, changed);
         if (!isInsideRoot(options.root, fullChangedPath))
           return;
         const known = watchers.has(fullChangedPath);
@@ -1439,79 +2110,29 @@ function startWorktreeUpdateWatch(options) {
   watchDirectory(options.root, true);
   return { started: watchers.size > 0, close: closeAll };
 }
+var init_worktree_watcher = __esm(() => {
+  init_search();
+});
 
 // web-src/server/preview.ts
-var WEB_ROOT = join5(ROOT, "web");
-var VERSION = JSON.parse(readFileSync2(join5(ROOT, "package.json"), "utf8")).version;
-var DEFAULT_ARGS = ["HEAD"];
-var PREVIEW_HUNKS_DEFAULT = 3;
-var PREVIEW_LINES_DEFAULT = 1200;
-var WATCHED_ASSET_FILES = ["index.html", "style.css", "app.js"];
-var SIZE_SMALL = 2000;
-var SIZE_MEDIUM = 8000;
-var SIZE_LARGE = 20000;
-var LINE_INDEX_MIN_START = 1e4;
-var LINE_INDEX_MAX_FILE_BYTES = 256 * 1024 * 1024;
-var BLOB_LINE_CACHE_MAX_BYTES = 128 * 1024 * 1024;
-var MAX_UPLOAD_FILE_BYTES = 512 * 1024 * 1024;
-var MAX_UPLOAD_TOTAL_BYTES = 1024 * 1024 * 1024;
-var MAX_UPLOAD_BODY_BYTES = MAX_UPLOAD_TOTAL_BYTES + 1024 * 1024;
-var MAX_UPLOAD_FILES = 50;
-var SAFE_UPLOAD_EXTENSIONS = new Set([
-  ".txt",
-  ".md",
-  ".markdown",
-  ".json",
-  ".csv",
-  ".tsv",
-  ".yaml",
-  ".yml",
-  ".toml",
-  ".png",
-  ".jpg",
-  ".jpeg",
-  ".gif",
-  ".webp",
-  ".svg",
-  ".pdf",
-  ".mp4",
-  ".mov",
-  ".m4v",
-  ".webm",
-  ".mp3",
-  ".wav",
-  ".m4a",
-  ".aac",
-  ".flac",
-  ".ogg",
-  ".zip",
-  ".ts",
-  ".tsx",
-  ".js",
-  ".jsx",
-  ".css",
-  ".scss",
-  ".html"
-]);
-var generation = 1;
-var cwd = repoRoot(process.cwd()) || process.cwd();
-var cliArgs = DEFAULT_ARGS;
-var listenPort = 0;
-var openAfterStart = false;
-var scopeOmitDirNames = DEFAULT_WORKTREE_OMIT_DIR_NAMES;
-var scopeOmitDirCliOverride = null;
-var scopeExcludeNames = DEFAULT_EXCLUDE_NAMES;
-var uploadDisabledByConfig = false;
-var rgAvailableCache = null;
-var enc = new TextEncoder;
-var sseClients = new Set;
-var fileCache = new Map;
-var metaCache = new Map;
-var fileListCache = new Map;
-var lineIndexCache = new Map;
-var blobLineIndexCache = new Map;
-var blobBytesCache = new Map;
-var blobLineCacheBytes = 0;
+var exports_preview = {};
+import {
+  closeSync,
+  constants,
+  existsSync as existsSync5,
+  lstatSync as lstatSync4,
+  mkdirSync as mkdirSync3,
+  openSync,
+  readFileSync as readFileSync5,
+  realpathSync as realpathSync2,
+  renameSync as renameSync2,
+  statSync as statSync2,
+  unlinkSync as unlinkSync2,
+  watch,
+  writeFileSync as writeFileSync3
+} from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { basename as basename2, dirname as dirname2, extname, join as join7, relative as relative2 } from "node:path";
 function parseCli() {
   const rest = [];
   for (let i = 2;i < process.argv.length; i++) {
@@ -1521,12 +2142,14 @@ function parseCli() {
 
 Usage:
   code-viewer [--cwd <repo>] [--port <port>] [--open] [git-diff-args...]
+  code-viewer annotate <start|add|list|delete|clear> [options]
 
 Examples:
   code-viewer --open
   code-viewer --cwd /path/to/repo --open
   code-viewer HEAD~1 HEAD
   code-viewer --staged
+  code-viewer annotate --help
 `);
       process.exit(0);
     } else if (arg === "--version" || arg === "-v") {
@@ -1539,7 +2162,7 @@ Examples:
         process.exit(1);
       }
       try {
-        cwd = repoRoot(next) || realpathSync(next);
+        cwd = repoRoot(next) || realpathSync2(next);
       } catch {
         console.error("--cwd must point to an existing directory");
         process.exit(1);
@@ -1648,10 +2271,10 @@ function staticFile(pathname) {
   const spec = map[pathname];
   if (!spec)
     return null;
-  const full = join5(WEB_ROOT, spec[0]);
-  if (!existsSync3(full))
+  const full = join7(WEB_ROOT, spec[0]);
+  if (!existsSync5(full))
     return text("not found", 404);
-  return new Response(readFileSync2(full), {
+  return new Response(readFileSync5(full), {
     headers: { "Content-Type": spec[1], "Cache-Control": "no-store" }
   });
 }
@@ -1882,21 +2505,21 @@ function parseScopeExcludeNamesQuery(value) {
   return normalizeScopeExcludeNames(names);
 }
 function loadProjectConfig() {
-  const full = join5(cwd, ".code-viewer.json");
-  if (!existsSync3(full))
+  const full = join7(cwd, ".code-viewer.json");
+  if (!existsSync5(full))
     return null;
   let realCwd;
   let realConfig;
   try {
-    realCwd = realpathSync(cwd);
-    realConfig = realpathSync(full);
+    realCwd = realpathSync2(cwd);
+    realConfig = realpathSync2(full);
   } catch {
     return null;
   }
   if (dirname2(realConfig) !== realCwd || basename2(realConfig) !== ".code-viewer.json")
     return null;
   try {
-    const parsed = JSON.parse(readFileSync2(realConfig, "utf8"));
+    const parsed = JSON.parse(readFileSync5(realConfig, "utf8"));
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed) && "version" in parsed && parsed.version !== 1)
       return null;
     return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
@@ -1947,14 +2570,14 @@ function safeWorktreePath(path) {
     return null;
   if (isGitInternalPath(path))
     return null;
-  const full = join5(cwd, path);
-  if (!existsSync3(full))
+  const full = join7(cwd, path);
+  if (!existsSync5(full))
     return null;
   let realCwd;
   let realFull;
   try {
-    realCwd = realpathSync(cwd);
-    realFull = realpathSync(full);
+    realCwd = realpathSync2(cwd);
+    realFull = realpathSync2(full);
   } catch {
     return null;
   }
@@ -1966,12 +2589,12 @@ function safeWorktreePath(path) {
   return realFull;
 }
 function worktreePath(path) {
-  return join5(cwd, path);
+  return join7(cwd, path);
 }
 function safeOpenWorktreePath(path) {
   if (path === "") {
     try {
-      const realCwd = realpathSync(cwd);
+      const realCwd = realpathSync2(cwd);
       if (isGitInternalPath(realCwd))
         return null;
       return realCwd;
@@ -2059,7 +2682,7 @@ function readReadme(target, dirPath) {
       if (!full)
         continue;
       try {
-        return { path, text: readFileSync2(full, "utf8") };
+        return { path, text: readFileSync5(full, "utf8") };
       } catch {
         continue;
       }
@@ -2171,7 +2794,7 @@ function grepWorktreeFallback(query, max, paths, omitDirNames, excludeNames) {
       continue;
     let data;
     try {
-      data = readFileSync2(full);
+      data = readFileSync5(full);
     } catch {
       continue;
     }
@@ -2729,10 +3352,10 @@ async function handleUploadFiles(req) {
     total += file.size;
     if (total > MAX_UPLOAD_TOTAL_BYTES)
       return text("upload too large", 413);
-    const target = join5(realDir, safeName);
+    const target = join7(realDir, safeName);
     if (relative2(realDir, dirname2(target)) !== "")
       return text("invalid filename", 400);
-    if (existsSync3(target))
+    if (existsSync5(target))
       return text("file exists", 409);
     uploads.push({ file, name: safeName, target });
   }
@@ -2741,7 +3364,7 @@ async function handleUploadFiles(req) {
     for (const upload of uploads) {
       const fd = openSync(upload.target, uploadOpenFlags(), 420);
       try {
-        writeFileSync(fd, new Uint8Array(await upload.file.arrayBuffer()));
+        writeFileSync3(fd, new Uint8Array(await upload.file.arrayBuffer()));
       } finally {
         closeSync(fd);
       }
@@ -2750,7 +3373,7 @@ async function handleUploadFiles(req) {
   } catch (error) {
     for (const path of written) {
       try {
-        unlinkSync(path);
+        unlinkSync2(path);
       } catch {}
     }
     if (error.code === "EEXIST")
@@ -2850,12 +3473,12 @@ function triggerUpdate() {
   sendSse("update");
 }
 function moveMacPathIntoTrash(path) {
-  const trashDir = join5(homedir(), ".Trash");
+  const trashDir = join7(homedir2(), ".Trash");
   const base = basename2(path) || "code-viewer-trash-item";
-  const target = join5(trashDir, `${base}-${Date.now()}-${process.pid}-${Math.random().toString(36).slice(2, 8)}`);
+  const target = join7(trashDir, `${base}-${Date.now()}-${process.pid}-${Math.random().toString(36).slice(2, 8)}`);
   try {
-    mkdirSync(trashDir, { recursive: true });
-    renameSync(path, target);
+    mkdirSync3(trashDir, { recursive: true });
+    renameSync2(path, target);
     return { ok: true, trashPath: target };
   } catch (error) {
     return { ok: false, error: String(error) };
@@ -2886,20 +3509,20 @@ function restoreTrashPath(originalPath, trashPath) {
   if (!parentFullPath)
     return { ok: false, error: "invalid restore target" };
   const original = worktreePath(originalPath);
-  if (existsSync3(original))
+  if (existsSync5(original))
     return { ok: false, error: "restore target exists" };
   if (trashPath) {
     if (process.platform !== "darwin")
       return { ok: false, error: "invalid trash handle" };
-    if (!existsSync3(trashPath))
+    if (!existsSync5(trashPath))
       return { ok: false, error: "trash item not found" };
     try {
-      const trashRoot = join5(homedir(), ".Trash");
+      const trashRoot = join7(homedir2(), ".Trash");
       const trashRelative = relative2(trashRoot, trashPath);
       if (trashRelative === "" || trashRelative.startsWith("..") || trashRelative.startsWith("/") || trashRelative.startsWith("\\"))
         return { ok: false, error: "invalid trash handle" };
-      mkdirSync(dirname2(original), { recursive: true });
-      renameSync(trashPath, original);
+      mkdirSync3(dirname2(original), { recursive: true });
+      renameSync2(trashPath, original);
       return { ok: true };
     } catch (error) {
       return { ok: false, error: String(error) };
@@ -3044,11 +3667,11 @@ async function handleCreateDirectory(req) {
   const targetPath = dir ? `${dir}/${name}` : name;
   if (!safeRepoPath(targetPath) || isGitInternalPath(targetPath))
     return text("invalid target", 400);
-  const target = join5(parent, name);
-  if (existsSync3(target))
+  const target = join7(parent, name);
+  if (existsSync5(target))
     return text("already exists", 409);
   try {
-    mkdirSync(target, { recursive: false });
+    mkdirSync3(target, { recursive: false });
   } catch (error) {
     if (error.code === "EEXIST")
       return text("already exists", 409);
@@ -3089,6 +3712,88 @@ async function handleRestoreTrash(req) {
   triggerUpdate();
   return json({ ok: true, generation });
 }
+function annotationSse(kind, sessionId, entryId) {
+  sendSse("annotation", JSON.stringify({ kind, session_id: sessionId, entry_id: entryId }));
+}
+async function handleAnnotations(req) {
+  if (req.method === "GET")
+    return json(loadAnnotationsState(cwd));
+  if (req.method !== "POST")
+    return text("method not allowed", 405);
+  if (!sideEffectRequestAllowed(req))
+    return text("forbidden", 403);
+  const contentType = req.headers.get("content-type") || "";
+  if (!/^application\/json(?:;|$)/i.test(contentType))
+    return text("unsupported media type", 415);
+  const maxBytes = ANNOTATION_BODY_MAX_BYTES + 4096;
+  const length = Number(req.headers.get("content-length") || "0");
+  if (length > maxBytes)
+    return text("payload too large", 413);
+  let body = {};
+  try {
+    const raw = await req.text();
+    if (raw.length > maxBytes)
+      return text("payload too large", 413);
+    body = JSON.parse(raw);
+  } catch {
+    return text("invalid json", 400);
+  }
+  const action = body.action;
+  if (action === "start") {
+    const title = typeof body.title === "string" ? body.title : "";
+    const started = startAnnotationSession(loadAnnotationsState(cwd), title, new Date().toISOString());
+    saveAnnotationsState(cwd, started.state);
+    annotationSse("start", started.session.id);
+    return json({ ok: true, session: started.session });
+  }
+  if (action === "add") {
+    const path = typeof body.path === "string" ? body.path.replace(/^\/+|\/+$/g, "") : "";
+    if (!path || !safeRepoPath(path))
+      return text("invalid path", 400);
+    if (isGitInternalPath(path) || isCodeViewerInternalPath(path))
+      return text("forbidden", 403);
+    const result = addAnnotationEntry(loadAnnotationsState(cwd), {
+      session_id: typeof body.session_id === "string" ? body.session_id : undefined,
+      session_title: typeof body.session_title === "string" ? body.session_title : undefined,
+      path,
+      line: body.line && typeof body.line === "object" ? body.line : undefined,
+      range: body.range && typeof body.range === "object" ? body.range : undefined,
+      title: typeof body.title === "string" ? body.title : undefined,
+      body: typeof body.body === "string" ? body.body : ""
+    }, new Date().toISOString());
+    if (result.ok === false)
+      return text(result.error, 400);
+    saveAnnotationsState(cwd, result.state);
+    annotationSse("add", result.session.id, result.entry.id);
+    return json({
+      ok: true,
+      session_id: result.session.id,
+      session_title: result.session.title,
+      created_session: result.created_session,
+      entry: result.entry
+    });
+  }
+  if (action === "delete") {
+    const id = typeof body.id === "string" ? body.id : "";
+    if (!id)
+      return text("invalid id", 400);
+    const result = deleteAnnotationById(loadAnnotationsState(cwd), id);
+    if (result.removed) {
+      saveAnnotationsState(cwd, result.state);
+      annotationSse("delete");
+    }
+    return json({ ok: true, removed: result.removed });
+  }
+  if (action === "clear") {
+    saveAnnotationsState(cwd, emptyAnnotationsState());
+    annotationSse("clear");
+    return json({ ok: true });
+  }
+  return text("invalid action", 400);
+}
+function isCodeViewerInternalPath(path) {
+  return path.split(/[\\/]+/).some((part) => part.toLowerCase() === ".code-viewer");
+}
 function sendSse(event, data = "tick") {
   const payload = enc.encode(`event: ${event}
 data: ${data}
@@ -3106,112 +3811,205 @@ function openBrowser(url) {
   const cmd = process.platform === "darwin" ? ["open", url] : process.platform === "win32" ? ["cmd.exe", "/c", "start", "", url] : ["xdg-open", url];
   spawnDetached(cmd);
 }
-parseCli();
-var server = await startServer({
-  hostname: "127.0.0.1",
-  port: listenPort,
-  async fetch(req) {
-    if (!requestAllowed(req))
-      return text("forbidden", 403);
-    const url = new URL(req.url);
-    const staticResponse = staticFile(url.pathname);
-    if (staticResponse)
-      return staticResponse;
-    if (url.pathname === "/diff.json")
-      return handleDiffJson(url);
-    if (url.pathname === "/_settings")
-      return handleSettings();
-    if (url.pathname === "/_tree")
-      return handleTree(url);
-    if (url.pathname === "/_files")
-      return handleFiles(url);
-    if (url.pathname === "/_grep")
-      return handleGrep(url);
-    if (url.pathname === "/_commits")
-      return handleRefCommits(url);
-    if (url.pathname === "/file_diff")
-      return handleFileDiff(url);
-    if (url.pathname === "/file_range")
-      return handleFileRange(url);
-    if (url.pathname === "/_file")
-      return handleRawFile(req, url);
-    if (url.pathname === "/_open_path")
-      return handleOpenPath(req);
-    if (url.pathname === "/_trash_path")
-      return handleTrashPath(req);
-    if (url.pathname === "/_restore_trash")
-      return handleRestoreTrash(req);
-    if (url.pathname === "/_create_directory")
-      return handleCreateDirectory(req);
-    if (url.pathname === "/_upload_files")
-      return handleUploadFiles(req);
-    if (url.pathname === "/_refs")
-      return json(refs(cwd));
-    if (url.pathname === "/refresh" && req.method === "POST") {
-      if (!sideEffectRequestAllowed(req))
+var WEB_ROOT, VERSION, DEFAULT_ARGS, PREVIEW_HUNKS_DEFAULT = 3, PREVIEW_LINES_DEFAULT = 1200, WATCHED_ASSET_FILES, SIZE_SMALL = 2000, SIZE_MEDIUM = 8000, SIZE_LARGE = 20000, LINE_INDEX_MIN_START = 1e4, LINE_INDEX_MAX_FILE_BYTES, BLOB_LINE_CACHE_MAX_BYTES, MAX_UPLOAD_FILE_BYTES, MAX_UPLOAD_TOTAL_BYTES, MAX_UPLOAD_BODY_BYTES, MAX_UPLOAD_FILES = 50, SAFE_UPLOAD_EXTENSIONS, generation = 1, cwd, cliArgs, listenPort = 0, openAfterStart = false, scopeOmitDirNames, scopeOmitDirCliOverride = null, scopeExcludeNames, uploadDisabledByConfig = false, rgAvailableCache = null, enc, sseClients, fileCache, metaCache, fileListCache, lineIndexCache, blobLineIndexCache, blobBytesCache, blobLineCacheBytes = 0, server;
+var init_preview = __esm(async () => {
+  init_routes();
+  init_annotations();
+  init_cache();
+  init_dev_assets();
+  init_git();
+  init_root();
+  init_runtime();
+  init_search();
+  init_server_registry();
+  init_worktree_watcher();
+  WEB_ROOT = join7(ROOT, "web");
+  VERSION = JSON.parse(readFileSync5(join7(ROOT, "package.json"), "utf8")).version;
+  DEFAULT_ARGS = ["HEAD"];
+  WATCHED_ASSET_FILES = ["index.html", "style.css", "app.js"];
+  LINE_INDEX_MAX_FILE_BYTES = 256 * 1024 * 1024;
+  BLOB_LINE_CACHE_MAX_BYTES = 128 * 1024 * 1024;
+  MAX_UPLOAD_FILE_BYTES = 512 * 1024 * 1024;
+  MAX_UPLOAD_TOTAL_BYTES = 1024 * 1024 * 1024;
+  MAX_UPLOAD_BODY_BYTES = MAX_UPLOAD_TOTAL_BYTES + 1024 * 1024;
+  SAFE_UPLOAD_EXTENSIONS = new Set([
+    ".txt",
+    ".md",
+    ".markdown",
+    ".json",
+    ".csv",
+    ".tsv",
+    ".yaml",
+    ".yml",
+    ".toml",
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".webp",
+    ".svg",
+    ".pdf",
+    ".mp4",
+    ".mov",
+    ".m4v",
+    ".webm",
+    ".mp3",
+    ".wav",
+    ".m4a",
+    ".aac",
+    ".flac",
+    ".ogg",
+    ".zip",
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".css",
+    ".scss",
+    ".html"
+  ]);
+  cwd = repoRoot(process.cwd()) || process.cwd();
+  cliArgs = DEFAULT_ARGS;
+  scopeOmitDirNames = DEFAULT_WORKTREE_OMIT_DIR_NAMES;
+  scopeExcludeNames = DEFAULT_EXCLUDE_NAMES;
+  enc = new TextEncoder;
+  sseClients = new Set;
+  fileCache = new Map;
+  metaCache = new Map;
+  fileListCache = new Map;
+  lineIndexCache = new Map;
+  blobLineIndexCache = new Map;
+  blobBytesCache = new Map;
+  parseCli();
+  server = await startServer({
+    hostname: "127.0.0.1",
+    port: listenPort,
+    async fetch(req) {
+      if (!requestAllowed(req))
         return text("forbidden", 403);
-      triggerUpdate();
-      return json({ ok: true, generation });
-    }
-    if (url.pathname === "/events") {
-      let ctrl;
-      let keepalive;
-      return new Response(new ReadableStream({
-        start(controller) {
-          ctrl = controller;
-          sseClients.add(controller);
-          controller.enqueue(enc.encode(`event: open
+      const url = new URL(req.url);
+      const staticResponse = staticFile(url.pathname);
+      if (staticResponse)
+        return staticResponse;
+      if (url.pathname === "/diff.json")
+        return handleDiffJson(url);
+      if (url.pathname === "/_settings")
+        return handleSettings();
+      if (url.pathname === "/_tree")
+        return handleTree(url);
+      if (url.pathname === "/_files")
+        return handleFiles(url);
+      if (url.pathname === "/_grep")
+        return handleGrep(url);
+      if (url.pathname === "/_commits")
+        return handleRefCommits(url);
+      if (url.pathname === "/file_diff")
+        return handleFileDiff(url);
+      if (url.pathname === "/file_range")
+        return handleFileRange(url);
+      if (url.pathname === "/_file")
+        return handleRawFile(req, url);
+      if (url.pathname === "/_open_path")
+        return handleOpenPath(req);
+      if (url.pathname === "/_trash_path")
+        return handleTrashPath(req);
+      if (url.pathname === "/_restore_trash")
+        return handleRestoreTrash(req);
+      if (url.pathname === "/_create_directory")
+        return handleCreateDirectory(req);
+      if (url.pathname === "/_upload_files")
+        return handleUploadFiles(req);
+      if (url.pathname === "/_annotations")
+        return handleAnnotations(req);
+      if (url.pathname === "/_refs")
+        return json(refs(cwd));
+      if (url.pathname === "/refresh" && req.method === "POST") {
+        if (!sideEffectRequestAllowed(req))
+          return text("forbidden", 403);
+        triggerUpdate();
+        return json({ ok: true, generation });
+      }
+      if (url.pathname === "/events") {
+        let ctrl;
+        let keepalive;
+        return new Response(new ReadableStream({
+          start(controller) {
+            ctrl = controller;
+            sseClients.add(controller);
+            controller.enqueue(enc.encode(`event: open
 data: ok
 
 `));
-          keepalive = setInterval(() => {
-            try {
-              controller.enqueue(enc.encode(`: ping
+            keepalive = setInterval(() => {
+              try {
+                controller.enqueue(enc.encode(`: ping
 
 `));
-            } catch {
-              sseClients.delete(controller);
+              } catch {
+                sseClients.delete(controller);
+                clearInterval(keepalive);
+              }
+            }, 15000);
+          },
+          cancel() {
+            if (ctrl)
+              sseClients.delete(ctrl);
+            if (keepalive)
               clearInterval(keepalive);
-            }
-          }, 15000);
-        },
-        cancel() {
-          if (ctrl)
-            sseClients.delete(ctrl);
-          if (keepalive)
-            clearInterval(keepalive);
-        }
-      }), {
-        headers: {
-          "Content-Type": "text/event-stream",
-          "Cache-Control": "no-cache"
-        }
-      });
+          }
+        }), {
+          headers: {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache"
+          }
+        });
+      }
+      return text("not found", 404);
     }
-    return text("not found", 404);
+  });
+  if (openAfterStart) {
+    openBrowser(`http://127.0.0.1:${server.port}/`);
+  }
+  writeServerRegistry({
+    url: `http://127.0.0.1:${server.port}/`,
+    pid: process.pid,
+    root: cwd,
+    started_at: new Date().toISOString()
+  });
+  process.on("exit", () => removeServerRegistry(cwd, process.pid));
+  for (const signal of ["SIGINT", "SIGTERM"]) {
+    process.on(signal, () => {
+      removeServerRegistry(cwd, process.pid);
+      process.exit(0);
+    });
   }
+  startDevAssetReload({
+    enabled: process.env.CODE_VIEWER_DEV === "1",
+    webRoot: WEB_ROOT,
+    watchedFiles: WATCHED_ASSET_FILES,
+    watch,
+    sendReload: () => sendSse("reload")
+  });
+  startWorktreeUpdateWatch({
+    root: cwd,
+    omitDirNames: scopeOmitDirNames,
+    excludeNames: scopeExcludeNames,
+    watch,
+    initialScanMode: "async",
+    onUpdate: triggerUpdate,
+    onError: (error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(`code-viewer worktree watch skipped: ${message}`);
+    }
+  });
+  console.log(`GDP_LISTEN_URL=http://127.0.0.1:${server.port}/`);
+  console.log(`git-diff-preview serving ${cwd}`);
 });
-if (openAfterStart) {
-  openBrowser(`http://127.0.0.1:${server.port}/`);
+
+// web-src/server/cli.ts
+if (process.argv[2] === "annotate") {
+  const { runAnnotateCli: runAnnotateCli2 } = await Promise.resolve().then(() => (init_annotate_cli(), exports_annotate_cli));
+  await runAnnotateCli2(process.argv.slice(3));
+} else {
+  await init_preview().then(() => exports_preview);
 }
-startDevAssetReload({
-  enabled: process.env.CODE_VIEWER_DEV === "1",
-  webRoot: WEB_ROOT,
-  watchedFiles: WATCHED_ASSET_FILES,
-  watch,
-  sendReload: () => sendSse("reload")
-});
-startWorktreeUpdateWatch({
-  root: cwd,
-  omitDirNames: scopeOmitDirNames,
-  excludeNames: scopeExcludeNames,
-  watch,
-  initialScanMode: "async",
-  onUpdate: triggerUpdate,
-  onError: (error) => {
-    const message = error instanceof Error ? error.message : String(error);
-    console.warn(`code-viewer worktree watch skipped: ${message}`);
-  }
-});
-console.log(`GDP_LISTEN_URL=http://127.0.0.1:${server.port}/`);
-console.log(`git-diff-preview serving ${cwd}`);