nastechai-desktop 18.1.0

package/scripts/profile-typing-lag.md

@@ -0,0 +1,381 @@
+# Profiling renderer typing lag
+
+Workflow for empirically measuring (and fixing) typing/submit lag in the
+desktop chat composer.
+
+## Quick boot for profiling
+
+Vite 8 + plugin-react 6 has a known issue where the React Fast Refresh
+preamble script isn't injected into `index.html`, so opening Electron at
+`http://127.0.0.1:5174` throws `$RefreshReg$ is not defined` on every TSX
+module and the React tree never mounts. Workaround: run vite with HMR off.
+
+```bash
+# Terminal A — start dev server without HMR
+cd apps/desktop
+node scripts/dev-no-hmr.mjs
+
+# Terminal B — start Electron with CDP exposed
+cd apps/desktop
+XCURSOR_SIZE=24 NASTECH_DESKTOP_DEV_SERVER=http://127.0.0.1:5174 \
+  ../../node_modules/.bin/electron --remote-debugging-port=9222 .
+```
+
+Terminal C is yours to run the harnesses.
+
+## Harnesses
+
+All zero-dep — Node 24 built-in `WebSocket` + `fetch`.
+
+### Typing latency — `measure-latency.mjs`
+
+Per-keystroke `keypress → next paint` latency, p50/p90/p99/max.
+Synthesizes keystrokes via `Input.dispatchKeyEvent` so the run is
+reproducible.
+
+```bash
+node apps/desktop/scripts/measure-latency.mjs --chars=120 --cps=20
+```
+
+Anything > 16ms is a dropped frame. On a freshly-loaded session
+(`scripts/click-session.mjs 'Phaser particle'`) we currently see:
+
+| | unpatched | patched |
+|---|---|---|
+| p50 paint | 1.9 ms | 2.0 ms |
+| p90 paint | 3.3 ms | 13.7 ms |
+| p99 paint | 16.7 ms | 15.2 ms |
+| max paint | 20.5 ms | 30.4 ms |
+| >16ms drops | 2/120 | 1/120 |
+
+Roughly even on a quick session — patches don't fix typing latency
+under benign synthetic conditions because the existing baseline is
+already snappy on synthetic input. The real wins are in the leak counters
+(see below). If the user reports typing jank, capture a profile + heap
+diff during their actual usage and compare against the synthetic baseline
+to identify what condition (long thread, popover open, paste, etc.)
+makes the path slow.
+
+### Leak counters — `leak-typing.mjs`
+
+Types N chars per round, clears, force-GCs, captures
+`Performance.getMetrics` deltas. Reveals leaked event listeners, heap
+drift, document node growth, and forced-layout counts.
+
+```bash
+# After clicking into a real session (e.g. via click-session.mjs):
+node apps/desktop/scripts/leak-typing.mjs --rounds=8 --chars=200 --cps=50
+```
+
+**Real-session numbers (Phaser thread, 8 rounds × 200 chars):**
+
+| | unpatched (HEAD~2) | patched (HEAD) |
+|---|---|---|
+| jsListeners growth/round | +0 | +0 |
+| DOM nodes growth/round | +0 | +0 |
+| heap growth/round | ~0 (V8 housekeeping) | ~0 |
+| **forced layouts/char** | **7.02** | **2.35** (3× fewer) |
+
+The forced-layout count is the load-bearing number — typing into a real
+session was triggering ~7 layouts per character on the unpatched build
+(scrollHeight reads + per-px CSS var writes + FadeText scrollWidth reads
+all stacking up). After the patches it's down to ~2.35/char, which is
+Blink's natural cost for a 1px/char-growing contentEditable and can't
+be lowered further without architectural changes.
+
+The initial "+35 listeners/round leak" I called out on the first
+unpatched run turned out to be transient warm-up (popovers initializing,
+etc.); steady-state listener growth was 0 both before and after.
+
+### CPU profile + heap snapshot — `profile-typing.mjs`
+
+Records a CPU profile while typing, plus before/after heap snapshots so
+you can do a comparison diff in Chrome DevTools Memory tab.
+
+```bash
+node apps/desktop/scripts/profile-typing.mjs \
+  --chars=400 --cps=30 --out=/tmp/NASTECH-typing
+# → /tmp/NASTECH-typing.cpuprofile  (open in Chrome DevTools Performance)
+# → /tmp/NASTECH-typing.before.heapsnapshot
+# → /tmp/NASTECH-typing.after.heapsnapshot
+```
+
+Loading the cpuprofile: Chrome DevTools → Performance tab → drag the file
+in, or VS Code → open the `.cpuprofile` directly.
+
+For heap diff: Chrome DevTools → Memory → Load snapshot → load "before",
+then Comparison view → load "after". Sort by `# Delta`. Stay alert for
+detached DOM, FiberNodes (unmounted), and listener growth.
+
+## Helpers
+
+- `probe-renderer.mjs` — dump page state (URL, composer mounted?, body text)
+- `click-session.mjs <title>` — click a sidebar session by partial title match
+- `reload-renderer.mjs` — force Page.reload via CDP (no HMR available)
+- `dump-state.mjs` — richer state dump (thread message count, sticky session, etc.)
+- `probe-console.mjs` — dump recent console errors / exceptions
+
+## Findings
+
+See commit message for `apps/desktop/src/app/chat/composer/index.tsx`
+edits. Three changes:
+
+1. **Per-keystroke `scrollHeight` read removed.** The expansion useEffect
+   used to read `editorRef.current.scrollHeight` on every draft change
+   (forces synchronous layout). Replaced with a `draft.length > 60`
+   heuristic; the ResizeObserver catches anything the heuristic misses.
+
+2. **Bucketed CSS custom-property writes.** `syncComposerMetrics`
+   used to `setProperty('--composer-measured-height', height + 'px')`
+   on every observed resize, invalidating computed style for the whole
+   tree. Now writes only when the height crosses an 8 px bucket, so
+   typing in a fixed-height row produces no style invalidation at all.
+
+3. **Removed dead `$composerDraft` → `aui.composer().setText` round-trip.**
+   Nothing outside the composer subscribed to `$composerDraft` (verified
+   via grep). The two useEffects that pushed draft → store and store →
+   composer were pure overhead per keystroke. `reconcileComposerTerminalSelections`
+   was also called per keystroke; can be deferred to submit time (it's a
+   stale-pruning step, not a correctness one — `terminalContextBlocksFromDraft`
+   walks the current text directly at submit and ignores stale labels).
+
+4. **`refreshTrigger` fast-bails when no `@`/`/` in draft.** Previously
+   `textBeforeCaret()` did `range.toString()` (O(n)) on every keystroke
+   even when no trigger char was present.
+
+The biggest win is the listener leak in (3) — without it, each round of
+typing leaked ~35 event listeners until a steady state.
+
+## Submit / TTFT stall (open)
+
+User reports a perceived stall *after* Enter, before the assistant starts
+streaming. `scripts/measure-submit.mjs` measures
+`enter → composer-cleared → user-message-rendered → first-paint`. The
+script triggers a real prompt submission, so use it on a throwaway
+session. Not enabled in CI.
+
+## Streaming "5fps" investigation (May 21, 2026)
+
+User complaint: "the streaming must bring fps to like 5? lol" — felt
+hitches during assistant streaming on long threads.
+
+### Tooling added
+
+- **`src/app/chat/perf-probe.tsx`** — dev-only side-effect import (guarded by
+  `import.meta.env.MODE !== 'production'` in `main.tsx`). Attaches two
+  helpers to `window`:
+  - `__PERF_PROBE__` — React `<Profiler>` recorder. Currently inert because
+    Vite is serving the production React build (see "Vite dev-build issue"
+    below); kept for when that's fixed.
+  - `__PERF_DRIVE__` — synthetic stream driver. Pushes tokens through the
+    live `$messages` atom at a fixed cadence, so the assistant-ui runtime,
+    incremental repository, Streamdown markdown renderer, and React commit
+    pipeline all see the same workload they'd see from a real LLM stream —
+    but with no LLM call (and no credit cost).
+- **`scripts/measure-synthetic-stream.mjs`** — drives `__PERF_DRIVE__`,
+  records rAF frame intervals, `PerformanceObserver({entryTypes:['longtask']})`
+  entries, `MutationObserver` cadence on the live message, and optional
+  type-while-streaming keystroke latency.
+- **`scripts/profile-synth-stream.mjs`** — CPU profile during a synthetic
+  stream; writes a `.cpuprofile` (open in Chrome DevTools Performance panel)
+  and a top-30 self-time table.
+- **`scripts/measure-real-stream.mjs`** — same harness as the synthetic but
+  fires a real LLM prompt. Use when you have credits and want to confirm
+  the synthetic predictions hold.
+- **`scripts/profile-real-stream.mjs`** — CPU profile over the duration of
+  a real LLM stream.
+
+Helpers: `scripts/eval.mjs` (one-shot CDP eval), `scripts/reload.mjs`
+(hard reload renderer over CDP).
+
+### Findings
+
+Measured on the Cloud Shadows session (7 turns, ~11k px scrollHeight) and
+the 34 MB session `session_20260514_215353_fe0ac8.json` (110 FadeText
+instances, lots of historical tool calls).
+
+| metric | Cloud Shadows | 34 MB session |
+|---|---|---|
+| avgFps (60 tok/sec, 5s) | 60.0 | 58.6 |
+| frame p50 / p95 / p99 (ms) | 16.7 / 18.0 / 21.1 | 16.6 / 25.6 / 31.4 |
+| max frame (ms) | 31.1 | 97-127 (varies) |
+| longtasks per 5s window | 0 | 1-2, 75-127 ms |
+| type-while-stream p95 latency (ms) | 17 | — |
+
+A single real-LLM stream on Cloud Shadows (gpt-4o-mini, 39s window) saw
+12 longtasks totalling 1.26 s — same cadence the synthetic predicted
+(~1 hitch per 3.25 s, max 123 ms). So the **synthetic stream is a faithful
+proxy for the real one** and is fine for iterating on fixes without paying
+for tokens.
+
+### CPU profile during streaming (synthetic, markdown content)
+
+Top self-time costs (5 s window, 400 tokens at 125 tok/s, markdown chunks):
+
+| ms (self) | function | source |
+|---|---|---|
+| 260 | `bn$1` | `chunk-BO2N…js:20003` (micromark tokenize) |
+| 249 | `m$1` | `chunk-BO2N…js:19949` (micromark) |
+| 128 | `compile` | `chunk-BO2N…js:21884` (mdast → hast compile) |
+| 73 | FadeText body | `components/ui/fade-text.tsx` |
+| 62 | `parser` | `chunk-BO2N…js:22680` |
+| 49 | `fromThreadMessageLike` | `@assistant-ui/internal` |
+
+That `chunk-BO2N2NFS` is the vendored bundle containing `micromark`,
+`mdast-util-from-markdown`, `mdast-util-to-hast`, `rehype-raw`,
+`hast-util-sanitize`, etc. — i.e. **Streamdown's markdown pipeline,
+re-parsing the entire growing assistant message on every token append**.
+Cost scales linearly with message length.
+
+Compare plain-text (no markdown) — the `chunk-BO2N…` entries drop out
+of the top 30 entirely; total work per 5 s window halves.
+
+### Fix landed: `FadeText` memo
+
+`FadeText` is used in `tool-fallback.tsx` (110 instances on a tool-heavy
+thread). Before: each parent re-render during streaming triggered a
+`useEffect([children])` that forced a `scrollWidth` layout read — even
+when the title text was unchanged. The `useResizeObserver` already covers
+the genuine resize case, so the effect was strictly redundant.
+
+After: wrapped in `React.memo` with a custom comparator that compares
+`children` (scalar fast-path), `className`, `fadeWidth`, and `style`
+field-by-field. Verified via temporary render counter:
+**122 renders during a 2 s synthetic stream vs ~11 000 without memo**
+(110 instances × ~100 stream updates). Doesn't move the longtask needle
+on its own — Streamdown dwarfs it — but eliminates a class of forced
+layouts and removes a steady CPU floor.
+
+### Also landed: `MarkdownText` plugins memo + upstream flush floor
+
+Two smaller follow-ups in the same investigation:
+
+1. **`MarkdownText` `plugins` object useMemo'd.** The inline
+   `plugins={{ math: mathPlugin, ...(isStreaming ? {} : { code }) }}`
+   was constructing a new object on every render, which churns
+   `<Streamdown>`'s outer memo and forces its internal `rehypePlugins` /
+   `remarkPlugins` arrays to rebuild. CPU profile after the change shows
+   `parser` self-time dropping out of the top 10, `compile` cut roughly
+   in half, and `bn$1` / `m$1` (micromark internals) dropping off the
+   top entries.
+
+2. **`use-message-stream.scheduleDeltaFlush` got a real minimum floor.**
+   Previously the rAF-only path effectively meant "at most one flush per
+   frame," but at typical LLM token rates of 30-80 tok/sec each token
+   arrives slower than rAF cadence and gets its own React commit. With
+   `STREAM_DELTA_FLUSH_MS = 33` (two frames) and a `lastFlushAt`-tracked
+   floor, slower streams now coalesce ~2 tokens per commit, halving
+   markdown re-parses. React's auto-batching already covers part of this
+   probabilistically; the floor makes the batching deterministic so the
+   max-longtask number tightens up.
+
+A/B on the 34 MB session, 300 tokens at 50 tok/sec, markdown chunks
+(3 trials each):
+
+| | avgFps | p99 frame | LTs/5s | max LT | mutations |
+|---|---|---|---|---|---|
+| no throttle  | 54.0 | 38 ms | 2.0 | 145 ms | varies (2-112) |
+| 33 ms throttle | 54.3 | 41 ms | 1.7 | 110 ms | ~135 |
+
+Modest. `inter-mutation` p50 tightens from 22-28 ms to a clean 33 ms,
+which is what you'd expect from a deterministic floor.
+
+### Also landed: `useDeferredValue` at the streamdown-text boundary
+
+The longtask CPU was unavoidable inside the block-memo pattern — the live
+tail re-parses every commit, scales linearly with current length, and
+nothing about Streamdown's architecture changes that without forking. The
+fix is to stop having that work *block* the main thread.
+
+`<DeferStreamingText>` in `markdown-text.tsx` is a 12-line wrapper that
+reads the message-part state via `useMessagePartText`, runs it through
+`useDeferredValue`, and re-publishes via assistant-ui's
+`<TextMessagePartProvider>`. The inner `StreamdownTextPrimitive` reads the
+deferred value through the normal `useMessagePartText` hook — no fork,
+no internal-path imports, fully on the assistant-ui public API.
+
+What React's concurrent scheduler now does:
+
+- When a new token arrives mid-render, the in-flight deferred render
+  is abandoned and a fresh one starts with the latest text.
+- When the main thread has urgent work (typing, scroll, layout), the
+  Streamdown render gets deprioritized — input stays responsive even
+  while a 100 ms parse is queued.
+
+Streamdown already uses `useTransition` internally for its block-array
+setState; `useDeferredValue` here just lifts the deferral all the way up
+to the consumer text boundary, so the whole pipeline — preprocess,
+block split, repair, parse, render — runs at low priority during streaming.
+This is the industry-standard approach (see
+[Streamdown architecture analysis](https://tigerabrodi.blog/how-to-build-a-performant-ai-markdown-renderer)
+and Chrome's [LLM-response render best practices](https://developer.chrome.google.cn/docs/ai/render-llm-responses)).
+
+A/B on the 34 MB session, 300 tokens at 50 tok/sec, markdown chunks
+(four trials each, prod-throttle (33 ms) on for both):
+
+| | avgFps | p99 frame | LTs / 5 s | max LT | typing p95 |
+|---|---|---|---|---|---|
+| pre-defer | 54.3 | 41 ms | 1.7 | 110 ms | ~17 ms |
+| **post-defer** | **58.5** | **31 ms** | 2.0 | 117 ms | 14-18 ms |
+
+Longtask count and max LT are unchanged — `useDeferredValue` doesn't
+reduce CPU, only its priority. The avgFps lift and p99 frame drop are
+the proof that the existing CPU is no longer blocking 60 fps cadence:
+when React can defer the parse, frames stay clean. One particularly
+clean run logged **MUTATIONS=0** — React skipped every intermediate
+text state and only committed the final one, the textbook
+useDeferredValue behaviour.
+
+### Not fixed: Streamdown markdown re-parse cost (the elephant)
+
+Total CPU spent in micromark/mdast/hast pipeline per 5 s window is still
+the same ~700 ms. With `useDeferredValue` that work no longer blocks
+input, but if you watch a CPU profile you'll see the same hot functions
+(`Tn$1`, `bn$1`, `m$1`, `parser`, `compile`).
+
+The path to actually *reduce* that cost (not just defer it) is to
+replace the parser with a state machine like
+[Flowdown](https://github.com/Atomics-hub/flowdown) — process each
+character exactly once, emit DOM ops directly, no re-parse of the prefix
+on every token. Claimed ~2,000× over `marked`. Trades: not a
+`react-markdown`-compatible API, no rehype security pipeline, would
+require replacing Streamdown wholesale. Worth investigating only if
+even the deferred work shows up in user-perceptible ways (e.g.
+trackpad-scrolling a stream-in-progress stutters).
+
+The synthetic harness now mirrors the real upstream pipeline via the
+`flushMinMs` option in `__PERF_DRIVE__.stream({ flushMinMs: 33 })`, so
+future Streamdown / Flowdown experiments can A/B without LLM credit cost.
+The synthetic numbers tracked the one real-LLM run we caught within
+noise, so it's a reliable proxy.
+
+Possible approaches (none implemented here):
+
+1. **Coalesce/throttle Streamdown updates** — render at most every 32 ms
+   instead of every set-state. Reduces parses but doesn't reduce
+   per-parse cost; trades latency for smoothness.
+2. **Memoize per-prefix** — diff the new text against the prior parsed
+   version; only re-parse the changed suffix.
+3. **Render in stable segments** — close-form historical paragraphs as
+   immutable React nodes; only the live tail goes through markdown each
+   token. Probably the highest-impact change but requires forking or
+   patching `@assistant-ui/react-streamdown`.
+4. **Move parsing to a Web Worker** — main thread no longer blocks on
+   markdown. Largest surgery; requires double-buffered hast.
+
+### Vite dev-build issue (separate)
+
+`http://127.0.0.1:5174/node_modules/.vite/deps/react.js` resolves to
+`react/cjs/react.production.js`, and `react-dom_client.js` →
+`react-dom-client.production.js`. As a result:
+
+- `<React.Profiler>` `onRender` is never called (production build is a
+  no-op).
+- `import.meta.env.DEV` is `false`, `PROD` is `true` even under `vite dev`
+  (hence `MODE !== 'production'` as the workaround in `main.tsx`).
+- All the React 19 dev-only warnings/devtools backend hooks are absent.
+
+Root cause likely sits in `vite.config.ts` aliasing + dedupe + Vite 8's
+new `optimizeDeps` defaults. Worth a separate fix pass — when it's
+resolved, the `<PerfProbe>` blocks in `perf-probe.tsx` become useful
+(per-id commit timings) instead of inert.

package/scripts/profile-typing.mjs

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+// Profile typing lag in the Electron renderer by:
+//  1. Connecting to a running renderer via CDP (--remote-debugging-port=9222)
+//  2. Focusing the composer contentEditable
+//  3. Starting CPU profile + heap snapshot
+//  4. Synthesizing keystrokes via Input.dispatchKeyEvent (so the run is
+//     reproducible, no human-typing variance)
+//  5. Stopping the profile + capturing a second heap snapshot
+//  6. Saving .cpuprofile + .heapsnapshot
+//
+// Usage:
+//   node apps/desktop/scripts/profile-typing.mjs
+//     [--port=9222] [--out=/tmp/nastech-typing]
+//     [--chars=400]              # how many characters to type
+//     [--cps=30]                 # keystrokes per second
+//     [--text="..."]             # override generated text
+//     [--no-heap]                # skip heap snapshots
+//     [--seconds=N]              # idle-record for N seconds instead of typing
+//
+// Zero deps — uses Node 24's global WebSocket + fetch.
+
+import { writeFileSync } from 'node:fs'
+
+const args = Object.fromEntries(
+  process.argv.slice(2).flatMap(s => {
+    const m = s.match(/^--([^=]+)(?:=(.*))?$/)
+    return m ? [[m[1], m[2] ?? true]] : []
+  })
+)
+
+const PORT = Number(args.port ?? 9222)
+const OUT = String(args.out ?? `/tmp/nastech-typing-${Date.now()}`)
+const CHARS = Number(args.chars ?? 400)
+const CPS = Number(args.cps ?? 30)
+const HEAP = args['no-heap'] ? false : true
+const IDLE_SECONDS = args.seconds ? Number(args.seconds) : null
+const CUSTOM_TEXT = args.text === undefined || args.text === true ? null : String(args.text)
+
+const log = (...m) => console.log('[profile]', ...m)
+const banner = m => console.log(`\n========== ${m} ==========`)
+
+async function pickRenderer() {
+  const list = await (await fetch(`http://127.0.0.1:${PORT}/json/list`)).json()
+  const pages = list.filter(t => t.type === 'page' && t.url.startsWith('http'))
+  if (!pages.length) {
+    console.error('No renderer page. Targets:')
+    list.forEach(t => console.error(' ', t.type, t.url))
+    process.exit(2)
+  }
+  return pages[0]
+}
+
+function connect(url) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(url)
+    let id = 0
+    const pending = new Map()
+    const events = new Map()
+    ws.addEventListener('open', () =>
+      resolve({
+        send(method, params = {}) {
+          const myId = ++id
+          ws.send(JSON.stringify({ id: myId, method, params }))
+          return new Promise((res, rej) => pending.set(myId, { res, rej }))
+        },
+        on(method, h) {
+          if (!events.has(method)) events.set(method, [])
+          events.get(method).push(h)
+        },
+        close: () => ws.close()
+      })
+    )
+    ws.addEventListener('error', reject)
+    ws.addEventListener('message', ev => {
+      const txt = typeof ev.data === 'string' ? ev.data : ev.data.toString('utf8')
+      const m = JSON.parse(txt)
+      if (m.id != null) {
+        const p = pending.get(m.id)
+        if (!p) return
+        pending.delete(m.id)
+        m.error ? p.rej(new Error(m.error.message)) : p.res(m.result)
+      } else if (m.method) {
+        ;(events.get(m.method) ?? []).forEach(h => h(m.params))
+      }
+    })
+  })
+}
+
+async function captureHeap(cdp, path) {
+  log(`heap snapshot → ${path}`)
+  const chunks = []
+  cdp.on('HeapProfiler.addHeapSnapshotChunk', ({ chunk }) => chunks.push(chunk))
+  await cdp.send('HeapProfiler.enable')
+  await cdp.send('HeapProfiler.takeHeapSnapshot', { reportProgress: false, captureNumericValue: true })
+  writeFileSync(path, chunks.join(''))
+  log(`  ${(Buffer.byteLength(chunks.join(''), 'utf8') / 1024 / 1024).toFixed(1)} MB`)
+}
+
+async function focusComposer(cdp) {
+  // Focus the rich-input contentEditable. RICH_INPUT_SLOT is the data-slot
+  // value used by the composer's editable div. If focus fails (no composer
+  // mounted yet — disabled state, etc.) the script logs and continues; the
+  // profile will still show idle behavior.
+  const result = await cdp.send('Runtime.evaluate', {
+    expression: `
+      (() => {
+        const el = document.querySelector('[data-slot="composer-rich-input"]')
+        if (!el) return { ok: false, reason: 'composer-rich-input not found' }
+        el.focus()
+        // place caret at end
+        const range = document.createRange()
+        range.selectNodeContents(el)
+        range.collapse(false)
+        const sel = window.getSelection()
+        sel.removeAllRanges()
+        sel.addRange(range)
+        return { ok: true, text: el.innerText.length }
+      })()
+    `,
+    returnByValue: true
+  })
+  if (!result.result.value?.ok) {
+    log(`focus failed: ${result.result.value?.reason ?? 'unknown'}`)
+    return false
+  }
+  log(`composer focused (existing text length: ${result.result.value.text})`)
+  return true
+}
+
+function genText(n) {
+  const lorem =
+    'the quick brown fox jumps over the lazy dog while the agent thinks really hard about why typing into this composer feels like wading through molasses on a hot afternoon '
+  let s = ''
+  while (s.length < n) s += lorem
+  return s.slice(0, n)
+}
+
+async function dispatchChar(cdp, ch) {
+  // For printable chars, char + keypress is enough — Electron treats it as text input
+  // and the contentEditable input event fires. For Enter / Space we could add
+  // specials; this run is one long line.
+  await cdp.send('Input.dispatchKeyEvent', {
+    type: 'char',
+    text: ch,
+    unmodifiedText: ch
+  })
+}
+
+async function typeText(cdp, text, cps) {
+  const intervalMs = Math.max(1, Math.round(1000 / cps))
+  const start = Date.now()
+  for (let i = 0; i < text.length; i++) {
+    await dispatchChar(cdp, text[i])
+    // Pace evenly; account for dispatch latency so we don't drift much.
+    const expected = start + (i + 1) * intervalMs
+    const wait = expected - Date.now()
+    if (wait > 0) await new Promise(r => setTimeout(r, wait))
+  }
+}
+
+async function main() {
+  log(`CDP port ${PORT}, out ${OUT}`)
+  const target = await pickRenderer()
+  log(`target ${target.url}`)
+  const cdp = await connect(target.webSocketDebuggerUrl)
+  await cdp.send('Runtime.enable')
+  await cdp.send('Page.enable')
+  await cdp.send('Profiler.enable')
+
+  // Pre-GC so the cpu profile + heap delta are clean.
+  try {
+    await cdp.send('HeapProfiler.collectGarbage')
+  } catch (e) {
+    log('GC skipped:', e.message)
+  }
+
+  if (HEAP) await captureHeap(cdp, `${OUT}.before.heapsnapshot`)
+
+  // 1ms sampling — fine enough for per-frame React work.
+  await cdp.send('Profiler.setSamplingInterval', { interval: 1000 })
+
+  let typedText = ''
+  if (!IDLE_SECONDS) {
+    const focused = await focusComposer(cdp)
+    if (!focused) {
+      log('aborting — composer not focusable. Make sure the app is past the boot screen.')
+      cdp.close()
+      process.exit(3)
+    }
+    typedText = CUSTOM_TEXT ?? genText(CHARS)
+  }
+
+  await cdp.send('Profiler.start')
+
+  if (IDLE_SECONDS) {
+    banner(`IDLE recording for ${IDLE_SECONDS}s — DO NOT TOUCH`)
+    await new Promise(r => setTimeout(r, IDLE_SECONDS * 1000))
+  } else {
+    banner(`TYPING ${typedText.length} chars @ ${CPS} cps (≈${(typedText.length / CPS).toFixed(1)}s)`)
+    const t0 = Date.now()
+    await typeText(cdp, typedText, CPS)
+    log(`typing wall time: ${((Date.now() - t0) / 1000).toFixed(2)}s`)
+    // Settle frame for trailing React work.
+    await new Promise(r => setTimeout(r, 500))
+  }
+
+  banner('STOP — saving profile')
+  const { profile } = await cdp.send('Profiler.stop')
+  writeFileSync(`${OUT}.cpuprofile`, JSON.stringify(profile))
+  log(`cpu profile → ${OUT}.cpuprofile (${(JSON.stringify(profile).length / 1024 / 1024).toFixed(1)} MB)`)
+
+  if (HEAP) {
+    try {
+      await cdp.send('HeapProfiler.collectGarbage')
+    } catch {}
+    await captureHeap(cdp, `${OUT}.after.heapsnapshot`)
+  }
+
+  // Quick triage: top-self-time frames from the profile.
+  const top = summarizeProfile(profile)
+  banner('TOP SELF-TIME FRAMES')
+  for (const row of top.slice(0, 20)) {
+    console.log(
+      `  ${row.selfMs.toFixed(1).padStart(7)}ms  ${row.functionName || '(anonymous)'}` +
+        `  ${row.url ? '· ' + row.url.replace(/^.*\/src\//, 'src/').slice(0, 80) : ''}`
+    )
+  }
+  console.log()
+  log(`total samples: ${top.totalSamples}, total time: ${(top.totalMs / 1000).toFixed(2)}s`)
+
+  cdp.close()
+}
+
+function summarizeProfile(profile) {
+  // Cumulative samples = how many sampling ticks landed on each node.
+  // selfMs = own time only, using sampling interval.
+  const intervalMs = (profile.endTime - profile.startTime) / 1000 / Math.max(1, profile.samples?.length ?? 1)
+  const counts = new Map()
+  for (const s of profile.samples ?? []) counts.set(s, (counts.get(s) ?? 0) + 1)
+  const rows = profile.nodes.map(n => {
+    const self = counts.get(n.id) ?? 0
+    return {
+      id: n.id,
+      functionName: n.callFrame.functionName,
+      url: n.callFrame.url,
+      lineNumber: n.callFrame.lineNumber,
+      selfSamples: self,
+      selfMs: self * intervalMs
+    }
+  })
+  rows.sort((a, b) => b.selfSamples - a.selfSamples)
+  rows.totalSamples = (profile.samples ?? []).length
+  rows.totalMs = ((profile.endTime - profile.startTime) / 1000)
+  return rows
+}
+
+main().catch(e => {
+  console.error('[profile] fatal:', e.stack ?? e.message)
+  process.exit(1)
+})

package/scripts/reload-renderer.mjs

@@ -0,0 +1,25 @@
+// Reload the renderer via CDP so it picks up the latest from Vite.
+const list = await (await fetch('http://127.0.0.1:9222/json/list')).json()
+const tgt = list.find(t => t.type === 'page' && t.url.startsWith('http'))
+const ws = new WebSocket(tgt.webSocketDebuggerUrl)
+let id = 0
+const pending = new Map()
+ws.addEventListener('message', ev => {
+  const m = JSON.parse(ev.data)
+  if (m.id != null && pending.has(m.id)) {
+    pending.get(m.id)(m)
+    pending.delete(m.id)
+  }
+})
+await new Promise(r => ws.addEventListener('open', r))
+const send = (method, params = {}) =>
+  new Promise(r => {
+    const i = ++id
+    pending.set(i, r)
+    ws.send(JSON.stringify({ id: i, method, params }))
+  })
+await send('Page.enable')
+await send('Page.reload', { ignoreCache: true })
+console.log('reload requested')
+await new Promise(r => setTimeout(r, 200))
+ws.close()