@cplieger/reactive 2.2.0-dev.1 → 2.3.0-dev.1

package/README.md

@@ -10,8 +10,9 @@ It replaces the change listeners, list re-renders and element builder you would
 
 reactive is built for a small browser app in plain TypeScript that needs no component framework.
 
-- Signals, computed values and effects track their dependencies on their own. When a write returns, every effect that depends on it has already run.
+- Signals, computed values and effects track their dependencies on their own. When a write returns, every effect that depends on it has already run, except those still running, which each finish before any re-run they need.
 - `createCollection` and `bindList` render a keyed list. Changing one item repaints only its row, and a reorder keeps the existing rows.
+- `createRoot` disposes a view's effects at once, and `resource` loads async data without painting a late answer over the next view.
 - `el` builds elements without HTML strings, so it works under a strict Content Security Policy. `patch` updates a subtree by reusing the elements on the page, so focus and scroll position survive a re-render.
 - The signals, stores, collections and event bus need no DOM, so they also run under Node, Deno, Bun or Workers.
 
@@ -94,9 +95,35 @@ effect(() => {
 name.value = "reactive"; // the same <h1> stays on the page with its new text
 ```
 
+`createRoot` owns what a view starts, and `resource` loads data for it. Disposing the root aborts the request, and a late answer writes nothing:
+
+```typescript
+import { createRoot, effect, el, resource, signal } from "@cplieger/reactive";
+
+const id = signal("a");
+const view = el("p");
+document.body.append(view);
+
+const dispose = createRoot((dispose) => {
+  const item = resource(
+    () => id.value,
+    (value, signal) => fetch(`/items/${value}`, { signal }).then((res) => res.text()),
+  );
+  effect(() => {
+    const s = item.value;
+    view.textContent = s.state === "ready" ? s.data : s.state;
+  });
+  return dispose;
+});
+
+id.value = "b"; // the request for "a" is aborted and its answer is dropped
+dispose();
+```
+
 ## API
 
 - Signals: `signal`, `computed`, `effect`, `batch`, `untracked`, `touch`, `on`, `subscribe`, `isSignal`, `isComputed` and `setEffectErrorHandler`.
+- Ownership and async: `createRoot` and `runWithOwner` for owners that dispose a tree of effects, and `resource` for async data as a `Loadable`.
 - State: `createStore` for a fixed set of typed keys, `SignalMap` for keys known only at run time, and `createCollection` for an ordered list of keyed items.
 - DOM: `el` builds elements, `reconcile` and `bindList` render keyed lists, and `patch` updates a subtree in place. `trackHandler` registers an `on*` handler on an element you built without `el`, so `patch` keeps it in step.
 - Events: `createBus` for typed events that hold no value.
@@ -129,26 +156,26 @@ This is the contract [@preact/signals-core](https://github.com/preactjs/signals/
 
 The package leaves these out on purpose. [Non-goals](docs/non-goals.md) gives the reason for each.
 
-- An ownership tree or `createRoot`, and automatic disposal of nested effects.
+- Ownership outside a root, and a public `getOwner()`.
 - Lazy activation and an `onMount` lifecycle.
 - `Signal.subtle.Watcher` and notify-on-dirty.
 - Introspection APIs, and explicit disposal of a computed.
 - Server-side rendering and per-request isolation.
-- Async signals and resources.
+- Suspense, or a resource that throws while loading.
 - Transactions, a custom scheduler, and a flush barrier such as `flushSync` or `nextTick`.
 - Controlled form inputs. `patch` syncs form values, so if a view can re-render while a user types, drive that field from an effect instead.
 - Writing a signal from inside a computed. The computed's own subscribers are not woken, so make that write in an effect.
 
 ## Documentation
 
-- [Signals, stores and collections](docs/signals.md) covers the flush model, effects, stores, collections and the event bus, for a reader writing state code.
+- [Signals, stores and collections](docs/signals.md) covers the flush model, effects, owners, resources, stores, collections and the event bus, for a reader writing state code.
 - [Building and updating the DOM](docs/dom.md) covers how `el`, `reconcile`, `bindList` and `patch` decide what to keep, for a reader rendering with them.
 - [Non-goals](docs/non-goals.md) lists what the package leaves out and why.
 
 ## Credits
 
 - The signal engine follows the design of [@preact/signals-core](https://github.com/preactjs/signals) in its dependency graph, its glitch-free computed refresh, its run-on-write effects and its untracked `subscribe` callback.
-- The `on()` helper follows [Solid](https://github.com/solidjs/solid)'s `on()`, and `untracked()` is Solid's `untrack()` under the name Preact gives it.
+- The `on()` helper follows [Solid](https://github.com/solidjs/solid)'s `on()`, and `untracked()` is Solid's `untrack()` under the name Preact gives it. `createRoot`, `runWithOwner` and owned nested effects follow Solid's ownership model.
 
 ## Contributing
 

package/THIRD_PARTY_NOTICES.md

@@ -2,7 +2,7 @@
 
 No third-party code is included in this repository. The signal engine is a re-derivation of an upstream design, not a copy of its source, so no license text is reproduced here.
 
-Two designs are followed, each named at the line of ours that follows it:
+Two designs are followed:
 
-- The dependency graph and the scheduler in `src/signal.ts` follow [@preact/signals-core](https://github.com/preactjs/signals) (MIT): the doubly-linked source/target edge nodes (`DepNode`, `SourceNode`, `TargetNode` at `src/signal.ts:75-100`), the pull-based glitch-free `refreshComputed` (`src/signal.ts:327`), the eager drain in `endBatch` (`src/signal.ts:397`), and the untracked `subscribe` callback (`src/signal.ts:711`, upstream `preactjs/signals#188`). The pinned baseline is `@preact/signals-core@1.14.4`; the header of `src/signal.ts` records every deliberate delta from it and the upstream machinery this engine does not carry, and `CONTRIBUTING.md` records the drift-audit procedure.
-- The explicit dependency helper `on()` (`src/signal.ts:734`) follows [solid-js](https://github.com/solidjs/solid) (MIT), whose `on()` has the same deps-plus-body shape; `untracked()` (`src/signal.ts:666`) is Solid's `untrack()` under the name Preact gives it.
+- The dependency graph and the scheduler in `src/signal.ts` follow [@preact/signals-core](https://github.com/preactjs/signals) (MIT): the doubly-linked source and target edge nodes (`DepNode`, `SourceNode` and `TargetNode`), the pull-based glitch-free `refreshComputed`, the eager drain in `endBatch`, and the untracked `subscribe` callback (upstream `preactjs/signals#188`). The baseline is `@preact/signals-core@1.14.4`. `CONTRIBUTING.md` lists every deliberate delta from it and the upstream machinery this engine does not carry.
+- The explicit dependency helper `on()` in `src/signal.ts` follows [solid-js](https://github.com/solidjs/solid) (MIT), whose `on()` has the same deps-plus-body shape. `untracked()` is Solid's `untrack()` under the name Preact gives it.

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/reactive",
-  "version": "2.2.0-dev.1",
+  "version": "2.3.0-dev.1",
   "license": "Apache-2.0",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/reactive",
-  "version": "2.2.0-dev.1",
+  "version": "2.3.0-dev.1",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -21,15 +21,15 @@
     "@stryker-mutator/typescript-checker": "10.0.0",
     "@stryker-mutator/vitest-runner": "10.0.0",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@vitest/browser-playwright": "5.0.3",
+    "@vitest/browser-playwright": "5.0.4",
     "eslint": "10.12.0",
     "fast-check": "4.10.2",
-    "knip": "6.39.0",
-    "playwright": "1.63.0",
-    "prettier": "3.9.9",
+    "knip": "6.41.0",
+    "playwright": "1.64.1",
+    "prettier": "3.9.10",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.71.0",
-    "vitest": "5.0.3"
+    "typescript-eslint": "8.71.2",
+    "vitest": "5.0.4"
   },
   "overrides": {
     "qs": "^6.15.2"

package/src/bind-list.ts

@@ -1,21 +1,13 @@
-// bind-list.ts — two-tier render binding for a reactive list source.
-//
-// Tier 1 (structure): one effect tracks `source.ids` and runs `reconcile`
-// over the id list, so add/remove/reorder touch the DOM minimally.
-// Tier 2 (content): each row owns a private effect that tracks ONLY its own
-// entity signal, so a per-entity update repaints just that row without a
-// structural reconcile. The engine isolates nested-effect tracking
-// (evalContext save/restore in signal.ts), so the per-row effect's reads never
-// leak into the structural effect.
-//
-// The source is a `ListSource<T>` — anything exposing a structure signal
-// (`ids`) plus a per-id content signal lookup (`signalFor`). A `Collection<T>`
-// satisfies it directly; a filtered/sorted/paginated view is just a `computed`
-// id-list paired with the collection's `signalFor` (so pagination is a sliced
-// view, not a separate primitive).
+// Two-tier render binding for a reactive list source. One structural effect
+// tracks `source.ids` and reconciles the id list; each row owns an effect that
+// tracks only its entity signal, so an entity update repaints just that row.
+// The engine saves and restores evalContext around nested effects, so a row
+// effect's reads never leak into the structural effect. A `Collection<T>` is a
+// `ListSource<T>`; a filtered, sorted or paginated view is a `computed` id
+// list paired with the collection's `signalFor`.
 
 import { reconcile } from "./reconcile.js";
-import { effect, type ReadonlySignal } from "./signal.js";
+import { createRoot, createRootUnder, effect, type Owner, type ReadonlySignal } from "./signal.js";
 
 /** The minimal reactive surface `bindList` renders: a structure signal (the
  *  ordered ids) and a per-id content-signal lookup. `Collection<T>` satisfies
@@ -27,79 +19,79 @@ export interface ListSource<T> {
   signalFor(id: string): ReadonlySignal<T> | undefined;
 }
 
-/** Row lifecycle for `bindList`. */
+/** Row lifecycle for `bindList`. Each row has its own owner, so effects and
+ *  roots created in `mount` and `update` are disposed when the row leaves. */
 export interface ListSpec<T> {
   /** Create the row element for a new entity. Receives the entity's current
-   *  value and id. Keep this to structural shell creation; let `update` fill
-   *  reactive content (it runs once at mount and on every later change). */
-  mount: (item: T, id: string) => HTMLElement;
+   *  value, its id and the row's owner, whose `signal` aborts when the row
+   *  leaves or the list is disposed. Keep this to structural shell creation;
+   *  let `update` fill reactive content (it runs once at mount and on every
+   *  later change). */
+  mount: (item: T, id: string, owner: Owner) => HTMLElement;
   /** Update a row when its entity changes. Runs immediately at mount and again
    *  on every per-entity change (the content tier). Omit for immutable rows
    *  whose `mount` renders everything. */
   update?: (el: HTMLElement, item: T, id: string) => void;
-  /** Optional cleanup when a row leaves the list (fires before the element is
-   *  removed from the DOM). */
+  /** Optional cleanup when a row leaves the list, after its owner is disposed
+   *  and before the element is removed from the DOM. */
   onRemove?: (el: HTMLElement, id: string) => void;
 }
 
-/** Bind a list source to a parent node with two-tier reactivity. Returns a
- *  dispose function that tears down the structural effect and every row
- *  effect. */
+/** Bind a list source to a parent node with two-tier reactivity, in a root
+ *  owned by the current owner when there is one. Returns a dispose function
+ *  that tears down the structural effect and every row. */
 export function bindList<T>(
   parent: ParentNode,
   source: ListSource<T>,
   spec: ListSpec<T>,
 ): () => void {
-  const rowDisposers = new Map<string, () => void>();
+  return createRoot((dispose, listOwner) => {
+    const rowDisposers = new WeakMap<HTMLElement, () => void>();
 
-  const disposeStructural = effect(() => {
-    // Structure tier: re-runs on add/remove/reorder only. An id whose entity
-    // signal is missing (an inconsistent ListSource) is skipped instead of
-    // mounting a row with a manufactured `undefined as T` value; it renders
-    // once the source becomes consistent (the next `ids` change).
-    const ids = source.ids.value.filter((id) => source.signalFor(id) !== undefined);
-    reconcile<string>(parent, ids, {
-      key: (id) => id,
-      mount: (id) => {
-        const sig = source.signalFor(id);
-        if (sig === undefined) {
-          // Unreachable via the structural filter above (same synchronous
-          // pass); reachable only by a source whose signalFor is not stable
-          // within one read — surface that loudly instead of manufacturing
-          // an entity value. Routed to the effect error handler.
-          throw new Error(`bindList: no entity signal for id "${id}"`);
-        }
-        const el = spec.mount(sig.peek(), id);
-        if (spec.update !== undefined) {
-          const update = spec.update;
-          // content tier: isolated per-row effect; runs now (fills content)
-          // and on every later change to THIS entity.
-          rowDisposers.set(
-            id,
-            effect(() => {
-              const cur = source.signalFor(id);
-              if (cur !== undefined) {
-                update(el, cur.value, id);
-              }
-            }),
-          );
-        }
-        return el;
-      },
-      // No structural `update`: content is owned entirely by the per-row effect.
-      onRemove: (el, id) => {
-        rowDisposers.get(id)?.();
-        rowDisposers.delete(id);
-        spec.onRemove?.(el, id);
-      },
+    effect(() => {
+      // Structure tier: re-runs on add/remove/reorder only. An id whose entity
+      // signal is missing (an inconsistent ListSource) is skipped instead of
+      // mounting a row with a manufactured `undefined as T` value; it renders
+      // once the source becomes consistent (the next `ids` change).
+      const ids = source.ids.value.filter((id) => source.signalFor(id) !== undefined);
+      reconcile<string>(parent, ids, {
+        key: (id) => id,
+        mount: (id) => {
+          const sig = source.signalFor(id);
+          if (sig === undefined) {
+            // Unreachable via the structural filter above (same synchronous
+            // pass); reachable only by a source whose signalFor is not stable
+            // within one read — surface that loudly instead of manufacturing
+            // an entity value. Routed to the effect error handler.
+            throw new Error(`bindList: no entity signal for id "${id}"`);
+          }
+          // A row belongs to the list, not to this structural run, whose
+          // scope is disposed on every add, remove or reorder.
+          return createRootUnder(listOwner, (disposeRow, rowOwner) => {
+            const el = spec.mount(sig.peek(), id, rowOwner);
+            rowDisposers.set(el, disposeRow);
+            if (spec.update !== undefined) {
+              const update = spec.update;
+              // content tier: isolated per-row effect; runs now (fills content)
+              // and on every later change to THIS entity.
+              effect(() => {
+                const cur = source.signalFor(id);
+                if (cur !== undefined) {
+                  update(el, cur.value, id);
+                }
+              });
+            }
+            return el;
+          });
+        },
+        // No structural `update`: content is owned entirely by the per-row effect.
+        onRemove: (el, id) => {
+          rowDisposers.get(el)?.();
+          spec.onRemove?.(el, id);
+        },
+      });
     });
-  });
 
-  return () => {
-    disposeStructural();
-    for (const dispose of rowDisposers.values()) {
-      dispose();
-    }
-    rowDisposers.clear();
-  };
+    return dispose;
+  });
 }

package/src/collection.ts

@@ -12,10 +12,9 @@ import { SignalMap } from "./signal-map.js";
 /** A reactive, ordered, keyed collection of entities of type T. */
 export interface Collection<T> {
   /** Replace the whole collection (e.g. initial load). Entities no longer
-   *  present are dropped; the order becomes `items`, deduplicated by key
-   *  (first occurrence keeps the position, the last value wins — Map
-   *  semantics), so the order tier can never list an id twice while the
-   *  entity tier holds a single signal for it. */
+   *  present are dropped; the order becomes `items`, deduplicated by key:
+   *  the first occurrence keeps the position, and a later value replaces the
+   *  held one only when `equals` reports a change. */
   setAll(items: readonly T[]): void;
   /** Add a new entity or replace an existing one (keyed by `keyOf`). New
    *  entities are appended to the order. */
@@ -49,15 +48,19 @@ export interface Collection<T> {
 }
 
 /** Create a reactive ordered keyed collection. `keyOf` derives a stable
- *  string id from an entity. */
-export function createCollection<T>(keyOf: (item: T) => string): Collection<T> {
+ *  string id from an entity; `equals` decides when a write of an entity is a
+ *  change to notify, `Object.is` when omitted. */
+export function createCollection<T>(
+  keyOf: (item: T) => string,
+  options?: { readonly equals?: (a: T, b: T) => boolean },
+): Collection<T> {
   // Shallow-equal so the structure tier fires only when the id sequence
   // actually changes (a same-order setAll updates entities without a
   // spurious structural re-render).
   const order = signal<readonly string[]>([], {
     equals: (a, b) => a.length === b.length && a.every((x, i) => x === b[i]),
   });
-  const sigs = new SignalMap<T>();
+  const sigs = new SignalMap<T>(options);
 
   function setAll(items: readonly T[]): void {
     // Atomic: batch the per-entity writes + the order swap so effects (and any
@@ -68,9 +71,7 @@ export function createCollection<T>(keyOf: (item: T) => string): Collection<T> {
       const seen = new Set<string>();
       for (const item of items) {
         const id = keyOf(item);
-        // Deduplicate repeated keys (first occurrence keeps the position, the
-        // last value wins) so the structure and entity tiers cannot disagree:
-        // one signal per id, one order entry per id.
+        // One order slot per id, matching the one signal per id.
         if (!seen.has(id)) {
           seen.add(id);
           ids.push(id);

package/src/index.ts

@@ -10,14 +10,19 @@ export {
   isSignal,
   isComputed,
   on,
+  createRoot,
+  runWithOwner,
 } from "./signal.js";
 export type {
   Signal,
   Cleanup,
   EffectErrorHandler,
+  Owner,
   ReadonlySignal,
   SignalOptions,
 } from "./signal.js";
+export { resource } from "./resource.js";
+export type { Loadable, Resource, ResourceOptions } from "./resource.js";
 export { createStore } from "./store.js";
 export type { Store } from "./store.js";
 export { SignalMap } from "./signal-map.js";

package/src/resource.ts

@@ -0,0 +1,102 @@
+import {
+  createRoot,
+  effect,
+  requireOwner,
+  runWithOwner,
+  signal,
+  type ReadonlySignal,
+} from "./signal.js";
+
+/** The state of an async value: loading, ready or failed. `stale` is the last
+ *  ready value, kept while a later run loads or after it fails. */
+export type Loadable<T, E = unknown> =
+  | { readonly state: "loading"; readonly stale?: T }
+  | { readonly state: "ready"; readonly data: T }
+  | { readonly state: "error"; readonly error: E; readonly stale?: T };
+
+/** A signal of the latest run's `Loadable`, with `refetch` to start a new run. */
+export interface Resource<T, E = unknown> extends ReadonlySignal<Loadable<T, E>> {
+  /** Start a new run for the current source value, superseding the running
+   *  one. Does nothing once the resource's owner is being disposed. */
+  refetch(): void;
+}
+
+/** Options for `resource`. */
+export interface ResourceOptions<S> {
+  /** Source equality; an equal new source value starts no run. Defaults to
+   *  `Object.is`. */
+  readonly equals?: (a: S, b: S) => boolean;
+}
+
+/** Load `load(source(), signal)` now and again whenever the tracked `source`
+ *  changes, owned by the current owner. Each run has its own owner, whose
+ *  `signal` is the one passed to `load` and which is current while `load`
+ *  runs: a new source value, `refetch()` or the resource's disposal disposes
+ *  the previous run, and a disposed run's settlement writes nothing. `E` is
+ *  whatever `load` throws or rejects with. A throw from `source` goes to the
+ *  effect error handler and starts no run. Throws outside an owner, or under
+ *  one being disposed. */
+export function resource<S, T, E = unknown>(
+  source: () => S,
+  load: (source: S, signal: AbortSignal) => Promise<T>,
+  options?: ResourceOptions<S>,
+): Resource<T, E> {
+  const owner = requireOwner("a resource");
+  const equals = options?.equals ?? Object.is;
+  const state = signal<Loadable<T, E>>({ state: "loading" });
+  let good: { readonly data: T } | undefined;
+  let current: { readonly value: S } | undefined;
+  let disposeRun: (() => void) | undefined;
+
+  const start = (value: S): void => {
+    runWithOwner(owner, () => {
+      disposeRun?.();
+      createRoot((dispose, run) => {
+        disposeRun = dispose;
+        state.value =
+          good === undefined ? { state: "loading" } : { state: "loading", stale: good.data };
+        // The async wrapper turns a synchronous throw from `load` into a rejection.
+        const pending = (async (): Promise<T> => load(value, run.signal))();
+        pending.then(
+          (data) => {
+            if (!run.signal.aborted) {
+              good = { data };
+              state.value = { state: "ready", data };
+            }
+          },
+          (error: unknown) => {
+            if (!run.signal.aborted) {
+              state.value =
+                good === undefined
+                  ? { state: "error", error: error as E }
+                  : { state: "error", error: error as E, stale: good.data };
+            }
+          },
+        );
+      });
+    });
+  };
+
+  effect(() => {
+    const value = source();
+    const prev = current;
+    current = { value };
+    if (prev === undefined || !equals(prev.value, value)) {
+      start(value);
+    }
+  });
+
+  return {
+    get value(): Loadable<T, E> {
+      return state.value;
+    },
+    peek(): Loadable<T, E> {
+      return state.peek();
+    },
+    refetch(): void {
+      if (current !== undefined) {
+        start(current.value);
+      }
+    },
+  };
+}

package/src/signal-map.ts

@@ -11,6 +11,13 @@ import { signal, type Signal } from "./signal.js";
  *  get / ensure / clear / clearAll over any value type. */
 export class SignalMap<V> {
   private readonly map = new Map<string, Signal<V>>();
+  private readonly equals: ((a: V, b: V) => boolean) | undefined;
+
+  /** `equals` decides when a write to one of the map's signals is a change;
+   *  `Object.is` when omitted. */
+  constructor(options?: { readonly equals?: (a: V, b: V) => boolean }) {
+    this.equals = options?.equals;
+  }
 
   /** The signal for `id`, or undefined if none has been created yet. */
   get(id: string): Signal<V> | undefined {
@@ -21,7 +28,7 @@ export class SignalMap<V> {
   ensure(id: string, initial: V): Signal<V> {
     let sig = this.map.get(id);
     if (sig === undefined) {
-      sig = signal(initial);
+      sig = this.equals === undefined ? signal(initial) : signal(initial, { equals: this.equals });
       this.map.set(id, sig);
     }
     return sig;

package/src/signal.ts

@@ -1,65 +1,10 @@
-// Reactive signals: signal<T>, effect (with cleanup), batch, computed, untracked.
-// Preact-style doubly-linked source/target edges, pull-based glitch-free refresh,
-// per-node version fast-skip, bitfield flags.
-// Apache-2.0.
-//
-// FLUSH MODEL — one phase, and the whole of it:
-//   1. A write flushes. When `sig.value = x` returns, every effect that depends
-//      on `sig` has already re-run. The setter opens an implicit batch, notifies,
-//      and drains before it returns, so there is no pending-effect state a caller
-//      can observe and no queue to drain.
-//   2. `batch(fn)` is the only deferral. Writes inside it coalesce; effects are
-//      held and run once, synchronously, when the OUTERMOST batch returns.
-//   3. Deferral beyond that is the caller's. To get effects on a later task,
-//      write on a later task (queueMicrotask, requestAnimationFrame). This module
-//      owns no scheduler and offers no flush barrier, because it never holds work.
-//
-// Clause 3 is why there is no `flushSync()`. A flush barrier is the API a
-// DEFERRED model owes its callers — Vue's `nextTick`, React's `flushSync` — and
-// an eager one owes none. The export existed until v2.0.0, could never find work
-// pending (endBatch drains the moment the depth reaches 0) and refused to act
-// when work WAS pending (it returned early above depth 0), so it was a no-op from
-// every position a caller could occupy; six mutants over its body were
-// permanently unkillable, and 71 consumer call sites had never done anything.
-// Anything reintroducing a barrier here is reintroducing that: the barrier is not
-// the missing piece, clause 1 is.
-//
-// Port provenance: graph/scheduler semantics verified against
-// @preact/signals-core@1.14.4 (drift audit 2026-07-17). The flush model above is
-// upstream's, including the absence of a barrier: upstream documents the write
-// contract in prose ("Changing a signal's value synchronously updates every
-// computed and effect that depends on that signal") and its surface is
-// signal/computed/effect/batch/untracked/createModel. Deliberate deltas from
-// upstream, pinned by tests: Object.is equality incl. NaN (upstream:
-// `!==`); custom `equals` / `equals: false` options (upstream has none);
-// isolate-and-continue effect error policy via setEffectErrorHandler
-// (upstream disposes-and-rethrows); the cycle guard lives in endBatch's drain
-// and un-notifies the chain it drops (upstream guards ONLY in the signal
-// setter, evaluated before the write, so it never drops a chain); and the drain
-// is re-entrant — `if (--batchDepth > 0) return` lets a write from an effect
-// body start a fresh drain, where upstream's `if (batchDepth > 1) return` plus
-// a post-drain `batchDepth--` keeps one drain per outermost batch.
-//
-// Upstream machinery NOT ported by design:
-//   - watched/unwatched hooks, createModel/action (1.13+);
-//   - the 1.14.x batch-snapshot A->B->A revert optimization — the
-//     version-monotonicity bug its first release carried
-//     (preactjs/signals#947) never existed here;
-//   - the `globalVersion` epoch fast-skip in refreshComputed. All three
-//     refresh call sites pre-check DIRTY, and because this port never
-//     unsubscribes a computed from its sources, notifyTargets always reaches
-//     every dependent computed — so DIRTY is a complete staleness signal.
-//     Upstream needs the epoch for computeds with no subscribers, which have
-//     no live edges. Do NOT try to revive it by deleting the DIRTY pre-checks:
-//     this refreshComputed has neither upstream's TRACKING shortcut nor its
-//     internal needsToRecompute gate, so an epoch miss recomputes
-//     unconditionally and six recompute-gating tests go red.
-//   - upstream's endBatch error capture and rethrow. Effect errors are
-//     isolated inside runEffect (see its contract below), so nothing can throw
-//     out of the drain and there was never anything to capture.
-//
-// Re-audit on upstream releases: diff src/index.ts against this file's
-// mechanisms and harvest engine-internal fixes (see CONTRIBUTING.md).
+// Signal engine: preact-style linked edges, pull-based glitch-free refresh.
+// User contract: docs/signals.md; upstream deltas: CONTRIBUTING.md. Invariants:
+// - A write flushes: when the setter returns, every dependent effect has run,
+//   except those still running, which are never interrupted; each one whose
+//   current run had already read the written signal re-runs once it returns.
+// - batch() is the only deferral; its effects run when the outermost returns.
+// - The drain is re-entrant: a write inside an effect starts a nested drain.
 
 const SIGNAL_BRAND = Symbol("signal");
 const COMPUTED_BRAND = Symbol("computed");
@@ -69,6 +14,7 @@ const DIRTY = 1;
 const RUNNING = 4;
 const DISPOSED = 8;
 const HAS_ERROR = 16;
+const RERUN = 32;
 const NOTIFIED = 64;
 
 // --- Linked-list Node for source↔target edges ---
@@ -113,6 +59,8 @@ interface EffectNode {
   _sources: DepNode | undefined;
   _nextBatchedEffect: EffectNode | undefined;
   _isComputed: false;
+  _owner: OwnerNode | undefined;
+  _scope: OwnerNode | undefined;
 }
 
 // --- Globals ---
@@ -150,6 +98,216 @@ export function setEffectErrorHandler(handler: EffectErrorHandler): EffectErrorH
   return prev;
 }
 
+// --- Ownership ---
+const OPEN = 0;
+const CLOSING = 1;
+const CLOSED = 2;
+
+let currentOwner: OwnerNode | undefined;
+
+/** A disposal scope made by `createRoot`. Effects and roots created while it is
+ *  current are disposed with it. */
+export interface Owner {
+  /** Aborted when the owner is disposed, after its children and callbacks. */
+  readonly signal: AbortSignal;
+  /** Run `fn` when the owner is disposed, after its children, in reverse
+   *  registration order. On an owner already being disposed, or disposed, `fn`
+   *  runs at once. A throw goes to the effect error handler. */
+  onDispose(fn: () => void): void;
+}
+
+class OwnerNode implements Owner {
+  _state = OPEN;
+  _parent: OwnerNode | undefined;
+  _children: Set<OwnerNode | EffectNode> | undefined;
+  _callbacks: (() => void)[] | undefined;
+  // Created on first read: every run of an owned effect makes a scope, and
+  // few of them are ever asked for a signal.
+  _controller: AbortController | undefined;
+
+  constructor(parent: OwnerNode | undefined) {
+    this._parent = parent;
+    parent?._adopt(this);
+  }
+
+  get signal(): AbortSignal {
+    if (this._controller === undefined) {
+      this._controller = new AbortController();
+      if (this._state === CLOSED) {
+        this._controller.abort();
+      }
+    }
+    return this._controller.signal;
+  }
+
+  onDispose(fn: () => void): void {
+    if (this._state === OPEN) {
+      (this._callbacks ??= []).push(fn);
+      return;
+    }
+    runLateDisposeCallback(this, fn);
+  }
+
+  _adopt(child: OwnerNode | EffectNode): void {
+    (this._children ??= new Set()).add(child);
+  }
+}
+
+function assertOpen(owner: OwnerNode | undefined, what: string): void {
+  if (owner !== undefined && owner._state !== OPEN) {
+    throw new Error(`reactive: cannot create ${what} under an owner that is being disposed`);
+  }
+}
+
+function ownerNode(owner: Owner): OwnerNode {
+  if (owner instanceof OwnerNode) {
+    return owner;
+  }
+  throw new TypeError("reactive: not an owner made by createRoot");
+}
+
+function runDisposeCallback(fn: () => void): void {
+  try {
+    fn();
+  } catch (e) {
+    safeCallHandler(e);
+  }
+}
+
+function runLateDisposeCallback(owner: OwnerNode, fn: () => void): void {
+  const prevOwner = currentOwner;
+  const prevContext = evalContext;
+  currentOwner = owner;
+  evalContext = undefined;
+  runDisposeCallback(fn);
+  currentOwner = prevOwner;
+  evalContext = prevContext;
+}
+
+function disposeOwner(owner: OwnerNode): void {
+  if (owner._state === OPEN) {
+    markClosing(owner);
+    teardownOwner(owner);
+  }
+}
+
+// The whole subtree is marked before anything is torn down, so a write made by
+// a cleanup or callback mid-walk cannot re-run an effect of this subtree: the
+// drain skips DISPOSED effects.
+function markClosing(owner: OwnerNode): void {
+  owner._state = CLOSING;
+  if (owner._children === undefined) {
+    return;
+  }
+  for (const child of owner._children) {
+    if (child instanceof OwnerNode) {
+      markClosing(child);
+    } else {
+      child._flags |= DISPOSED;
+      if (child._scope !== undefined) {
+        markClosing(child._scope);
+      }
+    }
+  }
+}
+
+// Invariant: nothing in this walk throws (callbacks are isolated, effect
+// teardown never throws), so the context restore and the abort need no finally.
+function teardownOwner(owner: OwnerNode): void {
+  owner._parent?._children?.delete(owner);
+  owner._parent = undefined;
+  const prevOwner = currentOwner;
+  const prevContext = evalContext;
+  currentOwner = owner;
+  evalContext = undefined;
+  const children = owner._children;
+  owner._children = undefined;
+  if (children !== undefined) {
+    for (const child of [...children].reverse()) {
+      if (child instanceof OwnerNode) {
+        teardownOwner(child);
+      } else {
+        releaseEffect(child);
+      }
+    }
+  }
+  const callbacks = owner._callbacks;
+  owner._callbacks = undefined;
+  if (callbacks !== undefined) {
+    for (const fn of callbacks.reverse()) {
+      runDisposeCallback(fn);
+    }
+  }
+  currentOwner = prevOwner;
+  evalContext = prevContext;
+  owner._controller?.abort();
+  owner._state = CLOSED;
+}
+
+/** @internal The current owner, for a primitive that refuses to exist without
+ *  one. Throws outside any owner, or under one being disposed. */
+export function requireOwner(what: string): Owner {
+  if (currentOwner === undefined) {
+    throw new Error(`reactive: cannot create ${what} outside an owner`);
+  }
+  assertOpen(currentOwner, what);
+  return currentOwner;
+}
+
+/** @internal `createRoot` with an explicit parent, for `bindList`'s rows. */
+export function createRootUnder<T>(
+  parent: Owner | undefined,
+  fn: (dispose: () => void, owner: Owner) => T,
+): T {
+  const parentNode = parent === undefined ? undefined : ownerNode(parent);
+  assertOpen(parentNode, "a root");
+  const owner = new OwnerNode(parentNode);
+  const prevOwner = currentOwner;
+  const prevContext = evalContext;
+  currentOwner = owner;
+  evalContext = undefined;
+  try {
+    return fn(() => {
+      disposeOwner(owner);
+    }, owner);
+  } catch (e) {
+    disposeOwner(owner);
+    throw e;
+  } finally {
+    currentOwner = prevOwner;
+    evalContext = prevContext;
+  }
+}
+
+/** Run `fn` untracked in a new owner, child of the current one when there is
+ *  one, and return its result. Effects and roots created inside are disposed by
+ *  `dispose`, or with the parent. A throw from `fn` disposes the root and
+ *  rethrows. Throws when the current owner is being disposed. */
+export function createRoot<T>(fn: (dispose: () => void, owner: Owner) => T): T {
+  return createRootUnder(currentOwner, fn);
+}
+
+/** Run `fn` untracked with `owner` current, so what it creates is owned by
+ *  `owner`. Returns `undefined` without calling `fn` once `owner` is being
+ *  disposed or is disposed. Throws a TypeError for an object `createRoot` did
+ *  not make. */
+export function runWithOwner<T>(owner: Owner, fn: () => T): T | undefined {
+  const node = ownerNode(owner);
+  if (node._state !== OPEN) {
+    return undefined;
+  }
+  const prevOwner = currentOwner;
+  const prevContext = evalContext;
+  currentOwner = node;
+  evalContext = undefined;
+  try {
+    return fn();
+  } finally {
+    currentOwner = prevOwner;
+    evalContext = prevContext;
+  }
+}
+
 // --- Dependency tracking ---
 function addDependency(source: SourceNode): DepNode | undefined {
   if (evalContext === undefined) {
@@ -269,19 +427,13 @@ function notifyTargets(source: SourceNode): void {
     if (target._isComputed) {
       // It's a ComputedNode
       if (target._flags & RUNNING) {
-        // A source written while this computed is mid-evaluation. Mark it stale
-        // so the next read re-runs it — every refresh call site pre-checks
-        // DIRTY, so without this the computed serves its pre-write value
-        // forever — but do NOT recurse: its own version has not moved yet, and
-        // recursing out of a RUNNING node is how a notify ping-pong is built.
-        //
-        // This repairs the PULL side only, deliberately. Two limits the next
-        // reader should not have to rediscover: (1) the computed's own
-        // subscribers are not woken here, so an effect that depends on it will
-        // not re-run until something else notifies it; (2) a computed that
-        // writes its own source unconditionally costs one extra recompute per
-        // read, and inside an effect it degrades into the documented
-        // MAX_BATCH_ITERATIONS "Cycle detected" path rather than hanging.
+        // A source written while this computed is mid-evaluation: mark it DIRTY
+        // so the next read recomputes (refresh callers check DIRTY first), but
+        // do not recurse: its version has not moved, and recursing out of a
+        // RUNNING node builds a notify ping-pong. Pull side only: its subscribers
+        // are not woken here, and a computed writing its own source costs one
+        // extra recompute per read, ending in the MAX_BATCH_ITERATIONS "Cycle
+        // detected" path inside an effect rather than hanging.
         target._flags |= DIRTY;
       } else if (!(target._flags & NOTIFIED)) {
         target._flags |= DIRTY | NOTIFIED;
@@ -289,8 +441,13 @@ function notifyTargets(source: SourceNode): void {
         target._flags &= ~NOTIFIED;
       }
     } else {
-      // It's an EffectNode
-      if (!(target._flags & NOTIFIED)) {
+      // It's an EffectNode. A running one, from its previous run's teardown to
+      // the end of its body, is never queued: a nested drain re-entering it
+      // would overwrite the scope and cleanup of the run still on the stack,
+      // so runEffect re-queues it once that run returns.
+      if (target._flags & RUNNING) {
+        target._flags |= RERUN;
+      } else if (!(target._flags & NOTIFIED)) {
         target._flags |= NOTIFIED;
         const eff = target as unknown as EffectNode;
         eff._nextBatchedEffect = batchedEffect;
@@ -324,13 +481,19 @@ function needsToRecompute(target: TargetNode): boolean {
 }
 
 // --- Computed refresh (pull-based, depth-first) ---
+// Callers check DIRTY first: there is no epoch fast-skip or staleness gate in
+// here, so a call on a clean computed recomputes it.
 function refreshComputed(comp: ComputedNode): void {
   if (comp._flags & RUNNING) {
     throw new Error("Cycle detected");
   }
 
   const prevContext = evalContext;
+  const prevOwner = currentOwner;
   evalContext = comp;
+  // A computed runs whenever it is read, so the reader's owner says nothing
+  // about it: what it creates is unowned.
+  currentOwner = undefined;
   const prevFlags = comp._flags;
   comp._flags = RUNNING;
 
@@ -356,6 +519,7 @@ function refreshComputed(comp: ComputedNode): void {
     }
   } finally {
     evalContext = prevContext;
+    currentOwner = prevOwner;
     cleanupSources(comp);
     if (!fnThrew) {
       comp._flags = comp._flags & ~RUNNING;
@@ -438,18 +602,23 @@ function endBatch(): void {
   batchIteration = enclosingIteration;
 }
 
-function runCleanup(eff: EffectNode): void {
+// `scope` is the disposed scope of the run being cleaned up, current during
+// the cleanup so an effect or root created there throws instead of escaping.
+function runCleanup(eff: EffectNode, scope: OwnerNode | undefined): void {
   if (eff._cleanup) {
     const c = eff._cleanup;
     eff._cleanup = undefined;
     const prevContext = evalContext;
+    const prevOwner = currentOwner;
     evalContext = undefined;
+    currentOwner = scope;
     try {
       c();
     } catch (e) {
       safeCallHandler(e);
     } finally {
       evalContext = prevContext;
+      currentOwner = prevOwner;
     }
   }
 }
@@ -462,12 +631,23 @@ function runCleanup(eff: EffectNode): void {
 // mid-drain — the same shape of failure as the cycle bail's NOTIFIED leak. If
 // you add a statement here that can throw, wrap it HERE, not at the call sites.
 function runEffect(eff: EffectNode): void {
-  // Run cleanup first (untracked)
-  runCleanup(eff);
+  // Set before the previous run's teardown, so a write from its cleanup or
+  // disposal callbacks finds this effect RUNNING (see notifyTargets).
+  eff._flags |= RUNNING;
+  const prevScope = eff._scope;
+  if (prevScope !== undefined) {
+    eff._scope = undefined;
+    disposeOwner(prevScope);
+  }
+  runCleanup(eff, prevScope);
 
   // Track dependencies
   const prevContext = evalContext;
+  const prevOwner = currentOwner;
+  const scope = eff._owner === undefined ? undefined : new OwnerNode(undefined);
+  eff._scope = scope;
   evalContext = eff;
+  currentOwner = scope;
   prepareSources(eff);
 
   try {
@@ -477,14 +657,47 @@ function runEffect(eff: EffectNode): void {
   } catch (e) {
     safeCallHandler(e);
   } finally {
+    eff._flags &= ~RUNNING;
     evalContext = prevContext;
+    currentOwner = prevOwner;
     cleanupSources(eff);
   }
+  if (eff._flags & DISPOSED) {
+    // Disposed during its own run, alone or with its owner. The cleanup this
+    // run returned runs now, like a late onDispose, with the run's closed
+    // scope current; the edges the rest of the run made are dropped.
+    runCleanup(eff, scope);
+    releaseEffect(eff);
+  } else if (eff._flags & RERUN) {
+    eff._flags &= ~RERUN;
+    eff._flags |= NOTIFIED;
+    eff._nextBatchedEffect = batchedEffect;
+    batchedEffect = eff;
+    // Inside a batch this only queues it. Otherwise it drains now, one level
+    // deeper, so a self-write loop still meets the cycle cap, whose throw is
+    // routed here because this function never throws.
+    startBatch();
+    try {
+      endBatch();
+    } catch (e) {
+      safeCallHandler(e);
+    }
+  }
 }
 
-function disposeEffect(eff: EffectNode): void {
-  // Run cleanup (untracked)
-  runCleanup(eff);
+// Disposes the run's scope first, then the cleanup, then the subscriptions.
+// The caller has already marked the scope closing. Idempotent, and never
+// throws: teardownOwner's walk relies on it.
+function releaseEffect(eff: EffectNode): void {
+  eff._flags |= DISPOSED;
+  eff._owner?._children?.delete(eff);
+  eff._owner = undefined;
+  const scope = eff._scope;
+  eff._scope = undefined;
+  if (scope !== undefined) {
+    teardownOwner(scope);
+  }
+  runCleanup(eff, scope);
 
   // Unsubscribe from all sources
   let node = eff._sources;
@@ -505,7 +718,6 @@ function disposeEffect(eff: EffectNode): void {
   // F5: null closures for GC
   eff._fn = undefined;
   eff._cleanup = undefined;
-  eff._flags |= DISPOSED;
 }
 
 // --- Public API ---
@@ -629,8 +841,13 @@ export function computed<T>(fn: () => T, options?: SignalOptions<T>): ReadonlySi
   return c;
 }
 
-/** Create a reactive effect that re-runs when its tracked signals change. Returns a dispose function. */
+/** Create a reactive effect that re-runs when its tracked signals change.
+ *  Returns a dispose function. Under an owner the effect is disposed with it,
+ *  and each run owns the effects and roots it creates, disposed before the next
+ *  run. Throws when the current owner is being disposed. */
 export function effect(fn: () => Cleanup): () => void {
+  const owner = currentOwner;
+  assertOpen(owner, "an effect");
   const eff: EffectNode = {
     _fn: fn,
     _cleanup: undefined,
@@ -638,16 +855,20 @@ export function effect(fn: () => Cleanup): () => void {
     _sources: undefined,
     _nextBatchedEffect: undefined,
     _isComputed: false,
+    _owner: owner,
+    _scope: undefined,
   };
+  owner?._adopt(eff);
 
   // Run immediately
   runEffect(eff);
 
+  // releaseEffect is idempotent, so a second dispose needs no guard.
   return () => {
-    if (eff._flags & DISPOSED) {
-      return;
+    if (eff._scope !== undefined) {
+      markClosing(eff._scope);
     }
-    disposeEffect(eff);
+    releaseEffect(eff);
   };
 }
 
@@ -673,22 +894,13 @@ export function untracked<T>(fn: () => T): T {
   }
 }
 
-/** Read a signal for its tracking effect alone, discarding the value.
- *
- *  The complement of `peek()`: `peek` reads without subscribing, `touch`
- *  subscribes without keeping. Outside a reactive scope it does nothing
- *  observable.
- *
- *  This exists because the two-tier shape `createCollection` and `bindList` are
- *  built on produces it: a scope reads per-entity values through `signalFor`,
- *  so it must depend on the structure signal separately to re-run when the id
- *  set changes, and that dependency has no value the body wants. `undefined`
- *  entries are accepted so a per-key lookup that may miss (`signalFor(id)`,
- *  `SignalMap.get(id)`) can be passed straight in.
- *
- *  Not a substitute for `on()`, which declares an exhaustive dependency list
- *  and runs its body untracked. `touch` ADDS a dependency and leaves every
- *  other read in the scope tracked as usual. */
+/** Read signals for their tracking alone, discarding the values: `peek` reads
+ *  without subscribing, `touch` subscribes without keeping. Outside a reactive
+ *  scope it does nothing observable. A scope reading per-entity values through
+ *  `signalFor` uses it to also re-run when the id set changes. `undefined`
+ *  entries are skipped, so a lookup that may miss (`signalFor(id)`,
+ *  `SignalMap.get(id)`) can be passed straight in. Unlike `on()`, it adds a
+ *  dependency and leaves the scope's other reads tracked. */
 export function touch(
   ...signals: readonly (Signal<unknown> | ReadonlySignal<unknown> | undefined)[]
 ): void {
@@ -729,15 +941,11 @@ export function isComputed(value: unknown): value is ReadonlySignal<unknown> {
   return value !== null && typeof value === "object" && COMPUTED_BRAND in value;
 }
 
-/** Explicit dependency declaration helper. Mirrors Solid's on().
- *
- * Overloaded so the return type and the `value`/`prev` parameter types stay
- * tight:
- *   - Without `defer` (or `{ defer: false }`) the accessor always returns `U`;
- *     only the `{ defer: true | boolean }` form widens to `U | undefined`
- *     (the deferred first call yields `undefined`).
- *   - A single accessor `() => T` correlates `value`/`prev` to `T`; an array of
- *     accessors correlates them to `unknown[]`. */
+/** Explicit dependency declaration helper, like Solid's `on()`. Without `defer`
+ *  (or with `{ defer: false }`) the accessor returns `U`; `{ defer: true |
+ *  boolean }` widens it to `U | undefined`, since the deferred first call yields
+ *  `undefined`. A single accessor `() => T` types `value` and `prev` as `T`; an
+ *  array of accessors types them as `unknown[]`. */
 // Single accessor, non-deferred (or explicit `{ defer: false }`): never undefined.
 export function on<T, U>(
   deps: () => T,