@palate/cli 0.0.0-stage → 0.0.1

package/src/paths.mjs

@@ -0,0 +1,13 @@
+// Where palate's own files live. Published, kb/ and skill/ ship inside the package (copied in by `npm pack`);
+// in this repo they sit at the repo root, two folders up. Modules that honoured PALATE_KB still read it themselves.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PKG_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const inPkg = (name) => path.join(PKG_DIR, name);
+const inRepo = (name) => path.resolve(PKG_DIR, "..", "..", name);
+const pick = (name) => (fs.existsSync(inPkg(name)) ? inPkg(name) : inRepo(name));
+
+export const KB_ROOT = pick("kb");
+export const SKILL_ROOT = pick("skill");

package/src/png.mjs

@@ -0,0 +1,107 @@
+// Just enough PNG for screenshots: decode Chrome's 8-bit RGB/RGBA PNGs to raw rows, stack and crop them, and
+// encode the result. Lets palate build a full page from screen-sized captures without an image library.
+import fs from "node:fs";
+import zlib from "node:zlib";
+
+const SIG = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+
+// { width, height, channels, data } with data the unfiltered rows, channels bytes per pixel.
+export function decodePng(buf) {
+  if (!buf.subarray(0, 8).equals(SIG)) throw new Error("not a PNG");
+  let width = 0, height = 0, channels = 0;
+  const idat = [];
+  for (let at = 8; at < buf.length; ) {
+    const len = buf.readUInt32BE(at);
+    const type = buf.toString("latin1", at + 4, at + 8);
+    const body = buf.subarray(at + 8, at + 8 + len);
+    if (type === "IHDR") {
+      width = body.readUInt32BE(0);
+      height = body.readUInt32BE(4);
+      const depth = body[8], color = body[9], interlace = body[12];
+      channels = { 0: 1, 2: 3, 4: 2, 6: 4 }[color];
+      if (depth !== 8 || !channels || interlace) throw new Error(`unsupported PNG (depth ${depth}, color ${color}, interlace ${interlace})`);
+    } else if (type === "IDAT") idat.push(body);
+    else if (type === "IEND") break;
+    at += 12 + len;
+  }
+  const raw = zlib.inflateSync(Buffer.concat(idat));
+  const stride = width * channels;
+  const data = Buffer.alloc(stride * height);
+  for (let y = 0; y < height; y++) {
+    const f = raw[y * (stride + 1)];
+    const src = y * (stride + 1) + 1, out = y * stride, prev = out - stride;
+    for (let i = 0; i < stride; i++) {
+      const x = raw[src + i];
+      const a = i >= channels ? data[out + i - channels] : 0;
+      const b = y ? data[prev + i] : 0;
+      const c = y && i >= channels ? data[prev + i - channels] : 0;
+      let v;
+      if (f === 0) v = x;
+      else if (f === 1) v = x + a;
+      else if (f === 2) v = x + b;
+      else if (f === 3) v = x + ((a + b) >> 1);
+      else if (f === 4) {
+        const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+        v = x + (pa <= pb && pa <= pc ? a : pb <= pc ? b : c);
+      } else throw new Error(`bad PNG filter ${f}`);
+      data[out + i] = v & 255;
+    }
+  }
+  return { width, height, channels, data };
+}
+
+const CRC = new Int32Array(256).map((_, n) => {
+  let c = n;
+  for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+  return c;
+});
+const crc32 = (buf) => {
+  let c = -1;
+  for (let i = 0; i < buf.length; i++) c = CRC[(c ^ buf[i]) & 255] ^ (c >>> 8);
+  return (c ^ -1) >>> 0;
+};
+const chunk = (type, body) => {
+  const head = Buffer.alloc(8);
+  head.writeUInt32BE(body.length, 0);
+  head.write(type, 4, "latin1");
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(Buffer.concat([head.subarray(4), body])), 0);
+  return Buffer.concat([head, body, crc]);
+};
+
+// Every row filtered "Up": screenshots are mostly flat bands, which that turns into zeros.
+export function encodePng({ width, height, channels, data }) {
+  const stride = width * channels;
+  const raw = Buffer.alloc((stride + 1) * height);
+  for (let y = 0; y < height; y++) {
+    const at = y * (stride + 1), row = y * stride;
+    raw[at] = y ? 2 : 0;
+    for (let i = 0; i < stride; i++) raw[at + 1 + i] = y ? (data[row + i] - data[row - stride + i]) & 255 : data[row + i];
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8;
+  ihdr[9] = { 1: 0, 2: 4, 3: 2, 4: 6 }[channels];
+  return Buffer.concat([SIG, chunk("IHDR", ihdr), chunk("IDAT", zlib.deflateSync(raw, { level: 6 })), chunk("IEND", Buffer.alloc(0))]);
+}
+
+// Images of one width and channel count, top to bottom.
+export function stackImages(parts) {
+  const { width, channels } = parts[0];
+  if (parts.some((p) => p.width !== width || p.channels !== channels)) throw new Error("parts differ in width or channels");
+  return { width, channels, height: parts.reduce((n, p) => n + p.height, 0), data: Buffer.concat(parts.map((p) => p.data)) };
+}
+
+// A rectangle of an image, clipped to it (null when nothing is left).
+export function cropImage(img, { x = 0, y = 0, width = img.width, height = img.height }) {
+  const x0 = Math.max(0, Math.round(x)), y0 = Math.max(0, Math.round(y));
+  const x1 = Math.min(img.width, Math.round(x + width)), y1 = Math.min(img.height, Math.round(y + height));
+  if (x1 <= x0 || y1 <= y0) return null;
+  const { channels } = img, stride = img.width * channels, w = (x1 - x0) * channels;
+  const data = Buffer.alloc(w * (y1 - y0));
+  for (let r = y0; r < y1; r++) img.data.copy(data, (r - y0) * w, r * stride + x0 * channels, r * stride + x1 * channels);
+  return { width: x1 - x0, height: y1 - y0, channels, data };
+}
+
+export const writePng = (file, img) => fs.writeFileSync(file, encodePng(img));

package/src/point/auto.mjs

@@ -0,0 +1,224 @@
+// `palate point --auto`: palate itself listens to the queue and, for each pin, runs the user's coding agent
+// headless on it (Claude Code: `claude -p`, Codex: `codex exec`), one at a time, in order. The agent gets the
+// same brief palate_point_next returns, with palate's MCP server for crop and done. A pin the agent leaves
+// without calling done is marked failed with its last output lines, and the user can retry it from the overlay.
+//
+// Permissions stay minimal and explicit. Claude Code may read and edit files in the project and call the two
+// point tools (palate_point_crop, palate_point_done), nothing else: no shell, no web. Codex runs in its
+// workspace-write sandbox. Skipping every permission check takes --yolo, and palate warns when it's on.
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { kill } from "../devserver.mjs";
+import { failRequest, formatRequest, getRequest, nextRequest, pointDir } from "./server.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+export const PALATE_BIN = path.resolve(here, "..", "..", "bin", "palate.mjs");
+// A pin that takes longer than this is stopped and marked failed.
+const PIN_TIMEOUT = Number(process.env.PALATE_AUTO_TIMEOUT_MIN ?? 20) * 60_000;
+
+export const AGENTS = {
+  claude: { bin: "claude", name: "Claude Code", install: "npm install -g @anthropic-ai/claude-code" },
+  codex: { bin: "codex", name: "Codex", install: "npm install -g @openai/codex" },
+};
+// What Claude Code may do on a pin (and nothing else): read and edit the project, and the two point tools.
+export const CLAUDE_TOOLS = ["Read", "Edit", "Write", "Glob", "Grep", "mcp__palate__palate_point_crop", "mcp__palate__palate_point_done"];
+
+// The executable for a command on PATH (with Windows' .exe/.cmd), or null.
+export function onPath(name) {
+  const win = process.platform === "win32";
+  const exts = win ? (process.env.PATHEXT || ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean).map((e) => e.toLowerCase()) : [""];
+  for (const d of (process.env.PATH || process.env.Path || "").split(path.delimiter)) {
+    if (!d) continue;
+    for (const e of exts) {
+      const f = path.join(d.replace(/^"|"$/g, ""), name + e);
+      try {
+        if (fs.statSync(f).isFile()) return f;
+      } catch {}
+    }
+  }
+  return null;
+}
+
+// Arguments for cmd.exe (needed for .cmd shims): quoted so spaces and quotes survive.
+const winQuote = (a) => (/^[\w./:\\=,@+-]+$/.test(a) ? a : `"${a.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, "$1$1")}"`);
+const slash = (p) => p.replace(/\\/g, "/");
+// How the brief names palate's CLI: `palate` when it's installed, else node with this checkout's bin.
+const palateCmd = () => (onPath("palate") ? "palate" : `node "${slash(PALATE_BIN)}"`);
+
+// The agent's command for one pin. The brief always goes in on stdin (no quoting trouble, no length limit).
+export function agentCommand(dir, { agent = "claude", agentCmd, yolo = false } = {}) {
+  if (agentCmd) return { name: "your --agent-cmd", command: agentCmd, args: [], shell: true, custom: true };
+  const a = AGENTS[agent];
+  if (!a) throw new Error(`Unknown agent "${agent}". Use --agent claude or --agent codex (or --agent-cmd "<command>").`);
+  const exe = onPath(a.bin);
+  if (!exe) return { missing: true, name: a.name, bin: a.bin, install: a.install };
+  let args;
+  if (agent === "claude") {
+    // palate's MCP server for this project only (--strict-mcp-config: not the user's other servers).
+    const cfg = path.join(pointDir(dir), "auto-mcp.json");
+    fs.mkdirSync(path.dirname(cfg), { recursive: true });
+    fs.writeFileSync(cfg, JSON.stringify({ mcpServers: { palate: { command: process.execPath, args: [PALATE_BIN, "mcp"], env: { PALATE_DIR: dir } } } }, null, 2));
+    args = ["-p", "--mcp-config", cfg, "--strict-mcp-config", "--output-format", "text"];
+    args.push(...(yolo ? ["--dangerously-skip-permissions"] : ["--allowedTools", CLAUDE_TOOLS.join(",")]));
+  } else {
+    const toml = (v) => JSON.stringify(v);
+    args = ["exec", "-C", dir, "-c", `mcp_servers.palate.command=${toml(slash(process.execPath))}`, "-c", `mcp_servers.palate.args=[${toml(slash(PALATE_BIN))},"mcp"]`, "-c", `mcp_servers.palate.env={PALATE_DIR=${toml(slash(dir))}}`];
+    args.push(...(yolo ? ["--dangerously-bypass-approvals-and-sandbox"] : ["--sandbox", "workspace-write"]), "-");
+  }
+  const shell = process.platform === "win32" && /\.(cmd|bat)$/i.test(exe);
+  // A .cmd shim needs cmd.exe: one command line, quoted here (Node doesn't quote arguments for a shell).
+  return { name: a.name, command: shell ? [`"${exe}"`, ...args.map(winQuote)].join(" ") : exe, args: shell ? [] : args, shell, permissions: yolo ? "every permission check skipped (--yolo)" : agent === "claude" ? `only ${CLAUDE_TOOLS.join(", ")}` : "Codex's workspace-write sandbox" };
+}
+
+// What the headless agent reads: the request exactly as palate_point_next gives it, then how to finish.
+export function autoBrief(r, dir) {
+  const p = palateCmd();
+  const d = ` --dir "${slash(dir)}"`;
+  return `${formatRequest(r, dir)}
+
+## You are running headless (palate point --auto)
+- palate started you for this one request in ${slash(dir)}. Do only this one; the user is not watching the chat.
+- Open the before crop first${r.crop ? ` (${slash(r.crop)})` : ""}, then make the change in the source.
+- Verify: palate_point_crop with id "${r.id}" (or run: ${p} point crop ${r.id}${d}) and open the new crop next to the before one. Fix once more if it isn't better. It also shoots ${r.other?.width ? `${r.other.width} wide` : "the other width"}; if it says that width broke, fix that too.
+- Finish: palate_point_done with id "${r.id}" and a one-line summary (or run: ${p} point done ${r.id} "<summary>"${d}). Without it the pin is marked failed. It refuses while the other width is broken; don't override it (the user isn't watching to accept it): fix it, or stop and say why.
+- Don't call palate_point_next and don't start a dev server: the page reloads by itself.${r.trail?.length ? `
+- The element sits in a state that needs steps to open (see "opened by" above); palate reopens it for every crop. If a crop says it couldn't reopen it, that isn't a break and doesn't block done: check the change in the code and say so in the summary.` : ""}
+- If you can't do it (the request is unclear, or the change would touch shared components used elsewhere), don't call done: say why in one or two lines and stop.`;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const fmtMs = (ms) => (ms < 60_000 ? `${Math.round(ms / 1000)}s` : `${Math.floor(ms / 60_000)}m ${Math.round((ms % 60_000) / 1000)}s`);
+
+// Runs the agent on one pin. Resolves with { code, lines, timedOut }.
+function runAgent(cmd, dir, r, brief, { log, onChild }) {
+  const folder = path.join(pointDir(dir), r.id);
+  fs.mkdirSync(folder, { recursive: true });
+  const briefFile = path.join(folder, "brief.md");
+  fs.writeFileSync(briefFile, brief);
+  const out = fs.createWriteStream(path.join(folder, "agent.log"));
+  const env = { ...process.env, PALATE_DIR: dir, PALATE_POINT_ID: r.id, PALATE_POINT_N: String(r.n), PALATE_POINT_BRIEF: briefFile, PALATE_BIN, PALATE_NO_OPEN: "1" };
+  return new Promise((resolve) => {
+    const child = spawn(cmd.command, cmd.args, { cwd: dir, env, shell: cmd.shell, windowsHide: true, stdio: ["pipe", "pipe", "pipe"] });
+    onChild(child);
+    const lines = [];
+    let partial = "";
+    const take = (chunk) => {
+      out.write(chunk);
+      const t = partial + chunk.toString("utf8");
+      const parts = t.split(/\r?\n/);
+      partial = parts.pop();
+      for (const l of parts) {
+        if (!l.trim()) continue;
+        lines.push(l);
+        if (lines.length > 40) lines.shift();
+        log(`  │ ${l.length > 200 ? `${l.slice(0, 200)}…` : l}`);
+      }
+    };
+    child.stdout.on("data", take);
+    child.stderr.on("data", take);
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      kill(child);
+    }, PIN_TIMEOUT);
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      lines.push(`Couldn't start the agent: ${e.message}`);
+      out.end();
+      resolve({ code: -1, lines, timedOut });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (partial.trim()) lines.push(partial);
+      out.end();
+      resolve({ code, lines, timedOut });
+    });
+    child.stdin.on("error", () => {});
+    child.stdin.end(brief);
+  });
+}
+
+// Watches the queue and runs the agent on each pin. Returns { stop, done } or { missing } when the agent's CLI
+// isn't on PATH (point keeps running; the user's chat agent can still take the pins).
+export async function runAuto(dir, { agent = "claude", agentCmd, yolo = false, log = (m) => console.error(m) } = {}) {
+  dir = path.resolve(dir);
+  const cmd = agentCommand(dir, { agent, agentCmd, yolo });
+  if (cmd.missing) {
+    log(`palate point --auto: ${cmd.name} isn't installed here ("${cmd.bin}" is not on PATH), so palate can't run it on your pins.
+  Install it (${cmd.install}) and start again, or pick another agent with --agent codex|claude.
+  Manual mode for now: your pins wait in the queue. In Claude Code run /mcp__palate__point (or ask your agent to run palate point), and it takes them in order.`);
+    return { missing: true, stop: async () => {}, done: Promise.resolve() };
+  }
+  if (yolo)
+    log(`WARNING: --yolo skips every permission check. ${cmd.name} can run any command and change any file without asking, on every pin anyone sends from this page. Use it only on a project you can restore (commit first).`);
+  log(`palate point --auto: ${cmd.name} takes each pin, one at a time, in order (${cmd.custom ? `runs: ${agentCmd}, with the brief on stdin` : `permissions: ${cmd.permissions}`}). Briefs and agent logs: ${slash(path.relative(dir, pointDir(dir)))}/<id>/`);
+
+  let stopping = false;
+  let child = null;
+  const label = `auto:${agentCmd ? "custom" : agent}`;
+  const logFile = path.join(pointDir(dir), "auto.jsonl");
+
+  async function one(r) {
+    const started = Date.now();
+    log(`Pin ${r.n}: "${r.prompt || (r.chips ?? []).join(", ")}" (${r.route}) → ${cmd.name}`);
+    // Variants need the user to pick in their browser; a headless agent can't do that.
+    if ((r.chips ?? []).includes("Variants of this")) {
+      await failRequest(dir, r.id, "Variants of this needs a pick from you, so auto mode leaves it to your chat agent: run /mcp__palate__point in Claude Code, or remove the chip and retry.").catch(() => {});
+      log(`Pin ${r.n}: skipped (variants need your pick; your chat agent can do it).`);
+      return;
+    }
+    const res = await runAgent(cmd, dir, r, autoBrief(r, dir), { log, onChild: (c) => (child = c) });
+    child = null;
+    const ms = Date.now() - started;
+    const after = await getRequest(dir, r.id).catch(() => null);
+    let result;
+    if (after?.status === "done") {
+      result = "done";
+      log(`Pin ${r.n}: done in ${fmtMs(ms)}. ${after.summary ?? ""}`);
+    } else {
+      result = "failed";
+      const why = res.timedOut ? `Stopped after ${fmtMs(PIN_TIMEOUT)} without finishing.` : stopping ? "palate point --auto was stopped." : `${cmd.name} exited (code ${res.code}) without calling palate point done.`;
+      const tail = res.lines.slice(-12).join("\n");
+      if (after?.status === "working") await failRequest(dir, r.id, `${why}${tail ? `\n${tail}` : ""}`).catch(() => {});
+      log(`Pin ${r.n}: failed after ${fmtMs(ms)}. ${why} The pin shows "Failed: retry" in the overlay.`);
+    }
+    try {
+      fs.appendFileSync(logFile, JSON.stringify({ id: r.id, n: r.n, agent: label, ms, result, code: res.code, at: new Date().toISOString() }) + "\n");
+    } catch {}
+  }
+
+  const done = (async () => {
+    let whenStopped = "return";
+    let misses = 0;
+    while (!stopping) {
+      let r;
+      try {
+        r = await nextRequest(dir, { wait: 55, agent: label, whenStopped });
+        misses = 0;
+      } catch (e) {
+        if (stopping) break;
+        if (++misses === 1) log(`palate point --auto: ${e.message} Retrying…`);
+        await sleep(3000);
+        continue;
+      }
+      if (!r) continue;
+      if (r.stopped) {
+        log("You pressed Done. Auto mode keeps waiting; send a pin to start again.");
+        whenStopped = "wait";
+        continue;
+      }
+      whenStopped = "return";
+      await one(r);
+    }
+  })();
+
+  return {
+    stop: async () => {
+      stopping = true;
+      if (child) kill(child);
+    },
+    done,
+  };
+}

package/src/point/locate.mjs

@@ -0,0 +1,114 @@
+// Where a pointed-at element lives in the source. The browser knows the component name (React fiber, Vue,
+// Svelte), the visible text, the class string and the id; palate greps the project for each and ranks the
+// files and lines where several of them meet. No index, no build step: a project's own source is small.
+import fs from "node:fs";
+import path from "node:path";
+
+const EXTS = new Set([".tsx", ".jsx", ".ts", ".js", ".mjs", ".vue", ".svelte", ".astro", ".html", ".mdx", ".md"]);
+const SKIP = new Set(["node_modules", ".next", ".git", ".palate", "dist", "build", "out", ".turbo", ".vercel", ".svelte-kit", ".nuxt", ".output", ".astro", "coverage", ".cache", "public", "storybook-static"]);
+const MAX_FILES = 6000;
+const MAX_BYTES = 400_000;
+
+let cache = { dir: null, at: 0, files: [] };
+
+// Source files of the project, cached for a few seconds (several requests often arrive together).
+function sourceFiles(dir) {
+  if (cache.dir === dir && Date.now() - cache.at < 5000) return cache.files;
+  const files = [];
+  const walk = (d) => {
+    if (files.length >= MAX_FILES) return;
+    let entries = [];
+    try {
+      entries = fs.readdirSync(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name.startsWith(".") && e.isDirectory()) continue;
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) {
+        if (!SKIP.has(e.name)) walk(p);
+      } else if (EXTS.has(path.extname(e.name)) && !/\.(min|d)\.[jt]s$|\.test\.|\.spec\./.test(e.name)) files.push(p);
+    }
+  };
+  walk(dir);
+  cache = { dir, at: Date.now(), files };
+  return files;
+}
+
+const escRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+// Text as it appears in JSX: whitespace may be a line break, quotes may be entities.
+const textRe = (t) => new RegExp(escRe(t).replace(/\s+/g, "\\s+").replace(/['’]/g, "(?:'|’|&apos;|&#39;|&rsquo;)").replace(/["“”]/g, '(?:"|“|”|&quot;|&ldquo;|&rdquo;)'), "i");
+
+// The phrases worth searching for: the element's own text nodes, longest first, a few words each.
+export function phrases(textNodes = [], max = 4) {
+  const out = [];
+  for (const t of [...textNodes].map((s) => s.replace(/\s+/g, " ").trim()).filter((s) => s.length >= 4).sort((a, b) => b.length - a.length)) {
+    const p = t.length > 48 ? t.slice(0, 48).replace(/\s\S*$/, "") : t;
+    if (p.length >= 4 && !out.some((o) => o.includes(p) || p.includes(o))) out.push(p);
+    if (out.length >= max) break;
+  }
+  return out;
+}
+
+// Ranks file:line candidates. Clues: { components: [names, nearest first], texts: [phrases], className, id, files: [known source files from the framework] }.
+export function locate(dir, clues) {
+  const files = sourceFiles(dir);
+  const comps = (clues.components ?? []).filter((n) => /^[A-Z][\w$]*$/.test(n)).slice(0, 4);
+  const texts = (clues.texts ?? []).slice(0, 4);
+  const cls = (clues.className ?? "").trim().replace(/\s+/g, " ");
+  const clsKey = cls.length >= 12 ? cls.slice(0, 60).replace(/\s\S*$/, "") : "";
+  const id = clues.id && !/^[:«]|^radix-|^headlessui-|\d{4,}/.test(clues.id) ? clues.id : "";
+  const known = new Set((clues.files ?? []).map((f) => path.resolve(dir, f)));
+  const routeFile = clues.routeFile ? path.resolve(dir, clues.routeFile) : null;
+
+  const hits = [];
+  for (const file of files) {
+    let src;
+    try {
+      const st = fs.statSync(file);
+      if (st.size > MAX_BYTES) continue;
+      src = fs.readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    const lines = src.split("\n");
+    const found = [];
+    const add = (re, why, weight) => {
+      for (let i = 0; i < lines.length; i++) if (re.test(lines[i])) found.push({ line: i + 1, why, weight });
+    };
+    comps.forEach((name, k) => {
+      const w = 6 - k * 1.5;
+      add(new RegExp(`(?:function|class|const|let|var)\\s+${escRe(name)}\\b|export\\s+default\\s+function\\s+${escRe(name)}\\b`), `defines <${name}>`, w + 2);
+      add(new RegExp(`<${escRe(name)}[\\s/>]`), `renders <${name}>`, w * 0.4);
+    });
+    texts.forEach((t, k) => add(textRe(t), `text "${t.length > 36 ? `${t.slice(0, 36)}…` : t}"`, 5 - k));
+    if (clsKey) add(new RegExp(escRe(clsKey)), "class string", 4);
+    if (id) add(new RegExp(`id=["'{\`]+${escRe(id)}["'}\`]`), `id="${id}"`, 4);
+    if (!found.length) continue;
+    const isKnown = known.has(path.resolve(file));
+    // The file that renders this route, and a file that defines the nearest component, are where it most likely lives.
+    const bonus = (isKnown ? 6 : 0) + (routeFile === path.resolve(file) ? 4 : 0) + (comps[0] && found.some((x) => x.why === `defines <${comps[0]}>`) ? 3 : 0);
+    // Group nearby lines: the element is where its clues meet.
+    found.sort((a, b) => a.line - b.line);
+    const groups = [];
+    for (const f of found) {
+      const g = groups.at(-1);
+      if (g && f.line - g.end <= 12) {
+        g.end = f.line;
+        g.items.push(f);
+      } else groups.push({ start: f.line, end: f.line, items: [f] });
+    }
+    for (const g of groups) {
+      const whys = [...new Set(g.items.map((x) => x.why))];
+      // The same clue on many lines counts once; different clues together count more.
+      const score = [...new Map(g.items.map((x) => [x.why, x.weight])).values()].reduce((a, b) => a + b, 0) * (whys.length > 1 ? 1.4 : 1) + bonus;
+      const best = g.items.find((x) => /^text|^class|^id/.test(x.why)) ?? g.items[0];
+      hits.push({ file: path.relative(dir, file).replace(/\\/g, "/"), line: best.line, score: Math.round(score * 10) / 10, why: whys.join(", "), snippet: lines[best.line - 1].trim().slice(0, 140) });
+    }
+  }
+  // The framework's own file (Vue __file, Svelte meta) first, even without other hits.
+  for (const f of known)
+    if (!hits.some((h) => path.resolve(dir, h.file) === f) && fs.existsSync(f)) hits.push({ file: path.relative(dir, f).replace(/\\/g, "/"), line: clues.line ?? 1, score: 6, why: "the framework's source file for this component", snippet: "" });
+  return hits.sort((a, b) => b.score - a.score).slice(0, 5);
+}