aihand 0.0.1 → 0.1.0

package/src/ui/client/client-patch.ts

@@ -0,0 +1,899 @@
+// aihand client patch — synchronous, non-module
+// Injected as inline <script> at head-prepend to patch console/fetch/XHR/errors
+// BEFORE any application modules execute.
+
+import type { ActionEntry, ErrorEntry, LogEntry, NetworkRequest } from '../core/types'
+
+type NetworkEntry = NetworkRequest
+
+// --- Perf buffer (runtime accumulation; client.ts projects it into PerformanceData) ---
+// Internal shape differs from core/types PerformanceData: buckets is a name→bucket map (not
+// array), carries startedAt + active (the live view key). client.ts does the array/windowMs
+// projection on collect.
+interface PerfStatBuf { total: number, n: number, max: number }
+interface PerfBucketBuf {
+    components: Record<string, PerfStatBuf>
+    frames: { total: number, long: number, max: number, samples: number[] }
+    lines: Record<string, PerfStatBuf>  // line-level: "File.tsx:42:varName" → stat
+}
+interface PerfBuffer {
+    startedAt: number
+    hiddenFrames: number
+    mobxPatched: boolean
+    buckets: Record<string, PerfBucketBuf>
+    active: string
+    // lastEndAt: when the most recent long task FINISHED (startTime + duration, page-relative ms).
+    // A longtask entry only dispatches AFTER the task ends, so this is "the main thread was blocking
+    // until at least here". The flow terminus reads it as a third, app-agnostic busy signal: a
+    // no-network, no-DOM-mutation compute flow (IndexedDB, a Worker's sync hop, a heavy render pass)
+    // still shows up as long tasks while it grinds, so freshness here means "still working".
+    longtasks: { count: number, max: number, lastEndAt: number }
+}
+
+interface AipeekBuffers {
+    consoleLogs: LogEntry[]
+    networkRequests: NetworkEntry[]
+    errorEntries: ErrorEntry[]
+    actionEntries: ActionEntry[]
+    perf: PerfBuffer
+    actionsDropped: number
+}
+
+// --- Ring buffers (persist across HMR) ---
+
+const MAX_CONSOLE = 100
+const MAX_NETWORK = 50
+const MAX_ERRORS = 20
+const MAX_ACTIONS = 30
+
+const BUFFERS_KEY = '__AIPEEK_BUFFERS__'
+const existing = (window as any)[BUFFERS_KEY] as AipeekBuffers | undefined
+const consoleLogs: LogEntry[] = existing?.consoleLogs ?? []
+const networkRequests: NetworkEntry[] = existing?.networkRequests ?? []
+const errorEntries: ErrorEntry[] = existing?.errorEntries ?? []
+const actionEntries: ActionEntry[] = existing?.actionEntries ?? []
+const perf: PerfBuffer = existing?.perf ?? {
+    startedAt: Date.now(),
+    hiddenFrames: 0,
+    mobxPatched: false,
+    buckets: {},
+    active: '__all__',
+    longtasks: { count: 0, max: 0, lastEndAt: 0 },
+}
+// Monotonic count of action entries the ring evicted from its head — the timeline is a causal
+// chain, so a silently-cut head reads as "this is the start". Survives HMR via the existing buffer.
+let actionsDropped = existing?.actionsDropped ?? 0
+;(window as any)[BUFFERS_KEY] = { consoleLogs, networkRequests, errorEntries, actionEntries, perf, get actionsDropped() { return actionsDropped } }
+
+const PERF_SAMPLE_CAP = 5000
+
+function perfBucket(name: string): PerfBucketBuf {
+    let b = perf.buckets[name]
+    if (!b) {
+        b = { components: {}, frames: { total: 0, long: 0, max: 0, samples: [] }, lines: {} }
+        perf.buckets[name] = b
+    }
+    return b
+}
+
+// The view bucket + the __all__ aggregate. When active IS __all__, return it once —
+// else every hit double-counts into __all__ (n, total, frames all 2×).
+function targetBuckets(): string[] {
+    return perf.active === '__all__' ? ['__all__'] : [perf.active, '__all__']
+}
+
+// One timed hit (component render / line exec) → a stat map, accumulating total/n/max.
+// No samples buffer: total/n/max are O(1) streaming all-time truths; p95 was the only sample
+// consumer and is gone (near-window p95 vs all-time total = same-row lie). Dropping the per-hit
+// push/shift also lightens the line-instrumentation hot path (less self-pollution).
+function recordStat(map: Record<string, PerfStatBuf>, key: string, ms: number) {
+    let s = map[key]
+    if (!s) {
+        s = { total: 0, n: 0, max: 0 }
+        map[key] = s
+    }
+    s.total += ms
+    s.n += 1
+    if (ms > s.max)
+        s.max = ms
+}
+
+// One component render's self-time → both its live view bucket and the __all__ aggregate.
+function hitComponent(name: string, ms: number) {
+    for (const bucketName of targetBuckets())
+        recordStat(perfBucket(bucketName).components, name, ms)
+}
+
+// One line's execution time → both its live view bucket and the __all__ aggregate.
+// Called by babel-inserted __line(label, fn) wrapper.
+function hitLine(label: string, ms: number) {
+    for (const bucketName of targetBuckets())
+        recordStat(perfBucket(bucketName).lines, label, ms)
+}
+
+// Runtime for babel plugin: wraps one statement, times it, records to perf.lines.
+// Exposed globally so babel-transformed code can call it (client-patch can't be imported).
+;(window as any).__line = function __line<T>(label: string, fn: () => T): T {
+    const start = performance.now()
+    try {
+        return fn()
+    }
+    finally {
+        hitLine(label, performance.now() - start)
+    }
+}
+
+// One frame's dt → both live view bucket and __all__. long = dropped (>16.7ms ≈ missed 60fps).
+function hitFrame(dt: number) {
+    for (const bucketName of targetBuckets()) {
+        const f = perfBucket(bucketName).frames
+        f.total += 1
+        if (dt > 16.7)
+            f.long += 1
+        if (dt > f.max)
+            f.max = dt
+        f.samples.push(dt)
+        if (f.samples.length > PERF_SAMPLE_CAP)
+            f.samples.shift()
+    }
+}
+
+// (b) Frame loop — zero-coupling, holds for any app. Throttle guard: a backgrounded OR unfocused
+// window throttles rAF to ~1fps, so each such frame looks like a ~1000ms "dropped" frame and lies.
+// document.hidden only fires when the TAB is switched away; a window that's merely unfocused
+// (another app has focus, minimized, fully occluded) keeps document.hidden=false yet the OS still
+// throttles its rAF — same lie, different probe. document.hasFocus() catches that second case.
+// Don't count dt while throttled; tally hiddenFrames so the report can flag it.
+const WARN_THRESHOLD = 20 // dropped% — push warning when ≥20% frames jank
+const WARN_COOLDOWN = 5000 // ms — don't spam, at most one warn per 5s
+let lastFrame = performance.now()
+let lastWarn = 0
+function frameLoop() {
+    const now = performance.now()
+    if (document.hidden || !document.hasFocus()) {
+        perf.hiddenFrames += 1
+        lastFrame = now
+        requestAnimationFrame(frameLoop)
+        return
+    }
+    const dt = now - lastFrame
+    hitFrame(dt)
+    lastFrame = now
+
+    // Push mode: auto-warn on jank (≥20% dropped), once per 5s
+    const bucket = perf.buckets[perf.active]
+    if (bucket && bucket.frames.total > 20) { // need ≥20 frames for stable %
+        const droppedPct = (bucket.frames.long / bucket.frames.total) * 100
+        if (droppedPct >= WARN_THRESHOLD && now - lastWarn > WARN_COOLDOWN) {
+            const top3 = Object.entries(bucket.components)
+                .sort(([, a], [, b]) => b.total - a.total)
+                .slice(0, 3)
+                .map(([name, s]) => `${name} ${s.total.toFixed(0)}ms`)
+                .join(', ')
+            const hot = top3 ? ` · hot: ${top3}` : ''
+            console.warn(`[aihand] 🐌 ${droppedPct.toFixed(0)}% frames dropped${hot}`)
+            lastWarn = now
+        }
+    }
+
+    requestAnimationFrame(frameLoop)
+}
+requestAnimationFrame(frameLoop)
+
+// (b) Longtask observer — main-thread blocks >50ms, app-agnostic.
+try {
+    new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) {
+            perf.longtasks.count += 1
+            if (entry.duration > perf.longtasks.max)
+                perf.longtasks.max = entry.duration
+            const endAt = entry.startTime + entry.duration
+            if (endAt > perf.longtasks.lastEndAt)
+                perf.longtasks.lastEndAt = endAt
+        }
+    }).observe({ entryTypes: ['longtask'] })
+}
+catch { /* longtask not supported — frames + components still work */ }
+
+// (a) Component self-time via MobX Reaction.track. client-patch can't import mobx, so the app
+// exposes the live singleton at window.__AIPEEK_MOBX__={Reaction} (dev-only seam in src/lib/mobx.ts).
+// mobx-react-lite names every component's Reaction "observer"+name, so name_.slice(8) is the
+// component name. Patch is idempotent (track.__aihand flag) and survives HMR via the shared buffer.
+function patchMobx() {
+    const mobx = (window as any).__AIPEEK_MOBX__
+    const Reaction = mobx?.Reaction
+    const track = Reaction?.prototype?.track
+    if (!track || (track as any).__aihand)
+        return
+    const patched = function (this: any, fn: () => void) {
+        const name: string = this.name_ ?? ''
+        if (name.indexOf('observer') !== 0)
+            return track.call(this, fn)
+        const start = performance.now()
+        try {
+            return track.call(this, fn)
+        }
+        finally {
+            hitComponent(name.slice(8) || '(anon)', performance.now() - start)
+        }
+    }
+    ;(patched as any).__aihand = true
+    Reaction.prototype.track = patched
+    perf.mobxPatched = true
+}
+patchMobx()
+// The seam may run after this patch (module order). Retry briefly so attribution turns on
+// once src/lib/mobx.ts executes; stops as soon as it succeeds.
+if (!perf.mobxPatched) {
+    let tries = 0
+    const retry = setInterval(() => {
+        patchMobx()
+        if (perf.mobxPatched || ++tries > 20)
+            clearInterval(retry)
+    }, 100)
+}
+
+function pushBounded<T>(arr: T[], item: T, max: number) {
+    arr.push(item)
+    if (arr.length > max)
+        arr.shift()
+}
+
+// --- Patch console ---
+
+/* eslint-disable no-console -- patching console is the point of this block */
+for (const level of ['log', 'info', 'warn', 'error', 'debug'] as const) {
+    const orig = console[level]
+    console[level] = (...args: unknown[]) => {
+        pushBounded(consoleLogs, {
+            level,
+            text: args.map(a => typeof a === 'string' ? a : formatValue(a)).join(' '),
+            timestamp: Date.now(),
+        }, MAX_CONSOLE)
+        orig.apply(console, args)
+    }
+}
+/* eslint-enable no-console */
+
+// --- Patch fetch — 透明摄像头：tee body，主流原样返回，副流后台 capture ---
+
+const originalFetch = window.fetch
+
+// --- Self-heal handshake: reconnect after a dev-server restart without a human reload ---
+// The whole aihand action chain rides the Vite HMR WebSocket. A full server restart kills
+// that socket and Vite's reconnect often gives up — stranding the page on "connection lost".
+// So we poll an HTTP heartbeat (independent of the WS) carrying the server's BOOT_ID; when it
+// changes (server is a new process), the page reloads itself and re-handshakes the new server.
+//
+// The heartbeat MUST run in a Worker, not a main-thread setInterval. Browsers throttle
+// main-thread timers in BACKGROUND tabs to once per minute (Chrome 88+) — and the aihand tab is
+// almost always backgrounded (the operator is watching a terminal, not the page). A main-thread
+// poll therefore took ~60s to notice a restart, forcing a manual reload. Worker timers are NOT
+// throttled (throttling is main-thread only), so the Worker keeps a true ~2s heartbeat while
+// backgrounded. The Worker only times + fetches + posts the BOOT_ID back; ALL decision logic
+// (sessionStorage debounce, wsDead check, location.reload) stays on the main thread, where a
+// Worker can't reach storage/location anyway.
+;(function keepAlive() {
+    const SEEN_KEY = '__aihand_boot__'
+    const RELOADING_KEY = '__aihand_reloading__'
+
+    // Main-thread decision: given a freshly-fetched BOOT_ID, decide whether to reload+re-handshake.
+    // Two reload triggers, same fix (reload → re-handshake), both debounced by RELOADING_KEY:
+    //   1. BOOT_ID changed  → server restarted (the original case).
+    //   2. BOOT_ID same but the HMR WebSocket is dead → the socket dropped (Electron window
+    //      backgrounded/suspended) and Vite's reconnect is gated on visibility, so it never
+    //      comes back on its own. The action chain rides that socket, so a dead WS = "can't
+    //      see" even though the server is fine. client.ts sets this flag on vite:ws:disconnect.
+    const handleBoot = (id: string) => {
+        sessionStorage.removeItem(RELOADING_KEY) // ping succeeded — clear the reload debounce
+        const seen = sessionStorage.getItem(SEEN_KEY)
+        if (!seen) {
+            sessionStorage.setItem(SEEN_KEY, id) // first sighting — remember this server
+            return
+        }
+        const wsDead = (window as { __aihand_ws_dead__?: boolean }).__aihand_ws_dead__ === true
+        if (seen !== id || wsDead) {
+            sessionStorage.setItem(SEEN_KEY, id)
+            if (!sessionStorage.getItem(RELOADING_KEY)) {
+                sessionStorage.setItem(RELOADING_KEY, '1')
+                location.reload()
+            }
+        }
+    }
+
+    // Heartbeat source: a Worker timer that survives background throttling. Its whole body is the
+    // poll — fetch the BOOT_ID, post it back; on failure post nothing (server not up yet → keep
+    // polling, never reload on a mere failure). Inlined as a Blob (client-patch can't import).
+    try {
+        if (typeof Worker === 'undefined')
+            throw new Error('no Worker')
+        // A Blob-URL Worker's baseURI is `blob:…`, not the page origin — a relative '/__aihand/ping'
+        // fails to parse there. So bake the absolute URL in from the main thread's location.origin.
+        const pingUrl = `${location.origin}/__aihand/ping`
+        const src = `setInterval(async () => {
+            try {
+                const r = await fetch(${JSON.stringify(pingUrl)}, { cache: 'no-store' })
+                postMessage(await r.text())
+            } catch (e) {}
+        }, 2000)`
+        const worker = new Worker(URL.createObjectURL(new Blob([src], { type: 'text/javascript' })))
+        worker.onmessage = e => handleBoot(e.data as string)
+    }
+    catch {
+        // No Worker (or Blob construction blocked) — fall back to a main-thread poll. Throttled in
+        // a background tab, but still self-heals eventually; never worse than before this change.
+        setInterval(async () => {
+            try {
+                handleBoot(await (await originalFetch('/__aihand/ping', { cache: 'no-store' })).text())
+            }
+            catch {}
+        }, 2000)
+    }
+})()
+
+// --- Restore-then-verify: a reload is only a heal if the page comes back rendered ---
+// handleBoot reloads on a server restart, then unconditionally assumes the page is healthy.
+// But a reload can land on a WHITE SCREEN — the new bundle threw on boot, the app mounted
+// nothing into #root. The old heartbeat never notices (BOOT_ID is stable, WS may even connect),
+// so the operator is stranded on a blank page that *looks* healed. Borrowing agent-browser's
+// `--restore-check`: the restore action carries its own verification fiber — if the restored
+// state isn't actually good, don't bank it as success. Here: after a heal-reload, confirm #root
+// rendered; if still empty past a grace window, reload once more (bounded), never claim success.
+// 元真理: one binary "did it render" check, no configurable assertion table — that's all it takes
+// to stop a white screen from masquerading as healed.
+;(function verifyRestore() {
+    const RELOADING_KEY = '__aihand_reloading__' // set by handleBoot right before its location.reload()
+    const RETRY_KEY = '__aihand_heal_retry__'
+    const MAX_RETRY = 2 // bounded: a genuinely-broken build must NOT reload-loop forever
+    if (!sessionStorage.getItem(RELOADING_KEY))
+        return // this load wasn't triggered by a self-heal reload — nothing to verify
+    const rendered = () => {
+        const root = document.getElementById('root') || document.querySelector('#app, [data-reactroot]')
+        return !!root && root.childElementCount > 0
+    }
+    // Grace window: the app needs a beat to mount. Check after the bundle has had time to run.
+    setTimeout(() => {
+        if (rendered()) {
+            sessionStorage.removeItem(RETRY_KEY) // healed for real — reset the retry budget
+            return
+        }
+        const tries = Number(sessionStorage.getItem(RETRY_KEY) || '0')
+        if (tries >= MAX_RETRY) {
+            // eslint-disable-next-line no-console
+            console.warn(`[aihand] self-heal reload left a white screen after ${tries} retries — build likely broken, stopping (not claiming healed)`)
+            return // don't reload-loop a broken bundle; leave it visibly broken, not falsely "healed"
+        }
+        sessionStorage.setItem(RETRY_KEY, String(tries + 1))
+        sessionStorage.setItem(RELOADING_KEY, '1') // keep the verify armed for the next attempt
+        location.reload()
+    }, 3000)
+})()
+
+window.fetch = async (input, init) => {
+    const url = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url
+    const method = init?.method || 'GET'
+    const start = performance.now()
+
+    // 立即推 entry，主线程持有同一引用，capture 完成后写回
+    const entry: NetworkEntry = {
+        method,
+        url,
+        status: 0,
+        duration: 0,
+        resourceType: 'fetch',
+    }
+    if (init?.headers) {
+        const rh: Record<string, string> = {}
+        new Headers(init.headers as HeadersInit).forEach((v, k) => {
+            rh[k] = v
+        })
+        entry.requestHeaders = rh
+    }
+    if (init?.body && typeof init.body === 'string') {
+        entry.requestBody = init.body.slice(0, 4000)
+        entry.requestSample = jsonSample(init.body)
+    }
+    pushBounded(networkRequests, entry, MAX_NETWORK)
+
+    let response: Response
+    try {
+        response = await originalFetch(input, init)
+    }
+    catch (err) {
+        entry.status = 0
+        entry.duration = Math.round(performance.now() - start)
+        entry.failed = true
+        entry.failureText = err instanceof Error ? err.message : String(err)
+        throw err
+    }
+
+    entry.status = response.status
+    entry.duration = Math.round(performance.now() - start)
+    const respHeaders: Record<string, string> = {}
+    response.headers.forEach((v, k) => {
+        respHeaders[k] = v
+    })
+    entry.responseHeaders = respHeaders
+
+    if (!response.body)
+        return response
+
+    // tee：主流原样给业务，副流后台读 4KB 做 capture
+    const [pass, peek] = response.body.tee()
+    captureBody(peek, entry).catch(() => {})
+
+    const proxied = new Response(pass, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+    })
+    Object.defineProperty(proxied, 'url', { value: response.url })
+    Object.defineProperty(proxied, 'type', { value: response.type })
+    Object.defineProperty(proxied, 'redirected', { value: response.redirected })
+    return proxied
+}
+
+async function captureBody(stream: ReadableStream<Uint8Array>, entry: NetworkEntry, MAX = 4000) {
+    const reader = stream.getReader()
+    const decoder = new TextDecoder()
+    let body = ''
+    try {
+        while (body.length < MAX) {
+            const { done, value } = await reader.read()
+            if (done)
+                break
+            body += decoder.decode(value, { stream: true })
+        }
+    }
+    catch { /* ignore */ }
+    finally {
+        try {
+            await reader.cancel()
+        }
+        catch {}
+    }
+    entry.responseBody = body.slice(0, MAX)
+    entry.responseSample = jsonSample(body)
+}
+
+// --- Patch XHR ---
+
+const XHRProto = XMLHttpRequest.prototype
+const origOpen = XHRProto.open
+const origSend = XHRProto.send
+
+XHRProto.open = function (method: string, url: string | URL, ...rest: unknown[]) {
+    (this as any).__aihand = { method, url: String(url), start: 0 }
+    return (origOpen as any).apply(this, [method, url, ...rest])
+}
+
+XHRProto.send = function (...args: unknown[]) {
+    const meta = (this as any).__aihand
+    if (meta) {
+        meta.start = performance.now()
+        this.addEventListener('loadend', () => {
+            const responseHeaders: Record<string, string> = {}
+            const rawHeaders = this.getAllResponseHeaders()
+            for (const line of rawHeaders.trim().split('\r\n')) {
+                const idx = line.indexOf(': ')
+                if (idx > 0)
+                    responseHeaders[line.slice(0, idx)] = line.slice(idx + 2)
+            }
+            pushBounded(networkRequests, {
+                method: meta.method,
+                url: meta.url,
+                status: this.status,
+                duration: Math.round(performance.now() - meta.start),
+                resourceType: 'xhr',
+                responseHeaders,
+            }, MAX_NETWORK)
+        })
+    }
+    return (origSend as any).apply(this, args)
+}
+
+// --- Patch errors ---
+
+// Extract a useful message+stack from any thrown value. The single chokepoint shared by the
+// 'error' and 'unhandledrejection' listeners so they can never diverge: an Error gives both;
+// a plain object with a .message (a common throw shape) gives that message; anything else
+// stringifies. `{}` → "[object Object]" is the honest floor — there is genuinely no message.
+function throwMeta(val: unknown): { message: string, stack: string | undefined } {
+    if (val instanceof Error)
+        return { message: val.message, stack: val.stack }
+    if (val == null)
+        return { message: '', stack: undefined }
+    const obj = val as { message?: unknown, stack?: unknown }
+    const message = typeof obj.message === 'string' && obj.message ? obj.message : String(val)
+    return { message, stack: typeof obj.stack === 'string' ? obj.stack : undefined }
+}
+
+window.addEventListener('error', (e) => {
+    if (e.target && e.target !== window) {
+        const el = e.target as HTMLElement
+        const src = (el as HTMLImageElement).src || (el as HTMLScriptElement).src || (el as HTMLLinkElement).href || ''
+        pushBounded(errorEntries, {
+            message: `Resource load failed: ${el.tagName.toLowerCase()} ${src}`,
+            source: src,
+        }, MAX_ERRORS)
+        return
+    }
+    // e.message can be empty — cross-origin "Script error.", or a non-Error throw
+    // (`throw undefined` / `throw {}` / `throw {code,detail}`). The real thrown value rides on
+    // e.error, so fall back to it instead of recording a blank "Uncaught" (a dead-end the consumer
+    // can't act on — 诊断纤维必须细分到根因,不可悲观坍缩成空). throwMeta is the shared extractor
+    // (Error → .message, {message} → .message, else String) so error & rejection can't drift.
+    const meta = throwMeta(e.error)
+    pushBounded(errorEntries, {
+        message: e.message || meta.message || 'Uncaught (no message — likely cross-origin script error)',
+        source: e.filename,
+        line: e.lineno,
+        column: e.colno,
+        stack: meta.stack,
+    }, MAX_ERRORS)
+}, true)
+
+window.addEventListener('unhandledrejection', (e) => {
+    const reason = e.reason
+    let message: string
+    let stack: string | undefined
+    if (reason instanceof Event) {
+        // A rejected resource-load event carries no message of its own — describe it by tag+src.
+        const target = reason.target as any
+        const tag = target?.tagName?.toLowerCase() || ''
+        const src = target?.src || target?.href || target?.currentSrc || ''
+        if (tag && src)
+            message = `Unhandled rejection: ${tag} load failed ${src}`
+        else if (tag)
+            message = `Unhandled rejection: ${tag} ${reason.type} event`
+        else
+            message = `Unhandled rejection: ${reason.type} event`
+    }
+    else {
+        const meta = throwMeta(reason)
+        message = meta.message
+        stack = meta.stack
+    }
+    pushBounded(errorEntries, { message, stack }, MAX_ERRORS)
+})
+
+// --- Patch EventSource (SSE) ---
+
+const OrigEventSource = window.EventSource
+if (OrigEventSource) {
+    window.EventSource = new Proxy(OrigEventSource, {
+        construct(Target, args) {
+            const es = new Target(...args as ConstructorParameters<typeof EventSource>)
+            const url = typeof args[0] === 'string' ? args[0] : String(args[0])
+            const start = performance.now()
+
+            pushBounded(networkRequests, {
+                method: 'GET',
+                url,
+                status: 0,
+                duration: 0,
+                resourceType: 'eventsource',
+            }, MAX_NETWORK)
+
+            es.addEventListener('open', () => {
+                const entry = networkRequests.find(r => r.url === url && r.resourceType === 'eventsource' && r.status === 0)
+                if (entry) {
+                    entry.status = 200
+                    entry.duration = Math.round(performance.now() - start)
+                }
+            })
+
+            es.addEventListener('error', () => {
+                pushBounded(networkRequests, {
+                    method: 'GET',
+                    url,
+                    status: es.readyState === EventSource.CLOSED ? 0 : es.readyState,
+                    duration: Math.round(performance.now() - start),
+                    resourceType: 'eventsource',
+                    failed: true,
+                    failureText: es.readyState === EventSource.CLOSED ? 'connection closed' : 'connection error',
+                }, MAX_NETWORK)
+            })
+
+            return es
+        },
+    })
+}
+
+// --- User action timeline ---
+//
+// One document capture listener catches every semantic action — both the user's real
+// events (isTrusted=true) and aihand's synthetic performAction events (isTrusted=false),
+// since both bubble through document. Each entry stamps its post-settle UI projection
+// (view/modal/focus) so a later diff against the prior entry reveals "dialog opened".
+
+const KEYS = new Set(['Enter', 'Escape', 'Tab', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'])
+let lastInputTarget: EventTarget | null = null
+
+// inline mirror of client.ts visibleText/inspPath — client-patch can't import (see formatValue note)
+function describe(el: Element): string {
+    // aria-label → own direct text → title → descendant text. Mirrors core elementLabel's chain
+    // order (candidates.ts): title sits BEFORE textContent — icon-only buttons (搜索/设置) carry
+    // their name in title=, with empty text, so without it they log as nameless <button>.
+    // client-patch can't import elementLabel (no-import constraint), so the chain is inlined.
+    // Flatten newlines → space then collapse runs: a multi-line tooltip/text
+    // (深度思考\n当前状态：关闭\n…) would otherwise spill the entry across 3 lines, breaking the
+    // one-line-per-action contract every reader (and /timeline) relies on. Literal split, not regex
+    // (codebase idiom — see line 427 / client.ts:483).
+    const flat = (el.getAttribute('aria-label') || directText(el) || el.getAttribute('title') || el.textContent || '')
+        .split('\n').join(' ').split('\t').join(' ')
+    const label = flat.split(' ').filter(Boolean).join(' ').slice(0, 40)
+    const tag = el.tagName.toLowerCase()
+    const name = label || `<${tag}>`
+    const raw = el.getAttribute('data-insp-path')
+    let loc = ''
+    if (raw) {
+        const [file, line] = raw.split(':')
+        const tail = file.split('/').slice(-2).join('/')
+        loc = line ? ` @${tail}:${line}` : ` @${tail}`
+    }
+    return `${name} [${tag}]${loc}`
+}
+
+function directText(el: Element): string {
+    let t = ''
+    for (const node of el.childNodes) {
+        if (node.nodeType === 3)
+            t += node.textContent
+    }
+    return t.trim()
+}
+
+// Light projection — just the variables that move when UI changes. NOT the full
+// collectScreen (knobs etc.) which lives in client.ts; this only needs the deltas.
+function stampScreen(entry: ActionEntry) {
+    let view = '(unknown)'
+    try { view = (window as any).__AIPEEK_VIEW__?.() ?? '(unknown)' } catch { /* app hook threw */ }
+    entry.view = view
+    perf.active = view === '(unknown)' ? '__all__' : view
+    const modalEl = document.querySelector('[role="dialog"][data-state="open"]')
+    entry.modal = modalEl
+        ? (modalEl.querySelector('h1, h2, [id^="radix"]')?.textContent || 'untitled').trim().slice(0, 40)
+        : 'none'
+    const active = document.activeElement
+    entry.focus = active && active !== document.body ? describe(active) : 'none'
+}
+
+// Enqueue + stamp in one place — every listener funnels here so the trusted/pushBounded/
+// settle-then-stamp triple isn't repeated five times.
+function record(e: Event, type: string, target: Element, value?: string) {
+    const entry: ActionEntry = {
+        type,
+        target: describe(target),
+        value: value === undefined ? undefined : value.slice(0, 60),
+        trusted: e.isTrusted,
+        ts: Date.now(),
+    }
+    actionEntries.push(entry)
+    if (actionEntries.length > MAX_ACTIONS) {
+        actionEntries.shift()
+        actionsDropped++ // head evicted — timeline must announce the clip (diagnostic-fiber law)
+    }
+    // Stamp view/modal/focus after the first React commit settles (<20ms). Must land before the
+    // action response ships, or attachTimeline reads the entry without its `→ ui change` suffix —
+    // so this stays under waitForStable's quiet (now 50ms), with ~10ms headroom.
+    setTimeout(() => stampScreen(entry), 40)
+}
+
+// e.target is the innermost leaf actually clicked — the <svg> icon *inside* the button, not
+// the button. A human perceives clicking "AI 对话", so record what they aimed at: climb to the
+// nearest interactive ancestor (same INTERACTIVE set as command dispatch; inlined — client-patch
+// can't import). The leaf often has no name (svg/span) → describe() falls back to <svg>, breaking
+// the action↔feedback morphism. Falls back to the leaf if no interactive ancestor (rare).
+const INTERACTIVE = 'a, button, input, textarea, select, [role], [onclick], [tabindex], [contenteditable], [aria-label]'
+const aimed = (el: Element) => el.closest(INTERACTIVE) ?? el
+document.addEventListener('click', e => e.target && record(e, 'click', aimed(e.target as Element)), true)
+document.addEventListener('submit', e => e.target && record(e, 'submit', e.target as Element), true)
+document.addEventListener('change', (e) => {
+    if (!e.target)
+        return
+    lastInputTarget = null
+    record(e, 'change', e.target as Element, (e.target as HTMLInputElement).value)
+}, true)
+
+document.addEventListener('keydown', (e) => {
+    if (KEYS.has(e.key))
+        record(e, `key:${e.key}`, (e.target as Element | null) ?? document.body)
+}, true)
+
+document.addEventListener('input', (e) => {
+    const el = e.target as HTMLInputElement | null
+    if (!el)
+        return
+    const value = el.value ?? (el.isContentEditable ? (el.textContent ?? '') : '')
+    // Debounce same-target keystrokes: rewrite the last entry instead of appending one
+    // per character (the timeline wants "input value=hello", not h/he/hel/…).
+    const last = actionEntries[actionEntries.length - 1]
+    if (lastInputTarget === el && last?.type === 'input') {
+        last.value = value.slice(0, 60)
+        last.trusted = e.isTrusted
+        last.ts = Date.now()
+        setTimeout(() => stampScreen(last), 180)
+        return
+    }
+    lastInputTarget = el
+    record(e, 'input', el, value)
+}, true)
+
+// --- 一体化反向态射最后一跳:Alt+Click 页面元素 → 浮层直接显示代码原因 ---
+// FUSION §7。Alt+Click 任一元素 → 沿 DOM 找最近 data-insp-path → fetch /source → 浮层渲染
+// 符号 + callers/callees(每条可点继续向上跳调用链)。镜像 read/locate.ts 的 sourcePanelHtml
+// (client-patch 不能 import),core 单测钉契约,这里靠 aihand 真页面验证字节一致。
+
+function srcEsc(s: string): string {
+    return s.split('&').join('&amp;').split('<').join('&lt;').split('>').join('&gt;').split('"').join('&quot;')
+}
+
+// 与 read/locate.ts sourcePanelHtml 同一渲染(LocateResult → HTML),逐字镜像。
+function srcPanelHtml(r: any): string {
+    const at = (s: any) => `${s.filePath}:${s.startLine + 1}`
+    const row = (c: any) => `<div class="aihand-src-edge" data-src-path="${srcEsc(at(c))}">${srcEsc(c.name)} <span class="aihand-src-at">${srcEsc(at(c))}</span></div>`
+    const out = [`<div class="aihand-src-head">${srcEsc(r.symbol.name)} <span class="aihand-src-kind">${srcEsc(r.symbol.kind)}</span> <span class="aihand-src-at">${srcEsc(at(r.symbol))}</span></div>`]
+    if (r.callers.length)
+        out.push(`<div class="aihand-src-sec">Callers (${r.callers.length})</div>`, ...r.callers.map(row))
+    if (r.callees.length)
+        out.push(`<div class="aihand-src-sec">Callees (${r.callees.length})</div>`, ...r.callees.map(row))
+    if (!r.callers.length && !r.callees.length)
+        out.push(`<div class="aihand-src-empty">(no call edges found)</div>`)
+    if (r.impact)
+        out.push(`<div class="aihand-src-impact">Impact: ${srcEsc(r.impact.risk)} (${r.impact.upstreamCount} upstream)</div>`)
+    return out.join('')
+}
+
+let srcPanelEl: HTMLDivElement | null = null
+function closeSrcPanel() {
+    srcPanelEl?.remove()
+    srcPanelEl = null
+}
+
+async function showSrcPanel(path: string, x: number, y: number) {
+    let r: any
+    try {
+        const resp = await originalFetch(`/__aihand/source?path=${encodeURIComponent(path)}&impact&json`, { cache: 'no-store' })
+        if (!resp.ok) {
+            r = null
+        }
+        else {
+            r = await resp.json()
+        }
+    }
+    catch {
+        r = null
+    }
+    closeSrcPanel()
+    const panel = document.createElement('div')
+    panel.className = 'aihand-src-panel'
+    panel.style.cssText = `position:fixed;left:${Math.min(x, window.innerWidth - 340)}px;top:${Math.min(y, window.innerHeight - 200)}px;z-index:2147483647;max-width:320px;max-height:60vh;overflow:auto;background:#1e1e1e;color:#ddd;font:12px/1.5 ui-monospace,monospace;border:1px solid #444;border-radius:6px;padding:8px 10px;box-shadow:0 8px 30px rgba(0,0,0,.5)`
+    panel.innerHTML = r
+        ? srcPanelHtml(r)
+        : `<div class="aihand-src-empty">no symbol owns ${srcEsc(path)}</div>`
+    panel.dataset.x = String(x)
+    panel.dataset.y = String(y)
+    document.body.appendChild(panel)
+    srcPanelEl = panel
+}
+
+// 监听挂 window capture,不是 document capture:本 app 在 window↔document 之间有一层 capture
+// 监听对「带修饰键的 click」(alt/meta/ctrl/shift 全部)stopPropagation,导致 document 级永远收不到
+// Alt+Click(实测:plain 到 document,任何修饰键都被吞)。window capture 是事件最外层,先于那层吞噬者。
+window.addEventListener('click', (e) => {
+    if (!(e.altKey && e.shiftKey))
+        return
+    const el = (e.target as Element | null)?.closest('[data-insp-path]') as HTMLElement | null
+    e.preventDefault()
+    e.stopPropagation()
+    if (!el) {
+        closeSrcPanel()
+        return
+    }
+    const raw = el.getAttribute('data-insp-path')!
+    // insp-path 形态 `rel:line` 或 `rel:line:col:Name` — 取 file:line 两段喂 /source(端点自会再 parse)。
+    const seg = raw.split(':')
+    const path = seg.length <= 2 ? raw : `${seg[0]}:${seg[1]}`
+    showSrcPanel(path, e.clientX + 4, e.clientY + 4)
+}, true)
+
+// 浮层内点 caller/callee 边 → 继续向上跳调用链。同样挂 window capture(本 app 吞掉冒泡到
+// 浮层的 click,panel.addEventListener 收不到),委托判定 target 落在边上。
+window.addEventListener('click', (e) => {
+    if ((e.altKey && e.shiftKey) || !srcPanelEl)
+        return
+    const edge = (e.target as Element | null)?.closest('[data-src-path]') as HTMLElement | null
+    if (edge && srcPanelEl.contains(edge)) {
+        e.preventDefault()
+        e.stopPropagation()
+        showSrcPanel(edge.getAttribute('data-src-path')!, Number(srcPanelEl.dataset.x), Number(srcPanelEl.dataset.y))
+    }
+}, true)
+
+window.addEventListener('keydown', (e) => {
+    if (e.key === 'Escape')
+        closeSrcPanel()
+}, true)
+// 点浮层外关闭(普通点击,非 Alt+Shift 触发手势)。
+window.addEventListener('click', (e) => {
+    if (!(e.altKey && e.shiftKey) && srcPanelEl && !srcPanelEl.contains(e.target as Node))
+        closeSrcPanel()
+}, true)
+
+// --- Utils ---
+
+function jsonSample(text: string): string | undefined {
+    if (!text || (text[0] !== '{' && text[0] !== '['))
+        return undefined
+    try {
+        return JSON.stringify(sampleOf(JSON.parse(text), 0))
+    }
+    catch {
+        return undefined
+    }
+}
+
+function sampleOf(v: unknown, d: number): unknown {
+    if (d > 4)
+        return null
+    if (v === null || v === undefined)
+        return v
+    if (typeof v === 'string')
+        return v.length > 50 ? v.slice(0, 50) : v
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return v
+    if (Array.isArray(v))
+        return v.length ? [sampleOf(v[0], d + 1)] : []
+    if (typeof v === 'object') {
+        const result: Record<string, unknown> = {}
+        for (const [k, val] of Object.entries(v as Record<string, unknown>).slice(0, 15)) {
+            if (typeof val === 'function')
+                continue
+            result[k] = sampleOf(val, d + 1)
+        }
+        return result
+    }
+    return null
+}
+
+// client-patch 是自包含内联脚本（esbuild transformSync，无模块解析）——不能 import core/util。
+// 这是 core/util.ts formatValue 的镜像；两处契约由各自单测守，client 侧靠运行时验证。
+function formatValue(v: unknown, seen: Set<object> = new Set()): string {
+    if (v === null || v === undefined)
+        return String(v)
+    const t = typeof v
+    if (t === 'string')
+        return v as string
+    if (t === 'number' || t === 'boolean' || t === 'bigint')
+        return String(v)
+    if (t === 'symbol')
+        return (v as symbol).toString()
+    if (t === 'function')
+        return `[Function: ${(v as { name?: string }).name || 'anonymous'}]`
+    const obj = v as object
+    if (seen.has(obj))
+        return '[Circular]'
+    if (v instanceof Error)
+        return v.stack || `${v.name}: ${v.message}`
+    seen.add(obj)
+    if (v instanceof Map) {
+        const items = [...v.entries()].slice(0, 15).map(([k, val]) => `${formatValue(k, seen)} => ${formatValue(val, seen)}`)
+        return `Map(${v.size}) {${items.join(', ')}${v.size > 15 ? ', …' : ''}}`
+    }
+    if (v instanceof Set) {
+        const items = [...v.values()].slice(0, 15).map(val => formatValue(val, seen))
+        return `Set(${v.size}) {${items.join(', ')}${v.size > 15 ? ', …' : ''}}`
+    }
+    if (Array.isArray(v)) {
+        const items = v.slice(0, 30).map(val => formatValue(val, seen))
+        return `[${items.join(', ')}${v.length > 30 ? ', …' : ''}]`
+    }
+    try {
+        return JSON.stringify(v)
+    }
+    catch {
+        const entries = Object.entries(v as Record<string, unknown>).slice(0, 15)
+        return `{${entries.map(([k, val]) => `${k}: ${formatValue(val, seen)}`).join(', ')}}`
+    }
+}