effect-atom-svelte 0.2.0 → 0.3.0

package/dist/Hooks.svelte.js

@@ -6,10 +6,15 @@
 import { Cause, Effect, Exit } from "effect";
 import { AsyncResult, Atom, AtomRegistry } from "effect/reactivity";
 import { BROWSER, DEV } from "esm-env";
-import { getAbortSignal, hydratable, onDestroy, untrack } from "svelte";
+import { getAbortSignal, hydratable, untrack } from "svelte";
 import { createSubscriber } from "svelte/reactivity";
-import { decodeSeed, encodeSeed, isWaiting, revalidatesOnHydrate, } from "./internal/hydration.js";
+import { queuedByBoundary } from "./internal/boundaries.js";
+import { onDispose } from "./internal/disposal.js";
+import { decodeSeed, encodeSeed, isWaiting, noSeed, revalidatesOnHydrate, } from "./internal/hydration.js";
+import { onRenderEnd } from "./internal/renderEnd.js";
 import { reportReads } from "./internal/scope.svelte.js";
+import { onTeardown } from "./internal/teardown.svelte.js";
+import { troubleshooting } from "./internal/troubleshooting.js";
 import { getRegistry } from "./RegistryContext.js";
 const toGetter = (input) => typeof input === "function" && !Atom.isAtom(input)
     ? input
@@ -38,20 +43,6 @@ const duringRead = (f) => {
         activeReads -= 1;
     }
 };
-/**
- * Runs `f` when the component is destroyed, even while its script is still awaiting. In the browser
- * `onDestroy` only takes effect once the component mounts, so a component removed while pending
- * would never call it. A pre effect runs during init and is torn down with the component (JND-16).
- * On the server, `onDestroy` runs when the render ends.
- */
-const onTeardown = (f) => {
-    if (BROWSER) {
-        $effect.pre(() => f);
-    }
-    else {
-        onDestroy(f);
-    }
-};
 /** Holds read and write closures; a class so `.current` is a real accessor `bind:` can use. */
 class AtomCell {
     #read;
@@ -68,7 +59,7 @@ class AtomCell {
     }
 }
 const readOnly = () => {
-    throw new Error("This atom value is read-only");
+    throw new Error(`This atom value is read-only: useAtomValue and useAtomSuspense only read, as does useAtomRef for a ref without set, such as one from map. Write an atom with useAtom or useAtomSet, and a writable ref by assigning useAtomRef's current. ${troubleshooting("this-atom-value-is-read-only")}`);
 };
 const valueOrThrow = (exit) => {
     if (Exit.isSuccess(exit)) {
@@ -76,13 +67,20 @@ const valueOrThrow = (exit) => {
     }
     throw Cause.squash(exit.cause);
 };
+/**
+ * Whether a result is `Initial` with nothing running to settle it, as an `Atom.fn` nothing has
+ * called. On the server nothing will start it during the render, so waiting would hang it.
+ */
+const notStarted = (result) => result._tag === "Initial" && !result.waiting;
 /**
  * Whether the atom has a `withServerValue` override. The server reads that instead and never
  * computes the atom, as its real read is often browser-only.
  */
 const hasServerValue = (atom) => Atom.ServerValueTypeId in atom;
 // SAFETY: ensureNode and scheduleNodeRemoval are on the registry implementation, not the interface
-// (Effect 4.0.0); @effect/atom-react uses ensureNode the same way.
+// (Effect 4.0.0); @effect/atom-react uses ensureNode the same way. Of the node's parts,
+// preserveInitialValueOnBuild, _value, setValue and failed (set while a first build has thrown)
+// are on its implementation too; the rest, currentState included, are on Effect's Node interface.
 const internals = (registry) => registry;
 /** The atom that holds a value given to `atom`: a wrapper such as `withRefresh` passes it on. */
 const initialValueTarget = (atom) => {
@@ -92,14 +90,14 @@ const initialValueTarget = (atom) => {
     }
     return target;
 };
-const noop = () => undefined;
 /**
  * Keeps an atom's node in the registry without computing it, as a mount would but without the read.
  * The registry sweeps a node without listeners, so a listener holds it; letting go schedules the
- * sweep, as an unsubscribe does.
+ * sweep, as an unsubscribe does. Each hold has its own listener: the node keeps its listeners in a
+ * set, so holds sharing one would all end with the first to let go.
  */
 const holdNode = (registry, node) => {
-    const unsubscribe = node.subscribe(noop);
+    const unsubscribe = node.subscribe(() => undefined);
     return () => {
         unsubscribe();
         if (node.canBeRemoved) {
@@ -107,34 +105,182 @@ const holdNode = (registry, node) => {
         }
     };
 };
+/**
+ * Lets a node that has taken a value since it was given an initial one compute as usual again.
+ * Effect's `setValue` (4.0.1) leaves the mark that tells a node's next build to keep its initial
+ * value, so a node given a seed or a `HydrationBoundary` value over one would keep that through its
+ * next build, a refresh's, and drop the build's result. Call it once the node holds a value of its
+ * own: after `setValue`, or after subscribing, which builds a node still waiting for its first build
+ * (using the mark up) and, as a lookup, applies a value a `HydrationBoundary` queued. Only a valid
+ * node loses the mark: a stale one still keeps its initial value through its first build. The atoms
+ * a wrapper such as `withRefresh` passes an initial value to are cleared too, as subscribing to the
+ * wrapper builds them.
+ */
+const dropInitialValueMark = (registry, atom) => {
+    let current = atom;
+    while (current) {
+        const node = internals(registry).ensureNode(current);
+        if (node.currentState() === "valid") {
+            node.preserveInitialValueOnBuild = false;
+        }
+        current = current.initialValueTarget;
+    }
+};
+/**
+ * On the server, the node holding a value from `useAtomInitialValues` for an atom: its own, or its
+ * source's for a wrapper such as `withRefresh`, which passes the value on and reads as its source.
+ * The server renders that value: mounting, reading or waiting for the atom would build it, and a
+ * build runs the atom's read, the source's included, even when it keeps the value. That read may be
+ * browser-only or start a request the value was there to save.
+ *
+ * For a wrapper, this assumes it reads as its source, as every wrapper Effect makes with
+ * `initialValueTarget` does. A user's `Atom.transform` given `initialValueTarget` that changes the
+ * value would render its source's value on the server, where Effect computes the transform.
+ */
+const initialNodeOnServer = (registry, atom) => {
+    if (BROWSER) {
+        return undefined;
+    }
+    const node = internals(registry).ensureNode(initialValueTarget(atom));
+    return node.preserveInitialValueOnBuild ? node : undefined;
+};
+/** Whether, on the server, an atom renders a value from `useAtomInitialValues`. */
+const initialOnServer = (registry, atom) => initialNodeOnServer(registry, atom) !== undefined;
+/** Keeps an atom for the server render: a node with an initial value is held, not mounted. */
+const serverMount = (registry, atom) => {
+    const node = initialNodeOnServer(registry, atom);
+    return node ? holdNode(internals(registry), node) : registry.mount(atom);
+};
+/** Reads an atom without building it on the server while it renders an initial value. */
+const serverGet = (registry, atom) => {
+    const node = initialNodeOnServer(registry, atom);
+    return node ? node._value : registry.get(atom);
+};
 const awaitResult = (registry, atom, options, signal) => Effect.runPromiseExit(AtomRegistry.getResult(registry, atom, options), {
     signal,
 });
-const subscribedReader = (registry, getAtom) => {
+/** Whether a hook stops waiting at a result: it has left `Initial`, and isn't refreshing if asked. */
+const settles = (result, suspendOnWaiting) => result._tag !== "Initial" && !(suspendOnWaiting && result.waiting);
+/**
+ * Waits for an async atom to settle, as `awaitResult` does, but resolves with the atom's own result
+ * rather than an `Exit` rebuilt from it, which would drop a `Failure`'s `previousSuccess`.
+ * Interrupted, with a failed `Exit`, once `signal` aborts.
+ */
+const awaitSettled = (registry, atom, options, signal) => {
+    const suspendOnWaiting = options.suspendOnWaiting ?? false;
+    return Effect.runPromiseExit(Effect.callback((resume) => {
+        const current = registry.get(atom);
+        if (settles(current, suspendOnWaiting)) {
+            resume(Effect.succeed(current));
+            return;
+        }
+        const cancel = registry.subscribe(atom, (value) => {
+            if (settles(value, suspendOnWaiting)) {
+                resume(Effect.succeed(value));
+                cancel();
+            }
+        });
+        return Effect.sync(cancel);
+    }), { signal });
+};
+/**
+ * A promise-mode setter's wait: as `awaitResult` with `suspendOnWaiting`, but a change to a result
+ * from before the call, which is what `Atom.Reset` from another setter leaves (an idle `Initial`,
+ * or an `Atom.fn`'s `initialValue`), ends it as interrupted. The reset interrupts the call, so
+ * otherwise the wait would hang until the next call, or settle with the initial value.
+ */
+const awaitWrite = (registry, atom, start, signal) => Effect.runPromiseExit(Effect.callback((resume) => {
+    const first = registry.get(atom);
+    if (first._tag !== "Initial" && !first.waiting) {
+        resume(AsyncResult.toExit(first));
+        return;
+    }
+    const cancel = registry.subscribe(atom, (result) => {
+        if (result.waiting) {
+            return;
+        }
+        cancel();
+        const reset = result._tag === "Initial" ||
+            (result._tag === "Success" && result.timestamp < start);
+        resume(reset
+            ? Exit.interrupt()
+            : AsyncResult.toExit(result));
+    });
+    return Effect.sync(cancel);
+}), { signal });
+// On the server, per registry, how many renders' seeds carry each key, until those renders end.
+const seededKeys = new WeakMap();
+/** Whether a render using the registry sends the key's result to the browser with a seed. */
+const seededOnServer = (registry, key) => (seededKeys.get(registry)?.get(key) ?? 0) > 0;
+/** Counts the key as seeded until the render ends. */
+const countSeeded = (registry, key) => {
+    let keys = seededKeys.get(registry);
+    if (!keys) {
+        keys = new Map();
+        seededKeys.set(registry, keys);
+    }
+    keys.set(key, (keys.get(key) ?? 0) + 1);
+    onRenderEnd(() => {
+        const count = (keys.get(key) ?? 1) - 1;
+        if (count > 0) {
+            keys.set(key, count);
+        }
+        else {
+            keys.delete(key);
+        }
+    });
+};
+// The keys of the atoms useAtomValue has warned about, so the server warns once per key, not per
+// request.
+const warnedUnsent = new Set();
+/**
+ * In development, warns once per key that a plain read on the server met a serializable async atom
+ * still running: only useAtomResult and useAtomSuspense send an atom's result to the browser, so
+ * the browser runs it again, and the page can show a loading state over what the server rendered.
+ * Not for a key the page sends anyway, with a seed or a HydrationBoundary's value, nor for a result
+ * nothing is computing, such as an Atom.fn nobody called or a value written to the atom.
+ */
+const warnUnsent = (registry, atom, value, hook) => {
+    if (!(DEV && Atom.isSerializable(atom) && AsyncResult.isAsyncResult(value)) ||
+        !value.waiting) {
+        return;
+    }
+    const { key } = atom[Atom.SerializableTypeId];
+    if (warnedUnsent.has(key) ||
+        queuedByBoundary(registry, key) ||
+        seededOnServer(registry, key)) {
+        return;
+    }
+    warnedUnsent.add(key);
+    console.warn(`effect-atom-svelte: ${hook} read the serializable atom "${key}" on the server while it was still running, but only useAtomResult and useAtomSuspense send an atom's result to the browser, so it runs again there. Read it with one of them. See https://atom.jarrednorris.dev/hydration#how-the-result-travels`);
+};
+/**
+ * Reads the getter's atom and follows it. `plainRead` names the plain read, `useAtomValue` or
+ * `useAtom`, for `warnUnsent`; the async hooks send their atom's result themselves.
+ */
+const subscribedReader = (registry, getAtom, plainRead) => {
     if (!BROWSER) {
         // Nothing subscribes during SSR, so without a mount the registry would sweep the node while the
         // render awaits, losing initial values and refetching async atoms. Mounting at setup, before any
-        // await, keeps it for the request. The mounts are released in onDestroy, which runs when the
-        // server render ends, because a registry passed in by the caller outlives the request (JND-17).
+        // await, keeps it for the request. The mounts are released when the server render ends,
+        // because a registry passed in by the caller outlives the request (JND-17).
         // An atom with a withServerValue override is never computed on the server, so it is not mounted:
-        // mounting would run its real read, which is often browser-only. Nor is one that holds a value
-        // from useAtomInitialValues: the server renders that value, which is what the atom's first build
-        // would keep, without running a read that may be browser-only or start a request.
+        // mounting would run its real read, which is often browser-only. One with a value from
+        // useAtomInitialValues is held and read without building it (see initialNodeOnServer).
+        // Once the render has ended, a read that switches atoms, as from a reader kept past the render,
+        // takes no mount: nothing would release it.
+        let ended = false;
         const releases = [];
-        onDestroy(() => {
+        onRenderEnd(() => {
+            ended = true;
             for (const release of releases) {
                 release();
             }
         });
-        const nodes = internals(registry);
         const mount = (atom) => {
-            if (hasServerValue(atom)) {
-                return atom;
+            if (!ended && !hasServerValue(atom)) {
+                releases.push(serverMount(registry, atom));
             }
-            const node = nodes.ensureNode(atom);
-            releases.push(node.preserveInitialValueOnBuild
-                ? holdNode(nodes, node)
-                : registry.mount(atom));
             return atom;
         };
         let mounted = mount(getAtom());
@@ -143,13 +289,18 @@ const subscribedReader = (registry, getAtom) => {
             if (atom !== mounted) {
                 mounted = mount(atom);
             }
-            if (!hasServerValue(atom)) {
-                const node = nodes.ensureNode(atom);
-                if (node.preserveInitialValueOnBuild) {
-                    return node._value;
-                }
+            if (hasServerValue(atom)) {
+                return Atom.getServerValue(atom, registry);
+            }
+            // An initial value is what the browser starts from too.
+            if (initialOnServer(registry, atom)) {
+                return serverGet(registry, atom);
             }
-            return Atom.getServerValue(atom, registry);
+            const value = registry.get(atom);
+            if (plainRead) {
+                warnUnsent(registry, atom, value, plainRead);
+            }
+            return value;
         };
     }
     reportReads(registry, getAtom, "read");
@@ -170,23 +321,30 @@ const subscribedReader = (registry, getAtom) => {
         kept?.cancel();
         kept = undefined;
     };
-    // Whether the component has mounted: its effects have run once.
-    let mounted = false;
     // The atom this reader's own registry.get is reading. A subscribed node is rebuilt as soon as it
     // goes stale, so the read builds it only the first time, and that build announces the very value
-    // the read returns. Before the component mounts, that announcement can only re-render its first
-    // render, which already has the value, so it is dropped. Delivered on a microtask it started a
-    // Svelte batch that, when the first render ran after an await in markup (a HydrationBoundary
-    // awaiting its state), committed before hydration's own and made Svelte's dev build throw "Batch
-    // has scheduled effects" (JND-95). After mount it is still delivered, as before. Nothing depends
-    // on the update it starts: a getter switched in onMount once did, by accident, as that update
-    // rendered before the registry swept the old atom (JND-98, fixed in the effect below).
+    // the read returns, so it is dropped: it could only re-render a read that already has the value.
+    // Before mount, delivered on a microtask it started a Svelte batch that, when the first render ran
+    // after an await in markup (a HydrationBoundary awaiting its state), committed before hydration's
+    // own and made Svelte's dev build throw "Batch has scheduled effects" (JND-95). After mount, a
+    // getter switched to an atom not built yet ran a transform twice, made a new object for an
+    // unchanged value, and re-ran an $effect that first read the atom. Only the build's own
+    // announcement is dropped: a value set during a registry batch is announced at commit, after
+    // `reading` is reset, and later changes arrive as usual. A getter switched in onMount once
+    // depended on that update, by accident (JND-98, fixed in the effect below). After mount, only a
+    // first build is dropped: a stale node the read rebuilds, as after a failed rebuild, announces a
+    // value the reader's other reads haven't seen.
+    let mounted = false;
     let reading;
-    const listen = (current, update) => registry.subscribe(current, () => {
-        if (mounted || reading !== current) {
-            update();
-        }
-    });
+    const listen = (current, update) => {
+        const unsubscribe = registry.subscribe(current, () => {
+            if (reading !== current) {
+                update();
+            }
+        });
+        dropInitialValueMark(registry, current);
+        return unsubscribe;
+    };
     const follow = (current) => {
         if (kept?.atom === current) {
             const { cancel: keptCancel } = kept;
@@ -213,8 +371,10 @@ const subscribedReader = (registry, getAtom) => {
         if (atom !== undefined && atom !== committed) {
             const previous = atom;
             const previousCancel = cancel;
+            // Subscribing can throw, as it rebuilds a stale atom; nothing moves until it has succeeded.
+            const next = follow(committed);
             atom = committed;
-            cancel = follow(committed);
+            cancel = next;
             if (previousCancel) {
                 releaseKept();
                 kept = { atom: previous, cancel: previousCancel };
@@ -236,8 +396,10 @@ const subscribedReader = (registry, getAtom) => {
         if (current !== atom) {
             const previous = atom;
             const previousCancel = cancel;
+            // As in the effect: a throwing subscribe leaves the reader on its old atom, to try again.
+            const next = follow(current);
             atom = current;
-            cancel = follow(current);
+            cancel = next;
             if (previous === committed &&
                 previous !== undefined &&
                 previousCancel) {
@@ -250,8 +412,17 @@ const subscribedReader = (registry, getAtom) => {
         }
         subscribe();
         const outer = reading;
-        reading = current;
+        if (!mounted) {
+            reading = current;
+        }
         try {
+            // After mount, only a first build is dropped: a stale node rebuilt here, as after a failed
+            // rebuild, announces a change other reads of this reader have not seen. A node whose first
+            // build failed is still uninitialized, but the page has shown that failure, so it counts too.
+            const node = internals(registry).ensureNode(current);
+            if (node.currentState() === "uninitialized" && !node.failed) {
+                reading = current;
+            }
             return registry.get(current);
         }
         finally {
@@ -260,7 +431,7 @@ const subscribedReader = (registry, getAtom) => {
     });
 };
 export function useAtomValue(input, f) {
-    const read = subscribedReader(getRegistry(), toGetter(input));
+    const read = subscribedReader(getRegistry(), toGetter(input), "useAtomValue");
     if (!f) {
         return new AtomCell(read, readOnly);
     }
@@ -290,14 +461,19 @@ export function useAtomValue(input, f) {
 export const useAtom = (input) => {
     const registry = getRegistry();
     const getAtom = toGetter(input);
-    return new AtomCell(subscribedReader(registry, getAtom), (value) => registry.set(getAtom(), value));
+    return new AtomCell(subscribedReader(registry, getAtom, "useAtom"), (value) => registry.set(getAtom(), value));
 };
 /** useAtomMount, telling an inspector scope why the atom is held: `useAtomSet` holds it to write. */
 const mountWhileAlive = (input, kind) => {
     const registry = getRegistry();
     const getAtom = toGetter(input);
     reportReads(registry, getAtom, kind);
-    $effect(() => registry.mount(getAtom()));
+    $effect(() => {
+        const atom = getAtom();
+        const release = registry.mount(atom);
+        dropInitialValueMark(registry, atom);
+        return release;
+    });
 };
 /**
  * Keeps an atom alive for as long as this component is mounted, even when no component reads
@@ -349,8 +525,21 @@ export function useAtomSet(input, options) {
             exit = Exit.interrupt();
         }
         else {
+            const start = Date.now();
             registry.set(atom, value);
-            exit = await awaitResult(registry, atom, { suspendOnWaiting: true }, writeOptions?.signal);
+            // A provider disposing of its registry ends the call without a last result, so the wait ends
+            // there too, as interrupted.
+            const controller = new AbortController();
+            const abort = () => controller.abort();
+            writeOptions?.signal?.addEventListener("abort", abort, { once: true });
+            const cancel = onDispose(registry, abort);
+            try {
+                exit = await awaitWrite(registry, atom, start, controller.signal);
+            }
+            finally {
+                cancel();
+                writeOptions?.signal?.removeEventListener("abort", abort);
+            }
         }
         return mode === "promiseExit" ? exit : valueOrThrow(exit);
     };
@@ -450,8 +639,11 @@ export const useAtomSubscribe = (input, f, options) => {
     const registry = getRegistry();
     const getAtom = toGetter(input);
     reportReads(registry, getAtom, "subscribe");
+    // The effect follows the atom, not what the getter reads: a getter that runs again and returns
+    // the same atom must not call `immediate` again, nor drop a change still waiting for delivery.
+    const current = $derived(getAtom());
     $effect(() => {
-        const atom = getAtom();
+        const atom = current;
         // `immediate` calls `f` now, inside this effect; what `f` reads must not re-run it.
         return untrack(() => {
             // registry.subscribe does not compute a node that has never been read, so an atom nothing
@@ -463,6 +655,7 @@ export const useAtomSubscribe = (input, f, options) => {
             }
             const deliver = orderedDelivery(f);
             const cancel = registry.subscribe(atom, deliver);
+            dropInitialValueMark(registry, atom);
             return () => {
                 deliver.stop();
                 cancel();
@@ -476,10 +669,14 @@ export const useAtomSubscribe = (input, f, options) => {
  */
 const setNodeValue = (registry, atom, value) => {
     internals(registry).ensureNode(atom).setValue(value);
+    dropInitialValueMark(registry, atom);
 };
 // The nodes given a value by useAtomInitialValues. A node belongs to one registry, and a node the
 // registry sweeps is gone from here too, so the next component to start it gives it the value again.
 const initialValuesApplied = new WeakSet();
+// On the server, how many renders hold each applied node. The value applies again only once none
+// does, so a request ending doesn't let a request starting overwrite the value another still renders.
+const serverHolders = new WeakMap();
 /**
  * Sets starting values as `AtomRegistry.make({ initialValues })` would: on the atom that receives it
  * (a wrapper such as `withRefresh` passes it to its source), kept as the value of the atom's first
@@ -489,9 +686,10 @@ const initialValuesApplied = new WeakSet();
  * an atom that can only compute in the browser can start from a value on the server.
  *
  * A value applies once while the atom is held, so a component mounted later, or a second
- * component with its own value, does not overwrite a value the atom has moved on from. Once nothing
- * holds the atom and the registry disposes it, the next component to start it applies its value
- * again. On the server a value lasts one render, so each request against a shared registry applies
+ * component with its own value, does not overwrite a value the atom has moved on from since the
+ * first applied one. An atom that is already in use without one, read by another component, is set
+ * to the value, as `@effect/atom-react` does. Once nothing holds the atom and the registry disposes
+ * it, the next component to start it applies its value again. On the server a value lasts one render, so each request against a shared registry applies
  * its own; requests rendering at the same time share the registry's atoms, and with them the value
  * the first one applied.
  *
@@ -515,51 +713,46 @@ const initialValuesApplied = new WeakSet();
 export const useAtomInitialValues = (initialValues) => {
     const registry = internals(getRegistry());
     const releases = [];
+    // Registered before the loop: an entry that throws midway leaves the earlier ones held otherwise.
+    onTeardown(() => {
+        for (const release of releases) {
+            release();
+        }
+    });
     for (const [atom, value] of initialValues) {
         const node = registry.ensureNode(initialValueTarget(atom));
         if (!initialValuesApplied.has(node)) {
             initialValuesApplied.add(node);
             node.setInitialValue(value);
-            if (!BROWSER) {
-                // A registry passed in by the caller outlives the request, and its node may not be swept
-                // before the next request starts, whose value must apply too (JND-17).
-                releases.push(() => initialValuesApplied.delete(node));
-            }
+        }
+        if (!BROWSER) {
+            // A registry passed in by the caller outlives the request, and its node may not be swept
+            // before the next request starts, whose value must apply too (JND-17). Requests rendering at
+            // the same time share the value the first applied, until the last of them ends.
+            serverHolders.set(node, (serverHolders.get(node) ?? 0) + 1);
+            releases.push(() => {
+                const holders = (serverHolders.get(node) ?? 1) - 1;
+                serverHolders.set(node, holders);
+                if (holders === 0) {
+                    initialValuesApplied.delete(node);
+                }
+            });
         }
         releases.push(holdNode(registry, node));
     }
-    onTeardown(() => {
-        for (const release of releases) {
-            release();
-        }
-    });
 };
-/**
- * Reads an `AtomRef`, following it when the getter returns a different ref. For one property of a
- * ref, use `useAtomRefPropValue`.
- *
- * A ref has no registry. On the server, one created at module level is shared by every request,
- * so don't write a visitor's data to it there: see
- * https://atom.jarrednorris.dev/server-rendering#module-state-is-shared-between-visitors
- *
- * **Example** (Reading a ref)
- *
- * ```ts
- * import { useAtomRef } from "effect-atom-svelte";
- * import { profile } from "./refs.ts";
- *
- * const current = useAtomRef(profile);
- * // In the markup: {current.current.name}
- * ```
- *
- * @stability unstable
- * @since 0.1.0
- * @category hooks
- */
-export const useAtomRef = (input) => {
+/** Writes a ref that has `set`; a read-only ref, as from `map`, throws as `useAtomValue` would. */
+const writeRef = (getRef) => (value) => {
+    const ref = getRef();
+    if (!("set" in ref)) {
+        readOnly();
+    }
+    ref.set(value);
+};
+export function useAtomRef(input) {
     const getRef = toGetter(input);
     if (!BROWSER) {
-        return new AtomCell(() => getRef().value, readOnly);
+        return new AtomCell(() => getRef().value, writeRef(getRef));
     }
     const ref = $derived(getRef());
     const subscribe = $derived.by(() => {
@@ -569,8 +762,8 @@ export const useAtomRef = (input) => {
     return new AtomCell(() => duringRead(() => {
         subscribe();
         return ref.value;
-    }), readOnly);
-};
+    }), writeRef(() => ref));
+}
 /**
  * Returns `ref.prop(prop)`, the `AtomRef` for one property of an `AtomRef`. It takes the ref
  * itself, not a getter, and does not follow later changes to `ref` or `prop`; to read a property
@@ -593,7 +786,8 @@ export const useAtomRef = (input) => {
 export const useAtomRefProp = (ref, prop) => ref.prop(prop);
 /**
  * Reads one property of an `AtomRef`, following the getter to a different ref. `prop` is taken
- * once, when the component starts, and is not followed.
+ * once, when the component starts, and is not followed. Assigning `current` sets the property, so
+ * `bind:checked={done.current}` works.
  *
  * **Example** (Reading one property of a ref)
  *
@@ -614,11 +808,6 @@ export const useAtomRefPropValue = (input, prop) => {
     const propRef = $derived(getRef().prop(prop));
     return useAtomRef(() => propRef);
 };
-/**
- * Whether a result is `Initial` with nothing running to settle it, as an `Atom.fn` nothing has
- * called. On the server nothing will start it during the render, so waiting would hang it.
- */
-const notStarted = (result) => result._tag === "Initial" && !result.waiting;
 const notStartedError = (hook) => new Error(`${hook} read an atom that has not started on the server: its result is Initial and nothing is running it, as for an Atom.fn that has not been called, so the render would wait for it forever. Read it with useAtomValue, which renders Initial, or inside a <svelte:boundary> with a pending snippet, which the server renders instead.`);
 /**
  * Puts the server's value in the registry as current, so nothing fetches it again (JND-19). Seeding
@@ -639,15 +828,25 @@ const applySeed = (registry, atom, value, revalidate) => {
 const seeds = new WeakMap();
 // hydratable returns one promise per key per render, so it identifies the atom that claimed a key.
 const serverSeeds = new WeakMap();
+// The keys, by their render's promise, that some reader reads with suspendOnWaiting: the seed is
+// then the settled result that reader renders, whichever reader claimed the key first.
+const settledSeeds = new WeakSet();
 /**
  * On the server each request seeds for itself: `hydratable` already shares one result per key
  * within a render, and a per-registry record would outlive the request when the caller owns the
  * registry, so later requests would skip embedding their seed (JND-17).
  */
-const seedOnServer = (registry, atom, key, encode) => {
+const seedOnServer = (registry, atom, key, encode, suspendOnWaiting) => {
     // Mounted until the render ends, so the settled node is what the render reads.
-    const release = registry.mount(atom);
-    onDestroy(release);
+    const release = serverMount(registry, atom);
+    // A render ends before its seeds settle only when it fails, as when a later reader throws during
+    // setup. The provider has disposed of the registry by then, so the seed reads nothing from it.
+    let ended = false;
+    onRenderEnd(() => {
+        ended = true;
+        release();
+    });
+    countSeeded(registry, key);
     // hydratable hands every later reader of a key the first reader's value, but Svelte's dev build
     // also runs each later reader's callback and throws hydratable_clobbering if what it encodes
     // differs. Reading the atom again there would encode whatever it holds by then, so a later
@@ -657,21 +856,38 @@ const seedOnServer = (registry, atom, key, encode) => {
     const encoded = hydratable(key, () => {
         claim.own = (async () => {
             await undefined;
+            if (ended) {
+                return noSeed;
+            }
             if (claim.first !== claim.own) {
                 return await claim.first;
             }
-            // Not waited for if nothing has started it: the hook rejects once seeded.
-            if (!notStarted(registry.get(atom))) {
-                await awaitResult(registry, atom);
+            // Not waited for if nothing has started it: the hook rejects once seeded. Waited for as the hook
+            // waits, so with suspendOnWaiting the seed is the settled result the render shows, not one the
+            // browser would run again because it was still waiting.
+            if (!initialOnServer(registry, atom) && !notStarted(registry.get(atom))) {
+                let settled = suspendOnWaiting === true;
+                await awaitResult(registry, atom, { suspendOnWaiting: settled });
+                // A later reader of the key may want the settled result once this one's wait has begun.
+                if (!settled && claim.first && settledSeeds.has(claim.first)) {
+                    settled = true;
+                    await awaitResult(registry, atom, { suspendOnWaiting: settled });
+                }
+            }
+            if (ended) {
+                return noSeed;
             }
-            return encodeSeed(key, encode, registry.get(atom));
+            return encodeSeed(key, encode, serverGet(registry, atom));
         })();
         return claim.own;
     });
     claim.first = encoded;
+    if (suspendOnWaiting === true) {
+        settledSeeds.add(encoded);
+    }
     const claimed = serverSeeds.get(encoded);
     if (claimed && claimed !== atom) {
-        throw new Error(`Two different atoms share the serialization key "${key}"`);
+        throw new Error(`Two different atoms share the serialization key "${key}", so the server can't tell whose result to send. Put what tells the copies apart into the key, such as an id, and define atoms at module level. ${troubleshooting("two-different-atoms-share-the-serialization-key")}`);
     }
     serverSeeds.set(encoded, atom);
     return (async () => {
@@ -694,7 +910,10 @@ const serverValues = () => {
 };
 const warnIfSent = async (key, sent) => {
     try {
-        if ((await sent) === undefined) {
+        // Undefined when the key wasn't sent, null when the server sent that it had no seed for it, as
+        // for a defect: either way the browser was always going to compute the atom.
+        const value = await sent;
+        if (value === undefined || value === null) {
             return;
         }
     }
@@ -738,7 +957,7 @@ const claimServerValue = (key, missed) => {
  * serialization key. The atom is fetched again once seeded if any component using the key then
  * asked to revalidate.
  */
-const seedFromServer = (registry, getAtom, revalidateOption) => {
+const seedFromServer = (registry, getAtom, revalidateOption, suspendOnWaiting) => {
     const atom = getAtom();
     // The server never computes an atom with a server value, so it has no value to pass on, and the
     // browser must not ask for one: hydratable throws for a key the server didn't write (JND-58).
@@ -748,7 +967,7 @@ const seedFromServer = (registry, getAtom, revalidateOption) => {
     const { decode, encode, key } = atom[Atom.SerializableTypeId];
     if (!BROWSER) {
         return {
-            done: seedOnServer(registry, atom, key, encode),
+            done: seedOnServer(registry, atom, key, encode, suspendOnWaiting),
             letGo: noSeedMount,
         };
     }
@@ -759,10 +978,11 @@ const seedFromServer = (registry, getAtom, revalidateOption) => {
         seeds.set(registry, registrySeeds);
     }
     const { held, spent } = registrySeeds;
+    // The server's value belongs to the key, not to an atom: the registry keeps a serializable atom's
+    // value under its key, so every atom with the key reads it, as HydrationBoundary assumes too.
+    // A remounted branch, as under {#key}, makes a new atom with the old one's key while the old one
+    // still holds it, until Svelte destroys the old branch or its outro ends: the new atom joins it.
     let entry = held.get(key);
-    if (entry && entry.atom !== atom) {
-        throw new Error(`Two different atoms share the serialization key "${key}"`);
-    }
     if (!entry && spent.has(key)) {
         return undefined;
     }
@@ -780,7 +1000,6 @@ const seedFromServer = (registry, getAtom, revalidateOption) => {
         let holders = 0;
         let revalidating = 0;
         entry = {
-            atom,
             done: (async () => {
                 const value = await encoded;
                 // Only the server's value is a seed, and only while someone is there to read it now: a seed
@@ -788,7 +1007,9 @@ const seedFromServer = (registry, getAtom, revalidateOption) => {
                 // The server sends no seed for a result it can't or mustn't pass on, such as a defect: the
                 // atom computes here instead. A seed still waiting, as a stream's between its values, runs
                 // again too: the server's run ended with the render, so it would wait forever.
-                const seed = !computedHere && holders > 0 ? decodeSeed(value, decode) : undefined;
+                const seed = !computedHere && holders > 0
+                    ? decodeSeed(key, value, decode)
+                    : undefined;
                 if (seed !== undefined) {
                     applySeed(registry, atom, seed, revalidating > 0 || isWaiting(seed));
                 }
@@ -878,7 +1099,7 @@ const seedFromServer = (registry, getAtom, revalidateOption) => {
 export const useAtomResult = async (input, options) => {
     const registry = getRegistry();
     const getAtom = toGetter(input);
-    const value = useAtomValue(getAtom);
+    const value = new AtomCell(subscribedReader(registry, getAtom), readOnly);
     const atom = getAtom();
     let release;
     // Aborted when the component is destroyed, which interrupts the wait below so the atom is not held.
@@ -897,7 +1118,7 @@ export const useAtomResult = async (input, options) => {
         release = undefined;
         return unmount;
     });
-    const seed = seedFromServer(registry, getAtom, options?.revalidateOnHydrate);
+    const seed = seedFromServer(registry, getAtom, options?.revalidateOnHydrate, options?.suspendOnWaiting);
     if (seed) {
         await seed.done;
     }
@@ -906,6 +1127,11 @@ export const useAtomResult = async (input, options) => {
     if (lifetime.signal.aborted || (!BROWSER && hasServerValue(atom))) {
         return value;
     }
+    // On the server, an initial value is what the render shows, with nothing to wait for.
+    if (initialOnServer(registry, atom)) {
+        release = serverMount(registry, atom);
+        return value;
+    }
     if (effectHolds) {
         // Mounted while seeding, as when the promise is not awaited straight away: the effect holds the
         // getter's atom, and a mount here would never be released. Once the getter has switched away,
@@ -946,7 +1172,7 @@ const fromSettled = (current, options) => {
  */
 const fromServerValue = (current, options) => {
     if (isPending(current, options)) {
-        return Promise.reject(new Error("useAtomSuspense read an atom whose server value is pending, so the server has nothing to render. Read it inside a <svelte:boundary> with a pending snippet, which the server renders instead, or use useAtomResult."));
+        return Promise.reject(new Error(`useAtomSuspense read an atom whose server value is pending, so the server has nothing to render. Read it inside a <svelte:boundary> with a pending snippet, which the server renders instead, or use useAtomResult. ${troubleshooting("useatomsuspense-read-an-atom-whose-server-value-is-pending")}`));
     }
     try {
         return Promise.resolve(fromSettled(current, options));
@@ -960,17 +1186,16 @@ const suspend = async (registry, atom, current, options, signal) => {
         if (!BROWSER && notStarted(current)) {
             throw notStartedError("useAtomSuspense");
         }
-        const exit = await awaitResult(registry, atom, { suspendOnWaiting: options.suspendOnWaiting }, signal);
+        const exit = await awaitSettled(registry, atom, { suspendOnWaiting: options.suspendOnWaiting }, signal);
         // Abandoned: rejects with the reason its last reader's signal was aborted with. For a re-run
         // that is Svelte's STALE_REACTION, which it ignores, so a pending render that still awaits this
         // wait keeps waiting for its next run instead of showing the interruption (JND-22).
         signal.throwIfAborted();
-        if (options.includeFailure) {
-            return Exit.isSuccess(exit)
-                ? AsyncResult.success(exit.value)
-                : AsyncResult.failure(exit.cause);
+        // Only an abort, handled above, ends the wait without a result.
+        if (Exit.isFailure(exit)) {
+            throw Cause.squash(exit.cause);
         }
-        return valueOrThrow(exit);
+        return fromSettled(exit.value, options);
     }
     return fromSettled(current, options);
 };
@@ -1056,13 +1281,14 @@ const sharedWait = (start, onAbandoned) => {
             listeners.push([signal, listener]);
         },
         promise,
+        settled: () => settled,
     };
 };
 export function useAtomSuspense(input, options = {}) {
     const registry = getRegistry();
     const getAtom = toGetter(input);
-    const result = useAtomValue(getAtom);
-    const seed = seedFromServer(registry, getAtom, options.revalidateOnHydrate);
+    const result = new AtomCell(subscribedReader(registry, getAtom), readOnly);
+    const seed = seedFromServer(registry, getAtom, options.revalidateOnHydrate, options.suspendOnWaiting);
     // A plain variable, not $state: a render in a batch with this write rolled back would take the
     // pre-seed path and track nothing but the flag. Reading `trackSeed` asks for a re-read instead.
     let seeded = seed === undefined;
@@ -1091,10 +1317,48 @@ export function useAtomSuspense(input, options = {}) {
     // Holds waits read outside any derived or effect (a top-level await in the script, an event
     // handler), which cannot say when they are done with them, until the component is destroyed.
     const lifetime = new AbortController();
-    onTeardown(() => lifetime.abort());
+    // Each reaction's signal, also aborted when the component is destroyed. Svelte aborts a derived's
+    // signal when it runs again or loses its last reader, and doesn't destroy deriveds with their
+    // component, so a derived only the script or an event handler reads would never abort it, and
+    // the wait it holds would keep the atom after the component is gone. Kept per signal, so a signal
+    // still holds a wait once (see sharedWait); those still live are aborted at teardown.
+    const bounded = new WeakMap();
+    const liveAborts = new Set();
+    onTeardown(() => {
+        lifetime.abort();
+        // Each abort deletes itself, which a Set's iteration allows.
+        for (const abort of liveAborts) {
+            abort();
+        }
+    });
+    const untilDestroyed = (signal) => {
+        let combined = bounded.get(signal);
+        if (!combined) {
+            const controller = new AbortController();
+            combined = controller.signal;
+            bounded.set(signal, combined);
+            // The reaction's reason, such as Svelte's STALE_REACTION, which it ignores (JND-22).
+            const reason = () => signal.aborted ? signal.reason : lifetime.signal.reason;
+            if (signal.aborted || lifetime.signal.aborted) {
+                controller.abort(reason());
+            }
+            else {
+                const abort = () => {
+                    liveAborts.delete(abort);
+                    signal.removeEventListener("abort", abort);
+                    controller.abort(reason());
+                };
+                liveAborts.add(abort);
+                signal.addEventListener("abort", abort, { once: true });
+            }
+        }
+        return combined;
+    };
     // Keyed by atom, then result: atoms can share a result object, as a derived atom returning its
     // source's result does, and a wait holds and waits for one atom.
     const waits = new WeakMap();
+    // Per atom, the wait the last read got, for a read after the component is destroyed.
+    const lastWaits = new WeakMap();
     const settle = (atom, current, signal) => {
         let atomWaits = waits.get(atom);
         if (!atomWaits) {
@@ -1108,6 +1372,7 @@ export function useAtomSuspense(input, options = {}) {
             atomWaits.set(current, wait);
         }
         wait.hold(signal);
+        lastWaits.set(atom, wait);
         return wait.promise;
     };
     const fromServer = new WeakMap();
@@ -1122,6 +1387,27 @@ export function useAtomSuspense(input, options = {}) {
             return promise;
         }
         const signal = readerSignal();
+        const holder = signal ? untilDestroyed(signal) : lifetime.signal;
+        if (holder.aborted) {
+            // Read once the reader is gone, as in onDestroy or a handler that resumes after the component
+            // is destroyed. A result it had settled is still there; a new wait would hold the atom until it
+            // settles, as nothing could let go of it. Handled here, so a read nobody awaits isn't reported
+            // as unhandled.
+            const last = lastWaits.get(getAtom());
+            if (last?.settled()) {
+                return last.promise;
+            }
+            const gone = Promise.reject(holder.reason);
+            void (async () => {
+                try {
+                    await gone;
+                }
+                catch {
+                    // Belongs to whoever awaits it.
+                }
+            })();
+            return gone;
+        }
         if (!seeded && seed) {
             // Reading the atom before the seed lands would fetch what hydration is about to provide.
             const atom = getAtom();
@@ -1138,9 +1424,15 @@ export function useAtomSuspense(input, options = {}) {
                     if (live.length === 0) {
                         return undefined;
                     }
-                    holdWhileRead(registry, atom, live);
+                    // A read outside any reaction can't say when it is done, so it doesn't hold the atom: held
+                    // by the component's lifetime, the atom would stay mounted after the getter moves on.
+                    const reactions = live.filter((reader) => reader !== lifetime.signal);
+                    if (reactions.length > 0) {
+                        holdWhileRead(registry, atom, reactions);
+                    }
                     seed.letGo();
-                    const current = registry.get(atom);
+                    // On the server, an initial value is read without building the atom.
+                    const current = serverGet(registry, atom);
                     let waited;
                     for (const reader of live) {
                         waited = settle(atom, current, reader);
@@ -1150,10 +1442,10 @@ export function useAtomSuspense(input, options = {}) {
                 pending = { promise, readers };
                 afterSeed.set(atom, pending);
             }
-            pending.readers.add(signal ?? lifetime.signal);
+            pending.readers.add(holder);
             return pending.promise;
         }
-        const promise = settle(getAtom(), result.current, signal ?? lifetime.signal);
+        const promise = settle(getAtom(), result.current, holder);
         if (signal) {
             // A reaction read it, so the reader's subscription holds the atom from here.
             seed?.letGo();