react-detective 0.0.0-stage → 0.1.1

package/dist/chunk-5TDNB3DH.js

@@ -0,0 +1,2686 @@
+import {
+  MISSING_KEY_MESSAGE,
+  findApiKey
+} from "./chunk-E23QXCCY.js";
+
+// src/server/explain.ts
+import path from "path";
+import { createSdkMcpServer, query, tool } from "@anthropic-ai/claude-agent-sdk";
+import { z as z2 } from "zod";
+
+// src/server/card.ts
+import { z } from "zod";
+var short = (words, what) => z.string().describe(`${what} At most ~${words} words.`);
+var OUTLINE_KINDS = [
+  "state",
+  "ref",
+  "context",
+  "store",
+  "hook",
+  "derived",
+  "memo",
+  "callback",
+  "function",
+  "effect",
+  "render",
+  "constant"
+];
+var outlineFields = {
+  kind: z.enum(OUTLINE_KINDS).describe(
+    "state = useState/useReducer, or another built-in holding a value that re-renders (useTransition, useOptimistic, useActionState, useFormStatus); ref = useRef or useImperativeHandle; context = useContext or use(SomeContext); store = useSyncExternalStore (a value read from outside React that re-renders on change); hook = custom or library hook call (also use(promise)); derived = value computed during render, including useDeferredValue and useId; memo = useMemo; callback = useCallback; function = handler or helper; effect = useEffect/useLayoutEffect; render = a component element in the returned JSX, or a conditional / list branch of it, named as written, e.g. '<UserRow>'; constant = module-level value."
+  ),
+  name: z.string().describe("The identifier as written, e.g. 'selectedId', 'handleClick', 'initials'. For effects, a short label, e.g. 'sync to localStorage'. For render items, the element as written, e.g. '<UserRow>', '<p>'."),
+  line: z.number().int().describe("1-based line in the component's file where it is declared."),
+  type: z.string().describe(
+    [
+      "TypeScript type, written as code, using the project's own type names where they exist (e.g. 'User[]' not 'object[]').",
+      "state / ref / derived / memo / constant: the value's type, e.g. 'number | null', 'HTMLInputElement | null', 'string'.",
+      "context / store / hook: the type of what it returns, e.g. '{ users: User[]; loading: boolean }'.",
+      "callback / function: its signature, e.g. '(id: number) => void'.",
+      "effect / render: empty string."
+    ].join(" ")
+  ),
+  initial: z.string().describe(`state / ref only: the initial value as code, e.g. '""', 'null', '[]'. Empty string otherwise.`),
+  returns: z.string().describe(
+    "function / callback: what calling it gives back, in plain words, e.g. 'nothing; tells the parent which user was clicked' or 'the formatted price'. effect: what its cleanup does, e.g. 'clears the pending timer', or 'no cleanup'. Empty string for other kinds."
+  ),
+  when: z.string().describe(
+    "effect: when it runs: its dependency list like '[query]', 'on mount' or 'every render'. render: when it is shown: 'always', 'if <condition>' (e.g. 'if loading') or 'each <item>' (e.g. 'each user'). Empty string for other kinds."
+  ),
+  explanation: short(60, "Shown when the developer clicks the item: what it does and why it exists, in plain language. Mention related items by name. No file paths.")
+};
+var CardSchema = z.object({
+  summary: short(40, "One short paragraph a new teammate understands: what this component is for in the product, and in plain terms how it does it."),
+  props: z.array(
+    z.object({
+      name: z.string(),
+      type: z.string().describe("TypeScript type as written, or a short guess if untyped, e.g. 'User', '() => void'."),
+      optional: z.boolean(),
+      description: short(30, "What this prop is and what the component does with it, in plain language. No file paths or line numbers.")
+    })
+  ).describe("Every prop the component accepts, in declaration order. Empty if it takes none."),
+  outline: z.array(
+    z.object({
+      ...outlineFields,
+      children: z.array(z.object({ ...outlineFields, children: z.array(z.object(outlineFields)) })).describe("Items inside this one: helpers declared inside a handler or effect, or for render items the components rendered inside it.")
+    })
+  ).describe("The component's internals in source order, like an IDE outline: state, refs, context, hook calls, derived values, memos, callbacks, handlers, effects, then the notable parts of what it renders. Do not include the component itself as an item."),
+  usedIn: z.array(z.object({ ref: z.string().describe("Call site as project-relative path:line.") })).describe("Where this component is rendered."),
+  history: z.array(
+    z.object({
+      commit: z.string(),
+      date: z.string().optional(),
+      author: z.string().optional(),
+      why: short(25, "What changed and why, from the commit message.")
+    })
+  ).describe("Only commits whose message explains intent. Empty if there is no useful history."),
+  fileNotes: z.array(
+    z.object({
+      file: z.string(),
+      summary: short(45, "Factual summary: what it exports, its responsibility, key behaviour."),
+      exports: z.array(
+        z.object({
+          name: z.string().describe("The exported name as importers write it; 'default' for the default export."),
+          description: short(
+            40,
+            "What an importer needs to use it without opening the file: what it does, what its arguments mean, what it returns, side effects (fetching, storage, timers, context it requires) and gotchas. Don't repeat the signature."
+          )
+        })
+      ).describe("Every export of the file (functions, components, hooks, constants, types), in source order. Empty if it exports nothing.")
+    })
+  ).describe("One entry for EVERY file you opened with Read in this session. Stored and given to future sessions (including ones about other components that import from these files) so they can skip re-reading.")
+});
+var AnswerSchema = z.object({
+  answer: z.string().describe("Markdown answer. Lead with the direct answer in one sentence, then at most a few short bullets. Under ~150 words."),
+  fileNotes: CardSchema.shape.fileNotes
+});
+var CARD_VERSION = 4;
+function isCurrentCard(card) {
+  return !!card && typeof card === "object" && card.v === CARD_VERSION;
+}
+var toSchema = (s) => {
+  const { $schema: _, ...rest } = z.toJSONSchema(s);
+  return rest;
+};
+var cardJsonSchema = toSchema(CardSchema);
+var answerJsonSchema = toSchema(AnswerSchema);
+function cardToMarkdown(card) {
+  const out = ["## Overview", card.summary];
+  if (card.props.length) {
+    out.push("", "## Props");
+    for (const p of card.props) out.push(`- \`${p.name}${p.optional ? "?" : ""}: ${p.type}\`: ${p.description}`);
+  }
+  if (card.outline.length) {
+    out.push("", "## Inside");
+    const list = (items, indent) => {
+      for (const item of items) {
+        out.push(`${indent}- ${item.kind} \`${item.name}\` (line ${item.line}${facts(item)}): ${item.explanation}`);
+        list(item.children ?? [], `${indent}  `);
+      }
+    };
+    list(card.outline, "");
+  }
+  if (card.usedIn.length) {
+    out.push("", "## Where it's used");
+    for (const u of card.usedIn) out.push(`- \`${u.ref}\``);
+  }
+  if (card.history.length) {
+    out.push("", "## History");
+    for (const h of card.history) out.push(`- \`${h.commit}\`${h.date ? ` ${h.date}` : ""}${h.author ? ` ${h.author}` : ""}: ${h.why}`);
+  }
+  return out.join("\n");
+}
+function facts(item) {
+  const parts = [item.type && `type ${item.type}`, item.initial && `initially ${item.initial}`, item.when, item.returns && `returns ${item.returns}`].filter(Boolean);
+  return parts.length ? `, ${parts.join(", ")}` : "";
+}
+
+// src/server/explain.ts
+var SYSTEM_PROMPT = `You are a senior engineer onboarding a developer onto a React codebase they did not write (often it was AI-generated). The developer pointed at a component in the running app and wants to understand it.
+
+Explore the code with your read-only tools. Files whose source is included in the message are already read: do not open them again. Otherwise open the component's file, then follow imports, hooks, contexts, stores and API calls as far as needed, and grep for where the component is rendered. Prefer a few targeted reads over reading everything. Never guess about code you have not opened.
+
+You may be given "verified file notes": summaries of files whose content has not changed since the summary was written. Trust them and do not re-read those files unless you need exact lines or details the note doesn't cover. This saves the developer time and money.
+
+You may also be given "imported exports": what the component imports from project files, each with its signature (read from the current source) and a verified description. Trust them like file notes: don't open a file just to learn what an imported function, hook, component or constant does.
+
+You may have read-only git tools (log, blame, show). Commit messages often explain intent, especially in AI-written code. Use them when the developer asks why, when or who, or when code looks odd and history would explain it; otherwise don't spend calls on them.
+
+Your final answer is structured data that is rendered as a visual panel, not prose. The developer reads it top to bottom: overview, then props, then an IDE-style outline of the component's internals they can click to expand.
+- Write in plain language for someone who has never seen this code. Short, concrete strings; no filler; don't repeat the same fact in two places.
+- Whenever you mention a prop, state, ref, function, value or constant of this component by name, wrap it in backticks (\`focused\`, \`clear()\`, \`MIN_QUERY\`): the panel turns those into hoverable links to their definitions.
+- Props and outline explanations describe what a thing is and does. Do not put file paths or line references in them; refer to other parts of the component by name instead.
+- The outline mirrors the component's source in order, like VS Code's outline view. Include every state, ref, context read, custom hook call, derived value, memo, callback, handler and effect, plus what it renders: one render item per component element in the returned JSX (named as written, e.g. \`<UserRow>\`) and per conditional or list branch that is a plain element (e.g. \`<p>\` shown if \`error\`), nested like the JSX so the developer sees which component sits inside which. Use exact line numbers from the component's file. Do not add the component itself as an item; its internals are the top level. Otherwise nest only items declared inside another item (e.g. a helper inside an effect).
+- If something is surprising or likely a bug, say so briefly in the relevant item's explanation.
+- usedIn uses project-relative \`path:line\` references so they become clickable links.
+- history holds only commits whose message explains intent; leave it empty otherwise.
+- fileNotes must cover every file you opened with Read and every file whose source was included in the message, and describe every export of each of those files: other components that import them rely on these descriptions instead of reading the file.
+
+When the developer asks a specific question, the answer field is short markdown: the direct answer first, then a few bullets at most.`;
+async function explainComponent(req, opts) {
+  const abortController = new AbortController();
+  opts.signal?.addEventListener("abort", () => abortController.abort(), { once: true });
+  const stream = query({
+    prompt: buildPrompt(req, opts.context),
+    options: {
+      cwd: opts.root,
+      systemPrompt: SYSTEM_PROMPT,
+      // Read-only: the agent may look at code but never change or execute anything.
+      tools: ["Read", "Grep", "Glob"],
+      allowedTools: ["Read", "Grep", "Glob", ...opts.git ? GIT_TOOL_NAMES : []],
+      mcpServers: opts.git ? { git: gitServer(opts.git, opts.root) } : void 0,
+      permissionMode: "dontAsk",
+      // Isolate from the developer's personal hooks/settings; we only want code exploration.
+      settingSources: [],
+      env: agentEnv(opts.apiKey),
+      maxTurns: opts.maxTurns ?? 30,
+      model: opts.model,
+      outputFormat: { type: "json_schema", schema: req.question ? answerJsonSchema : cardJsonSchema },
+      abortController
+    }
+  });
+  let raw = "";
+  let structured;
+  let costUsd;
+  let turns;
+  let modelUsed;
+  const filesRead = /* @__PURE__ */ new Set();
+  for await (const msg of stream) {
+    if (msg.type === "assistant" && !msg.parent_tool_use_id) {
+      for (const block of msg.message.content) {
+        if (block.type !== "tool_use") continue;
+        const input = block.input;
+        if (block.name === "Read" && typeof input.file_path === "string") {
+          const rel = toRelative(opts.root, input.file_path);
+          if (rel) filesRead.add(rel);
+        }
+        opts.onProgress?.(describeToolUse(block.name, input, opts.root));
+      }
+    } else if (msg.type === "result") {
+      costUsd = msg.total_cost_usd;
+      turns = msg.num_turns;
+      modelUsed = Object.keys(msg.modelUsage ?? {})[0];
+      if (process.env.DETECTIVE_DEBUG) console.log("[react-detective] usage", JSON.stringify({ turns, costUsd, usage: msg.usage, models: msg.modelUsage }));
+      if (msg.subtype === "success") {
+        raw = msg.result;
+        structured = msg.structured_output;
+      } else throw new Error(`Explanation failed (${msg.subtype})`);
+    }
+  }
+  const base = { filesRead: [...filesRead], costUsd, turns, model: modelUsed };
+  if (req.question) {
+    const parsed2 = AnswerSchema.safeParse(structured);
+    if (parsed2.success) return { ...base, markdown: parsed2.data.answer, ...notesRecord(parsed2.data.fileNotes) };
+  } else {
+    const parsed2 = CardSchema.safeParse(structured);
+    if (parsed2.success) {
+      const { fileNotes, ...fields } = parsed2.data;
+      const card = { ...fields, v: CARD_VERSION };
+      return { ...base, card, markdown: cardToMarkdown(card), ...notesRecord(fileNotes) };
+    }
+  }
+  if (!req.question || !raw.trim()) throw new Error("The agent returned no usable explanation.");
+  return { ...base, markdown: raw.trim(), notes: {}, exports: {} };
+}
+function notesRecord(list) {
+  const notes = {};
+  const exports = {};
+  for (const n of list) {
+    const file = n.file.replace(/\\/g, "/");
+    notes[file] = n.summary;
+    if (n.exports?.length) exports[file] = Object.fromEntries(n.exports.map((e) => [e.name, e.description]));
+  }
+  return { notes, exports };
+}
+function buildPrompt(req, ctx = {}) {
+  const lines = [];
+  const where = req.file ? `defined in \`${req.file}${req.line ? `:${req.line}` : ""}\`` : "(file unknown, so find it with Grep first)";
+  lines.push(`The developer is looking at the React component \`<${req.component}>\` ${where}.`);
+  if (req.chain?.length) lines.push(`In the page it is rendered inside: ${req.chain.map((c) => `<${c}>`).join(" > ")}.`);
+  if (req.elementText) lines.push(`They pointed at an element showing the text: "${req.elementText.slice(0, 200)}".`);
+  if (req.props !== void 0) lines.push(`Live props right now (serialized, may be truncated):
+\`\`\`json
+${JSON.stringify(req.props, null, 2).slice(0, 4e3)}
+\`\`\``);
+  if (req.state !== void 0) lines.push(`Live hook state values, in hook order:
+\`\`\`json
+${JSON.stringify(req.state, null, 2).slice(0, 2e3)}
+\`\`\``);
+  const notes = Object.entries(ctx.notes ?? {});
+  if (notes.length) {
+    lines.push(`
+Verified file notes (these files are unchanged since summarized):`);
+    for (const [file, summary] of notes) lines.push(`- \`${file}\`: ${summary}`);
+  }
+  if (ctx.imports?.length) {
+    lines.push(`
+Imported exports (what \`${req.file}\` imports from project files; signatures are read from the current source, descriptions are verified unchanged):`);
+    for (const i of ctx.imports) {
+      const where2 = `\`${i.declaredIn ?? i.from}:${i.line}\`${i.declaredIn ? ` (via \`${i.from}\`)` : ""}`;
+      lines.push(`- ${i.kind} \`${i.name}\`${i.signature ? ` \`${i.signature}\`` : ""} from ${where2}: ${i.description}`);
+    }
+  }
+  if (ctx.usages) {
+    lines.push(
+      ctx.usages.length ? `
+Where \`<${req.component}>\` is rendered (text search for \`<${req.component}\` across the project; no need to grep for this again):
+${ctx.usages.map((u) => `- \`${u}\``).join("\n")}` : `
+A text search found no \`<${req.component}\` in the project source (it may be rendered under another name, e.g. via a variable or re-export).`
+    );
+  }
+  for (const [file, text] of Object.entries(ctx.sources ?? {})) {
+    const numbered = text.split("\n").map((l, i) => `${String(i + 1).padStart(4)}	${l}`).join("\n");
+    lines.push(`
+Source of \`${file}\` (line-numbered, current version; this counts as having read it, so do not open it with Read):
+\`\`\`
+${numbered}
+\`\`\``);
+  }
+  if (ctx.history?.length) {
+    lines.push(`
+Recent commits touching \`${req.file}\` (newest first):`);
+    for (const c of ctx.history) lines.push(`- \`${c.sha}\` ${c.date} ${c.author}: ${c.subject}`);
+  }
+  if (ctx.explanation) lines.push(`
+Current explanation of this component (still accurate):
+<explanation>
+${ctx.explanation}
+</explanation>`);
+  const own = ctx.pastQuestions?.filter((q) => !q.component) ?? [];
+  const others = ctx.pastQuestions?.filter((q) => q.component) ?? [];
+  if (own.length || others.length) {
+    lines.push(
+      req.question ? `
+Questions developers already asked (answers verified still accurate: the code they relied on is unchanged). Build on them instead of re-investigating what they already established:` : `
+Questions developers already asked (answers verified still accurate: the code they relied on is unchanged). Use what they established: put any findings that belong to this component (bugs, gotchas, why something works the way it does) into the relevant prop or outline explanation, briefly, and skip re-investigating them:`
+    );
+    for (const q of own) lines.push(`<qa about="${req.component}">
+Q: ${q.question}
+A: ${q.answer}
+</qa>`);
+    for (const q of others) lines.push(`<qa about="${q.component}" related="true">
+Q: ${q.question}
+A: ${q.answer}
+</qa>`);
+  }
+  if (req.question) {
+    lines.push(`
+The developer's question: ${req.question}`);
+  } else if (ctx.previous) {
+    const { changes, markdown } = ctx.previous;
+    const changedFiles = changes.map((c) => c.file);
+    const unchanged = ctx.previous.unchanged.filter((f) => !changedFiles.includes(f));
+    lines.push(`
+An earlier explanation of this component exists, but some files it relied on have changed since it was written:`);
+    for (const c of changes) {
+      if (c.deleted) lines.push(`- \`${c.file}\` was deleted.`);
+      else if (c.diff) lines.push(`- \`${c.file}\` changed. Diff from the explained version to now:
+\`\`\`diff
+${c.diff}
+\`\`\``);
+      else lines.push(`- \`${c.file}\` changed (no diff available, so re-read it).`);
+    }
+    if (unchanged.length) {
+      lines.push(
+        `These files it relied on are unchanged, so do NOT open them again; the previous explanation and the notes above already cover them: ${unchanged.map((f) => `\`${f}\``).join(", ")}.`
+      );
+    }
+    lines.push(
+      `Where a diff is shown, use it instead of re-reading the file unless you need surrounding context. Then produce the updated explanation, keeping everything that is still correct.`,
+      `<previous_explanation>
+${markdown}
+</previous_explanation>`
+    );
+  } else {
+    lines.push(`
+Explain this component.`);
+  }
+  return lines.join("\n");
+}
+function toRelative(root, file) {
+  const rel = path.relative(root, path.resolve(root, file));
+  if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) return null;
+  return rel.split(path.sep).join("/");
+}
+var GIT_TOOL_NAMES = ["mcp__git__log", "mcp__git__blame", "mcp__git__show"];
+function gitServer(git, root) {
+  const text = (t) => ({ content: [{ type: "text", text: t }] });
+  const outside = text("Path is outside the project.");
+  return createSdkMcpServer({
+    name: "git",
+    tools: [
+      tool(
+        "log",
+        "Commit history (hash, date, author, full message) for a project file, newest first. Use it to learn why code was written or changed.",
+        { path: z2.string().describe("Project-relative file path"), limit: z2.number().int().min(1).max(30).optional() },
+        async ({ path: p, limit }) => {
+          const rel = toRelative(root, p);
+          return rel ? text(await git.logText(rel, limit ?? 10)) : outside;
+        },
+        { annotations: { readOnlyHint: true } }
+      ),
+      tool(
+        "blame",
+        "Which commit last changed each line in a range of a project file.",
+        { path: z2.string().describe("Project-relative file path"), start_line: z2.number().int().min(1), end_line: z2.number().int().min(1) },
+        async ({ path: p, start_line, end_line }) => {
+          const rel = toRelative(root, p);
+          return rel ? text(await git.blameText(rel, start_line, end_line)) : outside;
+        },
+        { annotations: { readOnlyHint: true } }
+      ),
+      tool(
+        "show",
+        "Full message, changed files and patch of one commit.",
+        { commit: z2.string().describe("Commit hash (short or full)") },
+        async ({ commit }) => text(await git.showText(commit)),
+        { annotations: { readOnlyHint: true } }
+      )
+    ]
+  });
+}
+function describeToolUse(name, input, root) {
+  const rel = (p) => p ? toRelative(root, p) ?? p : "";
+  switch (name) {
+    case "mcp__git__log":
+      return `Checking git history of ${rel(input.path)}`;
+    case "mcp__git__blame":
+      return `Running git blame on ${rel(input.path)}:${input.start_line}-${input.end_line}`;
+    case "mcp__git__show":
+      return `Reading commit ${input.commit}`;
+    case "Read":
+      return `Reading ${rel(input.file_path)}`;
+    case "Grep":
+      return `Searching for \u201C${input.pattern}\u201D${input.path ? ` in ${rel(input.path)}` : ""}`;
+    case "Glob":
+      return `Looking for files matching ${input.pattern}`;
+    default:
+      return `Using ${name}`;
+  }
+}
+function agentEnv(apiKey) {
+  const env = {};
+  for (const [k, v] of Object.entries(process.env)) if (v !== void 0) env[k] = v;
+  delete env.CLAUDE_CODE_OAUTH_TOKEN;
+  delete env.ANTHROPIC_AUTH_TOKEN;
+  env.ANTHROPIC_API_KEY = apiKey;
+  return env;
+}
+
+// src/server/handler.ts
+import path9 from "path";
+import launchEditor from "launch-editor";
+import { createTwoFilesPatch } from "diff";
+
+// src/server/store.ts
+import { createHash } from "crypto";
+import fs from "fs";
+import path2 from "path";
+var README = `# .react-detective
+
+Knowledge collected by [react-detective](https://github.com/) while explaining this codebase.
+
+- \`components/\` holds one file per component: the explanation and every question asked about it.
+  Each answer records the files the AI read and their git blob ids, so it is only reused while
+  that code is unchanged, and the commit it was written at.
+- \`files.json\` holds short AI-written summaries of source files and of each thing they export,
+  keyed by content hash. They let the AI skip re-reading files that haven't changed, including
+  when it explains another component that imports from them.
+
+Commit this folder so your team shares explanations instead of paying for them again.
+Delete any file to force it to be regenerated.
+`;
+var KnowledgeStore = class {
+  dir;
+  root;
+  /** Local-only copies of file versions we explained, so we can diff against them later. */
+  blobDir;
+  hashMemo = /* @__PURE__ */ new Map();
+  notes = null;
+  constructor(root, dirName = ".react-detective") {
+    this.root = root;
+    this.dir = path2.join(root, dirName);
+    this.blobDir = path2.join(root, "node_modules", ".cache", "react-detective", "blobs");
+  }
+  // ---------- hashing ----------
+  /** Normalized content of a project file, or null if it doesn't exist. */
+  readFile(rel) {
+    try {
+      return fs.readFileSync(path2.join(this.root, rel), "utf8").replace(/\r\n/g, "\n");
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Fingerprint of a project file (its git blob id), or null if it doesn't exist.
+   * Line endings are normalized so Windows and Unix checkouts agree.
+   */
+  hashFile(rel) {
+    let stat;
+    try {
+      stat = fs.statSync(path2.join(this.root, rel));
+    } catch {
+      return null;
+    }
+    const memo = this.hashMemo.get(rel);
+    if (memo && memo.mtimeMs === stat.mtimeMs && memo.size === stat.size) return memo.hash;
+    const content = this.readFile(rel);
+    if (content === null) return null;
+    const hash = blobHash(content);
+    this.hashMemo.set(rel, { mtimeMs: stat.mtimeMs, size: stat.size, hash });
+    return hash;
+  }
+  /** Keeps a local copy of each dependency's current content, so later diffs work even for never-committed versions. */
+  saveBlobs(deps) {
+    for (const [rel, hash] of Object.entries(deps)) {
+      const file = path2.join(this.blobDir, hash);
+      if (fs.existsSync(file)) continue;
+      const content = this.readFile(rel);
+      if (content === null || blobHash(content) !== hash) continue;
+      try {
+        fs.mkdirSync(this.blobDir, { recursive: true });
+        fs.writeFileSync(file, content);
+      } catch {
+      }
+    }
+  }
+  readBlob(hash) {
+    if (!/^[0-9a-f]{40}$/.test(hash)) return null;
+    try {
+      return fs.readFileSync(path2.join(this.blobDir, hash), "utf8");
+    } catch {
+      return null;
+    }
+  }
+  snapshot(files) {
+    const deps = {};
+    for (const f of [...new Set(files)].sort()) {
+      const h = this.hashFile(f);
+      if (h) deps[f] = h;
+    }
+    return deps;
+  }
+  check(deps) {
+    const changed = Object.entries(deps).filter(([f, h]) => this.hashFile(f) !== h).map(([f]) => f);
+    return { fresh: changed.length === 0, changed };
+  }
+  // ---------- components ----------
+  getComponent(component, file) {
+    try {
+      return JSON.parse(fs.readFileSync(this.componentPath(component, file), "utf8"));
+    } catch {
+      return { component, file: file ?? null, questions: [] };
+    }
+  }
+  saveExplanation(component, file, entry) {
+    const rec = this.getComponent(component, file);
+    rec.explanation = entry;
+    this.writeComponent(rec, file);
+  }
+  saveQuestion(component, file, entry) {
+    const rec = this.getComponent(component, file);
+    const key = normalizeQuestion(entry.question);
+    rec.questions = rec.questions.filter((q) => normalizeQuestion(q.question) !== key);
+    rec.questions.push(entry);
+    this.writeComponent(rec, file);
+  }
+  findQuestion(rec, question) {
+    const key = normalizeQuestion(question);
+    return rec.questions.find((q) => normalizeQuestion(q.question) === key);
+  }
+  /** Every saved component record, for finding knowledge about related components. */
+  listComponents() {
+    const dir = path2.join(this.dir, "components");
+    let names;
+    try {
+      names = fs.readdirSync(dir).filter((n) => n.endsWith(".json"));
+    } catch {
+      return [];
+    }
+    const out = [];
+    for (const name of names) {
+      try {
+        out.push(JSON.parse(fs.readFileSync(path2.join(dir, name), "utf8")));
+      } catch {
+      }
+    }
+    return out;
+  }
+  componentPath(component, file) {
+    const safeFile = (file ?? "_unknown").replace(/[\\/]/g, "--").replace(/[^\w.\-[\]()@]/g, "_");
+    return path2.join(this.dir, "components", `${safeFile}--${component.replace(/[^\w]/g, "_")}.json`);
+  }
+  writeComponent(rec, file) {
+    this.write(this.componentPath(rec.component, file), rec);
+  }
+  // ---------- file notes ----------
+  /** Notes whose file content is unchanged since they were written. */
+  validNotes(files) {
+    const out = {};
+    for (const f of files) {
+      const note = this.validNote(f);
+      if (note) out[f] = note.summary;
+    }
+    return out;
+  }
+  /** Saved descriptions of a file's exports, if the file is unchanged since they were written. */
+  validExports(file) {
+    return this.validNote(file)?.exports ?? {};
+  }
+  validNote(file) {
+    const note = this.loadNotes()[file];
+    return note && this.hashFile(file) === note.hash ? note : void 0;
+  }
+  noteFiles() {
+    return Object.keys(this.loadNotes());
+  }
+  saveNotes(summaries, deps, exports = {}) {
+    const all = this.loadNotes();
+    let changed = false;
+    for (const [file, summary] of Object.entries(summaries)) {
+      const hash = deps[file];
+      if (!hash || !summary?.trim()) continue;
+      const kept = all[file]?.hash === hash ? all[file].exports : void 0;
+      const described = Object.entries(exports[file] ?? {}).filter(([name, d]) => name.trim() && d?.trim());
+      const merged = { ...kept, ...Object.fromEntries(described.map(([name, d]) => [name.trim(), d.trim()])) };
+      all[file] = { hash, summary: summary.trim(), ...Object.keys(merged).length ? { exports: merged } : {}, updatedAt: Date.now() };
+      changed = true;
+    }
+    if (changed) this.write(path2.join(this.dir, "files.json"), sortKeys(all));
+  }
+  loadNotes() {
+    if (!this.notes) {
+      try {
+        this.notes = JSON.parse(fs.readFileSync(path2.join(this.dir, "files.json"), "utf8"));
+      } catch {
+        this.notes = {};
+      }
+    }
+    return this.notes;
+  }
+  // ---------- io ----------
+  write(file, data) {
+    try {
+      fs.mkdirSync(path2.dirname(file), { recursive: true });
+      const readme = path2.join(this.dir, "README.md");
+      if (!fs.existsSync(readme)) fs.writeFileSync(readme, README);
+      fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+    } catch (err) {
+      console.warn(`[react-detective] could not write ${file}: ${err.message}`);
+    }
+  }
+};
+function blobHash(content) {
+  const buf = Buffer.from(content, "utf8");
+  return createHash("sha1").update(`blob ${buf.length}\0`).update(buf).digest("hex");
+}
+function normalizeQuestion(q) {
+  return q.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, " ").trim();
+}
+function sortKeys(obj) {
+  return Object.fromEntries(Object.entries(obj).sort(([a], [b]) => a.localeCompare(b)));
+}
+function localImports(root, rel) {
+  let code;
+  try {
+    code = fs.readFileSync(path2.join(root, rel), "utf8");
+  } catch {
+    return [];
+  }
+  const out = [];
+  const re = /(?:from\s+|import\s*\(\s*|import\s+)["']([^"']+)["']/g;
+  for (const m of code.matchAll(re)) {
+    const hit = resolveImport(root, rel, m[1]);
+    if (hit) out.push(hit);
+  }
+  return [...new Set(out)];
+}
+function resolveModule(root, fromRel, spec) {
+  return resolveImport(root, fromRel, spec) ?? resolvePackage(root, fromRel, spec);
+}
+function resolvePackage(root, fromRel, spec) {
+  const parts = spec.split("/");
+  const name = spec.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+  const sub = spec.slice(name.length + 1);
+  if (!name || name.startsWith(".")) return null;
+  for (let dir = path2.dirname(path2.join(root, fromRel)); ; dir = path2.dirname(dir)) {
+    const pkgDir = path2.join(dir, "node_modules", name);
+    let pkg = null;
+    try {
+      pkg = JSON.parse(fs.readFileSync(path2.join(pkgDir, "package.json"), "utf8"));
+    } catch {
+    }
+    if (pkg) {
+      const entry = exportTarget(pkg.exports, sub ? `./${sub}` : ".") ?? (sub ? `./${sub}` : pkg.module ?? pkg.main ?? "index.js");
+      const hit = resolveFile(root, path2.relative(root, path2.join(pkgDir, entry)));
+      if (hit) return hit;
+    }
+    if (path2.dirname(dir) === dir) return null;
+  }
+}
+function exportTarget(exports, subpath) {
+  const pick = (t) => typeof t === "string" ? t : t && typeof t === "object" ? pick(t.import) ?? pick(t.module) ?? pick(t.browser) ?? pick(t.default) ?? null : null;
+  if (typeof exports === "string") return subpath === "." ? exports : null;
+  if (!exports || typeof exports !== "object") return null;
+  if (!Object.keys(exports).some((k) => k.startsWith("."))) return subpath === "." ? pick(exports) : null;
+  return pick(exports[subpath]);
+}
+function resolveImport(root, fromRel, spec) {
+  const bases = [];
+  if (spec.startsWith(".")) bases.push(path2.join(path2.dirname(fromRel), spec));
+  else if (spec.startsWith("@/") || spec.startsWith("~/")) bases.push(spec.slice(2), path2.join("src", spec.slice(2)));
+  for (const base of bases) {
+    const hit = resolveFile(root, base);
+    if (hit) return hit;
+  }
+  return null;
+}
+var EXTS = ["", ".tsx", ".ts", ".jsx", ".js", ".mjs", "/index.tsx", "/index.ts", "/index.jsx", "/index.js"];
+function resolveFile(root, base) {
+  for (const ext of EXTS) {
+    const candidate = base + ext;
+    try {
+      if (fs.statSync(path2.join(root, candidate)).isFile()) return candidate.split(path2.sep).join("/");
+    } catch {
+    }
+  }
+  return null;
+}
+
+// src/server/exports.ts
+import { parse } from "@babel/parser";
+import fs2 from "fs";
+import path3 from "path";
+var MAX_SIGNATURE = 200;
+var MAX_DEPTH = 4;
+var cache = /* @__PURE__ */ new Map();
+function exportsOf(root, rel, depth = 0) {
+  const info = fileInfo(root, rel);
+  const out = /* @__PURE__ */ new Map();
+  if (!info) return out;
+  for (const [name, e] of info.own) out.set(name, e);
+  if (depth >= MAX_DEPTH) return out;
+  for (const [name, [spec, there]] of info.reexports) {
+    const target = resolveImport(root, rel, spec);
+    const hit = target && exportsOf(root, target, depth + 1).get(there);
+    if (hit) out.set(name, { ...hit, name });
+  }
+  for (const spec of info.star) {
+    const target = resolveImport(root, rel, spec);
+    if (!target) continue;
+    for (const [name, e] of exportsOf(root, target, depth + 1)) if (name !== "default" && !out.has(name)) out.set(name, e);
+  }
+  return out;
+}
+function importsOf(root, rel) {
+  const info = fileInfo(root, rel);
+  if (!info) return [];
+  const out = /* @__PURE__ */ new Map();
+  for (const [spec, names] of info.imports) {
+    const file = resolveImport(root, rel, spec);
+    if (!file) continue;
+    const set = out.get(file) ?? /* @__PURE__ */ new Set();
+    names.forEach((n) => set.add(n));
+    out.set(file, set);
+  }
+  return [...out].map(([file, names]) => ({ file, names: [...names] }));
+}
+function fileInfo(root, rel) {
+  const abs = path3.join(root, rel);
+  let stat;
+  try {
+    stat = fs2.statSync(abs);
+  } catch {
+    return null;
+  }
+  const hit = cache.get(abs);
+  if (hit && hit.mtimeMs === stat.mtimeMs) return hit.info;
+  let info = null;
+  try {
+    info = readInfo(rel, fs2.readFileSync(abs, "utf8").replace(/\r\n/g, "\n"));
+  } catch {
+  }
+  cache.set(abs, { mtimeMs: stat.mtimeMs, info });
+  return info;
+}
+function readInfo(rel, source) {
+  const ast = parse(source, { sourceType: "module", errorRecovery: true, plugins: ["typescript", "jsx", "decorators-legacy"] });
+  const src = (n) => n ? source.slice(n.start, n.end) : "";
+  const info = { own: /* @__PURE__ */ new Map(), reexports: /* @__PURE__ */ new Map(), star: [], imports: /* @__PURE__ */ new Map() };
+  const declared = /* @__PURE__ */ new Map();
+  const addOwn = (name, d) => info.own.set(name, { name, declaredAs: name, ...d });
+  const pendingLocal = [];
+  const declare = (node) => {
+    const line = node.loc?.start.line ?? 0;
+    const base = { file: rel, line };
+    switch (node.type) {
+      case "FunctionDeclaration":
+        return node.id ? [[node.id.name, { ...base, local: node.id.name, kind: fnKind(node.id.name), signature: signature(node, src) }]] : [];
+      case "ClassDeclaration":
+        return node.id ? [[node.id.name, { ...base, local: node.id.name, kind: "class", signature: "" }]] : [];
+      case "TSInterfaceDeclaration":
+        return [[node.id.name, { ...base, local: node.id.name, kind: "interface", signature: clip(src(node.body)) }]];
+      case "TSTypeAliasDeclaration":
+        return [[node.id.name, { ...base, local: node.id.name, kind: "type", signature: clip(src(node.typeAnnotation)) }]];
+      case "TSEnumDeclaration":
+        return [[node.id.name, { ...base, local: node.id.name, kind: "enum", signature: "" }]];
+      case "VariableDeclaration":
+        return node.declarations.filter((d) => d.id.type === "Identifier").map((d) => {
+          const fn = functionOf(d.init);
+          const name = d.id.name;
+          const annotated = src(d.id.typeAnnotation?.typeAnnotation);
+          const kind = fn ? fnKind(name) : node.kind === "const" ? "const" : "variable";
+          const sig = annotated || (fn ? signature(fn, src) : kind === "const" && d.init && !/^(Call|New)Expression$/.test(d.init.type) ? src(d.init) : "");
+          return [name, { file: rel, line: d.loc?.start.line ?? line, local: name, kind, signature: clip(sig) }];
+        });
+      default:
+        return [];
+    }
+  };
+  for (const node of ast.program.body) {
+    if (node.type === "ImportDeclaration") {
+      if (node.importKind === "type" && !node.specifiers.length) continue;
+      const names = info.imports.get(node.source.value) ?? /* @__PURE__ */ new Set();
+      for (const s of node.specifiers) {
+        if (s.type === "ImportDefaultSpecifier") names.add("default");
+        else if (s.type === "ImportNamespaceSpecifier") names.add("*");
+        else names.add(s.imported.name ?? s.imported.value);
+      }
+      info.imports.set(node.source.value, names);
+      continue;
+    }
+    if (node.type === "ExportAllDeclaration") {
+      info.star.push(node.source.value);
+      continue;
+    }
+    if (node.type === "ExportNamedDeclaration") {
+      if (node.declaration) {
+        for (const [name, d] of declare(node.declaration)) addOwn(name, d);
+        continue;
+      }
+      for (const s of node.specifiers) {
+        const exported = s.exported.name ?? s.exported.value;
+        const local = s.local?.name ?? s.local?.value;
+        if (node.source) info.reexports.set(exported, [node.source.value, s.type === "ExportNamespaceSpecifier" ? "*" : local]);
+        else pendingLocal.push([exported, local]);
+      }
+      continue;
+    }
+    if (node.type === "ExportDefaultDeclaration") {
+      const decl = node.declaration;
+      if (decl.type === "Identifier") pendingLocal.push(["default", decl.name]);
+      else {
+        const own = declare(decl)[0];
+        if (own) {
+          addOwn("default", own[1]);
+          declared.set(own[0], own[1]);
+        } else {
+          const fn = functionOf(decl);
+          const line = decl.loc?.start.line ?? 0;
+          addOwn("default", {
+            file: rel,
+            line,
+            local: "default",
+            kind: fn ? "function" : "const",
+            signature: clip(fn ? signature(fn, src) : src(decl))
+          });
+        }
+      }
+      continue;
+    }
+    for (const [name, d] of declare(node)) declared.set(name, d);
+  }
+  for (const [exported, local] of pendingLocal) {
+    const d = declared.get(local);
+    if (d) addOwn(exported, d);
+  }
+  return info;
+}
+function fnKind(name) {
+  return /^use[A-Z0-9]/.test(name) ? "hook" : /^[A-Z]/.test(name) ? "component" : "function";
+}
+function functionOf(node) {
+  while (node?.type === "CallExpression") node = node.arguments.find((a) => /Function/.test(a.type)) ?? node.arguments[0];
+  return node && /Function/.test(node.type) ? node : null;
+}
+function signature(fn, src) {
+  const ret = src(fn.returnType?.typeAnnotation);
+  return clip(`(${fn.params.map(src).join(", ")})${ret ? ` => ${ret}` : ""}`);
+}
+function clip(text) {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > MAX_SIGNATURE ? flat.slice(0, MAX_SIGNATURE - 1) + "\u2026" : flat;
+}
+
+// src/server/git.ts
+import { execFile } from "child_process";
+var SEP = "";
+var Git = class {
+  repo = null;
+  cwd;
+  constructor(cwd) {
+    this.cwd = cwd;
+  }
+  isRepo() {
+    this.repo ??= this.run(["rev-parse", "--is-inside-work-tree"]).then((out) => out?.trim() === "true");
+    return this.repo;
+  }
+  async head() {
+    if (!await this.isRepo()) return null;
+    const [commit, branch] = await Promise.all([
+      this.run(["rev-parse", "--short", "HEAD"]),
+      this.run(["rev-parse", "--abbrev-ref", "HEAD"])
+    ]);
+    return commit ? { commit: commit.trim(), branch: branch?.trim() ?? "" } : null;
+  }
+  /** True if any of the files have uncommitted changes (or are untracked). */
+  async isDirty(files) {
+    if (!files.length || !await this.isRepo()) return false;
+    const out = await this.run(["status", "--porcelain", "--", ...files]);
+    return !!out?.trim();
+  }
+  async catBlob(sha) {
+    if (!/^[0-9a-f]{40}$/.test(sha) || !await this.isRepo()) return null;
+    return this.run(["cat-file", "blob", sha]);
+  }
+  async recentCommits(file, limit = 5) {
+    if (!await this.isRepo()) return [];
+    const out = await this.run(["log", `-n${limit}`, "--follow", "--date=short", `--format=%h${SEP}%an${SEP}%ad${SEP}%s`, "--", file]);
+    return (out ?? "").split("\n").filter(Boolean).map((line) => {
+      const [sha, author, date, subject] = line.split(SEP);
+      return { sha, author, date, subject };
+    });
+  }
+  // ---------- agent tools (formatted text, size-capped) ----------
+  async logText(file, limit) {
+    const out = await this.run([
+      "log",
+      `-n${Math.min(Math.max(limit, 1), 30)}`,
+      "--follow",
+      "--date=short",
+      "--format=commit %h  %ad  %an%n%B%n---",
+      "--",
+      file
+    ]);
+    return cap(out?.trim() || `No commits found for ${file}.`, 12e3);
+  }
+  async blameText(file, start, end) {
+    const s = Math.max(1, Math.floor(start));
+    const e = Math.min(Math.max(s, Math.floor(end)), s + 300);
+    const out = await this.run(["blame", "-L", `${s},${e}`, "--date=short", "--", file]);
+    return cap(out?.trim() || `Could not blame ${file}:${s}-${e} (uncommitted file or out of range).`, 12e3);
+  }
+  async showText(commit) {
+    if (!/^[0-9a-f]{4,40}$/i.test(commit)) return "Invalid commit hash.";
+    const out = await this.run(["show", "--stat", "--patch", "--date=short", "--format=commit %H%nAuthor: %an%nDate: %ad%n%n%B", commit]);
+    return cap(out?.trim() || `Commit ${commit} not found.`, 15e3);
+  }
+  run(args) {
+    return new Promise((resolve) => {
+      execFile(
+        "git",
+        ["-c", "core.quotepath=off", ...args],
+        { cwd: this.cwd, maxBuffer: 8 * 1024 * 1024, windowsHide: true },
+        (err, stdout) => resolve(err ? null : stdout)
+      );
+    });
+  }
+};
+function cap(text, max) {
+  return text.length > max ? `${text.slice(0, max)}
+\u2026 (truncated, ${text.length - max} more characters)` : text;
+}
+
+// src/server/types.ts
+import { parse as parse2 } from "@babel/parser";
+import fs3 from "fs";
+import path4 from "path";
+var MAX_LINES = 30;
+var MAX_FILES = 25;
+function resolveTypes(root, file, text) {
+  if (!file) return [];
+  const files = candidateFiles(root, file);
+  const declared = /* @__PURE__ */ new Map();
+  for (const f of files) for (const def of declarationsIn(root, f)) if (!declared.has(def.name)) declared.set(def.name, def);
+  const found = /* @__PURE__ */ new Map();
+  let pending = mentionedNames(text);
+  for (let depth = 0; depth < 3 && pending.size; depth++) {
+    const next = /* @__PURE__ */ new Set();
+    for (const name of pending) {
+      const def = declared.get(name);
+      if (!def || found.has(name)) continue;
+      found.set(name, def);
+      for (const n of mentionedNames(def.code)) if (!found.has(n)) next.add(n);
+    }
+    pending = next;
+  }
+  return [...found.values()];
+}
+function mentionedNames(text) {
+  return new Set(text.match(/\b[A-Z][A-Za-z0-9_]*\b/g) ?? []);
+}
+function candidateFiles(root, file) {
+  const out = [file];
+  for (let i = 0; i < out.length && out.length < MAX_FILES && i < 12; i++) {
+    for (const imp of localImports(root, out[i])) if (!out.includes(imp)) out.push(imp);
+  }
+  return out.slice(0, MAX_FILES).filter((f) => /\.[cm]?tsx?$/.test(f));
+}
+var cache2 = /* @__PURE__ */ new Map();
+function declarationsIn(root, rel) {
+  const abs = path4.join(root, rel);
+  let stat;
+  try {
+    stat = fs3.statSync(abs);
+  } catch {
+    return [];
+  }
+  const hit = cache2.get(abs);
+  if (hit && hit.mtimeMs === stat.mtimeMs) return hit.defs;
+  const source = fs3.readFileSync(abs, "utf8").replace(/\r\n/g, "\n");
+  let ast;
+  try {
+    ast = parse2(source, { sourceType: "module", errorRecovery: true, plugins: ["typescript", "jsx", "decorators-legacy"] });
+  } catch {
+    return [];
+  }
+  const defs = [];
+  for (let node of ast.program.body) {
+    if ((node.type === "ExportNamedDeclaration" || node.type === "ExportDefaultDeclaration") && node.declaration) node = node.declaration;
+    const kind = node.type === "TSInterfaceDeclaration" ? "interface" : node.type === "TSTypeAliasDeclaration" ? "type" : node.type === "TSEnumDeclaration" ? "enum" : null;
+    if (!kind || !node.id?.name) continue;
+    let code = source.slice(node.start, node.end);
+    const lines = code.split("\n");
+    if (lines.length > MAX_LINES) code = [...lines.slice(0, MAX_LINES), "  // \u2026"].join("\n");
+    defs.push({ name: node.id.name, kind, code, file: rel, line: node.loc.start.line });
+  }
+  cache2.set(abs, { mtimeMs: stat.mtimeMs, defs });
+  return defs;
+}
+
+// src/server/hookslots.ts
+import { parse as parse3 } from "@babel/parser";
+import fs4 from "fs";
+import path5 from "path";
+var VALUE = [{ state: false, element: 0 }];
+var STATE = [{ state: true, element: 0 }];
+var INTERNAL = { state: false, element: null };
+var BUILTIN_ENTRIES = {
+  useState: STATE,
+  useReducer: STATE,
+  useOptimistic: STATE,
+  // isPending, then the start function.
+  useTransition: [...STATE, INTERNAL],
+  // The state, isPending (the third element), then the action queue.
+  useActionState: [...STATE, { state: true, element: 2 }, INTERNAL],
+  // The snapshot, then the effect that subscribes to the store.
+  useSyncExternalStore: [...VALUE, INTERNAL],
+  useRef: VALUE,
+  useMemo: VALUE,
+  useCallback: VALUE,
+  useEffect: VALUE,
+  useLayoutEffect: VALUE,
+  useInsertionEffect: VALUE,
+  useImperativeHandle: VALUE,
+  useId: VALUE,
+  useDeferredValue: VALUE
+};
+var STATE_HOOKS = new Set(Object.keys(BUILTIN_ENTRIES).filter((h) => BUILTIN_ENTRIES[h].some((e) => e.state)));
+var NO_ENTRY = /* @__PURE__ */ new Set(["useContext", "useDebugValue", "use"]);
+var DEPS_ARG = { useEffect: 1, useLayoutEffect: 1, useInsertionEffect: 1, useMemo: 1, useCallback: 1, useImperativeHandle: 2 };
+var RETURNED = { type: "Identifier", name: "@returned" };
+var MAX_DEPTH2 = 4;
+function hookSlots(root, file, component) {
+  if (!file) return null;
+  const found = findFunction(root, file, component, 0);
+  if (!found) return null;
+  const raws = collect(root, found.file, found.fn, 0);
+  const unknownAt = raws.findIndex((r) => r.kind === "unknown");
+  const hookRaws = (unknownAt < 0 ? raws : raws.slice(0, unknownAt)).filter((r) => r.kind === "hook");
+  return {
+    hooks: hookRaws.map((r) => ({ ...toSlot(r), hook: r.hook, ...r.deps ? { deps: r.deps } : {} })),
+    complete: unknownAt < 0,
+    states: raws.filter((r) => r.kind === "hook" && r.state).map(toSlot),
+    contexts: raws.filter((r) => r.kind === "context").map(toSlot),
+    constants: constantsIn(root, file)
+  };
+}
+function toSlot(r) {
+  return r.owner ? { owner: r.owner, key: r.key, name: r.name } : { name: r.local ?? r.name };
+}
+function collect(root, file, fn, depth) {
+  const out = [];
+  const source = parseFile(root, file)?.source ?? "";
+  const body = fn.body?.type === "BlockStatement" ? fn.body : { type: "VariableDeclarator", id: RETURNED, init: fn.body };
+  walk(body, (call, declarator) => {
+    const callee = calleeName(call);
+    const readsContext = callee === "useContext" || callee === "use" && /Context$/.test(call.arguments[0]?.name ?? "");
+    if (!callee || NO_ENTRY.has(callee) && !readsContext) return;
+    if (callee in BUILTIN_ENTRIES) {
+      const first = boundName(declarator?.id, 0);
+      const name = first && first !== RETURNED.name ? first : callee;
+      const depsNode = DEPS_ARG[callee] !== void 0 ? call.arguments[DEPS_ARG[callee]] : void 0;
+      const deps = depsNode?.type === "ArrayExpression" ? depsNode.elements.map((e) => e ? source.slice(e.start, e.end) : "") : void 0;
+      BUILTIN_ENTRIES[callee].forEach((entry, n) => {
+        const local = entry.element === null ? null : boundName(declarator?.id, entry.element);
+        const label = n === 0 ? name : entry.element === null || !local ? `${name} (internal)` : local;
+        out.push({ kind: "hook", hook: callee, state: entry.state, local, name: label, ...n === 0 && deps ? { deps } : {} });
+      });
+    } else if (readsContext) {
+      const ctx = call.arguments[0]?.type === "Identifier" ? call.arguments[0].name : "context";
+      out.push({ kind: "context", local: declarator?.id?.type === "Identifier" ? declarator.id.name : null, name: ctx });
+    } else if (/^use[A-Z]/.test(callee)) {
+      const target = depth < MAX_DEPTH2 ? findFunction(root, file, callee, depth + 1) : null;
+      if (!target) return void out.push({ kind: "unknown", local: null, name: callee });
+      const inner = collect(root, target.file, target.fn, depth + 1);
+      const shape = returnShape(target.fn);
+      for (const s of inner) {
+        const key = shape && s.local ? exposedAs(shape, s.local, declarator?.id) : void 0;
+        out.push({
+          ...s,
+          owner: callee,
+          key,
+          local: key !== void 0 ? callerLocal(declarator?.id, shape, key) : null
+        });
+      }
+    }
+  });
+  return out;
+}
+function constantsIn(root, file) {
+  const parsed2 = parseFile(root, file);
+  return parsed2 ? Object.fromEntries(parsed2.constants) : {};
+}
+function returnShape(fn) {
+  let expr = fn.body?.type !== "BlockStatement" ? fn.body : null;
+  if (!expr) {
+    const ret = [...fn.body?.body ?? []].reverse().find((s) => s.type === "ReturnStatement");
+    expr = ret?.argument;
+  }
+  while (expr?.type === "TSAsExpression" || expr?.type === "TSSatisfiesExpression") expr = expr.expression;
+  if (!expr) return null;
+  if (expr.type === "Identifier") return { type: "single", name: expr.name };
+  if (expr.type === "CallExpression") return { type: "single", name: RETURNED.name };
+  if (expr.type === "ObjectExpression") {
+    const map = /* @__PURE__ */ new Map();
+    for (const p of expr.properties) {
+      if (p.type !== "ObjectProperty" || p.value?.type !== "Identifier") continue;
+      const key = p.key.type === "Identifier" ? p.key.name : p.key.type === "StringLiteral" ? p.key.value : null;
+      if (key) map.set(p.value.name, key);
+    }
+    return { type: "object", map };
+  }
+  if (expr.type === "ArrayExpression") {
+    const map = /* @__PURE__ */ new Map();
+    expr.elements.forEach((e, i) => e?.type === "Identifier" && map.set(e.name, i));
+    return { type: "array", map };
+  }
+  return null;
+}
+function exposedAs(shape, local, callSitePattern) {
+  if (shape.type === "single") return shape.name === local ? "" : void 0;
+  if (shape.type === "object") return shape.map.get(local);
+  const index = shape.map.get(local);
+  if (index === void 0) return void 0;
+  return boundName(callSitePattern, index) ?? `[${index}]`;
+}
+function callerLocal(pattern, shape, key) {
+  if (!pattern) return null;
+  if (shape.type === "single") return pattern.type === "Identifier" ? pattern.name : null;
+  if (shape.type === "array") return key.startsWith("[") ? null : key;
+  if (pattern.type === "ObjectPattern") {
+    for (const p of pattern.properties) {
+      const k = p.key?.type === "Identifier" ? p.key.name : p.key?.value;
+      if (k !== key) continue;
+      const v = p.value?.type === "AssignmentPattern" ? p.value.left : p.value;
+      return v?.type === "Identifier" ? v.name : null;
+    }
+  }
+  return null;
+}
+function boundName(pattern, index) {
+  if (!pattern) return null;
+  if (pattern.type === "Identifier") return index === 0 ? pattern.name : null;
+  if (pattern.type === "ArrayPattern") {
+    const el = pattern.elements[index];
+    const id = el?.type === "AssignmentPattern" ? el.left : el;
+    return id?.type === "Identifier" ? id.name : null;
+  }
+  return null;
+}
+function calleeName(call) {
+  const c = call.callee;
+  if (c.type === "Identifier") return c.name;
+  if (c.type === "MemberExpression" && c.property.type === "Identifier" && c.object.type === "Identifier" && c.object.name === "React") return c.property.name;
+  return null;
+}
+function walk(node, visit, declarator = null, top = true) {
+  if (!node || typeof node !== "object") return;
+  if (Array.isArray(node)) return node.forEach((n) => walk(n, visit, declarator, top));
+  if (!top && /Function/.test(node.type)) return;
+  if (node.type === "ReturnStatement" && node.argument?.type === "CallExpression") {
+    walk(node.argument, visit, { id: RETURNED }, false);
+    return;
+  }
+  if (node.type === "VariableDeclarator") {
+    walk(node.init, visit, node, false);
+    return;
+  }
+  if (node.type === "CallExpression") {
+    walk(node.arguments, visit, null, false);
+    visit(node, declarator);
+    return;
+  }
+  for (const key of Object.keys(node)) {
+    if (key === "loc" || key === "start" || key === "end" || key === "leadingComments" || key === "trailingComments") continue;
+    walk(node[key], visit, null, false);
+  }
+}
+var parsedCache = /* @__PURE__ */ new Map();
+function parseFile(root, rel) {
+  const abs = path5.join(root, rel);
+  let stat;
+  try {
+    stat = fs4.statSync(abs);
+  } catch {
+    return null;
+  }
+  const hit = parsedCache.get(abs);
+  if (hit && hit.mtimeMs === stat.mtimeMs) return hit.parsed;
+  let parsed2 = null;
+  try {
+    const source = fs4.readFileSync(abs, "utf8").replace(/\r\n/g, "\n");
+    const ast = parse3(source, { sourceType: "module", errorRecovery: true, plugins: ["typescript", "jsx", "decorators-legacy"] });
+    parsed2 = { source, constants: /* @__PURE__ */ new Map(), constantNodes: /* @__PURE__ */ new Map(), contexts: /* @__PURE__ */ new Map(), typeDecls: /* @__PURE__ */ new Map(), functions: /* @__PURE__ */ new Map(), defaultExport: null, imports: /* @__PURE__ */ new Map(), reexports: [] };
+    for (let node of ast.program.body) {
+      if (node.type === "ImportDeclaration") {
+        for (const s of node.specifiers) {
+          const imported = s.type === "ImportDefaultSpecifier" ? "default" : s.type === "ImportSpecifier" ? s.imported.name ?? s.imported.value : null;
+          if (imported) parsed2.imports.set(s.local.name, { spec: node.source.value, imported });
+        }
+        continue;
+      }
+      if (node.type === "ExportNamedDeclaration" && node.source) {
+        for (const s of node.specifiers) {
+          const exported = s.exported?.name ?? s.exported?.value;
+          if (exported && s.local) parsed2.imports.set(exported, { spec: node.source.value, imported: s.local.name ?? s.local.value });
+        }
+        continue;
+      }
+      if (node.type === "ExportAllDeclaration" && !node.exported) {
+        parsed2.reexports.push(node.source.value);
+        continue;
+      }
+      const isDefault = node.type === "ExportDefaultDeclaration";
+      if ((node.type === "ExportNamedDeclaration" || isDefault) && node.declaration) node = node.declaration;
+      if (isDefault) parsed2.defaultExport = functionOf2(node);
+      if (node.type === "FunctionDeclaration" && node.id) parsed2.functions.set(node.id.name, node);
+      if ((node.type === "TSInterfaceDeclaration" || node.type === "TSTypeAliasDeclaration") && node.id) parsed2.typeDecls.set(node.id.name, node);
+      if (node.type === "VariableDeclaration") {
+        for (const d of node.declarations) {
+          const fn = functionOf2(d.init);
+          if (d.id.type === "Identifier" && fn) parsed2.functions.set(d.id.name, fn);
+          else if (d.id.type === "Identifier" && d.init?.type === "CallExpression" && /^(React\.)?createContext$/.test(source.slice(d.init.callee.start, d.init.callee.end))) {
+            parsed2.contexts.set(d.id.name, d.init);
+          } else if (d.id.type === "Identifier" && d.init && node.kind === "const" && !/^(Call|New)Expression$/.test(d.init.type)) {
+            const value = source.slice(d.init.start, d.init.end);
+            parsed2.constants.set(d.id.name, value.length > 300 ? value.slice(0, 299) + "\u2026" : value);
+            parsed2.constantNodes.set(d.id.name, d);
+          }
+        }
+      }
+    }
+  } catch {
+    parsed2 = null;
+  }
+  parsedCache.set(abs, { mtimeMs: stat.mtimeMs, parsed: parsed2 });
+  return parsed2;
+}
+function functionOf2(node) {
+  while (node?.type === "CallExpression") node = node.arguments.find((a) => /Function/.test(a.type)) ?? node.arguments[0];
+  return node && /Function/.test(node.type) ? node : null;
+}
+function findContext(root, file, name) {
+  const parsed2 = parseFile(root, file);
+  if (!parsed2) return null;
+  const local = parsed2.contexts.get(name);
+  if (local) return { parsed: parsed2, call: local };
+  const imp = parsed2.imports.get(name);
+  const target = imp && resolveModule(root, file, imp.spec);
+  const targetParsed = target ? parseFile(root, target) : null;
+  const call = targetParsed?.contexts.get(imp.imported);
+  return call ? { parsed: targetParsed, call } : null;
+}
+function findFunction(root, file, name, depth) {
+  const parsed2 = parseFile(root, file);
+  if (!parsed2) return null;
+  const local = parsed2.functions.get(name);
+  if (local) return { file, fn: local };
+  if (depth === 0 && parsed2.defaultExport) return { file, fn: parsed2.defaultExport };
+  if (depth > MAX_DEPTH2) return null;
+  return importedFunction(root, file, parsed2, name, 0);
+}
+function importedFunction(root, file, parsed2, name, hops) {
+  if (hops > 6) return null;
+  const imp = parsed2.imports.get(name);
+  const sources = imp ? [{ spec: imp.spec, name: imp.imported }] : parsed2.reexports.map((spec) => ({ spec, name }));
+  for (const { spec, name: imported } of sources) {
+    const target = resolveModule(root, file, spec);
+    const targetParsed = target ? parseFile(root, target) : null;
+    if (!targetParsed) continue;
+    const fn = imported === "default" ? targetParsed.defaultExport : targetParsed.functions.get(imported);
+    if (fn) return { file: target, fn };
+    const further = imported === "default" ? null : importedFunction(root, target, targetParsed, imported, hops + 1);
+    if (further) return further;
+  }
+  return null;
+}
+
+// src/server/skeleton.ts
+import fs5 from "fs";
+import path6 from "path";
+var STATE_LIKE = {
+  useTransition: () => ({ type: "boolean", initial: "false" }),
+  useOptimistic: (args, src) => ({ type: literalType(args[0]), initial: src(args[0]) }),
+  useActionState: (args, src) => ({ type: literalType(args[1]), initial: src(args[1]) }),
+  useFormStatus: () => ({ type: "", initial: "" })
+};
+var VALUE_FIRST = /* @__PURE__ */ new Set(["useState", "useReducer", "useRef", "useMemo", "useCallback", "useContext", "useDeferredValue", "useId", "useSyncExternalStore", ...Object.keys(STATE_LIKE)]);
+function skeletonCard(root, file, component, usedIn = []) {
+  if (!file) return null;
+  const found = findFunction(root, file, component, 0);
+  const parsed2 = found && parseFile(root, found.file);
+  if (!found || !parsed2) return null;
+  const src = (node) => node ? parsed2.source.slice(node.start, node.end) : "";
+  const outline = [];
+  const item = (kind, name, node, extra = {}) => ({
+    kind,
+    name,
+    line: node.loc?.start.line ?? 0,
+    type: "",
+    initial: "",
+    returns: "",
+    when: "",
+    explanation: "",
+    children: [],
+    ...extra
+  });
+  const inner = (fn, renders = true) => nested(fn, item, src, renders);
+  const libraryOf = (hook) => {
+    const spec = parsed2.imports.get(hook)?.spec ?? "";
+    return /^[.~]|^@\//.test(spec) || spec === "react" ? "" : spec;
+  };
+  const opaque = (hook) => hook === "use" || !!libraryOf(hook);
+  const ownSignature = (hook) => opaque(hook) ? "" : hookSignature(root, found.file, hook);
+  const depsText = (deps) => deps?.type === "ArrayExpression" ? `[${deps.elements.map(src).join(", ")}]` : deps ? "" : "every render";
+  const actionSignature = (fn) => {
+    const f = fn?.type === "Identifier" ? parsed2.functions.get(fn.name) : fn;
+    const param = /Function/.test(f?.type ?? "") ? f.params[1] : null;
+    return param ? `(${src(param)}) => void` : "";
+  };
+  const companions = (name, type, node) => name ? [item("function", name, node, { type, reads: "1" })] : [];
+  const body = found.fn.body?.type === "BlockStatement" ? found.fn.body.body : [];
+  for (const stmt of body) {
+    if (stmt.type === "FunctionDeclaration" && stmt.id) {
+      outline.push(item("function", stmt.id.name, stmt, { type: signature2(stmt, src), children: inner(stmt) }));
+      continue;
+    }
+    if (stmt.type === "ExpressionStatement" && stmt.expression.type === "CallExpression") {
+      const call = stmt.expression;
+      const hook = calleeName(call);
+      if (hook && /^use(Layout|Insertion)?Effect$/.test(hook)) {
+        const deps = call.arguments[1];
+        outline.push(
+          item("effect", hook, stmt, {
+            hook,
+            when: deps?.type === "ArrayExpression" ? `[${deps.elements.map(src).join(", ")}]` : deps ? "" : "every render",
+            returns: hasCleanup(call.arguments[0]) ? "" : "no cleanup",
+            children: inner(call.arguments[0], false)
+          })
+        );
+      } else if (hook === "useImperativeHandle") {
+        const [refArg, factory, deps] = call.arguments;
+        const handleType = refArg?.type === "Identifier" ? refTarget(found.fn, refArg.name, parsed2) : null;
+        const fromType = typeMembers(handleType, parsed2);
+        const exposed = returnedObject(factory);
+        const members = exposed ? exposed.properties.flatMap((p) => {
+          const key = p.key?.name ?? p.key?.value;
+          if (key == null || p.computed) return [];
+          const declared = fromType.get(key);
+          const fn = p.type === "ObjectMethod" || /Function/.test(p.value?.type ?? "");
+          const type = declared?.type || (p.type === "ObjectMethod" ? `(${p.params.map(src).join(", ")})` : fn ? signature2(p.value, src) : literalType(p.value));
+          return [item(declared?.fn || fn ? "function" : "derived", key, p, { type, reads: key })];
+        }) : [...fromType].map(([key, m]) => item(m.fn ? "function" : "derived", String(key), stmt, { type: m.type, reads: String(key) }));
+        outline.push(
+          item("ref", `useImperativeHandle(${src(refArg)})`, stmt, {
+            hook,
+            type: src(handleType),
+            when: deps?.type === "ArrayExpression" ? `[${deps.elements.map(src).join(", ")}]` : deps ? "" : "every render",
+            children: members
+          })
+        );
+      } else if (hook && hook !== "useDebugValue" && /^use[A-Z]/.test(hook)) {
+        outline.push(item("hook", `${hook}(${call.arguments.map(src).join(", ")})`, stmt, { type: ownSignature(hook), from: libraryOf(hook) }));
+      }
+      continue;
+    }
+    if (stmt.type !== "VariableDeclaration") continue;
+    for (const d of stmt.declarations) {
+      const init = d.init;
+      const names = boundNames(d.id);
+      const named = names.filter(Boolean);
+      if (!init || !named.length) continue;
+      const hook = init.type === "CallExpression" ? calleeName(init) : null;
+      if (!names[0] && hook && VALUE_FIRST.has(hook)) continue;
+      const typeArg = init.typeParameters?.params?.[0] ?? init.typeArguments?.params?.[0];
+      const declared = d.id.typeAnnotation?.typeAnnotation;
+      if (hook === "useState" || hook === "useReducer") {
+        const first = init.arguments[hook === "useState" ? 0 : 1];
+        const type = src(typeArg) || literalType(first) || (first?.type === "Identifier" ? paramType(found.fn, first.name, src) : "");
+        const setter = hook === "useState" ? type ? `Dispatch<SetStateAction<${type}>>` : "" : actionSignature(init.arguments[0]);
+        outline.push(item("state", names[0], d, { hook, type, initial: hook === "useState" ? src(first) : "", children: companions(names[1], setter, d) }));
+      } else if (hook === "useRef") {
+        const first = init.arguments[0];
+        const t = src(typeArg);
+        outline.push(item("ref", names[0], d, { type: t ? first?.type === "NullLiteral" ? `${t} | null` : t : literalType(first), initial: src(first) }));
+      } else if (hook === "useMemo") {
+        if (d.id.type === "Identifier") {
+          outline.push(item("memo", names[0], d, { type: src(typeArg) || src(declared), when: depsText(init.arguments[1]), children: inner(init.arguments[0]) }));
+        } else {
+          const members = typeMembers(typeArg ?? declared, parsed2);
+          if (!members.size) for (const [key, m] of literalMembers(init.arguments[0], src)) members.set(key, m);
+          outline.push(item("memo", "useMemo()", d, { type: src(typeArg) || src(declared), when: depsText(init.arguments[1]), children: [...inner(init.arguments[0]), ...givenItems(item, d.id, d, members)] }));
+        }
+      } else if (hook === "useCallback") {
+        outline.push(item("callback", names[0], d, { type: signature2(init.arguments[0], src), when: depsText(init.arguments[1]), children: inner(init.arguments[0]) }));
+      } else if (hook === "useContext" || hook === "use" && /Context$/.test(src(init.arguments[0]))) {
+        const context = src(init.arguments[0]);
+        const type = src(typeArg) || src(declared) || contextType(root, found.file, context);
+        if (d.id.type === "Identifier") outline.push(item("context", names[0], d, { hook, type, from: context }));
+        else {
+          const given = givenItems(item, d.id, d, contextMembers(root, found.file, context));
+          outline.push(item("context", `${hook}(${context})`, d, { hook, type, from: context, children: given }));
+        }
+      } else if (hook === "useSyncExternalStore") {
+        const snapshot = init.arguments[1];
+        const body2 = /Function/.test(snapshot?.type ?? "") && snapshot.body.type !== "BlockStatement" ? snapshot.body : null;
+        const from = body2 ? src(body2) : snapshot ? `${src(snapshot)}()` : "";
+        const type = src(typeArg) || src(declared) || src(snapshot?.returnType?.typeAnnotation) || literalType(body2);
+        if (d.id.type === "Identifier") outline.push(item("store", names[0], d, { hook, type, from }));
+        else outline.push(item("store", `${hook}()`, d, { hook, type, from, children: givenItems(item, d.id, d, typeMembers(typeArg ?? declared, parsed2)) }));
+      } else if (hook && hook in STATE_LIKE) {
+        const { type, initial } = STATE_LIKE[hook](init.arguments, src);
+        const companion = d.id.type === "ObjectPattern" ? [] : companions(
+          names[1],
+          hook === "useTransition" ? "(action: () => void | Promise<void>) => void" : hook === "useOptimistic" ? actionSignature(init.arguments[1]) : hook === "useActionState" ? actionSignature(init.arguments[0]) : "",
+          d
+        );
+        for (const [i, name] of (d.id.type === "ObjectPattern" ? names : names.slice(0, 1)).entries()) {
+          outline.push(item("state", name, d, { hook, type: src(typeArg) || type, initial, children: i === 0 ? companion : [] }));
+        }
+        if (hook === "useActionState" && names[2]) outline.push(item("state", names[2], d, { hook, type: "boolean", initial: "false" }));
+      } else if (hook === "useDeferredValue" || hook === "useId") {
+        outline.push(item("derived", names[0], d, { hook, type: src(typeArg) || src(declared) || (hook === "useId" ? "string" : "") }));
+      } else if (hook === "use" || hook && /^use[A-Z]/.test(hook)) {
+        const given = d.id.type === "Identifier" ? [item("derived", d.id.name, d, { type: src(declared) || (opaque(hook) ? "" : hookReturnType(root, found.file, hook)), reads: "" })] : givenItems(item, d.id, d, opaque(hook) ? /* @__PURE__ */ new Map() : hookGives(root, found.file, hook));
+        outline.push(item("hook", `${hook}(${init.arguments.map(src).join(", ")})`, d, { type: ownSignature(hook), from: libraryOf(hook), children: given }));
+      } else if (/Function/.test(init.type)) {
+        outline.push(item("function", names[0], d, { type: signature2(init, src), children: inner(init) }));
+      } else {
+        for (const name of named) outline.push(item("derived", name, d, { type: src(declared) || (named.length === 1 ? literalType(init) : "") }));
+      }
+    }
+  }
+  const used = src(found.fn);
+  for (const [name, node] of found.file === file ? parsed2.constantNodes : /* @__PURE__ */ new Map()) {
+    if (!new RegExp(`\\b${name.replace(/\$/g, "\\$")}\\b`).test(used)) continue;
+    outline.push(item("constant", name, node, { type: src(node.id.typeAnnotation?.typeAnnotation) || literalType(node.init) }));
+  }
+  outline.push(...renderTree(found.fn, item, src));
+  outline.sort((a, b) => a.line - b.line);
+  return { summary: "", props: propsOf(found.fn, parsed2, src), outline, usedIn: usedIn.map((ref) => ({ ref })), history: [], v: CARD_VERSION };
+}
+function nested(fn, make, src, renders = true) {
+  if (!fn || !/Function/.test(fn.type)) return [];
+  const out = [];
+  for (const stmt of fn.body?.type === "BlockStatement" ? fn.body.body : []) {
+    if (stmt.type === "FunctionDeclaration" && stmt.id) {
+      out.push(make("function", stmt.id.name, stmt, { type: signature2(stmt, src), children: nested(stmt, make, src) }));
+    } else if (stmt.type === "VariableDeclaration") {
+      for (const d of stmt.declarations) {
+        if (d.id.type === "Identifier" && /Function/.test(d.init?.type ?? "")) {
+          out.push(make("function", d.id.name, d, { type: signature2(d.init, src), children: nested(d.init, make, src) }));
+        }
+      }
+    }
+  }
+  if (renders) out.push(...renderTree(fn, make, src));
+  return out.sort((a, b) => a.line - b.line);
+}
+function renderTree(fn, make, src) {
+  if (!fn || !/Function/.test(fn.type)) return [];
+  const locals = /* @__PURE__ */ new Map();
+  const hold = (name, node, when) => locals.set(name, [...locals.get(name) ?? [], { node, when }]);
+  const values = (e) => e?.type === "Identifier" && locals.has(e.name) ? locals.get(e.name) : [{ node: e, when: "" }];
+  const fnValue = (e) => values(e).map((v) => v.node).find((n) => /Function/.test(n?.type ?? ""));
+  const following = /* @__PURE__ */ new Set();
+  const follow = (name, run) => {
+    if (!name) return run();
+    if (following.has(name)) return [];
+    following.add(name);
+    try {
+      return run();
+    } finally {
+      following.delete(name);
+    }
+  };
+  const code = (node) => src(node).replace(/\s+/g, " ");
+  const and = (...parts) => parts.filter(Boolean).join(", ");
+  let depth = 0;
+  let keepRoot = false;
+  const element = (node, when) => {
+    const name = jsxName(node.openingElement.name);
+    const attrs = node.openingElement.attributes;
+    depth++;
+    const children = [
+      // JSX passed as props (`fallback={<Spinner />}`, `renderItem={(u) => <Row />}`) counts as inside.
+      ...attrs.flatMap((a) => a.type === "JSXAttribute" ? jsx(a.value, "") : []),
+      ...node.children.flatMap((c) => jsx(c, ""))
+    ];
+    depth--;
+    const hidden = hiddenWhen(attrs, code);
+    const plain = !/^[A-Z]/.test(name) && !name.includes(".") && !when && hidden === null;
+    if (plain && !children.length && !(keepRoot && depth === 0)) return [];
+    const shown = when || "always";
+    return [make("render", `<${name}>`, node, { when: hidden === null ? shown : and(shown, `hidden${hidden ? ` ${hidden}` : ""}`), children })];
+  };
+  const jsx = (node, when) => {
+    switch (node?.type) {
+      case "JSXElement":
+        return element(node, when);
+      case "JSXFragment":
+        return node.children.flatMap((c) => jsx(c, when));
+      case "JSXExpressionContainer":
+        return expr(node.expression, when);
+      default:
+        return [];
+    }
+  };
+  const expr = (e, when) => {
+    switch (e?.type) {
+      case "JSXElement":
+      case "JSXFragment":
+        return jsx(e, when);
+      case "LogicalExpression":
+        return e.operator === "&&" ? expr(e.right, and(when, `if ${code(e.left)}`)) : [...expr(e.left, when), ...expr(e.right, and(when, `unless ${code(e.left)}`))];
+      case "ConditionalExpression":
+        return [...expr(e.consequent, and(when, `if ${code(e.test)}`)), ...expr(e.alternate, and(when, `unless ${code(e.test)}`))];
+      case "ArrayExpression":
+        return e.elements.flatMap((x) => expr(x, when));
+      case "CallExpression": {
+        const { callee } = e;
+        const method = callee.type === "MemberExpression" && !callee.computed ? callee.property.name : null;
+        if (method === "map" || method === "flatMap") {
+          const cb = fnValue(e.arguments[0]);
+          if (!cb) return [];
+          const item = cb.params[0] ? code(cb.params[0]) : "item";
+          const each = `each ${item}${filtered(callee.object, item)}`;
+          return follow(e.arguments[0].type === "Identifier" ? e.arguments[0].name : null, () => body(cb, and(when, each)));
+        }
+        const helper = callee.type === "Identifier" ? fnValue(callee) : null;
+        return helper ? follow(callee.name, () => body(helper, when)) : [];
+      }
+      case "Identifier":
+        return follow(e.name, () => (locals.get(e.name) ?? []).flatMap((v) => expr(v.node, and(when, v.when))));
+      case "MemberExpression": {
+        const key = e.computed ? null : e.property.name;
+        return values(e.object).flatMap(
+          ({ node: obj, when: held }) => obj?.type !== "ObjectExpression" ? [] : obj.properties.flatMap((p) => {
+            const k = p.type === "ObjectProperty" ? p.key.name ?? p.key.value : void 0;
+            if (k === void 0) return [];
+            if (key !== null) return k === key ? expr(p.value, and(when, held)) : [];
+            return expr(p.value, and(when, held, `if ${code(e.property)} === ${JSON.stringify(String(k))}`));
+          })
+        );
+      }
+      case "ArrowFunctionExpression":
+      case "FunctionExpression":
+        return body(e, when);
+      // a render prop: `{(user) => <Row user={user} />}`
+      case "TSAsExpression":
+      case "TSSatisfiesExpression":
+      case "TSNonNullExpression":
+      case "ParenthesizedExpression":
+        return expr(e.expression, when);
+      default:
+        return [];
+    }
+  };
+  const filtered = (list, item) => {
+    const isFilter = list?.type === "CallExpression" && list.callee.type === "MemberExpression" && list.callee.property?.name === "filter";
+    if (!isFilter) return "";
+    const f = list.arguments[0];
+    if (!/Function/.test(f?.type ?? "") || f.body.type === "BlockStatement") return " (filtered)";
+    const param = f.params[0]?.type === "Identifier" ? f.params[0].name : null;
+    const test = code(f.body);
+    return ` where ${param && /^[\w$]+$/.test(item) ? test.replace(new RegExp(`\\b${param.replace(/\$/g, "\\$")}\\b`, "g"), item) : test}`;
+  };
+  const body = (f, when) => f.body?.type === "BlockStatement" ? statements(f.body.body, when) : expr(f.body, when);
+  const block = (s) => s?.type === "BlockStatement" ? s.body : s ? [s] : [];
+  const returns = (s) => block(s).some((x) => x.type === "ReturnStatement");
+  const ifChain = (s, when, first = true) => {
+    const test = code(s.test);
+    const out = statements(block(s.consequent), and(when, `${first ? "if" : "else if"} ${test}`));
+    if (s.alternate?.type === "IfStatement") out.push(...ifChain(s.alternate, when, false));
+    else if (s.alternate) out.push(...statements(block(s.alternate), and(when, first ? `unless ${test}` : "otherwise")));
+    return out;
+  };
+  const statements = (stmts, when) => {
+    const out = [];
+    const early = [];
+    for (const s of stmts) {
+      switch (s.type) {
+        case "FunctionDeclaration":
+          if (s.id) hold(s.id.name, s, "");
+          break;
+        case "VariableDeclaration":
+          for (const d of s.declarations) if (d.id.type === "Identifier" && d.init) hold(d.id.name, d.init, "");
+          break;
+        case "ExpressionStatement": {
+          const x = s.expression;
+          if (x.type === "AssignmentExpression" && x.operator === "=" && x.left.type === "Identifier") hold(x.left.name, x.right, when);
+          if (x.type === "CallExpression" && x.callee.type === "MemberExpression" && x.callee.property?.name === "push" && x.callee.object.type === "Identifier") {
+            for (const arg of x.arguments) hold(x.callee.object.name, arg, when);
+          }
+          break;
+        }
+        case "IfStatement":
+          out.push(...ifChain(s, when));
+          if (returns(s.consequent)) early.push(code(s.test));
+          break;
+        case "SwitchStatement": {
+          let tests = [];
+          for (const c of s.cases) {
+            if (c.test) tests.push(code(c.test));
+            if (!c.consequent.length) continue;
+            const test = c.test ? `${code(s.discriminant)} === ${tests.join(" or ")}` : "";
+            out.push(...statements(c.consequent, and(when, test ? `if ${test}` : "otherwise")));
+            if (c.consequent.some(returns)) early.push(test || "default");
+            tests = [];
+          }
+          break;
+        }
+        case "ForOfStatement":
+        case "ForInStatement":
+          out.push(...statements(block(s.body), and(when, `each ${code(s.left.declarations?.[0]?.id ?? s.left)}`)));
+          break;
+        case "ForStatement":
+        case "WhileStatement":
+          out.push(...statements(block(s.body), and(when, "in a loop")));
+          break;
+        case "BlockStatement":
+          out.push(...statements(s.body, when));
+          break;
+        case "ReturnStatement": {
+          const rest = early.length === 1 ? `unless ${early[0]}` : early.length ? "otherwise" : "";
+          out.push(...expr(s.argument, and(when, rest)));
+          return out;
+        }
+      }
+    }
+    return out;
+  };
+  const tree = body(fn, "");
+  if (tree.length) return tree;
+  locals.clear();
+  keepRoot = true;
+  return body(fn, "");
+}
+var hides = (n) => n?.type === "StringLiteral" && (n.value === "none" || n.value === "hidden");
+function hiddenWhen(attrs, code) {
+  for (const a of attrs) {
+    if (a.type !== "JSXAttribute") continue;
+    const v = a.value?.type === "JSXExpressionContainer" ? a.value.expression : a.value;
+    if (a.name.name === "hidden") {
+      if (!v) return "";
+      if (v.type === "BooleanLiteral") return v.value ? "" : null;
+      return `if ${code(v)}`;
+    }
+    if (a.name.name === "style" && v?.type === "ObjectExpression") {
+      for (const p of v.properties) {
+        const key = p.key?.name ?? p.key?.value;
+        if (key !== "display" && key !== "visibility") continue;
+        if (hides(p.value)) return "";
+        if (p.value?.type === "ConditionalExpression") {
+          if (hides(p.value.consequent)) return `if ${code(p.value.test)}`;
+          if (hides(p.value.alternate)) return `unless ${code(p.value.test)}`;
+        }
+      }
+    }
+  }
+  return null;
+}
+function jsxName(n) {
+  if (n.type === "JSXMemberExpression") return `${jsxName(n.object)}.${n.property.name}`;
+  if (n.type === "JSXNamespacedName") return `${n.namespace.name}:${n.name.name}`;
+  return n.name;
+}
+var FAMILY = {
+  state: "state",
+  ref: "ref",
+  context: "context",
+  store: "store",
+  hook: "hook",
+  derived: "value",
+  memo: "value",
+  function: "fn",
+  callback: "fn",
+  effect: "effect",
+  render: "render",
+  constant: "constant"
+};
+var FIELD_KINDS = {
+  type: /* @__PURE__ */ new Set(["state", "ref", "context", "store", "hook", "derived", "memo", "function", "callback", "constant"]),
+  initial: /* @__PURE__ */ new Set(["state", "ref"]),
+  when: /* @__PURE__ */ new Set(["effect", "render"]),
+  returns: /* @__PURE__ */ new Set(["function", "callback", "effect"])
+};
+var baseName = (name) => name.replace(/\(.*$/s, "").trim();
+function mergeType(s, modelType) {
+  const fromSource = s.type ?? "";
+  if (!fromSource) return modelType;
+  const isSignature = s.kind === "function" || s.kind === "callback" || s.kind === "hook";
+  if (!isSignature || fromSource.includes("=>") || !modelType) return fromSource;
+  if (s.kind !== "hook" && modelType.includes("=>")) return modelType;
+  return `${fromSource} => ${modelType}`;
+}
+function mergeWithSource(card, source) {
+  const clean = (item) => {
+    const out = { ...item, children: (item.children ?? []).map(clean) };
+    for (const [field, kinds] of Object.entries(FIELD_KINDS)) if (!kinds.has(out.kind)) out[field] = "";
+    return out;
+  };
+  const outline = card.outline.map(clean);
+  if (!source) return { ...card, outline };
+  const described = new Map(card.props.map((p) => [p.name, p]));
+  const props = source.props.length ? [
+    ...source.props.map((p) => {
+      const ai = described.get(p.name);
+      described.delete(p.name);
+      return { ...p, type: p.type || ai?.type || "", description: ai?.description ?? "" };
+    }),
+    ...described.values()
+  ] : card.props;
+  const refs = new Set(card.usedIn.map((u) => u.ref));
+  const usedIn = [...card.usedIn, ...source.usedIn.filter((u) => !refs.has(u.ref))];
+  return { ...card, props, outline: mergeItems(outline, source.outline), usedIn };
+}
+function mergeItems(outline, source) {
+  const givenBy = /* @__PURE__ */ new Map();
+  for (const s of source) for (const c of s.children) if (c.reads !== void 0) givenBy.set(c.name, s);
+  if (givenBy.size) {
+    const declared = new Set(source.map((s) => baseName(s.name)));
+    outline = outline.filter((item) => {
+      const parent = item.kind === "render" || declared.has(baseName(item.name)) ? void 0 : givenBy.get(baseName(item.name));
+      const owner = parent && outline.find((o) => o !== item && FAMILY[o.kind] === FAMILY[parent.kind] && baseName(o.name) === baseName(parent.name));
+      if (!owner) return true;
+      owner.children = [...owner.children, item];
+      return false;
+    });
+  }
+  const sourceRenders = source.filter((s) => s.kind === "render");
+  const pool = sourceRenders.length ? outline.filter((i) => i.kind === "render").flatMap(flatRenders) : [];
+  if (pool.length) outline = outline.filter((i) => i.kind !== "render");
+  const unmatched = new Set(source.filter((s) => s.kind !== "render"));
+  const take = (pred) => {
+    const hit = [...unmatched].find(pred);
+    if (hit) unmatched.delete(hit);
+    return hit;
+  };
+  for (const item of outline) {
+    if (item.kind === "render") continue;
+    const family = FAMILY[item.kind];
+    const s = item.kind === "effect" ? (
+      // Effects have descriptive labels: pair them by line, else in order.
+      take((s2) => s2.kind === "effect" && Math.abs(s2.line - item.line) <= 1) ?? take((s2) => s2.kind === "effect")
+    ) : take((s2) => FAMILY[s2.kind] === family && baseName(s2.name) === baseName(item.name)) ?? take((s2) => baseName(s2.name) === baseName(item.name));
+    if (!s) continue;
+    if (item.kind !== "effect") item.name = s.name;
+    item.kind = s.kind;
+    item.line = s.line;
+    item.type = mergeType(s, item.type ?? "");
+    if (s.initial) item.initial = s.initial;
+    if (s.reads !== void 0) item.reads = s.reads;
+    if (s.hook) item.hook = s.hook;
+    if (s.from) item.from = s.from;
+    if ((s.kind === "ref" || s.kind === "memo" || s.kind === "callback") && s.when) item.when = s.when;
+    if (s.kind === "effect") {
+      if (s.when) item.when = s.when;
+      if (!item.returns) item.returns = s.returns;
+    }
+    item.children = mergeItems(item.children, s.children);
+  }
+  const merged = [...outline, ...unmatched, ...mergeRenders(sourceRenders, pool)];
+  merged.push(...pool.filter((p) => !p.used && !PLAIN_ELEMENT.test(p.name)).map(({ used: _, ...p }) => p));
+  return merged.sort((a, b) => a.line - b.line);
+}
+function flatRenders(item) {
+  return [{ ...item, children: [] }, ...item.children.filter((c) => c.kind === "render").flatMap(flatRenders)];
+}
+var tagName = (name) => name.replace(/[<>/\s]/g, "").replace(/^([a-z][\w-]*)[.#].*$/, "$1").toLowerCase();
+var PLAIN_ELEMENT = /^<?[a-z][\w-]*(?:[.#][\w-]+)*\s*\/?>?$/;
+function mergeRenders(nodes, pool) {
+  const nearest = (fits, line) => pool.filter((p) => !p.used && fits(p)).sort((a, b) => Math.abs(a.line - line) - Math.abs(b.line - line))[0];
+  return nodes.map((s) => {
+    const tag = tagName(s.name);
+    const named = labelPattern(s.name);
+    const m = nearest((p) => tagName(p.name) === tag, s.line) ?? nearest((p) => p.line === s.line, s.line) ?? nearest((p) => Math.abs(p.line - s.line) <= 3 && named.test(p.name), s.line);
+    if (m) m.used = true;
+    return { ...s, explanation: m?.explanation || s.explanation, children: mergeRenders(s.children, pool) };
+  });
+}
+function labelPattern(name) {
+  const words = name.replace(/[<>/\s]/g, "").split(/[.:_-]+|(?<=[a-z0-9])(?=[A-Z])/).filter(Boolean).map((w) => w.replace(/[$]/g, "\\$&"));
+  return new RegExp(`\\b${words.join("[\\s._-]*")}s?\\b`, "i");
+}
+var REF_TYPES = /^(React.)?(Ref|RefObject|ForwardedRef|MutableRefObject)$/;
+function refTarget(fn, name, parsed2) {
+  const src = (n) => n ? parsed2.source.slice(n.start, n.end) : "";
+  const unwrap = (t) => t?.type === "TSTypeReference" && REF_TYPES.test(src(t.typeName)) ? (t.typeParameters ?? t.typeArguments)?.params?.[0] : null;
+  const second = fn.params?.[1];
+  if (second?.type === "Identifier" && second.name === name) return unwrap(second.typeAnnotation?.typeAnnotation);
+  const member = propMembers(fn, parsed2).find((m) => (m.key?.name ?? m.key?.value) === name);
+  return unwrap(member?.typeAnnotation?.typeAnnotation);
+}
+function returnedExpression(fn) {
+  if (!/Function/.test(fn?.type ?? "")) return null;
+  const unwrap = (n) => n?.type === "ParenthesizedExpression" || /^TS(As|Satisfies)Expression$/.test(n?.type ?? "") ? unwrap(n.expression) : n;
+  return unwrap(fn.body.type === "BlockStatement" ? [...fn.body.body].reverse().find((s) => s.type === "ReturnStatement")?.argument : fn.body);
+}
+function returnedObject(fn) {
+  const obj = returnedExpression(fn);
+  return obj?.type === "ObjectExpression" ? obj : null;
+}
+function literalMembers(fn, src) {
+  const out = /* @__PURE__ */ new Map();
+  const member = (v) => /Function/.test(v?.type ?? "") ? { fn: true, type: signature2(v, src) } : { fn: false, type: literalType(v) };
+  const e = returnedExpression(fn);
+  if (e?.type === "ArrayExpression") e.elements.forEach((el, i) => el && out.set(i, member(el)));
+  for (const p of e?.type === "ObjectExpression" ? e.properties : []) {
+    const key = p.key?.name ?? p.key?.value;
+    if (key == null || p.computed) continue;
+    out.set(key, p.type === "ObjectMethod" ? { fn: true, type: `(${p.params.map(src).join(", ")})` } : member(p.value));
+  }
+  return out;
+}
+function propMembers(fn, parsed2) {
+  const param = fn.params?.[0];
+  if (!param) return [];
+  const pattern = param.type === "AssignmentPattern" ? param.left : param;
+  let typeNode = pattern.typeAnnotation?.typeAnnotation;
+  while (typeNode?.type === "TSTypeReference" && typeNode.typeName?.type === "Identifier") {
+    const decl = parsed2.typeDecls.get(typeNode.typeName.name);
+    if (decl) typeNode = decl.type === "TSInterfaceDeclaration" ? decl.body : decl.typeAnnotation;
+    else typeNode = (typeNode.typeParameters ?? typeNode.typeArguments)?.params?.[0];
+  }
+  return typeNode?.type === "TSTypeLiteral" ? typeNode.members : typeNode?.type === "TSInterfaceBody" ? typeNode.body : [];
+}
+function propsOf(fn, parsed2, src) {
+  const param = fn.params?.[0];
+  if (!param) return [];
+  const pattern = param.type === "AssignmentPattern" ? param.left : param;
+  const members = propMembers(fn, parsed2);
+  const out = [];
+  for (const m of members) {
+    const name = m.key?.type === "Identifier" ? m.key.name : m.key?.value;
+    if (!name) continue;
+    const type = m.type === "TSMethodSignature" ? `(${m.params?.map(src).join(", ") ?? ""}) => ${src(m.returnType?.typeAnnotation) || "void"}` : src(m.typeAnnotation?.typeAnnotation);
+    out.push({ name, type, optional: !!m.optional, description: "" });
+  }
+  if (!out.length && pattern.type === "ObjectPattern") {
+    for (const p of pattern.properties) {
+      const name = p.key?.type === "Identifier" ? p.key.name : null;
+      if (name) out.push({ name, type: "", optional: p.value?.type === "AssignmentPattern", description: "" });
+    }
+  }
+  return out;
+}
+function boundNames(id) {
+  if (id.type === "Identifier") return [id.name];
+  if (id.type === "ArrayPattern") {
+    return id.elements.map((el) => {
+      const target = el?.type === "AssignmentPattern" ? el.left : el?.type === "RestElement" ? el.argument : el;
+      return target?.type === "Identifier" ? target.name : "";
+    });
+  }
+  if (id.type === "ObjectPattern") {
+    return id.properties.map((p) => p.type === "RestElement" ? p.argument : p.value?.type === "AssignmentPattern" ? p.value.left : p.value).filter((v) => v?.type === "Identifier").map((v) => v.name);
+  }
+  return [];
+}
+function hookSignature(root, file, hook) {
+  const found = findFunction(root, file, hook, 1);
+  const parsed2 = found && parseFile(root, found.file);
+  if (!found || !parsed2) return "";
+  return signature2(found.fn, (n) => n ? parsed2.source.slice(n.start, n.end) : "");
+}
+function givenItems(make, id, node, members) {
+  return givenNames(id).map(({ key, name }) => {
+    const member = members.get(key);
+    return make(member?.fn ? "function" : "derived", name, node, { type: member?.type ?? "", reads: String(key) });
+  });
+}
+function givenNames(id) {
+  const local = (v) => v?.type === "AssignmentPattern" ? v.left : v;
+  if (id.type === "ObjectPattern") {
+    return id.properties.filter((p) => local(p.value)?.type === "Identifier" && (p.key?.type === "Identifier" || p.key?.type === "StringLiteral")).map((p) => ({ key: p.key.name ?? p.key.value, name: local(p.value).name }));
+  }
+  if (id.type === "ArrayPattern") {
+    return id.elements.flatMap((el, i) => local(el)?.type === "Identifier" ? [{ key: i, name: local(el).name }] : []);
+  }
+  return [];
+}
+function typeMembers(t, parsed2, depth = 0) {
+  const src = (n) => n ? parsed2.source.slice(n.start, n.end) : "";
+  const out = /* @__PURE__ */ new Map();
+  if (!t || depth > 4) return out;
+  if (t.type === "TSUnionType") return typeMembers(t.types.find((u) => !/^TS(Null|Undefined)Keyword$/.test(u.type)), parsed2, depth + 1);
+  if (t.type === "TSTypeOperator") return typeMembers(t.typeAnnotation, parsed2, depth + 1);
+  if (t.type === "TSTypeReference" && t.typeName?.type === "Identifier") {
+    const decl = parsed2.typeDecls.get(t.typeName.name);
+    return typeMembers(decl?.type === "TSInterfaceDeclaration" ? decl.body : decl?.typeAnnotation, parsed2, depth + 1);
+  }
+  if (t.type === "TSTupleType") {
+    t.elementTypes.forEach((e, i) => {
+      const el = e.type === "TSNamedTupleMember" ? e.elementType : e;
+      out.set(i, { fn: el.type === "TSFunctionType", type: src(el) });
+    });
+  }
+  for (const m of t.type === "TSTypeLiteral" ? t.members : t.type === "TSInterfaceBody" ? t.body : []) {
+    const key = m.key?.name ?? m.key?.value;
+    if (key == null) continue;
+    if (m.type === "TSMethodSignature") out.set(key, { fn: true, type: `(${m.params?.map(src).join(", ") ?? ""}) => ${src(m.returnType?.typeAnnotation) || "void"}` });
+    else out.set(key, { fn: m.typeAnnotation?.typeAnnotation?.type === "TSFunctionType", type: src(m.typeAnnotation?.typeAnnotation) });
+  }
+  return out;
+}
+function hookGives(root, file, hook) {
+  const found = findFunction(root, file, hook, 1);
+  const parsed2 = found && parseFile(root, found.file);
+  if (!found || !parsed2) return /* @__PURE__ */ new Map();
+  const src = (n) => n ? parsed2.source.slice(n.start, n.end) : "";
+  const unwrap = (n) => /^TS(As|Satisfies|NonNull)Expression$|^ParenthesizedExpression$/.test(n?.type) ? unwrap(n.expression) : n;
+  const typeArg = (call) => call?.typeParameters?.params?.[0] ?? call?.typeArguments?.params?.[0];
+  const typeShape = (t) => typeMembers(t, parsed2);
+  if (found.fn.returnType) return typeShape(found.fn.returnType.typeAnnotation);
+  const stmts = found.fn.body?.type === "BlockStatement" ? found.fn.body.body : [];
+  const locals = /* @__PURE__ */ new Map();
+  for (const stmt of stmts) {
+    if (stmt.type === "FunctionDeclaration" && stmt.id) locals.set(stmt.id.name, { fn: true, type: signature2(stmt, src) });
+    if (stmt.type !== "VariableDeclaration") continue;
+    for (const d of stmt.declarations) {
+      if (d.id.type === "Identifier") locals.set(d.id.name, d);
+      else if (d.id.type === "ArrayPattern" && d.init?.type === "CallExpression" && /^use(State|Reducer)$/.test(calleeName(d.init) ?? "")) {
+        const [value, set] = d.id.elements;
+        const initial = d.init.arguments[calleeName(d.init) === "useState" ? 0 : 1];
+        const type = src(typeArg(d.init)) || literalType(initial) || (initial?.type === "Identifier" ? paramType(found.fn, initial.name, src) : "");
+        if (value?.type === "Identifier") locals.set(value.name, { fn: false, type });
+        if (set?.type === "Identifier") locals.set(set.name, { fn: true, type: "" });
+      }
+    }
+  }
+  const memberOf = (expr) => {
+    const e = unwrap(expr);
+    if (/Function/.test(e?.type)) return { fn: true, type: signature2(e, src) };
+    const call = e?.type === "CallExpression" ? calleeName(e) : null;
+    if (call === "useCallback") return { fn: true, type: signature2(e.arguments[0], src) };
+    if (call === "useMemo") return { fn: false, type: src(typeArg(e)) };
+    if (e?.type === "Identifier") {
+      const local = locals.get(e.name);
+      if (local && "fn" in local) return local;
+      if (local) return local.id.typeAnnotation ? { fn: false, type: src(local.id.typeAnnotation.typeAnnotation) } : memberOf(local.init);
+      const fn = parsed2.functions.get(e.name);
+      if (fn) return { fn: true, type: signature2(fn, src) };
+    }
+    return { fn: false, type: literalType(e) };
+  };
+  const shape = (expr, depth = 0) => {
+    const e = unwrap(expr);
+    const out = /* @__PURE__ */ new Map();
+    if (e?.type === "ObjectExpression") {
+      for (const p of e.properties) {
+        const key = p.key?.name ?? p.key?.value;
+        if (key == null || p.computed) continue;
+        out.set(key, p.type === "ObjectMethod" ? { fn: true, type: `(${p.params.map(src).join(", ")})` } : memberOf(p.value));
+      }
+    } else if (e?.type === "ArrayExpression") {
+      e.elements.forEach((el, i) => el && out.set(i, memberOf(el)));
+    } else if (e?.type === "CallExpression" && /^use(Context)?$/.test(calleeName(e) ?? "") && e.arguments[0]?.type === "Identifier") {
+      return typeShape(typeArg(parsed2.contexts.get(e.arguments[0].name)));
+    } else if (e?.type === "Identifier" && depth < 4) {
+      const local = locals.get(e.name);
+      if (local && !("fn" in local)) return local.id.typeAnnotation ? typeShape(local.id.typeAnnotation.typeAnnotation) : shape(local.init, depth + 1);
+    }
+    return out;
+  };
+  const returned = found.fn.body?.type === "BlockStatement" ? [...stmts].reverse().find((s) => s.type === "ReturnStatement")?.argument : found.fn.body;
+  return shape(returned);
+}
+function contextMembers(root, file, name) {
+  const found = findContext(root, file, name);
+  const t = found && (found.call.typeParameters?.params?.[0] ?? found.call.typeArguments?.params?.[0]);
+  return t ? typeMembers(t, found.parsed) : /* @__PURE__ */ new Map();
+}
+function hookReturnType(root, file, hook) {
+  const found = findFunction(root, file, hook, 1);
+  const parsed2 = found && parseFile(root, found.file);
+  const t = found?.fn.returnType?.typeAnnotation;
+  return parsed2 && t ? parsed2.source.slice(t.start, t.end) : "";
+}
+function contextType(root, file, name) {
+  const found = findContext(root, file, name);
+  if (!found) return "";
+  const { call, parsed: parsed2 } = found;
+  const t = call.typeParameters?.params?.[0] ?? call.typeArguments?.params?.[0];
+  return t ? parsed2.source.slice(t.start, t.end) : literalType(call.arguments[0]);
+}
+function paramType(fn, name, src) {
+  const fromDefault = (p) => src(p.left.typeAnnotation?.typeAnnotation) || literalType(p.right);
+  for (const p of fn?.params ?? []) {
+    if (p.type === "Identifier" && p.name === name) return src(p.typeAnnotation?.typeAnnotation);
+    if (p.type === "AssignmentPattern" && p.left.type === "Identifier" && p.left.name === name) return fromDefault(p);
+    const pattern = p.type === "AssignmentPattern" ? p.left : p;
+    if (pattern.type !== "ObjectPattern") continue;
+    for (const prop of pattern.properties) {
+      if (prop.value?.type === "AssignmentPattern" && prop.value.left.name === name) return literalType(prop.value.right);
+    }
+  }
+  return "";
+}
+function signature2(fn, src) {
+  if (!fn || !/Function/.test(fn.type)) return "";
+  const ret = src(fn.returnType?.typeAnnotation);
+  return `(${fn.params.map(src).join(", ")})${ret ? ` => ${ret}` : ""}`;
+}
+function literalType(node) {
+  switch (node?.type) {
+    case "StringLiteral":
+    case "TemplateLiteral":
+      return "string";
+    case "NumericLiteral":
+      return "number";
+    case "BooleanLiteral":
+      return "boolean";
+    case "NullLiteral":
+      return "null";
+    default:
+      return "";
+  }
+}
+function hasCleanup(fn) {
+  if (!fn || !/Function/.test(fn.type) || fn.body?.type !== "BlockStatement") return false;
+  return fn.body.body.some((s) => s.type === "ReturnStatement" && s.argument);
+}
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "build", ".next", "out", "coverage", ".turbo", ".vercel", ".cache", ".react-detective"]);
+var SOURCE_EXT = /\.(tsx|jsx|ts|js|mdx)$/;
+var MAX_FILES2 = 4e3;
+function findUsages(root, component, limit = 20) {
+  const re = new RegExp(`<${component.replace(/[$.]/g, "\\$&")}[\\s/>]`);
+  const out = [];
+  let seen = 0;
+  const visit = (dir) => {
+    let entries;
+    try {
+      entries = fs5.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (out.length >= limit || seen >= MAX_FILES2) return;
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name) && !e.name.startsWith(".")) visit(path6.join(dir, e.name));
+        continue;
+      }
+      if (!SOURCE_EXT.test(e.name)) continue;
+      seen++;
+      const abs = path6.join(dir, e.name);
+      let text;
+      try {
+        text = fs5.readFileSync(abs, "utf8");
+      } catch {
+        continue;
+      }
+      if (!re.test(text)) continue;
+      const rel = path6.relative(root, abs).split(path6.sep).join("/");
+      text.split(/\r?\n/).forEach((line, i) => {
+        if (out.length < limit && re.test(line)) out.push(`${rel}:${i + 1}`);
+      });
+    }
+  };
+  visit(root);
+  return out;
+}
+
+// src/server/callsites.ts
+import { parse as parse4 } from "@babel/parser";
+import fs6 from "fs";
+import path7 from "path";
+var asts = /* @__PURE__ */ new Map();
+function parsed(root, rel) {
+  const abs = path7.join(root, rel);
+  let mtimeMs;
+  try {
+    mtimeMs = fs6.statSync(abs).mtimeMs;
+  } catch {
+    return null;
+  }
+  const hit = asts.get(abs);
+  if (hit !== void 0 && hit?.mtimeMs === mtimeMs) return hit;
+  let entry = null;
+  try {
+    const source = fs6.readFileSync(abs, "utf8").replace(/\r\n/g, "\n");
+    entry = { mtimeMs, source, ast: parse4(source, { sourceType: "module", errorRecovery: true, plugins: ["typescript", "jsx", "decorators-legacy"] }) };
+  } catch {
+  }
+  asts.set(abs, entry);
+  return entry;
+}
+function describeCallSites(root, component, usedIn) {
+  return usedIn.map((u) => {
+    const m = u.ref.match(/^(.+?):(\d+)(?::\d+)?$/);
+    const file = m && parsed(root, m[1]);
+    if (!m || !file) return u;
+    const found = findElement(file.ast, component, Number(m[2]));
+    if (!found) return u;
+    const src = (n) => file.source.slice(n.start, n.end);
+    const declaredAt = (name) => declarationLine(name, found.scopes);
+    const props = [];
+    for (const attr of found.element.openingElement.attributes) {
+      if (attr.type === "JSXSpreadAttribute") {
+        props.push(withLine({ name: "...", value: src(attr.argument) }, attr.argument, declaredAt));
+        continue;
+      }
+      const name = attr.name.type === "JSXNamespacedName" ? `${attr.name.namespace.name}:${attr.name.name.name}` : attr.name.name;
+      const v = attr.value;
+      if (!v) props.push({ name, value: "true" });
+      else if (v.type === "StringLiteral") props.push({ name, value: JSON.stringify(v.value) });
+      else if (v.type === "JSXExpressionContainer" && v.expression.type !== "JSXEmptyExpression") props.push(withLine({ name, value: src(v.expression) }, v.expression, declaredAt));
+      else props.push({ name, value: src(v) });
+    }
+    const children = found.element.children.filter((c) => !(c.type === "JSXText" && !c.value.trim()) && c.type !== "JSXEmptyExpression");
+    if (children.length) props.push({ name: "children", value: children.map((c) => c.type === "JSXText" ? c.value.trim() : src(c)).join(" ") });
+    return { ...u, parent: found.parent, props };
+  });
+}
+function withLine(prop, expr, declaredAt) {
+  let base = expr;
+  while (base?.type === "MemberExpression" || base?.type === "OptionalMemberExpression") base = base.object;
+  const line = base?.type === "Identifier" ? declaredAt(base.name) : void 0;
+  return line ? { ...prop, line } : prop;
+}
+function findElement(ast, component, line) {
+  let result = null;
+  const visit = (node, scopes, parent) => {
+    if (result || !node || typeof node !== "object") return;
+    if (Array.isArray(node)) return node.forEach((n) => visit(n, scopes, parent));
+    if (node.type === "JSXElement" && node.loc?.start.line === line && jsxName2(node.openingElement.name) === component) {
+      result = { element: node, parent, scopes };
+      return;
+    }
+    let inner = scopes;
+    let name = parent;
+    if (/Function/.test(node.type) || node.type === "Program") {
+      inner = [node, ...scopes];
+      name = functionName(node) ?? parent;
+    }
+    for (const key of Object.keys(node)) {
+      if (key === "loc" || key === "start" || key === "end" || key.endsWith("Comments")) continue;
+      const child = node[key];
+      if (node.type === "VariableDeclarator" && key === "init" && /Function/.test(child?.type ?? "") && node.id.type === "Identifier") {
+        child.__name = node.id.name;
+      }
+      visit(child, inner, name);
+    }
+  };
+  visit(ast.program, []);
+  return result;
+}
+function jsxName2(n) {
+  return n.type === "JSXIdentifier" ? n.name : n.type === "JSXMemberExpression" ? `${jsxName2(n.object)}.${n.property.name}` : "";
+}
+function functionName(fn) {
+  return fn.id?.name ?? fn.__name;
+}
+function declarationLine(name, scopes) {
+  for (const scope of scopes) {
+    const params = scope.type === "Program" ? [] : scope.params;
+    for (const p of params) {
+      const line = bindingLine(p, name);
+      if (line) return line;
+    }
+    const body = scope.type === "Program" ? scope.body : scope.body?.type === "BlockStatement" ? scope.body.body : [];
+    for (let stmt of body) {
+      if ((stmt.type === "ExportNamedDeclaration" || stmt.type === "ExportDefaultDeclaration") && stmt.declaration) stmt = stmt.declaration;
+      if (stmt.type === "FunctionDeclaration" && stmt.id?.name === name) return stmt.loc.start.line;
+      if (stmt.type === "ImportDeclaration" && stmt.specifiers.some((s) => s.local.name === name)) return stmt.loc.start.line;
+      if (stmt.type !== "VariableDeclaration") continue;
+      for (const d of stmt.declarations) {
+        const line = bindingLine(d.id, name);
+        if (line) return line;
+      }
+    }
+  }
+  return void 0;
+}
+function bindingLine(p, name) {
+  if (!p) return void 0;
+  if (p.type === "Identifier") return p.name === name ? p.loc.start.line : void 0;
+  if (p.type === "AssignmentPattern") return bindingLine(p.left, name);
+  if (p.type === "RestElement") return bindingLine(p.argument, name);
+  if (p.type === "TSParameterProperty") return bindingLine(p.parameter, name);
+  const parts = p.type === "ArrayPattern" ? p.elements : p.type === "ObjectPattern" ? p.properties.map((prop) => prop.type === "RestElement" ? prop : prop.value) : [];
+  for (const part of parts) {
+    const line = bindingLine(part, name);
+    if (line) return line;
+  }
+  return void 0;
+}
+
+// src/server/tstypes.ts
+import fs7 from "fs";
+import { createRequire } from "module";
+import path8 from "path";
+var services = /* @__PURE__ */ new Map();
+var WARM_UP_DELAY = 3e3;
+var MAX_TYPE = 120;
+function warmUpTypes(root, delay = WARM_UP_DELAY) {
+  if (services.has(root)) return Promise.resolve();
+  services.set(root, "starting");
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      try {
+        services.set(root, createService(root));
+      } catch {
+        services.set(root, null);
+      }
+      resolve();
+    }, delay).unref();
+  });
+}
+function createService(root) {
+  let ts;
+  try {
+    ts = createRequire(path8.join(root, "package.json"))("typescript");
+  } catch {
+    return null;
+  }
+  const configFile = ts.findConfigFile(root, ts.sys.fileExists, "tsconfig.json");
+  const config = configFile ? ts.parseJsonConfigFileContent(ts.readConfigFile(configFile, ts.sys.readFile).config, ts.sys, path8.dirname(configFile)) : { fileNames: [], options: { jsx: ts.JsxEmit.ReactJSX, allowJs: true, strict: true } };
+  const files = new Set(config.fileNames.map((f) => path8.resolve(f)));
+  const version = (f) => {
+    try {
+      return String(fs7.statSync(f).mtimeMs);
+    } catch {
+      return "0";
+    }
+  };
+  const host = {
+    getScriptFileNames: () => [...files],
+    getScriptVersion: version,
+    getScriptSnapshot: (f) => fs7.existsSync(f) ? ts.ScriptSnapshot.fromString(fs7.readFileSync(f, "utf8")) : void 0,
+    getCurrentDirectory: () => root,
+    getCompilationSettings: () => ({ ...config.options, noEmit: true }),
+    getDefaultLibFileName: (o) => ts.getDefaultLibFilePath(o),
+    fileExists: ts.sys.fileExists,
+    readFile: ts.sys.readFile,
+    readDirectory: ts.sys.readDirectory,
+    directoryExists: ts.sys.directoryExists,
+    getDirectories: ts.sys.getDirectories
+  };
+  const service = ts.createLanguageService(host, ts.createDocumentRegistry());
+  service.getProgram();
+  return { ts, service };
+}
+function withCheckedTypes(root, file, card) {
+  const entry = services.get(root);
+  if (!file || !entry || entry === "starting") return card;
+  const { ts, service } = entry;
+  const abs = path8.resolve(root, file);
+  const program = service.getProgram();
+  const sf = program?.getSourceFile(abs);
+  if (!program || !sf) return card;
+  const checker = program.getTypeChecker();
+  const lines = sf.text.split("\n");
+  const identifierAt = (name, line) => {
+    const word = new RegExp(`(?<![\\w$])${name.replace(/\$/g, "\\$")}(?![\\w$])`);
+    for (let l = line - 1; l < Math.min(lines.length, line + 9); l++) {
+      const col = lines[l]?.search(word) ?? -1;
+      if (col < 0) continue;
+      const pos = sf.getPositionOfLineAndCharacter(l, col);
+      const node = deepest(ts, sf, pos);
+      if (node && ts.isIdentifier(node) && node.text === name) return node;
+    }
+    return null;
+  };
+  const show = (type, at) => {
+    const text = checker.typeToString(type, at, ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope);
+    return text.length > MAX_TYPE || text === "any" ? "" : text;
+  };
+  const fill = (item) => {
+    const children = item.children.map(fill);
+    if (item.type) return { ...item, children };
+    let type = "";
+    try {
+      if (item.kind === "hook") {
+        const callee = identifierAt(item.name.replace(/\(.*$/s, ""), item.line);
+        const call = callee?.parent && ts.isCallExpression(callee.parent) ? callee.parent : null;
+        const sig = call && checker.getResolvedSignature(call);
+        if (sig) {
+          const ret = show(sig.getReturnType(), call);
+          if (ret) type = `(${sig.parameters.map((p) => p.name).join(", ")}) => ${ret}`;
+        }
+      } else if (["state", "ref", "derived", "memo", "context", "store", "constant", "function", "callback"].includes(item.kind) && /^[\w$]+$/.test(item.name)) {
+        const id = identifierAt(item.name, item.line);
+        if (id) type = show(checker.getTypeAtLocation(id), id);
+      }
+    } catch {
+    }
+    return { ...item, type, children };
+  };
+  return { ...card, outline: card.outline.map(fill) };
+}
+function deepest(ts, sf, pos) {
+  let found = null;
+  const visit = (node) => {
+    if (pos < node.getStart(sf) || pos >= node.getEnd()) return;
+    found = node;
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return found;
+}
+
+// src/server/handler.ts
+var MAX_FILE_DIFF = 8e3;
+var MAX_TOTAL_DIFF = 2e4;
+var MAX_PRELOAD_FILE = 16e3;
+var MAX_PRELOAD_TOTAL = 36e3;
+var MAX_IMPORT_NOTES = 8e3;
+var DEFAULT_MODEL = "sonnet";
+function createDetectiveHandler(opts) {
+  const base = opts.base ?? "/__detective";
+  const root = path9.resolve(opts.root);
+  const store = new KnowledgeStore(root, opts.storeDir);
+  warmUpTypes(root);
+  const git = new Git(root);
+  return async function handle(req, res, next) {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    if (!url.pathname.startsWith(base)) return next ? next() : notFound(res);
+    const origin = req.headers.origin;
+    if (origin && !isLocalOrigin(origin)) return send(res, 403, { error: "Only local origins may use react-detective." });
+    if (origin) {
+      res.setHeader("Access-Control-Allow-Origin", origin);
+      res.setHeader("Access-Control-Allow-Headers", "content-type");
+      res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+      res.setHeader("Vary", "Origin");
+    }
+    if (req.method === "OPTIONS") return send(res, 204);
+    const route = url.pathname.slice(base.length);
+    try {
+      if (route === "/health" && req.method === "GET") return send(res, 200, { ok: true, root });
+      if (route === "/open" && req.method === "POST") {
+        const body = await readJson(req);
+        const file = safeResolve(root, body.file);
+        if (!file) return send(res, 400, { error: "Invalid file" });
+        launchEditor(`${file}:${Number(body.line) || 1}:${Number(body.column) || 1}`);
+        return send(res, 200, { ok: true });
+      }
+      if (route === "/explain" && req.method === "POST") return explain(await readJson(req), res);
+    } catch (err) {
+      return send(res, 500, { error: String(err?.message ?? err) });
+    }
+    return notFound(res);
+  };
+  async function explain(body, res) {
+    if (!body?.component || typeof body.component !== "string") return send(res, 400, { error: "component is required" });
+    if (body.file && !safeResolve(root, body.file)) return send(res, 400, { error: "Invalid file" });
+    res.writeHead(200, { "Content-Type": "application/x-ndjson; charset=utf-8", "Cache-Control": "no-cache", "X-Accel-Buffering": "no" });
+    const emit = (event) => res.write(JSON.stringify(event) + "\n");
+    const rec = store.getComponent(body.component, body.file);
+    const saved = isCurrentCard(rec.explanation?.card) ? rec.explanation : void 0;
+    const context = {};
+    const reliedOn = new Set(body.file ? [body.file] : []);
+    const slotsFor = () => hookSlots(root, body.file, body.component);
+    const fromSource = (card) => card ? withCheckedTypes(root, body.file, { ...card, usedIn: describeCallSites(root, body.component, card.usedIn) }) : card;
+    const typesFor = (content) => resolveTypes(root, body.file, typeof content === "string" ? content : JSON.stringify(content));
+    const gitInfo = (async () => {
+      const isRepo2 = await git.isRepo();
+      if (!isRepo2 || !body.file) return { isRepo: isRepo2, history: [], uncommitted: false };
+      const [history2, uncommitted] = await Promise.all([git.recentCommits(body.file, 5), body.question ? false : git.isDirty([body.file])]);
+      return { isRepo: isRepo2, history: history2, uncommitted };
+    })();
+    let contextSent = false;
+    const sendContext = async () => {
+      const g = await gitInfo;
+      if (contextSent || body.question || !g.isRepo || !body.file) return;
+      contextSent = true;
+      emit({ type: "context", lastChange: g.history[0] ?? null, uncommitted: g.uncommitted });
+    };
+    const finishCached = async (event) => {
+      emit(event);
+      await sendContext();
+      res.end();
+    };
+    let prev;
+    if (body.question) {
+      prev = store.findQuestion(rec, body.question);
+      if (prev && !body.refresh && store.check(prev.deps).fresh) {
+        return finishCached({ type: "result", markdown: prev.answer, types: typesFor(prev.answer), cached: true, createdAt: prev.createdAt, git: prev.git });
+      }
+      if (saved && store.check(saved.deps).fresh) {
+        context.explanation = saved.markdown;
+        Object.keys(saved.deps).forEach((f) => reliedOn.add(f));
+      }
+    } else {
+      emit({
+        type: "history",
+        questions: rec.questions.map((q) => ({
+          question: q.question,
+          answer: q.answer,
+          createdAt: q.createdAt,
+          stale: !store.check(q.deps).fresh
+        }))
+      });
+      if (saved?.card && !body.refresh) {
+        const { fresh, changed } = store.check(saved.deps);
+        const card = fromSource(mergeWithSource(saved.card, skeletonCard(root, body.file, body.component)));
+        if (fresh) {
+          return finishCached({ type: "result", markdown: saved.markdown, card, types: typesFor(card), slots: slotsFor(), cached: true, createdAt: saved.createdAt, git: saved.git });
+        }
+        const changes = await describeChanges(saved.deps, changed);
+        emit({ type: "stale", markdown: saved.markdown, card, types: typesFor(card), slots: slotsFor(), changes, createdAt: saved.createdAt, git: saved.git });
+        context.previous = { markdown: saved.markdown, changes, unchanged: Object.keys(saved.deps) };
+        Object.keys(saved.deps).forEach((f) => reliedOn.add(f));
+      }
+    }
+    const usages = findUsages(root, body.component);
+    if (!body.question && !context.previous) {
+      const skeleton = fromSource(skeletonCard(root, body.file, body.component, usages));
+      if (skeleton) emit({ type: "skeleton", card: skeleton, types: typesFor(skeleton), slots: slotsFor() });
+    }
+    const apiKey = findApiKey(root);
+    if (!apiKey) {
+      emit({ type: "error", code: "no-api-key", message: MISSING_KEY_MESSAGE(root) });
+      await sendContext();
+      return void res.end();
+    }
+    await sendContext();
+    const { isRepo, history } = await gitInfo;
+    if (history.length) context.history = history;
+    const related = relatedRecords(rec, body);
+    context.pastQuestions = pastAnswers(rec, related, reliedOn, prev);
+    context.notes = relevantNotes(rec, body.file, related);
+    Object.keys(context.notes).forEach((f) => reliedOn.add(f));
+    context.imports = importedExports(body.file, reliedOn);
+    context.usages = usages;
+    context.sources = preloadSources(body.file, context);
+    Object.keys(context.sources).forEach((f) => reliedOn.add(f));
+    const abort = new AbortController();
+    res.on("close", () => {
+      if (!res.writableFinished) abort.abort();
+    });
+    try {
+      const model = opts.model ?? DEFAULT_MODEL;
+      const result = await explainComponent(body, {
+        root,
+        model,
+        maxTurns: opts.maxTurns,
+        signal: abort.signal,
+        context,
+        apiKey,
+        git: isRepo ? git : void 0,
+        onProgress: (text) => emit({ type: "progress", text })
+      });
+      if (result.card) {
+        result.card = fromSource(mergeWithSource(result.card, skeletonCard(root, body.file, body.component, usages)));
+        result.markdown = cardToMarkdown(result.card);
+      }
+      const deps = store.snapshot([...reliedOn, ...result.filesRead]);
+      store.saveBlobs(deps);
+      store.saveNotes(result.notes, store.snapshot([...result.filesRead, ...Object.keys(context.sources ?? {})]), result.exports);
+      const stamp = await gitStamp(Object.keys(deps));
+      const now = Date.now();
+      if (body.question) {
+        store.saveQuestion(body.component, body.file, { question: body.question, answer: result.markdown, deps, createdAt: now, git: stamp });
+      } else {
+        store.saveExplanation(body.component, body.file, { markdown: result.markdown, card: result.card, deps, createdAt: now, model: result.model ?? model, git: stamp });
+      }
+      emit({
+        type: "result",
+        markdown: result.markdown,
+        card: result.card,
+        types: typesFor(result.card ?? result.markdown),
+        slots: body.question ? void 0 : slotsFor(),
+        cached: false,
+        costUsd: result.costUsd,
+        turns: result.turns,
+        model: result.model ?? model,
+        filesRead: result.filesRead.length,
+        notesReused: Object.keys(context.notes ?? {}).length,
+        exportsReused: context.imports?.length ?? 0,
+        answersReused: context.pastQuestions?.length ?? 0,
+        git: stamp
+      });
+    } catch (err) {
+      if (!abort.signal.aborted) emit({ type: "error", message: friendlyError(err) });
+    }
+    res.end();
+  }
+  async function describeChanges(deps, changed) {
+    let budget = MAX_TOTAL_DIFF;
+    const out = [];
+    for (const file of changed) {
+      const now = store.readFile(file);
+      if (now === null) {
+        out.push({ file, deleted: true });
+        continue;
+      }
+      const old = store.readBlob(deps[file]) ?? (await git.catBlob(deps[file]))?.replace(/\r\n/g, "\n") ?? null;
+      if (old === null) {
+        out.push({ file });
+        continue;
+      }
+      const diff = createTwoFilesPatch(`a/${file}`, `b/${file}`, old, now, "explained version", "now", { context: 3 }).replace(/^=+\n/, "").trimEnd();
+      if (diff.length > MAX_FILE_DIFF || diff.length > budget) out.push({ file });
+      else {
+        budget -= diff.length;
+        out.push({ file, diff });
+      }
+    }
+    return out;
+  }
+  async function gitStamp(files) {
+    const head = await git.head();
+    return head ? { ...head, dirty: await git.isDirty(files) } : void 0;
+  }
+  function relatedRecords(rec, body) {
+    const names = new Set((body.chain ?? []).filter((c) => c !== body.component));
+    const files = new Set(body.file ? localImports(root, body.file) : []);
+    callerFiles(rec).forEach((f) => files.add(f));
+    if (body.file) files.add(body.file);
+    return store.listComponents().filter((r) => !(r.component === body.component && r.file === (body.file ?? null))).filter((r) => names.has(r.component) || r.file && files.has(r.file));
+  }
+  function callerFiles(rec) {
+    const usedIn = isCurrentCard(rec.explanation?.card) ? rec.explanation.card.usedIn : [];
+    return usedIn.map((u) => u.ref.replace(/:\d+(:\d+)?$/, "")).filter((f) => !!safeResolve(root, f));
+  }
+  function pastAnswers(rec, related, reliedOn, exclude) {
+    const own = rec.questions.filter((q) => q !== exclude && store.check(q.deps).fresh).slice(-5).reverse().map((entry) => ({ entry }));
+    const others = related.flatMap((r) => r.questions.map((entry) => ({ entry, component: r.component }))).filter((c) => store.check(c.entry.deps).fresh).sort((a, b) => b.entry.createdAt - a.entry.createdAt).slice(0, 4);
+    const out = [];
+    let budget = 8e3;
+    for (const { entry, component } of [...own, ...others]) {
+      const answer = entry.answer.slice(0, 1500);
+      if ((budget -= answer.length + entry.question.length) < 0) break;
+      out.push({ question: entry.question, answer, component });
+      if (!component) Object.keys(entry.deps).forEach((f) => reliedOn.add(f));
+    }
+    return out;
+  }
+  function preloadSources(file, ctx) {
+    const out = {};
+    if (!file) return out;
+    const changedWithDiff = new Set((ctx.previous?.changes ?? []).filter((c) => c.diff).map((c) => c.file));
+    const unchanged = new Set(ctx.previous?.unchanged ?? []);
+    let budget = MAX_PRELOAD_TOTAL;
+    const described = /* @__PURE__ */ new Set();
+    for (const { file: from, names } of importsOf(root, file)) {
+      if (!names.includes("*") && names.every((n) => ctx.imports?.some((i) => i.from === from && i.name === n))) described.add(from);
+    }
+    const add = (f) => {
+      if (out[f] !== void 0 || changedWithDiff.has(f) || unchanged.has(f) || ctx.notes?.[f] || described.has(f)) return;
+      const text = store.readFile(f);
+      if (text === null || text.length > MAX_PRELOAD_FILE || text.length > budget) return;
+      budget -= text.length;
+      out[f] = text;
+    };
+    const own = store.readFile(file);
+    if (own !== null && own.length <= MAX_PRELOAD_FILE && !changedWithDiff.has(file) && !(ctx.previous && unchanged.has(file))) {
+      budget -= own.length;
+      out[file] = own;
+    }
+    if (!ctx.previous) localImports(root, file).forEach(add);
+    return out;
+  }
+  function importedExports(file, reliedOn) {
+    if (!file) return [];
+    const out = [];
+    let budget = MAX_IMPORT_NOTES;
+    for (const { file: from, names } of importsOf(root, file)) {
+      const exported = exportsOf(root, from);
+      const wanted = names.includes("*") ? [...exported.keys()] : names;
+      for (const name of wanted) {
+        const e = exported.get(name);
+        if (!e) continue;
+        const own = store.validExports(e.file);
+        const description = own[e.declaredAs] ?? (e.declaredAs === "default" ? own[e.local] : void 0) ?? (e.file !== from ? store.validExports(from)[name] : void 0);
+        if (!description) continue;
+        const entry = { name, from, declaredIn: e.file !== from ? e.file : void 0, line: e.line, kind: e.kind, signature: e.signature, description };
+        if ((budget -= description.length + e.signature.length + name.length + from.length) < 0) return out;
+        out.push(entry);
+        reliedOn.add(e.file);
+        reliedOn.add(from);
+      }
+    }
+    return out;
+  }
+  function relevantNotes(rec, file, related) {
+    const candidates = /* @__PURE__ */ new Set();
+    if (file) {
+      candidates.add(file);
+      localImports(root, file).forEach((f) => candidates.add(f));
+    }
+    callerFiles(rec).forEach((f) => candidates.add(f));
+    related.forEach((r) => r.file && candidates.add(r.file));
+    Object.keys(rec.explanation?.deps ?? {}).forEach((f) => candidates.add(f));
+    rec.questions.forEach((q) => Object.keys(q.deps).forEach((f) => candidates.add(f)));
+    const out = {};
+    let budget = 12e3;
+    const close = store.validNotes(candidates);
+    const rest = store.validNotes(store.noteFiles().filter((f) => !candidates.has(f)));
+    for (const [f, summary] of [...Object.entries(close), ...Object.entries(rest)]) {
+      if ((budget -= summary.length + f.length) < 0) break;
+      out[f] = summary;
+    }
+    return out;
+  }
+}
+function isLocalOrigin(origin) {
+  try {
+    const { hostname } = new URL(origin);
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname.endsWith(".localhost");
+  } catch {
+    return false;
+  }
+}
+function safeResolve(root, rel) {
+  if (typeof rel !== "string" || !rel) return null;
+  const abs = path9.resolve(root, rel);
+  const relative = path9.relative(root, abs);
+  return relative && !relative.startsWith("..") && !path9.isAbsolute(relative) ? abs : null;
+}
+function friendlyError(err) {
+  const msg = String(err?.message ?? err);
+  if (/auth|api key|x-api-key|invalid.*key|401|credential/i.test(msg)) {
+    return `${msg}
+
+The Anthropic API key was rejected. Check ANTHROPIC_API_KEY in your .env.local (or environment) and try again.`;
+  }
+  return msg;
+}
+function readJson(req) {
+  return new Promise((resolve, reject) => {
+    let data = "";
+    req.on("data", (chunk) => {
+      data += chunk;
+      if (data.length > 1e6) reject(new Error("Body too large"));
+    });
+    req.on("end", () => {
+      try {
+        resolve(data ? JSON.parse(data) : {});
+      } catch {
+        reject(new Error("Invalid JSON"));
+      }
+    });
+    req.on("error", reject);
+  });
+}
+function send(res, status, body) {
+  res.statusCode = status;
+  if (body) res.setHeader("Content-Type", "application/json");
+  res.end(body ? JSON.stringify(body) : void 0);
+}
+function notFound(res) {
+  send(res, 404, { error: "Not found" });
+}
+
+// src/server/reload.ts
+import fs8 from "fs";
+import path10 from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+function reloadingHandler(opts, onReload) {
+  let handler = createDetectiveHandler(opts);
+  const here = fileURLToPath(import.meta.url);
+  if (here.split(path10.sep).includes("node_modules") || path10.basename(path10.dirname(here)) !== "dist") return handler;
+  const entry = path10.join(path10.dirname(here), "server.js");
+  const mtime = () => {
+    try {
+      return fs8.statSync(entry).mtimeMs;
+    } catch {
+      return 0;
+    }
+  };
+  let loaded = mtime();
+  let seen = loaded;
+  const timer = setInterval(async () => {
+    const now = mtime();
+    if (!now || now === loaded || now !== seen) return void (seen = now);
+    loaded = now;
+    try {
+      const mod = await import(`${pathToFileURL(entry).href}?t=${now}`);
+      handler = mod.createDetectiveHandler(opts);
+      console.log("[react-detective] rebuilt: reloaded the server code");
+      onReload?.();
+    } catch (err) {
+      console.warn("[react-detective] couldn't reload the rebuilt server code:", err);
+    }
+  }, 1e3);
+  timer.unref();
+  return ((req, res, next) => handler(req, res, next));
+}
+
+export {
+  explainComponent,
+  createDetectiveHandler,
+  reloadingHandler
+};