@opentf/web 0.6.0 → 0.8.0

package/core/signals.js

@@ -15,6 +15,8 @@ import { reportError } from "./errors.js";
 
 /** The consumer (effect or computed) currently executing, if any. */
 let activeConsumer = null;
+/** Disposer collector of the innermost `scope()` currently building, if any. */
+let activeScope = null;
 /** Depth of nested `batch()` calls; effects flush when this returns to 0. */
 let batchDepth = 0;
 /** Re-entrancy guard for the flush loop. */
@@ -149,6 +151,36 @@ export function computed(fn) {
   };
 }
 
+/**
+ * Collect ownership of the effects created while `fn` runs. Returns
+ * `{ result, dispose }`: `dispose()` stops every effect `fn` created (including
+ * ones created in nested calls, unless an inner `scope()` claimed them first).
+ *
+ * This is how dynamic regions own their bindings: a keyed-list item, a
+ * conditional branch, or a mounted page builds its DOM inside a scope, and
+ * evicting/swapping/unmounting disposes the scope — otherwise the bindings'
+ * effects would stay subscribed to their signals forever (a leak that also
+ * makes every later write pay for dead subscribers).
+ */
+export function scope(fn) {
+  const disposers = [];
+  const prev = activeScope;
+  activeScope = disposers;
+  let result;
+  try {
+    result = fn();
+  } finally {
+    activeScope = prev;
+  }
+  return {
+    result,
+    dispose() {
+      for (const d of disposers) d();
+      disposers.length = 0;
+    },
+  };
+}
+
 /**
  * Run `fn` immediately, tracking the signals it reads, and re-run it whenever
  * any of them change. `fn` may return a cleanup function, which runs before the
@@ -166,22 +198,31 @@ export function effect(fn) {
       runCleanup(node);
       clearSources(node);
       const prev = activeConsumer;
+      const prevScope = activeScope;
+      // Effects created during a run belong to whoever the run's body says they
+      // do (an explicit inner scope()), never to whatever scope happens to be
+      // ambient — a flush-time re-run must not donate its children to an
+      // unrelated scope that was open when the write occurred.
       activeConsumer = node;
+      activeScope = null;
       try {
         const result = node.fn();
         if (typeof result === "function") node.cleanup = result;
       } finally {
         activeConsumer = prev;
+        activeScope = prevScope;
       }
     },
   };
   node.run();
-  return function dispose() {
+  const dispose = function dispose() {
     if (node.disposed) return;
     node.disposed = true;
     runCleanup(node);
     clearSources(node);
   };
+  if (activeScope) activeScope.push(dispose);
+  return dispose;
 }
 
 function runCleanup(node) {

package/package.json

@@ -1,13 +1,20 @@
 {
   "name": "@opentf/web",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "The native-first OTF Web runtime — signal-based reactivity and zero-VDOM DOM operations, paired with the IR-based compiler.",
   "type": "module",
   "exports": {
     ".": "./index.js",
     "./signals": "./core/signals.js",
     "./runtime": "./runtime/index.js",
-    "./server": "./server/index.js"
+    "./server": {
+      "types": "./server/index.d.ts",
+      "default": "./server/index.js"
+    },
+    "./server/adapters/node": {
+      "types": "./server/adapters/node.d.ts",
+      "default": "./server/adapters/node.js"
+    }
   },
   "files": [
     "index.js",

package/runtime/dom.js

@@ -2,7 +2,8 @@
 // also back runtime-driven updates (reactive text/attributes). No virtual DOM,
 // no diffing — just direct, fine-grained DOM writes wired to signals.
 
-import { effect, signal } from "../core/signals.js";
+import { effect, scope, signal } from "../core/signals.js";
+import { claimRegionEnd, claimRegionStart } from "./hydrate.js";
 
 // Attribute names that must be assigned as JS properties (not setAttribute) for
 // correct behavior. Mirrors the set the old runtime relied on (core/constants).
@@ -253,16 +254,62 @@ function toNodes(value) {
  * Returns the effect disposer.
  */
 export function bindChild(anchor, fn) {
-  let current = [];
-  return effect(() => {
-    const next = toNodes(fn());
+  return childEffect(anchor, fn, [], false);
+}
+
+/**
+ * Hydrate a server-rendered conditional / dynamic-node region (docs/HYDRATION.md §3.1,
+ * 2.1b). The cursor `cur` is at the `<!--[-->` marker; between it and `<!--]-->` sits the
+ * one branch the server rendered (or nothing). `adoptFn(cur)` evaluates the same branch
+ * expression with *adopt* calls — only the taken branch's builder runs, claiming its nodes
+ * off the shared cursor — so the adopted nodes become the region's initial content with no
+ * rebuild. `buildFn()` is the CSR version (build calls) the effect swaps to when a later
+ * reactive change selects a different branch. The closing `<!--]-->` is the swap anchor.
+ * Returns the effect disposer.
+ */
+export function hydrateChild(cur, adoptFn, buildFn) {
+  claimRegionStart(cur);
+  // Adopt inside a scope so the adopted branch owns its bindings' effects; the
+  // region disposes it when a reactive change swaps the branch out.
+  const adoptedScope = scope(() => toNodes(adoptFn(cur)));
+  const anchor = claimRegionEnd(cur);
+  // Seed with the adopted nodes and skip the first effect run's DOM write: the branch is
+  // already in place. The first run still evaluates `buildFn` to subscribe to its reactive
+  // deps (the built nodes are discarded); from the second run on it swaps normally.
+  return childEffect(anchor, buildFn, adoptedScope.result, true, adoptedScope);
+}
+
+/** The child-region effect shared by {@link bindChild} (empty seed, no skip) and
+ * {@link hydrateChild} (seeded with adopted nodes, first DOM write skipped). On each run
+ * the previous nodes are replaced with the new ones, inserted before `anchor`; the
+ * previous branch's scope is disposed so its bindings' effects don't outlive it. */
+function childEffect(anchor, fn, current, skipFirst, currentScope = null) {
+  let first = skipFirst;
+  const disposeEffect = effect(() => {
+    // Build in a scope: the branch's nested bindings (text/attr/list effects)
+    // belong to this run and are disposed when the branch is replaced.
+    const built = scope(() => toNodes(fn()));
+    if (first) {
+      first = false;
+      // Hydration first run subscribes the region effect only; the discarded
+      // build's own effects must not stay live alongside the adopted branch.
+      built.dispose();
+      return; // keep the adopted DOM on first paint
+    }
+    const next = built.result;
     const host = anchor.parentNode;
     for (const n of current) {
       if (n.parentNode === host) host.removeChild(n);
     }
     if (host) for (const n of next) host.insertBefore(n, anchor);
+    if (currentScope) currentScope.dispose();
+    currentScope = built;
     current = next;
   });
+  return () => {
+    disposeEffect();
+    if (currentScope) currentScope.dispose();
+  };
 }
 
 /**
@@ -279,10 +326,48 @@ export function bindChild(anchor, fn) {
 export function bindList(parent, sourceFn, renderItem, keyFn) {
   const anchor = document.createComment("");
   parent.appendChild(anchor);
-  let cache = new Map(); // key -> { sig, node }
-  let prevKeys = []; // keys in current DOM order, for minimal-move reconciliation
+  return reconcileList(anchor, sourceFn, renderItem, keyFn, new Map(), []);
+}
 
-  return effect(() => {
+/**
+ * Hydrate a server-rendered list region (docs/HYDRATION.md §3.1/2.1). The cursor `cur` is
+ * positioned at the `<!--[-->` marker; the region holds one root node per item, then
+ * `<!--]-->`. Adopts each item's server node via `adoptItem(cur, itemSignal, index)`
+ * (claiming off the shared cursor, which advances to the next item), seeds the reconcile
+ * cache with the adopted `{sig, node}` pairs, then wires the *same* keyed-reconcile effect
+ * `bindList` uses — so a later data change builds/moves/removes with no first-paint flash.
+ * The closing `<!--]-->` becomes the reconcile anchor. Returns the effect disposer.
+ */
+export function hydrateList(cur, sourceFn, adoptItem, renderItem, keyFn) {
+  claimRegionStart(cur);
+  const data = sourceFn();
+  const items = Array.isArray(data) ? data : [];
+  const cache = new Map();
+  const prevKeys = [];
+  for (let index = 0; index < items.length; index++) {
+    const item = items[index];
+    const key = keyFn ? keyFn(item, index) : index;
+    const sig = signal(item);
+    // Adopt inside a scope so the item owns its bindings' effects; eviction
+    // disposes them (same ownership as CSR-built items in reconcileList).
+    const s = scope(() => adoptItem(cur, sig, index)); // claims one item subtree off `cur`
+    cache.set(key, { sig, node: s.result, dispose: s.dispose });
+    prevKeys.push(key);
+  }
+  const anchor = claimRegionEnd(cur);
+  // The seeded effect's first run re-reads the same data: every key hits the cache, so it
+  // subscribes for future updates without mutating the already-correct adopted DOM.
+  return reconcileList(anchor, sourceFn, renderItem, keyFn, cache, prevKeys);
+}
+
+/**
+ * The keyed-reconcile effect shared by {@link bindList} (empty seed) and
+ * {@link hydrateList} (seeded from adopted nodes). `anchor` is the trailing comment new
+ * items are inserted before; `cache` (key → `{sig, node}`) and `prevKeys` (keys in DOM
+ * order) carry reconciliation state across runs. Returns the effect disposer.
+ */
+function reconcileList(anchor, sourceFn, renderItem, keyFn, cache, prevKeys) {
+  const disposeEffect = effect(() => {
     const data = sourceFn();
     const items = Array.isArray(data) ? data : [];
     const next = new Map();
@@ -305,7 +390,12 @@ export function bindList(parent, sourceFn, renderItem, keyFn) {
         prevIndex[index] = prevPos.has(key) ? prevPos.get(key) : -1;
       } else {
         const sig = signal(item);
-        entry = { sig, node: renderItem(sig, index) };
+        // Build inside a scope: the item owns its bindings' effects, so
+        // evicting it detaches them from shared signals (e.g. a selection
+        // signal every row's class reads). Without this every discarded row
+        // leaves a zombie effect that all later writes keep re-running.
+        const s = scope(() => renderItem(sig, index));
+        entry = { sig, node: s.result, dispose: s.dispose };
         prevIndex[index] = -1;
       }
       next.set(key, entry);
@@ -313,8 +403,9 @@ export function bindList(parent, sourceFn, renderItem, keyFn) {
       nodes[index] = entry.node;
     }
 
-    // Remove nodes whose keys disappeared.
+    // Remove nodes whose keys disappeared, and dispose their bindings.
     for (const entry of cache.values()) {
+      if (entry.dispose) entry.dispose();
       if (entry.node.parentNode) entry.node.parentNode.removeChild(entry.node);
     }
     cache = next;
@@ -327,13 +418,21 @@ export function bindList(parent, sourceFn, renderItem, keyFn) {
     // cascade into. Walk back to front so each insertion's reference node is
     // already in its final position.
     const keep = longestIncreasingRun(prevIndex);
-    const host = anchor.parentNode || parent;
+    const host = anchor.parentNode;
+    if (!host) return; // anchor detached (list torn down) — nothing to place
     for (let i = nodes.length - 1; i >= 0; i--) {
       if (keep.has(i)) continue;
       const ref = i + 1 < nodes.length ? nodes[i + 1] : anchor;
       if (nodes[i].nextSibling !== ref) host.insertBefore(nodes[i], ref);
     }
   });
+  return () => {
+    disposeEffect();
+    for (const entry of cache.values()) {
+      if (entry.dispose) entry.dispose();
+    }
+    cache.clear();
+  };
 }
 
 /**

package/runtime/hydrate.js

@@ -19,6 +19,21 @@
 export const HOLE_START = "$";
 export const HOLE_END = "/";
 
+/** Comment markers bounding a variable structural region — a list or a conditional —
+ * in server HTML (docs/HYDRATION.md §3.1): `<!--[-->` opens, `<!--]-->` closes. A list
+ * holds one item root node per item; a conditional holds the currently rendered branch
+ * (or nothing). The closing marker becomes the reconcile/swap anchor on hydration. */
+export const REGION_START = "[";
+export const REGION_END = "]";
+
+/** Markers bounding a *component's* light-DOM `{children}` slot (docs/HYDRATION.md §3.1,
+ * 2.1d) — distinct bytes from the list/conditional region markers so a component's own
+ * internal regions never collide with its slot. The slot's content is the *parent's* JSX
+ * (server-rendered here), so the parent finds this slot by its `<!--c[-->` marker within the
+ * host and adopts the children (its reactivity), while the component steps over the slot. */
+export const SLOT_START = "c[";
+export const SLOT_END = "c]";
+
 const ELEMENT = 1;
 const TEXT = 3;
 const COMMENT = 8;
@@ -37,6 +52,12 @@ export class HydrationMismatch extends Error {
 // True during the initial hydration pass. A component's connectedCallback reads it
 // to decide whether to *adopt* its server children or *build* a fresh subtree — the
 // custom-element-as-island coordination (docs/HYDRATION.md §3.4).
+//
+// Why a flag and not the per-instance `this.firstChild` test: a server-rendered host
+// and a client-`createElement`'d host that was handed call-site children both have a
+// `firstChild`, so the structural test alone can't tell "adopt the server DOM" from
+// "build and slot these children" (it mis-adopts on plain SPA navigation). The flag is
+// the unambiguous signal — it is only ever set during the one-shot first-paint pass.
 let _hydrating = false;
 
 /** Is the client mid-hydration right now? */
@@ -44,7 +65,9 @@ export function isHydrating() {
   return _hydrating;
 }
 
-/** Run `fn` with the hydration flag set, restoring the prior value (nesting-safe). */
+/** Run `fn` with the hydration flag set, restoring the prior value (nesting-safe).
+ * Synchronous only — for the async first-paint pass use {@link beginHydration} /
+ * {@link endHydration}, which span the route module's `import()`. */
 export function runHydration(fn) {
   const prev = _hydrating;
   _hydrating = true;
@@ -55,6 +78,65 @@ export function runHydration(fn) {
   }
 }
 
+// Route modules are code-split (`() => import(...)`), so a route's custom elements are
+// defined — and its server-rendered hosts upgrade synchronously — *during* the router's
+// `await import()`, before the page `hydrate` factory runs. The flag therefore has to be
+// set across that whole async region, which a synchronous `runHydration` can't do; the
+// router brackets first paint with these instead. First-paint hydration is a single,
+// sequential boot step (no concurrent navigation), so a plain module-global set is safe.
+
+/** Begin the first-paint hydration pass; pair with {@link endHydration}. Set *before*
+ * the route module is imported so every server host upgrading at `customElements.define`
+ * observes it and adopts (docs/HYDRATION.md §3.4). */
+export function beginHydration() {
+  _hydrating = true;
+}
+
+/** End the first-paint hydration pass — subsequent client navigations build fresh. */
+export function endHydration() {
+  _hydrating = false;
+}
+
+// ── the serialized props payload (compiler-driven data hydration) ─────────────
+// SSG/SSR embeds each island's rich props in a `<script type="application/json"
+// id="__otfw_h">`, keyed by the host's `data-h` id (see server/ssg-runtime.js). A
+// hydrating component reads its props from here — real JS values (objects, arrays,
+// numbers), not lossy string attributes — so it resumes with correct data, with no flash
+// and no dependence on a parent walk re-applying props. Read once and cached.
+let _payload; // undefined = not yet read; null = none present; else the parsed array
+
+function hydrationPayload() {
+  if (_payload === undefined) {
+    const el = typeof document !== "undefined" ? document.getElementById("__otfw_h") : null;
+    try {
+      _payload = el ? JSON.parse(el.textContent || "[]") : null;
+    } catch {
+      _payload = null;
+    }
+  }
+  return _payload;
+}
+
+/**
+ * The rich hydration props recorded for host `el` (keyed by its `data-h` id), or `null`
+ * when there is no payload for it — a client-`createElement`'d element on SPA navigation,
+ * or a plain CSR build. A hydrate-target component constructor reads this to initialize
+ * its prop signals, falling back to attributes/defaults when it returns `null`.
+ */
+export function hydrationProps(el) {
+  const data = hydrationPayload();
+  if (!data || !el || typeof el.getAttribute !== "function") return null;
+  const id = el.getAttribute("data-h");
+  if (id == null) return null;
+  const entry = data[+id];
+  return entry == null ? null : entry;
+}
+
+/** Reset the cached payload (tests only — a fresh document between cases). */
+export function __resetHydrationPayload() {
+  _payload = undefined;
+}
+
 // ── the cursor ────────────────────────────────────────────────────────────────
 
 /** A walker over `parent`'s children, positioned at the next node to claim. */
@@ -63,10 +145,16 @@ export function cursor(parent) {
 }
 
 /** Advance past the next node without claiming it (a static text node between
- * dynamic siblings), returning it. */
+ * dynamic siblings), returning it. The template only emits a skip for a static
+ * `ViewNode::Text`, which the server renders as a real text node; assert that so a
+ * cursor misalignment surfaces *here* (with a clear message) instead of downstream at
+ * an unrelated claim. Throws {@link HydrationMismatch} on a wrong/absent node. */
 export function skipNode(cur) {
   const n = cur.node;
-  cur.node = n ? n.nextSibling : null;
+  if (!n || n.nodeType !== TEXT) {
+    throw new HydrationMismatch(`expected static text, found ${describe(n)}`);
+  }
+  cur.node = n.nextSibling;
   return n;
 }
 
@@ -111,6 +199,65 @@ export function claimText(cur) {
   return textNode;
 }
 
+/** Claim the `<!--[-->` marker that opens a server-rendered region (list or conditional),
+ * advancing the cursor past it. Throws {@link HydrationMismatch} on a wrong/absent node. */
+export function claimRegionStart(cur) {
+  const n = cur.node;
+  if (!n || n.nodeType !== COMMENT || n.data !== REGION_START) {
+    throw new HydrationMismatch(`expected a region start marker, found ${describe(n)}`);
+  }
+  cur.node = n.nextSibling;
+  return n;
+}
+
+/** Claim the `<!--]-->` marker that closes a region and return it — it becomes the
+ * reconcile/swap anchor (`hydrateList`/`hydrateChild` insert later nodes before it).
+ * Advances the cursor past it. Throws {@link HydrationMismatch} on a wrong/absent node. */
+export function claimRegionEnd(cur) {
+  const n = cur.node;
+  if (!n || n.nodeType !== COMMENT || n.data !== REGION_END) {
+    throw new HydrationMismatch(`expected a region end marker, found ${describe(n)}`);
+  }
+  cur.node = n.nextSibling;
+  return n;
+}
+
+/** Step a component's own adopt walk past its `{children}` slot — claim the
+ * `<!--c[-->`…`<!--c]-->` markers and skip the slotted nodes (the parent owns their
+ * reactivity, wired separately by {@link hydrateSlot}), leaving them in place. Advances the
+ * cursor past the closing marker. Throws {@link HydrationMismatch} on a missing start marker. */
+export function skipSlot(cur) {
+  const start = cur.node;
+  if (!start || start.nodeType !== COMMENT || start.data !== SLOT_START) {
+    throw new HydrationMismatch(`expected a children-slot marker, found ${describe(start)}`);
+  }
+  let n = start.nextSibling;
+  while (n && !(n.nodeType === COMMENT && n.data === SLOT_END)) n = n.nextSibling;
+  cur.node = n ? n.nextSibling : null; // step past the `<!--c]-->` end marker
+}
+
+/**
+ * Adopt a component's slotted children — the *parent's* JSX, server-rendered inside the
+ * component host at its `{children}` slot. The parent owns their reactivity but the
+ * component decides where they sit, so the parent locates the slot by its `<!--c[-->` marker
+ * within `host` and adopts from the first slotted node via `adoptFn(cursor)`. Independent of
+ * when the component upgrades: the markers are static server DOM and adoption only *wires*
+ * (never moves) nodes, so it commutes with the component's own `skipSlot`. A missing marker
+ * (a rebuilt component, or no children) is a no-op.
+ */
+export function hydrateSlot(host, adoptFn) {
+  const start = findComment(host, SLOT_START);
+  if (start) adoptFn({ node: start.nextSibling });
+}
+
+/** The first descendant comment of `root` whose data is `data` (tree order). */
+function findComment(root, data) {
+  const walker = document.createTreeWalker(root, 128 /* NodeFilter.SHOW_COMMENT */);
+  let n;
+  while ((n = walker.nextNode())) if (n.data === data) return n;
+  return null;
+}
+
 /** A short human description of a node for mismatch messages. */
 function describe(node) {
   if (!node) return "nothing";

package/runtime/index.js

@@ -14,6 +14,8 @@ export * from "./mount.js";
 export * from "./hydrate.js";
 export * from "./lifecycle.js";
 export * from "./router.js";
+export * from "./route-data.js";
+export * from "./resource.js";
 export * from "./context.js";
 export * from "./error-boundary.js";
 export * from "./portal.js";

package/runtime/mount.js

@@ -2,6 +2,7 @@
 // SPEC §2.2). Components compile to Custom Elements and mount via the DOM.
 
 import { reportError } from "../core/errors.js";
+import { scope } from "../core/signals.js";
 
 /**
  * Mount a view into `target`. `view` is either a factory function returning a
@@ -11,9 +12,21 @@ import { reportError } from "../core/errors.js";
  * built from `onMount`/`onCleanup`. After insertion we run the `onMount` callbacks,
  * collecting any returned disposer into `cleanups` so a caller (e.g. the router)
  * can tear the page down on navigation.
+ *
+ * A factory build runs inside a reactive `scope`, and the scope's disposer joins
+ * the cleanups: teardown (router navigation) stops every binding effect the page
+ * created, so a replaced page's subscriptions don't outlive it.
  */
 export function mount(view, target) {
-  const node = typeof view === "function" ? view() : view;
+  let node;
+  if (typeof view === "function") {
+    const s = scope(view);
+    node = s.result;
+    const lc = (node.__lifecycle ??= { mounts: [], cleanups: [] });
+    lc.cleanups.push(s.dispose);
+  } else {
+    node = view;
+  }
   target.appendChild(node);
   runMount(node);
   return node;

package/runtime/resource.js

@@ -0,0 +1,139 @@
+// `resource()` — the client-side async-data primitive (SPEC §7.4, docs/DATA.md).
+// Components are strictly synchronous (SPEC §5.5), so async data lives *next to*
+// the view: a resource wraps a fetcher in signals and the view renders its
+// reactive `loading` / `error` / `data` states:
+//
+//   const users = resource(() => fetch("/api/users").then((r) => r.json()));
+//   // in JSX: {users.loading ? <Spinner /> : users.data.map(...)}
+//
+// With a reactive source, the fetch re-runs whenever the source changes, and a
+// `null`/`false` source pauses it (conditional fetching):
+//
+//   const user = resource(() => router.params.id, (id, { signal }) =>
+//     fetch(`/api/users/${id}`, { signal }).then((r) => r.json()));
+//
+// Staleness: each run bumps a token and aborts the previous run's AbortController
+// (passed to the fetcher as `{ signal }`), so an out-of-order resolution can never
+// overwrite newer data — even for fetchers that ignore the signal.
+//
+// Server (SSG/SSR): no effect is created and nothing is fetched — `loading` stays
+// `true`, so the prerendered HTML shows the loading branch. That is exactly what
+// the client's first paint renders before its own fetch resolves, keeping
+// hydration adoption aligned.
+
+import { batch, effect, signal, untracked } from "../core/signals.js";
+
+// Test override: bun tests run under happy-dom (a `document` always exists), so
+// server behavior is opted into explicitly.
+let serverOverride = null;
+
+/** Force server (true) / client (false) behavior for new resources — tests only. */
+export function __setResourceServer(v) {
+  serverOverride = v;
+}
+
+const isServer = () => serverOverride ?? typeof document === "undefined";
+
+/**
+ * Create a resource. Two call shapes:
+ *
+ *   resource(fetcher, options?)          — fetch once (and on refetch())
+ *   resource(source, fetcher, options?)  — re-fetch when the reactive `source`
+ *                                          changes; `null`/`false` pauses
+ *
+ * @param {Function} source  reactive source read inside the tracking effect; its
+ *        value is passed to the fetcher.
+ * @param {Function} fetcher  `(sourceValue, { signal }) => data | Promise<data>`.
+ * @param {{ initial?: unknown }} [options]  `initial` seeds `data` before the
+ *        first resolution.
+ * @returns {{ data: unknown, loading: boolean, error: unknown,
+ *             refetch: () => Promise<unknown> | undefined }}  reactive getters —
+ *        read them inside bindings/effects to subscribe.
+ */
+export function resource(source, fetcher, options = {}) {
+  if (typeof fetcher !== "function") {
+    options = fetcher ?? {};
+    fetcher = source;
+    source = null;
+  }
+  const src = typeof source === "function" ? source : () => true;
+  const data = signal(options.initial);
+  const error = signal(undefined);
+  const loading = signal(true); // a fetch is intended; the server leaves it true
+  let token = 0;
+  let controller = null;
+
+  function run(value) {
+    controller?.abort();
+    // Captured per-run: by the time a superseded run's promise settles, the
+    // module-level `controller` already belongs to a newer run.
+    const c = (controller = typeof AbortController !== "undefined" ? new AbortController() : null);
+    const t = ++token;
+    batch(() => {
+      loading.value = true;
+      error.value = undefined;
+    });
+    // The async IIFE starts the fetcher *synchronously* (no wasted microtask)
+    // while converting a synchronous throw into a rejection.
+    return (async () => fetcher(value, { signal: c?.signal }))()
+      .then(
+        (v) => {
+          if (t !== token) return; // superseded — a newer run owns the signals
+          batch(() => {
+            data.value = v;
+            loading.value = false;
+          });
+          return v;
+        },
+        (e) => {
+          if (t !== token) return;
+          // Keep the last good `data` (stale-while-error); only `error` flips.
+          batch(() => {
+            error.value = e;
+            loading.value = false;
+          });
+        },
+      );
+  }
+
+  if (!isServer()) {
+    effect(() => {
+      const value = src(); // the effect's ONLY tracked read
+      if (value == null || value === false) {
+        // Paused: cancel anything in flight and settle as "not loading".
+        untracked(() => {
+          token++;
+          controller?.abort();
+          controller = null;
+          loading.value = false;
+        });
+        return;
+      }
+      untracked(() => run(value));
+      // Before a re-run (source changed) and on scope dispose: invalidate + abort,
+      // so a torn-down region's fetch can neither land nor leak a connection.
+      return () => {
+        token++;
+        controller?.abort();
+      };
+    });
+  }
+
+  return {
+    get data() {
+      return data.value;
+    },
+    get loading() {
+      return loading.value;
+    },
+    get error() {
+      return error.value;
+    },
+    /** Re-run the fetcher with the current source value (no-op while paused). */
+    refetch() {
+      const value = untracked(src);
+      if (value == null || value === false) return undefined;
+      return run(value);
+    },
+  };
+}