aihand 0.0.1 → 0.1.0

package/src/ui/core/perf.ts

@@ -0,0 +1,254 @@
+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,
+    }
+}
+
+// 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 or unfocused — ${p.hiddenFrames} throttled frames skipped (rAF throttling lies about timing)`)
+        lines.push('For accurate profiling: keep tab FOREGROUND + FOCUSED + 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. total===0 means NO trustworthy frames were sampled (tab unfocused/hidden
+        // the whole window). Printing "0 dropped (0.0%)" then reads as "buttery smooth" — the exact
+        // inverse of the truth. An empty denominator is not 0%, it's no data: say so plainly.
+        const { total, long, max, samples } = bucket.frames
+        if (total === 0) {
+            lines.push('Frames: none sampled (tab unfocused/hidden — no frame data this window)')
+        } else {
+            const droppedPct = ((long / total) * 100).toFixed(1)
+            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: the after-window must actually REPRODUCE the workload to be diffable.
+    // afterSelf===0 means zero components re-rendered. Two shapes both mean "workload not run":
+    //   (a) hard-blind — frames.total===0 too (rAF frozen, tab fully suspended);
+    //   (b) soft-blind — frames still ticked (rAF only throttled) but self-time is zero while the
+    //       before-window had real self-time. Frames alone then describe an idle tab's compositor,
+    //       not the render workload — a -5% frame delta off a backgrounded tab is NOT a code win.
+    // A genuine fix shows frames recovering AND self-time dropping in agreement; "frames still
+    // dropping but self-time vanished entirely" is the contradiction that betrays an idle after-tab.
+    // The pure-paint case (beforeSelf===0===afterSelf, frames>0) is NOT blind — it goes to frames.
+    const afterBlind = afterSelf === 0 && (beforeSelf > 0 || (afterAll?.frames.total ?? 0) === 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) {
+        const why = (afterAll?.frames.total ?? 0) === 0
+            ? 'recorded no frames and no re-renders'
+            : `recorded frames but zero re-renders (was ${Math.round(beforeSelf)}ms self-time)`
+        out.push(`after-window ${why} — tab backgrounded or workload not reproduced. Re-run with the tab focused and the interaction repeated.`)
+        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/ui/core/types.ts

@@ -0,0 +1,164 @@
+export interface LogEntry {
+    level: 'error' | 'warn' | 'info' | 'debug' | 'log'
+    text: string
+    timestamp?: number
+    source?: string
+}
+
+export interface NetworkRequest {
+    method: string
+    url: string
+    status: number
+    duration: number
+    resourceType: string
+    requestHeaders?: Record<string, string>
+    responseHeaders?: Record<string, string>
+    requestBody?: string
+    requestSample?: string
+    responseBody?: string
+    responseSample?: string
+    failed?: boolean
+    failureText?: string
+}
+
+export interface ErrorEntry {
+    message: string
+    stack?: string
+    source?: string
+    line?: number
+    column?: number
+}
+
+// One semantic page action — a state-machine transition. trusted=real human / real
+// input; !trusted=aihand 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[]
+    actionsDropped?: number // head entries the per-tab ring evicted before this window
+    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
+    console: string
+    network: string
+    errors: string
+    state: string
+    performance?: string
+    timestamp: number
+    counts: {
+        console: number
+        network: number
+        errors: number
+        state: number
+    }
+}
+
+export interface Assertion {
+    name: string
+    pass: boolean
+    detail?: string
+}
+
+export interface CheckResult {
+    pass: boolean
+    assertions: Assertion[]
+}
+
+export interface DiffResult {
+    newErrors: LogEntry[]
+    newExceptions: ErrorEntry[]
+    newFailedRequests: NetworkRequest[]
+    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 aihand'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.
+// A big structural block of the page (>5% viewport), digested to a comparison-stable key.
+// key = tag + quantized rect + childElementCount — small jitter doesn't change it, wholesale
+// region replacement does. The DOM-only signal behind view-change inference (see diffScreen).
+// label = role||tag + child count — a cheap human name (no text walk) so an *appeared* region
+// (a dropdown/popover that isn't a modal and isn't a nav) can be reported self-sufficiently.
+export interface RegionDigest {
+    tag: string
+    key: string
+    label: string
+}
+
+export interface ScreenSnap {
+    view: string
+    modal: string
+    focus: string
+    domain: Record<string, unknown>
+    // >5% viewport structural blocks. Only consumed when view is double-(unknown) — i.e. the app
+    // didn't inject __AIPEEK_VIEW__, so view-change is inferred from region replacement instead.
+    // Absent in old fixtures → treated as empty (no DOM fallback signal), zero regression.
+    regions: RegionDigest[]
+}

package/src/ui/core/util.ts

@@ -0,0 +1,221 @@
+import type { ActionEntry, TabInfo } from './types'
+
+export function truncate(s: string, max: number): string {
+    return s.length > max ? `${s.slice(0, max)}…` : s
+}
+
+// unknown → 人类可读字符串。穷举 JS 类型，让 JSON.stringify 的「漏网类型 → {}」失败模式不可能出现。
+// 返回未截断字符串——截断由调用方按各自 max 处理。
+export 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'}]`
+    // 此后 v 是 object
+    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 {
+        // 循环引用 / getter 抛错 → 手动遍历可枚举键，循环处标 [Circular]
+        const entries = Object.entries(v as Record<string, unknown>).slice(0, 15)
+        const parts = entries.map(([k, val]) => `${k}: ${formatValue(val, seen)}`)
+        return `{${parts.join(', ')}}`
+    }
+}
+
+// stack → 应用栈帧（去 node_modules / <anonymous>），保留 `at ` 前缀。max 与溢出提示由调用方决定。
+export function appStackFrames(stack: string, max: number): string[] {
+    return stack
+        .split('\n')
+        .map(l => l.trim())
+        .filter(l => l.startsWith('at ') && !l.includes('node_modules') && !l.includes('<anonymous>'))
+        .slice(0, max)
+}
+
+// pathname only; pass `search` to append a truncated query string
+export function compactUrl(url: string, search?: number): string {
+    try {
+        const u = new URL(url)
+        if (search && u.search)
+            return `${u.pathname}?${truncate(u.search.slice(1), search)}`
+        return u.pathname
+    }
+    catch {
+        return truncate(url, 80)
+    }
+}
+
+// SPA 路由切换判据(出口2 同文档导航回填用):CDP Page.navigatedWithinDocument 对一次真路由切换
+// 之外还会为锚点滚动 / replaceState 状态更新喷一串事件,只有 pathname+search 真变的那一次才是换页。
+// 纯 #hash 变化(同 path 同 search,只 hash 不同)是页内锚点跳转、不是路由切换,排除。URL 解析失败
+// (相对/畸形)退回字符串严格不等——保守:宁可漏判一次少见的畸形 URL 换页,不误判一次锚点为换页。
+export function isRouteChange(fromUrl: string, toUrl: string): boolean {
+    try {
+        const a = new URL(fromUrl)
+        const b = new URL(toUrl)
+        return a.pathname !== b.pathname || a.search !== b.search
+    }
+    catch {
+        return fromUrl !== toUrl && stripHash(fromUrl) !== stripHash(toUrl)
+    }
+}
+function stripHash(u: string): string {
+    const i = u.indexOf('#')
+    return i < 0 ? u : u.slice(0, i)
+}
+
+// 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.
+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.
+// When NO tab is visible (the user is reading the terminal, so every dev tab is
+// backgrounded — the common case), append a note: background is fully operable, so
+// the model never reads `○ background` as "can't act, ask the user to foreground it".
+export function formatTabs(tabs: TabInfo[], now: number): string {
+    const live = tabs.filter(t => isLive(t, now))
+    if (!live.length)
+        return '(no live tabs)'
+    const rows = 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')
+    if (live.some(t => t.visible))
+        return rows
+    return `${rows}\n(all backgrounded because the user is looking at the terminal — this is normal. Reads and clicks/fills work on background tabs; do NOT ask the user to foreground a tab. Only /profile needs focus.)`
+}
+
+// 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 / socket dropped mid self-heal   (retry, 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 aihand 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 — most likely the HMR socket dropped while the tab was backgrounded and self-heal hasn't reconnected yet (retry in ~2s, it reloads itself), or the handler threw/hung on a bad selector. Reads (/screen /dom) work backgrounded — do NOT ask the user to foreground the tab. Check /__aihand/console.`
+            : `tab '${tab}' is not connected — it closed, or the server restarted and it hasn't re-handshaked yet. Check /__aihand/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 /__aihand/tabs (still live?) and /__aihand/console (errors?).`
+    return socketCount > 0
+        ? `no aihand tab registered, but ${socketCount} page(s) are connected to this dev server via HMR — the page is open yet the aihand 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
+// (aihand). 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).
+//
+// dropped = how many head entries the ring evicted before this window (it's a bounded ring,
+// 30 per-tab / 200 server). A causal chain with a silently-cut head reads as "this is the
+// start" → the model anchors on a non-start. Same diagnostic-fiber law diff.ts already obeys
+// for flow frames (a clipped trace must announce the clip): announce the eviction at the head.
+export function formatActions(entries: ActionEntry[], anchorTs?: number, dropped = 0): string {
+    if (!entries.length)
+        return dropped > 0 ? `┄ … 更早 ${dropped} 条动作已超出窗口（此处非会话起点）` : '(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[] = []
+    if (dropped > 0)
+        lines.push(`┄ … 更早 ${dropped} 条动作已超出窗口（下方非会话起点）`)
+    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}」`
+    }
+    // Both sides must be captured to call it a transition. A prior entry whose view wasn't
+    // snapshotted (screen hook not injected yet) is *unknown*, not "a different view" — rendering
+    // `视图 undefined→chat` projects a non-event as a transition (ker π must not collapse
+    // unknown-prior into changed). Unknown prior → no change.
+    if (prev && cur.view !== undefined && prev.view !== undefined && cur.view !== prev.view)
+        return `视图 ${prev.view}→${cur.view}`
+    return ''
+}

package/src/ui/index.ts

@@ -0,0 +1,5 @@
+export { check } from './core/check'
+export { diffState } from './core/diff'
+export { emitCheck, emitDiff, emitSummary } from './core/emit'
+export type { CheckResult, CompactState, DiffResult, RawState } from './core/types'
+export { aihandPlugin } from './server/plugin'