aipeek 0.2.6 → 0.2.8

package/dist/{chunk-XA2LT6I4.js → chunk-4BPXH2SW.js}

@@ -6,7 +6,7 @@ import { fileURLToPath } from "url";
 import { transformSync } from "esbuild";
 
 // src/core/action.ts
-var TYPES = ["click", "fill", "press", "wait", "screenshot"];
+var TYPES = ["click", "fill", "press", "wait", "screenshot", "realclick", "query", "assert", "drag", "scrollIntoView", "drop", "clipboard"];
 function resolveAction(type, args) {
   if (!TYPES.includes(type))
     return { valid: false, error: `unknown action: ${type}` };
@@ -14,6 +14,8 @@ function resolveAction(type, args) {
   switch (type) {
     case "click":
       return hasTarget ? { valid: true } : { valid: false, error: "click needs sel= or text=" };
+    case "realclick":
+      return hasTarget || args.x !== void 0 && args.y !== void 0 ? { valid: true } : { valid: false, error: "realclick needs sel=, text=, or x= & y=" };
     case "fill":
       if (!hasTarget)
         return { valid: false, error: "fill needs sel= or text=" };
@@ -26,6 +28,32 @@ function resolveAction(type, args) {
       return hasTarget ? { valid: true } : { valid: false, error: "wait needs sel= or text=" };
     case "screenshot":
       return { valid: true };
+    case "query":
+      return args.sel ? { valid: true } : { valid: false, error: "query needs sel=" };
+    case "assert":
+      if (!args.screen && !args.sel)
+        return { valid: false, error: "assert needs screen= (a __AIPEEK_SCREEN__ key) or sel=" };
+      if (args.equals === void 0)
+        return { valid: false, error: "assert needs equals=" };
+      return { valid: true };
+    case "drag":
+      if (!hasTarget)
+        return { valid: false, error: "drag needs sel= or text= (the source)" };
+      if (!args.to)
+        return { valid: false, error: "drag needs to= (destination selector)" };
+      return { valid: true };
+    case "scrollIntoView":
+      return hasTarget ? { valid: true } : { valid: false, error: "scrollIntoView needs sel= or text=" };
+    case "drop":
+      if (!hasTarget)
+        return { valid: false, error: "drop needs sel= or text= (the drop target)" };
+      if (!args.files || !args.files.length)
+        return { valid: false, error: "drop needs files= (array of file names)" };
+      return { valid: true };
+    case "clipboard":
+      if (args.mode === "write" && args.value === void 0)
+        return { valid: false, error: "clipboard write needs value=" };
+      return { valid: true };
     default:
       return { valid: false, error: `unknown action: ${type}` };
   }
@@ -63,6 +91,155 @@ function check(raw) {
   };
 }
 
+// src/core/perf.ts
+var FRAME_NOISE_PCT = 3;
+var SELF_NOISE_REL = 0.1;
+var SELF_NOISE_MS = 5;
+var avgOf = (samples) => samples.length > 0 ? samples.reduce((s, v) => s + v, 0) / samples.length : 0;
+function p95(samples) {
+  if (samples.length === 0) return 0;
+  const sorted = [...samples].sort((a, b) => a - b);
+  const idx = Math.floor(0.95 * sorted.length);
+  return sorted[idx] ?? 0;
+}
+function summarizeStat(stat) {
+  const avg = stat.n > 0 ? stat.total / stat.n : 0;
+  return {
+    total: stat.total,
+    n: stat.n,
+    avg,
+    max: stat.max,
+    p95: p95(stat.samples)
+  };
+}
+function compactPerformance(p) {
+  const all = p.buckets.find((b) => b.name === "__all__");
+  if (!all) return "perf: (no data)";
+  const { total, long, samples } = all.frames;
+  const fps = total > 0 ? Math.round(1e3 / avgOf(samples) * 10) / 10 : 0;
+  const droppedPct = total > 0 ? Math.round(long / total * 100) : 0;
+  const parts = [`${fps}fps`, `${droppedPct}% dropped`];
+  if (p.longtasks.count > 0) {
+    parts.push(`${p.longtasks.count} longtasks(max ${Math.round(p.longtasks.max)}ms)`);
+  }
+  const topComps = Object.entries(all.components).map(([name, stat]) => ({ name, total: stat.total })).sort((a, b) => b.total - a.total).slice(0, 2);
+  if (topComps.length > 0 && p.mobxPatched) {
+    const hot = topComps.map((c) => `${c.name} ${Math.round(c.total)}ms`).join(", ");
+    parts.push(`hot: ${hot}`);
+  }
+  return `perf: ${parts.join(" \xB7 ")}`;
+}
+function detailPerformance(p) {
+  const lines = [];
+  const windowSec = (p.windowMs / 1e3).toFixed(1);
+  lines.push(`=== Performance (${windowSec}s window) ===`);
+  if (p.hiddenFrames > 0) {
+    lines.push(`\u26A0 Tab was backgrounded \u2014 ${p.hiddenFrames} hidden frames skipped (rAF throttling lies about timing)`);
+    lines.push("For accurate profiling: keep tab FOREGROUND + run /profile/reset before reproducing");
+  }
+  lines.push(`MobX attribution: ${p.mobxPatched ? "ON" : "OFF"}`);
+  if (!p.mobxPatched) {
+    lines.push("(Component attribution disabled \u2014 set window.__AIPEEK_MOBX__={Reaction} in src/lib/mobx.ts to enable)");
+  }
+  lines.push("");
+  if (p.longtasks.count > 0) {
+    lines.push(`Longtasks (>50ms): ${p.longtasks.count}, max ${Math.round(p.longtasks.max)}ms`);
+    lines.push("");
+  }
+  const showPerView = p.buckets.length > 1;
+  for (const bucket of p.buckets) {
+    if (bucket.name !== "__all__" && !showPerView) continue;
+    lines.push(`--- ${bucket.name} ---`);
+    const { total, long, max, samples } = bucket.frames;
+    const droppedPct = total > 0 ? (long / total * 100).toFixed(1) : "0.0";
+    const avgFrame = avgOf(samples).toFixed(1);
+    lines.push(`Frames: ${total} total, ${long} dropped (${droppedPct}%), max ${Math.round(max)}ms, avg ${avgFrame}ms`);
+    const comps = Object.entries(bucket.components).map(([name, stat]) => ({ name, ...summarizeStat(stat) })).sort((a, b) => b.total - a.total).slice(0, 20);
+    if (comps.length > 0 && p.mobxPatched) {
+      lines.push("Components (by total self-time):");
+      for (const c of comps) {
+        lines.push(`  ${c.name.padEnd(30)} ${Math.round(c.total)}ms / ${c.n}\xD7 = ${c.avg.toFixed(1)}ms avg, max ${Math.round(c.max)}ms, p95 ${Math.round(c.p95)}ms`);
+      }
+    } else if (!p.mobxPatched) {
+      lines.push("(no component data \u2014 attribution OFF)");
+    }
+    const hotLines = Object.entries(bucket.lines ?? {}).map(([label, stat]) => ({ label, ...summarizeStat(stat) })).sort((a, b) => b.total - a.total).slice(0, 15);
+    if (hotLines.length > 0) {
+      lines.push("Hot lines (by total self-time):");
+      for (const l of hotLines) {
+        lines.push(`  ${l.label.padEnd(36)} ${Math.round(l.total)}ms / ${l.n}\xD7 = ${l.avg.toFixed(1)}ms avg, max ${Math.round(l.max)}ms`);
+      }
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function diffPerformance(before, after) {
+  const out = [];
+  const beforeAll = before.buckets.find((b) => b.name === "__all__");
+  const afterAll = after.buckets.find((b) => b.name === "__all__");
+  const droppedPct = (b) => b && b.frames.total > 0 ? b.frames.long / b.frames.total * 100 : 0;
+  const beforeDrop = droppedPct(beforeAll);
+  const afterDrop = droppedPct(afterAll);
+  const dropDelta = afterDrop - beforeDrop;
+  const sumTotal = (b) => b ? Object.values(b.components).reduce((s, c) => s + c.total, 0) : 0;
+  const beforeSelf = sumTotal(beforeAll);
+  const afterSelf = sumTotal(afterAll);
+  const selfDelta = afterSelf - beforeSelf;
+  const bothSampledFrames = (beforeAll?.frames.total ?? 0) > 0 && (afterAll?.frames.total ?? 0) > 0;
+  const sawDrops = (beforeAll?.frames.long ?? 0) > 0 || (afterAll?.frames.long ?? 0) > 0;
+  const framesExercised = bothSampledFrames && sawDrops;
+  let verdict;
+  if (framesExercised) {
+    if (dropDelta < -FRAME_NOISE_PCT) verdict = "IMPROVED";
+    else if (dropDelta > FRAME_NOISE_PCT) verdict = "REGRESSED";
+    else verdict = "UNCHANGED";
+  } else {
+    const floor = Math.max(SELF_NOISE_MS, beforeSelf * SELF_NOISE_REL);
+    if (selfDelta < -floor) verdict = "IMPROVED";
+    else if (selfDelta > floor) verdict = "REGRESSED";
+    else verdict = "UNCHANGED";
+  }
+  out.push(`=== Perf diff: ${verdict} ===`);
+  out.push(`Dropped frames: ${beforeDrop.toFixed(1)}% \u2192 ${afterDrop.toFixed(1)}% (${dropDelta >= 0 ? "+" : ""}${dropDelta.toFixed(1)}%)`);
+  if (!framesExercised && Math.round(selfDelta) !== 0) {
+    out.push(`Total self-time: ${Math.round(beforeSelf)}ms \u2192 ${Math.round(afterSelf)}ms (${selfDelta >= 0 ? "+" : ""}${Math.round(selfDelta)}ms) \u2014 frames flat, verdict by self-time`);
+  }
+  if (before.longtasks.count !== after.longtasks.count) {
+    out.push(`Longtasks: ${before.longtasks.count} \u2192 ${after.longtasks.count}`);
+  }
+  out.push("");
+  const compDelta = keyedTotalDelta(beforeAll?.components ?? {}, afterAll?.components ?? {});
+  if (compDelta.length > 0) {
+    out.push("Components (\u0394 total self-time):");
+    for (const d of compDelta) out.push("  " + formatDelta(d));
+    out.push("");
+  }
+  const lineDelta = keyedTotalDelta(beforeAll?.lines ?? {}, afterAll?.lines ?? {});
+  if (lineDelta.length > 0) {
+    out.push("Hot lines (\u0394 total self-time):");
+    for (const d of lineDelta) out.push("  " + formatDelta(d));
+  }
+  return out.join("\n").trimEnd();
+}
+function keyedTotalDelta(a, b) {
+  const keys = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
+  const rows = [];
+  for (const key of keys) {
+    const beforeT = a[key]?.total ?? 0;
+    const afterT = b[key]?.total ?? 0;
+    const delta = afterT - beforeT;
+    if (Math.round(delta) === 0) continue;
+    rows.push({ key, before: beforeT, after: afterT, delta, isNew: !a[key], gone: !b[key] });
+  }
+  return rows.sort((x, y) => Math.abs(y.delta) - Math.abs(x.delta)).slice(0, 20);
+}
+function formatDelta(d) {
+  const sign = d.delta >= 0 ? "+" : "";
+  const tag = d.isNew ? " (new)" : d.gone ? " (gone)" : "";
+  return `${d.key.padEnd(36)} ${Math.round(d.before)}ms \u2192 ${Math.round(d.after)}ms (${sign}${Math.round(d.delta)}ms)${tag}`;
+}
+
 // src/core/util.ts
 function truncate(s, max) {
   return s.length > max ? `${s.slice(0, max)}\u2026` : s;
@@ -118,6 +295,78 @@ function compactUrl(url, search) {
     return truncate(url, 80);
   }
 }
+var STALE_MS = 3e4;
+var isLive = (t, now) => now - t.lastSeen < STALE_MS;
+function formatTabs(tabs, now) {
+  const live = tabs.filter((t) => isLive(t, now));
+  if (!live.length)
+    return "(no live tabs)";
+  return live.sort((a, b) => Number(b.visible) - Number(a.visible) || a.id.localeCompare(b.id)).map((t) => {
+    const age = Math.round((now - t.lastSeen) / 1e3);
+    const mark = t.visible ? "\u25CF visible" : "\u25CB background";
+    return `${t.id}  ${mark}  ${truncate(t.title || "(untitled)", 40)}  ${compactUrl(t.url)}  ${age}s ago`;
+  }).join("\n");
+}
+function diagnose(tab, tabs, now, socketCount, port) {
+  if (tab) {
+    const t = tabs.find((x) => x.id === tab);
+    return t && isLive(t, now) ? `tab '${tab}' is connected but didn't answer in time \u2014 the handler likely threw or hung (bad selector, infinite loop, or a read that needs the tab foreground). Check /__aipeek/console.` : `tab '${tab}' is not connected \u2014 it closed, or the server restarted and it hasn't re-handshaked yet. Check /__aipeek/tabs for live ids; if the page is mid self-heal, retry in ~2s.`;
+  }
+  const live = tabs.filter((t) => isLive(t, now));
+  if (live.length)
+    return `${live.length} tab(s) connected but none answered \u2014 a handler threw, or they just closed. Check /__aipeek/tabs (still live?) and /__aipeek/console (errors?).`;
+  return socketCount > 0 ? `no aipeek tab registered, but ${socketCount} page(s) are connected to this dev server via HMR \u2014 the page is open yet the aipeek client didn't load. Is it served by THIS vite server on :${port}? A separate vite config / vite preview / production build won't inject it.` : `no browser tab connected to this dev server on :${port} \u2014 open the app, or check you're hitting the right port.`;
+}
+function formatActions(entries, anchorTs) {
+  if (!entries.length)
+    return "(no actions)";
+  const sorted = [...entries].sort((a, b) => a.ts - b.ts);
+  const multiTab = new Set(sorted.map((e) => e.tab).filter(Boolean)).size > 1;
+  const lines = [];
+  const prevByTab = /* @__PURE__ */ new Map();
+  let anchored = false;
+  for (const e of sorted) {
+    const isAnchor = anchorTs !== void 0 && !anchored && e.ts === anchorTs;
+    if (isAnchor) {
+      lines.push("\u2014\u2014\u2014\u2014\u2014\u2014 \u4F60\u5F53\u524D\u7684\u884C\u4E3A \u2014\u2014\u2014\u2014\u2014\u2014");
+      anchored = true;
+    }
+    const who = e.trusted ? "T" : "S";
+    const tag = multiTab ? `${e.tab ?? "?"} ` : "";
+    const val = e.value ? ` value="${e.value}"` : "";
+    const change = uiChange(prevByTab.get(e.tab), e);
+    lines.push(`${tag}[${who}] ${e.type} ${e.target}${val}${change ? `   \u2192 ${change}` : ""}`);
+    if (isAnchor)
+      lines.push("\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014");
+    prevByTab.set(e.tab, e);
+  }
+  return lines.join("\n");
+}
+function appendAction(log, tab, entry, max) {
+  const last = log[log.length - 1];
+  if (entry.type === "input" && last?.type === "input" && last.tab === tab && last.target === entry.target) {
+    log[log.length - 1] = { ...entry, tab };
+    return;
+  }
+  log.push({ ...entry, tab });
+  if (log.length > max)
+    log.shift();
+}
+function uiChange(prev, cur) {
+  if (cur.modal === void 0)
+    return "";
+  const prevModal = prev?.modal ?? "none";
+  if (cur.modal !== prevModal) {
+    if (cur.modal === "none")
+      return "\u5F39\u7A97\u5173\u95ED";
+    if (prevModal === "none")
+      return `\u5F39\u7A97\u6253\u5F00\u300C${cur.modal}\u300D`;
+    return `\u5F39\u7A97\u5207\u6362\u300C${cur.modal}\u300D`;
+  }
+  if (prev && cur.view !== void 0 && cur.view !== prev.view)
+    return `\u89C6\u56FE ${prev.view}\u2192${cur.view}`;
+  return "";
+}
 
 // src/core/compact.ts
 var SLOW_THRESHOLD = 1e3;
@@ -354,6 +603,7 @@ function compact(raw) {
     network: compactNetwork(raw.network),
     errors: compactErrors(raw.errors),
     state: compactState(raw.state),
+    performance: raw.performance ? detailPerformance(raw.performance) : void 0,
     timestamp: raw.timestamp,
     counts: {
       console: raw.console.length,
@@ -377,6 +627,8 @@ function detail(raw, section, index, full) {
       return detailError(raw.errors, index, full);
     case "state":
       return detailState(raw.state, index, full);
+    case "profile":
+      return raw.performance ? detailPerformance(raw.performance) : "(no perf data \u2014 is the tab foreground?)";
     default:
       return null;
   }
@@ -574,6 +826,43 @@ function byteSize(s) {
 }
 
 // src/core/diff.ts
+function diffScreen(before, after, newErrors, newExceptions, newFailedRequests) {
+  const lines = [];
+  if (after.view !== before.view)
+    lines.push(`view: ${before.view} \u2192 ${after.view}`);
+  if (after.modal !== before.modal) {
+    if (after.modal === "none")
+      lines.push(`modal: closed (${before.modal})`);
+    else if (before.modal === "none")
+      lines.push(`modal: opened ${after.modal}`);
+    else
+      lines.push(`modal: ${before.modal} \u2192 ${after.modal}`);
+  }
+  if (after.focus !== before.focus)
+    lines.push(`focus: ${after.focus}`);
+  const beforeDomain = before.domain ?? {};
+  const afterDomain = after.domain ?? {};
+  for (const key of /* @__PURE__ */ new Set([...Object.keys(beforeDomain), ...Object.keys(afterDomain)])) {
+    const b = stringifyDomain(beforeDomain[key]);
+    const a = stringifyDomain(afterDomain[key]);
+    if (b !== a)
+      lines.push(`${key}: ${b} \u2192 ${a}`);
+  }
+  for (const e of newErrors)
+    lines.push(`+error: ${e.text}`);
+  for (const e of newExceptions)
+    lines.push(`+exception: ${e.message}`);
+  for (const r of newFailedRequests)
+    lines.push(`+failed: ${r.method} ${r.url} \u2192 ${r.status || "failed"}`);
+  return lines;
+}
+function stringifyDomain(v) {
+  if (v === null || v === void 0)
+    return String(v);
+  if (typeof v === "object")
+    return JSON.stringify(v).slice(0, 80);
+  return String(v).slice(0, 80);
+}
 function diffState(prev, curr) {
   if (!prev) {
     return {
@@ -604,7 +893,7 @@ function diffState(prev, curr) {
 
 // src/core/emit.ts
 import pc from "picocolors";
-var SECTIONS = ["ui", "console", "network", "errors", "state"];
+var SECTIONS = ["ui", "console", "network", "errors", "state", "performance"];
 var COUNTED_SECTIONS = {
   console: "console",
   network: "network",
@@ -675,6 +964,15 @@ function emitSummary(raw) {
     lines.push(`errors (${raw.errors.length}):`);
     for (const e of raw.errors) lines.push(`  ${truncate(e.message, 150)}`);
   }
+  if (raw.performance) {
+    const all = raw.performance.buckets.find((b) => b.name === "__all__");
+    if (all) {
+      const droppedPct = all.frames.total > 0 ? all.frames.long / all.frames.total * 100 : 0;
+      if (droppedPct > 10) {
+        lines.push(compactPerformance(raw.performance));
+      }
+    }
+  }
   const storeNames = Object.keys(raw.state);
   if (storeNames.length) {
     const parts = storeNames.map((n) => {
@@ -782,12 +1080,24 @@ function aipeekSnippet(port) {
   return `
 # aipeek \u2014 Runtime Browser Inspector
 
+IMPORTANT: Before debugging any UI issue, visual bug, or runtime error, ALWAYS \`curl ${base}/screen\` to see the live app first. Do NOT guess, and do NOT ask the user to open or describe the page \u2014 you read it directly, including background tabs.
+
+- \`curl ${base}/screen\` \u2014 state-machine view of the UI (start here). \`/ui\`, \`/dom?scope=X\` for detail; \`/console\`, \`/network\`, \`/errors\`, \`/check\` for health.
+- \`curl ${base}/click?text=\u2026\` (also \`/fill\`, \`/press\`, \`/wait\`) \u2014 drive the page. POST \`/chain\` for a whole scripted interaction.
+- \`curl ${base}/help\` \u2014 full command reference (every endpoint, flags, federation, examples). Read it the first time you reach for a command you don't see above.`;
+}
+function helpText(port) {
+  const base = `http://localhost:${port}/__aipeek`;
+  return `
+# aipeek \u2014 Runtime Browser Inspector
+
 IMPORTANT: Before debugging any UI issue, visual bug, or runtime error, ALWAYS fetch the live app state first. Do NOT guess \u2014 look at the actual browser state.
 
 ## Read state \u2014 cheapest first
 
 \`\`\`bash
-curl ${base}/screen   # state-machine projection {view, modal, focus, knobs} \u2014 START HERE
+curl ${base}/screen   # state-machine projection {view, modal, focus, knobs} \u2014 START HERE (returns token: tN)
+curl '${base}/screen?since=tN'  # only what moved since that token (view/modal/focus + new errors), not a full snapshot
 curl ${base}/ui                  # React component tree \u2014 deep-dive when /screen isn't enough
 curl '${base}/dom?scope=ChatInput' # semantic DOM scoped to a component \u2014 UI as text, src locations
 curl ${base}          # high-density summary (ok sections \u2192 1 line, issues \u2192 expanded)
@@ -797,10 +1107,24 @@ curl ${base}/console  # console logs (errors, warnings, info)
 curl ${base}/network  # fetch/XHR requests with status and timing
 curl ${base}/errors   # uncaught errors and unhandled rejections
 curl ${base}/state    # registered store snapshots
+curl ${base}/tabs     # list live tabs (id, visible/background, title) for ?tab= addressing
+curl ${base}/timeline # interleaved action stream across all tabs (who clicked what, in order)
+curl '${base}/query?sel=[role=menuitem]' # this selector right now: count + each element's text/visible/attrs
+curl ${base}/profile  # performance profiler: which component/function is burning frames (+ source lines with AIPEEK_LINES=1)
+curl ${base}/profile/reset  # clear the profiler window, then reproduce the interaction
+curl ${base}/profile/diff  # closed loop: 1st call marks baseline, fix+reproduce, 2nd call \u2192 IMPROVED/REGRESSED verdict
 \`\`\`
 
+\`/query\` is the read-side twin of click/fill's \`sel=\` \u2014 assert on a specific element
+(how many match, its text, \`data-state\`, \`aria-*\`/\`data-*\`, value, disabled) without \`/eval\`.
+Secret fields (password inputs, API-key/token fields) show \`\u2039redacted N chars\u203A\` instead of
+their value across \`/dom\`, \`/query\` and \`/screen\` \u2014 length stays visible, the secret doesn't.
+
 \`/screen\` projects the whole UI to a few state variables \u2014 start there, not \`/ui\`. Append
-\`?full\` for untruncated output. Append \`/{index}\` for a specific item's detail.
+\`?full\` for untruncated output. Each read prints a \`token: tN\` line; pass it back as
+\`/screen?since=tN\` to get only the transition since that read (view/modal/focus + new
+errors/failed requests), \`(no state change)\` if nothing moved \u2014 the cheap "what changed
+after I acted" read, without re-paying for the unchanged 99%.
 
 To inspect or edit a component, work top-down \u2014 the full DOM is huge, a scoped view is
 accurate: \`/screen\` or \`/ui\` to find the component, then \`/dom?scope=<Name>\` (matches the
@@ -817,11 +1141,59 @@ curl '${base}/wait?text=Done&timeout=8000' # poll until text/sel appears (add go
 curl '${base}/screenshot?out=shot.png'   # DOM\u2192PNG into .aipeek/ (html-to-image; lossy)
 \`\`\`
 
-\`click\`/\`fill\`/\`press\` settle the DOM and append the resulting UI tree (\`--- ui after ---\`)
-to the response \u2014 no follow-up read needed. On a miss, the response lists the reachable
-clickable elements so you can re-target. URL-encode any \`sel=\` with non-ASCII or quotes:
+\`click\`/\`fill\`/\`press\` settle the DOM and append \`--- changed ---\`: only the state-machine
+transition this action caused (\`view: a \u2192 b\`, \`modal: opened X\`, \`focus: \u2026\`) plus any new
+errors/failed requests \u2014 not a fresh snapshot. \`(no state change)\` means nothing moved. Read
+the delta, then drill into /ui or /dom for detail if you need it. On a miss, the response lists
+the reachable clickable elements so you can re-target. URL-encode any \`sel=\` with non-ASCII or quotes:
 \`curl -G ${base}/click --data-urlencode 'sel=button[title="\u77E5\u8BC6\u5E93"]'\`.
 
+Each \`click\`/\`fill\`/\`press\` response also carries a \`--- recent actions ---\` timeline:
+the semantic page actions (yours and the user's) in order, \`T\`=trusted human / \`S\`=synthetic
+aipeek, each with its resulting UI change (\`\u2192 \u5F39\u7A97\u6253\u5F00\u300C\u2026\u300D\`/\`\u2192 \u5F39\u7A97\u5173\u95ED\`). Your own action is
+bracketed by \`\u4F60\u5F53\u524D\u7684\u884C\u4E3A\` dividers. So if the user closed a dialog you just opened, you see
+their \`T key:Escape \u2192 \u5F39\u7A97\u5173\u95ED\` right after your \`S\` action \u2014 no need to query for it.
+
+**Beyond click/fill/press** \u2014 four more interactions for what those can't reach:
+
+\`\`\`bash
+curl '${base}/scrollIntoView?text=Row 99'              # scroll a target into view (off-screen list rows)
+curl '${base}/drag?sel=.item&to=.slot'                 # synthetic pointer drag, source \u2192 destination
+curl '${base}/drop?sel=.dropzone&files=a.png,b.pdf'    # fire a file-drop (DataTransfer) on a target
+curl '${base}/clipboard?mode=write&value=hi'           # seed the clipboard (mode=read reports it back)
+\`\`\`
+
+\`drag\` fires a real pointer sequence (down \u2192 stepped moves past dnd-kit's activation
+distance \u2192 up); if a dnd-kit reorder doesn't take, retry the same gesture via \`realclick\`
+(trusted events). \`drop\` delivers the drop event with the named files (synthetic Files have
+no byte content \u2014 fine for triggering handlers, not for real uploads). \`clipboard\` needs the
+tab focused (browser security) and says so plainly when it isn't, rather than hanging.
+
+A control tagged \`{needs-trusted?}\` in \`/screen\` or \`/dom\` opens a popup (\`aria-haspopup\`)
+that a synthetic click may not trigger \u2014 reach for \`realclick\` on it from the start instead
+of discovering it via a dead click. (Right-click-only menus carry no DOM marker, so they
+still surface only on a miss \u2014 use \`realclick\` with \`button=right\` there.)
+
+**Multiple tabs.** Every read/drive command takes \`?tab=<id>\` to address one specific tab \u2014
+including a **background** one (you can drive the Chat tab while the user is looking at a
+different tab). Run \`${base}/tabs\` to see the live ids. With one tab open, omit \`?tab=\` and
+it just works. With several tabs open and no \`?tab=\`, the command returns \`409\` + the tab
+list (rather than randomly hitting one) \u2014 pick an id from it and retry with \`?tab=\`.
+
+**Multiple servers (federation).** When several dev servers run at once \u2014 a micro-frontend,
+separate front/back servers, or a teammate's machine \u2014 every command also takes
+\`?host=<host:port>\` to reach a *sibling* aipeek. The plugin you curl reverse-proxies the
+request to that peer (server-side, no browser): \`${base}/screen?host=localhost:5174\` reads
+the app on :5174; combine with \`?tab=\` to point at one tab over there
+(\`?host=192.168.1.9:5173&tab=t3\`). Omit \`?host=\` and it's the local server as always. There's
+no registry \u2014 you name the peer, so list its tabs with \`/tabs?host=<host:port>\` first.
+
+**Cross-tab timeline.** \`${base}/timeline\` interleaves the semantic actions of *every* tab
+in time order \u2014 each line \`<tab> [T|S] <action> \u2192 <ui change>\` (\`T\`=trusted human,
+\`S\`=synthetic aipeek). The per-action \`--- recent actions ---\` tail only shows the acting
+tab; \`/timeline\` is the group view, so an A/B comparison across two tabs (drive A, watch B
+react) is one read. \`?tab=<id>\` filters to one tab's history.
+
 **Chain \u2014 a whole interaction in one round-trip.** POST a JSON array; runs in sequence,
 each step settles before the next, stops on first failure:
 
@@ -830,39 +1202,46 @@ curl -X POST ${base}/chain -d '[
   {"type":"click","sel":"button[title=\\"\u77E5\u8BC6\u5E93\\"]"},
   {"type":"wait","text":"Done"},
   {"type":"fill","sel":"textarea","value":"hi"},
+  {"type":"assert","screen":"\u6D41\u5F0F\u4E2D","equals":"false"},
   {"type":"press","key":"Enter"}
 ]'
 \`\`\`
 
+\`assert\` is the chain's mid-step judge: \`{type,screen,equals}\` checks a domain variable
+(from the app's \`window.__AIPEEK_SCREEN__\`), or \`{type,sel,equals}\` an element's text. On
+mismatch the chain stops and reports \`asserted X=="Y", actual "Z"\` \u2014 a test, not a guess.
+Domain variables also show up in \`/screen\`'s \`domain:\` block and in every \`--- changed ---\`
+diff (e.g. \`\u6D41\u5F0F\u4E2D: false \u2192 true\`) \u2014 the app's own state machine, which a DOM-only inspector
+can't see. The app opts in by setting \`window.__AIPEEK_SCREEN__ = () => ({...})\`.
+
 **Escape hatch.** \`curl '${base}/eval?code=...'\` (or POST the code as the body) runs arbitrary
-JS in the page and returns the result \u2014 for anything the typed endpoints can't do.
+JS in the page and returns the result \u2014 for what the typed endpoints can't do (install listeners,
+read closures, probe event flow). For count/text/state/attr assertions reach for \`/query\` first.
 
 aipeek auto-detects errors after HMR and prints them to the terminal \u2014 watch for \`[aipeek]\` messages.
 `;
 }
 var START_TAG = "<!-- AIPEEK:START -->";
 var END_TAG = "<!-- AIPEEK:END -->";
-function injectClaudeMd(root, port) {
-  const path = resolve(root, "CLAUDE.md");
+function renderClaudeMd(existing, port) {
   const block = `${START_TAG}
 ${aipeekSnippet(port).trim()}
 ${END_TAG}
 `;
+  if (existing === null)
+    return block;
+  const si = existing.indexOf(START_TAG);
+  const ei = existing.indexOf(END_TAG);
+  if (si !== -1 && ei !== -1)
+    return existing.slice(0, si) + block.trimEnd() + existing.slice(ei + END_TAG.length);
+  const sep = existing.endsWith("\n") ? "" : "\n";
+  return `${existing}${sep}
+${block}`;
+}
+function injectClaudeMd(root, port) {
+  const path = resolve(root, "CLAUDE.md");
   try {
-    if (!existsSync(path)) {
-      writeFileSync(path, block);
-      return;
-    }
-    const content = readFileSync(path, "utf-8");
-    const si = content.indexOf(START_TAG);
-    const ei = content.indexOf(END_TAG);
-    if (si !== -1 && ei !== -1) {
-      writeFileSync(path, content.slice(0, si) + block.trimEnd() + content.slice(ei + END_TAG.length));
-      return;
-    }
-    const sep = content.endsWith("\n") ? "" : "\n";
-    writeFileSync(path, `${content}${sep}
-${block}`);
+    writeFileSync(path, renderClaudeMd(existsSync(path) ? readFileSync(path, "utf-8") : null, port));
   } catch {
   }
 }
@@ -870,21 +1249,107 @@ function aipeekPlugin() {
   let pendingResolve = null;
   let server;
   let lastRaw = null;
+  let perfBaseline = null;
   let pushTimer;
   const pendingActions = /* @__PURE__ */ new Map();
   let actionId = 0;
+  const tabs = /* @__PURE__ */ new Map();
+  function seen(data) {
+    if (!data.tab)
+      return;
+    const prev = tabs.get(data.tab);
+    tabs.set(data.tab, {
+      id: data.tab,
+      url: data.url ?? prev?.url ?? "",
+      title: data.title ?? prev?.title ?? "",
+      visible: data.visible ?? prev?.visible ?? false,
+      lastSeen: Date.now()
+    });
+  }
+  const liveTabs = () => [...tabs.values()].filter((t) => isLive(t, Date.now()));
+  const diagnose2 = (tab) => diagnose(tab, [...tabs.values()], Date.now(), server.ws.clients.size, server.config.server.port || 5173);
+  const actionLog = [];
+  const BOOT_ID = Date.now().toString(36);
+  const mergeActions = (tab, actions) => {
+    if (!tab || !actions?.length)
+      return;
+    for (const entry of actions) {
+      if (!actionLog.some((e) => e.tab === tab && e.ts === entry.ts))
+        appendAction(actionLog, tab, entry, 200);
+    }
+  };
+  const cdpQueue = [];
+  let cdpWaiter = null;
+  const cdpResults = /* @__PURE__ */ new Map();
+  let cdpId = 0;
+  function runCdpClick(x, y, button) {
+    const id = ++cdpId;
+    const cmd = { id, x, y, button };
+    return new Promise((resolve2, reject) => {
+      cdpResults.set(id, resolve2);
+      if (cdpWaiter) {
+        cdpWaiter(cmd);
+        cdpWaiter = null;
+      } else {
+        cdpQueue.push(cmd);
+      }
+      setTimeout(() => {
+        if (cdpResults.delete(id))
+          reject(new Error("cdp timeout: no extension result within 10s (is the aipeek extension loaded and the debugger attached?)"));
+      }, 1e4);
+    });
+  }
   let pendingDom = null;
   let pendingScreen = null;
   const pendingEvals = /* @__PURE__ */ new Map();
   let evalId = 0;
+  const screenStash = /* @__PURE__ */ new Map();
+  let screenToken = 0;
+  function stashScreen(r) {
+    const token = `t${++screenToken}`;
+    screenStash.set(token, { snap: r.snap, console: r.console, network: r.network, errors: r.errors });
+    if (screenStash.size > 32)
+      screenStash.delete(screenStash.keys().next().value);
+    return token;
+  }
   const VISIBLE_MS = 400;
-  function twoPhase(event, payload, arm, fullMs = 3e3) {
+  function twoPhase(event, payload, arm, fullMs = 3e3, tab) {
     return new Promise((resolve2, reject) => {
       let settled = false;
       const clear = arm((v) => {
         settled = true;
         resolve2(v);
       });
+      if (tab) {
+        const RETRY_MS = 500;
+        const ABSENT_CEILING_MS = 1e4;
+        const startedAt = Date.now();
+        const deliver = () => server.hot.send(event, { ...payload, tab });
+        deliver();
+        const iv = setInterval(() => {
+          if (settled) {
+            clearInterval(iv);
+            return;
+          }
+          const t = tabs.get(tab);
+          const live = !!t && isLive(t, Date.now());
+          const elapsed = Date.now() - startedAt;
+          if (live) {
+            if (elapsed > fullMs) {
+              clearInterval(iv);
+              clear();
+              reject(new Error(diagnose2(tab)));
+            }
+          } else if (elapsed > ABSENT_CEILING_MS) {
+            clearInterval(iv);
+            clear();
+            reject(new Error(diagnose2(tab)));
+          } else {
+            deliver();
+          }
+        }, RETRY_MS);
+        return;
+      }
       server.hot.send(event, { ...payload, requireVisible: true });
       setTimeout(() => {
         if (settled)
@@ -894,36 +1359,36 @@ function aipeekPlugin() {
           if (settled)
             return;
           clear();
-          reject(new Error(`timeout: no client response within ${VISIBLE_MS + fullMs}ms`));
+          reject(new Error(diagnose2(tab)));
         }, fullMs);
       }, VISIBLE_MS);
     });
   }
-  function collectFromClient() {
+  function collectFromClient(tab) {
     return twoPhase("aipeek:collect", {}, (resolve2) => {
       pendingResolve = resolve2;
       return () => {
         pendingResolve = null;
       };
-    });
+    }, 3e3, tab);
   }
-  function collectDomFromClient(scope, sel) {
+  function collectDomFromClient(scope, sel, tab) {
     return twoPhase("aipeek:collect-dom", { scope, sel }, (resolve2) => {
       pendingDom = resolve2;
       return () => {
         pendingDom = null;
       };
-    });
+    }, 3e3, tab);
   }
-  function collectScreenFromClient() {
+  function collectScreenFromClient(tab) {
     return twoPhase("aipeek:collect-screen", {}, (resolve2) => {
       pendingScreen = resolve2;
       return () => {
         pendingScreen = null;
       };
-    });
+    }, 3e3, tab);
   }
-  function sendAction(type, args) {
+  function sendAction(type, args, tab) {
     const id = ++actionId;
     const fullMs = Math.max(args.timeout ?? 0, 3e3) + 2e3;
     return twoPhase("aipeek:action", { id, type, args }, (resolve2) => {
@@ -931,16 +1396,28 @@ function aipeekPlugin() {
       return () => {
         pendingActions.delete(id);
       };
-    }, fullMs);
+    }, fullMs, tab);
+  }
+  async function runAction(type, args, tab) {
+    const result = await sendAction(type, args, tab);
+    lastRaw = null;
+    if (type === "realclick" && result.ok && !result.fired) {
+      const cdp = await runCdpClick(result.x, result.y, args.button ?? "left");
+      if (!cdp.ok)
+        return { ok: false, error: `cdp click failed: ${cdp.error ?? "unknown"}` };
+      result.detail = `${result.detail} \u2192 clicked via extension`;
+      result.screen = (await collectScreenFromClient(tab)).screen;
+    }
+    return result;
   }
-  function evalInClient(code) {
+  function evalInClient(code, tab) {
     const id = ++evalId;
     return twoPhase("aipeek:eval", { id, code }, (resolve2) => {
       pendingEvals.set(id, resolve2);
       return () => {
         pendingEvals.delete(id);
       };
-    }, 8e3);
+    }, 8e3, tab);
   }
   return {
     name: "aipeek",
@@ -968,12 +1445,16 @@ function aipeekPlugin() {
       server = _server;
       injectClaudeMd(server.config.root, server.config.server.port || 5173);
       server.hot.on("aipeek:state", (data) => {
+        seen(data);
+        mergeActions(data.tab, data.actions);
         if (pendingResolve) {
           pendingResolve(data);
           pendingResolve = null;
         }
       });
+      server.hot.on("aipeek:hello", (data) => seen(data));
       server.hot.on("aipeek:result", (data) => {
+        seen(data);
         const resolve2 = pendingActions.get(data.id);
         if (resolve2) {
           pendingActions.delete(data.id);
@@ -981,6 +1462,7 @@ function aipeekPlugin() {
         }
       });
       server.hot.on("aipeek:eval-result", (data) => {
+        seen(data);
         const resolve2 = pendingEvals.get(data.id);
         if (resolve2) {
           pendingEvals.delete(data.id);
@@ -988,14 +1470,16 @@ function aipeekPlugin() {
         }
       });
       server.hot.on("aipeek:dom", (data) => {
+        seen(data);
         if (pendingDom) {
           pendingDom(data.dom);
           pendingDom = null;
         }
       });
       server.hot.on("aipeek:screen", (data) => {
+        seen(data);
         if (pendingScreen) {
-          pendingScreen(data.screen);
+          pendingScreen(data);
           pendingScreen = null;
         }
       });
@@ -1019,7 +1503,56 @@ function aipeekPlugin() {
         const url = new URL(req.url || "/", "http://localhost");
         const parts = url.pathname.split("/").filter(Boolean);
         const full = url.searchParams.has("full");
+        const tab = url.searchParams.get("tab") || void 0;
+        const host = url.searchParams.get("host") || void 0;
+        const selfPort = server.config.server.port || 5173;
+        const selfHosts = /* @__PURE__ */ new Set([`localhost:${selfPort}`, `127.0.0.1:${selfPort}`, `:${selfPort}`, `${selfPort}`]);
+        if (host && !selfHosts.has(host)) {
+          const fwd = new URL(url);
+          fwd.searchParams.delete("host");
+          const target = `http://${host}/__aipeek/${parts.join("/")}${fwd.search}`;
+          try {
+            const body = req.method === "POST" ? await readBody(req) : void 0;
+            const r = await fetch(target, { method: req.method, body });
+            send(res, r.status, await r.text());
+          } catch (e) {
+            const code = e.cause?.code;
+            const why = code === "ECONNREFUSED" ? `nothing is listening on ${host} \u2014 its dev server isn't running (start it), or the port is wrong.` : code === "ENOTFOUND" ? `host '${host}' doesn't resolve \u2014 check the hostname.` : code === "ETIMEDOUT" || code === "UND_ERR_CONNECT_TIMEOUT" ? `connection to ${host} timed out \u2014 it's unreachable (firewall, or wrong host).` : `${e.message} (code ${code ?? "unknown"}).`;
+            send(res, 502, `cannot reach aipeek peer at ${host}: ${why}`);
+          }
+          return;
+        }
+        if (parts[0] === "ping") {
+          send(res, 200, BOOT_ID);
+          return;
+        }
+        if (parts[0] === "help") {
+          send(res, 200, helpText(selfPort).trim());
+          return;
+        }
+        const ambiguous = () => !tab && !["tabs", "timeline", "cdp"].includes(parts[0]) && liveTabs().length > 1;
+        const refuse = () => send(res, 409, `multiple live tabs \u2014 add ?tab=<id>:
+
+${formatTabs(liveTabs(), Date.now())}`);
         try {
+          if (parts[0] === "tabs") {
+            const roster = formatTabs(liveTabs(), Date.now());
+            send(res, 200, roster === "(no live tabs)" ? `(${diagnose2()})` : roster);
+            return;
+          }
+          if (parts[0] === "timeline") {
+            const targets = tab ? [tab] : liveTabs().map((t) => t.id);
+            for (const id of targets)
+              await collectFromClient(id).catch(() => {
+              });
+            const entries = tab ? actionLog.filter((e) => e.tab === tab) : actionLog;
+            send(res, 200, formatActions(entries));
+            return;
+          }
+          if (ambiguous()) {
+            refuse();
+            return;
+          }
           if (parts[0] === "eval") {
             let code = url.searchParams.get("code") || "";
             if (!code && req.method === "POST")
@@ -1028,21 +1561,78 @@ function aipeekPlugin() {
               send(res, 400, "eval needs ?code= or a POST body");
               return;
             }
-            const r = await evalInClient(code);
+            const r = await evalInClient(code, tab);
             send(res, r.ok ? 200 : 422, r.ok ? r.value ?? "undefined" : `error: ${r.error}`);
             return;
           }
           if (parts[0] === "dom") {
             const dom = await collectDomFromClient(
               url.searchParams.get("scope") || void 0,
-              url.searchParams.get("sel") || void 0
+              url.searchParams.get("sel") || void 0,
+              tab
             );
             send(res, 200, dom || "(empty)");
             return;
           }
           if (parts[0] === "screen") {
-            const screen = await collectScreenFromClient();
-            send(res, 200, screen || "(empty)");
+            const reply = await collectScreenFromClient(tab);
+            const since = url.searchParams.get("since");
+            const token = stashScreen(reply);
+            if (since) {
+              const prev = screenStash.get(since);
+              if (!prev) {
+                send(res, 422, `unknown since token "${since}" (expired or never issued) \u2014 read /screen first for a fresh token`);
+                return;
+              }
+              const d = diffState(
+                { ui: "", console: prev.console, network: prev.network, errors: prev.errors, state: {}, url: "", timestamp: 0 },
+                { ui: "", console: reply.console, network: reply.network, errors: reply.errors, state: {}, url: "", timestamp: 0 }
+              );
+              const changed = diffScreen(prev.snap, reply.snap, d.newErrors, d.newExceptions, d.newFailedRequests);
+              send(res, 200, `token: ${token}
+${changed.length ? changed.join("\n") : "(no state change)"}`);
+              return;
+            }
+            send(res, 200, reply.screen ? `token: ${token}
+${reply.screen}` : "(empty)");
+            return;
+          }
+          if (parts[0] === "cdp" && parts[1] === "poll") {
+            const queued = cdpQueue.shift();
+            if (queued) {
+              send(res, 200, JSON.stringify(queued));
+              return;
+            }
+            const cmd = await new Promise((resolve2) => {
+              cdpWaiter = resolve2;
+              setTimeout(() => {
+                if (cdpWaiter === resolve2) {
+                  cdpWaiter = null;
+                  resolve2(null);
+                }
+              }, 25e3);
+            });
+            if (cmd)
+              send(res, 200, JSON.stringify(cmd));
+            else
+              send(res, 204, "");
+            return;
+          }
+          if (parts[0] === "cdp" && parts[1] === "result") {
+            const body = await readBody(req);
+            let data;
+            try {
+              data = JSON.parse(body);
+            } catch {
+              send(res, 400, "cdp/result needs a JSON body {id, ok, error?}");
+              return;
+            }
+            const resolveCdp = cdpResults.get(data.id);
+            if (resolveCdp) {
+              cdpResults.delete(data.id);
+              resolveCdp({ ok: data.ok, error: data.error });
+            }
+            send(res, 200, "ok");
             return;
           }
           if (parts[0] === "chain") {
@@ -1058,7 +1648,7 @@ function aipeekPlugin() {
             }
             lastRaw = null;
             const lines = [];
-            let lastUi = "";
+            let lastActions = "";
             let allOk = true;
             for (let i = 0; i < steps.length; i++) {
               const { type, ...args } = steps[i];
@@ -1068,24 +1658,25 @@ function aipeekPlugin() {
                 allOk = false;
                 break;
               }
-              const r = await sendAction(type, args);
+              const r = await runAction(type, args, tab);
               lines.push(`[${i}] ${r.ok ? "\u2713" : "\u2717"} ${type}: ${r.ok ? r.detail || "ok" : r.error}`);
               if (r.screen)
                 lines.push(r.screen.split("\n").map((l) => `    ${l}`).join("\n"));
-              if (r.ui)
-                lastUi = r.ui;
+              if (r.actions)
+                lastActions = r.actions;
               if (!r.ok) {
                 allOk = false;
                 break;
               }
             }
-            send(res, allOk ? 200 : 422, lastUi ? `${lines.join("\n")}
+            const chainActions = lastActions ? `
 
---- ui after ---
-${lastUi}` : lines.join("\n"));
+--- recent actions ---
+${lastActions}` : "";
+            send(res, allOk ? 200 : 422, `${lines.join("\n")}${chainActions}`);
             return;
           }
-          if (["click", "fill", "press", "wait", "screenshot"].includes(parts[0])) {
+          if (["click", "fill", "press", "wait", "screenshot", "realclick", "query", "assert", "drag", "scrollIntoView", "drop", "clipboard"].includes(parts[0])) {
             const q = url.searchParams;
             const args = {
               sel: q.get("sel") || void 0,
@@ -1093,15 +1684,22 @@ ${lastUi}` : lines.join("\n"));
               value: q.has("value") ? q.get("value") : void 0,
               key: q.get("key") || void 0,
               timeout: q.has("timeout") ? Number(q.get("timeout")) : void 0,
-              gone: q.has("gone") ? q.get("gone") !== "false" : void 0
+              gone: q.has("gone") ? q.get("gone") !== "false" : void 0,
+              button: q.get("button") === "right" ? "right" : q.get("button") === "left" ? "left" : void 0,
+              x: q.has("x") ? Number(q.get("x")) : void 0,
+              y: q.has("y") ? Number(q.get("y")) : void 0,
+              screen: q.get("screen") || void 0,
+              equals: q.has("equals") ? q.get("equals") : void 0,
+              to: q.get("to") || void 0,
+              files: q.has("files") ? q.get("files").split(",").map((s) => s.trim()).filter(Boolean) : void 0,
+              mode: q.get("mode") === "write" ? "write" : q.get("mode") === "read" ? "read" : void 0
             };
             const check2 = resolveAction(parts[0], args);
             if (!check2.valid) {
               send(res, 400, check2.error ?? "invalid action");
               return;
             }
-            const result = await sendAction(parts[0], args);
-            lastRaw = null;
+            const result = await runAction(parts[0], args, tab);
             if (parts[0] === "screenshot" && result.dataUrl) {
               const dir = resolve(server.config.root, ".aipeek");
               mkdirSync(dir, { recursive: true });
@@ -1114,32 +1712,89 @@ ${lastUi}` : lines.join("\n"));
             const head = result.ok ? result.detail || "ok" : `${result.error}${result.detail ? `
 
 clickable: ${result.detail}` : ""}`;
-            send(res, result.ok ? 200 : 422, result.ui ? `${head}
+            const actionsTail = result.actions ? `
 
---- ui after ---
-${result.ui}` : head);
+--- recent actions ---
+${result.actions}` : "";
+            const changedTail = result.screen ? `
+
+--- changed ---
+${result.screen}` : "";
+            send(res, result.ok ? 200 : 422, `${head}${actionsTail}${changedTail}`);
             return;
           }
           if (parts[0] === "check") {
-            const raw2 = await collectFromClient();
+            const raw2 = await collectFromClient(tab);
             lastRaw = raw2;
             const result = check(raw2);
             const output = emitCheck(result);
             send(res, result.pass ? 200 : 417, output);
             return;
           }
+          if (parts[0] === "profile") {
+            const noPerfMsg = (t) => {
+              const info = t ? tabs.get(t) : liveTabs()[0];
+              return info ? `tab '${info.id}' is connected but BACKGROUNDED \u2014 the browser throttles rAF to ~1fps for hidden tabs, so there are no real frames to profile. You don't need to open anything: the page is already running. Ask the user to click that browser tab to the foreground and keep it there ~2s, then re-run /profile. (Profiling is the only read needing foreground \u2014 /screen and /dom work backgrounded.)` : `(${diagnose2(t)})`;
+            };
+            const resetPerfWindow = () => new Promise((resolve2, reject) => {
+              const timeout = setTimeout(() => reject(new Error("timeout waiting for perf-reset-ack")), 3e3);
+              const handler = (data) => {
+                if (tab && data.tab !== tab) return;
+                clearTimeout(timeout);
+                server.hot.off("aipeek:perf-reset-ack", handler);
+                resolve2();
+              };
+              server.hot.on("aipeek:perf-reset-ack", handler);
+              server.hot.send("aipeek:perf-reset", { tab, requireVisible: false });
+            });
+            if (parts[1] === "reset") {
+              await resetPerfWindow();
+              send(res, 200, "perf window cleared \u2014 reproduce the interaction, then GET /profile");
+              return;
+            }
+            if (parts[1] === "diff") {
+              const raw3 = await collectFromClient(tab);
+              lastRaw = raw3;
+              if (!raw3.performance) {
+                send(res, 200, noPerfMsg(tab));
+                return;
+              }
+              if (!perfBaseline) {
+                perfBaseline = raw3.performance;
+                await resetPerfWindow();
+                send(res, 200, "baseline captured + window cleared \u2014 make your fix, reproduce the interaction, then GET /profile/diff again for the verdict");
+                return;
+              }
+              const report = diffPerformance(perfBaseline, raw3.performance);
+              perfBaseline = null;
+              send(res, 200, report);
+              return;
+            }
+            const raw2 = await collectFromClient(tab);
+            lastRaw = raw2;
+            if (!raw2.performance) {
+              send(res, 200, noPerfMsg(tab));
+              return;
+            }
+            const hiddenNote = raw2.performance.hiddenFrames > 10 ? `
+
+\u26A0 ${raw2.performance.hiddenFrames} frames skipped while tab was hidden \u2014 bring it to foreground and /profile/reset for accurate data.` : "";
+            send(res, 200, detail(raw2, "profile", void 0, false) + hiddenNote);
+            return;
+          }
           if (parts.length >= 1) {
             if (!lastRaw)
-              lastRaw = await collectFromClient();
+              lastRaw = await collectFromClient(tab);
             const result = detail(lastRaw, parts[0], parts[1], full);
             if (result !== null) {
               send(res, 200, result);
               return;
             }
-            send(res, 404, `not found: ${parts.join("/")}`);
+            const SECTIONS2 = ["ui", "console", "network", "errors", "state", "profile"];
+            send(res, 404, SECTIONS2.includes(parts[0]) ? `'${parts[0]}' is empty right now \u2014 nothing captured this window (not an error).` : `unknown section '${parts[0]}'. Valid: ${SECTIONS2.join(", ")}. (Or /screen, /dom, /tabs, /timeline, /check.)`);
             return;
           }
-          const raw = await collectFromClient();
+          const raw = await collectFromClient(tab);
           lastRaw = raw;
           if (full) {
             const compacted = compact(raw);
@@ -1163,6 +1818,7 @@ export {
   emitDiff,
   START_TAG,
   END_TAG,
+  renderClaudeMd,
   injectClaudeMd,
   aipeekPlugin
 };