palot-performance
Measure and improve Palot desktop runtime performance. Use for reported slowness or regressions; profiling CPU, memory, long tasks, React commits, style/layout/paint cost, GPU compositing, frame pacing, or streaming latency; changing the performance harness; React Scan or Compiler experiments; or performance budgets. Use test-palot-desktop for non-performance UI QA.
ItsWendell · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add ItsWendell/palot --skill palot-performance技能说明
name: palot-performance description: Measure and improve Palot desktop runtime performance. Use for reported slowness or regressions; profiling CPU, memory, long tasks, React commits, style/layout/paint cost, GPU compositing, frame pacing, or streaming latency; changing the performance harness; React Scan or Compiler experiments; or performance budgets. Use test-palot-desktop for non-performance UI QA.
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:doctorfor changed code andbun run perf:react-checkfor 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:steadyandbun run perf:batch:burstuse 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:videoor add--videoto a matching E2E command. Requiresffmpeg; retains renderer-onlyvideo.mp4and 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(orperf: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; usebun run perf:parallel:tracefor whole-app attribution.bun run perf:parallel:memoryrepeats accumulating workloads with forced GC to investigate retention, not independent latency samples. - Style attribution: run
bun run perf:selectors. Phase-separated React render attribution: runbun 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 writesperformance-trace.jsonbesideperformance.json. - Render overlay: enable React Scan in Settings > Diagnostics or run
bun run dev:scan. The dev client starts hidden; usePALOT_REACT_SCAN=1 bun run dev:visiblefor visible inspection without taking focus, andPALOT_REACT_SCAN=1 bun run dev:focusonly 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:compilerfor whole-rendererinfermode orbun run perf:compiler:annotationto validate opt-in mode. The normal build does not enable React Compiler.
The deterministic harness is the default. Load test-palot-desktop before live native inspection or screenshots.
Measurement Contract
- Use a document-visible window for frame data. Performance runs show it inactive by default so they do not steal keyboard focus; use
--focusonly when focus behavior is part of the test. Hidden or fully occluded Electron windows are throttled and cannot provide a valid FPS baseline. - Compare the same scenario, window size, display scale, power state, hardware, build mode, and glass setting.
- Warm the flow before recording. Report medians across repeated runs when proposing a budget or claiming an improvement.
- Keep React Scan, DevTools overlays, paint flashing, and verbose logging off during benchmark runs. They are investigation tools, not neutral observers.
- Keep Palot's own diagnostics dashboard and overlay off during benchmark runs. Their collector is demand-driven, but active sampling still adds observer cost.
- Keep traces and screenshots under the primary checkout's
.local/directory. Treat them as private because traces can contain rendered text and source paths. - Change one rendering variable at a time. For blur work, compare the normal tier and
PALOT_DISABLE_GLASS=1, then isolate individual CSS backdrop surfaces. - State build mode with every result. Development, production, and React profiling builds have different overhead.
Read The Report
performance.json contains:
sessionSwitch.targetVisibleAtMs: click to useful target