aipeek 0.2.7 → 0.2.9

package/dist/{chunk-37VLLZIU.js → chunk-7NJSWR7E.js}

@@ -6,7 +6,7 @@ import { fileURLToPath } from "url";
 import { transformSync } from "esbuild";
 
 // src/core/action.ts
-var TYPES = ["click", "fill", "press", "wait", "screenshot", "realclick", "query"];
+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}` };
@@ -30,6 +30,30 @@ function resolveAction(type, args) {
       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}` };
   }
@@ -67,6 +91,156 @@ 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 summarizeStat(stat) {
+  const avg = stat.n > 0 ? stat.total / stat.n : 0;
+  return {
+    total: stat.total,
+    n: stat.n,
+    avg,
+    max: stat.max
+  };
+}
+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`);
+      }
+    } 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 inclusive time \u2014 contains nested calls):");
+      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;
+  const afterBlind = (afterAll?.frames.total ?? 0) === 0 && afterSelf === 0;
+  let verdict;
+  if (afterBlind) {
+    verdict = "NO DATA";
+  } else 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} ===`);
+  if (afterBlind) {
+    out.push("after-window recorded no frames and no self-time \u2014 tab backgrounded or idle. Re-run with the tab focused and the interaction reproduced.");
+    out.push("");
+    return out.join("\n").trimEnd();
+  }
+  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 inclusive 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;
@@ -122,6 +296,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;
@@ -358,6 +604,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,
@@ -381,6 +628,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;
   }
@@ -578,6 +827,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 {
@@ -608,7 +894,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",
@@ -679,6 +965,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) => {
@@ -786,12 +1081,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)
@@ -801,14 +1108,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
@@ -825,11 +1142,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:
 
@@ -838,10 +1203,18 @@ 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 what the typed endpoints can't do (install listeners,
 read closures, probe event flow). For count/text/state/attr assertions reach for \`/query\` first.
@@ -877,9 +1250,35 @@ 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();
@@ -905,14 +1304,53 @@ function aipeekPlugin() {
   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)
@@ -922,36 +1360,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) => {
@@ -959,28 +1397,28 @@ function aipeekPlugin() {
       return () => {
         pendingActions.delete(id);
       };
-    }, fullMs);
+    }, fullMs, tab);
   }
-  async function runAction(type, args) {
-    const result = await sendAction(type, args);
+  async function runAction(type, args, tab) {
+    const result = await sendAction(type, args, tab);
     lastRaw = null;
-    if (type === "realclick" && result.ok && result.ui === void 0) {
+    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.ui = await collectScreenFromClient();
+      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",
@@ -1008,12 +1446,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);
@@ -1021,6 +1463,7 @@ function aipeekPlugin() {
         }
       });
       server.hot.on("aipeek:eval-result", (data) => {
+        seen(data);
         const resolve2 = pendingEvals.get(data.id);
         if (resolve2) {
           pendingEvals.delete(data.id);
@@ -1028,14 +1471,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;
         }
       });
@@ -1059,7 +1504,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")
@@ -1068,21 +1562,40 @@ 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") {
@@ -1136,7 +1649,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];
@@ -1146,24 +1659,25 @@ function aipeekPlugin() {
                 allOk = false;
                 break;
               }
-              const r = await runAction(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", "realclick", "query"].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,
@@ -1174,14 +1688,19 @@ ${lastUi}` : lines.join("\n"));
               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
+              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 runAction(parts[0], args);
+            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 });
@@ -1194,32 +1713,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);