palot: Skill for Codex

Palot Performance

Use the smallest loop that can prove or disprove the suspected cost. Preserve UX, motion, and native/CSS material unless measurements show a concrete problem and the cheaper rendering path still looks right.

Read repository-root ../../../docs/desktop-testing.md for harness commands and measurement contracts. Read references/main-thread-budget.md for current main-thread investigation rules; historical measurements are not evidence for the current checkout.

Choose The Loop

• Static React health: run bun run perf:doctor for changed code and bun run perf:react-check for React Compiler compatibility diagnostics.
• Full static baseline: run bun run perf:doctor:full. Treat it as advisory until the documented baseline has been paid down.
• Deterministic native measurement: run bun run perf:e2e. It builds an isolated Electron app, warms a long transcript switch, records frame intervals, long tasks, CDP metrics, Electron process CPU/memory, and streaming latency, then retains private artifacts.
• Input contention: run bun run perf:input. It types a real draft while the visible session and background sessions stream. Use it to evaluate responsiveness, not only throughput.
• Batch-size contention: bun run perf:batch:steady and bun run perf:batch:burst use identical numbered text with different provider arrival clustering. Inspect actual renderer batch sizes and synchronous callback durations alongside typing, freshness, and throughput; the transport timer is not a processing budget. These are different workloads, not a product A/B comparison.
• Navigation/cancellation contention: run bun run perf:interactions. It checks trusted session switches, wheel-up, a stable visible reading anchor, return to latest, and Stop under four continuous streams. Per-action DOM milestones include existing fades and are not compositor presentation.
• Visual recording: bun run perf:input:video or add --video to a matching E2E command. Requires ffmpeg; retains renderer-only video.mp4 and capture metadata. Recording adds observer overhead, is not presented-frame/FPS evidence, and must not be compared to unrecorded benchmarks.
• Streaming geometry: bun run perf:stability (or perf:stability:video) adds bounded active-turn/composer/scroll geometry sampling. Use it for bottom-follow jumps, not as a clean input benchmark. Inspect rAF and resize-observer phases separately; transient DOM measurements are not presented-frame proof.
• Streaming throughput and scroll correctness: run bun run perf:parallel; use bun run perf:parallel:trace for whole-app attribution. bun run perf:parallel:memory repeats accumulating workloads with forced GC to investigate retention, not independent latency samples.
• Style attribution: run bun run perf:selectors. Phase-separated React render attribution: run bun run perf:scan:render. Both add observer overhead and are not neutral benchmarks.
• Repeated comparison: bun run perf:compare <baseline.json...> -- <candidate.json...> checks matched report metadata and summarizes run-level medians/ranges. It requires at least two independent runs per group (five recommended), rejects legacy/memory-cycle reports, and does not launch tests or declare regression budgets.
• Attribution trace: run bun run perf:trace. It repeats the deterministic scenario with React's profiling build and writes performance-trace.json beside performance.json.
• Render overlay: enable React Scan in Settings > Diagnostics or run bun run dev:scan. The dev client starts hidden; use PALOT_REACT_SCAN=1 bun run dev:visible for visible inspection without taking focus, and PALOT_REACT_SCAN=1 bun run dev:focus only when focus behavior matters. Palot reloads so React Scan can install before React. Use it to find candidate rerenders, then disable it before measuring.
• Compiler experiment: run bun run perf:compiler for whole-renderer infer mode or bun run perf:compiler:annotation to validate opt-in mode. The normal build does not enable React Compiler.