Skip to content

Commit 49887e1

Browse files
docs(plans): responsiveness findings — the facts worth emitting through the observe tier
The backlog that follows the observe tier's wiring: eight items, each with what the runtime already knows, the finding or record shape, the idle cost, and the proof. Two decisions first (an interaction staying open across its handler's promise; whether cost findings are on by default in observe). Reconciled with the Chrome Performance Tracks plan, which owns the DevTools panel adapter and the engine records it needs; the meeting points are marked. Co-Authored-By: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]>
1 parent f2bd662 commit 49887e1

1 file changed

Lines changed: 246 additions & 0 deletions

File tree

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
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

Comments
 (0)