fix: preserve fragment data identity across snapshot updates

[nyanrus]

createFragment's result observer pre-clears data to undefined inside the same batch() that subsequently applies the reconciled snapshot. Because reconcile({ key: "__id", merge: true }) only walks the existing tree in place when the current value is wrappable (solid-js/store's modifiers.ts — the early if (!isWrappable(state) || !isWrappable(v)) return v;), the pre-clear guarantees reconcile is always reconciling against undefined and produces a fresh top-level reference on every snapshot. The identity-preservation contract that key: "__id", merge: true is supposed to provide is silently defeated.

This PR drops the shared pre-clears so each branch of the state switch owns its full state transition and reconcile can merge against the live store tree. Behaviour is otherwise unchanged.

Fixes #70 . Also resolves the "loading" direction discussed in # in favour of stale-while-revalidate (matching createLazyLoadQuery's observer) — if the maintainer prefers a different direction there, a one-case follow-up is straightforward.

Why this matters

Identity-sensitive consumers — most prominently <Show keyed when={data()}> — re-mount their subtree on every change to the fragment data's top-level reference. Today that's every snapshot tick, including pure field updates (a single reaction toggle, a share count delta, a polled cursor refresh). In a real fediverse timeline rendering ~25 cards × multiple Kobalte primitives per card (Tooltip, Popover, DropdownMenu, HoverCard), this dominates CPU and heap during interaction.

Concrete trace from a hackers.pub /feed recording (Firefox profiler, 30 s with one composer open/close and one reaction toggle):

• hackers.pub process heap: +10 MB/s sustained during interaction (vs. ~0 MB/s when idle on the same route).
• _$createComponent dominated the leaf-sample list, with @kobalte/core/dist/chunk/* at ~1,200 inclusive samples per ~1,733 hackers.pub-thread samples.

<Show keyed> is the correct primitive for this use case (non-keyed risks the documented "Stale read from <Show>" race when the fragment flips to null inside the same tick as a downstream reactive read), so the fix needed to be at the snapshot-write site rather than at every consumer.

What changed

src/primitives/createFragment.ts — the next handler is restructured so each branch owns its full state transition with no shared pre-clears:

   next(res) {
     queueMicrotask(() => {
       batch(() => {
-        setResult("data", undefined);
-        setResult("error", undefined);
-
         switch (res.state) {
           case "ok":
             setResult("error", undefined);
             setResult("pending", false);
             setResult("data", reconcile(cleanSnapshot(res.value), { key: "__id", merge: true }));
             break;
           case "error":
             setResult("data", undefined);
             setResult("error", res.error);
             setResult("pending", false);
             break;
         }
       });
     });
   }

State machine after the change:

res.state	data	error	pending
ok	reconcile(value)	undefined	false
error	undefined	res.error	false
loading	unchanged	unchanged	unchanged

Notes:

• All updates remain inside the same batch(), so observers never see intermediate state. The previous shared pre-clears were never externally observable; they only mattered to the next reconcile call within the same batch.
• The "error" arm still explicitly resets data to undefined, which is intentional: an errored fragment shouldn't keep its previous successful data visible.
• The "loading" state intentionally has no case. Leaving the result store untouched gives consumers stale-while-revalidate behaviour during transient missing-data snapshots rather than flashing an empty UI, and matches createLazyLoadQuery's observer in this same package, which has always handled only the "ok" and "error" states. See # for the discussion of this direction.

Test plan

• Existing test suite passes (pnpm test).
• In a downstream consumer (hackers.pub /feed), verify with a Firefox / Chrome profiler that toggling a reaction on a single post no longer re-mounts every Kobalte primitive on the timeline, and that hackers.pub-process heap growth during interaction falls from ~+10 MB/s to under ~1 MB/s.
• Verify that fragment errors still clear stale data (the "error" arm intentionally preserves the setResult("data", undefined)).
• Verify that fragment key transitions (key() returning a new key, or returning null) still produce the expected undefined data — this path is unaffected (still goes through the resource generator's explicit setResult("data", undefined) in the if (!k) branch around line 187).

Compatibility

• No public API changes.
• Identity preservation is a behavioural change in the sense that the top-level reference of data will now be stable across snapshots for unchanged records, which is the documented contract of reconcile({ key, merge: true }). Any consumer that depended on the previous behaviour (fresh reference on every update) was detecting fragment-data updates at the wrong granularity and should be reading the specific field that changed instead.
• "loading" behaviour changes from "implicitly clear data and error" (via the pre-clears) to "no-op" (stale-while-revalidate). This brings createFragment into alignment with createLazyLoadQuery. See # for the rationale and alternatives.

AI disclosure

Investigation and patch developed with Claude (Opus 4.7) as a programming assistant. The reasoning behind the change — tracing through reconcile / applyState in solid-js/store and Show in solid-js's flow control to confirm that the pre-clear breaks identity preservation and that <Show keyed> consequently re-mounts on every snapshot — was verified by reading the upstream source. The commit message and this PR description include the relevant pointers into that source for review.

[changeset-bot]

🦋 Changeset detected

Latest commit: ac5b256

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
solid-relay	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[gemini-code-assist]

Code Review

This pull request modifies createFragmentInternal to prevent pre-clearing data to undefined before reconciling, which preserves object identity for unchanged records and avoids unnecessary re-mounts in consumers. The reviewer suggested moving setResult("error", undefined) back into the "ok" case of the switch block to avoid a redundant write during the "error" state.

[gemini-code-assist]

By keeping setResult("error", undefined) at the top of the batch, it is unconditionally executed for both "ok" and "error" states. In the "error" state, this results in a redundant write where error is first set to undefined and then immediately overwritten with res.error inside the switch block. Moving setResult("error", undefined) into the "ok" case avoids this redundant write and keeps the state transitions clean and explicit.

Suggested change

	setResult("error", undefined);
	switch (res.state) {
	case "ok":
	setResult("error", undefined);
	setResult("pending", false);
	setResult("data", reconcile(cleanSnapshot(res.value), { key: "__id", merge: true }));
	break;
	switch (res.state) {
	case "ok":
	setResult("error", undefined);
	setResult("pending", false);
	setResult("data", reconcile(cleanSnapshot(res.value), { key: "__id", merge: true }));
	break;

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/solid-relay@68

commit: d3c271c

[codecov]

Codecov Report

❌ Patch coverage is 0% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.29%. Comparing base (1bfb1a9) to head (ac5b256).

Files with missing lines	Patch %	Lines
src/primitives/createFragment.ts	0.00%	5 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #68      +/-   ##
==========================================
- Coverage   91.95%   91.29%   -0.66%     
==========================================
  Files          20       20              
  Lines         721      724       +3     
  Branches      137      138       +1     
==========================================
- Hits          663      661       -2     
- Misses         50       55       +5     
  Partials        8        8              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.