Skip to content

Commit 5351a3e

Browse files
ryansolidcursoragentClaude via Cursor
authored
feat(signals): OPTIMISTIC_REVERTED — an optimistic value the screen showed was replaced (#3607)
* feat(signals): OPTIMISTIC_REVERTED — the person saw the guess, then the correction An optimistic override the screen displayed is replaced by a different value on two roads: the guess lifts at settle back to the committed value it covered (the action failed, or never wrote what it promised), or an authoritative value lands that differs from it. Both are the runtime doing what optimistic UI promises, so the finding is `info` and structured-channel only — a count that grows for one source is what says the guess, or the failure rate, is wrong. Judged by the node's own equality. `AttributionHooks.optimisticReverted(el, shown, truth, how)` is the seam, fired from supersedeOverride (how derived from whether a landing is staged) and from the non-superseded drop in resolveOptimisticNodes. Not covered yet, and said so: optimistic stores, and the interaction that wrote the guess (optimistic writes bypass the write hook, so the node carries no origin). The plan marks item 2 satisfied by #3580 — `at` equals the Event Timing entry's `startTime`; `interactionId` is not readable at dispatch. Size: engine +266 B, tier +38 B; the engine cap moved with a note. Co-Authored-By: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> * chore(size): re-measure OPTIMISTIC_REVERTED at landing; engine cap 31.45 -> 31.65 KB Co-authored-by: Claude via Cursor <[email protected]> * fix(signals): OPTIMISTIC_REVERTED never judges the runtime's own optimistic nodes The finding fired on every acknowledged hold: isPending()'s companion is an optimistic signal that goes true while pending and back to false at commit by design — the acknowledgement SILENT_HOLD asks for — so the repair for one finding produced another. The check now skips companions and derived overrides by the predicate the hold census already uses (`isCompanion`), and `optimisticReverts: false` disables it like the other verdicts. The regression test is the acknowledged hold itself (isPending and latest readers over a held write): silent with the guard, one false finding without it. Co-Authored-By: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]> * chore(size): re-measure the OPTIMISTIC_REVERTED companion guard; engine 31,625 B under the 31.65 KB cap The `optimisticReverts` option and the `isCompanion` skip in checkOptimisticRevert are +35 B on the engine scenario (31,590 -> 31,625 B). The cap holds; the note records the new measurement. Tier unchanged at 17,618. 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 873187b commit 5351a3e

10 files changed

Lines changed: 460 additions & 65 deletions

File tree

‎.changeset/optimistic-reverted.md‎

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+
`OPTIMISTIC_REVERTED` (info, responsiveness): an optimistic value the screen showed was replaced by a different one — reverted at settle, or superseded by the truth — with the source and both values. `AttributionHooks.optimisticReverted` is the seam; `optimisticReverts: false` disables it. The runtime's own optimistic nodes (`isPending`/`latest` companions, derived overrides) are never judged.

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

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,14 @@ any pre-await write opens the hold path, which `SILENT_HOLD` judges.
9292
once and its interaction record's `settledMs` covers the await; the same
9393
handler with `isPending(source)` read in JSX fires nothing.
9494

95-
### 2. Stamp the browser's `interactionId` on the interaction
95+
### 2. Stamp the browser's `interactionId` on the interaction — SATISFIED BY #3580
96+
97+
`interactionId` lives on the `PerformanceEventTiming` entry, delivered by a
98+
`PerformanceObserver` after the fact; it is not readable during dispatch, so
99+
a stamp was never available. #3580 made `InteractionEvent.at` the event's
100+
`timeStamp`, which equals the entry's `startTime`: the join is by equality
101+
on `at`. Nothing further to do in the runtime; the adapter recipe belongs
102+
in the docs.
96103

97104
- **Known:** the web runtime is inside the event dispatch when it opens
98105
the frame; Event Timing (`PerformanceEventTiming.interactionId`) assigns
@@ -112,7 +119,15 @@ any pre-await write opens the hold path, which `SILENT_HOLD` judges.
112119
- **Proof:** a click whose Event Timing entry reports 480 ms produces an
113120
interaction record with the same id and a hold that names the blocker.
114121

115-
### 3. Optimistic reverts
122+
### 3. Optimistic reverts — LANDED (signals; stores follow)
123+
124+
Shipped as `AttributionHooks.optimisticReverted` (two sites in
125+
`optimistic.ts`: supersession, and the drop at settle) and
126+
`OPTIMISTIC_REVERTED` (see RFC 08). Left for a follow-up: optimistic
127+
_stores_ (the overlay folds off per path in `_clearOptimisticStores`), and
128+
naming the interaction that wrote the guess — optimistic writes bypass the
129+
`write` hook today, so the node carries no origin stamp; stamping them
130+
touches the interaction accounting and is its own change.
116131

117132
- **Known:** the optimistic lane knows the shown value and the settled
118133
value; `asyncEnd`'s `prev`/`value` and the lane commit see both.

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

Lines changed: 68 additions & 61 deletions
Large diffs are not rendered by default.

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -199,6 +199,21 @@ export interface AttributionHooks {
199199
shown: boolean,
200200
transition?: Transition | null
201201
): void;
202+
/**
203+
* An optimistic override the screen displayed is being replaced by a
204+
* different value. `"superseded"`: a new authoritative value landed that
205+
* differs from the guess (tracked readers re-derive to it). `"reverted"`:
206+
* nothing new landed and the guess lifts back to the committed value it
207+
* covered (the action failed, or never wrote what it promised). `shown`
208+
* is the override as displayed. Fired when the two differ by identity;
209+
* the engine applies the node's own equality before judging.
210+
*/
211+
optimisticReverted(
212+
el: Signal<any> | Computed<any>,
213+
shown: unknown,
214+
truth: unknown,
215+
how: "superseded" | "reverted"
216+
): void;
202217
/**
203218
* The one query on the surface: the provenance a root write performed at
204219
* this moment would be stamped with — the innermost open frame (an effect

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

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -496,6 +496,15 @@ export interface AttributionOptions {
496496
* and every one of them waited on the same source. `false` disables.
497497
*/
498498
stackedHolds?: { count: number } | false;
499+
/**
500+
* Optimistic-revert finding: emit OPTIMISTIC_REVERTED (`info`) when an
501+
* optimistic value the screen showed is replaced by a different one —
502+
* reverted at settle, or superseded by the truth (default true). The
503+
* runtime's own optimistic nodes — `isPending`/`latest` companions and
504+
* derived overrides — are never judged: they are the acknowledgement
505+
* machinery, not a guess the person saw. `false` disables.
506+
*/
507+
optimisticReverts?: boolean;
499508
}
500509

501510
/** A fallback shown for less than this is a flash: feedback for a wait too short to need it. */
@@ -572,6 +581,7 @@ const defaultOptions = {
572581
graphGrowth: { visits: 3, ratio: 1.25 } as { visits: number; ratio: number } | false,
573582
abandonedFlights: { count: 3, windowMs: 1000 } as { count: number; windowMs: number } | false,
574583
fallbackFlashes: true,
584+
optimisticReverts: true,
575585
stackedHolds: { count: 3 } as { count: number } | false
576586
};
577587
let options: typeof defaultOptions = { ...defaultOptions };
@@ -2908,6 +2918,52 @@ function checkLongHold(event: HoldEvent, subject: Signal<any>): void {
29082918
if (severity === "warn") reportDiagnostic(entry);
29092919
}
29102920

2921+
/**
2922+
* The person saw the guess, then the correction. An optimistic value is a
2923+
* promise the UI makes about the outcome; when the outcome differs — the
2924+
* action failed and the override lifted back to the old value, or the
2925+
* source answered with something else — the screen changes twice for one
2926+
* intent. Expected on failure and correct by construction (the override
2927+
* reverts; that is the feature), so `info`: a count that grows for one
2928+
* source is what says the guess, or the failure rate, is wrong. Judged by
2929+
* the node's own equality, so a structurally equal replacement is not a
2930+
* revert.
2931+
*/
2932+
function checkOptimisticRevert(
2933+
el: Signal<any> | Computed<any>,
2934+
shown: unknown,
2935+
truth: unknown,
2936+
how: "superseded" | "reverted"
2937+
): void {
2938+
// The runtime's own optimistic nodes are not guesses the person saw: an
2939+
// `isPending()` companion goes true while pending and back to false at
2940+
// commit by design — the acknowledgement SILENT_HOLD asks for — and a
2941+
// derived override promotes rather than reverts. Same predicate the hold
2942+
// census uses to skip them.
2943+
if (!options.optimisticReverts || isCompanion(el)) return;
2944+
const equals = (el as { _equals?: false | ((a: unknown, b: unknown) => boolean) })._equals;
2945+
if (equals && equals(shown, truth)) return;
2946+
const source = nodeName(el);
2947+
const message =
2948+
`[OPTIMISTIC_REVERTED] the optimistic value of ${source} showed ${preview(shown)}; it ` +
2949+
`${how === "superseded" ? "settled to" : "reverted to"} ${preview(truth)}. The person saw ` +
2950+
`the guess, then the correction. A revert on failure is the feature; one that recurs says ` +
2951+
`the guess is wrong for this input or the action fails often — show the failure where the ` +
2952+
`value renders (the action's catch, an Errored boundary) rather than letting the value ` +
2953+
`snap back on its own.`;
2954+
emitDiagnostic(
2955+
{
2956+
code: "OPTIMISTIC_REVERTED",
2957+
kind: "responsiveness",
2958+
severity: "info",
2959+
message,
2960+
nodeName: source,
2961+
data: { source, shown: preview(shown), truth: preview(truth), how }
2962+
},
2963+
el
2964+
);
2965+
}
2966+
29112967
// --- Graph growth -----------------------------------------------------------------
29122968

29132969
/** Per route: the graph's size at its last `visits` settles, oldest first. */
@@ -4129,6 +4185,9 @@ const engineHooks: AttributionHooks = {
41294185
// The folds hear the show at its display (see trackFallback), not here.
41304186
trackFallback(boundary, tree, shown, transition ?? null);
41314187
},
4188+
optimisticReverted(el, shown, truth, how) {
4189+
checkOptimisticRevert(el, shown, truth, how);
4190+
},
41324191
currentOrigin() {
41334192
return ambientOrigin();
41344193
}

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,7 @@ export type DiagnosticCode =
7979
| "ABANDONED_FLIGHTS"
8080
| "FALLBACK_FLASH"
8181
| "STACKED_HOLDS"
82+
| "OPTIMISTIC_REVERTED"
8283
| "EFFECT_WRITES_OWN_SOURCE"
8384
| "EFFECT_RELAY_TEAR"
8485
| "IMMUTABLE_UPDATE_IN_STORE"

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

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -256,7 +256,13 @@ function resolveOptimisticNodes(nodes: OptimisticNode[]): void {
256256
node._value !== unwrapOverride(prevOverride)
257257
) {
258258
if (derived) node._value = unwrapOverride(prevOverride);
259-
else insertSubs(node, true);
259+
else {
260+
// The guess lifts and what was beneath it differs: the screen
261+
// changes from the override to the committed value.
262+
if (__OBSERVE__ && attrHooks !== null)
263+
attrHooks.optimisticReverted(node, unwrapOverride(prevOverride), node._value, "reverted");
264+
insertSubs(node, true);
265+
}
260266
}
261267
node._transition = null;
262268
if (node._x !== null) node._x._overrideOwner = null;
@@ -323,6 +329,16 @@ function supersedeOverride(el: OptimisticNode, value: unknown): void {
323329
// 0 is mainline (no action): always the current question.
324330
if (origin && origin < el._x!._overrideStamp) return;
325331
el._config |= CONFIG_OVERRIDE_SUPERSEDED;
332+
// A fresh landing is staged in `_pendingValue` (landOnOverride) or is the
333+
// truth endOptimism read from it; the committed value with nothing staged
334+
// is the value the guess covered — the screen goes back, not forward.
335+
if (__OBSERVE__ && attrHooks !== null)
336+
attrHooks.optimisticReverted(
337+
el,
338+
unwrapOverride(el._x!._overrideValue),
339+
value,
340+
el._pendingValue === NOT_PENDING && value === el._value ? "reverted" : "superseded"
341+
);
326342
const lane = el._x?._optimisticLane;
327343
if (lane) {
328344
const root = findLane(lane);

0 commit comments

Comments
 (0)