aihand 0.0.1 → 0.1.0

package/src/ui/client/client.ts

@@ -0,0 +1,2562 @@
+/// <reference types="vite/client" />
+// aihand client — collectors + HMR channel (module)
+// The patch code (console/fetch/XHR/errors) is in client-patch.ts,
+// injected as a synchronous inline script before any modules execute.
+
+import type { ActionArgs, ActionResult, ActionType } from '../core/action'
+import type { ActionEntry, ErrorEntry, LogEntry, NetworkRequest, PerformanceData, PerfBucketData, RegionDigest, ScreenSnap } from '../core/types'
+import { elementLabel, getDirectText, INTERACTIVE, isSensitive, performAction, reachable, runEval, safeValue, withDialogGuard } from '../core/action'
+import { isBusyState, isSecretKey, redactSecretValue } from '../core/candidates'
+import type { Box, BoxKind } from '../core/canvas'
+import { numberKnobs, renderCanvas, renderKnobs, renderSemanticTree } from '../core/canvas'
+import { diffScreen, diffState, redactDomain, traceFlow } from '../core/diff'
+import { executeKnob, parseLiteral, resolveKnobRef } from '../core/knob-exec'
+import { formatActions } from '../core/util'
+import type { KnobProjection } from '../server/knob-schema'
+import type { Transport } from '../bridge/transport'
+
+// 旋钮态射的 build 时投影(virtual:aihand-knobs)。join 键 = label+file。给 live DOM 候选叠加语义:
+// 拨它 → store.{field=to}。出口1 shim 从 virtual 模块拉来填进这里(lookupSem/collectKnobs 在
+// 模块作用域读它,渲染 /screen 的旋钮态射);出口2(外部站无 schema)留空——/screen knobs 退回纯
+// label+坐标,行为不变(元真理:没它只是少个 → 后缀)。installProbe 默认也读它,出口1 二者同一份。
+let knobSem: Record<string, KnobProjection> = {}
+
+declare global {
+    interface Window {
+        __AIPEEK_STORES__?: Record<string, unknown>
+        // The app's own domain projection — collapses the UI to a few domain variables
+        // that don't live in the DOM (是否流式 / 选了哪个模型 / 未读数). Optional; when
+        // absent /screen falls back to the generic view/modal/focus projection unchanged.
+        __AIPEEK_SCREEN__?: () => Record<string, unknown>
+        // The view axis — the app's top-level mode/route. Only the app knows which of its
+        // many enum fields is the *top-level* view, so it declares it (the probe never guesses
+        // a store field). Absent → view falls back to '(unknown)'. App-agnostic seam.
+        __AIPEEK_VIEW__?: () => string
+        // Idempotency for shortest-path delivery: the server re-broadcasts an addressed action
+        // while a tab is mid self-heal, so the same action id can arrive more than once. Map id →
+        // its final result; on a repeat we replay the cached result instead of re-executing.
+        __AIPEEK_DONE_ACTIONS__?: Map<number, ActionResult>
+        // The green channel — named semantic actions the app exposes (sendPrompt, …). Each is
+        // the store-write + real semantic fn a button's onClick runs, minus the DOM; it returns
+        // its own before/after delta. The probe calls these by name, bypassing selector resolution
+        // and disabled/covered gating. App-declared (the app knows its own actions); absent → none.
+        __AIHAND_ACTIONS__?: Record<string, (...args: any[]) => unknown>
+    }
+}
+
+// Internal perf buffer shape (from client-patch.ts) — differs from PerformanceData
+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>
+}
+interface PerfBuffer {
+    startedAt: number
+    hiddenFrames: number
+    mobxPatched: boolean
+    buckets: Record<string, PerfBucketBuf>
+    active: string
+    longtasks: { count: number, max: number, lastEndAt: number }
+}
+
+interface AipeekBuffers {
+    consoleLogs: LogEntry[]
+    networkRequests: NetworkRequest[]
+    errorEntries: ErrorEntry[]
+    actionEntries: ActionEntry[]
+    perf: PerfBuffer
+    actionsDropped: number // monotonic head-eviction count from the action ring (getter on buffers)
+}
+
+// Read buffers from the synchronous patch script
+const buffers = (window as any).__AIPEEK_BUFFERS__ as AipeekBuffers | undefined
+const consoleLogs: LogEntry[] = buffers?.consoleLogs ?? []
+const networkRequests: NetworkRequest[] = buffers?.networkRequests ?? []
+const errorEntries: ErrorEntry[] = buffers?.errorEntries ?? []
+const actionEntries: ActionEntry[] = buffers?.actionEntries ?? []
+const perfBuffer: PerfBuffer | undefined = buffers?.perf
+
+// Project the runtime perf buffer into PerformanceData for collection.
+// Top-20 components by total, capped samples already in buffer.
+function collectPerformance(): PerformanceData | undefined {
+    if (!perfBuffer) return undefined
+    const buckets: PerfBucketData[] = []
+    // __all__ first, then named buckets
+    const names = Object.keys(perfBuffer.buckets).sort((a, b) => (a === '__all__' ? -1 : b === '__all__' ? 1 : a.localeCompare(b)))
+    for (const name of names) {
+        const b = perfBuffer.buckets[name]
+        const comps: Record<string, { total: number, n: number, max: number }> = {}
+        const sorted = Object.entries(b.components).sort((a, b) => b[1].total - a[1].total).slice(0, 20)
+        for (const [cname, stat] of sorted) {
+            comps[cname] = { total: stat.total, n: stat.n, max: stat.max }
+        }
+        const lines: Record<string, { total: number, n: number, max: number }> = {}
+        const sortedLines = Object.entries(b.lines ?? {}).sort((a, b) => b[1].total - a[1].total).slice(0, 30)
+        for (const [label, stat] of sortedLines) {
+            lines[label] = { total: stat.total, n: stat.n, max: stat.max }
+        }
+        buckets.push({
+            name,
+            components: comps,
+            frames: { total: b.frames.total, long: b.frames.long, max: b.frames.max, samples: [...b.frames.samples] },
+            lines,
+        })
+    }
+    return {
+        windowMs: Date.now() - perfBuffer.startedAt,
+        hiddenFrames: perfBuffer.hiddenFrames,
+        mobxPatched: perfBuffer.mobxPatched,
+        buckets,
+        longtasks: { ...perfBuffer.longtasks },
+    }
+}
+
+// Reset the perf buffer (clear window, start fresh)
+function resetPerf() {
+    if (!perfBuffer) return
+    perfBuffer.startedAt = Date.now()
+    perfBuffer.hiddenFrames = 0
+    perfBuffer.buckets = {}
+    perfBuffer.longtasks = { count: 0, max: 0, lastEndAt: 0 }
+}
+
+// Stable per-tab id so commands can address one tab among many (?tab=). Lives in
+// sessionStorage: one browser tab = one id, survives HMR/refresh, cleared on close.
+// Falls back to an in-memory id if sessionStorage is unavailable (degrades to old
+// broadcast behavior, never throws).
+const TAB_ID = (() => {
+    try {
+        const k = '__aihand_tab_id__'
+        let id = sessionStorage.getItem(k)
+        if (!id) {
+            id = `t${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`
+            sessionStorage.setItem(k, id)
+        }
+        return id
+    }
+    catch {
+        return `t${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`
+    }
+})()
+
+// --- On-demand collectors ---
+
+const SKIP_TAGS = new Set(['script', 'style', 'noscript', 'link', 'meta', 'head'])
+
+const IMPLICIT_ROLES: Record<string, string> = {
+    a: 'link',
+    button: 'button',
+    input: 'textbox',
+    textarea: 'textbox',
+    select: 'combobox',
+    img: 'img',
+    nav: 'navigation',
+    main: 'main',
+    header: 'banner',
+    footer: 'contentinfo',
+    aside: 'complementary',
+    form: 'form',
+    dialog: 'dialog',
+    ul: 'list',
+    ol: 'list',
+    li: 'listitem',
+    table: 'table',
+    h1: 'heading',
+    h2: 'heading',
+    h3: 'heading',
+    h4: 'heading',
+    h5: 'heading',
+    h6: 'heading',
+}
+
+// The implicit role of an element, refined by input type. An <input> alone maps to 'textbox',
+// but that collapses a password/email/checkbox field into the same token as a plain text box —
+// and an EMPTY secret field (no redacted value to give it away) then reads identically to an
+// empty text field, so an AI consuming /dom can't tell which box takes the API key. type=text is
+// the default (no suffix); any other type is a real distinguishing event the projection must carry.
+// The single chokepoint for role derivation, shared by /ui, /dom-fallback, and /dom.
+function roleOf(el: Element): string {
+    const explicit = el.getAttribute('role')
+    if (explicit)
+        return explicit
+    const tag = el.tagName.toLowerCase()
+    const base = IMPLICIT_ROLES[tag] || ''
+    if (tag === 'input') {
+        const type = (el.getAttribute('type') || 'text').toLowerCase()
+        if (type !== 'text')
+            return `${base}:${type}`
+    }
+    return base
+}
+
+function collectUI(): string {
+    const root = document.getElementById('root')
+    if (!root)
+        return collectDomFallback()
+
+    const fiberKey = Object.keys(root).find(k =>
+        k.startsWith('__reactContainer$') || k.startsWith('__reactFiber$'),
+    )
+    if (!fiberKey)
+        return collectDomFallback()
+
+    const rootFiber = (root as any)[fiberKey]
+    if (!rootFiber)
+        return collectDomFallback()
+
+    const COMPONENT_TAGS = new Set([0, 1, 14, 15])
+    const SKIP_EXACT = new Set([
+        'Fragment',
+        'Suspense',
+        'StrictMode',
+        'Context',
+        'Outlet',
+        'Routes',
+        'RenderedRoute',
+        'DataRoutes',
+        'RemoveScrollBar',
+        'Sheet',
+        'Router',
+        'RenderErrorBoundary',
+        'Tooltip',
+        'Popover',
+        'Dialog',
+        'DropdownMenu',
+        'ContextMenu',
+        'HoverCard',
+        'Select',
+        'Command',
+        'Tabs',
+        'RadioGroup',
+        'Markdown',
+        'Sonner',
+    ])
+    // wrapper components carry no UI semantics — skip by name shape
+    const SKIP_CONTAINS = ['Provider', 'Consumer', 'Portal', 'Popper', 'Presence', 'SideCar']
+    const SKIP_ENDS = ['Warning', 'Header', 'Footer', 'Menu', 'Root']
+    const isSkipped = (name: string) =>
+        SKIP_CONTAINS.some(s => name.includes(s)) || SKIP_ENDS.some(s => name.endsWith(s))
+    const lines: string[] = []
+
+    // strip a trailing run of digits (React dedup suffix: Foo2 → Foo)
+    function cleanName(name: string): string {
+        let end = name.length
+        while (end > 0 && name[end - 1] >= '0' && name[end - 1] <= '9') end--
+        return name.slice(0, end)
+    }
+
+    function getDomDesc(fiber: any): string {
+        const el = fiber.stateNode
+        if (!(el instanceof Element))
+            return ''
+
+        const parts: string[] = []
+        const tag = el.tagName.toLowerCase()
+        const role = roleOf(el)
+        if (role)
+            parts.push(role)
+
+        const ariaLabel = el.getAttribute('aria-label') || ''
+        const text = ariaLabel || getDirectText(el)
+        if (text)
+            parts.push(`"${text.slice(0, 80)}"`)
+
+        for (const s of baseState(el)) parts.push(`[${s}]`)
+
+        return parts.join(' ')
+    }
+
+    function getComponentDomDesc(fiber: any): string {
+        let node = fiber.child
+        while (node) {
+            if (node.tag === 5)
+                return getDomDesc(node)
+            if (node.tag === 6) {
+                const text = node.memoizedProps
+                if (typeof text === 'string' && text.trim())
+                    return `"${text.trim().slice(0, 80)}"`
+            }
+            node = node.child
+        }
+        return ''
+    }
+
+    function walkFiber(fiber: any, depth: number) {
+        if (!fiber || depth > 40)
+            return
+
+        const isComponent = COMPONENT_TAGS.has(fiber.tag)
+        const rawName = fiber.type?.displayName || fiber.type?.name
+
+        if (isComponent && rawName && rawName.length > 1 && rawName[0] !== '_'
+            && !SKIP_EXACT.has(rawName) && !isSkipped(rawName)) {
+            const name = cleanName(rawName)
+            const indent = '  '.repeat(depth)
+            let desc = name
+
+            const domDesc = getComponentDomDesc(fiber)
+            if (domDesc)
+                desc += ` — ${domDesc}`
+
+            const props = fiber.memoizedProps
+            if (props?.generating)
+                desc += ' [generating]'
+            if (props?.loading)
+                desc += ' [loading]'
+
+            lines.push(`${indent}${desc}`)
+            walkChildren(fiber, depth + 1)
+        }
+        else {
+            walkChildren(fiber, depth)
+        }
+    }
+
+    function walkChildren(fiber: any, depth: number) {
+        let child = fiber.child
+        while (child) {
+            walkFiber(child, depth)
+            child = child.sibling
+        }
+    }
+
+    walkFiber(rootFiber, 0)
+    if (!lines.length)
+        return collectDomFallback()
+
+    const minIndent = Math.min(...lines.map(l => l.length - l.trimStart().length))
+    if (minIndent > 0)
+        return lines.map(l => l.slice(minIndent)).join('\n')
+    return lines.join('\n')
+}
+
+function collectDomFallback(): string {
+    const lines: string[] = []
+
+    function walk(el: Element, depth: number) {
+        if (depth > 12)
+            return
+        const tag = el.tagName.toLowerCase()
+        if (SKIP_TAGS.has(tag))
+            return
+        if (tag === 'svg') {
+            lines.push(`${'  '.repeat(depth)}img: [svg]`)
+            return
+        }
+
+        const role = roleOf(el)
+        const ariaLabel = el.getAttribute('aria-label') || ''
+        const directText = getDirectText(el)
+
+        let desc = role || tag
+        if (ariaLabel)
+            desc += `: ${ariaLabel}`
+        else if (directText)
+            desc += `: ${directText.slice(0, 80)}`
+
+        for (const s of baseState(el)) desc += ` [${s}]`
+
+        lines.push('  '.repeat(depth) + desc)
+        for (const child of el.children) walk(child, depth + 1)
+    }
+
+    walk(document.body, 0)
+    return lines.join('\n')
+}
+
+// --- Semantic DOM collector ---
+// UI-as-text: strip Tailwind atomic classes, keep only what carries meaning —
+// tag, role, semantic classes, data-*/aria, text, interactive state, a usable selector.
+
+// Tailwind atomic-class prefixes. A class is "noise" if it starts with one of
+// these (with - or end), or contains a variant separator (hover:, md:, dark:).
+const TW_PREFIXES = new Set([
+    'flex',
+    'grid',
+    'block',
+    'inline',
+    'hidden',
+    'table',
+    'contents',
+    'p',
+    'px',
+    'py',
+    'pt',
+    'pb',
+    'pl',
+    'pr',
+    'm',
+    'mx',
+    'my',
+    'mt',
+    'mb',
+    'ml',
+    'mr',
+    'w',
+    'h',
+    'min',
+    'max',
+    'size',
+    'gap',
+    'space',
+    'text',
+    'font',
+    'leading',
+    'tracking',
+    'whitespace',
+    'truncate',
+    'break',
+    'bg',
+    'border',
+    'rounded',
+    'ring',
+    'shadow',
+    'outline',
+    'divide',
+    'opacity',
+    'items',
+    'justify',
+    'self',
+    'place',
+    'content',
+    'order',
+    'col',
+    'row',
+    'absolute',
+    'relative',
+    'fixed',
+    'sticky',
+    'static',
+    'top',
+    'bottom',
+    'left',
+    'right',
+    'z',
+    'inset',
+    'overflow',
+    'overscroll',
+    'cursor',
+    'select',
+    'pointer',
+    'resize',
+    'scroll',
+    'transition',
+    'duration',
+    'ease',
+    'delay',
+    'animate',
+    'transform',
+    'translate',
+    'rotate',
+    'scale',
+    'skew',
+    'origin',
+    'fill',
+    'stroke',
+    'object',
+    'aspect',
+    'basis',
+    'shrink',
+    'grow',
+    'flex',
+    'antialiased',
+    'uppercase',
+    'lowercase',
+    'capitalize',
+    'italic',
+    'underline',
+    'line',
+    'list',
+    'align',
+    'backdrop',
+    'blur',
+    'brightness',
+    'contrast',
+    'saturate',
+    'invert',
+    'sepia',
+    'grayscale',
+])
+
+function isNoiseClass(cls: string): boolean {
+    if (cls.includes(':')) // variant: hover:, md:, dark:, group-hover:
+        return true
+    if (cls[0] === '[') // arbitrary value: [mask-type:luminance]
+        return true
+    const head = cls.split('-')[0]
+    return TW_PREFIXES.has(head)
+}
+
+export function semanticClasses(el: Element): string {
+    const cls = el.getAttribute('class')
+    if (!cls)
+        return ''
+    return cls.split(' ').map(c => c.trim()).filter(c => c && !isNoiseClass(c)).slice(0, 6).join('.')
+}
+
+// data-insp-path looks like "src/features/Sidebar/index.tsx:78:17:App"
+// → compact to "Sidebar/index.tsx:78" (last dir + file + line)
+export function compactInsp(raw: string): string {
+    if (!raw)
+        return ''
+    const segs = raw.split(':')
+    const tail = segs[0].split('/').slice(-2).join('/')
+    return segs[1] ? `${tail}:${segs[1]}` : tail
+}
+
+export function inspPath(el: Element): string {
+    return compactInsp(el.getAttribute('data-insp-path') || '')
+}
+
+// Full path + line (drop the :col:Name suffix) — for the click-to-source popover, where the
+// whole point is reading exactly which file you'll jump into.
+export function fullInsp(raw: string): string {
+    if (!raw)
+        return ''
+    const segs = raw.split(':')
+    return segs[1] ? `${segs[0]}:${segs[1]}` : segs[0]
+}
+
+// The owner ladder: who *rendered* this element, with each component's source location.
+// data-insp-path on a host node is its DEFINITION point (where <button> is written). But the
+// element you usually want to edit is the component that placed it — its owner. React's dev
+// fiber keeps `_debugOwner` (the component whose render produced this element) even in React 19,
+// where _debugSource / __source are gone. So we walk the owner chain for the component NAMES,
+// and recover each owner's source location from the first host in its render subtree (that host
+// carries the babel-stamped data-insp-path = the component's own definition file:line). The
+// result is a climbable ladder: [leaf, NavItem, SidebarNav, …]. level 0 = the host itself.
+function fiberOf(el: Element): { _debugOwner?: unknown, _debugStack?: unknown } | null {
+    for (const k in el) {
+        if (k.startsWith('__reactFiber$'))
+            return (el as unknown as Record<string, never>)[k]
+    }
+    return null
+}
+
+// React 19 dropped _debugSource, but each dev fiber keeps `_debugStack` — an Error captured at
+// jsxDEV() time. Its first user (/src/, non-node_modules) frame is the line where THIS element's
+// JSX tag is written: the call site. For the <ActionBtn/> fiber that frame is Sidebar:554 — where
+// the developer wrote it, which is what you want to edit (not ActionBtn's own definition).
+// Returns "src/…/file.tsx:line:col" (origin + ?t= HMR query stripped), or '' if no user frame.
+function ownerCallSite(fiber: { _debugStack?: unknown }): string {
+    const ds = fiber?._debugStack as { stack?: string } | string | undefined
+    const stack = !ds ? '' : typeof ds === 'string' ? ds : (ds.stack || '')
+    if (!stack)
+        return ''
+    for (const line of stack.split('\n')) {
+        if (line.includes('node_modules'))
+            continue
+        const at = line.indexOf('/src/')
+        if (at < 0)
+            continue
+        let seg = line.slice(at + 1)            // "src/…/file.tsx?t=1:554:20" maybe trailing ')'
+        const close = seg.indexOf(')')
+        if (close >= 0)
+            seg = seg.slice(0, close)
+        const q = seg.indexOf('?')              // strip HMR ?t=… query before :line:col
+        if (q >= 0) {
+            const colon = seg.indexOf(':', q)
+            seg = seg.slice(0, q) + (colon >= 0 ? seg.slice(colon) : '')
+        }
+        return seg
+    }
+    return ''
+}
+
+// _debugStack line:col are in Vite-TRANSFORMED coordinates: the served module is rewritten by
+// babel (source-loc stamping) + the mobx plugin, inflating Sidebar/index.tsx from 533 source lines
+// to 1077. So a raw frame like ":554" is a real position in the served file but a nonexistent line
+// in the source — opening it lands nowhere. Each served module carries an inline sourcemap; we
+// fetch it once per file, decode the VLQ mappings (no regex — charcode scan per the repo rule), and
+// map transformed (line,col) back to the source (line,col). Verified live: transformed 554:20 →
+// source 312:16 = `<ActionBtn`, 881:33 → 460:20 = `<ChatList />`.
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+function decodeVlq(seg: string): number[] {
+    const out: number[] = []
+    let shift = 0
+    let value = 0
+    for (const ch of seg) {
+        let digit = B64.indexOf(ch)
+        if (digit < 0)
+            break
+        const cont = digit & 32
+        digit &= 31
+        value += digit << shift
+        if (cont) {
+            shift += 5
+        }
+        else {
+            const neg = value & 1
+            value >>= 1
+            out.push(neg ? -value : value)
+            value = 0
+            shift = 0
+        }
+    }
+    return out
+}
+
+// Decoded mappings as line → sorted [genCol, srcLine, srcCol][], original (0-based) coords.
+const mapCache = new Map<string, Promise<Array<Array<[number, number, number]>>>>()
+
+async function loadMappings(modUrl: string): Promise<Array<Array<[number, number, number]>>> {
+    const txt = await (await fetch(modUrl)).text()
+    const key = 'sourceMappingURL=data:application/json;base64,'
+    const at = txt.lastIndexOf(key)
+    if (at < 0)
+        return []
+    const b64 = txt.slice(at + key.length).trim()
+    const map = JSON.parse(atob(b64)) as { mappings: string }
+    let srcLine = 0
+    let srcCol = 0
+    return map.mappings.split(';').map((line) => {
+        let genCol = 0
+        const segs: Array<[number, number, number]> = []
+        for (const seg of line.split(',')) {
+            if (!seg)
+                continue
+            const d = decodeVlq(seg)
+            genCol += d[0]
+            if (d.length >= 4) {
+                srcLine += d[2]
+                srcCol += d[3]
+                segs.push([genCol, srcLine, srcCol])
+            }
+        }
+        return segs
+    })
+}
+
+// Map a "src/…/file.tsx:line:col" (transformed coords) to source coords via the module's inline
+// sourcemap. Returns the same shape; falls back to the input unchanged when no map / no mapping.
+async function mapToSource(raw: string): Promise<string> {
+    const segs = raw.split(':')
+    const file = segs[0]
+    const genLine = Number(segs[1])
+    const genCol = Number(segs[2]) || 0
+    if (!file || !genLine)
+        return raw
+    if (!mapCache.has(file))
+        mapCache.set(file, loadMappings(`/${file}`).catch(() => []))
+    const lines = await mapCache.get(file)!
+    const row = lines[genLine - 1]
+    if (!row || !row.length)
+        return raw
+    // largest genCol ≤ target (least-upper-bound style): the segment covering this column
+    let best = row[0]
+    for (const s of row) {
+        if (s[0] <= genCol)
+            best = s
+        else break
+    }
+    return `${file}:${best[1] + 1}:${best[2]}`
+}
+
+export interface LadderRung { name: string, raw: string }
+
+// The owner ladder: who *placed* this element, climbing the chain, each rung pointing at its CALL
+// SITE (where its <Tag/> is written). data-insp-path on a host is its definition; the element you
+// usually want to edit is where its owner component instantiated it. React 19 keeps _debugOwner
+// (the component whose render produced this element) and _debugStack (an Error captured at
+// jsxDEV → its first /src/ frame is THE call site where this element's <Tag/> is written). We walk
+// the owner chain: each rung's jump target is its own call site. Radix internals
+// (Primitive/Slot/PopperAnchor/…) have no /src/ frame → call site '' → dropped as noise. Then
+// collapse consecutive rungs sharing a call site. Result for an ActionBtn button:
+//   [div @ ActionBtn:30, ActionBtn @ Sidebar:554, ChatList @ Sidebar:881, SideBar @ App:97, App @ main:45]
+// — every rung is a real authored line, the 10-row Radix mess gone, ActionBtn's call site reachable.
+export function ownerLadder(el: Element): LadderRung[] {
+    const fiber = fiberOf(el)
+    const chain: LadderRung[] = [{ name: el.tagName.toLowerCase(), raw: ownerCallSite(fiber || {}) || el.getAttribute('data-insp-path') || '' }]
+    let o = fiber?._debugOwner as { type?: { displayName?: string, name?: string }, _debugOwner?: unknown, _debugStack?: unknown } | undefined
+    let guard = 0
+    while (o && guard++ < 24) {
+        const cs = ownerCallSite(o)
+        if (cs) {
+            const name = o.type?.displayName || o.type?.name || '?'
+            chain.push({ name, raw: cs })
+        }
+        o = o._debugOwner as typeof o
+    }
+    const out: LadderRung[] = []
+    for (let i = 0; i < chain.length; i++) {
+        // collapse consecutive rungs that resolve to one authored line (host + same-line owner)
+        if (i + 1 < chain.length && chain[i].raw && fullInsp(chain[i + 1].raw) === fullInsp(chain[i].raw))
+            continue
+        out.push(chain[i])
+    }
+    return out
+}
+
+// The "上层调用点": the first rung whose source FILE differs from the leaf's — i.e. where this
+// element's component was instantiated from the outside, not the component rendering its own
+// internals. For an ActionBtn button the leaf is the inner <div> (ActionBtn.tsx:30); rungs still
+// in ActionBtn.tsx (TooltipTrigger:68, …) are ActionBtn's own guts — skip them; the first rung in
+// another file is ActionBtn @ Sidebar:554, the place the developer wrote <ActionBtn/>. Used as the
+// /dom owner tag and the overlay default. Returns null when nothing escapes the leaf's file.
+export function callSite(l: LadderRung[]): LadderRung | null {
+    const leafFile = (l[0]?.raw || '').split(':')[0]
+    for (let i = 1; i < l.length; i++) {
+        if (l[i].raw && l[i].raw.split(':')[0] !== leafFile)
+            return l[i]
+    }
+    return null
+}
+
+// focused/disabled/expanded — the three states shared by every DOM describer
+function baseState(el: Element): string[] {
+    const parts: string[] = []
+    if (document.activeElement === el)
+        parts.push('focused')
+    if ((el as HTMLButtonElement).disabled)
+        parts.push('disabled')
+    if (el.getAttribute('aria-expanded') === 'true')
+        parts.push('expanded')
+    return parts
+}
+
+// Heuristic: does opening this control need a *trusted* event (realclick), not a synthetic
+// one? Synthetic dispatchEvent can't open a Radix portal popup reliably (and never a native
+// right-click menu). aria-haspopup is the W3C marker Radix puts on menu/dropdown/popover/
+// select triggers — the honest, low-false-positive signal. Tag it so the AI picks realclick
+// up front instead of discovering it by a failed synthetic click. The `?` keeps it honest:
+// a hint, not a guarantee (right-click-only handlers carry no DOM attribute, so they can't be
+// detected here — those still surface only on a miss).
+function needsTrusted(el: Element): boolean {
+    const hp = el.getAttribute('aria-haspopup')
+    return hp === 'menu' || hp === 'dialog' || hp === 'listbox' || hp === 'true'
+}
+
+function domState(el: Element): string {
+    const parts = baseState(el)
+    if (el.getAttribute('aria-selected') === 'true' || el.getAttribute('aria-checked') === 'true')
+        parts.push('selected')
+    if ((el as HTMLInputElement).value)
+        parts.push(`value="${safeValue(el).slice(0, 40)}"`)
+    if (el.hasAttribute('contenteditable'))
+        parts.push('editable')
+    // aria-activedescendant is the W3C combobox/listbox mechanism for "which option is currently
+    // highlighted" under keyboard nav — the focus stays on the input while ArrowDown/Up moves a
+    // *virtual* cursor over options (no DOM focus move). Without surfacing it, ArrowDown reports
+    // "(no state change)" though the active suggestion just moved (live: Wikipedia search combobox),
+    // blinding the agent to keyboard navigation. Resolve the pointed option's label so the focus
+    // line changes as the cursor moves — the single semantic signal, not a noisy attribute dump.
+    const activeId = el.getAttribute('aria-activedescendant')
+    const activeOpt = activeId ? document.getElementById(activeId) : null
+    if (activeOpt)
+        parts.push(`active="${elementLabel(activeOpt).slice(0, 40)}"`)
+    if (needsTrusted(el))
+        parts.push('needs-trusted?')
+    return parts.length ? ` {${parts.join(' ')}}` : ''
+}
+
+// Find the scope root: a CSS selector, or a component name matched against the
+// data-insp-path. Returns body when no scope given, null on miss.
+function scopeRoot(scope?: string, sel?: string): Element | null {
+    if (sel)
+        return document.querySelector(sel)
+    if (scope) {
+        const all = document.querySelectorAll('[data-insp-path]')
+        const lower = scope.toLowerCase()
+        for (const el of all) {
+            if ((el.getAttribute('data-insp-path') || '').toLowerCase().includes(lower))
+                return el
+        }
+        return null
+    }
+    return document.body
+}
+
+export function collectDom(scope?: string, sel?: string): string {
+    const root = scopeRoot(scope, sel)
+    if (!root)
+        return `(no element for scope="${scope || sel}")`
+    const lines: string[] = []
+
+    function walk(el: Element, depth: number) {
+        if (depth > 20)
+            return
+        const tag = el.tagName.toLowerCase()
+        if (SKIP_TAGS.has(tag))
+            return
+        if (tag === 'svg') {
+            if (el.getBoundingClientRect().width > 0)
+                lines.push(`${'  '.repeat(depth)}svg [icon]`)
+            return
+        }
+
+        const role = roleOf(el)
+        const sem = semanticClasses(el)
+        // data-* minus framework noise. data-insp-path is the source
+        // location — keep it, but compacted to its file:line tail, shown only when the
+        // node is itself meaningful (carries role/text/state), not on bare wrappers.
+        // On a secret field, redact data-* values too — an app could mirror the value into
+        // a data attr, and we never want that echoed (same stance as the value redaction).
+        // Redact a data-* value when the element is a secret field (mirrored value) OR the attr
+        // NAME itself names a secret (data-token / data-api-key) — same isSecretKey chokepoint as
+        // /state and /network. Element-level alone missed the per-attr case: a plain div carrying
+        // data-token leaked plaintext because the div isn't a sensitive input.
+        const secret = isSensitive(el)
+        const dataAttrs = Array.from(el.attributes)
+            .filter(a => a.name.startsWith('data-') && a.name !== 'data-testid' && a.name !== 'data-insp-path')
+            .map(a => a.value ? `${a.name}="${secret || isSecretKey(a.name) ? `‹redacted ${a.value.length}›` : a.value.slice(0, 30)}"` : a.name)
+            .slice(0, 3)
+        const aria = el.getAttribute('aria-label') || ''
+        const text = aria || getDirectText(el)
+        const state = domState(el)
+
+        // collapse an element whose only child is an icon → one line
+        const onlyIcon = el.children.length === 1 && el.children[0].tagName.toLowerCase() === 'svg'
+
+        // a node is meaningful if it carries semantics a layout div doesn't
+        const meaningful = !!(role || sem || dataAttrs.length || text || el.id || state || el.hasAttribute('contenteditable'))
+
+        if (meaningful) {
+            const parts = [role ? `${tag}[${role}]` : tag]
+            if (sem)
+                parts.push(`.${sem}`)
+            if (el.id)
+                parts.push(`#${el.id}`)
+            for (const d of dataAttrs)
+                parts.push(`[${d}]`)
+            if (text)
+                parts.push(`"${text.slice(0, 60)}"`)
+            if (onlyIcon)
+                parts.push('[icon]')
+            const src = inspPath(el)
+            // The component that placed this host. Its name is reliable, but its call-site LINE
+            // comes from _debugStack in TRANSFORMED coords (babel + mobx inflate the served module),
+            // and collectDom is sync so it can't fetch the sourcemap to map it back. Show name +
+            // file only — the file is correct; the precise mapped line lives in the jumpable overlay
+            // (paint/openRung map it via the inline sourcemap). Never print a transformed line here.
+            const owner = callSite(ownerLadder(el))
+            const ownerFile = owner ? (owner.raw.split(':')[0].split('/').slice(-2).join('/')) : ''
+            const ownerTag = owner && ownerFile && ownerFile !== (src.split(':')[0]) ? ` ↟${owner.name}@${ownerFile}` : (owner ? ` ↟${owner.name}` : '')
+            lines.push('  '.repeat(depth) + parts.join(' ') + state + (src ? ` @${src}` : '') + ownerTag)
+            depth += 1
+        }
+
+        if (!onlyIcon) {
+            for (const child of el.children) walk(child, depth)
+        }
+    }
+
+    walk(root, 0)
+    return lines.join('\n')
+}
+
+export function collectState(): Record<string, unknown> {
+    const stores = window.__AIPEEK_STORES__
+    if (!stores)
+        return {}
+
+    const result: Record<string, unknown> = {}
+    for (const [name, store] of Object.entries(stores)) {
+        try {
+            result[name] = boundedSnapshot(store)
+        }
+        catch {
+            result[name] = '[error]'
+        }
+    }
+    return result
+}
+
+// The point-drill twin of /dom?sel=. /state gives the overview, /state/<store> the domain;
+// both go through boundedSnapshot, which collapses every array to "Array(N)" and stops at
+// depth 3 — so a nested list (imStore.conversations) is unreachable from the bulk dump, the
+// gap that used to force a hand-rolled /eval. collectStatePath walks the *raw* live store
+// along a dotted path (no truncation during the walk, so depth is no obstacle), then expands
+// the leaf ONE level: an array becomes its bounded elements, an object its bounded fields —
+// exactly one bound deeper than where the bulk snapshot stopped. Numeric segments index
+// arrays; everything else is an object key. isSecretKey redaction still applies at the leaf.
+export function collectStatePath(path: string): { ok: boolean, value?: unknown, error?: string } {
+    const stores = window.__AIPEEK_STORES__ as Record<string, any> | undefined
+    if (!stores)
+        return { ok: false, error: 'no stores registered' }
+    const segs = path.split('.').filter(Boolean)
+    if (!segs.length)
+        return { ok: false, error: 'empty path' }
+
+    let node: unknown = stores
+    const walked: string[] = []
+    for (const seg of segs) {
+        if (node === null || typeof node !== 'object')
+            return { ok: false, error: `${walked.join('.') || '<root>'} is ${node === null ? 'null' : typeof node}, cannot read '${seg}'` }
+        const container = node as Record<string, unknown>
+        if (!(seg in container))
+            return { ok: false, error: `'${seg}' not found under ${walked.join('.') || '<root>'}` }
+        node = container[seg]
+        walked.push(seg)
+    }
+
+    // Expand the leaf one level: arrays show their (bounded) elements, objects their (bounded)
+    // fields — instead of the bulk dump's "Array(N)" / depth-3 cliff. Scalars pass through.
+    if (Array.isArray(node))
+        return { ok: true, value: node.map(el => boundedSnapshot(el)) }
+    if (node !== null && typeof node === 'object') {
+        const out: Record<string, unknown> = {}
+        for (const [k, v] of Object.entries(node as Record<string, unknown>)) {
+            if (typeof v === 'function')
+                continue
+            out[k] = isSecretKey(k) && (typeof v === 'string' || typeof v === 'number')
+                ? redactSecretValue(String(v))
+                : boundedSnapshot(v)
+        }
+        return { ok: true, value: out }
+    }
+    return { ok: true, value: node }
+}
+
+// The DOM-only view signal: a digest of the page's big structural blocks. Walk every element,
+// keep the visible ones covering >5% of the viewport, and key each by tag + quantized rect +
+// child count. A human knows "the page changed" not by reading a store but by seeing whole
+// regions get replaced — this captures exactly that, for ANY page, zero app cooperation.
+// rect is snapped to a ~16px grid so reflow jitter doesn't register; only wholesale replacement
+// (one big region's key gone, another appeared) survives the diff. Reuses rectOf/isVisible.
+const REGION_MIN_AREA_FRAC = 0.05
+const REGION_GRID = 16
+function collectRegions(): RegionDigest[] {
+    const minArea = innerWidth * innerHeight * REGION_MIN_AREA_FRAC
+    const out: RegionDigest[] = []
+    for (const el of document.querySelectorAll('*')) {
+        const r = rectOf(el)
+        if (!isVisible(r) || r.width * r.height < minArea)
+            continue
+        const tag = el.tagName.toLowerCase()
+        const q = (n: number) => Math.round(n / REGION_GRID)
+        const role = el.getAttribute('role')
+        const label = `${role || tag}, ${el.childElementCount} blocks`
+        out.push({ tag, key: `${tag}@${q(r.left)},${q(r.top)},${q(r.width)},${q(r.height)}#${el.childElementCount}`, label })
+    }
+    return out
+}
+
+// State-machine projection: collapse the whole UI to {view, modal, focus, knobs}
+// — the few variables a human reads off a washing-machine panel to act in O(1).
+// knobs are clipped to what's reachable *now*: when a modal is open, only its
+// subtree counts (the layer beneath is unclickable).
+// The state-machine projection — just the three vars that move when the UI transitions.
+// Shared by collectScreen (the /screen header) and the action handler's before/after diff.
+export function screenSnap(): ScreenSnap {
+    let view = '(unknown)'
+    try { view = window.__AIPEEK_VIEW__?.() ?? '(unknown)' } catch { /* app hook threw — keep fallback */ }
+
+    const modalEl = document.querySelector('[role="dialog"][data-state="open"]')
+    const modalTitle = modalEl
+        ? (modalEl.querySelector('h1, h2, [id^="radix"]')?.textContent || '').trim().slice(0, 40)
+        : ''
+    const modal = modalEl ? `${modalTitle || 'untitled'} @${inspPath(modalEl) || 'dialog'}` : 'none'
+
+    const active = document.activeElement
+    const focus = active && active !== document.body
+        ? `${elementLabel(active).slice(0, 30) || active.tagName.toLowerCase()} [${active.tagName.toLowerCase()}]${domState(active)}`
+        : 'none'
+
+    let domain: Record<string, unknown> = {}
+    try {
+        domain = window.__AIPEEK_SCREEN__?.() ?? {}
+    }
+    catch {
+        domain = { '[error]': '__AIPEEK_SCREEN__ threw' }
+    }
+
+    return { view, modal, focus, domain, regions: collectRegions() }
+}
+
+export function collectScreen(): string {
+    // 整页导航刚切到新文档、或空白文档时,document.body 可能尚未挂上 —— 任何 body.querySelectorAll
+    // 都会 NPE。collectScreen 在无 body 时无意义,响亮报「页面未就绪」而非崩(出口2 整页导航会撞)。
+    if (!document.body)
+        return 'page not ready (no document.body — mid-navigation or blank document)'
+    const { view, modal, focus, domain } = screenSnap()
+    // 按 store 前缀分组:键是 `store.field` 点路径,每行重复 `appUIStore.` 是纯噪音 —— store 名读一次
+    // 当组头,字段缩进列在下。无点的键(罕见)留作裸顶层行。禁正则,indexOf 取首个 '.'。
+    const domainLines: string[] = []
+    let curStore = ''
+    for (const [k, v] of Object.entries(domain)) {
+        const dot = k.indexOf('.')
+        if (dot < 0) {
+            domainLines.push(`  ${k}: ${redactDomain(k, v)}`)
+            curStore = ''
+            continue
+        }
+        const store = k.slice(0, dot)
+        if (store !== curStore) {
+            domainLines.push(`  ${store}:`)
+            curStore = store
+        }
+        domainLines.push(`    ${k.slice(dot + 1)}: ${redactDomain(k, v)}`)
+    }
+
+    const modalEl = document.querySelector('[role="dialog"][data-state="open"]')
+
+    // Group by source location. A source rendered many times is a *list* (content),
+    // not a control — collapse it to one "source ×N" line. The washing-machine
+    // panel shows "the laundry", not every garment.
+    const root = modalEl ?? document.body
+    const bySource = new Map<string, Element[]>()
+    for (const el of root.querySelectorAll(INTERACTIVE)) {
+        // reachable, not just isVisible: only list knobs a click can actually land on now —
+        // same predicate /click uses, so read and write agree (no "listed but unclickable").
+        if (!reachable(el))
+            continue
+        const loc = inspPath(el) || '?'
+        if (!bySource.has(loc))
+            bySource.set(loc, [])
+        bySource.get(loc)!.push(el)
+    }
+    const knobs: string[] = []
+    for (const [loc, els] of bySource) {
+        if (els.length > 2) {
+            knobs.push(`  ${loc} ×${els.length} (list)`)
+            continue
+        }
+        for (const el of els) {
+            const full = elementLabel(el)
+            const tag = el.tagName.toLowerCase()
+            const label = full.slice(0, 40)
+            const sem = lookupSem(el, full || `<${tag}>`)
+            const morphism = sem ? ` → ${sem.store}.{ ${sem.transitions} }` : ''
+            knobs.push(`  ${label || `<${tag}>`} [${tag}]${loc !== '?' ? ` ${loc}` : ''}${domState(el)}${morphism}`)
+        }
+        if (knobs.length >= 40)
+            break
+    }
+
+    return [
+        `view: ${view}`,
+        ...(domainLines.length ? [`domain:`, ...domainLines] : []),
+        `modal: ${modal}`,
+        `focus: ${focus}`,
+        `knobs (${knobs.length}):`,
+        ...knobs,
+    ].join('\n')
+}
+
+// 运行时旋钮采集:供 `aihand read panel --live` 的合缝(seam.ts)消费。返回每个可交互元素的
+// (label, file)—— label 走命中路同一 elementLabel(全 accname 信号),file 走 knobFile(调用点
+// 文件,共享组件正确归位)。这是 seam 的唯一真理来源:seam 不再自带弱化的内联 label/file 副本
+// (那会与 elementLabel 漂移、且按 host 定义文件 join 漏掉共享组件旋钮)。挂到 window 供 /eval 抠。
+export function collectKnobs(): Array<{ label: string, files: string[], tag: string }> {
+    const out: Array<{ label: string, files: string[], tag: string }> = []
+    for (const el of document.querySelectorAll(INTERACTIVE)) {
+        if (!reachable(el))
+            continue
+        const label = elementLabel(el)
+        if (!label)
+            continue
+        // The static knob's filePath is where its on* handler is WRITTEN — which is one of two
+        // files depending on how the developer wrote it, and the runtime can't tell which:
+        //   - inline host (`<button onClick>` in Sidebar): handler is on the leaf → LEAF file.
+        //   - shared component (`<ActionBtn onClick>` in MsgItem): handler is a prop on the
+        //     <ActionBtn> call → the OWNER CALL-SITE file (the leaf is ActionBtn's inner div,
+        //     whose insp-path is ActionBtn.tsx, useless for the join).
+        // callSite over-climbs the inline case (NavItem's leaf is in Sidebar but callSite jumps
+        // to App), and the leaf file misses the shared case. Rather than guess, emit BOTH as join
+        // candidates — the static panel is the oracle; whichever file it recorded, the join finds.
+        const files = [...new Set([knobFile(el, 'leaf'), knobFile(el, 'callsite')].filter(f => f && f !== '?'))]
+        out.push({ label, files, tag: el.tagName.toLowerCase() })
+    }
+    return out
+}
+// Expose for the seam's /eval probe (read panel --live). On window so a self-contained eval
+// string can reach the canonical collector instead of forking a weaker label/file derivation.
+;(window as any).__aihandCollectKnobs = collectKnobs
+
+// 界面字符画的采集半:DOM 包含树 → Region 树(纯渲染半 renderCanvas 在 core/canvas.ts)。
+// 代替视觉 —— 把人眼看到的结构(侧边栏哪些按钮、主区几条消息、输入框、disabled 态)摊成
+// AI 一眼可读的嵌套框。语义结构优先(用户拍板):区域边界 = DOM 语义 landmark 的包含关系,
+// 零 getBoundingClientRect 几何 —— 留在数学端(离散可枚举),不掉进像素坍缩。
+//
+// landmark = 有语义的容器:role / nav·main·header·footer·aside·form·dialog / 带 aria-label。
+// 布局 div(无语义)被穿透,孩子上提到最近的 landmark 祖先 —— 同 selection.ts 穿透 TRANSPARENT。
+const LANDMARK_TAGS = new Set(['nav', 'main', 'header', 'footer', 'aside', 'form', 'dialog', 'section'])
+
+function isLandmark(el: Element): boolean {
+    const tag = el.tagName.toLowerCase()
+    if (LANDMARK_TAGS.has(tag))
+        return true
+    const role = el.getAttribute('role') || ''
+    if (role && role !== 'button' && role !== 'link' && role !== 'textbox' && role !== 'listitem')
+        return true
+    return false
+}
+
+// 区域名:只取「人给的名字」(aria-label 或首个 heading 文本),如「角色设置」。
+// 没有人给的名字就返回空 —— 摆位本身已说明这是哪栏,不写 ARIA 角色英文名(complementary/region
+// 是给屏幕阅读器的噪音,人画草图不标它)。
+function landmarkLabel(el: Element): string {
+    const named = (el.getAttribute('aria-label')
+        || (el.querySelector('h1, h2, h3, [role="heading"]')?.textContent || '')).trim()
+    return named ? named.slice(0, 24) : ''
+}
+
+// 生成 id 不是人眼读的「名字」—— radix/uuid 那种 `id-19ea…` 或 32+ 位无空格 hex/dash 串,
+// 当 label 是纯噪音。人眼看按钮看的是文字/图标,看不见 DOM id。这类 label 降级成 <tag>。
+// 禁正则:纯字符扫描 —— 单 token(无空格)+ 以 id- 开头 或 够长且只含 hex/dash/下划线。
+function isNoiseLabel(s: string): boolean {
+    if (!s || s.includes(' '))
+        return false
+    if (s.startsWith('id-') || s.startsWith('radix-') || s.startsWith('«'))
+        return true
+    if (s.length < 24)
+        return false
+    for (const ch of s) {
+        const ok = (ch >= '0' && ch <= '9') || (ch >= 'a' && ch <= 'f') || ch === '-' || ch === '_'
+        if (!ok)
+            return false
+    }
+    return true
+}
+
+// 旋钮语义:label(含状态后缀) + 态射(共用 knobSem/morphism)。供 build 装进 Box。
+// The file a knob JOINS to the static control panel on. The static side (panel.ts) records a
+// knob at the file where its on* handler is WRITTEN — for `<ActionBtn onClick={() => store.x=…}>`
+// that's the CALLER (Sidebar/index.tsx), not ActionBtn.tsx. But a host element's raw
+// data-insp-path is its DEFINITION file (ActionBtn.tsx). For any shared component (ActionBtn,
+// NavItem-as-import, …) these differ, so joining on the definition file silently misses the knob:
+// label matches, file doesn't → no `→ store.{}` morphism in /screen, ○ "not live" in --live.
+// callSite(ownerLadder) already recovers where `<Tag/>` was instantiated (the `↟` owner tag); use
+// its file. Fall back to the insp-path definition file for inline knobs (host file == handler
+// file, e.g. a raw <button onClick> written in place), where the two coincide.
+// The file a knob joins to the static control panel on, in one of three resolutions:
+//   - 'leaf'     → the host element's OWN insp-path file (where an inline `<button onClick>` is
+//                  written). Full relative path. Correct for inline knobs.
+//   - 'callsite' → the OWNER CALL-SITE file (where `<ActionBtn onClick>` is written). Full path.
+//                  Correct for shared-component knobs whose handler arrives via props.
+//   - 'compact'  → the leaf-or-callsite file in last-dir/file form (matches knob-schema's
+//                  filePath.slice(-2) key, used by /screen's knobSem lookup).
+// The static side records the handler's authored file, which is leaf OR callsite depending on how
+// the developer wrote it; the runtime can't tell which, so collectKnobs emits both candidates.
+function knobFile(el: Element, form: 'leaf' | 'callsite' | 'compact'): string {
+    const leafRaw = el.getAttribute('data-insp-path') || ''
+    if (form === 'leaf')
+        return leafRaw ? fullInsp(leafRaw).split(':')[0] : '?'
+    const cs = callSite(ownerLadder(el))
+    if (form === 'callsite')
+        return cs ? fullInsp(cs.raw).split(':')[0] : '?'
+    // compact: prefer the call-site (shared component), else the leaf — last-dir/file form.
+    const raw = cs ? cs.raw : leafRaw
+    return raw ? compactInsp(raw).split(':')[0] : '?'
+}
+
+// Look up a knob's static morphism (→ store.{…}), trying BOTH candidate files (leaf + call-site,
+// compact form) since the developer's handler file is one of them and the runtime can't tell which
+// (see collectKnobs). knobSem keys are `label file` in last-dir/file form. First hit wins.
+function lookupSem(el: Element, label: string): { transitions: string, store: string, line: number } | undefined {
+    const leafRaw = el.getAttribute('data-insp-path') || ''
+    const cs = callSite(ownerLadder(el))
+    const files = [...new Set([
+        leafRaw ? compactInsp(leafRaw).split(':')[0] : '',
+        cs ? compactInsp(cs.raw).split(':')[0] : '',
+    ].filter(Boolean))]
+    for (const f of files) {
+        const sem = knobSem[`${label} ${f}`]
+        if (sem)
+            return sem
+    }
+    return undefined
+}
+
+function knobSemOf(el: Element): { label: string, morphism: string } {
+    const tag = el.tagName.toLowerCase()
+    const raw = elementLabel(el)
+    const full = isNoiseLabel(raw) ? '' : raw
+    const sem = lookupSem(el, full || `<${tag}>`)
+    // 状态:disabled / checked / 空文本框 —— 人眼一眼看见的「这个能不能用、填没填」。
+    // domState 产 ` {a b}`(或空串),换成字符画的 ` (a b)`。纯字符切片,禁正则。
+    const st = domState(el) // ' {disabled selected}' | ''
+    const dom = st ? ` (${st.slice(2, -1)})` : ''
+    const name = full.slice(0, 40) || `<${tag}>`
+    return {
+        label: `${name}${dom}`,
+        morphism: sem ? ` → ${sem.store}.{ ${sem.transitions} }` : '',
+    }
+}
+
+// 元素几何 —— 单次 getBoundingClientRect(可见性 + axis/lane/colWidth 都复用这一次)。
+function rectOf(el: Element): DOMRect {
+    return el.getBoundingClientRect()
+}
+
+// 在视口里吗 —— 肉眼所见的物理边界。元素有盒子、且盒子和视口矩形相交才算「看得见」;
+// 滚动出去的消息肉眼看不见,草绘也不画(用户拍板的边界:视口可见,非「采样前 N 条」)。
+function isVisible(r: DOMRect): boolean {
+    if (r.width <= 0 || r.height <= 0)
+        return false
+    return r.bottom > 0 && r.right > 0 && r.top < innerHeight && r.left < innerWidth
+}
+
+// 元素自己的直接文本(不含后代 —— 后代由递归各自成行,保留肉眼看到的层次,不拼平)。
+// getDirectText 已是「只取直接 TEXT_NODE」,这里复用。
+function ownText(el: Element): string {
+    const aria = el.getAttribute('aria-label') || ''
+    return (aria || getDirectText(el)).trim()
+}
+
+const MAX_CANVAS_COLS = 160 // 与 canvas.ts MAX_COLS 一致:整页降采样到 ≤160 列
+const MAX_CANVAS_ROWS = 80 // 与 canvas.ts MAX_ROWS 一致:画布行高上限
+// 一画布行 ≈ N 真实像素高。28:行现在是真 2D 高度(纵向 gap 成空行),要比旧 48 更细的分辨率
+// —— round(199/28)=7 高 bot 气泡、round(44/28)=2 矮 user 气泡,高矮分明又不炸满屏。
+const PX_PER_ROW = 28
+// 一字符列 ≈ N 真实像素宽,使整页 innerWidth 映射到 ≤MAX_CANVAS_COLS 列。≈7.17 @1148px。
+function colScale(): number {
+    return Math.max(innerWidth, 1) / MAX_CANVAS_COLS
+}
+
+// 把绝对 DOMRect 降采样成「相对父框内壁」的整数网格矩形。-1 抵父边框(父内部原点缩进 1 格,
+// 故子贴父左壁时网格 col=0)。w/h 含 2 列/行边框。纯几何,全在采集端,renderer 零像素。
+function gridRect(child: DOMRect, parent: DOMRect): { col: number, row: number, w: number, h: number } {
+    const s = colScale()
+    return {
+        col: Math.max(0, Math.round((child.left - parent.left) / s) - 1),
+        row: Math.max(0, Math.round((child.top - parent.top) / PX_PER_ROW) - 1),
+        w: Math.max(1, Math.round(child.width / s)),
+        h: Math.max(1, Math.round(child.height / PX_PER_ROW)),
+    }
+}
+
+// 行四舍五入会让相邻竖排框的下边框行 == 下一个框的上边框行,两条边框线挤成一条(读起来像框
+// 互相穿插)。对水平有重叠(同一竖列)的画框兄弟,强制下一个的 row 落到上一个底边之下,留 1 行
+// 边框带各自独立。纯整数几何,按 row 稳定排序后线性下推。横向并排的栏(不重叠)互不影响。
+function decollide(boxes: Box[]): Box[] {
+    const order = boxes.map((_, i) => i).sort((a, b) => boxes[a].row - boxes[b].row || a - b)
+    for (let i = 0; i < order.length; i++) {
+        const cur = boxes[order[i]]
+        if (!cur.drawBorder)
+            continue
+        for (let j = 0; j < i; j++) {
+            const prev = boxes[order[j]]
+            if (!prev.drawBorder)
+                continue
+            // 重叠列数 > 较窄框一半才算「真竖排撞车」;1-2 列舍入溢出(并排栏边缘擦碰)不算,
+            // 否则相邻栏因取整微叠被错误下推到对方整高之下(三栏坍成一栏)。
+            const overlap = Math.min(cur.col + cur.w, prev.col + prev.w) - Math.max(cur.col, prev.col)
+            const stacked = overlap > Math.min(cur.w, prev.w) / 2
+            if (stacked && cur.row < prev.row + prev.h)
+                cur.row = prev.row + prev.h
+        }
+    }
+    return boxes
+}
+
+// 框中心落在整页哪三分之一 → 中性方位名。不臆造语义(成员栏/详情栏),只标方位;
+// renderSemanticTree 另加 (左/中/右) band tag,这里给身份名足够 reader 区分三栏。
+export function bandLabel(col: number, w: number, rootW: number): string {
+    const center = col + w / 2
+    if (center < rootW / 3)
+        return '侧边栏'
+    if (center > (rootW * 2) / 3)
+        return '侧栏'
+    return '主区'
+}
+
+// landmark 间隙聚栏。DOM 缺 <main> 时,对话线散落框被平摊到 root 下,丢了「主内容区」这层 frame。
+// 纯几何兜底:landmark frame 没覆盖的横向区间各收成一个虚拟内容 frame,散落子框按中心归入。
+// 元真理守门:无 landmark / 全覆盖 / 空间隙 → 一框不造,老页零变化。
+const MIN_COL_GAP = 8 // 窄于此的 landmark 间缝隙不造空栏(舍入毛刺)
+export function gatherContentColumns(root: Box): void {
+    const frames = root.children.filter(c => c.kind === 'frame')
+    if (frames.length === 0)
+        return // 无 landmark:整页本就是一个内容区,不聚(零变化)
+    // 无名 landmark 补 band 名(两个无 aria/heading 的 aside 现在显示「侧边栏/侧栏」而非 <frame>)
+    for (const f of frames)
+        if (!f.label)
+            f.label = bandLabel(f.col, f.w, root.w)
+    // [0, root.w) 减去所有 covered 区间 = 补集间隙。排序后扫描,纯数值比较。
+    const covered = frames.map(f => [f.col, f.col + f.w] as [number, number]).sort((a, b) => a[0] - b[0])
+    const gaps: [number, number][] = []
+    let cursor = 0
+    for (const [lo, hi] of covered) {
+        if (lo - cursor >= MIN_COL_GAP)
+            gaps.push([cursor, lo])
+        cursor = Math.max(cursor, hi)
+    }
+    if (root.w - cursor >= MIN_COL_GAP)
+        gaps.push([cursor, root.w])
+    if (gaps.length === 0)
+        return // 全覆盖
+    const strays = root.children.filter(c => c.kind !== 'frame')
+    const newCols: Box[] = []
+    const claimed = new Set<Box>()
+    for (const [lo, hi] of gaps) {
+        const kids = strays.filter(s => {
+            const center = s.col + s.w / 2
+            return center >= lo && center < hi
+        })
+        if (kids.length === 0)
+            continue // 空间隙不造 frame
+        for (const k of kids) {
+            claimed.add(k)
+            k.col -= lo // 平移到相对新 frame 内壁
+        }
+        newCols.push({
+            kind: 'frame', col: lo, row: 0, w: hi - lo, h: root.h,
+            label: bandLabel(lo, hi - lo, root.w), morphism: '', drawBorder: true,
+            children: kids,
+        })
+    }
+    if (newCols.length === 0)
+        return
+    // 重建 root.children = landmark frames + 新虚拟栏 + 未被任何栏认领的散落框,按 col 排序
+    const leftover = strays.filter(s => !claimed.has(s))
+    root.children = [...frames, ...newCols, ...leftover].sort((a, b) => a.col - b.col)
+}
+
+// 几何偏移块 —— 复用 deriveLane 信号。窄于父 0.85 且偏移(lane≠left,即居中/靠右),
+// 或虽不偏移但明显窄于父并承载文字 = 无 CSS 框的聊天气泡。全宽块(wfrac>0.85)非气泡 → 递归。
+function isOffsetBubble(el: Element, r: DOMRect): boolean {
+    const p = el.parentElement
+    if (!p)
+        return false
+    const parent = rectOf(p)
+    if (parent.width <= 0)
+        return false
+    const wfrac = r.width / parent.width
+    if (wfrac > 0.85)
+        return false // 全宽 wrapper:递归下降到内层窄块,别抓 wrapper
+    const lane = deriveLane(el, r)
+    if (lane !== 'left')
+        return true // 居中(日期)/ 靠右(用户气泡)
+    return wfrac < 0.7 && ownText(el).length > 0 // 偏左但明显窄且有字:bot 气泡
+}
+
+// 孩子在纵向列表里的水平车道(被 isOffsetBubble 复用)。框 = el.parentElement 盒子,量相对
+// 自己 DOM 父非被上提进的 region。占满整行(wfrac>0.8)非信号。左 0.40 / 右 0.60 三分。
+function deriveLane(el: Element, child: DOMRect): 'left' | 'center' | 'right' {
+    const p = el.parentElement
+    if (!p)
+        return 'left'
+    const parent = rectOf(p)
+    if (parent.width <= 0)
+        return 'left'
+    const wfrac = child.width / parent.width
+    if (wfrac > 0.8)
+        return 'left'
+    const cx = (child.left + child.right) / 2
+    const frac = (cx - parent.left) / parent.width
+    if (frac < 0.40)
+        return 'left'
+    if (frac > 0.60)
+        return 'right'
+    return 'center'
+}
+
+// 一个元素该不该成框,成什么框。三源:landmark(栏) / interactive(旋钮) / 几何偏移块(气泡)。
+// CSS 背景/边框不成框 —— 人画草图不框脚手架,框只给内容(栏/气泡/按钮)。
+// 都不是 → null(由 emit 决定:有字成 text 叶,否则穿透递归)。
+function classify(el: Element, r: DOMRect): BoxKind | null {
+    if (isLandmark(el))
+        return 'frame'
+    if (el.matches(INTERACTIVE) && reachable(el))
+        return 'knob'
+    if (isOffsetBubble(el, r))
+        return 'bubble'
+    return null
+}
+
+// read 投影:抠正文。文本密集页(文章/评论树/README)的字符画全是导航外壳噪音,要正文得再发一轮
+// /eval 手写选择器 —— 杀掉这轮往返。DOM 找文本密度最高的主内容子树,剥导航/页脚,块边界保留串化。
+// 浏览器原生,零 app 合作(外部站 CDP 空降也跑),与字符画同源 Box 采集外的第四条渲染路。
+
+// 块级标签:每个成正文里独立一行。div 也算块(README/评论容器常用裸 div 分段);行内标签(a/span/
+// strong/em/code)不在内,它们的字并进父块行。
+const BLOCK_TAGS = new Set(['p', 'li', 'blockquote', 'tr', 'article', 'section', 'pre', 'div',
+    'h1', 'h2', 'h3', 'h4', 'h5', 'h6'])
+
+// read 的可见性 ≠ 字符画的 isVisible:字符画画「视口里」(滚动出去的不画),但读正文要整篇文档
+// —— 文章大半滚在视口外,按视口门控只剩首屏一截。read 用「在布局里」(盒子非 0×0 = 非 display:none)
+// 当门:剥掉折叠菜单/隐藏导航(0×0),保留视口外的正文。这是 read 与 visual 投影的语义分水岭。
+function isRendered(r: DOMRect): boolean {
+    return r.width > 0 && r.height > 0
+}
+
+// 页面外壳标签:nav/header/footer/aside 按 HTML 语义就是导航/页眉页脚/边栏,永不是正文 —— read
+// 整子树跳过(连 <main> 里嵌套的 <nav> 工具菜单也剥,wiki 的「What links here / Read / View source」
+// 都在 <main> 内的 <nav> 里)。这就是「剥导航/页脚/边栏」的落点,比 link-density 启发式简单且确定。
+const CHROME_TAGS = new Set(['nav', 'header', 'footer', 'aside'])
+
+// 容器渲染后代文本总字数 —— Readability 密度评分:正文容器 = 字最多的子树。跳 SKIP_TAGS(script/
+// style)和未渲染(display:none)子树,但不按视口裁(整篇文档都算,见 isRendered)。
+function descendantTextLen(el: Element): number {
+    let n = 0
+    function walk(e: Element): void {
+        const tag = e.tagName.toLowerCase()
+        if (SKIP_TAGS.has(tag) || CHROME_TAGS.has(tag) || !isRendered(rectOf(e)))
+            return
+        for (const node of e.childNodes)
+            if (node.nodeType === 3)
+                n += node.textContent?.trim().length ?? 0
+        for (const c of e.children)
+            walk(c)
+    }
+    walk(el)
+    return n
+}
+
+// 选正文根:先认语义 landmark(<main>/<article>,过 200 字门避开空壳),否则下沉到「装大部分字(≥60%)
+// 的最深容器」—— 经典 Readability「最紧的装着主体文字的容器」,天然排除小导航条(导航子树字数远低于阈)。
+// 下沉只穿包装容器(div/section/…),撞 TEXT_BLOCK(p/li/h*/…)就停 —— 段落本身是内容,再下沉会把
+// 标题/兄弟段落甩在外。一个大段落字数超阈也不能当根:它的兄弟会丢。
+const TEXT_BLOCK = new Set(['p', 'li', 'blockquote', 'tr', 'pre', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6'])
+
+export function pickReadableRoot(body: Element): Element {
+    for (const el of body.querySelectorAll('main, article, [role="main"], [role="article"]'))
+        if (descendantTextLen(el) >= 200)
+            return el
+    const total = descendantTextLen(body)
+    let best = body
+    function walk(e: Element): void {
+        for (const c of e.children)
+            if (!TEXT_BLOCK.has(c.tagName.toLowerCase()) && descendantTextLen(c) >= total * 0.6) {
+                best = c
+                walk(c)
+            }
+    }
+    if (total > 0)
+        walk(body)
+    return best
+}
+
+// 行内空白折叠:对**渲染后**文本的字节级归一(HTML 布局注入的空格/换行/nbsp → 人见单空格),
+// 非对结构化语法 pattern match —— 同 candidates.ts normWs 先例,此处正则正当。
+function collapseWs(s: string): string {
+    return s.replace(/\s+/g, ' ').trim()
+}
+
+// 块边界保留串化:DFS,每个 BLOCK_TAGS 元素的「直接文本 + 行内后代文字」成一行(撞嵌套块子节点就停,
+// 它们各自递归成行,不重复计数);heading 前缀 #;超预算尾截 + 响亮报丢弃字数(no-silent-cap)。
+export function serializeReadable(root: Element, budget: number): string {
+    const lines: string[] = []
+    // 收一个块自身的行文字:并入行内后代,撞块子节点停(留给它们自己的行)。
+    function inlineText(e: Element): string {
+        let t = ''
+        for (const node of e.childNodes) {
+            if (node.nodeType === 3)
+                t += node.textContent ?? ''
+            else if (node.nodeType === 1) {
+                const ch = node as Element
+                const ct = ch.tagName.toLowerCase()
+                if (BLOCK_TAGS.has(ct) || SKIP_TAGS.has(ct) || CHROME_TAGS.has(ct))
+                    continue
+                t += inlineText(ch)
+            }
+        }
+        return t
+    }
+    function walk(e: Element): void {
+        const tag = e.tagName.toLowerCase()
+        if (SKIP_TAGS.has(tag) || CHROME_TAGS.has(tag) || !isRendered(rectOf(e)))
+            return
+        if (BLOCK_TAGS.has(tag)) {
+            const txt = collapseWs(inlineText(e))
+            if (txt)
+                lines.push(tag[0] === 'h' && tag.length === 2 ? `# ${txt}` : txt)
+        }
+        for (const c of e.children)
+            walk(c)
+    }
+    walk(root)
+    const text = lines.join('\n')
+    if (text.length <= budget)
+        return text
+    // 头尾保留截断:limitations / conclusion / future work 永远在文末,纯头截恰好丢掉最有价值的部分
+    // (实战:arXiv Section 5「threats to validity」被 8000 头截砍掉,被迫 eval 兜底)。留头 70% + 尾 30%。
+    const head = Math.floor(budget * 0.7)
+    const tail = budget - head
+    return `${text.slice(0, head)}\n\n… +${text.length - budget} chars truncated(中段省略,已保留结尾)…\n\n${text.slice(-tail)}`
+}
+
+export function renderReadable(): string {
+    return serializeReadable(pickReadableRoot(document.body), 40000)
+}
+
+// form 决定用哪个纯渲染器投影同一棵 Box 树:tree=语义布局树(默认,eval 证帕累托最优)、
+// visual=ASCII 草图(旧默认,空间直觉对人眼好对 AI 差)、knobs=纯控制面旋钮表、read=抠正文(剥外壳)。
+// C 关系式不开口(误导率最高)。
+export function collectCanvas(form: 'tree' | 'visual' | 'knobs' | 'read' = 'tree'): string {
+    const modalEl = document.querySelector('[role="dialog"][data-state="open"]')
+    const rootEl = modalEl ?? document.body
+
+    // 等价草图:每个框按真实 (x,y,w,h) 降采样成相对父内壁的整数网格,renderer 画矩形。
+    // 单递归 + 几何停止:框宽塞得下字 → 叶(填字);塞不下且是容器 → 递归子框。三档从框宽涌现。
+    type Kid = { box: Box, el: Element }
+
+    // knob Box → 其源元素的 join 候选文件(leaf+callsite,同 collectKnobs)。Box 是纯几何不带 el,
+    // 但 @kN→{label,file} 翻译要 file 消歧同名旋钮 —— 在 build 时旁路记下,return 时与 numberKnobs 拼。
+    const knobFiles = new Map<Box, string[]>()
+
+    // 为 el 造一个框(kind 由 classify 给),坐标相对 parentRect 内壁。几何停止决定叶 or 容器。
+    function build(el: Element, r: DOMRect, parentRect: DOMRect, kind: BoxKind): Box {
+        const g = gridRect(r, parentRect)
+        const box: Box = { kind, ...g, label: '', morphism: '', drawBorder: kind !== 'text', children: [] }
+        const innerCols = box.w - 2
+
+        if (kind === 'knob') {
+            const sem = knobSemOf(el)
+            box.label = sem.label
+            box.morphism = sem.morphism
+            knobFiles.set(box, [...new Set([knobFile(el, 'leaf'), knobFile(el, 'callsite')].filter(f => f && f !== '?'))])
+            return box // 旋钮永远是叶
+        }
+        if (kind === 'text') {
+            box.label = ownText(el).slice(0, 80)
+            return box
+        }
+        // frame / bubble:有字且塞得下 → 叶填字;否则当容器递归子框。
+        // bubble 用 elementLabel(命中路同一真理)：它会下沉到包裹的 form control 的 title/value,
+        // 于是会话项(div 包 pointer-events-none input)在 /screen 显示真名而非 <bubble> —— 显示
+        // 路和 /click text= 命中路名字一致(读得出=点得中)。frame 仍走 landmark/ownText(容器名)。
+        const label = kind === 'bubble' ? elementLabel(el) : (kind === 'frame' && isLandmark(el)) ? landmarkLabel(el) : ownText(el)
+        const fits = label !== '' && innerCols >= 1 && [...label].length <= innerCols
+        if (kind === 'bubble' && fits) {
+            box.label = label
+            box.h = Math.max(box.h, 3) // 画框的带字叶需内部行放 label,h<3 会把字写到下边框上
+            return box
+        }
+        const kids: Kid[] = []
+        for (const child of el.children)
+            emit(child, kids, r)
+        if (kids.length === 0) {
+            // 无子框:landmark 头作 label,否则该框自身的文字作叶(不画空框)。
+            box.label = label.slice(0, 80)
+            return box
+        }
+        const landmark = kind === 'frame' && isLandmark(el)
+        box.label = landmark ? landmarkLabel(el) : ''
+        box.children = decollide(kids.map(k => k.box))
+        // 同心框坍缩:非 landmark 的 CSS 壳框,若无 label 且唯一子框几乎填满它(脚手架嵌套),
+        // 不画自己的墙 —— 只贡献布局,免去 │││ 同心噪音墙(元真理:墙不带信息就去掉)。
+        if (!landmark && !box.label && box.children.length === 1) {
+            const c = box.children[0]
+            if (c.drawBorder && c.w >= box.w - 3 && c.h >= box.h - 1)
+                box.drawBorder = false
+        }
+        return box
+    }
+
+    // 把 child 摊进 kids:成框 → build;svg/img → alt 文字叶;有自己的字 → text 叶;否则穿透递归。
+    function emit(el: Element, kids: Kid[], parentRect: DOMRect): void {
+        const tag = el.tagName.toLowerCase()
+        if (SKIP_TAGS.has(tag))
+            return
+        const r = rectOf(el)
+        if (tag === 'svg' || tag === 'img') {
+            const alt = (el.getAttribute('aria-label') || el.getAttribute('alt') || '').trim()
+            if (alt && isVisible(r)) {
+                const g = gridRect(r, parentRect)
+                kids.push({ box: { kind: 'text', ...g, label: alt.slice(0, 80), morphism: '', drawBorder: false, children: [] }, el })
+            }
+            return
+        }
+        if (!isVisible(r))
+            return // 视口外,肉眼看不见
+
+        const kind = classify(el, r)
+        if (kind) {
+            kids.push({ box: build(el, r, parentRect, kind), el })
+            return
+        }
+        const text = ownText(el)
+        if (text) {
+            const g = gridRect(r, parentRect)
+            kids.push({ box: { kind: 'text', ...g, label: text.slice(0, 80), morphism: '', drawBorder: false, children: [] }, el })
+            return
+        }
+        for (const c of el.children)
+            emit(c, kids, parentRect) // 穿透:孩子坐标仍相对同一父框(脚手架不占框)
+    }
+
+    const rootRect = rectOf(rootEl)
+    const root = build(rootEl, rootRect, rootRect, 'frame')
+    // root 填满画布(不画整视口框)。h 按真实高降采样,cap MAX_CANVAS_ROWS。
+    root.col = 0
+    root.row = 0
+    root.w = MAX_CANVAS_COLS
+    root.h = Math.min(MAX_CANVAS_ROWS, Math.max(1, Math.round(rootRect.height / PX_PER_ROW)))
+    root.drawBorder = false
+    root.label = ''
+    gatherContentColumns(root) // landmark 间隙聚成虚拟内容栏 + 无名 landmark 补 band 名
+    // 把同一棵 Box 树挂到 window,供实验台从 /eval 抠出,机械派生 B/C/D 形态(四形态同源,零手写)。
+    ;(window as any).__aihandScreenTree = root
+    // @kN 编号:单一权威源 numberKnobs(root),四投影都读这一份 → 号必一致(轴间对称)。
+    const refs = numberKnobs(root)
+    // 把 @kN→{label,files} 随 /screen 带回服务端,供 /action?knob=@kN 翻译。files 是 leaf+callsite
+    // 两个 join 候选(同 collectKnobs):runtime 分不清 handler 写在哪,两个都给,resolveKnob 命中任一。
+    const knobRefs: Record<string, { label: string, files: string[] }> = {}
+    for (const [box, ref] of refs)
+        knobRefs[ref] = { label: box.label, files: knobFiles.get(box) ?? [] }
+    ;(window as any).__aihandKnobRefs = knobRefs
+    return form === 'read' ? renderReadable()
+        : form === 'visual' ? renderCanvas(root, refs)
+        : form === 'knobs' ? renderKnobs(root, refs)
+        : renderSemanticTree(root, refs)
+}
+
+// Called from the action handler after the DOM has settled. The synthetic event aihand
+// just fired was captured into actionEntries by client-patch; find that entry (latest
+// synthetic) and back-fill its snapshot synchronously off the now-settled DOM — not via
+// client-patch's async 180ms stamp, which may not have run yet (Risk 1). Then render the
+// timeline anchored on it, so the model sees its own action between before/after context.
+function attachTimeline(): string {
+    const cur = [...actionEntries].reverse().find(e => !e.trusted)
+    if (cur) {
+        try { cur.view = window.__AIPEEK_VIEW__?.() ?? '(unknown)' } catch { cur.view = '(unknown)' }
+        const modalEl = document.querySelector('[role="dialog"][data-state="open"]')
+        cur.modal = modalEl ? (modalEl.querySelector('h1, h2, [id^="radix"]')?.textContent || 'untitled').trim().slice(0, 40) : 'none'
+    }
+    return formatActions([...actionEntries], cur?.ts, buffers?.actionsDropped ?? 0)
+}
+
+function boundedSnapshot(obj: unknown, depth = 0): unknown {
+    if (depth > 3)
+        return '[…]'
+    if (obj === null || obj === undefined)
+        return obj
+    if (typeof obj === 'function')
+        return undefined
+    if (typeof obj === 'string')
+        return obj.length > 100 ? `${obj.slice(0, 100)}…` : obj
+    if (typeof obj !== 'object')
+        return obj
+    if (Array.isArray(obj))
+        return `Array(${obj.length})`
+
+    const result: Record<string, unknown> = {}
+    for (const [k, v] of Object.entries(obj as Record<string, unknown>).slice(0, 20)) {
+        if (typeof v === 'function')
+            continue
+        // Redact at capture, not at echo: a secret-named field (sessionToken/apiKey/…) never
+        // crosses the wire into raw.state, so no downstream reader (/state dump, diffState) can
+        // re-leak it. The third consumer of the isSecretKey chokepoint, after DOM input + domain.
+        if (isSecretKey(k) && (typeof v === 'string' || typeof v === 'number'))
+            result[k] = redactSecretValue(String(v))
+        else
+            result[k] = boundedSnapshot(v, depth + 1)
+    }
+    return result
+}
+
+// --- HMR channel ---
+
+// Resolve once the DOM goes quiet (no mutations for `quiet`ms) or `timeout` hits,
+// then return the fresh UI tree. Lets a click/fill report its own outcome.
+// quiet=50: settle now only waits for the *state machine* (view/modal/mode) to settle — that
+// happens in the first React commit (<20ms); 50 gives streaming render a little headroom and the
+// MutationObserver resets the timer on every mutation, so a still-rendering tree extends the wait on
+// its own. Click TARGETING used to force this higher (a Radix dialog's exit-animation overlay covered
+// the next target, so a close→open sequence at low quiet hit "hit <div> on top"), but that's now
+// handled where it belongs — doClick (action.ts) waits for any covering overlay to clear before it
+// clicks. So settle no longer pays the overlay tax for every action; the floor is the state machine's.
+// Is any domain field asserting in-flight work right now? (流式中: true, isLoading: true, …)
+// Generic over the app — isBusyState is a key-level classifier, never a hard-coded field.
+function domainBusy(): boolean {
+    let dom: Record<string, unknown> = {}
+    try {
+        dom = window.__AIPEEK_SCREEN__?.() ?? {}
+    }
+    catch { return false }
+    return Object.entries(dom).some(([k, v]) => isBusyState(k, v))
+}
+
+// In-flight, action-scoped: a fetch/stream that's still open (status 0, not failed) AND was not
+// already open when the action began. Scoping to new requests excludes a pre-existing long-poll /
+// persistent stream (which stays status 0 forever and would otherwise trap the settle until the cap).
+function newInFlight(baseline: Set<NetworkRequest>): boolean {
+    return networkRequests.some(r =>
+        r.status === 0 && !r.failed
+        && (r.resourceType === 'fetch' || r.resourceType === 'eventsource')
+        && !baseline.has(r))
+}
+
+// Main thread just busy? A long task (>50ms block) only dispatches to its observer AFTER it ends,
+// so longtasks.lastEndAt is "the main thread was blocking until at least here" (page-relative ms).
+// Freshness = the last long task ended within MAIN_THREAD_FRESH_MS of now → still grinding. This is
+// the third, fully app-agnostic signal: PerformanceObserver('longtask') is a browser native, needs
+// ZERO app cooperation (unlike domainBusy, which reads the app-injected __AIPEEK_SCREEN__ hook). It
+// covers the one gap the other two miss — a compute flow with NO network and NO domain field: an
+// IndexedDB query, a Worker round-trip, a heavy synchronous render pass. On a bare app with no hook
+// and no fetch, this is the only thing that still says "working".
+const MAIN_THREAD_FRESH_MS = 120
+function mainThreadBusy(): boolean {
+    if (!perfBuffer) return false
+    const last = perfBuffer.longtasks.lastEndAt
+    if (!last) return false
+    return performance.now() - last < MAIN_THREAD_FRESH_MS
+}
+
+// True while an async flow is still running — the settle terminus for a flow. Three generic signals,
+// gapless together: (1) a NEW request in flight covers send→response-start, the false-silence gap
+// where the DOM is quiet but the first token hasn't arrived; (2) a busy domain field (流式中/isLoading…)
+// covers response-start→done, where the body streams without a fetch state change; (3) a fresh long
+// task covers a no-network, no-domain compute flow (IndexedDB / Worker / heavy render) that neither
+// (1) nor (2) can see. None hard-codes an app field. The fetch wrapper flips status to the real code
+// the moment headers arrive, so signal (1) is exactly the pre-stream window, not the whole stream.
+function flowInFlight(baseline: Set<NetworkRequest>): boolean {
+    return domainBusy() || newInFlight(baseline) || mainThreadBusy()
+}
+
+// onFrame: same MutationObserver, one extra exit. When the caller wants to trace an async flow
+// (send a message → think → stream → done), it passes onFrame; we sample screenSnap() on every
+// DOM-change burst — the trajectory's frames, each stamped with ms since the action began.
+//
+// The hard part is the settle TERMINUS for an async flow. "DOM quiet for `quiet`ms" is the right
+// terminus for a synchronous action, but WRONG mid-flow: after Enter the input clears (one DOM burst)
+// then the DOM falls silent for ~700ms while the network fetches the first token — a *false* rest. So
+// in flow mode the terminus is the STATE MACHINE, not the DOM: stable = DOM quiet ∧ ¬flowInFlight,
+// where flowInFlight = a busy domain field truthy (流式中…, covers the streaming phase) OR a new
+// request still open (covers send→first-token). A short CONFIRM window bridges action→fetch-dispatch.
+// A synchronous action passes no onFrame: none of this runs, the old DOM-quiet terminus holds.
+// The unified post-action terminal: settle the DOM, sample the async trajectory, return the
+// compact `changed` delta + `flow` trace. All three mutating paths (DOM action / knob / semantic)
+// share it — none re-implements frame collection. The caller snapshots `before` + the four buffers
+// and runs the mutator itself (performAction / executeKnob / fn()), then hands the post-mutation
+// settle here. `progress(id, kind?)` is the throttled server-deadline ping (so a multi-second flow
+// keeps the handler alive); a synchronous write just yields [before, after] → traceFlow returns []
+// → no flow line, zero overhead. One terminal, no second copy to drift (the knob path was a
+// byte-for-byte duplicate of the action path; the semantic path had none — both collapse here).
+async function settleAndTrace(
+    before: ScreenSnap,
+    beforeConsole: LogEntry[],
+    beforeNetwork: NetworkRequest[],
+    beforeErrors: ErrorEntry[],
+    progress: () => void,
+    actionKind = '',
+): Promise<{ changed: string, flow?: string }> {
+    const frames: { snap: ScreenSnap, t: number }[] = [{ snap: before, t: 0 }]
+    let lastPing = 0
+    const ping = () => {
+        const now = performance.now()
+        if (now - lastPing < 750)
+            return
+        lastPing = now
+        progress()
+    }
+    // Baseline = requests already in flight BEFORE the mutator fired (from the pre-act buffer), so
+    // the action's own synchronously-dispatched request counts as new-in-flight — the send→first-
+    // token signal — not pre-existing.
+    const preBaseline = new Set(beforeNetwork.filter(r => r.status === 0 && !r.failed))
+    await waitForStable(50, 2000, (snap, t) => {
+        frames.push({ snap, t })
+        ping()
+    }, ping, preBaseline, actionKind)
+    const after = screenSnap()
+    // after is the post-settle snap; the last onFrame fired ~quiet ms before this, so any final
+    // domain move is usually already captured. Append after at the last frame's time (its diff vs
+    // that frame is empty when they agree → traceFlow skips it, no dup line).
+    frames.push({ snap: after, t: frames[frames.length - 1].t })
+    const d = diffState(
+        { ui: '', console: beforeConsole, network: beforeNetwork, errors: beforeErrors, state: {}, url: '', timestamp: 0 },
+        { ui: '', console: [...consoleLogs], network: [...networkRequests], errors: [...errorEntries], state: {}, url: '', timestamp: 0 },
+    )
+    const changed = diffScreen(before, after, d.newErrors, d.newExceptions, d.newFailedRequests)
+    const flow = traceFlow(frames)
+    return { changed: changed.length ? changed.join('\n') : '(no state change)', flow: flow.length ? flow.join('\n') : undefined }
+}
+
+function waitForStable(quiet = 50, timeout = 2000, onFrame?: (snap: ScreenSnap, t: number) => void, onProgress?: () => void, preBaseline?: Set<NetworkRequest>, actionKind = ''): Promise<string> {
+    return new Promise((resolve) => {
+        const start = performance.now()
+        // Two caps: the normal short bound until a flow is actually confirmed, and a long bound once
+        // one is (a real stream can run tens of seconds). Without this split, a busy-but-flowless DOM
+        // (a settings dialog's spinner mutating forever) would hold every action open for the long cap
+        // and blow the server deadline. flowSeen latches true the first time flowInFlight reads true.
+        const SHORT_CAP = timeout
+        const LONG_CAP = 30000
+        let flowSeen = false
+        const cap = () => (onFrame && flowSeen ? LONG_CAP : SHORT_CAP)
+        // A busy domain field that has gone true→false = a flow that ran and FINISHED. The long
+        // CONFIRM_PREP window exists only to wait out an async prep period whose fetch hasn't dispatched
+        // yet (unobservable: no request, no busy field, idle on I/O). Once a busy field has opened and
+        // closed, that premise is falsified — the flow is over, not pending — so the confirm window can
+        // collapse back to BASE and return promptly instead of taxing the full PREP wait. This precisely
+        // excludes the send-prep case: at input-clear time 流式中 is still false (never opened), so a
+        // pre-dispatch transition there does NOT latch this and the long window holds. Latched in the
+        // observer/settle below by sampling domainBusy() each tick.
+        let busyOpened = false
+        let flowClosed = false
+        // Requests already open when the action begins — excluded from the in-flight flow signal so a
+        // persistent stream / long-poll doesn't keep us waiting. Only requests dispatched *by* this
+        // action count toward "still in flight". The caller passes a baseline captured BEFORE the
+        // action fired (preBaseline): an action's own request often dispatches synchronously during
+        // act(), so a baseline captured here (after act) would already contain it and wrongly exclude
+        // it — making the send→first-token in-flight window invisible. Fall back to now if absent.
+        const baseline = preBaseline ?? new Set(networkRequests.filter(r => r.status === 0 && !r.failed))
+        // Settle-confirm window: an action that triggers a flow dispatches its fetch a few ms after
+        // the DOM settles. Hold a short window so a not-yet-issued request can register before we
+        // call it done. Far cheaper than blindly waiting out a whole first-token delay — the real
+        // first-token gap is covered by the in-flight fetch signal (flowInFlight), not by waiting.
+        //
+        // But the dispatch latency is NOT a fixed "few ms": an app may do async prep before the
+        // request leaves — read history from IndexedDB, compress, compose the body — so the fetch
+        // lands a second or more after the DOM fell quiet, with NOTHING observable in between (no
+        // request yet, no busy field yet, the main thread idle on async I/O). A flat 400ms confirm
+        // misses those flows; a flat 2.5s confirm would tax EVERY sync action by 2.5s. The generic
+        // tell that "a flow is being prepared" is a long task fired since the action began — the
+        // prep's synchronous CPU burst (serialize/compress) shows up as one. It's browser-native and
+        // app-agnostic (PerformanceObserver('longtask'), no app field). So the confirm window is
+        // dynamic: CONFIRM_BASE for a sync action, CONFIRM_PREP once a post-action long task proves
+        // prep is underway. A pure sync action (no long task, no follow-up) still returns at BASE.
+        //
+        // BASE is NOT a "wait for a possibly-slow flow" budget — that's PREP's job, gated on the
+        // longtask precursor. BASE only has to outlast the gap between DOM-settle and a request that
+        // dispatches a tick or two later (a .then()/microtask after the click handler), so the
+        // in-flight signal can catch it. A synchronously-dispatched request is already visible to
+        // newInFlight when settle begins (it fired inside act()'s call stack); only a deferred-by-a-
+        // -microtask dispatch needs any wait at all, and that lands within ~100ms. 400ms was paying a
+        // flow-sized tax on EVERY sync action (tab switch, panel toggle) that never dispatches anything
+        // — the dominant case. 120ms covers the microtask-deferred dispatch and cuts the common sync
+        // action from ~480ms to ~170ms. A real slow-prep flow is unaffected: it trips sawPrep → PREP.
+        // hover and fill share a *timer-gated reveal* that lands after a sync action would return:
+        //   · hover — a dwell-gated tooltip/preview/menu fires from a setTimeout (~300-600ms) with
+        //     NO longtask and NO request until then (live: Wikipedia page-preview ~500ms dwell).
+        //   · fill — typing into a search/combobox box almost always kicks a *debounced* suggestion
+        //     fetch (~150ms debounce + XHR + render → dropdown lands ~300-500ms later). On exit-2 the
+        //     parachute probe never wraps window.fetch, so newInFlight is structurally dead on
+        //     external sites — the reveal is invisible to the network signal and arrives as a pure
+        //     DOM mutation after the debounce. With a 120ms base, settle returns "(no state change)"
+        //     before the dropdown even fetches (live: Wikipedia autocomplete missed entirely),
+        //     forcing the agent to guess-and-/screen — the exact extra-roundtrip class hover fixed.
+        // Both fire from a setTimeout, no CPU burst (sawPrep stays false) and no observable request,
+        // so neither BASE nor PREP would otherwise extend the window. A base long enough to outlast
+        // the timer to its FIRST mutation closes both; once that fires the quiet-loop takes over.
+        // Matches the wait to the action's known semantics — no tax on click/press.
+        const CONFIRM_BASE = actionKind === 'hover' || actionKind === 'fill' ? 700 : 120
+        const CONFIRM_PREP = 2500
+        // A long task whose end is after this settle began = the action kicked off CPU work → likely
+        // preparing an async request. lastEndAt is page-relative ms, same clock as `start`.
+        const sawPrep = () => !!perfBuffer && perfBuffer.longtasks.lastEndAt > start
+        // PREP only while a flow might still be PENDING. Once a busy field has opened and closed
+        // (flowClosed), the flow already finished — collapse to BASE so a fast async op (open→fetch→
+        // loading:false in 165ms) returns promptly instead of taxing the full 2.5s prep wait.
+        const trackBusy = () => {
+            if (!onFrame) return
+            if (domainBusy()) busyOpened = true
+            else if (busyOpened) flowClosed = true
+        }
+        const confirmWindow = () => (onFrame && sawPrep() && !flowClosed ? CONFIRM_PREP : CONFIRM_BASE)
+        let timer = 0
+        let observer: MutationObserver
+        const elapsed = () => performance.now() - start
+        const done = () => {
+            observer.disconnect()
+            clearTimeout(timer)
+            resolve(collectUI())
+        }
+        // Called when the DOM has been quiet for `quiet`ms. In flow mode this is a *candidate*
+        // terminus, vetoed while the state machine is busy, a request is in flight, or we're still
+        // inside the brief confirm window that lets a just-dispatched request appear.
+        const settle = () => {
+            // sawPrep latches flowSeen: a post-action long task is evidence a flow is being prepared,
+            // so the cap must already be the long one (else SHORT_CAP=2000 would kill a >2s prep before
+            // its fetch ever dispatches — the outer gate fires done() first). Treat prep like in-flight
+            // for cap/ping purposes; the confirmWindow below still bounds how long we wait for nothing.
+            if (onFrame && sawPrep())
+                flowSeen = true
+            trackBusy()
+            if (onFrame && elapsed() < cap()) {
+                if (flowInFlight(baseline)) {
+                    flowSeen = true
+                    // Work in flight (busy domain field truthy, or a fetch/stream still open). Poll
+                    // until it clears — a stream updates React state without a body mutation we'd see.
+                    // Ping each poll: a flow can wait seconds with no DOM mutation (network pending),
+                    // so the server's action deadline must be extended from here, not only on frames.
+                    onProgress?.()
+                    timer = window.setTimeout(settle, quiet)
+                    return
+                }
+                if (elapsed() < confirmWindow()) {
+                    // Nothing in flight yet, but a flow's request may be moments from dispatch — the
+                    // window stretches to CONFIRM_PREP if a long task already proved prep is underway.
+                    // Ping too: the prep wait itself can outlast the server's base deadline.
+                    onProgress?.()
+                    timer = window.setTimeout(settle, quiet)
+                    return
+                }
+            }
+            done()
+        }
+        observer = new MutationObserver(() => {
+            clearTimeout(timer)
+            if (flowInFlight(baseline))
+                flowSeen = true
+            trackBusy()
+            try {
+                onFrame?.(screenSnap(), elapsed())
+            }
+            catch {}
+            if (elapsed() > cap())
+                done()
+            else
+                timer = window.setTimeout(settle, quiet)
+        })
+        observer.observe(document.body, { childList: true, subtree: true, attributes: true, characterData: true })
+        timer = window.setTimeout(settle, quiet)
+    })
+}
+
+// Multi-tab: the HMR channel broadcasts to every open tab. Only the tab the user
+// is actually looking at should answer — otherwise server races N responses and
+// keeps a random one, while click/fill fire in *all* tabs. visibilityState is
+// 'visible' for exactly the focused tab (or single tab), 'hidden' for the rest.
+//
+// But when the user is reading the terminal, EVERY dev tab is hidden — then no one
+// would answer. So the server sends requireVisible=true first; if it times out with
+// no answer it retries requireVisible=false, and every tab answers (the original
+// race). `skip` collapses that into one guard: hidden tab skips only round one.
+function skip(msg?: { requireVisible?: boolean, tab?: string }) {
+    if (msg?.tab) // addressed by id: only that tab answers, regardless of visibility (incl. background)
+        return msg.tab !== TAB_ID
+    return msg?.requireVisible !== false && document.visibilityState !== 'visible'
+}
+
+// Click-to-source overlay. Hold Alt or Ctrl and the element under the cursor gets a highlight
+// box + a `file:line` label; click opens it in the editor via GET /__aihand/open. Reads the
+// raw data-insp-path the source-loc babel plugin stamps on host elements — the same attribute
+// /dom and /screen consume. This is the human-facing half of aihand (the AI never holds a
+// modifier, so its synthetic clicks never trigger this).
+function installClickToSource() {
+    // HMR re-runs this module; without a guard each reload adds another set of mousemove/click
+    // listeners (and a fresh closure with its own card), so you'd see one overlay per reload —
+    // the stale dark card + the new one. A window flag makes installation idempotent.
+    const w = window as { __aihand_click_to_source__?: boolean }
+    if (w.__aihand_click_to_source__)
+        return
+    w.__aihand_click_to_source__ = true
+
+    let root: HTMLDivElement | null = null
+    let parts: Record<string, HTMLDivElement> = {}
+    let card: HTMLDivElement | null = null
+    let tip: Record<string, HTMLElement> = {}
+    let armed = false
+    let current: Element | null = null
+    let pinned = false
+    let ladder: LadderRung[] = []
+
+    // Chrome DevTools box-model palette: content / padding / margin in distinct tints.
+    const MARGIN = 'rgba(246,178,107,0.66)'
+    const PADDING = 'rgba(147,196,125,0.55)'
+    const CONTENT = 'rgba(111,168,220,0.66)'
+
+    const nearestInsp = (el: Element | null): Element | null => {
+        let n: Element | null = el
+        while (n && n !== document.body) {
+            if (n.getAttribute('data-insp-path'))
+                return n
+            n = n.parentElement
+        }
+        return null
+    }
+
+    // Default jump target: the call site (first rung past the host with a distinct location) —
+    // i.e. the component that wrote <ActionBtn/>, not ActionBtn's own internals. Fall back to 0.
+    const defaultLevel = (l: LadderRung[]): number => {
+        const cs = callSite(l)
+        return cs ? l.indexOf(cs) : 0
+    }
+
+    const openRung = async (rung: LadderRung | undefined) => {
+        if (!rung?.raw)
+            return
+        // map transformed → source coords (cached) so the editor opens the real line, not the
+        // inflated transformed one
+        const [file, line, column] = (await mapToSource(rung.raw)).split(':')
+        if (!file)
+            return
+        fetch(`/__aihand/open?file=${encodeURIComponent(file)}&line=${line || 1}&column=${column || 1}`)
+        clear()
+    }
+
+    // Freeze the popover: stop tracking hover, make the card clickable, and re-style the default
+    // rung as the obvious primary target. Now you can release Alt and click any rung at leisure.
+    const pin = () => {
+        if (!card)
+            return
+        pinned = true
+        card.style.pointerEvents = 'auto'
+        if (tip.hint)
+            tip.hint.textContent = 'click a row to open · esc to close'
+    }
+
+    const row = (key: string, makeValue: () => HTMLElement[]) => {
+        const r = document.createElement('div')
+        r.style.cssText = 'display:flex;align-items:center;gap:8px;justify-content:space-between'
+        const k = document.createElement('span')
+        k.textContent = key
+        k.style.cssText = 'color:#80868b'
+        const v = document.createElement('span')
+        v.style.cssText = 'display:flex;align-items:center;gap:5px;color:#202124;min-width:0'
+        v.append(...makeValue())
+        r.append(k, v)
+        return r
+    }
+
+    const ensure = () => {
+        if (root)
+            return
+        root = document.createElement('div')
+        root.style.cssText = 'position:fixed;inset:0;z-index:2147483646;pointer-events:none;overflow:hidden'
+        // Order matters: margin (outermost) painted first, content (innermost) last on top.
+        for (const k of ['mt', 'mr', 'mb', 'ml', 'pt', 'pr', 'pb', 'pl', 'content']) {
+            const d = document.createElement('div')
+            d.style.cssText = 'position:fixed;pointer-events:none'
+            parts[k] = d
+            root.append(d)
+        }
+
+        card = document.createElement('div')
+        // pointer-events:none while hovering (so it never blocks the cursor); pin() flips it to
+        // auto so the frozen popover's rungs become clickable.
+        card.style.cssText = 'position:fixed;z-index:2147483647;pointer-events:none;display:flex;flex-direction:column;gap:6px;min-width:360px;max-width:640px;background:#fff;color:#202124;font:11px/1.55 ui-monospace,SFMono-Regular,Menlo,monospace;padding:12px 14px;border:1px solid rgba(0,0,0,0.08);border-radius:8px;box-shadow:0 6px 24px rgba(0,0,0,.2)'
+
+        const header = document.createElement('div')
+        header.style.cssText = 'display:flex;align-items:baseline;gap:10px;justify-content:space-between;margin-bottom:1px'
+        tip.tag = document.createElement('span')
+        tip.tag.style.cssText = 'font-weight:700;color:#9333ea;font-size:12px'
+        tip.dim = document.createElement('span')
+        tip.dim.style.cssText = 'color:#202124;white-space:nowrap'
+        header.append(tip.tag, tip.dim)
+
+        tip.swatch = document.createElement('span')
+        tip.swatch.style.cssText = 'width:12px;height:12px;border-radius:2px;border:1px solid rgba(0,0,0,0.25);flex:none'
+        tip.color = document.createElement('span')
+        const colorRow = row('Color', () => [tip.swatch, tip.color])
+
+        tip.font = document.createElement('span')
+        tip.font.style.cssText = 'overflow:hidden;text-overflow:ellipsis;white-space:nowrap'
+        const fontRow = row('Font', () => [tip.font])
+
+        const divider = document.createElement('div')
+        divider.style.cssText = 'height:1px;background:rgba(0,0,0,0.1);margin:4px 0'
+
+        // The owner ladder: leaf host at the bottom, each owner component above. Each rung is a
+        // jump target — the number key picks it, the default (nearest component) is highlighted.
+        tip.ladder = document.createElement('div')
+        tip.ladder.style.cssText = 'display:flex;flex-direction:column;gap:2px'
+
+        tip.hint = document.createElement('div')
+        tip.hint.textContent = '⌥click to pin, then pick a row'
+        tip.hint.style.cssText = 'color:#9aa0a6;white-space:nowrap;margin-top:4px;font-size:11px'
+
+        card.append(header, colorRow, fontRow, divider, tip.ladder, tip.hint)
+        document.body.append(root, card)
+    }
+    const clear = () => {
+        root?.remove()
+        card?.remove()
+        root = card = current = null
+        pinned = false
+        ladder = []
+        parts = {}
+        tip = {}
+    }
+
+    const place = (k: string, x: number, y: number, w: number, h: number, bg: string) => {
+        const d = parts[k]
+        d.style.cssText = `position:fixed;pointer-events:none;left:${x}px;top:${y}px;width:${w}px;height:${h}px;background:${bg}`
+    }
+
+    const paint = (el: Element) => {
+        ensure()
+        const r = el.getBoundingClientRect()
+        const cs = getComputedStyle(el)
+        const m = { t: parseInt(cs.marginTop) || 0, r: parseInt(cs.marginRight) || 0, b: parseInt(cs.marginBottom) || 0, l: parseInt(cs.marginLeft) || 0 }
+        const p = { t: parseInt(cs.paddingTop) || 0, r: parseInt(cs.paddingRight) || 0, b: parseInt(cs.paddingBottom) || 0, l: parseInt(cs.paddingLeft) || 0 }
+        // Boxes in viewport coords (position:fixed → no scroll math). border-box = r.
+        const mx = r.left - m.l, my = r.top - m.t, mw = r.width + m.l + m.r
+        place('mt', mx, my, mw, m.t, MARGIN)
+        place('mb', mx, r.bottom, mw, m.b, MARGIN)
+        place('ml', mx, r.top, m.l, r.height, MARGIN)
+        place('mr', r.right, r.top, m.r, r.height, MARGIN)
+        place('pt', r.left, r.top, r.width, p.t, PADDING)
+        place('pb', r.left, r.bottom - p.b, r.width, p.b, PADDING)
+        place('pl', r.left, r.top + p.t, p.l, r.height - p.t - p.b, PADDING)
+        place('pr', r.right - p.r, r.top + p.t, p.r, r.height - p.t - p.b, PADDING)
+        place('content', r.left + p.l, r.top + p.t, r.width - p.l - p.r, r.height - p.t - p.b, CONTENT)
+
+        tip.tag.textContent = el.tagName.toLowerCase()
+        tip.dim.textContent = `${Math.round(r.width)} × ${Math.round(r.height)}`
+        const color = cs.color
+        tip.swatch.style.background = color
+        tip.color.textContent = color
+        tip.font.textContent = `${cs.fontSize} ${cs.fontFamily.split(',')[0].replaceAll('"', '')}`
+
+        // Build the climbable ladder and render one clickable row per rung. Default jump =
+        // nearest component (level 1) when there is one, else the host itself (level 0).
+        ladder = ownerLadder(el)
+        const def = defaultLevel(ladder)
+        tip.ladder.textContent = ''
+        ladder.forEach((rung, i) => {
+            const r = document.createElement('div')
+            const isDef = i === def
+            const jumpable = !!rung.raw
+            r.style.cssText = `display:flex;align-items:center;gap:8px;padding:3px 6px;border-radius:4px;${jumpable ? 'cursor:pointer;' : 'opacity:0.45;'}${isDef ? 'background:rgba(26,115,232,0.1)' : ''}`
+            const num = document.createElement('span')
+            num.textContent = String(i + 1)
+            num.style.cssText = 'color:#9aa0a6;flex:none;width:14px;text-align:right'
+            const nm = document.createElement('span')
+            nm.textContent = rung.name
+            nm.style.cssText = `flex:none;${i === 0 ? 'color:#9333ea' : 'color:#188038;font-weight:600'}`
+            const loc = document.createElement('span')
+            loc.textContent = fullInsp(rung.raw)
+            loc.style.cssText = 'color:#1a73e8;overflow:hidden;text-overflow:ellipsis;white-space:nowrap'
+            // rung.raw is in transformed coords (_debugStack); map it back to source via the
+            // module's sourcemap for display. rung.raw stays immutable (transformed) — openRung
+            // maps it again on click off the same cache, so there's no double-mapping.
+            if (rung.raw) {
+                mapToSource(rung.raw).then((mapped) => { loc.textContent = fullInsp(mapped) })
+            }
+            r.append(num, nm, loc)
+            if (jumpable) {
+                r.addEventListener('mouseenter', () => { r.style.background = 'rgba(26,115,232,0.18)' })
+                r.addEventListener('mouseleave', () => { r.style.background = isDef ? 'rgba(26,115,232,0.1)' : '' })
+                // mousedown not click: the global Alt+click handler also fires on click and would
+                // double-jump. mousedown + stopPropagation claims the gesture here, on this rung.
+                r.addEventListener('mousedown', (ev) => {
+                    ev.preventDefault()
+                    ev.stopPropagation()
+                    openRung(rung)
+                })
+            }
+            tip.ladder.append(r)
+        })
+
+        // Position the card just above the element, flipping below if it would clip the top.
+        card!.style.left = `${Math.min(r.left, innerWidth - 348)}px`
+        const cardH = card!.offsetHeight
+        const above = my - cardH - 6
+        card!.style.top = `${above < 4 ? r.bottom + m.b + 6 : above}px`
+    }
+
+
+
+    addEventListener('mousemove', (e) => {
+        // Once pinned, the popover is frozen — hover no longer repaints, so you can move the
+        // mouse to a rung and click it without the target shifting under you.
+        if (pinned)
+            return
+        armed = e.altKey && e.shiftKey
+        if (!armed) {
+            if (current)
+                clear()
+            return
+        }
+        const hit = nearestInsp(e.target as Element)
+        if (!hit) {
+            clear()
+            return
+        }
+        if (hit !== current) {
+            current = hit
+            paint(hit)
+        }
+    }, true)
+
+    addEventListener('click', (e) => {
+        // Pinned: a click is a selection. On a rung → jump there; anywhere else → dismiss.
+        if (pinned) {
+            if (card && card.contains(e.target as Node))
+                return // a rung's own mousedown handled the jump
+            e.preventDefault()
+            e.stopPropagation()
+            clear()
+            return
+        }
+        // Unpinned: Alt+Shift-click pins the popover open (release the modifiers, then pick a rung).
+        if (!(e.altKey && e.shiftKey))
+            return
+        const hit = nearestInsp(e.target as Element)
+        if (!hit)
+            return
+        e.preventDefault()
+        e.stopPropagation()
+        if (hit !== current) {
+            current = hit
+            paint(hit)
+        }
+        pin()
+    }, true)
+
+    // While the popover is open, number keys jump to that rung. macOS emits the Option-composed
+    // glyph in e.key (Alt+1 → "¡"), so match e.code ("Digit1"/"Numpad1") which is layout-stable.
+    addEventListener('keydown', (e) => {
+        if (!current || !ladder.length)
+            return
+        if (e.key === 'Escape') {
+            clear()
+            return
+        }
+        const digit = e.code.startsWith('Digit') || e.code.startsWith('Numpad') ? e.code.slice(-1) : ''
+        const n = digit >= '1' && digit <= '9' ? Number(digit) : 0
+        if (n >= 1 && n <= ladder.length && ladder[n - 1].raw) {
+            e.preventDefault()
+            openRung(ladder[n - 1])
+        }
+    }, true)
+
+    // Only an unpinned (hover) overlay tracks the modifier; a pinned popover stays put.
+    addEventListener('keyup', () => { if (current && !pinned) clear() })
+    addEventListener('blur', () => { if (current && !pinned) clear() })
+}
+
+// 探针体——transport 无关的消息处理器全集。出口1(Vite HMR)、出口2(CDP)各自把
+// 自己的双向通道包成 Transport 注入进来,体内 27 处 send 走的是同一个收敛点。返回 dispose。
+// 体内全部辅助(skip/TAB_ID/screenSnap/collectUI/settleAndTrace…)是模块作用域闭包,原样可用;
+// knobSem 也是模块级——出口1 shim 填,出口2 留空,knob-action 经它解析态射。
+export function installProbe(transport: Transport) {
+    const hot = { send: transport.send }
+    const disposers: Array<() => void> = []
+    const onMsg = (event: string, handler: (...a: any[]) => void) => {
+        disposers.push(transport.onMsg(event, handler))
+    }
+
+    onMsg('aihand:collect', (msg: { requireVisible?: boolean, tab?: string }) => {
+        if (skip(msg))
+            return
+        hot.send('aihand:state', {
+            tab: TAB_ID,
+            url: location.href,
+            title: document.title,
+            visible: document.visibilityState === 'visible',
+            ui: collectUI(),
+            console: [...consoleLogs],
+            network: [...networkRequests],
+            errors: [...errorEntries],
+            actions: [...actionEntries],
+            actionsDropped: buffers?.actionsDropped ?? 0,
+            state: collectState(),
+            performance: collectPerformance(),
+            timestamp: Date.now(),
+        })
+    })
+
+    onMsg('aihand:action', async (msg: { id: number, type: ActionType, args: ActionArgs, requireVisible?: boolean, tab?: string }) => {
+        if (skip(msg))
+            return
+        // Idempotency: the server re-broadcasts an addressed action while the tab is mid self-heal,
+        // so the same id can land twice. Execute once per id; on a repeat replay the cached result
+        // (re-settles the server's pendingActions slot if the original reply was lost in teardown).
+        const done = (window.__AIPEEK_DONE_ACTIONS__ ??= new Map<number, ActionResult>())
+        const cached = done.get(msg.id)
+        if (cached) {
+            hot.send('aihand:result', { tab: TAB_ID, id: msg.id, ...cached })
+            return
+        }
+        // Snapshot the state machine + error/network buffers *before* the action, so the
+        // post-settle diff is exactly what this action caused (see result.screen below).
+        const before = screenSnap()
+        const beforeConsole = [...consoleLogs]
+        const beforeNetwork = [...networkRequests]
+        const beforeErrors = [...errorEntries]
+        // Guard against native alert/confirm/prompt freezing the probe (see withDialogGuard).
+        const { result, dialogs } = await withDialogGuard(() => performAction(msg.type, msg.args))
+        if (dialogs.length)
+            result.detail = `${result.detail ?? ''} [auto-dismissed ${dialogs.join('; ')}]`.trim()
+        // realclick resolved to (x,y) but didn't click — synthetic events can't open a Radix
+        // ContextMenu. Fire a trusted click through whatever channel can: in Electron the page
+        // can reach the main process via electronAPI.invoke('aihand:input') → sendInputEvent;
+        // in a plain Chrome tab it can't (no chrome.debugger from page JS), so leave ui
+        // undefined and let the server drive its extension queue.
+        // realclick resolved (x,y) but synthetic events can't open a Radix ContextMenu — fire
+        // a trusted click via Electron's main process if reachable, else leave it for the
+        // server's extension queue. Either path then settles like any other mutating action.
+        const electronAPI = (window as { electronAPI?: { invoke: (channel: string, ...args: unknown[]) => Promise<unknown> } }).electronAPI
+        if (msg.type === 'realclick' && result.ok && electronAPI) {
+            await electronAPI.invoke('aihand:input', { type: 'click', button: msg.args.button ?? 'left', x: result.x, y: result.y })
+            result.fired = true // server: trusted click already fired in-process, skip the extension queue
+        }
+
+        // For mutating actions, settle the DOM then ship *only the change this action caused*
+        // (state-machine transition + new errors/failed requests), not a fresh snapshot. AI
+        // reads the delta and drills into /ui or /dom for detail if needed. The timeline still
+        // surfaces concurrent user actions. hover counts: its whole point is revealing a
+        // menu/tooltip — what it surfaces is invisible without the delta, forcing an extra
+        // /screen otherwise (same forced-roundtrip class as click's nav back-fill).
+        const mutated = msg.type === 'click' || msg.type === 'fill' || msg.type === 'press'
+            || msg.type === 'hover'
+            || (msg.type === 'realclick' && !!electronAPI)
+        if (result.ok && mutated) {
+            const { changed, flow } = await settleAndTrace(before, beforeConsole, beforeNetwork, beforeErrors,
+                () => hot.send('aihand:action-progress', { tab: TAB_ID, id: msg.id }), msg.type)
+            result.screen = changed
+            if (flow)
+                result.flow = flow
+            result.actions = attachTimeline()
+        }
+        done.set(msg.id, result)
+        if (done.size > 64)
+            done.delete(done.keys().next().value!)
+        hot.send('aihand:result', { tab: TAB_ID, id: msg.id, ...result })
+    })
+
+    // eval: run server-supplied code in the page with auto-return (see runEval).
+    onMsg('aihand:eval', async (msg: { id: number, code: string, requireVisible?: boolean, tab?: string }) => {
+        if (skip(msg))
+            return
+        const { ok, value, error, hint } = await runEval(msg.code)
+        hot.send('aihand:eval-result', { tab: TAB_ID, id: msg.id, ok, value, error, hint })
+    })
+
+    // semantic-action: the green channel. The app mounts named semantic functions on
+    // window.__AIHAND_ACTIONS__ (e.g. sendPrompt) — each is the very (store-write + real
+    // semantic fn) the button's onClick runs, minus the DOM. Calling it returns the act()
+    // delta (operation IS observation), so there's no separate /screen round-trip. Unlike
+    // /click it skips selector-resolution and disabled/covered gating entirely. A missing
+    // action name or a throw comes back as ok:false — the app declares which actions exist.
+    onMsg('aihand:semantic-action', async (msg: { id: number, name: string, args?: unknown[], requireVisible?: boolean, tab?: string }) => {
+        if (skip(msg))
+            return
+        const actions = window.__AIHAND_ACTIONS__
+        const fn = actions?.[msg.name]
+        if (!fn) {
+            const available = actions ? Object.keys(actions).join(', ') : '(app mounted no __AIHAND_ACTIONS__)'
+            hot.send('aihand:semantic-result', { tab: TAB_ID, id: msg.id, ok: false, error: `no semantic action "${msg.name}" — available: ${available || '(none)'}` })
+            return
+        }
+        // Same terminal as click/knob. A semantic action IS the store-write + real semantic fn a
+        // button's onClick runs (sendPrompt = set input + generateWithPrompt) — the prototypical
+        // async flow (send → think → stream → done). Snapshot before, run the fn, then settleAndTrace
+        // samples the full A→Δt→B→Δt→C trajectory. Previously this path bypassed settle entirely and
+        // returned the fn's own return value, so an async flow collapsed to whatever delta the fn had
+        // already computed at first await — the stream was invisible. Now the feedback axis covers
+        // every mutating path identically; no action type gets a lesser feedback contract.
+        // Arity guard: fn.length is the count of required params (defaulted/rest params don't
+        // count), so args.length < fn.length is a strict under-call — calling anyway feeds
+        // undefined into the app and crashes downstream (e.g. sendPrompt(undefined) → split of
+        // undefined). Refine that dead-end back to the recoverable cause: name the missing args
+        // before invoking. Never over-fires — optional params keep fn.length low. (Wrong param
+        // NAME like ?arg= lands here too: it's dropped at the HTTP layer, so args stays [].)
+        const argv = msg.args ?? []
+        if (argv.length < fn.length) {
+            hot.send('aihand:semantic-result', { tab: TAB_ID, id: msg.id, ok: false, error: `"${msg.name}" needs ${fn.length} arg(s), got ${argv.length}. pass args=<JSON array>, e.g. args=["…"]` })
+            return
+        }
+        const before = screenSnap()
+        const beforeConsole = [...consoleLogs]
+        const beforeNetwork = [...networkRequests]
+        const beforeErrors = [...errorEntries]
+        try {
+            await fn(...argv)
+        }
+        catch (e) {
+            hot.send('aihand:semantic-result', { tab: TAB_ID, id: msg.id, ok: false, error: e instanceof Error ? e.message : String(e) })
+            return
+        }
+        const { changed, flow } = await settleAndTrace(before, beforeConsole, beforeNetwork, beforeErrors,
+            () => hot.send('aihand:action-progress', { tab: TAB_ID, id: msg.id, kind: 'semantic' }))
+        const parts = [changed]
+        if (flow)
+            parts.push(`--- flow ---\n${flow}`)
+        hot.send('aihand:semantic-result', { tab: TAB_ID, id: msg.id, ok: true, value: parts.join('\n') })
+    })
+
+    // knob-action: the god-tier green channel. No hand-mounting — the app exposes only its store
+    // instances (__AIPEEK_STORES__); we resolve the knob's morphism from the build-time schema
+    // (knobSem) and write the store directly via executeKnob. Then we sample the resulting
+    // trajectory exactly like aihand:action does (before-frame + onFrame bursts → diffScreen +
+    // traceFlow), returning the compact `--- changed ---` delta, never a full state dump. A
+    // context-dependent morphism (executable:false) or an ambiguous/unknown label throws → ok:false
+    // with the reason; the channel never fake-replays.
+    onMsg('aihand:knob-action', async (msg: { id: number, knob: string, file?: string, value?: string, requireVisible?: boolean, tab?: string }) => {
+        if (skip(msg))
+            return
+        const fail = (error: string) => hot.send('aihand:knob-result', { tab: TAB_ID, id: msg.id, ok: false, error })
+
+        // @kN 可寻址 ref → 投影:translate(@kN→label,号取自最近一次 /screen 的 __aihandKnobRefs)+ 消歧
+        // (leaf/callsite 两候选试一遍)都在 resolveKnobRef 一处。非 @k 形(直传 label)原样走老路。
+        const refs = (window as any).__aihandKnobRefs as Record<string, { label: string, files: string[] }> | undefined
+        const resolved = resolveKnobRef(knobSem, msg.knob, refs, msg.file)
+        if (!resolved.ok) {
+            fail(resolved.error)
+            return
+        }
+        const stores = window.__AIPEEK_STORES__ as Record<string, any> | undefined
+        if (!stores) {
+            fail('app mounted no __AIPEEK_STORES__ — cannot replay a store morphism')
+            return
+        }
+
+        const before = screenSnap()
+        const beforeConsole = [...consoleLogs]
+        const beforeNetwork = [...networkRequests]
+        const beforeErrors = [...errorEntries]
+        try {
+            executeKnob(resolved.proj, msg.value === undefined ? undefined : parseLiteral(msg.value), stores)
+        }
+        catch (e) {
+            fail(e instanceof Error ? e.message : String(e))
+            return
+        }
+
+        // Same terminal as aihand:action — a knob may kick off an async flow (mode switch that
+        // lazy-loads, a toggle that fetches), so settleAndTrace samples the trajectory and pings to
+        // extend the server deadline; a synchronous write just yields [before, after] → no flow.
+        const { changed, flow } = await settleAndTrace(before, beforeConsole, beforeNetwork, beforeErrors,
+            () => hot.send('aihand:action-progress', { tab: TAB_ID, id: msg.id, kind: 'knob' }))
+        const parts = [changed]
+        if (flow)
+            parts.push(`--- flow ---\n${flow}`)
+        hot.send('aihand:knob-result', { tab: TAB_ID, id: msg.id, ok: true, value: parts.join('\n') })
+    })
+
+    onMsg('aihand:collect-dom', (msg: { scope?: string, sel?: string, requireVisible?: boolean, tab?: string }) => {
+        if (skip(msg))
+            return
+        hot.send('aihand:dom', { tab: TAB_ID, dom: collectDom(msg?.scope, msg?.sel) })
+    })
+
+    onMsg('aihand:collect-state-path', (msg: { path: string, requireVisible?: boolean, tab?: string }) => {
+        if (skip(msg))
+            return
+        hot.send('aihand:state-path', { tab: TAB_ID, ...collectStatePath(msg.path) })
+    })
+
+    onMsg('aihand:collect-screen', (msg: { requireVisible?: boolean, tab?: string, form?: 'tree' | 'visual' | 'knobs' | 'read' }) => {
+        if (skip(msg))
+            return
+        // Ship the rendered text *and* the structured snap + buffers, so the server can serve
+        // /screen?since=<token> by diffing this snap against a stashed prior one (diffScreen).
+        hot.send('aihand:screen', {
+            tab: TAB_ID,
+            screen: collectScreen(),
+            canvas: collectCanvas(msg?.form),
+            snap: screenSnap(),
+            console: [...consoleLogs],
+            network: [...networkRequests],
+            errors: [...errorEntries],
+        })
+    })
+
+    // Perf profiler handlers
+    onMsg('aihand:perf-reset', (msg: { requireVisible?: boolean, tab?: string }) => {
+        if (skip(msg))
+            return
+        resetPerf()
+        hot.send('aihand:perf-reset-ack', { tab: TAB_ID })
+    })
+
+    return () => {
+        for (const off of disposers) off()
+    }
+}
+
+// 出口1(Vite dev server)适配:把 HMR WebSocket 包成 Transport 注入 installProbe。
+// Vite 专属的一切——hello 报到、HMR socket 自愈、virtual:aihand-knobs 拉旋钮投影、
+// import.meta.hot.accept() 字面量——全留这里,绝不下沉进 installProbe(对偶出口2 没有 HMR)。
+if (import.meta.hot) {
+    const hot = import.meta.hot
+    installClickToSource()
+
+    const transport: Transport = {
+        send: (event, payload) => hot.send(event, payload),
+        onMsg: (event, handler) => {
+            hot.on(event, handler)
+            return () => hot.off(event, handler)
+        },
+    }
+
+    // virtual:aihand-knobs:knobSchema() 插件长出的 build 时旋钮投影,填进模块级 knobSem
+    // (lookupSem/collectKnobs 与 installProbe 共读同一份)。插件缺席时(测试/未注册)留空表。
+    // @ts-expect-error virtual module only resolves when knobSchema() plugin is registered
+    import('virtual:aihand-knobs').then(m => { knobSem = m.knobs }).catch(() => {})
+
+    // The probe is a side-effect-only module: it registers channel handlers + window listeners,
+    // it exports nothing. A naive HMR re-run would STACK them (a second aihand:collect handler, a
+    // second mousemove listener) — so historically this module was NOT self-accepting and every
+    // edit triggered a FULL PAGE RELOAD, which wipes the app under test (mobx stores, scroll,
+    // open dialogs). That reload is pure collateral: editing the probe shouldn't reset the page
+    // it observes. The fix decouples the two — track every registration this run, tear them all
+    // down in hot.dispose, then hot.accept so vite swaps the module in place with no reload.
+    const probeDispose = installProbe(transport)
+
+    const disposers: Array<() => void> = [probeDispose]
+    const onMsg = (event: string, handler: (...a: any[]) => void) => {
+        hot.on(event, handler)
+        disposers.push(() => hot.off(event, handler))
+    }
+
+    // 主动报到:补上 roster 缺失的「注册边」。在此之前 roster 只在收到轮询回复时(aihand:state/
+    // result/dom/screen)才登记一个 tab——于是会话里第一个命令若是 /tabs(纯 roster 读,自身不轮询),
+    // 即使前台开着健康 tab 也必然读到 (no live tabs)。连上即 hello、visibilitychange 重发,roster
+    // 实时为真。TAB_ID 存 sessionStorage 跨自愈 reload 存活,reload 后 hello 自然重放。
+    const hello = () => hot.send('aihand:hello', {
+        tab: TAB_ID,
+        url: location.href,
+        title: document.title,
+        visible: document.visibilityState === 'visible',
+    })
+    // hot.send is fire-and-forget: a hello sent before the HMR socket is OPEN is silently dropped,
+    // not queued. On a fresh load (especially the self-heal reload) this module often evaluates
+    // before the socket finishes connecting — and `vite:ws:connect` only fires once, so if it
+    // already fired before this listener attached, the connect-retry never runs either. The tab
+    // then never registers (eval still works, but /tabs is blind) until a stray visibilitychange
+    // happens to resend. So don't bet hello on one fire: resend on a short interval until the
+    // server acknowledges via the roster (it echoes back over `aihand:hello-ack`), capped so a
+    // genuinely-down server doesn't spin. Idempotent on the server (seen() just upserts the tab).
+    let helloAcked = false
+    onMsg('aihand:hello-ack', (msg: { tab?: string }) => { if (msg.tab === TAB_ID) helloAcked = true })
+    let helloTries = 0
+    const helloUntilAcked = () => {
+        if (helloAcked || helloTries++ > 20) return
+        hello()
+        setTimeout(helloUntilAcked, 250)
+    }
+    helloUntilAcked()
+    addEventListener('visibilitychange', hello)
+    disposers.push(() => removeEventListener('visibilitychange', hello))
+
+    // Self-heal a dropped HMR socket. The whole action chain rides this WS; when it drops,
+    // Vite's own reconnect (client.mjs waitForSuccessfulPing) is GATED on visibilityState ===
+    // 'visible', so a backgrounded tab/window (Electron we app.hide() on launch) never reconnects
+    // and never reloads — stranding the chain on a dead socket while BOOT_ID is unchanged.
+    //
+    // The fix is EVENT-DRIVEN, not polled. An earlier version set a flag for the client-patch
+    // HTTP heartbeat to notice — but a long-lived background setInterval is exactly what the
+    // browser throttles/freezes (verified: a page-load-time interval stops firing in a long-
+    // backgrounded tab, while the WS message channel stays instantly live). So we act the moment
+    // vite:ws:disconnect fires: kick off a short self-bound setTimeout poll (armed by the event,
+    // not a resident timer) that waits for /ping to answer, then reloads to re-handshake. We also
+    // keep the global flag for the heartbeat as a belt-and-suspenders second trigger.
+    const wsDead = (v: boolean) => { (window as { __aihand_ws_dead__?: boolean }).__aihand_ws_dead__ = v }
+    let healing = false
+    const healAfterDrop = async () => {
+        if (healing) return
+        healing = true
+        // Poll the HTTP heartbeat (independent of the dead WS). Once the server answers, reload.
+        // setTimeout (re-armed per tick) rather than setInterval: a fresh timer scheduled right
+        // after live activity resists the background freeze that kills resident intervals.
+        const tick = async () => {
+            try {
+                await fetch('/__aihand/ping', { cache: 'no-store' })
+                location.reload() // server reachable again → re-handshake the WS via a fresh load
+            }
+            catch {
+                setTimeout(tick, 2000) // server still down — keep waiting, don't reload on failure
+            }
+        }
+        tick()
+    }
+    onMsg('vite:ws:disconnect', () => { wsDead(true); healAfterDrop() })
+    onMsg('vite:ws:connect', () => {
+        wsDead(false)
+        healing = false
+        hello() // socket came back without a page reload — re-register so roster doesn't go stale
+    })
+
+    // Self-accept + unwind: dispose runs before the next module instance evaluates, so the new
+    // run re-registers fresh handlers onto a clean slate (no stacking), and vite swaps in place
+    // instead of reloading the page. This is what makes editing the probe NOT reset the app
+    // under test. (vite:ws self-heal still reloads on a real server restart — a different path.)
+    //
+    // The accept MUST be spelled `import.meta.hot.accept()` LITERALLY, not via the `hot` alias.
+    // Vite detects self-acceptance by lexically scanning source for the token run
+    // `import.meta.hot.accept` (importAnalysis: `source.slice(endHot, endHot+7) === ".accept"`);
+    // an aliased `hot.accept()` is invisible to that scan, so the module stays
+    // isSelfAccepting:false and every edit force-reloads the page (`!node.importers.size` path),
+    // wiping the app under test. Keep this call literal.
+    hot.dispose(() => {
+        for (const off of disposers) off()
+    })
+    import.meta.hot.accept()
+}