|
| 1 | +# Responsiveness Findings Plan — the facts worth emitting through the observe tier |
| 2 | + |
| 3 | +_Drafted 2026-09-18. Status: BACKLOG, worked against RCs as time allows. |
| 4 | +Successor to `observe-tier-plan.md` (the wiring, shipped in rc.9) and |
| 5 | +`sentry-integration-plan.md` (the first consumer, `@sentry/solid-2`, in |
| 6 | +review). Sibling of the **Chrome Performance Tracks** plan (Cursor plan |
| 7 | +`chrome_performance_tracks`, not yet in the repo), which owns the DevTools |
| 8 | +panel adapter and the engine records it needs; the two meet at the points |
| 9 | +marked "↔ Tracks" below. Owner: Ryan._ |
| 10 | + |
| 11 | +## Why this list exists |
| 12 | + |
| 13 | +The observe tier ships the channel; this is the backlog of things worth |
| 14 | +putting on it. The shape of the list follows from one observation: a |
| 15 | +component-rerendering framework's failure modes are about rendering too |
| 16 | +much, so its tooling counts renders. Solid does not re-run components, and |
| 17 | +its failure modes are about **waiting** — a write that landed behind async |
| 18 | +work, and whether the screen said so. Everything below is in that family, |
| 19 | +or is a consumer that shows the family to a developer where they already |
| 20 | +look. Each item is something only a runtime that owns the write can say. |
| 21 | + |
| 22 | +Every item carries the same four fields so it can be picked up alone: |
| 23 | + |
| 24 | +- **Known** — the hook or record that already carries the fact, so nobody |
| 25 | + re-derives it. |
| 26 | +- **Shape** — a finding (code, severity, fingerprint fields) or a record |
| 27 | + (type, fields). Findings are issues: stable identity, recur, counted. |
| 28 | +- **Idle cost** — what the observe build pays when nothing subscribes. |
| 29 | + Several are one integer. Anything more than a field on an existing record |
| 30 | + needs a size-cap measurement before it lands (`scripts/size/`). |
| 31 | +- **Proof** — the test, as a sentence. |
| 32 | + |
| 33 | +Ordered by value per effort. Items 1 and 2 are the pair that turns an INP |
| 34 | +number, which every tool reports, into a cause, which only this runtime can |
| 35 | +report. |
| 36 | + |
| 37 | +## Decide first |
| 38 | + |
| 39 | +Two items change a contract; settle them before their code. |
| 40 | + |
| 41 | +- **D1 — Does an interaction stay open across its handler's returned |
| 42 | + promise?** (↔ Tracks: the Interactions track's settle span ends at |
| 43 | + `settledMs`; D1 lengthens it. Decide before Stage 1 of that plan ships a |
| 44 | + shape.) Today `withInteraction` closes the frame when the synchronous |
| 45 | + handler returns; `onClick={async () => set(await save())}` settles as |
| 46 | + `idle` at once and the wait the user experiences is invisible. Item 1 |
| 47 | + proposes observing the returned promise. That changes `settledMs` and |
| 48 | + `outcome` for existing consumers: `@sentry/solid-2` currently parents a |
| 49 | + late `"call"` record under the ended interaction span and marks it |
| 50 | + `after_settle`; with D1 that path becomes dead and should be removed, not |
| 51 | + kept as a second route. Decide whether the continuation is the same |
| 52 | + record (one interaction, longer) or a second phase on it |
| 53 | + (`continuationMs`), and whether a handler that returns a promise which |
| 54 | + never settles caps the frame (a timeout) or leaves it open. |
| 55 | +- **D2 — Are cost findings on by default in the observe build?** |
| 56 | + `HOT_SCOPE_RERUNS`, `UNSTABLE_MEMO_OUTPUT` and the rest fire "only while |
| 57 | + attribution is enabled". Item 6 adds a production-shaped one. Decide |
| 58 | + whether enabling the engine implies the cost checks (today's behavior) or |
| 59 | + whether a production consumer opts into them (`enable({ costs: true })`), |
| 60 | + since a finding nobody subscribes to still pays for its accounting. |
| 61 | + |
| 62 | +## Items |
| 63 | + |
| 64 | +### 1. Close the `await` escape in interactions |
| 65 | + |
| 66 | +- **Known:** `withInteraction(ref, fn)` in the web runtime's event dispatch |
| 67 | + opens the frame; the handler's return value is discarded. Writes after |
| 68 | + the first `await` carry no origin (the same escape `CallEvent.origin` |
| 69 | + documents: "read at dispatch"). |
| 70 | +- **Shape:** per D1, the interaction record keeps the frame open until the |
| 71 | + handler's returned promise settles; writes, holds and `"call"` records |
| 72 | + made in the continuation attribute to it. New finding |
| 73 | + `UNACKNOWLEDGED_ASYNC_HANDLER` (warn; fingerprint `ownerPath` of the |
| 74 | + handler's owner + `ref.type`): the handler awaited ≥ `holds.infoMs` with |
| 75 | + no `isPending`/`latest`/optimistic reader for anything it wrote, and no |
| 76 | + write at all before the await. This is the dead click that is not a hold. |
| 77 | +- **Idle cost:** a `then` on the returned value when it is thenable; zero |
| 78 | + for a synchronous handler. |
| 79 | +- **Proof:** a handler that awaits 300 ms then writes fires the finding |
| 80 | + once and its interaction record's `settledMs` covers the await; the same |
| 81 | + handler with `isPending(source)` read in JSX fires nothing. |
| 82 | + |
| 83 | +### 2. Stamp the browser's `interactionId` on the interaction |
| 84 | + |
| 85 | +- **Known:** the web runtime is inside the event dispatch when it opens |
| 86 | + the frame; Event Timing (`PerformanceEventTiming.interactionId`) assigns |
| 87 | + every user interaction an id, and INP is the worst of those entries. |
| 88 | +- **Shape:** `InteractionRef.interactionId?: number`, carried onto |
| 89 | + `InteractionEvent`. No finding. A consumer joins the browser's INP entry |
| 90 | + (and its Long Animation Frame `scripts[]`) to the runtime's explanation |
| 91 | + — the held write, the blocker, the acknowledgement — by id rather than |
| 92 | + by time. |
| 93 | +- **Idle cost:** one property read per dispatch where the API exists. |
| 94 | + Confirm the id is readable synchronously during dispatch (it is set on |
| 95 | + the `PerformanceEventTiming` entry, not the event; the join may need the |
| 96 | + entry's `target`/`startTime` instead — measure before promising the |
| 97 | + field). ↔ Tracks: that plan passes `at: e.timeStamp` into |
| 98 | + `dispatchAsInteraction` at the same call site; land the two stamps |
| 99 | + together. |
| 100 | +- **Proof:** a click whose Event Timing entry reports 480 ms produces an |
| 101 | + interaction record with the same id and a hold that names the blocker. |
| 102 | + |
| 103 | +### 3. Optimistic reverts |
| 104 | + |
| 105 | +- **Known:** the optimistic lane knows the shown value and the settled |
| 106 | + value; `asyncEnd`'s `prev`/`value` and the lane commit see both. |
| 107 | +- **Shape:** finding `OPTIMISTIC_REVERTED` (info; fingerprint source name): |
| 108 | + the value a `createOptimistic`/optimistic store showed differed from the |
| 109 | + value that settled — the user saw one thing, then another. `data` carries |
| 110 | + the source and the two previews (subject to the 40-char preview rule in |
| 111 | + RFC 08's PII section). |
| 112 | +- **Idle cost:** one equality check at settle. |
| 113 | +- **Proof:** an optimistic write of `"saved"` whose action settles to |
| 114 | + `"queued"` fires once; one that settles to `"saved"` fires nothing. |
| 115 | + |
| 116 | +### 4. Promote the feedback-table facts to findings |
| 117 | + |
| 118 | +- **Known:** `feedback()` already counts `flights.abandoned` (started and |
| 119 | + superseded before landing — the request-per-keystroke signature), |
| 120 | + `fallbacks.flashes` (a `<Loading>` fallback shown under 150 ms) and |
| 121 | + `interactions.heldMs`; the accounting exists. ↔ Tracks: Stage 2 of that |
| 122 | + plan promotes the same `flight`/`fallback` fold facts to public |
| 123 | + attribution records. These findings are the counted, fingerprinted form |
| 124 | + of those records; build them on the record shapes that plan defines |
| 125 | + rather than a second set. |
| 126 | +- **Shape:** `ABANDONED_FLIGHTS` (warn; fingerprint source; fires when |
| 127 | + abandoned/started crosses a ratio over a window), `FALLBACK_FLASH` (info; |
| 128 | + fingerprint boundary `ownerPath`; fires per flash, counted), and |
| 129 | + `STACKED_HOLDS` (warn; fingerprint source; N ≥ 3 interactions queued |
| 130 | + behind one in-flight source). Thresholds live beside `holds`/`longHolds` |
| 131 | + in `AttributionOptions`. |
| 132 | +- **Idle cost:** zero beyond the fold that already runs when `feedback` is |
| 133 | + imported; per D2, the findings should not force the fold on. |
| 134 | +- **Proof:** five keystrokes into a search box that each start a fetch and |
| 135 | + abandon the previous fire `ABANDONED_FLIGHTS` once with `abandoned: 4`. |
| 136 | + |
| 137 | +### 5. Server waterfall and N+1, per request |
| 138 | + |
| 139 | +- **Known:** `"invocation"` records carry `boundary` (the `<Loading>` whose |
| 140 | + pass made a direct call), `id`, `at`, `durationMs`; `"boundary"` records |
| 141 | + carry `at`, `durationMs`, `passes`. Both are on `OBSERVE.records` today. |
| 142 | +- **Shape:** two options. (a) Runtime findings `SSR_BOUNDARY_WATERFALL` |
| 143 | + (boundary B's first call began after boundary A settled, A nested in B's |
| 144 | + ancestry) and `SERVER_FUNCTION_FAN_OUT` (one boundary's pass made ≥ N |
| 145 | + calls to the same function id). (b) Leave it to consumers: the records |
| 146 | + suffice, and an adapter computing it per request keeps the runtime free |
| 147 | + of a per-request join table. Default to (b) and document the recipe in |
| 148 | + the adapter guide; revisit (a) if two consumers implement the same join. |
| 149 | +- **Idle cost:** (b) zero. |
| 150 | +- **Proof:** (b) a documented snippet against the records that names the |
| 151 | + boundary and the function; a test in `@solidjs/diagnostics` server |
| 152 | + scenario asserting the join. |
| 153 | + |
| 154 | +### 6. Wasted recomputation, measured |
| 155 | + |
| 156 | +- **Known:** `ScopeCost.wastedMs` — time spent on runs whose result |
| 157 | + compared equal — is accumulated by the costs fold; `UNSTABLE_MEMO_OUTPUT` |
| 158 | + fires in dev on a memo returning a new-but-equal object. |
| 159 | +- **Shape:** `WASTED_RECOMPUTE` (warn; fingerprint `ownerPath`): a scope |
| 160 | + whose runs over a window were ≥ 80% no-ops and cost ≥ N ms. The fix is |
| 161 | + implied by the cause: an equality boundary upstream or a narrower read. |
| 162 | + This is "why did this render" with a stopwatch, in production. Gated by |
| 163 | + D2. ↔ Tracks: that plan paints `changed: false` runs as `warning` on the |
| 164 | + Effects/Memos tracks; this is the same fact as an issue. |
| 165 | +- **Idle cost:** the costs fold, when imported; nothing otherwise. |
| 166 | +- **Proof:** a memo over a store object that is replaced with an equal |
| 167 | + copy on every tick fires once after the window; the same memo reading |
| 168 | + one property fires nothing. |
| 169 | + |
| 170 | +### 7. Graph growth as a leak detector |
| 171 | + |
| 172 | +- **Known:** the core keeps node and edge counters in the observe build |
| 173 | + (the graph-size checks `HUGE_FAN_OUT`/`HUGE_FAN_IN` read them); a router |
| 174 | + declares navigations with `withOrigin`. |
| 175 | +- **Shape:** a `"graph"` record on `OBSERVE.records` at each navigation |
| 176 | + settle: `{ nodes, roots, at, navigation }`. A monotonic climb across |
| 177 | + navigations is a leaked root or an undisposed subscription. Finding |
| 178 | + `GRAPH_GROWTH` (warn; fingerprint route pattern) when the count after |
| 179 | + leaving a route exceeds the count on entering it by a ratio over K |
| 180 | + visits. A consumer can compute this from the record alone; the finding |
| 181 | + is a convenience. |
| 182 | +- **Idle cost:** one integer per navigation. |
| 183 | +- **Proof:** a route that creates a root in an effect without disposing |
| 184 | + it fires after three visits; the same route with `onCleanup` fires |
| 185 | + nothing. |
| 186 | + |
| 187 | +### 8. Client recovery from `render/client` |
| 188 | + |
| 189 | +- **Known:** the server `"boundary"` record with `outcome: "client"` and |
| 190 | + the server error hook's `handling: "client"` say the server handed a |
| 191 | + rejected `<Loading>` fragment to the client; the client's hydration then |
| 192 | + renders the content itself. |
| 193 | +- **Shape:** a field on the client's frame/hydration record (or a new |
| 194 | + `"recovery"` record) with the boundary's hydration `id`, `at`, and the |
| 195 | + time to first content — joinable to the server record by `id`. The |
| 196 | + question it answers: "this boundary fails on the server 4% of the time |
| 197 | + and costs users 900 ms when it does." |
| 198 | +- **Idle cost:** a timestamp per recovered boundary; zero when none fail. |
| 199 | +- **Proof:** a boundary whose server read rejects produces a server record |
| 200 | + (`client`) and a client record with the same id and a positive duration. |
| 201 | + |
| 202 | +## Consumers — showing the facts where developers already look |
| 203 | + |
| 204 | +These are not runtime changes; they are the places the records should |
| 205 | +appear, and they shape which fields the records need. |
| 206 | + |
| 207 | +- **Chrome DevTools performance tracks** — owned by the Chrome Performance |
| 208 | + Tracks plan: `@solidjs/web/performance-tracks`, `enablePerformanceTracks()`, |
| 209 | + a `Solid` track group (Interactions, Scheduler, Components, Effects/Memos, |
| 210 | + Async, Holds, Navigations, Server) emitted with `console.timeStamp` / |
| 211 | + `performance.measure` the way React 19.2's tracks are, staged adapter → |
| 212 | + engine records (`flush`, `create`, `effect`, `flight`, `fallback`) → |
| 213 | + `component` mount record → dev enrichments (`performanceIssue`, |
| 214 | + `console.createTask` stacks). It is also the fastest way to _see_ what |
| 215 | + items 1–4 here change, and its Stage 4 `performanceIssue` mapping is |
| 216 | + where the findings on this page surface in Chrome's Insights. |
| 217 | +- **React DevTools parity checklist**, for the docs and for gap-finding: |
| 218 | + "highlight updates" (we have re-run records with `nodeId` → element via |
| 219 | + `subjectOf`), "why did this render" (`why()`), owner stacks |
| 220 | + (`ownerPath`), the `<Profiler>` render durations (`costs().scopes` |
| 221 | + self-time). What React DevTools cannot show and we can: holds and their |
| 222 | + acknowledgements, the interaction behind a write, the server boundary |
| 223 | + behind a wait. Keep this list current as items land. |
| 224 | +- **Sentry (`@sentry/solid-2`).** Items 1 and 2 are what the adapter is |
| 225 | + waiting on to replace `after_settle` and to join its INP span to a cause; |
| 226 | + item 4's findings become issues without adapter changes. The reviewer |
| 227 | + brief in `getsentry/sentry-javascript` (`docs/solid-2-observe.md`) points |
| 228 | + here from its open questions. |
| 229 | + |
| 230 | +## Not a runtime job |
| 231 | + |
| 232 | +Computable from today's records by any consumer; the plan does not grow |
| 233 | +runtime code for them unless two consumers implement the same join: |
| 234 | + |
| 235 | +- Server N+1 and waterfall per request (item 5b). |
| 236 | +- Call ↔ invocation wire time (`"call".durationMs − "invocation".durationMs` |
| 237 | + by `id`). |
| 238 | +- Frame produce ↔ apply latency (`"frame"` records by `id` + `version`). |
| 239 | +- Per-route hold budgets (navigation records' `holds` against a threshold |
| 240 | + the app chooses). |
| 241 | + |
| 242 | +## Out of scope here |
| 243 | + |
| 244 | +- Dev-only checks and the console reporter (`agent-diagnostics-plan.md`). |
| 245 | +- Changes to the record wire format beyond adding optional fields; the |
| 246 | + shapes shipped in rc.9 are what consumers built against. |
0 commit comments