aipeek 0.2.6 → 0.2.8

package/src/server/plugin.ts

@@ -1,6 +1,6 @@
 import type { Plugin, ViteDevServer } from 'vite'
 import type { ActionArgs, ActionResult } from '../core/action'
-import type { RawState } from '../core/types'
+import type { ActionEntry, ErrorEntry, LogEntry, NetworkRequest, PerformanceData, RawState, ScreenSnap, TabInfo } from '../core/types'
 import { Buffer } from 'node:buffer'
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
@@ -10,8 +10,10 @@ import { resolveAction } from '../core/action'
 import { check } from '../core/check'
 import { compact } from '../core/compact'
 import { detail } from '../core/detail'
-import { diffState } from '../core/diff'
+import { diffScreen, diffState } from '../core/diff'
 import { emit, emitCheck, emitDiff, emitSummary } from '../core/emit'
+import { diffPerformance } from '../core/perf'
+import { appendAction, diagnose as diagnoseConn, formatActions, formatTabs, isLive } from '../core/util'
 
 function readBody(req: { on: (e: string, cb: (c: unknown) => void) => void }): Promise<string> {
     return new Promise((resolve) => {
@@ -49,17 +51,36 @@ function compilePatch(): string {
     return result.code
 }
 
+// What lands in CLAUDE.md, resident every session. It earns that residency only by the one
+// behaviour it must trigger — "go look at the live page, don't guess, don't ask the user to
+// open it" — plus where to get everything else. The full command catalogue is reference, not
+// trigger: the model is already curling aipeek the moment it needs a command, so the catalogue
+// rides along on `curl …/help` then, instead of sitting in context every session (the exact
+// always-resident cost this tool exists to avoid). 7 lines, not 134.
 function aipeekSnippet(port: number) {
     const base = `http://localhost:${port}/__aipeek`
     return `
 # aipeek — 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 — you read it directly, including background tabs.
+
+- \`curl ${base}/screen\` — state-machine view of the UI (start here). \`/ui\`, \`/dom?scope=X\` for detail; \`/console\`, \`/network\`, \`/errors\`, \`/check\` for health.
+- \`curl ${base}/click?text=…\` (also \`/fill\`, \`/press\`, \`/wait\`) — drive the page. POST \`/chain\` for a whole scripted interaction.
+- \`curl ${base}/help\` — 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: number) {
+    const base = `http://localhost:${port}/__aipeek`
+    return `
+# aipeek — Runtime Browser Inspector
+
 IMPORTANT: Before debugging any UI issue, visual bug, or runtime error, ALWAYS fetch the live app state first. Do NOT guess — look at the actual browser state.
 
 ## Read state — cheapest first
 
 \`\`\`bash
-curl ${base}/screen   # state-machine projection {view, modal, focus, knobs} — START HERE
+curl ${base}/screen   # state-machine projection {view, modal, focus, knobs} — 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 — deep-dive when /screen isn't enough
 curl '${base}/dom?scope=ChatInput' # semantic DOM scoped to a component — UI as text, src locations
 curl ${base}          # high-density summary (ok sections → 1 line, issues → expanded)
@@ -69,10 +90,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 → IMPROVED/REGRESSED verdict
 \`\`\`
 
+\`/query\` is the read-side twin of click/fill's \`sel=\` — 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 \`‹redacted N chars›\` instead of
+their value across \`/dom\`, \`/query\` and \`/screen\` — length stays visible, the secret doesn't.
+
 \`/screen\` projects the whole UI to a few state variables — 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 — the cheap "what changed
+after I acted" read, without re-paying for the unchanged 99%.
 
 To inspect or edit a component, work top-down — the full DOM is huge, a scoped view is
 accurate: \`/screen\` or \`/ui\` to find the component, then \`/dom?scope=<Name>\` (matches the
@@ -89,11 +124,59 @@ curl '${base}/wait?text=Done&timeout=8000' # poll until text/sel appears (add go
 curl '${base}/screenshot?out=shot.png'   # DOM→PNG into .aipeek/ (html-to-image; lossy)
 \`\`\`
 
-\`click\`/\`fill\`/\`press\` settle the DOM and append the resulting UI tree (\`--- ui after ---\`)
-to the response — 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 → b\`, \`modal: opened X\`, \`focus: …\`) plus any new
+errors/failed requests — 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="知识库"]'\`.
 
+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 (\`→ 弹窗打开「…」\`/\`→ 弹窗关闭\`). Your own action is
+bracketed by \`你当前的行为\` dividers. So if the user closed a dialog you just opened, you see
+their \`T key:Escape → 弹窗关闭\` right after your \`S\` action — no need to query for it.
+
+**Beyond click/fill/press** — 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 → 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 → stepped moves past dnd-kit's activation
+distance → 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 — 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 — 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 — use \`realclick\` with \`button=right\` there.)
+
+**Multiple tabs.** Every read/drive command takes \`?tab=<id>\` to address one specific tab —
+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) — pick an id from it and retry with \`?tab=\`.
+
+**Multiple servers (federation).** When several dev servers run at once — a micro-frontend,
+separate front/back servers, or a teammate's machine — 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 — 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 — each line \`<tab> [T|S] <action> → <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 — a whole interaction in one round-trip.** POST a JSON array; runs in sequence,
 each step settles before the next, stops on first failure:
 
@@ -102,12 +185,21 @@ curl -X POST ${base}/chain -d '[
   {"type":"click","sel":"button[title=\\"知识库\\"]"},
   {"type":"wait","text":"Done"},
   {"type":"fill","sel":"textarea","value":"hi"},
+  {"type":"assert","screen":"流式中","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"\` — a test, not a guess.
+Domain variables also show up in \`/screen\`'s \`domain:\` block and in every \`--- changed ---\`
+diff (e.g. \`流式中: false → true\`) — 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 — for anything the typed endpoints can't do.
+JS in the page and returns the result — 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 — watch for \`[aipeek]\` messages.
 `
@@ -116,44 +208,140 @@ aipeek auto-detects errors after HMR and prints them to the terminal — watch f
 export const START_TAG = '<!-- AIPEEK:START -->'
 export const END_TAG = '<!-- AIPEEK:END -->'
 
-// Marker-based injection — the block lives between START_TAG and END_TAG, so
-// re-injection is a deterministic splice (find markers, replace between) rather
-// than fuzzy line matching. New file → write markers + snippet. Existing markers
-// → replace their contents. No markers yet → append a fresh marked block.
+// Marker-based injection 的纯核心：existing（文件现内容，缺文件传 null）+ port → 新内容。
+// 块夹在 START_TAG..END_TAG 间，再注入是确定性 splice（找标记替换中间）而非模糊行匹配。
+// 缺文件 → 仅块；有标记 → 替换其内容；无标记 → 末尾追加新块。fs 读写是 injectClaudeMd 的边界，
+// 这里 0 副作用——四条分支（新建/替换/追加/补换行）全可被快照锁死。
+export function renderClaudeMd(existing: string | null, port: number): string {
+    const block = `${START_TAG}\n${aipeekSnippet(port).trim()}\n${END_TAG}\n`
+    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}\n${block}`
+}
+
 export function injectClaudeMd(root: string, port: number) {
     const path = resolve(root, 'CLAUDE.md')
-    const block = `${START_TAG}\n${aipeekSnippet(port).trim()}\n${END_TAG}\n`
     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}\n${block}`)
+        writeFileSync(path, renderClaudeMd(existsSync(path) ? readFileSync(path, 'utf-8') : null, port))
     }
     catch {}
 }
 
+// The enriched /screen reply: rendered text for display + structured snap & buffers so the
+// server can diff one read against an earlier one for /screen?since=<token>.
+interface ScreenReply { screen: string, snap: ScreenSnap, console: LogEntry[], network: NetworkRequest[], errors: ErrorEntry[] }
+
 export function aipeekPlugin(): Plugin {
     let pendingResolve: ((data: RawState) => void) | null = null
     let server: ViteDevServer
     let lastRaw: RawState | null = null
+    let perfBaseline: PerformanceData | null = null // /profile/diff before-snapshot
     let pushTimer: ReturnType<typeof setTimeout> | undefined
     const pendingActions = new Map<number, (r: ActionResult) => void>()
     let actionId = 0
 
+    // Live-tab roster. Every reply carries the client's tab id; we upsert here so commands
+    // can address one tab (?tab=) and so a multi-tab session reports a "which tab?" list
+    // instead of racing N answers. lastSeen = server-side arrival time (Node clock).
+    const tabs = new Map<string, TabInfo>()
+    function seen(data: { tab?: string, url?: string, title?: string, visible?: boolean }) {
+        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()))
+
+    // Bind the pure diagnose() (the single π, in core/util) to live server state. Every
+    // "didn't get an answer" path routes through here — twoPhase rejects, /tabs empty roster,
+    // /profile tab-absent — so the state→action split lives in exactly one tested function.
+    const diagnose = (tab?: string) =>
+        diagnoseConn(tab, [...tabs.values()], Date.now(), server.ws.clients.size, server.config.server.port || 5173)
+
+    // Cross-tab action timeline. Each tab already ships its full action ring inside every
+    // aipeek:state reply (the same `actions` the single-tab `recent actions` tail reads); we
+    // merge those into a global ring keyed by tab on each collect — no separate fire-and-forget
+    // report path, no dependency on client-patch (which only reloads on server restart).
+    // GET /timeline interleaves all tabs by ts, so a multi-tab A/B comparison sees who did what.
+    const actionLog: ActionEntry[] = []
+
+    // Self-heal handshake: a process-level id, fresh on every server start. The injected
+    // client-patch polls GET /ping and reloads the page when this id changes — so a full
+    // server restart (which kills the HMR socket the whole action chain rides on) heals
+    // itself instead of stranding the page on "connection lost" until a human hits ⌘R.
+    const BOOT_ID = Date.now().toString(36)
+
+    const mergeActions = (tab: string | undefined, actions?: ActionEntry[]) => {
+        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)
+        }
+    }
+
+    // Chrome real-input channel: synthetic events can't open a Radix ContextMenu, and the
+    // in-page script can't reach chrome.debugger. So for a plain browser tab, realclick is a
+    // two-step handshake — the page resolves the element to (x,y), then the server enqueues a
+    // CDP command here for the extension to execute with trusted input. The extension long-polls
+    // /cdp/poll for the next command and POSTs the verdict to /cdp/result. Electron never touches
+    // this (it fires sendInputEvent in-process from the page — see client.ts).
+    interface CdpCommand { id: number, x: number, y: number, button: 'left' | 'right' }
+    const cdpQueue: CdpCommand[] = []
+    let cdpWaiter: ((cmd: CdpCommand | null) => void) | null = null
+    const cdpResults = new Map<number, (r: { ok: boolean, error?: string }) => void>()
+    let cdpId = 0
+
+    function runCdpClick(x: number, y: number, button: 'left' | 'right'): Promise<{ ok: boolean, error?: string }> {
+        const id = ++cdpId
+        const cmd: CdpCommand = { id, x, y, button }
+        return new Promise((resolve, reject) => {
+            cdpResults.set(id, resolve)
+            // hand the command to a parked poller, else queue it for the next poll
+            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?)'))
+            }, 10000)
+        })
+    }
+
     let pendingDom: ((dom: string) => void) | null = null
-    let pendingScreen: ((screen: string) => void) | null = null
+    let pendingScreen: ((reply: ScreenReply) => void) | null = null
     const pendingEvals = new Map<number, (r: { ok: boolean, value?: string, error?: string }) => void>()
     let evalId = 0
 
+    // /screen?since=<token> diffs the current screen against an earlier one. We stash each
+    // /screen read's structured snap + buffers under a monotonic token; `since` looks the
+    // token up and renders only the transition (diffScreen). Ring-bounded so it can't grow.
+    interface Stash { snap: ScreenSnap, console: LogEntry[], network: NetworkRequest[], errors: ErrorEntry[] }
+    const screenStash = new Map<string, Stash>()
+    let screenToken = 0
+    function stashScreen(r: ScreenReply): string {
+        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
+    }
+
     // Multi-tab: round one asks only the visible tab (requireVisible). If no tab is
     // visible (user reading the terminal), nobody answers within VISIBLE_MS, so round
     // two drops the guard and any tab replies. `arm` installs the pending slot and
@@ -164,6 +352,7 @@ export function aipeekPlugin(): Plugin {
         payload: Record<string, unknown>,
         arm: (resolve: (v: T) => void) => () => void,
         fullMs = 3000,
+        tab?: string,
     ): Promise<T> {
         return new Promise<T>((resolve, reject) => {
             let settled = false
@@ -171,6 +360,49 @@ export function aipeekPlugin(): Plugin {
                 settled = true
                 resolve(v)
             })
+            // Addressed at one tab: skip the requireVisible round entirely — only that tab
+            // answers (skip() matches on tab id), background or not. No visibility race.
+            //
+            // Shortest-path delivery: assume the tab always exists. TAB_ID is sessionStorage-backed
+            // and survives the self-heal location.reload(), so a tab keeps its id across a server
+            // restart — it's the same descendant. Two regimes, split on whether the tab is live now:
+            //   live   → present-but-silent past fullMs is a real miss (bad sel / hung handler) →
+            //            reject fast, exactly as before. Never re-send to a live tab (double-exec hazard).
+            //   absent → server just restarted / page mid self-heal. Keep re-delivering every RETRY_MS
+            //            until it re-registers (self-heal brings it back ~2-4s), bounded by ABSENT_CEILING_MS.
+            // Re-delivery is made idempotent client-side (__AIPEEK_DONE_ACTIONS__ de-dups by action id).
+            if (tab) {
+                const RETRY_MS = 500
+                const ABSENT_CEILING_MS = 10000
+                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(diagnose(tab)))
+                        }
+                    }
+                    else if (elapsed > ABSENT_CEILING_MS) {
+                        clearInterval(iv)
+                        clear()
+                        reject(new Error(diagnose(tab)))
+                    }
+                    else {
+                        deliver()
+                    }
+                }, RETRY_MS)
+                return
+            }
             server.hot.send(event, { ...payload, requireVisible: true })
             setTimeout(() => {
                 if (settled)
@@ -181,40 +413,40 @@ export function aipeekPlugin(): Plugin {
                     if (settled)
                         return
                     clear()
-                    reject(new Error(`timeout: no client response within ${VISIBLE_MS + fullMs}ms`))
+                    reject(new Error(diagnose(tab)))
                 }, fullMs)
             }, VISIBLE_MS)
         })
     }
 
-    function collectFromClient(): Promise<RawState> {
+    function collectFromClient(tab?: string): Promise<RawState> {
         return twoPhase<RawState>('aipeek:collect', {}, (resolve) => {
             pendingResolve = resolve
             return () => {
                 pendingResolve = null
             }
-        })
+        }, 3000, tab)
     }
 
-    function collectDomFromClient(scope?: string, sel?: string): Promise<string> {
+    function collectDomFromClient(scope?: string, sel?: string, tab?: string): Promise<string> {
         return twoPhase<string>('aipeek:collect-dom', { scope, sel }, (resolve) => {
             pendingDom = resolve
             return () => {
                 pendingDom = null
             }
-        })
+        }, 3000, tab)
     }
 
-    function collectScreenFromClient(): Promise<string> {
-        return twoPhase<string>('aipeek:collect-screen', {}, (resolve) => {
+    function collectScreenFromClient(tab?: string): Promise<ScreenReply> {
+        return twoPhase<ScreenReply>('aipeek:collect-screen', {}, (resolve) => {
             pendingScreen = resolve
             return () => {
                 pendingScreen = null
             }
-        })
+        }, 3000, tab)
     }
 
-    function sendAction(type: string, args: ActionArgs): Promise<ActionResult> {
+    function sendAction(type: string, args: ActionArgs, tab?: string): Promise<ActionResult> {
         const id = ++actionId
         // wait actions own their timeout; give the channel that long + slack
         const fullMs = Math.max(args.timeout ?? 0, 3000) + 2000
@@ -223,17 +455,35 @@ export function aipeekPlugin(): Plugin {
             return () => {
                 pendingActions.delete(id)
             }
-        }, fullMs)
+        }, fullMs, tab)
+    }
+
+    // sendAction + the Chrome realclick handshake, in one place so the single endpoint and
+    // /chain both get it. The page resolves realclick to (x,y): if result.fired, Electron
+    // already fired the trusted click in-process — done. Otherwise (plain Chrome tab) the page
+    // couldn't click, so drive the extension's CDP queue with the coords, then collect the
+    // settled screen. A CDP failure comes back as a normal ok:false result.
+    async function runAction(type: string, args: ActionArgs, tab?: string): Promise<ActionResult> {
+        const result = await sendAction(type, args, tab)
+        lastRaw = null // page mutated; force fresh collect next read
+        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} → clicked via extension`
+            result.screen = (await collectScreenFromClient(tab)).screen
+        }
+        return result
     }
 
-    function evalInClient(code: string): Promise<{ ok: boolean, value?: string, error?: string }> {
+    function evalInClient(code: string, tab?: string): Promise<{ ok: boolean, value?: string, error?: string }> {
         const id = ++evalId
         return twoPhase('aipeek:eval', { id, code }, (resolve) => {
             pendingEvals.set(id, resolve)
             return () => {
                 pendingEvals.delete(id)
             }
-        }, 8000)
+        }, 8000, tab)
     }
 
     return {
@@ -265,13 +515,20 @@ export function aipeekPlugin(): Plugin {
             injectClaudeMd(server.config.root, server.config.server.port || 5173)
 
             server.hot.on('aipeek:state', (data: RawState) => {
+                seen(data)
+                mergeActions(data.tab, data.actions)
                 if (pendingResolve) {
                     pendingResolve(data)
                     pendingResolve = null
                 }
             })
 
-            server.hot.on('aipeek:result', (data: ActionResult & { id: number }) => {
+            // Client announces itself on connect (and on visibilitychange) — the registration
+            // edge the roster otherwise lacks, so /tabs is accurate without first being polled.
+            server.hot.on('aipeek:hello', (data: { tab?: string, url?: string, title?: string, visible?: boolean }) => seen(data))
+
+            server.hot.on('aipeek:result', (data: ActionResult & { id: number, tab?: string }) => {
+                seen(data)
                 const resolve = pendingActions.get(data.id)
                 if (resolve) {
                     pendingActions.delete(data.id)
@@ -279,7 +536,8 @@ export function aipeekPlugin(): Plugin {
                 }
             })
 
-            server.hot.on('aipeek:eval-result', (data: { id: number, ok: boolean, value?: string, error?: string }) => {
+            server.hot.on('aipeek:eval-result', (data: { id: number, ok: boolean, value?: string, error?: string, tab?: string }) => {
+                seen(data)
                 const resolve = pendingEvals.get(data.id)
                 if (resolve) {
                     pendingEvals.delete(data.id)
@@ -287,16 +545,18 @@ export function aipeekPlugin(): Plugin {
                 }
             })
 
-            server.hot.on('aipeek:dom', (data: { dom: string }) => {
+            server.hot.on('aipeek:dom', (data: { dom: string, tab?: string }) => {
+                seen(data)
                 if (pendingDom) {
                     pendingDom(data.dom)
                     pendingDom = null
                 }
             })
 
-            server.hot.on('aipeek:screen', (data: { screen: string }) => {
+            server.hot.on('aipeek:screen', (data: ScreenReply & { tab?: string }) => {
+                seen(data)
                 if (pendingScreen) {
-                    pendingScreen(data.screen)
+                    pendingScreen(data)
                     pendingScreen = null
                 }
             })
@@ -326,8 +586,100 @@ export function aipeekPlugin(): Plugin {
                 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') || undefined
+
+                // Federation: ?host=<host:port> reverse-proxies this request to a *sibling*
+                // aipeek (another dev server — micro-frontend, separate front/back servers, a
+                // teammate's machine). N peers, no registry, no discovery, no central router:
+                // each plugin is already an HTTP server, so any one of them proxies to a named
+                // peer via a server-side fetch (no browser, no CORS). The forwarded URL drops
+                // host= so the peer treats it as local — `host===self` and re-forwarding both
+                // collapse to the normal path. ?host= is a routing directive, not stored state.
+                const host = url.searchParams.get('host') || undefined
+                const selfPort = server.config.server.port || 5173
+                const selfHosts = 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) : undefined
+                        const r = await fetch(target, { method: req.method, body })
+                        send(res, r.status, await r.text())
+                    }
+                    catch (e) {
+                        // Split the failure fibers — each needs a different fix. node's fetch nests
+                        // the syscall error under .cause.code.
+                        const code = (e as { cause?: { code?: string } }).cause?.code
+                        const why = code === 'ECONNREFUSED'
+                            ? `nothing is listening on ${host} — its dev server isn't running (start it), or the port is wrong.`
+                            : code === 'ENOTFOUND'
+                                ? `host '${host}' doesn't resolve — check the hostname.`
+                                : code === 'ETIMEDOUT' || code === 'UND_ERR_CONNECT_TIMEOUT'
+                                    ? `connection to ${host} timed out — it's unreachable (firewall, or wrong host).`
+                                    : `${(e as Error).message} (code ${code ?? 'unknown'}).`
+                        send(res, 502, `cannot reach aipeek peer at ${host}: ${why}`)
+                    }
+                    return
+                }
+
+                // /__aipeek/ping — process-level BOOT_ID, polled by the injected client-patch
+                // to self-heal after a server restart (see BOOT_ID). Server-self health, no tab,
+                // highest frequency — short-circuit before everything else.
+                if (parts[0] === 'ping') {
+                    send(res, 200, BOOT_ID)
+                    return
+                }
+
+                // /__aipeek/help — the full command reference. Static, tab-independent: this is
+                // the body that used to sit in CLAUDE.md every session. It moved here so the model
+                // pulls it on demand (it's already curling aipeek when it needs a command) instead
+                // of paying for it resident. The injected snippet points here.
+                if (parts[0] === 'help') {
+                    send(res, 200, helpText(selfPort).trim())
+                    return
+                }
+
+                // Multi-tab guard: with >1 live tab and no ?tab=, a broadcast would race N
+                // answers and keep a random one. Refuse and show the roster so the caller
+                // picks. Single tab (or addressed) falls through to the normal path.
+                // /tabs, /timeline and /cdp/* are exempt (server-side aggregate reads / polling).
+                const ambiguous = () => !tab && !['tabs', 'timeline', 'cdp'].includes(parts[0]) && liveTabs().length > 1
+                const refuse = () => send(res, 409, `multiple live tabs — add ?tab=<id>:\n\n${formatTabs(liveTabs(), Date.now())}`)
 
                 try {
+                    // /__aipeek/tabs — list live clients (tab id, visibility, title, url, age).
+                    // On an empty roster, defer to the single diagnose() projection so the
+                    // "page open but not injected" vs "no browser at all" split is never re-derived
+                    // here — one π, one place.
+                    if (parts[0] === 'tabs') {
+                        const roster = formatTabs(liveTabs(), Date.now())
+                        send(res, 200, roster === '(no live tabs)' ? `(${diagnose()})` : roster)
+                        return
+                    }
+
+                    // /__aipeek/timeline — interleaved action stream across all tabs (server's
+                    // global ring), rendered by the same formatActions as the single-tab tail.
+                    // With >1 tab, lines are prefixed with the tab id; ?tab= filters to one.
+                    // Pull a fresh collect from each addressed tab first so the ring is current at
+                    // read time — actions flush into actionLog via the aipeek:state merge, decoupled
+                    // from whichever read happened before (a /screen wouldn't have flushed them).
+                    if (parts[0] === 'timeline') {
+                        // Sequential, not parallel: collectFromClient shares one module-level
+                        // pendingResolve, so concurrent collects would clobber each other.
+                        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
+                    }
+
                     // /__aipeek/eval — run arbitrary JS in the page. POST body = code,
                     // or ?code=. The page evaluates it and returns the result (or thrown
                     // error). The escape hatch for anything the typed endpoints can't do:
@@ -340,7 +692,7 @@ export function aipeekPlugin(): Plugin {
                             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
                     }
@@ -350,15 +702,80 @@ export function aipeekPlugin(): Plugin {
                         const dom = await collectDomFromClient(
                             url.searchParams.get('scope') || undefined,
                             url.searchParams.get('sel') || undefined,
+                            tab,
                         )
                         send(res, 200, dom || '(empty)')
                         return
                     }
 
-                    // /__aipeek/screen — state-machine projection {view, modal, focus, knobs}
+                    // /__aipeek/screen — state-machine projection {view, modal, focus, knobs}.
+                    // Each read stashes its snap under a token and prints `token: tN`. With
+                    // ?since=<token> we diff this read against that stashed snap and return only
+                    // the transition (diffScreen) — what moved since you last looked, not a snapshot.
                     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) — 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}\n${changed.length ? changed.join('\n') : '(no state change)'}`)
+                            return
+                        }
+                        send(res, 200, reply.screen ? `token: ${token}\n${reply.screen}` : '(empty)')
+                        return
+                    }
+
+                    // /__aipeek/cdp/poll — the Chrome extension long-polls here for the next
+                    // trusted-input command. Returns the command as JSON, or 204 on timeout
+                    // (the extension simply re-polls). Only one poller is parked at a time.
+                    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<CdpCommand | null>((resolve) => {
+                            cdpWaiter = resolve
+                            setTimeout(() => {
+                                if (cdpWaiter === resolve) {
+                                    cdpWaiter = null
+                                    resolve(null)
+                                }
+                            }, 25000)
+                        })
+                        if (cmd)
+                            send(res, 200, JSON.stringify(cmd))
+                        else
+                            send(res, 204, '')
+                        return
+                    }
+
+                    // /__aipeek/cdp/result — POST {id, ok, error?}; resolves the awaiting realclick.
+                    if (parts[0] === 'cdp' && parts[1] === 'result') {
+                        const body = await readBody(req)
+                        let data: { id: number, ok: boolean, error?: string }
+                        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
                     }
 
@@ -379,7 +796,7 @@ export function aipeekPlugin(): Plugin {
                         }
                         lastRaw = null
                         const lines: string[] = []
-                        let lastUi = ''
+                        let lastActions = ''
                         let allOk = true
                         for (let i = 0; i < steps.length; i++) {
                             const { type, ...args } = steps[i]
@@ -389,26 +806,26 @@ export function aipeekPlugin(): Plugin {
                                 allOk = false
                                 break
                             }
-                            const r = await sendAction(type, args)
+                            const r = await runAction(type, args, tab)
                             lines.push(`[${i}] ${r.ok ? '✓' : '✗'} ${type}: ${r.ok ? (r.detail || 'ok') : r.error}`)
-                            // Per-step screen projection — captures the transition each
-                            // mutating step caused, so a view change mid-chain is visible
-                            // at its source step rather than collapsed into the final tree.
+                            // Per-step change — the state-machine transition each mutating step
+                            // caused (view/modal/focus + new errors), shown at its source step.
                             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')}\n\n--- ui after ---\n${lastUi}` : lines.join('\n'))
+                        const chainActions = lastActions ? `\n\n--- recent actions ---\n${lastActions}` : ''
+                        send(res, allOk ? 200 : 422, `${lines.join('\n')}${chainActions}`)
                         return
                     }
 
-                    // action endpoints: /__aipeek/{click|fill|press|wait|screenshot}?...
-                    if (['click', 'fill', 'press', 'wait', 'screenshot'].includes(parts[0])) {
+                    // action endpoints: /__aipeek/{click|fill|press|wait|screenshot|realclick}?...
+                    if (['click', 'fill', 'press', 'wait', 'screenshot', 'realclick', 'query', 'assert', 'drag', 'scrollIntoView', 'drop', 'clipboard'].includes(parts[0])) {
                         const q = url.searchParams
                         const args: ActionArgs = {
                             sel: q.get('sel') || undefined,
@@ -417,14 +834,21 @@ export function aipeekPlugin(): Plugin {
                             key: q.get('key') || undefined,
                             timeout: q.has('timeout') ? Number(q.get('timeout')) : undefined,
                             gone: q.has('gone') ? q.get('gone') !== 'false' : undefined,
+                            button: q.get('button') === 'right' ? 'right' : q.get('button') === 'left' ? 'left' : undefined,
+                            x: q.has('x') ? Number(q.get('x')) : undefined,
+                            y: q.has('y') ? Number(q.get('y')) : undefined,
+                            screen: q.get('screen') || undefined,
+                            equals: q.has('equals') ? q.get('equals')! : undefined,
+                            to: q.get('to') || undefined,
+                            files: q.has('files') ? q.get('files')!.split(',').map(s => s.trim()).filter(Boolean) : undefined,
+                            mode: q.get('mode') === 'write' ? 'write' : q.get('mode') === 'read' ? 'read' : undefined,
                         }
                         const check = resolveAction(parts[0], args)
                         if (!check.valid) {
                             send(res, 400, check.error ?? 'invalid action')
                             return
                         }
-                        const result = await sendAction(parts[0], args)
-                        lastRaw = null // page mutated; force fresh collect next read
+                        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 })
@@ -435,13 +859,15 @@ export function aipeekPlugin(): Plugin {
                             return
                         }
                         const head = result.ok ? (result.detail || 'ok') : `${result.error}${result.detail ? `\n\nclickable: ${result.detail}` : ''}`
-                        send(res, result.ok ? 200 : 422, result.ui ? `${head}\n\n--- ui after ---\n${result.ui}` : head)
+                        const actionsTail = result.actions ? `\n\n--- recent actions ---\n${result.actions}` : ''
+                        const changedTail = result.screen ? `\n\n--- changed ---\n${result.screen}` : ''
+                        send(res, result.ok ? 200 : 422, `${head}${actionsTail}${changedTail}`)
                         return
                     }
 
                     // check endpoint
                     if (parts[0] === 'check') {
-                        const raw = await collectFromClient()
+                        const raw = await collectFromClient(tab)
                         lastRaw = raw
                         const result = check(raw)
                         const output = emitCheck(result)
@@ -449,21 +875,107 @@ export function aipeekPlugin(): Plugin {
                         return
                     }
 
+                    // /__aipeek/profile — performance profiler (always-on, semantic-bucketed).
+                    // /profile reads the current window; /profile/reset clears it.
+                    // Hidden tabs throttle rAF to ~1fps, making each hidden frame look like a
+                    // 1000ms dropped frame — the profiler guards with document.hidden, but if
+                    // hiddenFrames is high the data is suspect. Mention it.
+                    if (parts[0] === 'profile') {
+                        // Empty perf data is a recoverable state, not a dead end: the tab DID answer
+                        // collectFromClient (so it's connected) — it's just backgrounded, where the
+                        // browser throttles rAF to ~1fps and there are no real frames to sample. The
+                        // bare "(no perf data)" reads to a model as "no browser, can't help", so it
+                        // gives up. Say the page is already running and a 2s foreground fixes it —
+                        // profiling is the only read that needs foreground (/screen, /dom work hidden).
+                        // Empty perf data after a SUCCESSFUL collect is its own fiber, disjoint from
+                        // diagnose() (which is the no-reply projection): the tab answered, so it's
+                        // connected — it's just backgrounded, where the browser throttles rAF to ~1fps
+                        // and there are no real frames to sample. Recoverable in 2s, not a dead end.
+                        // The tab-absent fallback defers to diagnose() so the socket logic lives once.
+                        const noPerfMsg = (t?: string) => {
+                            const info = t ? tabs.get(t) : liveTabs()[0]
+                            return info
+                                ? `tab '${info.id}' is connected but BACKGROUNDED — 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 — /screen and /dom work backgrounded.)`
+                                : `(${diagnose(t)})`
+                        }
+                        // Clear the client-side perf window and wait for ack. Used by /profile/reset
+                        // and by /profile/diff when capturing a baseline — so "before" and "after"
+                        // each measure ONLY their own reproduce, not an ever-growing running sum.
+                        const resetPerfWindow = () => new Promise<void>((resolve, reject) => {
+                            const timeout = setTimeout(() => reject(new Error('timeout waiting for perf-reset-ack')), 3000)
+                            const handler = (data: { tab?: string }) => {
+                                if (tab && data.tab !== tab) return
+                                clearTimeout(timeout)
+                                server.hot.off('aipeek:perf-reset-ack', handler)
+                                resolve()
+                            }
+                            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 — reproduce the interaction, then GET /profile')
+                            return
+                        }
+                        if (parts[1] === 'diff') {
+                            // Closed-loop verdict. First call captures a baseline; second diffs
+                            // current vs baseline and clears it. Workflow: /profile/diff (mark before)
+                            // → make a fix → reproduce → /profile/diff (get IMPROVED/REGRESSED verdict).
+                            const raw = await collectFromClient(tab)
+                            lastRaw = raw
+                            if (!raw.performance) {
+                                send(res, 200, noPerfMsg(tab))
+                                return
+                            }
+                            if (!perfBaseline) {
+                                perfBaseline = raw.performance
+                                // Clear the window so the NEXT collect measures only the post-fix
+                                // reproduce. Without this, "after" ⊇ "before" (samples append, total
+                                // is a running sum) → self-time can only grow → IMPROVED impossible.
+                                await resetPerfWindow()
+                                send(res, 200, 'baseline captured + window cleared — make your fix, reproduce the interaction, then GET /profile/diff again for the verdict')
+                                return
+                            }
+                            const report = diffPerformance(perfBaseline, raw.performance)
+                            perfBaseline = null // consumed; next call starts a fresh baseline
+                            send(res, 200, report)
+                            return
+                        }
+                        // /profile — fresh collect, render detail
+                        const raw = await collectFromClient(tab)
+                        lastRaw = raw
+                        if (!raw.performance) {
+                            send(res, 200, noPerfMsg(tab))
+                            return
+                        }
+                        const hiddenNote = raw.performance.hiddenFrames > 10
+                            ? `\n\n⚠ ${raw.performance.hiddenFrames} frames skipped while tab was hidden — bring it to foreground and /profile/reset for accurate data.`
+                            : ''
+                        send(res, 200, detail(raw, 'profile', undefined, false) + hiddenNote)
+                        return
+                    }
+
                     // detail: /__aipeek/{section}[/{index}][?full]
                     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('/')}`)
+                        // null splits two fibers: an unknown section name (→ fix the path) vs a
+                        // known section that's simply empty (→ nothing to show, not an error). Name
+                        // the valid sections so the caller can tell which it hit.
+                        const SECTIONS = ['ui', 'console', 'network', 'errors', 'state', 'profile']
+                        send(res, 404, SECTIONS.includes(parts[0])
+                            ? `'${parts[0]}' is empty right now — nothing captured this window (not an error).`
+                            : `unknown section '${parts[0]}'. Valid: ${SECTIONS.join(', ')}. (Or /screen, /dom, /tabs, /timeline, /check.)`)
                         return
                     }
 
                     // summary or full: /__aipeek[?full]
-                    const raw = await collectFromClient()
+                    const raw = await collectFromClient(tab)
                     lastRaw = raw
                     if (full) {
                         const compacted = compact(raw)