aipeek 0.2.7 → 0.2.9

package/src/core/perf.ts

@@ -0,0 +1,250 @@
+import type { PerformanceData, PerfStat, PerfBucketData } from './types.js'
+
+// Verdict noise floors: a delta smaller than these is treated as measurement noise, not a real
+// change. Frame %: ±3pp. Self-time fallback: 10% relative, but at least 5ms absolute.
+const FRAME_NOISE_PCT = 3
+const SELF_NOISE_REL = 0.1
+const SELF_NOISE_MS = 5
+
+const avgOf = (samples: number[]) =>
+    samples.length > 0 ? samples.reduce((s, v) => s + v, 0) / samples.length : 0
+
+// Summarize accumulated stat into display shape. total/n/max are O(1) streaming all-time
+// truths; avg derives from them. No p95 here: it would need a per-key sample buffer, which is
+// near-window while total/n/max are all-time — putting two different sample sets in one row
+// (a row implies one distribution). max already gives the worst case, avg the center; that's
+// enough to decide "is this worth optimizing" without a same-row lie.
+export function summarizeStat(stat: PerfStat) {
+    const avg = stat.n > 0 ? stat.total / stat.n : 0
+    return {
+        total: stat.total,
+        n: stat.n,
+        avg,
+        max: stat.max,
+    }
+}
+
+// Merge two stats (for __all__ aggregation or HMR accumulation)
+export function mergeStat(a: PerfStat, b: PerfStat): PerfStat {
+    return {
+        total: a.total + b.total,
+        n: a.n + b.n,
+        max: Math.max(a.max, b.max),
+    }
+}
+
+// Which buckets a single hit (component/line/frame) writes to: the live view + the __all__
+// aggregate. When the active view IS __all__, return it ONCE — else every hit double-counts
+// into __all__ (n, total, frames all 2×). Mirrors client-patch.ts targetBuckets().
+export function targetBuckets(active: string): string[] {
+    return active === '__all__' ? ['__all__'] : [active, '__all__']
+}
+
+// One-line summary: 23fps · 18% dropped · 4 longtasks(max 120ms) · hot: ChatList 340ms, Markdown 120ms
+export function compactPerformance(p: PerformanceData): string {
+    const all = p.buckets.find(b => b.name === '__all__')
+    if (!all) return 'perf: (no data)'
+
+    const { total, long, samples } = all.frames
+    const fps = total > 0 ? Math.round((1000 / avgOf(samples)) * 10) / 10 : 0
+    const droppedPct = total > 0 ? Math.round((long / total) * 100) : 0
+
+    const parts: string[] = [`${fps}fps`, `${droppedPct}% dropped`]
+
+    if (p.longtasks.count > 0) {
+        parts.push(`${p.longtasks.count} longtasks(max ${Math.round(p.longtasks.max)}ms)`)
+    }
+
+    // Top 2 components by total
+    const topComps = Object.entries(all.components)
+        .map(([name, stat]) => ({ name, total: stat.total }))
+        .sort((a, b) => b.total - a.total)
+        .slice(0, 2)
+
+    if (topComps.length > 0 && p.mobxPatched) {
+        const hot = topComps.map(c => `${c.name} ${Math.round(c.total)}ms`).join(', ')
+        parts.push(`hot: ${hot}`)
+    }
+
+    return `perf: ${parts.join(' · ')}`
+}
+
+// Full report adapting litcode __recReport
+export function detailPerformance(p: PerformanceData): string {
+    const lines: string[] = []
+
+    // Banner
+    const windowSec = (p.windowMs / 1000).toFixed(1)
+    lines.push(`=== Performance (${windowSec}s window) ===`)
+    if (p.hiddenFrames > 0) {
+        lines.push(`⚠ Tab was backgrounded — ${p.hiddenFrames} hidden frames skipped (rAF throttling lies about timing)`)
+        lines.push('For accurate profiling: keep tab FOREGROUND + run /profile/reset before reproducing')
+    }
+    lines.push(`MobX attribution: ${p.mobxPatched ? 'ON' : 'OFF'}`)
+    if (!p.mobxPatched) {
+        lines.push('(Component attribution disabled — set window.__AIPEEK_MOBX__={Reaction} in src/lib/mobx.ts to enable)')
+    }
+    lines.push('')
+
+    // longtasks
+    if (p.longtasks.count > 0) {
+        lines.push(`Longtasks (>50ms): ${p.longtasks.count}, max ${Math.round(p.longtasks.max)}ms`)
+        lines.push('')
+    }
+
+    // Buckets (always show __all__, then per-view only if >1 bucket)
+    const showPerView = p.buckets.length > 1
+    for (const bucket of p.buckets) {
+        if (bucket.name !== '__all__' && !showPerView) continue
+
+        lines.push(`--- ${bucket.name} ---`)
+
+        // Frame stats
+        const { total, long, max, samples } = bucket.frames
+        const droppedPct = total > 0 ? ((long / total) * 100).toFixed(1) : '0.0'
+        const avgFrame = avgOf(samples).toFixed(1)
+        lines.push(`Frames: ${total} total, ${long} dropped (${droppedPct}%), max ${Math.round(max)}ms, avg ${avgFrame}ms`)
+
+        // Components (top 20 by total, desc)
+        const comps = Object.entries(bucket.components)
+            .map(([name, stat]) => ({ name, ...summarizeStat(stat) }))
+            .sort((a, b) => b.total - a.total)
+            .slice(0, 20)
+
+        if (comps.length > 0 && p.mobxPatched) {
+            lines.push('Components (by total self-time):')
+            for (const c of comps) {
+                lines.push(`  ${c.name.padEnd(30)} ${Math.round(c.total)}ms / ${c.n}× = ${c.avg.toFixed(1)}ms avg, max ${Math.round(c.max)}ms`)
+            }
+        } else if (!p.mobxPatched) {
+            lines.push('(no component data — attribution OFF)')
+        }
+
+        // Hot lines (top 15 by total time) — babel line-level instrumentation.
+        // Orthogonal to component attribution: points at the exact source line, not just the component.
+        // INCLUSIVE, not self-time: __line wraps each statement, so an outer statement's timing
+        // contains every nested __line below it (`const x = foo(bar())` counts foo+bar). Labeling
+        // this "self-time" would lie — you'd optimize a high-level line that just sums its callees.
+        const hotLines = Object.entries(bucket.lines ?? {})
+            .map(([label, stat]) => ({ label, ...summarizeStat(stat) }))
+            .sort((a, b) => b.total - a.total)
+            .slice(0, 15)
+
+        if (hotLines.length > 0) {
+            lines.push('Hot lines (by total inclusive time — contains nested calls):')
+            for (const l of hotLines) {
+                lines.push(`  ${l.label.padEnd(36)} ${Math.round(l.total)}ms / ${l.n}× = ${l.avg.toFixed(1)}ms avg, max ${Math.round(l.max)}ms`)
+            }
+        }
+
+        lines.push('')
+    }
+
+    return lines.join('\n')
+}
+
+// Closed-loop verdict: did my fix work? Compares two snapshots (before/after) by component
+// name + line label, lists per-key total-ms deltas, and a headline verdict driven by the
+// __all__ frame dropped% change. This is what lets an automated fix→measure loop decide
+// "keep it" vs "revert and try again" without eyeballing two reports.
+export function diffPerformance(before: PerformanceData, after: PerformanceData): string {
+    const out: string[] = []
+
+    const beforeAll = before.buckets.find(b => b.name === '__all__')
+    const afterAll = after.buckets.find(b => b.name === '__all__')
+
+    const droppedPct = (b: PerfBucketData | undefined) =>
+        b && b.frames.total > 0 ? (b.frames.long / b.frames.total) * 100 : 0
+    const beforeDrop = droppedPct(beforeAll)
+    const afterDrop = droppedPct(afterAll)
+    const dropDelta = afterDrop - beforeDrop
+
+    // Total self-time across all components — the fallback ground truth when frames weren't
+    // exercised (e.g. a fix reproduced via direct calls, not real renders → 0%→0% frames).
+    const sumTotal = (b: PerfBucketData | undefined) =>
+        b ? Object.values(b.components).reduce((s, c) => s + c.total, 0) : 0
+    const beforeSelf = sumTotal(beforeAll)
+    const afterSelf = sumTotal(afterAll)
+    const selfDelta = afterSelf - beforeSelf
+
+    // Verdict: frame health is the user-visible truth. But frames are only comparable when BOTH
+    // snapshots actually sampled frames AND at least one saw drops. If the after-tab went hidden
+    // its frameLoop stops (frames.total→0), which would read as a false "0% dropped" win — so fall
+    // back to self-time (MobX self-time keeps recording in the background) whenever a side is blind.
+    const bothSampledFrames = (beforeAll?.frames.total ?? 0) > 0 && (afterAll?.frames.total ?? 0) > 0
+    const sawDrops = (beforeAll?.frames.long ?? 0) > 0 || (afterAll?.frames.long ?? 0) > 0
+    const framesExercised = bothSampledFrames && sawDrops
+
+    // Blind-window guard: a backgrounded after-tab records NEITHER frames (rAF frozen) NOR
+    // self-time (nothing re-renders, so Reaction.track never fires). Both signals are absent, so
+    // selfDelta = 0 - beforeSelf is a large negative → a FALSE "IMPROVED" off an empty window.
+    // (The fallback comment above assumed self-time survives backgrounding; live data disproved it
+    // — a hidden tab renders nothing.) No data is not a win: refuse to render any direction.
+    const afterBlind = (afterAll?.frames.total ?? 0) === 0 && afterSelf === 0
+    let verdict: string
+    if (afterBlind) {
+        verdict = 'NO DATA'
+    } else if (framesExercised) {
+        if (dropDelta < -FRAME_NOISE_PCT) verdict = 'IMPROVED'
+        else if (dropDelta > FRAME_NOISE_PCT) verdict = 'REGRESSED'
+        else verdict = 'UNCHANGED'
+    } else {
+        const floor = Math.max(SELF_NOISE_MS, beforeSelf * SELF_NOISE_REL)
+        if (selfDelta < -floor) verdict = 'IMPROVED'
+        else if (selfDelta > floor) verdict = 'REGRESSED'
+        else verdict = 'UNCHANGED'
+    }
+
+    out.push(`=== Perf diff: ${verdict} ===`)
+    if (afterBlind) {
+        out.push('after-window recorded no frames and no self-time — tab backgrounded or idle. Re-run with the tab focused and the interaction reproduced.')
+        out.push('')
+        return out.join('\n').trimEnd()
+    }
+    out.push(`Dropped frames: ${beforeDrop.toFixed(1)}% → ${afterDrop.toFixed(1)}% (${dropDelta >= 0 ? '+' : ''}${dropDelta.toFixed(1)}%)`)
+    if (!framesExercised && Math.round(selfDelta) !== 0) {
+        out.push(`Total self-time: ${Math.round(beforeSelf)}ms → ${Math.round(afterSelf)}ms (${selfDelta >= 0 ? '+' : ''}${Math.round(selfDelta)}ms) — frames flat, verdict by self-time`)
+    }
+    if (before.longtasks.count !== after.longtasks.count) {
+        out.push(`Longtasks: ${before.longtasks.count} → ${after.longtasks.count}`)
+    }
+    out.push('')
+
+    // Per-component total-ms deltas (union of names), biggest absolute change first.
+    const compDelta = keyedTotalDelta(beforeAll?.components ?? {}, afterAll?.components ?? {})
+    if (compDelta.length > 0) {
+        out.push('Components (Δ total self-time):')
+        for (const d of compDelta) out.push('  ' + formatDelta(d))
+        out.push('')
+    }
+
+    // Per-line total-ms deltas (only when line instrumentation was on).
+    const lineDelta = keyedTotalDelta(beforeAll?.lines ?? {}, afterAll?.lines ?? {})
+    if (lineDelta.length > 0) {
+        out.push('Hot lines (Δ total inclusive time):')
+        for (const d of lineDelta) out.push('  ' + formatDelta(d))
+    }
+
+    return out.join('\n').trimEnd()
+}
+
+interface KeyDelta { key: string, before: number, after: number, delta: number, isNew: boolean, gone: boolean }
+
+function keyedTotalDelta(a: Record<string, PerfStat>, b: Record<string, PerfStat>): KeyDelta[] {
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)])
+    const rows: KeyDelta[] = []
+    for (const key of keys) {
+        const beforeT = a[key]?.total ?? 0
+        const afterT = b[key]?.total ?? 0
+        const delta = afterT - beforeT
+        if (Math.round(delta) === 0) continue // unchanged keys add noise
+        rows.push({ key, before: beforeT, after: afterT, delta, isNew: !a[key], gone: !b[key] })
+    }
+    return rows.sort((x, y) => Math.abs(y.delta) - Math.abs(x.delta)).slice(0, 20)
+}
+
+function formatDelta(d: KeyDelta): string {
+    const sign = d.delta >= 0 ? '+' : ''
+    const tag = d.isNew ? ' (new)' : d.gone ? ' (gone)' : ''
+    return `${d.key.padEnd(36)} ${Math.round(d.before)}ms → ${Math.round(d.after)}ms (${sign}${Math.round(d.delta)}ms)${tag}`
+}

package/src/core/types.ts

@@ -29,16 +29,76 @@ export interface ErrorEntry {
     column?: number
 }
 
+// One semantic page action — a state-machine transition. trusted=real human / real
+// input; !trusted=aipeek synthetic. view/modal/focus are the post-settle projection
+// snapshot; the UI change ("dialog opened") is the diff against the prior entry.
+export interface ActionEntry {
+    type: string
+    target: string
+    value?: string
+    trusted: boolean
+    view?: string
+    modal?: string
+    focus?: string
+    ts: number
+    tab?: string // set only in the server's cross-tab /timeline merge; undefined per-tab
+}
+
 export interface RawState {
+    tab?: string
     url: string
+    title?: string
+    visible?: boolean
     ui: string
     console: LogEntry[]
     network: NetworkRequest[]
     errors: ErrorEntry[]
+    actions?: ActionEntry[]
     state: Record<string, unknown>
+    performance?: PerformanceData
     timestamp: number
 }
 
+// --- Performance profiler ---
+//
+// 语义分桶 profiler 的投影。三类正交信号(组件 self-time / 帧 dt / longtask)按 view 分桶,
+// 答「哪个组件在烧帧」。client-patch 采集进 ring buffer,client 投影成此结构,core/perf.ts 纯渲染。
+
+// 一段重复计时的累积统计。total/n/max 全是 O(1) 流式全程真值,avg=total/n 派生。
+// 不存 samples:它过去只为 p95,而 p95 是近窗近似、和全程 total 不同源(放同一行即撒谎),已删。
+export interface PerfStat {
+    total: number
+    n: number
+    max: number
+}
+
+// 一个语义桶(一个 view,或全局 __all__):组件 self-time map + 帧统计 + 行级 self-time map。
+export interface PerfBucketData {
+    name: string
+    components: Record<string, PerfStat>
+    frames: { total: number, long: number, max: number, samples: number[] }
+    lines: Record<string, PerfStat>  // "File.tsx:42:varName" → stat,babel 行级插桩
+}
+
+export interface PerformanceData {
+    windowMs: number       // Date.now() - startedAt,采样窗口时长
+    hiddenFrames: number   // 标签页隐藏期被跳过的帧(后台 rAF 节流会说谎,故不计入 frames)
+    mobxPatched: boolean   // Reaction.track patch 是否生效(否则无组件归因)
+    buckets: PerfBucketData[]  // __all__ 在前
+    longtasks: { count: number, max: number }
+}
+
+// One live client (browser tab / Electron window) seen by the server. lastSeen is the
+// server-side arrival time of its most recent reply — used to address one tab (?tab=)
+// and to age out stale entries from /tabs.
+export interface TabInfo {
+    id: string
+    url: string
+    title: string
+    visible: boolean
+    lastSeen: number
+}
+
 export interface CompactState {
     url: string
     ui: string
@@ -46,6 +106,7 @@ export interface CompactState {
     network: string
     errors: string
     state: string
+    performance?: string
     timestamp: number
     counts: {
         console: number
@@ -73,3 +134,15 @@ export interface DiffResult {
     uiGone: boolean
     clean: boolean
 }
+
+// The state-machine projection at one instant — what a click/fill is diffed against
+// before vs after it settles. view/modal/focus are aipeek's generic UI vars; `domain`
+// is the app's own state machine, injected via window.__AIPEEK_SCREEN__() — the few
+// variables that DON'T live in the DOM (是否流式 / 选了哪个模型 / 未读数), which a
+// DOM-only projector can never synthesize. Empty when the app injects nothing.
+export interface ScreenSnap {
+    view: string
+    modal: string
+    focus: string
+    domain: Record<string, unknown>
+}

package/src/core/util.ts

@@ -1,3 +1,5 @@
+import type { ActionEntry, TabInfo } from './types'
+
 export function truncate(s: string, max: number): string {
     return s.length > max ? `${s.slice(0, max)}…` : s
 }
@@ -67,3 +69,116 @@ export function compactUrl(url: string, search?: number): string {
         return truncate(url, 80)
     }
 }
+
+// A tab is "live" if it replied within STALE_MS (a closed tab stops replying, so its
+// lastSeen freezes). One definition, shared by the server's roster/guard and formatTabs.
+export const STALE_MS = 30_000
+export const isLive = (t: TabInfo, now: number) => now - t.lastSeen < STALE_MS
+
+// Render the live-tab roster — shared by GET /tabs and the 409 "which tab?" guard.
+// `now` is server time. The visible one is marked first so the caller can pick.
+export function formatTabs(tabs: TabInfo[], now: number): string {
+    const live = tabs.filter(t => isLive(t, now))
+    if (!live.length)
+        return '(no live tabs)'
+    return live
+        .sort((a, b) => Number(b.visible) - Number(a.visible) || a.id.localeCompare(b.id))
+        .map((t) => {
+            const age = Math.round((now - t.lastSeen) / 1000)
+            const mark = t.visible ? '● visible' : '○ background'
+            return `${t.id}  ${mark}  ${truncate(t.title || '(untitled)', 40)}  ${compactUrl(t.url)}  ${age}s ago`
+        })
+        .join('\n')}
+
+// The single projection π for every "didn't get an answer" path: connection state → one
+// actionable message. Defined once, pure (no closure, no clock), so no failure path can
+// collapse two states that need different fixes (the law: ker π ⊆ ker f*). The five fibers
+// each demand a different action, so each gets its own branch:
+//   addressed, live      → handler threw / hung / read needs foreground   (check console)
+//   addressed, not live  → tab closed or mid self-heal                    (check /tabs, retry)
+//   broadcast, live tabs → handler threw or tab just closed               (check /tabs + console)
+//   broadcast, sockets>0 → page open but client not injected/wrong server (check the port)
+//   broadcast, no socket → no browser pointed here at all                 (open the app)
+// `socketCount` is the raw HMR-socket count (server.ws.clients.size) — the bit that separates
+// "open but uninjected" from "no browser", which the aipeek roster alone can't see.
+export function diagnose(tab: string | undefined, tabs: TabInfo[], now: number, socketCount: number, port: number): string {
+    if (tab) {
+        const t = tabs.find(x => x.id === tab)
+        return t && isLive(t, now)
+            ? `tab '${tab}' is connected but didn't answer in time — the handler likely threw or hung (bad selector, infinite loop, or a read that needs the tab foreground). Check /__aipeek/console.`
+            : `tab '${tab}' is not connected — it closed, or the server restarted and it hasn't re-handshaked yet. Check /__aipeek/tabs for live ids; if the page is mid self-heal, retry in ~2s.`
+    }
+    const live = tabs.filter(t => isLive(t, now))
+    if (live.length)
+        return `${live.length} tab(s) connected but none answered — a handler threw, or they just closed. Check /__aipeek/tabs (still live?) and /__aipeek/console (errors?).`
+    return socketCount > 0
+        ? `no aipeek tab registered, but ${socketCount} page(s) are connected to this dev server via HMR — the page is open yet the aipeek client didn't load. Is it served by THIS vite server on :${port}? A separate vite config / vite preview / production build won't inject it.`
+        : `no browser tab connected to this dev server on :${port} — open the app, or check you're hitting the right port.`
+}
+
+// Render the action ring as a cause-effect timeline. Each entry is a transition; the UI
+// change (→ dialog opened / closed / view switched) is the diff of this entry's post-settle
+// snapshot against the prior one *on the same tab*. `T`=trusted (human), `S`=synthetic
+// (aipeek). With anchorTs set, the matching entry is bracketed by "你当前的行为" dividers so
+// the model reads [earlier] → its own action → [what followed]. Pure: no DOM. Shared by the
+// single-tab `recent actions` tail (client.ts) and the cross-tab GET /timeline (server).
+export function formatActions(entries: ActionEntry[], anchorTs?: number): string {
+    if (!entries.length)
+        return '(no actions)'
+    const sorted = [...entries].sort((a, b) => a.ts - b.ts)
+    // Tag lines with their tab only when the stream spans >1 tab (the cross-tab /timeline).
+    // Single-tab `recent actions` stays byte-identical — no tab prefix. uiChange diffs per
+    // tab, so an interleaved A/B stream doesn't read B's modal as A's transition.
+    const multiTab = new Set(sorted.map(e => e.tab).filter(Boolean)).size > 1
+    const lines: string[] = []
+    const prevByTab = new Map<string | undefined, ActionEntry>()
+    let anchored = false
+    for (const e of sorted) {
+        const isAnchor = anchorTs !== undefined && !anchored && e.ts === anchorTs
+        if (isAnchor) {
+            lines.push('—————— 你当前的行为 ——————')
+            anchored = true
+        }
+        const who = e.trusted ? 'T' : 'S'
+        const tag = multiTab ? `${e.tab ?? '?'} ` : ''
+        const val = e.value ? ` value="${e.value}"` : ''
+        const change = uiChange(prevByTab.get(e.tab), e)
+        lines.push(`${tag}[${who}] ${e.type} ${e.target}${val}${change ? `   → ${change}` : ''}`)
+        if (isAnchor)
+            lines.push('——————————————————————————')
+        prevByTab.set(e.tab, e)
+    }
+    return lines.join('\n')
+}
+
+// Append an action to the server's cross-tab ring, mutating it in place. Mirrors
+// client-patch's input debounce at the aggregation point: a tab fires its hook on every
+// keystroke (rewriting its in-page entry in place), so consecutive same-tab input on the
+// same target rewrites the logged entry instead of appending — else "hello" becomes 5 rows
+// (h/he/hel/…). Any other action ends the run. Ring-bounded by max. Pure logic, fixture-tested.
+export function appendAction(log: ActionEntry[], tab: string, entry: ActionEntry, max: number): void {
+    const last = log[log.length - 1]
+    if (entry.type === 'input' && last?.type === 'input' && last.tab === tab && last.target === entry.target) {
+        log[log.length - 1] = { ...entry, tab }
+        return
+    }
+    log.push({ ...entry, tab })
+    if (log.length > max)
+        log.shift()
+}
+
+function uiChange(prev: ActionEntry | undefined, cur: ActionEntry): string {
+    if (cur.modal === undefined)
+        return ''
+    const prevModal = prev?.modal ?? 'none'
+    if (cur.modal !== prevModal) {
+        if (cur.modal === 'none')
+            return '弹窗关闭'
+        if (prevModal === 'none')
+            return `弹窗打开「${cur.modal}」`
+        return `弹窗切换「${cur.modal}」`
+    }
+    if (prev && cur.view !== undefined && cur.view !== prev.view)
+        return `视图 ${prev.view}→${cur.view}`
+    return ''
+}