Make workspace tab switching faster (#1251)

* Avoid workspace shell renders when toggling sidebar * Avoid rerendering inactive workspace screens * Avoid rerendering unchanged sidebar rows * Keep sidebar selection state in the list * Speed up workspace tab switching
2026-05-31 15:46:17 +08:00
parent 67133e3ebc
commit f26a81798b
12 changed files with 909 additions and 323 deletions
@@ -43,6 +43,70 @@ In any worktree-style or portless setup, never assume default ports.
 `http://127.0.0.1:9223` so renderer CPU profiles can be captured through CDP.
 Override the port with `PASEO_ELECTRON_REMOTE_DEBUGGING_PORT` when `9223` is busy.

+### React render profiling
+
+The app has a gated React render profiler in
+`packages/app/src/utils/render-profiler.tsx`. Wrap the component boundary you want
+to measure with `RenderProfile`, then open the app with `?renderProfile=1`. When
+the query param is absent, `RenderProfile` returns children directly and records
+nothing.
+
+Captured samples are exposed on `globalThis.__PASEO_RENDER_PROFILE__`. Call
+`globalThis.__PASEO_RESET_RENDER_PROFILE__?.()` after warm-up and before the
+interaction you want to measure. If a memo comparator or subscription boundary
+needs explanation, call `recordRenderProfileReasons(id, reasons)` while profiling;
+reason counts are exposed on `globalThis.__PASEO_RENDER_PROFILE_REASONS__`.
+
+Use this workflow for any render investigation:
+
+1. Add stable `RenderProfile` boundaries around the suspected root and expensive
+   children. Keep IDs specific enough to compare before and after.
+2. Reproduce against real app state, not toy fixtures, whenever practical.
+3. Record an idle baseline first. If idle is noisy, fix or account for that
+   before optimizing the interaction.
+4. Warm up the route, reset profiler samples, run the exact interaction, then
+   compare `actualDuration`, render counts, and per-commit samples.
+5. When a memo boundary still renders, record reasons before changing code. Do
+   not guess from object identity alone.
+6. Keep changes that move the measured profile. Remove probes or memo wrappers
+   that do not move the number.
+
+What this caught during the workspace tab investigation:
+
+- A large apparent workspace cost was real interaction work, not daemon noise;
+  the idle baseline stayed near zero.
+- The expensive stream rerender was mostly prop identity churn from pane context
+  callbacks and capability objects, not new stream data.
+- Stabilizing provider actions at the pane boundary helped because every mounted
+  panel consumes that context.
+- Comparing value-shaped capability flags beat preserving object identity through
+  unrelated stores.
+- Some plausible fixes did not pay off: memoizing the tab row and composer draft
+  object barely moved the profile, so they were removed.
+
+Existing scenario script: workspace agent/terminal tab switching. Start Expo on
+web, keep a daemon available, then run:
+
+```bash
+PASEO_PROFILE_SERVER_ID=<server-id> \
+PASEO_PROFILE_WORKSPACE_ID=<workspace-path> \
+PASEO_PROFILE_AGENT_ID=<agent-id> \
+  npm run profile:workspace-tabs --workspace=@getpaseo/app
+```
+
+This script opens the app with `?renderProfile=1`, creates a temporary terminal
+tab, switches between a real agent and that terminal, prints aggregated React
+Profiler timings, then removes the temporary terminal. It is an example of the
+workflow above, not the only way to use the profiler. Useful knobs:
+
+```bash
+PASEO_PROFILE_APP_URL=http://localhost:19010 # Expo web URL
+PASEO_PROFILE_SWITCH_COUNT=1                # number of agent/terminal switch pairs
+PASEO_PROFILE_SWITCH_WAIT_MS=250            # delay after each click
+PASEO_PROFILE_IDLE_WAIT_MS=3000             # idle baseline before switching
+PASEO_PROFILE_DUMP_COMMITS=1                # include per-commit profiler samples
+```
+
 ### Desktop macOS compositor watchdog

 macOS display sleep can leave Chromium's GPU-process display link — the vsync