effect-atom-svelte 0.2.0 → 0.4.0

package/dist/HydrationBoundary.svelte

@@ -1,13 +1,22 @@
 <!--
   @component
   Hydrates dehydrated atom state, for example from `Hydration.dehydrate` returned by a remote
-  function. Atoms new to the registry are hydrated before children render; in the browser, atoms
-  that already exist are updated after render, so current UI does not jump to the incoming data
-  mid-render. On the server, where nothing renders again, they are updated at once.
+  function. Atoms new to the registry, or holding only an initial value nobody has read yet, are
+  hydrated before children render; in the browser, atoms that already exist are updated after
+  render, so current UI does not jump to the incoming data mid-render. On the server, where nothing
+  renders again, and in the browser while it hydrates the server's markup, they are updated at once.
+  That needs Svelte's `experimental.async`: without it, the browser can't tell that it is hydrating,
+  and atoms that already exist, as one read above the boundary, are updated after the first render.
+
+  With `experimental.async` on, custom server rendering must `await render(...)`, as SvelteKit does,
+  so the boundary's `hydratable` entry is written into the page. Otherwise a production build of
+  Svelte logs `hydratable_missing_but_expected` once per boundary as the page hydrates.
 
   A value for an atom nobody reads waits in the registry until something does. When the boundary
   is destroyed, as at the end of a server render, the values it brought that are still unread are
-  dropped, so a registry that outlives the boundary doesn't hand them to a later reader.
+  dropped, as is a promise-encoded value that lands afterwards, so a registry that outlives the
+  boundary doesn't hand them to a later reader. In the browser, a reader that already held the atom
+  when the boundary ended and still holds it, as a layout's reader above it, gets the late value.
 
   **Example** (Hydrating the state a load function dehydrated)
 
@@ -28,10 +37,15 @@
 -->
 <script lang="ts">
   import { Hydration } from "effect/reactivity";
+  import type { AtomRegistry } from "effect/reactivity";
   import { BROWSER } from "esm-env";
-  import { onDestroy } from "svelte";
+  import { hydratable } from "svelte";
   import type { Snippet } from "svelte";
 
+  import { queuedBy } from "./internal/boundaries.js";
+  import { holdsInitialValue } from "./internal/nodeInternals.js";
+  import { onRenderEnd } from "./internal/renderEnd.js";
+  import { onTeardownAfterChildren } from "./internal/teardown.svelte.js";
   import { getRegistry } from "./RegistryContext.js";
 
   interface Props {
@@ -42,21 +56,99 @@
   const { children, state }: Props = $props();
   const registry = getRegistry();
 
-  // SAFETY: preloadedSerializable is on the registry implementation, not the interface (Effect
-  // 4.0.0). It holds the encoded values Hydration.hydrate queued, until a lookup of the key takes one.
-  const { preloadedSerializable: preloaded } = registry as unknown as {
-    readonly preloadedSerializable?: Map<string, unknown>;
-  };
+  // The encoded values Hydration.hydrate queued, until a lookup of the key takes one. Public since
+  // Effect 4.0.2; typed as possibly missing for a registry that isn't Effect's own.
+  const preloaded: Map<string, unknown> | undefined =
+    registry.preloadedSerializable;
   // The values this boundary queued, by key, so it can drop the ones nobody took.
   const queued = new Map<string, unknown>();
+  // Whether the boundary has ended, as at the end of the server render or once the browser destroys
+  // it, after which a late promise-encoded value is dropped.
+  let ended = false;
+
+  const counts =
+    queuedBy.get(registry) ?? new Map<string, Map<unknown, number>>();
+  queuedBy.set(registry, counts);
+  /** Adds one to or takes one from the boundaries queueing a value, and returns the new count. */
+  const count = (key: string, value: unknown, delta: 1 | -1): number => {
+    const byValue = counts.get(key) ?? new Map<unknown, number>();
+    counts.set(key, byValue);
+    const next = (byValue.get(value) ?? 0) + delta;
+    if (next > 0) {
+      byValue.set(value, next);
+    } else {
+      byValue.delete(value);
+      if (byValue.size === 0) {
+        counts.delete(key);
+      }
+    }
+    return next;
+  };
+
+  // SAFETY: Hydration.hydrate ignores a promise-encoded value that resolves to this marker, which
+  // Hydration.ts registers with Symbol.for (Effect 4.0.1) but doesn't export.
+  const skipped = Symbol.for("effect/reactivity/Hydration/Skipped");
+  // The keys of the promise-encoded values the boundary is waiting for.
+  const waiting = new Set<string>();
+  // In the browser, the node that held each of those keys when the boundary ended. That node, as a
+  // layout's reader above the boundary that took its waiting value, still needs the result, or it
+  // waits forever. A node a later reader creates doesn't get it, nor does one that replaced a node
+  // swept since, as a reader inside the boundary's is just after it ends.
+  const nodesAtEnd = new Map<string, AtomRegistry.Node<unknown>>();
+  /** A promise-encoded value as the boundary waits for it; one landing after the boundary ends is skipped. */
+  const lateDropped = async (
+    key: string,
+    late: Promise<unknown>
+  ): Promise<unknown> => {
+    waiting.add(key);
+    const value = await late;
+    if (!ended) {
+      return value;
+    }
+    const held = BROWSER ? nodesAtEnd.get(key) : undefined;
+    return held !== undefined && registry.getNodes().get(key) === held
+      ? value
+      : skipped;
+  };
 
   const queue = (atoms: readonly Hydration.DehydratedAtomValue[]): void => {
-    Hydration.hydrate(registry, atoms);
+    // A promise-encoded value landing after the boundary has ended, after the server render or once
+    // the browser has navigated away, would stay queued in a registry that outlives it for a later
+    // reader, however late: it is ignored once the boundary ends, unless, in the browser, the node
+    // that held its key then still does.
+    Hydration.hydrate(
+      registry,
+      atoms.map((atom) =>
+        atom.resultPromise === undefined
+          ? atom
+          : {
+              ...atom,
+              resultPromise: lateDropped(atom.key, atom.resultPromise),
+            }
+      )
+    );
     for (const { key, value } of atoms) {
+      if (queued.has(key)) {
+        if (queued.get(key) === value) {
+          continue;
+        }
+        count(key, queued.get(key), -1);
+      }
       queued.set(key, value);
+      count(key, value, 1);
     }
   };
 
+  /**
+   * Whether a node's value may be on the page already. A node holding only an initial value nobody
+   * has read, as RegistryProvider's initialValues leave it, shows nowhere yet: it takes the incoming
+   * value before children render, as on the server, so the browser's first render matches the
+   * server's markup.
+   */
+  const shown = (node: AtomRegistry.Node<unknown> | undefined): boolean =>
+    node !== undefined &&
+    !(holdsInitialValue(node) && node.currentState() === "stale");
+
   const hydrateNew = (
     incoming: Iterable<Hydration.DehydratedAtom> | undefined
   ): Hydration.DehydratedAtomValue[] => {
@@ -64,7 +156,7 @@
     const fresh: Hydration.DehydratedAtomValue[] = [];
     const existing: Hydration.DehydratedAtomValue[] = [];
     for (const atom of Hydration.toValues([...(incoming ?? [])])) {
-      (nodes.has(atom.key) ? existing : fresh).push(atom);
+      (shown(nodes.get(atom.key)) ? existing : fresh).push(atom);
     }
     queue(fresh);
     return existing;
@@ -91,8 +183,18 @@
   // svelte-ignore state_referenced_locally
   let deferred = hydrateNew(state);
   // Effects don't run on the server, and nothing there renders again, so the atoms that already
-  // exist are updated now, before the children read them.
-  if (!BROWSER) {
+  // exist are updated now, before the children read them. The browser does the same while it
+  // hydrates the server's markup, so its first render matches the server's. The server writes true;
+  // the browser reads it only while hydrating, and false otherwise. hydratable throws in development
+  // for a key the server didn't write, as for a boundary the server didn't render: that is false too.
+  const hydratingServerMarkup = (() => {
+    try {
+      return hydratable("effect-atom-svelte/HydrationBoundary", () => !BROWSER);
+    } catch {
+      return false;
+    }
+  })();
+  if (!BROWSER || hydratingServerMarkup) {
     hydrateExisting(deferred);
     deferred = [];
   }
@@ -111,13 +213,28 @@
 
   // A queued value stays in the registry until its key is looked up. With a registry that outlives
   // the boundary, such as one the caller passes to the server's provider, it would reach a later
-  // request. Drop the ones still waiting, unless something queued another value since.
-  onDestroy(() => {
+  // request. Drop the ones still waiting, unless something queued another value since or another
+  // live boundary queued the same one. On the server they're dropped when the render ends, even if
+  // a failed boundary discarded this one; in the browser, also when it is destroyed while pending.
+  (BROWSER ? onTeardownAfterChildren : onRenderEnd)(() => {
+    if (ended) {
+      return;
+    }
+    ended = true;
+    if (BROWSER) {
+      const nodes = registry.getNodes();
+      for (const key of waiting) {
+        const node = nodes.get(key);
+        if (node) {
+          nodesAtEnd.set(key, node);
+        }
+      }
+    }
     if (!preloaded) {
       return;
     }
     for (const [key, value] of queued) {
-      if (preloaded.get(key) === value) {
+      if (count(key, value, -1) <= 0 && preloaded.get(key) === value) {
         preloaded.delete(key);
       }
     }

package/dist/HydrationBoundary.svelte.d.ts

@@ -6,13 +6,22 @@ interface Props {
 }
 /**
  * Hydrates dehydrated atom state, for example from `Hydration.dehydrate` returned by a remote
- * function. Atoms new to the registry are hydrated before children render; in the browser, atoms
- * that already exist are updated after render, so current UI does not jump to the incoming data
- * mid-render. On the server, where nothing renders again, they are updated at once.
+ * function. Atoms new to the registry, or holding only an initial value nobody has read yet, are
+ * hydrated before children render; in the browser, atoms that already exist are updated after
+ * render, so current UI does not jump to the incoming data mid-render. On the server, where nothing
+ * renders again, and in the browser while it hydrates the server's markup, they are updated at once.
+ * That needs Svelte's `experimental.async`: without it, the browser can't tell that it is hydrating,
+ * and atoms that already exist, as one read above the boundary, are updated after the first render.
+ *
+ * With `experimental.async` on, custom server rendering must `await render(...)`, as SvelteKit does,
+ * so the boundary's `hydratable` entry is written into the page. Otherwise a production build of
+ * Svelte logs `hydratable_missing_but_expected` once per boundary as the page hydrates.
  *
  * A value for an atom nobody reads waits in the registry until something does. When the boundary
  * is destroyed, as at the end of a server render, the values it brought that are still unread are
- * dropped, so a registry that outlives the boundary doesn't hand them to a later reader.
+ * dropped, as is a promise-encoded value that lands afterwards, so a registry that outlives the
+ * boundary doesn't hand them to a later reader. In the browser, a reader that already held the atom
+ * when the boundary ended and still holds it, as a layout's reader above it, gets the late value.
  *
  * **Example** (Hydrating the state a load function dehydrated)
  *

package/dist/Inspector.d.ts

@@ -17,8 +17,10 @@ import type { ReadKind } from "./internal/scope.svelte.ts";
  * - `FirstRead`: its first computation.
  * - `ParentChanged`: atoms it read changed since its last computation; `parents` are those nodes.
  * - `Refreshed`: `registry.refresh` (or `useAtomRefresh`) asked for it, or for an atom it wraps.
- * - `Invalidated`: something else made it stale, such as the atom refreshing itself (`refreshSelf`,
- *   a reactivity key, a window-focus signal).
+ *   A signal that refreshes the atom (`refreshOnWindowFocus`, `makeRefreshOnSignal`, `swr`) calls
+ *   `registry.refresh` too, so it is reported the same way.
+ * - `Invalidated`: something else made it stale, such as the atom refreshing itself (`refreshSelf`)
+ *   or a reactivity key.
  *
  * @stability unstable
  * @since 0.2.0
@@ -58,7 +60,9 @@ export type UpdateSource = "build" | "write" | "async";
  * - `ReadersChanged`: a listener was added or removed; `readers` is how many it has now. Hooks,
  *   `registry.subscribe` and `mount`, and atoms that subscribe to others all count.
  * - `Interrupted`: its effect hadn't finished when what its computation started was torn down, so
- *   the fiber was interrupted. Followed by `Finalized`.
+ *   the fiber was interrupted. Followed by `Finalized`. Not reported for an `Atom.runtime` atom,
+ *   whose layer build isn't interrupted. An effect atom made with `{ uninterruptible: true }` is
+ *   reported all the same, though its fiber keeps running: the inspector can't tell it apart.
  * - `Finalized`: what its last computation started was torn down, before it computes again or as
  *   it is removed; `finalizers` ran.
  * - `NodeRemoved`: the registry disposed of the node, as nothing read it any more.

package/dist/Inspector.js

@@ -10,13 +10,23 @@
  */
 import { AsyncResult, Atom } from "effect/reactivity";
 import { BROWSER } from "esm-env";
-import { defaultIdleTTL, instrumentNode } from "./internal/nodeInternals.js";
+import { buildWillRead, defaultIdleTTL, holdsInitialValue, instrumentNode, } from "./internal/nodeInternals.js";
 import { list, watch } from "./internal/registries.js";
 import { nameComponent as setComponentName, setReporter, } from "./internal/scope.svelte.js";
 const nodeKey = (atom) => Atom.isSerializable(atom) ? atom[Atom.SerializableTypeId].key : atom;
+/**
+ * An `Atom.runtime` atom, by the `layer` and `factory` it carries. It builds its layer with
+ * `uninterruptible: true`, so a build torn down midway keeps running.
+ */
+const isRuntime = (atom) => "layer" in atom &&
+    Atom.isAtom(atom.layer) &&
+    "factory" in atom &&
+    typeof atom.factory === "function";
 const install = (registry) => {
     const listeners = new Set();
     const records = new WeakMap();
+    // The node that held each result first: the one whose computation or effect made it.
+    const origins = new WeakMap();
     let writing = 0;
     let complete = true;
     const emit = (event) => {
@@ -38,6 +48,7 @@ const install = (registry) => {
                 builds: 0,
                 changed: new Set(),
                 refreshed: false,
+                removing: false,
                 values: 0,
             };
             records.set(node, found);
@@ -73,7 +84,12 @@ const install = (registry) => {
                 }
                 // An effect atom's computation leaves a waiting result until its fiber is done, and a
                 // finalizer that interrupts the fiber.
-                if (AsyncResult.isAsyncResult(value) && value.waiting) {
+                // A wrapper that passes on another atom's result (debounce, makeRefreshOnSignal) holds a
+                // value that atom made, and has no fiber of its own. A runtime's fiber isn't interrupted.
+                const ownWait = AsyncResult.isAsyncResult(value) &&
+                    value.waiting &&
+                    (origins.get(value) ?? node) === node;
+                if (ownWait && !isRuntime(node.atom)) {
                     emit({ _tag: "Interrupted", node, time: performance.now() });
                 }
                 emit({ _tag: "Finalized", finalizers, node, time: performance.now() });
@@ -86,13 +102,27 @@ const install = (registry) => {
                     time: performance.now(),
                 });
             },
+            removed: () => {
+                const self = record(node);
+                if (self.removing) {
+                    self.removing = false;
+                    emit({ _tag: "NodeRemoved", node, time: performance.now() });
+                }
+            },
             value: (previous, value) => {
                 const self = record(node);
+                if (AsyncResult.isAsyncResult(value) && !origins.has(value)) {
+                    origins.set(value, node);
+                }
                 const first = self.values === 0;
                 self.values += 1;
                 if (!first) {
                     for (const child of node.children) {
-                        record(child).changed.add(node);
+                        // A running build that hasn't read this node yet reads the new value: not a cause of
+                        // its next computation.
+                        if (!buildWillRead(child, node)) {
+                            record(child).changed.add(node);
+                        }
                     }
                 }
                 let source = "async";
@@ -115,8 +145,11 @@ const install = (registry) => {
         });
         complete &&= instrumented;
     };
-    const patchable = registry;
-    const { modify, onNodeAdded, onNodeRemoved, refresh, set, update } = patchable;
+    const { onNodeAdded, onNodeRemoved } = registry;
+    const modify = registry.modify.bind(registry);
+    const refresh = registry.refresh.bind(registry);
+    const set = registry.set.bind(registry);
+    const update = registry.update.bind(registry);
     const writes = (f) => {
         writing += 1;
         try {
@@ -126,25 +159,51 @@ const install = (registry) => {
             writing -= 1;
         }
     };
-    patchable.set = (atom, value) => writes(() => set.call(registry, atom, value));
-    patchable.update = (atom, f) => writes(() => update.call(registry, atom, f));
-    patchable.modify = (atom, f) => writes(() => modify.call(registry, atom, f));
-    // An atom with its own refresh (a wrapper such as withRefresh) calls the registry's refresh for
-    // the atoms it wraps, through this replacement, so each of those is marked too.
-    patchable.refresh = (atom) => {
-        const node = registry.getNodes().get(nodeKey(atom));
-        if (node !== undefined) {
-            record(node).refreshed = true;
-        }
-        refresh.call(registry, atom);
+    const patched = {
+        modify: (atom, f) => writes(() => modify(atom, f)),
+        // An atom with its own refresh (a wrapper such as withRefresh) calls the registry's refresh for
+        // the atoms it wraps, through this replacement, so each of those is marked too.
+        refresh: (atom) => {
+            const node = registry.getNodes().get(nodeKey(atom));
+            if (node !== undefined) {
+                record(node).refreshed = true;
+            }
+            try {
+                refresh(atom);
+            }
+            finally {
+                // Still valid: the refresh didn't reach it (what it wraps computed an equal value), or it
+                // computed already. Either way the mark isn't the cause of a later computation.
+                if (node?.currentState() === "valid") {
+                    record(node).refreshed = false;
+                }
+            }
+        },
+        set: (atom, value) => {
+            writes(() => {
+                set(atom, value);
+            });
+        },
+        update: (atom, f) => {
+            writes(() => {
+                update(atom, f);
+            });
+        },
     };
-    patchable.onNodeAdded = (node) => {
+    // Readonly in the interface: replaced on this registry only, as its nodes are.
+    Object.assign(registry, patched);
+    registry.onNodeAdded = (node) => {
         onNodeAdded?.(node);
         instrument(node);
         emit({ _tag: "NodeAdded", node, time: performance.now() });
     };
-    patchable.onNodeRemoved = (node) => {
+    registry.onNodeRemoved = (node) => {
         onNodeRemoved?.(node);
+        // An idle node is announced before it is removed; its teardown is reported first.
+        if (node.currentState() !== "removed" && records.has(node)) {
+            record(node).removing = true;
+            return;
+        }
         emit({ _tag: "NodeRemoved", node, time: performance.now() });
     };
     for (const node of registry.getNodes().values()) {
@@ -152,7 +211,7 @@ const install = (registry) => {
         // A node that has computed before isn't on its first read or value any more.
         if (node.currentState() !== "uninitialized") {
             const self = record(node);
-            self.builds = 1;
+            self.builds = holdsInitialValue(node) ? 0 : 1;
             self.values = 1;
         }
     }
@@ -161,8 +220,9 @@ const install = (registry) => {
             return complete;
         },
         idleTTL: (atom) => {
-            if (atom.keepAlive) {
-                return undefined;
+            // An idle TTL of 0 is none: the registry removes the atom as soon as nothing reads it.
+            if (atom.keepAlive || atom.idleTTL === 0) {
+                return;
             }
             return atom.idleTTL ?? defaultIdleTTL(registry);
         },
@@ -239,7 +299,9 @@ const emptySnapshot = { edges: [], nodes: [], readers: [] };
 /** The scope on the server: always empty. */
 const inertScope = {
     snapshot: () => emptySnapshot,
-    subscribe: () => () => undefined,
+    subscribe: () => () => {
+        // Nothing to unsubscribe from.
+    },
 };
 const stateOf = (node) => {
     // A valid node's value is read without computing anything.
@@ -251,6 +313,7 @@ const stateOf = (node) => {
 class Scope {
     #reads = new Map();
     #ids = new WeakMap();
+    #keyIds = new Map();
     #listeners = new Set();
     // The inspectors the scope follows while it has listeners, by registry.
     #following = new Map();
@@ -276,19 +339,31 @@ class Scope {
         },
     };
     #id(atom) {
-        let id = this.#ids.get(atom);
+        const key = nodeKey(atom);
+        let id = typeof key === "string" ? this.#keyIds.get(key) : this.#ids.get(atom);
         if (id === undefined) {
             this.#nextId += 1;
             id = this.#nextId;
-            this.#ids.set(atom, id);
+            if (typeof key === "string") {
+                this.#keyIds.set(key, id);
+            }
+            else {
+                this.#ids.set(atom, id);
+            }
         }
         return id;
     }
     /** Every node the scope's hooks use, and every node upstream of them. */
     #nodes() {
-        if (this.#members !== undefined) {
-            return this.#members;
+        // Without a listener the scope follows no inspector, so nothing would say the graph changed.
+        if (this.#listeners.size === 0) {
+            return this.#walk();
         }
+        this.#members ??= this.#walk();
+        return this.#members;
+    }
+    /** Works out the scope's nodes from the graph as it is now, without keeping them. */
+    #walk() {
         const members = new Set();
         const add = (node) => {
             if (!members.has(node)) {
@@ -304,7 +379,6 @@ class Scope {
                 add(node);
             }
         }
-        this.#members = members;
         return members;
     }
     /** The nearest shown atoms upstream of `node`, looking through those not shown. */
@@ -362,6 +436,11 @@ class Scope {
         return { edges, nodes: shown, readers };
     }
     subscribe(listener) {
+        if (this.#listeners.size === 0) {
+            // Kept from before the scope last stopped following, and the graph may have changed since.
+            this.#members = undefined;
+            this.#previous = new Set();
+        }
         this.#listeners.add(listener);
         for (const read of this.#reads.values()) {
             this.#follow(read.registry);
@@ -381,10 +460,15 @@ class Scope {
         if (this.#listeners.size === 0 || this.#following.has(registry)) {
             return;
         }
-        this.#following.set(registry, inspect(registry).subscribe((event) => this.#receive(event)));
+        this.#following.set(registry, inspect(registry).subscribe((event) => {
+            this.#receive(event);
+        }));
     }
     #receive(event) {
-        const inScope = this.#previous.has(event.node) || this.#nodes().has(event.node);
+        // Events arrive in the middle of the registry's work, while a computation is still changing
+        // the edges it reads through: what is worked out now isn't kept for the snapshot.
+        const inScope = this.#previous.has(event.node) ||
+            (this.#members ?? this.#walk()).has(event.node);
         if (event._tag === "NodeAdded" ||
             event._tag === "NodeRemoved" ||
             event._tag === "Built") {

package/dist/RegistryContext.d.ts

@@ -99,6 +99,8 @@ export type ProvideRegistryOptions = ProvideExistingRegistry | ProvideNewRegistr
  *
  * A registry created here is owned by the component and disposed of with it, which on the server
  * means at the end of the request. A registry passed in is left for the caller to dispose of.
+ * In the browser, a finalizer that throws while the provider disposes of its registry is reported
+ * as an uncaught error after teardown, rather than thrown into Svelte's teardown.
  *
  * **Example** (Giving the app a registry from the root layout)
  *

package/dist/RegistryContext.js

@@ -5,9 +5,12 @@
  */
 import { AtomRegistry } from "effect/reactivity";
 import { BROWSER, DEV } from "esm-env";
-import { createContext, onDestroy } from "svelte";
+import { createContext } from "svelte";
+import { disposeRegistry } from "./internal/disposal.js";
 import { setRevalidateOnHydrate } from "./internal/hydration.js";
 import { track } from "./internal/registries.js";
+import { onTeardownAfterChildren } from "./internal/teardown.svelte.js";
+import { troubleshooting } from "./internal/troubleshooting.js";
 const [getContextRegistry, setContextRegistry, hasContextRegistry] = createContext();
 let browserRegistry;
 /**
@@ -35,7 +38,7 @@ export const getRegistry = () => {
         return getContextRegistry();
     }
     if (!BROWSER) {
-        throw new Error("No AtomRegistry in context. Wrap the app in <RegistryProvider> so each server request gets its own registry.");
+        throw new Error(`No AtomRegistry in context. Wrap the app in <RegistryProvider> so each server request gets its own registry. ${troubleshooting("no-atomregistry-in-context")}`);
     }
     if (browserRegistry === undefined) {
         browserRegistry = AtomRegistry.make();
@@ -50,6 +53,8 @@ export const getRegistry = () => {
  *
  * A registry created here is owned by the component and disposed of with it, which on the server
  * means at the end of the request. A registry passed in is left for the caller to dispose of.
+ * In the browser, a finalizer that throws while the provider disposes of its registry is reported
+ * as an uncaught error after teardown, rather than thrown into Svelte's teardown.
  *
  * **Example** (Giving the app a registry from the root layout)
  *
@@ -77,19 +82,22 @@ export const provideRegistry = (options = {}) => {
     if (provided &&
         Object.values(registryOptions).some((value) => value !== undefined)) {
         // The types rule this out; a caller without them would otherwise lose the options silently.
-        throw new Error("provideRegistry takes an existing registry or options for a new one, not both. Apply initialValues to the existing registry yourself.");
+        throw new Error(`provideRegistry takes an existing registry or options for a new one, not both. Apply initialValues to the existing registry yourself. ${troubleshooting("provideregistry-takes-an-existing-registry-or-options-for-a-new-one-not-both")}`);
     }
     const registry = provided ?? AtomRegistry.make(registryOptions);
     setContextRegistry(registry);
     if (revalidateOnHydrate !== undefined) {
         setRevalidateOnHydrate(revalidateOnHydrate);
     }
+    // Not onDestroy: in the browser it never runs for a component destroyed while its script awaits.
     if (!provided) {
-        onDestroy(() => registry.dispose());
+        onTeardownAfterChildren(() => {
+            disposeRegistry(registry);
+        });
     }
     if (DEV && BROWSER) {
         // For developer tools to find (effect-atom-svelte/inspector).
-        onDestroy(track(registry));
+        onTeardownAfterChildren(track(registry));
     }
     return registry;
 };

package/dist/ScopedAtom.d.ts

@@ -49,10 +49,11 @@ export interface MakeOptions {
 /**
  * Creates a scoped atom from a factory, which runs once per providing component.
  *
- * Each provider gets its own atom, so a factory that adds `Atom.serializable` with a fixed key
- * gives every copy the same key: once two providers are on a page, reading them with
- * `useAtomResult` or `useAtomSuspense` throws, as two different atoms share the serialization
- * key. Put the input in the key, or leave scoped atoms unserialized.
+ * Each provider gets its own atom, so a factory that makes a serializable atom gives every copy of
+ * one input the same key, and two such providers on a server-rendered page make the render throw:
+ * two different atoms share the serialization key. For a value from the server, return a family's
+ * atom instead, `ScopedAtom.make((id: string) => userAtom(id))`, so every provider of one input
+ * holds the same atom.
  *
  * **Example** (A counter per subtree, started from an input)
  *