Skip to content

Commit c1b68d9

Browse files
ryansolidcursoragentClaude via Cursor
authored
feat(signals): interactions wait for the handler's promise; UNTRACKED_ASYNC_HANDLER (#3604)
* feat(signals): an interaction waits for its handler's promise; UNTRACKED_ASYNC_HANDLER names the dead click no hold could judge `onClick={async () => setResult(await save())}` returns a promise and continues past the interaction frame. The record settled `idle` the moment the handler returned, so the wait the person experienced — the whole round-trip — was invisible to every verdict: no root write before the `await` means no hold opened, and SILENT_HOLD judges holds. `withInteraction` now hands the handler's return value to the engine (`AttributionHooks.interactionEnd(returned)`); a thenable keeps the `InteractionEvent` open until it settles either way, capped at 10s so a promise that never settles cannot pin a record. The record carries `continuationMs` (handler return → settle) and `settledMs` covers it, so a consumer's span spans the wait. Writes in the continuation run with no frame on the stack and stay unattributed; only the duration is claimed. At settle, `UNTRACKED_ASYNC_HANDLER` fires when the handler took no other road: no write before the await (a pending flag or optimistic value is the acknowledgement, and its hold is SILENT_HOLD's to judge) and no `action()` step under the frame (an action's steps stay attributed across yields). Hold thresholds, since it is the same wait; off with `holds: false`. The message carries the two repairs: make the work an action, or write the pending state first. Size: the tier +65 B (the return value through the seam), the engine +384 B (the wait, the cap timer, the check and its text); caps moved with notes. RFC 08 and the skill guide document the code; the plan records D1 and D2 as decided. Co-Authored-By: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> * test(signals): judge UNTRACKED_ASYNC_HANDLER's threshold on a test-owned clock "stays quiet below the hold threshold, and info between the two" raced the wall clock: a 1ms `await` had to settle under `infoMs: 10`, and on the coverage-instrumented CI job (12× slower than a local run) it did not. The engine reads `performance.now()` at the handler's return and at its promise's settle, so the test now owns that clock (#3598's pattern): it stands still unless the handler advances it — 9ms for the quiet side, 30ms for the info side — and both `continuationMs` values are asserted exactly. Real timers still drive the await; only the stamps are the test's. Co-authored-by: Claude via Cursor <[email protected]> * chore(size): re-measure the UNTRACKED_ASYNC_HANDLER engine note at landing 29,408 B against next's 29,018 on the rebased tree (+390 B, 42 B under the 29.45 KB cap); the PR's figures were taken on the pre-#3630 base. Co-authored-by: Claude via Cursor <[email protected]> --------- Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Claude via Cursor <[email protected]>
1 parent e77087a commit c1b68d9

9 files changed

Lines changed: 326 additions & 13 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@solidjs/signals": patch
3+
---
4+
5+
An interaction whose handler returns a promise stays open until it settles (`InteractionEvent.continuationMs`, `settledMs` covers the wait, 10s cap), and `UNTRACKED_ASYNC_HANDLER` names a handler that awaited past its frame with no write before the `await` and no `action()` — the dead click no hold could judge. `AttributionHooks.interactionEnd` receives the handler's return value.

‎documentation/plans/responsiveness-findings-plan.md‎

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,13 @@ report.
3838

3939
Two items change a contract; settle them before their code.
4040

41-
- **D1 — Does an interaction stay open across its handler's returned
42-
promise?** (↔ Tracks: the Interactions track's settle span ends at
41+
- **D1 — DECIDED (2026-09-22): yes, same record.** A thenable return keeps
42+
the `InteractionEvent` open until it settles (cap 10s); `settledMs` covers
43+
the wait and `continuationMs` names it; `outcome` is unchanged (writes in
44+
the continuation are not attributed — no frame). The finding is
45+
`UNTRACKED_ASYNC_HANDLER`, on the hold thresholds; an `action()` step or a
46+
write before the `await` clears it. `@sentry/solid-2`'s `after_settle`
47+
path is now dead and should go. Original question: (↔ Tracks: the Interactions track's settle span ends at
4348
`settledMs`; D1 lengthens it. Decide before Stage 1 of that plan ships a
4449
shape.) Today `withInteraction` closes the frame when the synchronous
4550
handler returns; `onClick={async () => set(await save())}` settles as
@@ -52,7 +57,9 @@ Two items change a contract; settle them before their code.
5257
record (one interaction, longer) or a second phase on it
5358
(`continuationMs`), and whether a handler that returns a promise which
5459
never settles caps the frame (a timeout) or leaves it open.
55-
- **D2 — Are cost findings on by default in the observe build?**
60+
- **D2 — DECIDED by #3580:** `checks?: boolean` on `enable()` (default
61+
`true`), combined most-demanding across holds; a records-only consumer
62+
passes `checks: false`. Item 6 lands under that switch. Original question:
5663
`HOT_SCOPE_RERUNS`, `UNSTABLE_MEMO_OUTPUT` and the rest fire "only while
5764
attribution is enabled". Item 6 adds a production-shaped one. Decide
5865
whether enabling the engine implies the cost checks (today's behavior) or
@@ -61,7 +68,12 @@ Two items change a contract; settle them before their code.
6168

6269
## Items
6370

64-
### 1. Close the `await` escape in interactions
71+
### 1. Close the `await` escape in interactions — LANDED
72+
73+
Shipped as `interactionEnd(returned)` + `InteractionEvent.continuationMs` +
74+
`UNTRACKED_ASYNC_HANDLER` (see RFC 08). The finding requires _no_ write
75+
before the await rather than "no acknowledged reader for what it wrote":
76+
any pre-await write opens the hold path, which `SILENT_HOLD` judges.
6577

6678
- **Known:** `withInteraction(ref, fn)` in the web runtime's event dispatch
6779
opens the frame; the handler's return value is discarded. Writes after

‎documentation/solid-2.0/08-dev-diagnostics.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -526,6 +526,14 @@ The hold _was_ acknowledged and still outlasted what a stale screen should carry
526526

527527
The design point: a hold is the stale-while-revalidate tool, right when the old screen stays useful for the wait. Past that, the honest UI is a fallback — which a `Loading` boundary provides only when it has not revealed yet or its `on` prop changed; a revealed boundary with no `on` keeps the old content, which _is_ the hold. So the repair is `on`, a fresh boundary, or making the data fast (preload, cache), never removing the acknowledgement. Silent long holds are not double-reported: they stay one `SILENT_HOLD` with the same repair appended. `feedback().sources[].long`/`longMs` counts long tails at the table level, acknowledged or not.
528528

529+
#### `UNTRACKED_ASYNC_HANDLER`
530+
531+
**Message:** "[click on button#save]'s handler awaited for 430ms after returning and wrote nothing before the await, so nothing on screen could show the wait and no hold was opened for the engine to judge — the interaction was dead for 430ms. Make the async work an `action()`: its steps stay attributed to this click across yields, the writes it makes are held and the hold is judged (`SILENT_HOLD`). Or write the pending state before the await — a `createOptimistic(false)` "saving" flag the UI reads."
532+
533+
The dead click that is not a hold. `onClick={async () => setResult(await save())}` returns a promise and continues past the interaction frame; the handler made no root write before its first `await`, so no hold opened, nothing could acknowledge one, and the engine's other verdicts never see the wait. `withInteraction` hands the handler's return value to the engine (`interactionEnd(returned)`); a thenable keeps the `InteractionEvent` open until it settles (either way — a rejection ended the wait too), capped at `ASYNC_HANDLER_CAP_MS` (10s) so a promise that never settles cannot pin a record. The record then carries `continuationMs` (handler return → settle) and `settledMs` covers it, so a consumer's interaction span spans the wait the person experienced. The continuation runs with no frame on the stack, so writes it makes are _not_ attributed to the interaction — only its duration is; the join for work dispatched synchronously in the handler (a `"call"` record's `origin`) is unchanged.
534+
535+
The finding fires at settle when the handler took no other road: no root write before returning (a write is the acknowledgement — a pending flag, an optimistic value — and its hold, if any, is judged by `SILENT_HOLD`), and no `action()` step under the frame (an action's steps stay attributed across yields and its holds are judged). Same thresholds as holds — it is the same wait: `info` from `holds.infoMs` (100ms), `warn` from `holds.warnMs` (200ms); off with `holds: false`. `data`: `interaction` (`type`, `target`), `continuationMs`, `capped`. No subject: an interaction has no node.
536+
529537
### Server rendering (`ssr`, `head`)
530538

531539
The server runtime reports on the same channel. Two groups, two tiers. **Findings** are facts about a render whichever tier is running — an error a boundary contained, work the stream threw away, an error the server-function wire replaced. They ride `OBSERVE.diagnostics` in observe and dev builds (a production observability consumer subscribes to them; in dev they also print) and fold out of prod entirely. **Checks** are guidance for a developer at a console — a write on the server, an invalid preload descriptor — and exist only in the dev build, where they print like any client warning. Every entry carries `ownerPath` when it fired inside a component: on the server the component wrapper labels its owner `<Name>` exactly as the client's does, so `in <App> › <Page>` reads the same on both sides. Codes that already exist on the client (`ASYNC_OUTSIDE_LOADING_BOUNDARY`, `UNRECOGNIZED_INSERT_VALUE`) are shared, not duplicated; `data.side` or the message tells the platforms apart where it matters.
@@ -844,6 +852,7 @@ The runtime derives a request's trace itself in every tier — the W3C `tracepar
844852
| `UNSTABLE_LIST_IDENTITY` | warn | perf | `mapArray`/`For` recreated rows for equivalent items (attribution enabled) |
845853
| `SILENT_HOLD` | info/warn | responsiveness | Write held 100ms+/200ms+ by pending async with no on-screen acknowledgement (attribution enabled) |
846854
| `LONG_HOLD` | info/warn | responsiveness | Acknowledged hold whose tail (last input → commit) ran 500ms+/1000ms+ (attribution enabled) |
855+
| `UNTRACKED_ASYNC_HANDLER` | info/warn | responsiveness | Handler awaited 100ms+/200ms+ past its frame with no write before the `await` and no `action()`: a dead click no hold could judge (attribution enabled) |
847856
| `SSR_RENDER_ERROR_CONTAINED` | error | ssr | Server render error routed by a boundary: `data.handling` fallback / client / failed (observe + dev) |
848857
| `SSR_SUBTREE_ABANDONED` | warn | ssr | A failed fragment's pending descendants were discarded (observe + dev) |
849858
| `SSR_STREAM_ABANDONED` | warn | ssr | Response stream cancelled or sink failed with fragments pending (observe + dev) |

‎packages/signals/src/core/attribution-hooks.ts‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,13 @@ export interface AttributionHooks {
2626
* nest strictly (synchronous dispatch), so the engine keeps a stack.
2727
*/
2828
interactionStart(ref: InteractionRef): void;
29-
interactionEnd(): void;
29+
/**
30+
* The handler returned. `returned` is its return value: a thenable means
31+
* the handler continues past this frame (`async () => { await … }`), and
32+
* the engine may keep the interaction's record open until it settles —
33+
* the wait the person experiences is that continuation, not the frame.
34+
*/
35+
interactionEnd(returned?: unknown): void;
3036
/**
3137
* `withOrigin` opened a declared-origin frame: root writes until the
3238
* matching `originEnd` are the unit of work `ref` describes (a router's
@@ -302,10 +308,11 @@ export function withInteraction<T>(ref: InteractionRef, fn: () => T): T {
302308
const hooks = attrHooks;
303309
if (hooks === null) return fn();
304310
hooks.interactionStart(ref);
311+
let returned: T | undefined;
305312
try {
306-
return fn();
313+
return (returned = fn());
307314
} finally {
308-
hooks.interactionEnd();
315+
hooks.interactionEnd(returned);
309316
}
310317
}
311318

‎packages/signals/src/core/attribution.ts‎

Lines changed: 97 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -660,10 +660,10 @@ function interactionStart(ref: InteractionRef): void {
660660
openInteraction(origin, opened);
661661
}
662662

663-
function interactionEnd(): void {
663+
function interactionEnd(returned?: unknown): void {
664664
const closing = currentInteraction;
665665
currentInteraction = interactionStack.length ? interactionStack.pop()! : null;
666-
if (closing !== null) closeInteraction(closing);
666+
if (closing !== null) closeInteraction(closing, returned);
667667
}
668668

669669
/** The interaction an origin runs under (itself, when it is one). */
@@ -3209,6 +3209,15 @@ export interface InteractionEvent {
32093209
*/
32103210
settledMs?: number;
32113211
outcome?: "idle" | "committed" | "held";
3212+
/**
3213+
* The handler returned a thenable (`async () => { await save(); … }`) and
3214+
* the record waited for it: handler return → the promise settling, in
3215+
* milliseconds, capped at `ASYNC_HANDLER_CAP_MS`. The continuation runs
3216+
* with no frame on the stack, so writes it makes are not attributed to
3217+
* this interaction — only its duration is. Absent when the handler
3218+
* returned synchronously.
3219+
*/
3220+
continuationMs?: number;
32123221
/**
32133222
* The frame object every downstream fact carries — `ChangeOrigin.interaction`
32143223
* on writes and frames, `RerunEvent.interaction`, `HoldEvent.interaction`,
@@ -3231,6 +3240,10 @@ interface InteractionState {
32313240
held: boolean;
32323241
/** Root writes to excluded subjects (the observer's own store): not the app's. */
32333242
excludedWrites: number;
3243+
/** The handler returned a thenable that has not settled; the record waits for it. */
3244+
awaiting: boolean;
3245+
/** An action step ran under the frame: the handler's async work is an action's, tracked as such. */
3246+
actioned: boolean;
32343247
}
32353248
const interactionStates = new WeakMap<ChangeOrigin, InteractionState>();
32363249
/** Opened, not yet settled. */
@@ -3262,24 +3275,100 @@ function openInteraction(frame: ChangeOrigin, opened: number): void {
32623275
writeDrain: drainSeq,
32633276
heldIn: new Set(),
32643277
held: false,
3265-
excludedWrites: 0
3278+
excludedWrites: 0,
3279+
awaiting: false,
3280+
actioned: false
32663281
};
32673282
interactionStates.set(frame, state);
32683283
openInteractions.add(state);
32693284
interactionLog.push(event);
32703285
if (interactionLog.length > options.historyLimit) interactionLog.shift();
32713286
}
32723287

3288+
/**
3289+
* How long the record waits on a handler's returned promise before settling
3290+
* without it: a promise that never settles (a hung request, a listener
3291+
* awaiting an event that never comes) must not keep the record open forever.
3292+
*/
3293+
const ASYNC_HANDLER_CAP_MS = 10_000;
3294+
32733295
/** interactionEnd: the handler returned. */
3274-
function closeInteraction(frame: ChangeOrigin): void {
3296+
function closeInteraction(frame: ChangeOrigin, returned?: unknown): void {
32753297
const state = interactionStates.get(frame);
32763298
if (state === undefined) return;
32773299
state.open = false;
32783300
const end = now();
32793301
state.event.handlerMs = end - state.opened;
3302+
// `async () => { await save(); set(…) }` returns a promise and continues
3303+
// past the frame; the person's wait is that continuation. The record stays
3304+
// open until it settles (or the cap), then judges whether anything on
3305+
// screen could have shown the wait.
3306+
const thenable =
3307+
returned !== null &&
3308+
(typeof returned === "object" || typeof returned === "function") &&
3309+
typeof (returned as PromiseLike<unknown>).then === "function"
3310+
? (returned as PromiseLike<unknown>)
3311+
: null;
3312+
if (thenable !== null) {
3313+
state.awaiting = true;
3314+
let done = false;
3315+
let timer: ReturnType<typeof setTimeout> | undefined;
3316+
const settle = (): void => {
3317+
if (done) return;
3318+
done = true;
3319+
if (timer !== undefined) clearTimeout(timer);
3320+
if (!openInteractions.has(state)) return;
3321+
state.awaiting = false;
3322+
const at = now();
3323+
state.event.continuationMs = at - end;
3324+
checkUntrackedAsyncHandler(state);
3325+
maybeSettleInteraction(state, at);
3326+
};
3327+
timer = setTimeout(settle, ASYNC_HANDLER_CAP_MS);
3328+
// A pending cap must not hold a Node process (tests, SSR harnesses) open.
3329+
(timer as { unref?: () => void }).unref?.();
3330+
// Both branches: a rejected handler promise still ended the wait.
3331+
thenable.then(settle, settle);
3332+
return;
3333+
}
32803334
maybeSettleInteraction(state, end);
32813335
}
32823336

3337+
/**
3338+
* The handler awaited past its frame with nothing in the graph carrying the
3339+
* wait: no root write before the `await` (a pending flag, an optimistic
3340+
* value) and no action step (an action's steps stay attributed across
3341+
* yields, and its holds are judged by SILENT_HOLD). From the person's side
3342+
* the click did nothing for `continuationMs`; from the engine's side the
3343+
* wait is invisible — no hold opened, so no hold could be acknowledged.
3344+
* Thresholds are the hold thresholds: it is the same wait.
3345+
*/
3346+
function checkUntrackedAsyncHandler(state: InteractionState): void {
3347+
const cfg = options.holds;
3348+
if (cfg === false) return;
3349+
const event = state.event;
3350+
const ms = event.continuationMs!;
3351+
if (state.actioned || event.writes > 0 || ms < cfg.infoMs) return;
3352+
const actor = formatOrigin(event.origin);
3353+
const message =
3354+
`[UNTRACKED_ASYNC_HANDLER] ${actor}'s handler awaited ${ms.toFixed(0)}ms past its frame with no ` +
3355+
`write before the await: no hold opened, so nothing on screen could show the wait — the ` +
3356+
`interaction was dead for ${ms.toFixed(0)}ms. Make the async work an action() (its steps stay ` +
3357+
`attributed across yields and its hold is judged), or write the pending state first: a ` +
3358+
`createOptimistic(false) "saving" flag the UI reads.`;
3359+
const severity = ms >= cfg.warnMs ? "warn" : "info";
3360+
const data: Record<string, unknown> = {
3361+
interaction: { type: event.name, target: event.target },
3362+
continuationMs: ms,
3363+
capped: ms >= ASYNC_HANDLER_CAP_MS
3364+
};
3365+
const entry = emitDiagnostic(
3366+
{ code: "UNTRACKED_ASYNC_HANDLER", kind: "responsiveness", severity, message, data },
3367+
null
3368+
);
3369+
if (severity === "warn") reportDiagnostic(entry);
3370+
}
3371+
32833372
/** The open record a frame runs under, if any. */
32843373
function openInteractionOf(origin: ChangeOrigin | undefined): InteractionState | undefined {
32853374
const interaction = interactionOf(origin);
@@ -3347,7 +3436,7 @@ function settleInteractionsHeld(t: Transition, hold: HoldEvent | undefined): voi
33473436

33483437
function maybeSettleInteraction(state: InteractionState, end: number = now()): void {
33493438
const event = state.event;
3350-
if (state.open || state.heldIn.size > 0) return;
3439+
if (state.open || state.awaiting || state.heldIn.size > 0) return;
33513440
// A drain must have committed the last write (the handler's, or a redirect
33523441
// hop's after the click's own drain) — the handler returning is not the
33533442
// screen having it.
@@ -3579,6 +3668,9 @@ const engineHooks: AttributionHooks = {
35793668
if (interaction === undefined && !actionInteractions.has(it)) {
35803669
interaction = currentInteraction ?? undefined;
35813670
actionInteractions.set(it, interaction);
3671+
// The handler's async work is an action's: tracked across yields.
3672+
const state = interaction !== undefined ? interactionStates.get(interaction) : undefined;
3673+
if (state !== undefined) state.actioned = true;
35823674
}
35833675
pushFrame("action", name, interaction);
35843676
},

‎packages/signals/src/core/dev.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,7 @@ export type DiagnosticCode =
7373
| "HOT_SCOPE_FANOUT"
7474
| "SILENT_HOLD"
7575
| "LONG_HOLD"
76+
| "UNTRACKED_ASYNC_HANDLER"
7677
| "EFFECT_WRITES_OWN_SOURCE"
7778
| "EFFECT_RELAY_TEAR"
7879
| "IMMUTABLE_UPDATE_IN_STORE"

0 commit comments

Comments
 (0)