Palot Performance

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.

The deterministic harness is the default. Load test-palot-desktop before live native inspection or screenshots.

Measurement Contract

1. Use a document-visible window for frame data. Performance runs show it inactive by default so they do not steal keyboard focus; use --focus only when focus behavior is part of the test. Hidden or fully occluded Electron windows are throttled and cannot provide a valid FPS baseline.
2. Compare the same scenario, window size, display scale, power state, hardware, build mode, and glass setting.
3. Warm the flow before recording. Report medians across repeated runs when proposing a budget or claiming an improvement.
4. Keep React Scan, DevTools overlays, paint flashing, and verbose logging off during benchmark runs. They are investigation tools, not neutral observers.
5. Keep Palot's own diagnostics dashboard and overlay off during benchmark runs. Their collector is demand-driven, but active sampling still adds observer cost.
6. Keep traces and screenshots under the primary checkout's .local/ directory. Treat them as private because traces can contain rendered text and source paths.
7. 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.
8. 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 transcript.
• interaction.page: document visibility and Chromium's internal document.hasFocus() state.
• interaction.runIdentity: revision/dirty state, host hardware/load context, declared versions, runner versions, scenario, and explicit build/trace/material controls. Power, refresh rate, and occlusion still require controlled manual recording.
• interaction.measurementWindow: renderer monotonic start/end and time origin, correlated with palot:measurement:start / palot:measurement:end trace marks.
• interaction.collectors and interaction.droppedEntries: distinguish observing, disabled, unsupported, or failed collectors and truncated samples. Missing instrumentation never means zero work.
• interaction.inputTimings: Event Timing stages and per-interaction duration summaries. Entries are thresholded at 16 ms, quantized, and limited to supported discrete interactions; these are not page-level INP or a distribution of every keystroke.
• interaction.longAnimationFrames: optional rendering/script attribution without React Scan; enabled by the input scenario. Entries and script attribution are bounded.
• interaction.frames: p50, p95, maximum frame interval, and counts over 25/50/100 ms.
• interaction.longTasks: count, total duration, maximum, and the 20 longest entries.
• interaction.reactCommits: profiling-build React commit count and actual/base render durations.
• interaction.browserMetrics.delta: CDP task, script, layout, style, heap, node, document, frame, and listener deltas.
• interaction.batchProcessing: opt-in (captureBatchProcessing) synchronous event-subscriber timing, event counts, and text-delta UTF-16 lengths. Only active in harness builds during measurement. The first 2,048 numeric samples are retained; complete counts/total/max continue after truncation. disabled/unavailable is not zero work. This excludes later React rendering, asynchronous request completion, and paint.
• interaction.appMetrics: on-demand Electron app.getAppMetrics() snapshots, host-window focus/visibility, interval CPU, working set, GPU feature status, and hardware acceleration state.
• interaction.streamingLatency: commit-cursor-scoped receive-to-React-commit samples, owner identity, applied batch count, oldest pending age, and retention loss. Latest-batch stage timings alone can hide an older pending batch. Top-level streamingLatency in older scenario reports remains a run-wide buffer.

CPU percentages from Electron are interval values since the prior snapshot. Memory values from Electron are KiB. CDP duration metrics are seconds, so convert deltas to milliseconds when presenting them.

Use interaction.appMetrics.*.window.focused for OS window focus. interaction.page.documentHasFocus is Chromium renderer state and can remain true for a non-focusable Electron window.