@palate/cli 0.0.0-stage → 0.0.2

package/src/point/server.mjs

@@ -0,0 +1,1122 @@
+// `palate point`: fix things by pointing at them in the running app. palate starts (or reuses) the project's
+// dev server and puts a small proxy in front of it. The proxy injects palate's overlay into HTML pages and
+// passes everything else through untouched, HMR websockets included, so nothing in the project changes.
+// The user points at an element and says what should change; each request is saved with everything an
+// agent needs (selector, DOM path, trimmed HTML, styles, component names, a crop, likely source lines) in
+// .palate/point/<id>/request.json, and the agent takes them one by one: next → fix → done. Every `next` is
+// also a heartbeat, so the overlay can say whether an agent is listening; `palate point --auto` (auto.mjs)
+// is palate itself listening, running the user's coding agent headless on each pin.
+import fs from "node:fs";
+import http from "node:http";
+import net from "node:net";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { startDevServer } from "../devserver.mjs";
+import { HIDE_DEV, routeFile, stamp } from "../look.mjs";
+import { TASTE_DIR, readJson } from "../loop/common.mjs";
+import { freePort, launch, normalizeRoute } from "../shoot.mjs";
+import { locate, phrases } from "./locate.mjs";
+import { cleanLayer, cleanTrail, replay, trailCore, trailWords } from "./trail.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+export const POINT_LOG = path.join(TASTE_DIR, "point.jsonl");
+export const pointDir = (dir) => path.join(dir, ".palate", "point");
+const serverFile = (dir) => path.join(pointDir(dir), "server.json");
+const TAG = Buffer.from('<script src="/__palate/overlay.js" data-palate defer></script>');
+const PUBLIC = ["id", "n", "status", "route", "selector", "label", "prompt", "chips", "box", "scroll", "viewport", "summary", "error", "created", "startedAt", "doneAt", "hasCrop", "hasAfter", "cropFound", "afterFound", "removed", "width", "alt", "other", "trail", "layer"];
+// An agent counts as listening while it waits in `next`, while a pin is being worked on (fixing takes minutes
+// without a call), or if it called or finished a pin within this long (a wait is 55 s).
+export const LISTEN_MS = 120_000;
+
+// The width a request is about, when it isn't the user's own: "a hamburger menu in mobile mode" → 390,
+// "at 768px" → 768. Crops at the user's desktop viewport would show no change for those.
+export function askedWidth(prompt, viewportWidth = 1440) {
+  const p = String(prompt ?? "");
+  let w = null;
+  const m = /\b(\d{3,4})\s*(?:px\b|wide\b|width\b|w\b)/i.exec(p) || /\b(?:at|below|under|width(?: of)?|on a?)\s+(\d{3,4})\b/i.exec(p);
+  if (m && +m[1] >= 280 && +m[1] <= 1280) w = +m[1];
+  if (!w && /\b(mobile|phones?|iphone|android|small[- ]screens?|narrow screens?|handheld)\b/i.test(p)) w = 390;
+  if (!w && /\b(tablets?|ipad)\b/i.test(p)) w = 768;
+  return w && w < (viewportWidth || 1440) - 40 ? w : null;
+}
+// Every pin is checked at two widths: the one the user pointed at and the other one, so a fix at 1440 that
+// breaks 390 doesn't go unnoticed. The other one is the width the user's words name ("on mobile"), else a
+// phone for a desktop pin and a desktop for a phone pin.
+export const PHONE = 390;
+export const DESKTOP = 1440;
+export const widthName = (w) => (w <= 500 ? "phone" : w < 1024 ? "tablet" : "desktop");
+export function otherWidth(viewport, prompt) {
+  const vw = viewport?.width || DESKTOP;
+  const asked = askedWidth(prompt, vw);
+  if (asked) return { width: asked, asked: true };
+  return { width: vw >= 768 ? PHONE : DESKTOP, asked: false };
+}
+
+// The pinned element in plain words, for notes: the button "Get invite".
+const TAG_NAME = { a: "link", button: "button", img: "image", svg: "icon", h1: "heading", h2: "heading", h3: "heading", h4: "heading", p: "paragraph", li: "list item", ul: "list", ol: "list", nav: "navigation", header: "header", footer: "footer", section: "section", input: "field", textarea: "field", select: "menu", form: "form", table: "table", label: "label" };
+export function elName(r) {
+  const t = r?.label?.text;
+  return `the ${TAG_NAME[r?.tag] ?? "element"}${t ? ` "${t.length > 28 ? `${t.slice(0, 27).trimEnd()}…` : t}"` : ""}`;
+}
+
+// Before vs after at the other width. "broke": the page now scrolls sideways (or gets wider than the screen),
+// the element disappeared (not asked for), or text in it is now cut off. "changed": it moved or resized beyond
+// a few pixels, or the crop looks different (expected for shared CSS; shown, not blocked). Else "unchanged".
+// before/after: { state: "shown"|"hidden"|"missing", box: {x,y,width,height} in page px, overflow, scrolls,
+// clipped, cutText }; diff: { ratio, sizeChanged } from the two crops.
+const TOL = 4;
+export function otherVerdict(before, after, { width, asked = false, removed = false, diff = null, name = "the element" } = {}) {
+  const where = `At ${width} (${widthName(width)}, ${asked ? "the width the user asked about" : "the width you didn't point at"})`;
+  if (!before || !after || before.error || after.error)
+    return { verdict: "unknown", problems: [], changes: [], note: `${where}: not checked (${!before || before.error ? "no before shot" : "no after shot"}${(before?.error ?? after?.error) ? `: ${before?.error ?? after?.error}` : ""}).`, short: `Not checked at ${width}` };
+  // A pin inside an opened state (a modal, a menu) that palate couldn't open again: not checked, never "broke".
+  const stuck = [before, after].find((s) => s.reopen?.state === "couldn't reopen" && !(removed && s.reopen.ran));
+  if (stuck)
+    return { verdict: "unknown", problems: [], changes: [], reopen: true, note: `${where}: not checked in the opened state. palate couldn't reopen it ${stuck === before ? "for the before shot" : "after the change"}: ${stuck.reopen.why}. That isn't counted as broken.`, short: `Couldn't reopen at ${width}` };
+  const problems = [];
+  const changes = [];
+  const shown = (s) => s.state === "shown" || (s.state === undefined && s.found === true);
+  const bo = before.overflow ?? 0;
+  const ao = after.overflow ?? 0;
+  if (ao > 1 && bo <= 1) problems.push(after.scrolls === false ? `the page is now ${ao}px wider than the screen (cut off at the right)` : `the page now scrolls sideways (${ao}px wider than the screen)`);
+  else if (bo > 1 && ao > bo + 8) problems.push(`the page scrolls further sideways (${ao}px wider than the screen, was ${bo}px)`);
+  if (shown(before) && !shown(after)) {
+    if (removed) changes.push(`${name} is gone, as asked`);
+    else problems.push(`${name} ${after.state === "hidden" ? "is now hidden" : "disappeared"}`);
+  }
+  if (!shown(before) && shown(after)) changes.push(`${name} shows now (it was ${before.state === "hidden" ? "hidden" : "not on the page"})`);
+  if (shown(before) && shown(after)) {
+    if ((after.clipped ?? 0) > (before.clipped ?? 0)) problems.push(`text in ${name} is now cut off${after.cutText ? ` ("${after.cutText}")` : ""}`);
+    const a = before.box ?? {};
+    const b = after.box ?? {};
+    const dw = (b.width ?? 0) - (a.width ?? 0);
+    const dh = (b.height ?? 0) - (a.height ?? 0);
+    const dx = (b.x ?? 0) - (a.x ?? 0);
+    const dy = (b.y ?? 0) - (a.y ?? 0);
+    const size = [];
+    if (Math.abs(dw) > TOL) size.push(`${Math.abs(dw)}px ${dw < 0 ? "narrower" : "wider"}`);
+    if (Math.abs(dh) > TOL) size.push(`${Math.abs(dh)}px ${dh < 0 ? "shorter" : "taller"}`);
+    if (size.length) changes.push(`${name} is ${size.join(" and ")}`);
+    const move = [];
+    if (Math.abs(dx) > TOL) move.push(`${Math.abs(dx)}px ${dx < 0 ? "left" : "right"}`);
+    if (Math.abs(dy) > TOL) move.push(`${Math.abs(dy)}px ${dy < 0 ? "up" : "down"}`);
+    if (move.length) changes.push(`${size.length ? "it" : name} moved ${move.join(" and ")}`);
+  }
+  if (diff && !changes.length && (diff.sizeChanged || diff.ratio > 0.005)) changes.push(`${name} looks different (${Math.max(1, Math.round(diff.ratio * 100))}% of the crop changed)`);
+  const verdict = problems.length ? "broke" : changes.length ? "changed" : "unchanged";
+  const scroll = ao > 1 ? (bo > 1 && !problems.length ? "; the page already scrolled sideways before" : "") : "; no sideways scroll";
+  const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+  const note =
+    verdict === "broke"
+      ? `${where}: broke. ${cap(problems.join("; "))}.${changes.length ? ` Also: ${changes.join("; ")}.` : ""}`
+      : verdict === "changed"
+        ? `${where}: changed. ${cap(changes.join("; "))}${scroll}.`
+        : `${where}: unchanged${ao > 1 ? " (the page already scrolled sideways before)" : ""}.`;
+  const short = verdict === "broke" ? `Broke at ${width}: ${problems[0]}` : verdict === "changed" ? `Changed at ${width}: ${changes.join("; ")}` : `Unchanged at ${width}`;
+  return { verdict, problems, changes, note, short };
+}
+
+// palate_point_done refuses while the other width is broken, unless the agent overrides (the user accepts it).
+export function doneBlocked(r, override = false) {
+  const o = r?.other;
+  if (override || o?.verdict !== "broke") return null;
+  return `Not done yet. ${o.note} Fix it so both widths work (palate_point_crop shows before and after at both), then call palate_point_done again. Only if the user accepts it as it is, pass override: true (CLI: --override).`;
+}
+
+// The user asked for the element to go away.
+const REMOVE = /\b(remove|delete|hide|get rid of|take (?:it |this |that )?out|drop|don'?t need|do not need|no need for)\b/i;
+const words = (t) => new Set(String(t ?? "").toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? []);
+// Is the element a shot found the one the user pointed at (same tag, most of its words), or something else
+// that now sits at that selector?
+function sameElement(r, sig) {
+  if (!sig) return false;
+  if (r.tag && sig.tag !== r.tag) return false;
+  const a = words(r.text);
+  if (!a.size) return true;
+  const b = words(sig.text);
+  let k = 0;
+  for (const w of a) if (b.has(w)) k++;
+  return k / a.size >= 0.5;
+}
+// A shot whose opened state couldn't be reopened says nothing about whether the element is gone.
+const isRemoved = (r, shot, said) => Boolean(said) || (REMOVE.test(r.prompt ?? "") && Boolean(shot) && !(shot.reopen && !shot.reopen.ran) && (!shot.found || !sameElement(r, shot.sig)));
+
+// Where a pin's opened state couldn't be reopened, newest first: [{ width, when, why }].
+export function reopenTrouble(r) {
+  const o = r.other?.width ? r.other : null;
+  const out = [];
+  const add = (width, when, x) => x?.state === "couldn't reopen" && out.push({ width, when, why: x.why });
+  add(r.viewport?.width ?? null, "after", r.reopen?.after);
+  add(o?.width ?? null, "after", o?.after?.reopen);
+  add(r.viewport?.width ?? null, "before", r.reopen?.before);
+  add(o?.width ?? null, "before", o?.before?.reopen);
+  return out;
+}
+
+// In the page, at another width: the pinned element (its selector, or the same tag with the same words when
+// the selector finds something else), whether it shows, and what's wrong around it: sideways scroll and
+// text cut off inside it. Runs in the browser, so it uses nothing from this file.
+function measureInPage({ sel, tag, text, width }) {
+  const words = (s) => new Set(String(s || "").toLowerCase().match(/[\p{L}\p{N}]+/gu) || []);
+  const want = words(text);
+  const score = (el) => {
+    if (!want.size) return 1;
+    const a = words(el.textContent);
+    let k = 0;
+    for (const w of want) if (a.has(w)) k++;
+    // A parent with the same words and much more is not the same element.
+    return k / want.size - Math.abs(Math.log((a.size + 1) / (want.size + 1))) * 0.15;
+  };
+  const shows = (el) => (el.checkVisibility ? el.checkVisibility({ opacityProperty: true, visibilityProperty: true }) : el.getClientRects().length > 0) && el.getBoundingClientRect().width >= 1 && el.getBoundingClientRect().height >= 1;
+  let el = null;
+  let how = "selector";
+  try {
+    el = document.querySelector(sel);
+  } catch {}
+  if (el && ((tag && el.tagName.toLowerCase() !== tag) || score(el) < 0.5)) el = null;
+  if (!el && tag && want.size) {
+    how = "text";
+    let best = 0;
+    const all = document.getElementsByTagName(tag);
+    for (let i = 0; i < all.length && i < 4000; i++) {
+      const s = score(all[i]) + (shows(all[i]) ? 0.05 : 0);
+      if (s > best) [best, el] = [s, all[i]];
+    }
+    if (best < 0.6) el = null;
+  }
+  // Sideways scroll: try it. A phone may also zoom out to fit a too-wide page (innerWidth grows).
+  const de = document.documentElement;
+  const y0 = scrollY;
+  window.scrollTo({ left: 1e6, top: y0, behavior: "instant" });
+  const sx = scrollX;
+  window.scrollTo({ left: 0, top: y0, behavior: "instant" });
+  const scrolls = sx > 1 || innerWidth > width + 1;
+  const overflow = Math.max(0, Math.round(Math.max(sx, de.scrollWidth - de.clientWidth, innerWidth - width)));
+  const page = { overflow, scrolls, pageWidth: Math.max(de.scrollWidth, innerWidth), vw: de.clientWidth, vh: innerHeight, H: de.scrollHeight };
+  if (!el) return { state: "missing", how: null, ...page };
+  if (!shows(el)) return { state: "hidden", how, ...page, tag: el.tagName.toLowerCase() };
+  let b = el.getBoundingClientRect();
+  if ((b.bottom < 0 || b.top > innerHeight) && b.height < innerHeight - 48) {
+    el.scrollIntoView({ block: "center", inline: "nearest", behavior: "instant" });
+    b = el.getBoundingClientRect();
+  }
+  // Text cut off: the element, or something in it, hides overflow and holds more than it shows.
+  let clipped = 0;
+  let cutText = null;
+  for (const n of [el, ...el.querySelectorAll("*")].slice(0, 400)) {
+    if (!(n.textContent || "").trim()) continue;
+    const cs = getComputedStyle(n);
+    const hides = /hidden|clip/.test(cs.overflowX + cs.overflowY) || cs.textOverflow === "ellipsis" || (cs.webkitLineClamp && cs.webkitLineClamp !== "none");
+    if (hides && (n.scrollWidth > n.clientWidth + 1 || n.scrollHeight > n.clientHeight + 1)) {
+      clipped++;
+      cutText ??= n.textContent.replace(/\s+/g, " ").trim().slice(0, 40);
+    }
+  }
+  return {
+    state: "shown",
+    how,
+    ...page,
+    box: { x: Math.round(b.left + scrollX), y: Math.round(b.top + scrollY), width: Math.round(b.width), height: Math.round(b.height) },
+    v: { x: b.left, y: b.top, w: b.width, h: b.height },
+    clipped,
+    cutText,
+    tag: el.tagName.toLowerCase(),
+    text: (el.innerText || el.textContent || "").replace(/\s+/g, " ").trim().slice(0, 600),
+  };
+}
+
+// How much two PNG crops differ, drawn into a canvas in the browser (scaled down together, max side 800):
+// { ratio of changed pixels, sizeChanged }.
+async function diffInPage([a, b]) {
+  const load = (src) =>
+    new Promise((resolve, reject) => {
+      const i = new Image();
+      i.onload = () => resolve(i);
+      i.onerror = reject;
+      i.src = src;
+    });
+  const [x, y] = await Promise.all([load(a), load(b)]);
+  const W = Math.max(x.naturalWidth, y.naturalWidth);
+  const H = Math.max(x.naturalHeight, y.naturalHeight);
+  const k = Math.min(1, 800 / Math.max(W, H));
+  const w = Math.max(1, Math.round(W * k));
+  const h = Math.max(1, Math.round(H * k));
+  const px = (img) => {
+    const c = new OffscreenCanvas(w, h);
+    const g = c.getContext("2d");
+    g.fillStyle = "#fff";
+    g.fillRect(0, 0, w, h);
+    g.drawImage(img, 0, 0, img.naturalWidth * k, img.naturalHeight * k);
+    return g.getImageData(0, 0, w, h).data;
+  };
+  const p = px(x);
+  const q = px(y);
+  let changed = 0;
+  for (let i = 0; i < p.length; i += 4) if (Math.abs(p[i] - q[i]) + Math.abs(p[i + 1] - q[i + 1]) + Math.abs(p[i + 2] - q[i + 2]) > 48) changed++;
+  return { ratio: changed / (w * h), sizeChanged: Math.abs(x.naturalWidth - y.naturalWidth) > 8 || Math.abs(x.naturalHeight - y.naturalHeight) > 8 };
+}
+
+// The overlay as served: trail.mjs's shared part pasted in, so the overlay and the server trim and word
+// trails the same way.
+const TRAIL_SRC = `(${trailCore.toString()})()`;
+export const overlaySource = () => fs.readFileSync(path.join(here, "overlay.js"), "utf8").replace(/\/\*@trail\*\/[\s\S]*?\/\*@end\*\//, () => TRAIL_SRC);
+
+// The trail in the taste log: what was clicked or pressed and whether it could be reopened, never typed values.
+const trailLog = (r) =>
+  r.trail?.length
+    ? { trail: r.trail.map((s) => ({ type: s.type, text: s.text ?? s.name ?? null, ...(s.key ? { key: s.key } : {}) })), layer: r.layer ?? null, reopen: reopenTrouble(r).map(({ width, when, why }) => ({ width, when, why })) }
+    : {};
+
+const logTaste = (record) => {
+  try {
+    fs.mkdirSync(TASTE_DIR, { recursive: true });
+    fs.appendFileSync(POINT_LOG, JSON.stringify({ ...record, at: new Date().toISOString() }) + "\n");
+  } catch {}
+};
+
+const readBody = (req, limit = 2_000_000) =>
+  new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    req.on("data", (c) => {
+      size += c.length;
+      if (size > limit) {
+        reject(new Error("Request too large"));
+        req.destroy();
+      } else chunks.push(c);
+    });
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+
+// A running point server for this project, if there is one (it answers its ping with the same folder).
+export async function runningPoint(dir) {
+  const info = readJson(serverFile(dir), null);
+  if (!info?.url) return null;
+  try {
+    const r = await fetch(`${info.url}/__palate/api/ping`, { signal: AbortSignal.timeout(1500) });
+    const j = await r.json();
+    return path.resolve(j.dir) === path.resolve(dir) ? info : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function startPoint(dir, { url, route = "/", port, open = true, log = (m) => console.error(m) } = {}) {
+  dir = path.resolve(dir);
+  const existing = await runningPoint(dir);
+  if (existing) {
+    // Starting point again means the user wants an agent again, even after they pressed Done.
+    await fetch(`${existing.url}/__palate/api/resume`, { method: "POST", signal: AbortSignal.timeout(1500) }).catch(() => {});
+    const link = existing.url + normalizeRoute(route);
+    if (open) (await import("../loop/pick.mjs")).openBrowser(link);
+    return { url: existing.url, link, base: existing.base, reused: true, stop: () => {}, done: new Promise(() => {}) };
+  }
+  const dev = await startDevServer(dir, { url });
+  const target = new URL(dev.base);
+  const root = pointDir(dir);
+  fs.mkdirSync(root, { recursive: true });
+  fs.writeFileSync(path.join(dir, ".palate", ".gitignore"), "*\n");
+
+  // ---------- The queue ----------
+  const requests = new Map();
+  const ready = new Map();
+  // The user's cookies (for crops of signed-in pages) stay in memory, never on disk.
+  const cookies = new Map();
+  const waiters = new Set();
+  const clients = new Set();
+  let counter = 0;
+  // Earlier requests stay: open ones are still the agent's to do, recent done ones keep their pins.
+  for (const id of fs.existsSync(root) ? fs.readdirSync(root) : []) {
+    const r = readJson(path.join(root, id, "request.json"), null);
+    if (!r?.id) continue;
+    if (r.status === "working") r.status = "queued";
+    if (r.width === undefined) r.width = askedWidth(r.prompt, r.viewport?.width);
+    // Pins from an older palate: the other width is shot before the agent takes them.
+    if (r.status === "queued" && !r.other) r.other = otherWidth(r.viewport, r.prompt);
+    const fresh = Date.now() - Date.parse(r.doneAt ?? r.created) < 12 * 3600_000;
+    if (r.status === "queued" || (["done", "canceled", "failed"].includes(r.status) && fresh)) requests.set(r.id, r);
+    counter = Math.max(counter, r.n ?? 0);
+  }
+
+  const pub = (r) => {
+    const o = Object.fromEntries(PUBLIC.map((k) => [k, r[k]]));
+    // The other width without file paths: the overlay loads its crops by name (crop-390, after-390).
+    if (r.other) {
+      const side = (s) => s && { has: Boolean(s.crop), state: s.state, found: s.found, box: s.box, overflow: s.overflow, scrolls: s.scrolls, clipped: s.clipped, removed: s.removed, shot: s.shot, error: s.error, reopen: s.reopen?.state };
+      const { width, asked, verdict, note, short, problems, changes } = r.other;
+      o.other = { width, asked, verdict, note, short, problems, changes, before: side(r.other.before), after: side(r.other.after) };
+    }
+    // Whether its opened state could be reopened for the checks (the newest trouble, if any).
+    if (r.trail?.length) {
+      const t = reopenTrouble(r);
+      o.reopen = { before: r.reopen?.before?.state ?? null, after: r.reopen?.after?.state ?? null, fail: t[0] ?? null };
+    }
+    if (r.status === "queued") o.position = [...requests.values()].filter((x) => x.status === "queued" && x.n <= r.n).length;
+    return o;
+  };
+  const save = (r) => {
+    fs.mkdirSync(path.join(root, r.id), { recursive: true });
+    fs.writeFileSync(path.join(root, r.id, "request.json"), JSON.stringify(r, null, 2));
+  };
+  const broadcast = (msg) => {
+    const line = `data: ${JSON.stringify(msg)}\n\n`;
+    for (const c of clients) c.write(line);
+  };
+  const changed = (r) => {
+    save(r);
+    broadcast({ type: "update", request: pub(r) });
+    // Queue positions move for everyone behind it.
+    for (const x of requests.values()) if (x !== r && x.status === "queued") broadcast({ type: "update", request: pub(x) });
+    for (const w of waiters) w();
+    emitAgent();
+  };
+
+  // ---------- Is an agent listening? ----------
+  // Every `next` is a heartbeat. The overlay shows listening, busy (a pin is being worked on) or none, and
+  // when the user sends a pin with no agent listening it says how to start one.
+  const hb = { polls: 0, seen: 0, label: null, stopAck: 0 };
+  let stopped = false;
+  const agentState = () => {
+    const working = [...requests.values()].filter((x) => x.status === "working").sort((a, b) => a.n - b.n)[0];
+    // A pin finished recently means an agent is around (unless it has since been told the user stopped).
+    const lastDone = Math.max(0, ...[...requests.values()].map((x) => Date.parse(x.doneAt ?? "") || 0));
+    const live = hb.polls > 0 || Date.now() - hb.seen < LISTEN_MS || (lastDone > hb.stopAck && Date.now() - lastDone < LISTEN_MS);
+    const queued = [...requests.values()].filter((x) => x.status === "queued").length;
+    const auto = Boolean(live && hb.label?.startsWith("auto"));
+    if (working) return { state: "busy", pin: working.n, id: working.id, label: hb.label, auto, queued };
+    if (stopped) return { state: "stopped", label: hb.label, auto, queued };
+    if (live) return { state: "listening", label: hb.label, auto, queued };
+    return { state: "none", queued };
+  };
+  let lastAgent = "";
+  function emitAgent() {
+    const a = agentState();
+    const key = JSON.stringify(a);
+    if (key === lastAgent) return;
+    lastAgent = key;
+    broadcast({ type: "agent", agent: a });
+  }
+  // A heartbeat goes stale without any request, so look every few seconds.
+  const staleTimer = setInterval(emitAgent, 5000);
+  staleTimer.unref?.();
+
+  // ---------- Crops, in a browser palate keeps warm ----------
+  let browserP = null;
+  const browser = () => (browserP ??= launch());
+  // Two shots at a time (the pinned width and the other one, side by side); more wait their turn.
+  let active = 0;
+  const waiting = [];
+  const slot = async (fn) => {
+    if (active < 2) active++;
+    else await new Promise((resolve) => waiting.push(resolve));
+    try {
+      return await fn();
+    } finally {
+      const w = waiting.shift();
+      if (w) w();
+      else active--;
+    }
+  };
+  // Same viewport and scroll as the user's tab, straight from the dev server (no overlay), with their cookies.
+  // width: shoot at that width instead (a phone when it's narrow), from the top, finding the element there.
+  // screen: at that width, always the whole screen (a request about that width: "a hamburger menu on mobile").
+  // A pin inside an opened state (r.trail: a modal, a menu, a tab): the steps are replayed with real input on
+  // the fresh page first. When a step fails, or (for a before shot) the element isn't there after them, the
+  // shot says "couldn't reopen" and falls back to the page as it loads. before: the shot taken at pin time.
+  const shootElement = (r, file, cookie, { width, screen = false, before = false } = {}) =>
+    slot(async () => {
+      const b = await browser();
+      const vp = width
+        ? { width, height: width <= 500 ? 844 : width < 1000 ? 1024 : 900 }
+        : { width: Math.max(320, Math.min(r.viewport?.width ?? 1440, 2560)), height: Math.max(320, Math.min(r.viewport?.height ?? 900, 1600)) };
+      const phone = Boolean(width && width <= 500);
+      const ctx = await b.newContext({ viewport: vp, isMobile: phone, hasTouch: phone, deviceScaleFactor: vp.width < 700 || (r.box?.width ?? 0) * (r.box?.height ?? 0) < 400_000 ? 2 : 1, colorScheme: r.colorScheme === "dark" ? "dark" : "light" });
+      try {
+        if (cookie) {
+          const cookies = cookie
+            .split(/;\s*/)
+            .map((c) => c.split("="))
+            .filter(([k]) => k)
+            .map(([name, ...v]) => ({ name, value: v.join("="), url: target.origin }));
+          await ctx.addCookies(cookies).catch(() => {});
+        }
+        const page = await ctx.newPage();
+        await page.addInitScript(HIDE_DEV);
+        const load = async () => {
+          await page.goto(target.origin + r.route, { waitUntil: "load", timeout: 60_000 });
+          await page.waitForLoadState("networkidle", { timeout: 6000 }).catch(() => {});
+          await page.evaluate(({ x, y }) => window.scrollTo({ left: x, top: y, behavior: "instant" }), width ? { x: 0, y: 0 } : (r.scroll ?? { x: 0, y: 0 }));
+          await page.waitForTimeout(700);
+        };
+        await load();
+        let reopen = null;
+        if (r.trail?.length) {
+          reopen = await replay(page, r.trail, { loose: Boolean(width) }).catch((e) => ({ state: "couldn't reopen", ran: false, why: `the steps didn't run: ${String(e.message).split("\n")[0]}` }));
+          await page.waitForTimeout(200);
+        }
+        const pad = 32;
+        if (width) return await shootAtWidth(page, r, file, { width, screen, pad, reopen, before, load });
+        const findIt = () =>
+          page.evaluate((sel) => {
+            let el = null;
+            try {
+              el = document.querySelector(sel);
+            } catch {}
+            if (!el || !el.getClientRects().length) return null;
+            let b = el.getBoundingClientRect();
+            // Bring it into view when it fits, so fixed and sticky things look as they do for the user.
+            if ((b.bottom < 0 || b.top > innerHeight) && b.height < innerHeight - 48) {
+              el.scrollIntoView({ block: "center", behavior: "instant" });
+              b = el.getBoundingClientRect();
+            }
+            return { x: b.left, y: b.top, w: b.width, h: b.height, sx: scrollX, sy: scrollY, vw: document.documentElement.clientWidth, vh: innerHeight, H: document.documentElement.scrollHeight, tag: el.tagName.toLowerCase(), text: (el.innerText || el.textContent || "").replace(/\s+/g, " ").trim().slice(0, 600) };
+          }, r.selector);
+        let m = await findIt();
+        if (reopen?.state === "reopened" && !m && before) reopen = { ...reopen, state: "couldn't reopen", why: "the steps ran, but the element wasn't there after them" };
+        if (reopen?.state === "couldn't reopen") {
+          await load();
+          m = await findIt();
+        }
+        await page.waitForTimeout(150);
+        const found = Boolean(m);
+        const sig = m ? { tag: m.tag, text: m.text } : null;
+        const box = m ?? { x: r.box.x, y: r.box.y, w: r.box.width, h: r.box.height, sx: r.scroll?.x ?? 0, sy: r.scroll?.y ?? 0, vw: vp.width, vh: vp.height, H: 1e6 };
+        await cropBox(page, file, box, pad);
+        return { found, sig, width: null, box: { x: Math.round(box.x), y: Math.round(box.y), width: Math.round(box.w), height: Math.round(box.h) }, ...(reopen ? { reopen } : {}) };
+      } finally {
+        await ctx.close().catch(() => {});
+      }
+    });
+  // A crop around a box in the viewport (x, y, w, h, with the page's scroll sx/sy, viewport vw/vh and height H).
+  const cropBox = async (page, file, box, pad) => {
+    const inView = box.y >= 0 && box.y + box.h <= box.vh && box.x >= 0 && box.x + box.w <= box.vw + 1;
+    const x0 = Math.max(0, box.x - pad);
+    const w = Math.max(8, Math.min(box.vw, box.x + box.w + pad) - x0);
+    if (inView) {
+      const y0 = Math.max(0, box.y - pad);
+      await page.screenshot({ path: file, clip: { x: x0, y: y0, width: w, height: Math.max(8, Math.min(box.vh, box.y + box.h + pad) - y0) } });
+    } else {
+      const y0 = Math.max(0, box.y + box.sy - pad);
+      await page.screenshot({ path: file, fullPage: true, clip: { x: x0, y: y0, width: w, height: Math.max(8, Math.min(box.h + pad * 2, 2000, box.H - y0)) } });
+    }
+  };
+  // At another width the element may not show at all (hidden, or not on the page): then the shot is that
+  // screen around where it was on the page. When it shows, a crop of it (or the screen with it in view, for
+  // a request about that width). Measured either way, for the verdict.
+  const shootAtWidth = async (page, r, file, { width, screen, pad, reopen = null, before = false, load }) => {
+    const measure = () => page.evaluate(measureInPage, { sel: r.selector, tag: r.tag, text: r.text ?? r.label?.text ?? "", width });
+    let m = await measure();
+    if (reopen?.state === "reopened" && m.state !== "shown" && before) reopen = { ...reopen, state: "couldn't reopen", why: `the steps ran, but the element ${m.state === "hidden" ? "was hidden" : "wasn't there"} after them at ${width}` };
+    if (reopen?.state === "couldn't reopen") {
+      await load();
+      m = await measure();
+    }
+    await page.waitForTimeout(150);
+    const shown = m.state === "shown";
+    if (!shown) {
+      const y = Math.max(0, (r.box?.y ?? 0) + (r.scroll?.y ?? 0) - 120);
+      await page.evaluate((top) => window.scrollTo({ left: 0, top, behavior: "instant" }), y < (r.viewport?.height ?? 900) ? 0 : y);
+      await page.waitForTimeout(200);
+    }
+    if (screen || !shown) await page.screenshot({ path: file });
+    else await cropBox(page, file, { x: m.v.x, y: m.v.y, w: m.v.w, h: m.v.h, sx: 0, sy: m.box.y - m.v.y, vw: m.vw, vh: m.vh, H: m.H }, pad);
+    const { v, ...rest } = m;
+    return { ...rest, found: shown, sig: shown ? { tag: m.tag, text: m.text } : null, width, crop: file, shot: screen || !shown ? "screen" : "element", ...(reopen ? { reopen } : {}) };
+  };
+  // How different two crops look (null when either is missing or the browser can't say).
+  const pixelDiff = (a, b) =>
+    !a || !b || !fs.existsSync(a) || !fs.existsSync(b)
+      ? Promise.resolve(null)
+      : slot(async () => {
+          const ctx = await (await browser()).newContext();
+          try {
+            const page = await ctx.newPage();
+            const url = (f) => `data:image/png;base64,${fs.readFileSync(f).toString("base64")}`;
+            return await page.evaluate(diffInPage, [url(a), url(b)]);
+          } finally {
+            await ctx.close().catch(() => {});
+          }
+        }).catch(() => null);
+
+  const sourcesFor = (body) => {
+    const f = body.framework ?? {};
+    const comps = [...(f.react?.owners ?? []).map((o) => o.name), ...(f.react?.components ?? []), f.vue?.component].filter(Boolean);
+    return locate(dir, {
+      components: [...new Set(comps)],
+      texts: phrases(body.textNodes ?? []),
+      className: body.className,
+      id: body.id,
+      files: [f.vue?.file, f.svelte?.file].filter(Boolean),
+      line: f.svelte?.line,
+      routeFile: routeFile(dir, String(body.route ?? "/").split("?")[0])?.file,
+    });
+  };
+
+  async function addRequest(body, cookie) {
+    // A new pin after Done means the user is pointing again.
+    stopped = false;
+    const n = ++counter;
+    const id = `${stamp()}-${n}`;
+    const r = {
+      id,
+      n,
+      status: "queued",
+      created: new Date().toISOString(),
+      project: path.basename(dir),
+      route: normalizeRoute(String(body.route ?? "/")),
+      href: body.href,
+      title: body.title,
+      prompt: String(body.prompt ?? "").slice(0, 4000),
+      chips: Array.isArray(body.chips) ? body.chips.map(String).slice(0, 10) : [],
+      selector: String(body.selector ?? ""),
+      path: body.path,
+      tag: body.tag,
+      elementId: body.id,
+      className: body.className,
+      label: body.label,
+      text: body.text,
+      outerHTML: body.outerHTML,
+      styles: body.styles,
+      framework: body.framework,
+      box: body.box,
+      viewport: body.viewport,
+      dpr: body.dpr,
+      scroll: body.scroll,
+      colorScheme: body.colorScheme,
+      // The steps that opened the state the element sits in (a modal, a menu, a tab), replayed before each crop.
+      trail: cleanTrail(body.trail),
+      layer: cleanLayer(body.layer),
+      sources: [],
+      crop: null,
+      hasCrop: false,
+      hasAfter: false,
+    };
+    if (!r.trail.length) {
+      delete r.trail;
+      delete r.layer;
+    }
+    r.width = askedWidth(r.prompt, r.viewport?.width);
+    r.other = otherWidth(r.viewport, r.prompt);
+    requests.set(id, r);
+    if (cookie) cookies.set(id, cookie);
+    save(r);
+    broadcast({ type: "update", request: pub(r) });
+    // The crops (at the pinned width and the other one, side by side) and the source search finish before
+    // the agent gets the request, in the background: the dialog has already closed.
+    const work = (async () => {
+      try {
+        r.sources = sourcesFor(body);
+      } catch (e) {
+        r.sourcesError = e.message;
+      }
+      const main = (async () => {
+        try {
+          const file = path.join(root, id, "crop.png");
+          const shot = await shootElement(r, file, cookie, { before: true });
+          r.crop = file;
+          r.hasCrop = true;
+          r.cropFound = shot.found;
+          if (shot.reopen) r.reopen = { before: shot.reopen };
+        } catch (e) {
+          r.cropError = e.message.split("\n")[0];
+        }
+      })();
+      await Promise.all([main, otherBefore(r, cookie)]);
+      save(r);
+      broadcast({ type: "update", request: pub(r) });
+      logTaste({ kind: "point-request", id, project: r.project, route: r.route, prompt: r.prompt, chips: r.chips, component: r.label?.comp ?? null, tag: r.tag, selector: r.selector, crop: r.crop, viewport: r.viewport, other: r.other ? { width: r.other.width, state: r.other.before?.state ?? null } : null, ...trailLog(r) });
+    })();
+    ready.set(id, work);
+    for (const w of waiters) w();
+    return r;
+  }
+
+  // The oldest queued pin, marked working. Pins already sent are taken even after Done; once the queue is
+  // empty a stopped session answers { stopped } (or keeps waiting, for palate's own auto runner).
+  async function next(waitMs, { gone = () => false, whenStopped = "return" } = {}) {
+    const until = Date.now() + waitMs;
+    for (;;) {
+      if (gone()) return null;
+      const r = [...requests.values()].filter((x) => x.status === "queued").sort((a, b) => a.n - b.n)[0];
+      if (r) {
+        r.status = "working";
+        r.startedAt = new Date().toISOString();
+        delete r.error;
+        changed(r);
+        await ready.get(r.id);
+        if (r.other?.width && !r.other.before) {
+          await otherBefore(r);
+          save(r);
+        }
+        return r;
+      }
+      if (stopped && whenStopped !== "wait") return { stopped: true };
+      const left = until - Date.now();
+      if (left <= 0) return null;
+      await new Promise((resolve) => {
+        const done = () => {
+          waiters.delete(done);
+          clearTimeout(t);
+          resolve();
+        };
+        const t = setTimeout(done, left);
+        waiters.add(done);
+      });
+    }
+  }
+
+  async function reshoot(r, file, opts) {
+    await ready.get(r.id);
+    return shootElement(r, file, cookies.get(r.id), opts);
+  }
+  // The before at the other width (390 for a desktop pin, 1440 for a phone pin, or the width the user's words
+  // name), taken before any edit. A request about that width keeps its older name too (alt).
+  async function otherBefore(r, cookie = cookies.get(r.id)) {
+    const o = r.other;
+    if (!o?.width || o.before) return;
+    const file = path.join(root, r.id, `crop-${o.width}.png`);
+    try {
+      const { sig, ...shot } = await shootElement(r, file, cookie, { width: o.width, screen: o.asked, before: true });
+      o.before = shot;
+    } catch (e) {
+      o.before = { error: e.message.split("\n")[0] };
+    }
+    if (o.asked) r.alt = o.before.error ? { width: o.width, before: false, error: o.before.error } : { width: o.width, before: true, beforeFound: o.before.found, crop: file };
+  }
+
+  // ---------- HTTP: palate's own endpoints, then the proxy ----------
+  let proxyOrigin = "";
+  const agent = new http.Agent({ keepAlive: true, maxSockets: 64 });
+  const json = (res, code, obj) => {
+    res.writeHead(code, { "content-type": "application/json", "cache-control": "no-store" });
+    res.end(JSON.stringify(obj));
+  };
+  // Only palate's own overlay (same origin) and local tools may use the API; other sites in the user's browser may not.
+  const foreign = (req) => {
+    if (req.headers["sec-fetch-site"] === "cross-site") return true;
+    const o = req.headers.origin;
+    if (!o) return false;
+    try {
+      const u = new URL(o);
+      return !(u.port === String(proxyPort) && ["localhost", "127.0.0.1", "[::1]"].includes(u.hostname));
+    } catch {
+      return true;
+    }
+  };
+
+  async function palateRoute(req, res, u) {
+    if (u.pathname === "/__palate/overlay.js") {
+      res.writeHead(200, { "content-type": "text/javascript; charset=utf-8", "cache-control": "no-cache" });
+      return res.end(overlaySource());
+    }
+    if (foreign(req)) return json(res, 403, { error: "forbidden" });
+    if (u.pathname === "/__palate/events") {
+      res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store", connection: "keep-alive" });
+      res.write(`retry: 2000\ndata: ${JSON.stringify({ type: "state", requests: [...requests.values()].map(pub), agent: agentState() })}\n\n`);
+      clients.add(res);
+      const ping = setInterval(() => res.write(": ping\n\n"), 20_000);
+      req.on("close", () => {
+        clearInterval(ping);
+        clients.delete(res);
+      });
+      return;
+    }
+    const img = /^\/__palate\/img\/([\w-]+)\/((?:crop|after)(?:-\d{3,4})?)\.png$/.exec(u.pathname);
+    if (img) {
+      const r = requests.get(img[1]);
+      const file = r && path.join(root, r.id, `${img[2]}.png`);
+      if (!file || !fs.existsSync(file)) return json(res, 404, { error: "no image" });
+      res.writeHead(200, { "content-type": "image/png", "cache-control": "no-store" });
+      return fs.createReadStream(file).pipe(res);
+    }
+    const api = u.pathname.replace(/^\/__palate\/api\//, "");
+    try {
+      if (api === "ping") return json(res, 200, { palate: "point", dir, base: dev.base, url: proxyOrigin, agent: agentState() });
+      if (api === "state") return json(res, 200, { requests: [...requests.values()].map(pub), agent: agentState() });
+      if (api === "request" && req.method === "POST") {
+        if (!/application\/json/.test(req.headers["content-type"] ?? "")) return json(res, 415, { error: "json only" });
+        const r = await addRequest(JSON.parse(await readBody(req)), req.headers.cookie);
+        return json(res, 200, { ...pub(r), agent: agentState() });
+      }
+      // The overlay's Done: the agent finishes the pins already sent, then its next call says point mode stopped.
+      if ((api === "stop" || api === "resume") && req.method === "POST") {
+        stopped = api === "stop";
+        for (const w of waiters) w();
+        emitAgent();
+        if (stopped) logTaste({ kind: "point-stop", project: path.basename(dir) });
+        return json(res, 200, { ok: true, agent: agentState() });
+      }
+      if (api === "retry" && req.method === "POST") {
+        const { id } = JSON.parse(await readBody(req));
+        const r = requests.get(id);
+        if (r && r.status === "failed") {
+          r.status = "queued";
+          delete r.error;
+          stopped = false;
+          changed(r);
+        }
+        return json(res, 200, { ok: true, agent: agentState() });
+      }
+      if (api === "fail" && req.method === "POST") {
+        const { id, error } = JSON.parse(await readBody(req));
+        const r = requests.get(id);
+        if (!r) return json(res, 404, { error: `No request ${id}` });
+        if (r.status === "working") {
+          r.status = "failed";
+          r.error = String(error ?? "The agent stopped without marking it done.").slice(-2000);
+          r.failedAt = new Date().toISOString();
+          changed(r);
+          logTaste({ kind: "point-failed", id: r.id, project: r.project, route: r.route, prompt: r.prompt });
+        }
+        return json(res, 200, pub(r));
+      }
+      if (api === "cancel" && req.method === "POST") {
+        const { id } = JSON.parse(await readBody(req));
+        const r = requests.get(id);
+        if (r && (r.status === "queued" || r.status === "failed")) {
+          r.status = "canceled";
+          changed(r);
+          logTaste({ kind: "point-cancel", id: r.id, project: r.project, route: r.route });
+        }
+        return json(res, 200, { ok: true });
+      }
+      if (api === "next") {
+        const wait = Math.min(Number(u.searchParams.get("wait") ?? 55), 120) * 1000;
+        let closed = false;
+        res.on("close", () => {
+          closed = true;
+          // Wake the wait so an agent that hung up stops counting as listening.
+          for (const w of waiters) w();
+        });
+        hb.polls++;
+        hb.label = u.searchParams.get("agent") || "agent";
+        hb.seen = Date.now();
+        emitAgent();
+        let r;
+        try {
+          r = await next(wait, { gone: () => closed, whenStopped: u.searchParams.get("whenStopped") ?? "return" });
+        } finally {
+          hb.polls--;
+          hb.seen = Date.now();
+        }
+        // The agent hung up while it waited: the pin goes back to the queue instead of hanging as "working".
+        if (closed && r && !r.stopped) {
+          r.status = "queued";
+          delete r.startedAt;
+          changed(r);
+          return;
+        }
+        // An agent told to stop is no longer listening.
+        if (r?.stopped) {
+          hb.seen = 0;
+          hb.stopAck = Date.now();
+        }
+        emitAgent();
+        if (r?.stopped) return json(res, 200, { stopped: true });
+        return r ? json(res, 200, r) : json(res, 200, { none: true, queued: 0 });
+      }
+      if (api === "get") {
+        const r = requests.get(u.searchParams.get("id"));
+        return r ? json(res, 200, r) : json(res, 404, { error: "no such request" });
+      }
+      if ((api === "done" || api === "crop") && req.method === "POST") {
+        const { id, summary, removed: said, override } = JSON.parse(await readBody(req));
+        const r = requests.get(id);
+        if (!r) return json(res, 404, { error: `No request ${id}` });
+        hb.seen = Date.now();
+        const stampN = Date.now();
+        const file = path.join(root, r.id, api === "done" ? "after.png" : `check-${stampN}.png`);
+        // The pinned width and the other width, shot side by side.
+        const o = r.other?.width ? r.other : null;
+        const ofile = o && path.join(root, r.id, api === "done" ? `after-${o.width}.png` : `check-${stampN}-${o.width}.png`);
+        const [shot, oshot] = await Promise.all([
+          reshoot(r, file).catch((e) => {
+            if (api === "crop") throw e;
+            return null;
+          }),
+          o ? reshoot(r, ofile, { width: o.width, screen: o.asked }).catch((e) => ({ error: e.message.split("\n")[0] })) : null,
+        ]);
+        // Removed (asked for, and gone or replaced by something else): no crop of whatever sits there now.
+        if (shot?.reopen) r.reopen = { ...(r.reopen ?? {}), after: shot.reopen };
+        const gone = isRemoved(r, shot, said);
+        if (gone && api === "done") fs.rmSync(file, { force: true });
+        let alt = null;
+        if (o) {
+          const ok = oshot && !oshot.error;
+          const agone = gone || (ok && isRemoved(r, oshot, false));
+          const diff = ok ? await pixelDiff(o.before?.crop, ofile) : null;
+          const { sig, ...after } = oshot ?? { error: "not shot" };
+          o.after = { ...after, crop: ok && !(agone && api === "done") ? ofile : null, removed: agone };
+          if (!o.after.crop && ok && api === "done") fs.rmSync(ofile, { force: true });
+          Object.assign(o, otherVerdict(o.before, o.after, { width: o.width, asked: o.asked, removed: Boolean(said) || REMOVE.test(r.prompt ?? ""), diff, name: elName(r) }), { diff, checkedAt: new Date().toISOString() });
+          // A request about that width: the same shots under the older name.
+          if (o.asked) alt = { width: o.width, file: o.after.crop, found: o.after.found, removed: agone, before: o.before?.crop ?? null };
+        }
+        const other = o && { width: o.width, asked: o.asked, verdict: o.verdict, note: o.note, problems: o.problems, changes: o.changes, before: o.before?.crop ?? null, after: o.after?.crop ?? null, beforeState: o.before?.state ?? null, afterState: o.after?.state ?? null, ...(r.trail ? { beforeReopen: o.before?.reopen ?? null, afterReopen: o.after?.reopen ?? null } : {}) };
+        if (api === "crop") {
+          save(r);
+          broadcast({ type: "update", request: pub(r) });
+          return json(res, 200, { id, file, found: shot?.found, removed: gone, before: r.crop, viewport: r.viewport, alt, other, ...(r.trail ? { trail: trailWords(r.trail, r.layer), reopen: shot?.reopen ?? null } : {}) });
+        }
+        // Done waits while the other width is broken, unless the user accepts it.
+        const blocked = doneBlocked(r, override);
+        if (blocked) {
+          save(r);
+          broadcast({ type: "update", request: pub(r) });
+          return json(res, 409, { error: blocked, other });
+        }
+        r.status = "done";
+        delete r.error;
+        r.summary = String(summary ?? "").slice(0, 400);
+        r.doneAt = new Date().toISOString();
+        r.removed = gone;
+        r.after = shot && !gone ? file : null;
+        r.hasAfter = Boolean(r.after);
+        r.afterFound = shot?.found;
+        if (alt) r.alt = { ...(r.alt ?? { width: r.width }), after: Boolean(alt.file), afterFound: alt.found, removed: alt.removed, afterFile: alt.file };
+        if (o && override && o.verdict === "broke") o.overridden = true;
+        changed(r);
+        logTaste({ kind: "point-done", id: r.id, project: r.project, route: r.route, prompt: r.prompt, chips: r.chips, component: r.label?.comp ?? null, tag: r.tag, selector: r.selector, summary: r.summary, before: r.crop, after: r.after, viewport: r.viewport, other: o ? { width: o.width, asked: o.asked, verdict: o.verdict, note: o.note, overridden: Boolean(o.overridden), before: o.before?.crop ?? null, after: o.after?.crop ?? null } : null, ...trailLog(r) });
+        return json(res, 200, r);
+      }
+      return json(res, 404, { error: "unknown endpoint" });
+    } catch (e) {
+      return json(res, 500, { error: String(e?.message ?? e) });
+    }
+  }
+
+  // Requests go to the dev server as if the browser had opened it directly (its host and origin), so
+  // dev-only checks for cross-origin requests and allowed hosts pass.
+  const forwardHeaders = (req) => {
+    const h = { ...req.headers, host: target.host };
+    if (h.origin) h.origin = target.origin;
+    if (h.referer) h.referer = h.referer.replace(/^https?:\/\/[^/]+/, target.origin);
+    return h;
+  };
+
+  const proxy = (req, res) => {
+    const headers = forwardHeaders(req);
+    const isDoc = req.method === "GET" && (req.headers["sec-fetch-dest"] === "document" || /text\/html/.test(req.headers.accept ?? ""));
+    if (isDoc) headers["accept-encoding"] = "identity";
+    const up = http.request({ hostname: target.hostname, port: target.port || 80, method: req.method, path: req.url, headers, agent }, (pres) => {
+      const h = { ...pres.headers };
+      if (h.location) h.location = h.location.replace(target.origin, proxyOrigin);
+      const html = /text\/html/.test(h["content-type"] ?? "") && !h["content-encoding"] && req.method !== "HEAD" && pres.statusCode !== 204 && pres.statusCode !== 304;
+      if (!html) {
+        res.writeHead(pres.statusCode, pres.statusMessage, h);
+        return pres.pipe(res);
+      }
+      delete h["content-length"];
+      delete h.etag;
+      res.writeHead(pres.statusCode, pres.statusMessage, h);
+      // Inject while streaming: before </head> (or <body> when there's no head), never holding the page back.
+      let carry = Buffer.alloc(0);
+      let injected = false;
+      pres.on("data", (chunk) => {
+        if (injected) return res.write(chunk);
+        const buf = Buffer.concat([carry, chunk]);
+        const s = buf.toString("latin1");
+        const m = /<\/head\s*>|<body[\s>]/i.exec(s);
+        if (m) {
+          res.write(buf.subarray(0, m.index));
+          res.write(TAG);
+          res.write(buf.subarray(m.index));
+          injected = true;
+          carry = Buffer.alloc(0);
+        } else {
+          const keep = Math.min(buf.length, 8);
+          res.write(buf.subarray(0, buf.length - keep));
+          carry = buf.subarray(buf.length - keep);
+        }
+      });
+      pres.on("end", () => {
+        if (!injected) {
+          res.write(carry);
+          res.write(TAG);
+        }
+        res.end();
+      });
+      pres.on("error", () => res.destroy());
+    });
+    up.on("error", (e) => {
+      if (res.headersSent) return res.destroy();
+      res.writeHead(502, { "content-type": "text/plain" });
+      res.end(`palate point: the dev server at ${target.origin} didn't answer (${e.code ?? e.message}).`);
+    });
+    req.pipe(up);
+  };
+
+  // The proxy rewrites Host and Origin for the dev server, which would switch off the dev server's own
+  // allowed-hosts and origin checks; so they're checked here. Only localhost names on this port (no DNS
+  // rebinding), and no other site's scripts (a link or redirect from another site still opens the page).
+  const localHost = (req) => {
+    try {
+      const h = new URL(`http://${req.headers.host}`);
+      return ["localhost", "127.0.0.1", "[::1]"].includes(h.hostname) && h.port === String(proxyPort);
+    } catch {
+      return false;
+    }
+  };
+  const server = http.createServer((req, res) => {
+    if (!localHost(req) || (req.headers["sec-fetch-site"] === "cross-site" && req.headers["sec-fetch-mode"] !== "navigate")) {
+      res.writeHead(403, { "content-type": "text/plain" });
+      return res.end("palate point: only for this machine's browser at localhost.");
+    }
+    const u = new URL(req.url, "http://x");
+    if (u.pathname.startsWith("/__palate/")) return void palateRoute(req, res, u);
+    proxy(req, res);
+  });
+  // Websockets (Next, Vite, Astro, Nuxt HMR …) are piped through byte for byte.
+  server.on("upgrade", (req, socket, head) => {
+    if (req.url.startsWith("/__palate/") || !localHost(req) || foreign(req)) return socket.destroy();
+    const up = net.connect(Number(target.port || 80), target.hostname, () => {
+      const h = forwardHeaders(req);
+      const lines = [`${req.method} ${req.url} HTTP/${req.httpVersion}`];
+      for (const [k, v] of Object.entries(h)) for (const x of Array.isArray(v) ? v : [v]) lines.push(`${k}: ${x}`);
+      up.write(lines.join("\r\n") + "\r\n\r\n");
+      if (head?.length) up.write(head);
+      up.pipe(socket);
+      socket.pipe(up);
+    });
+    up.on("error", () => socket.destroy());
+    socket.on("error", () => up.destroy());
+  });
+
+  const proxyPort = port ?? (await freePort());
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(proxyPort, "127.0.0.1", resolve);
+  });
+  proxyOrigin = `http://localhost:${proxyPort}`;
+  fs.writeFileSync(serverFile(dir), JSON.stringify({ url: proxyOrigin, port: proxyPort, base: dev.base, pid: process.pid, dir, started: new Date().toISOString() }, null, 2));
+  const link = proxyOrigin + normalizeRoute(route);
+  log(`palate point: ${link}  (in front of ${dev.name} at ${dev.base})`);
+  if (open) (await import("../loop/pick.mjs")).openBrowser(link);
+
+  let finish;
+  const done = new Promise((r) => (finish = r));
+  const stop = async () => {
+    clearInterval(staleTimer);
+    for (const c of clients) c.end();
+    for (const w of waiters) w();
+    server.close();
+    server.closeAllConnections?.();
+    agent.destroy();
+    if (browserP) await (await browserP.catch(() => null))?.close().catch(() => {});
+    dev.stop();
+    try {
+      if (readJson(serverFile(dir), {}).port === proxyPort) fs.rmSync(serverFile(dir), { force: true });
+    } catch {}
+    finish();
+  };
+  return { url: proxyOrigin, link, base: dev.base, reused: false, stop, done };
+}
+
+// ---------- The agent's side: the same calls over HTTP, from the CLI or the MCP server ----------
+async function api(dir, p, { method = "GET", body, timeout = 70_000 } = {}) {
+  const info = await runningPoint(dir);
+  if (!info) throw new Error("palate point isn't running for this project. Start it: palate point [route] (or palate_point_start).");
+  const r = await fetch(`${info.url}/__palate/api/${p}`, { method, headers: body ? { "content-type": "application/json" } : {}, body: body ? JSON.stringify(body) : undefined, signal: AbortSignal.timeout(timeout) });
+  const j = await r.json();
+  if (!r.ok) throw new Error(j.error ?? `palate point answered ${r.status}`);
+  return j;
+}
+
+// The next request, null when the wait ran out, or { stopped: true } when the user pressed Done.
+// agent: who is listening (shown in the overlay); whenStopped "wait" keeps waiting through a Done.
+export const nextRequest = (dir, { wait = 55, agent = "agent", whenStopped = "return" } = {}) =>
+  api(dir, `next?wait=${wait}&agent=${encodeURIComponent(agent)}&whenStopped=${whenStopped}`, { timeout: (wait + 20) * 1000 }).then((r) => (r.none ? null : r));
+// override: mark it done even though the other width broke (only when the user accepts that).
+export const doneRequest = (dir, id, summary, { removed = false, override = false } = {}) => api(dir, "done", { method: "POST", body: { id, summary, removed, override }, timeout: 180_000 });
+export const cropRequest = (dir, id) => api(dir, "crop", { method: "POST", body: { id }, timeout: 180_000 });
+export const getRequest = (dir, id) => api(dir, `get?id=${encodeURIComponent(id)}`);
+export const failRequest = (dir, id, error) => api(dir, "fail", { method: "POST", body: { id, error } });
+export const stopPointMode = (dir) => api(dir, "stop", { method: "POST", body: {} });
+export const pointState = (dir) => api(dir, "state");
+
+const slash = (p) => String(p ?? "").replace(/\\/g, "/");
+
+// What each quick chip asks for, so every agent reads them the same way.
+const CHIP_BRIEF = {
+  "Fix spacing": "Spacing: one rhythm from the project's spacing scale. Equal gaps between siblings, padding that matches its neighbours, more space between groups than inside them.",
+  "Fix alignment": "Alignment: shared left edges and baselines, one alignment axis per group, optically centred icons. Nothing a few pixels off.",
+  "Type hierarchy": "Type: one obvious first read, 2–3 sizes inside this element, weight and colour before size, 45–75 characters per line, tighter tracking on large type. Use the project's type tokens.",
+  "Make it premium": "Premium is restraint: fewer borders and boxes, precise radii and shadows from the tokens, real content, generous space, one crafted detail at most. No gradient text, glows or decoration for its own sake.",
+  "Add motion": "Motion that explains: one purposeful transition (a state change, or an entrance that shows where something came from), 150–300 ms ease-out, transform and opacity only, prefers-reduced-motion respected, content visible without it.",
+  "Real content & avatars": "Real content: replace placeholders with the project's real data. People get real photos or generated avatars (never initials in circles), brands their official marks. Never invent testimonials, customers or numbers.",
+  "Variants of this": "",
+};
+
+// The request as the agent reads it.
+export function formatRequest(r, dir) {
+  const L = r.label ?? {};
+  const f = r.framework ?? {};
+  const comp = L.comp ?? f.react?.component ?? f.vue?.component ?? null;
+  const owners = (f.react?.owners ?? []).filter((o, i) => i || o.name !== comp).map((o) => `${o.name}${o.server ? " (server)" : ""}`);
+  const variants = (r.chips ?? []).includes("Variants of this");
+  const styles = Object.entries(r.styles ?? {}).map(([k, v]) => `${k}: ${v}`).join("; ");
+  const vp = r.viewport ?? {};
+  const o = r.other?.width ? r.other : null;
+  const at = (w) => `${w} (${widthName(w)})`;
+  // Where the problem appears, first: the width the user pointed at, and the one the fix is also checked at.
+  const where = vp.width
+    ? `**Pinned at ${vp.width}×${vp.height} (${widthName(vp.width)}).**${o?.asked ? ` **The problem is at ${at(o.width)}, from the user's words; judge the fix there.**` : ""}${o ? ` palate checks the fix at ${vp.width} and at ${at(o.width)}, before and after: palate_point_crop shows both, and palate_point_done refuses while ${o.width} is broken (the page scrolls sideways, the element disappears, or text in it is cut off).` : ""}`
+    : "";
+  // A pin inside an opened state: the steps that open it, in plain words.
+  const tw = trailWords(r.trail, r.layer);
+  const opened = tw ? `**This element is inside a state opened by: ${tw}. palate reopens it for every check:** it replays those steps on a fresh load before each crop, at both widths.` : "";
+  const stuck = (x) => (x?.state === "couldn't reopen" ? ` palate couldn't reopen the opened state for it (${x.why}), so this is the page as it loads.` : "");
+  const ob = o?.before;
+  const otherLine = !o
+    ? ""
+    : !ob
+      ? `- Before at ${at(o.width)}: none yet.`
+      : ob.error
+        ? `- No before at ${at(o.width)}: ${ob.error}`
+        : `- Before at ${at(o.width)}: ${slash(ob.crop)}${ob.state === "hidden" ? " (the element is hidden at this width; this is the screen around where it was)" : ob.state === "missing" ? " (the element isn't on the page at this width; this is the screen around where it was)" : o.asked ? " (that screen, with the element in view)" : ""}${ob.overflow > 1 ? `. The page already scrolls sideways there (${ob.overflow}px) before your change.` : ""}${stuck(ob.reopen)}`;
+  const out = [
+    `# Point request ${r.n} (id ${r.id})`,
+    "",
+    where,
+    "",
+    opened,
+    "",
+    `**The user asks:** ${r.prompt ? `"${r.prompt}"` : "(no text)"}${r.chips?.length ? `  ·  chips: ${r.chips.join(", ")}` : ""}`,
+    "",
+    "## The element",
+    `- Route: ${r.route}  ·  viewport ${r.viewport?.width}×${r.viewport?.height}, scrolled to ${r.scroll?.x ?? 0},${r.scroll?.y ?? 0}`,
+    `- ${comp ? `<${comp}> ` : ""}${r.tag}${r.elementId ? `#${r.elementId}` : ""}${L.text ? ` "${L.text}"` : ""}, ${r.box?.width}×${r.box?.height} at (${r.box?.x}, ${r.box?.y}) in the viewport`,
+    `- Selector: \`${r.selector}\``,
+    `- DOM path: \`${r.path}\``,
+    comp || owners.length ? `- Component: ${comp ?? "?"}${owners.length ? `  ·  rendered by: ${owners.join(" ← ")}` : ""}${f.react?.components?.length ? `  ·  inside: ${f.react.components.slice(0, 5).join(" ← ")}` : ""}` : "",
+    f.vue ? `- Vue component: ${f.vue.component ?? "?"}${f.vue.file ? ` (${slash(f.vue.file)})` : ""}` : "",
+    f.svelte ? `- Svelte source: ${slash(f.svelte.file)}:${f.svelte.line}` : "",
+    r.crop ? `- Crop when the user pointed: ${slash(r.crop)}${stuck(r.reopen?.before) || (r.cropFound === false ? ` (the selector didn't match on a fresh load${r.trail ? " after the steps" : ""}, so this is the region where it was)` : "")}` : `- No crop${r.cropError ? `: ${r.cropError}` : ""}`,
+    otherLine,
+    "",
+    "## Where it lives (best guesses; confirm by the text and classes)",
+    ...(r.sources?.length ? r.sources.map((s, i) => `${i + 1}. ${s.file}:${s.line}  (${s.why})${s.snippet ? `\n   \`${s.snippet.replace(/`/g, "'")}\`` : ""}`) : ["No match in the source. Search for the text or class names yourself."]),
+    "",
+    styles ? `## Key computed styles\n${styles}\n` : "",
+    "## outerHTML (trimmed)",
+    "```html",
+    String(r.outerHTML ?? "").slice(0, 6000),
+    "```",
+    "",
+    "## What to do",
+  ];
+  if (variants)
+    out.push(
+      `- The user wants variants, not one edit. Run palate_vary with route "${r.route}" and section \`${r.selector}\` (CLI: palate vary ${r.route} --section "${r.selector}"), build its briefs, then palate_pick_start so the user picks. When the pick is made real, call palate_point_done with id "${r.id}" and what was chosen.`,
+    );
+  else out.push("- Change exactly this element (or this section, if it's a section) in its source. Keep everything around it as it is, and keep the project's tokens, components and copy rules.");
+  for (const c of r.chips ?? []) if (CHIP_BRIEF[c]) out.push(`- ${CHIP_BRIEF[c]}`);
+  out.push(
+    "- If the request is unclear or would change shared components used elsewhere, say so in the summary instead of guessing.",
+    ...(r.trail ? ["- If a check says palate couldn't reopen the opened state (say a button in the steps was renamed), that width isn't checked in it; it never counts as broken and never blocks done. Look at the change in the code, and say so in the summary."] : []),
+    `- Verify: palate_point_crop with id "${r.id}" (CLI: palate point crop ${r.id}) re-shoots this element after your edit${o ? `, at ${vp.width ?? "the pinned width"} and at ${o.width}, with a verdict for ${o.width} (unchanged, changed or broke)` : ""}; open it next to the before crop. Fix once more if it isn't better${o ? `, and fix ${o.width} too if it broke` : ""}.`,
+    `- Then palate_point_done with id "${r.id}" and a one-line summary of what changed (CLI: palate point done ${r.id} "<summary>"). The user's pin turns done and shows before and after.${REMOVE.test(r.prompt ?? "") ? ` If you removed the element, pass removed: true (CLI: --removed) so the after view says "Removed" instead of showing what sits there now.` : ""}`,
+  );
+  return out.filter((l) => l !== "").join("\n").replace(/\n## /g, "\n\n## ").replace(/\n{3,}/g, "\n\n");
+}