raf-effect-atom 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,111 @@
+# Changelog
+
+## 0.1.0 (2026-10-23)
+
+### ⚠ BREAKING CHANGES
+
+* **raf-effect-atom:** `useAtomResult(atom, claims)` is gone. Read
+  `useAtomResult(boundary.wrap(atom))` instead. `effect-atom-boundary` is no
+  longer a peer dependency.
+
+  effect-atom-boundary stays a devDependency, so the hook's tests still read
+  through a real boundary's wrap (claimed tag thrown to the boundary, others
+  returned). The type test now checks that a derived atom with an
+  initialValueTarget is read with its own type.
+
+  The request waterfalls docs sample, written against the claims overload,
+  reads through `useIssueBoundary().wrap(atom)` too.
+* **raf-effect-atom:** follow initialValueTarget in useAtomResult and throw defects
+* **raf-effect-atom:** the loader verbs take a source and its arguments and
+  return a handle, and `useAtomResult` reads a handle through a source.
+
+  - `prefetch(issue, id)` returns a `Handle<typeof issue>`; `ensure` and
+    `fetch` return a `LoadedHandle`, which adds `loaded: true`. A source is
+    an atom family, such as an AtomRpc query, or one AsyncResult atom, whose
+    handle has no arguments. The same holds for `Loader.make(registry)`, the
+    router contexts' `atoms` and `raf-effect-atom/next`'s verbs.
+  - A handle is plain data, `{ args, key }`, so loaders return it in their
+    data and server components pass it to client components as a prop. Its
+    type names its source through a brand on the key, `HandleKey<S>`, so
+    one family's handle doesn't fit another's prop. The brand is on the key
+    because React Router's `Serialize` type drops an optional phantom field
+    from loader data and keeps branded strings; an atom source's args are a
+    mutable `[]` because `Serialize<readonly []>` is `readonly never[]`.
+  - `Loader.result(handle)` gives loader code the settled result of an
+    `ensure` or `fetch`. The result can't ride on the handle: AsyncResult and
+    Schema classes don't survive turbo-stream, seroval, JSON or server
+    component props. It's kept in a WeakMap keyed by the handle object, and
+    a copy of the handle throws.
+  - `useAtomResult(source, handle)` reads `source(...handle.args)`. Its
+    handle parameter widens the source's error to `unknown`, so a boundary's
+    `wrap(issue)` reads `issue`'s handles with the per-tag narrowing and the
+    `Success<A, never>` typing kept. In development it throws when the atom
+    it hydrates has a serialization key other than the handle's.
+  - `useWaterfall(source, ...args)` returns a handle, the one way to make a
+    handle during render.
+
+  The waterfall warning names the new call shapes.
+
+  Migrated with it, so no commit has a red tree:
+  - The three example apps: loaders return the handles of the atoms they
+    start, and pages pass them down (TanStack Start through
+    `Route.useLoaderData()`, React Router through `loaderData.handles` next
+    to the dehydrated atoms, Next.js as server component props). Components
+    take a handle instead of an id. "Load more" keeps the next page's handle
+    in state, made by `Loader.make(registry).prefetch(source, ...args)` in
+    the click handler.
+  - www: the docs route, demo embeds and the loader-verbs, waterfalls,
+    hydration, boundary-chain and every-tag-caught demos; the TanStack Start, Next.js and
+    React Router doc samples, the error-boundaries and every-tag-caught
+    samples included; the home page's steps; and the pages that
+    show the verbs and reads (loader verbs gains a Handles section and
+    `Loader.result`, reading atoms explains handles as props, request
+    waterfalls, coding agents, shared boundaries, error boundaries, loader
+    failures).
+    `www/src/use-loaded.ts` is gone: a wrapper generic over a family can't
+    satisfy `useAtomResult`'s `Readable` constraint, and
+    `useAtomResult(source, handle).value` reads as well. The "Fetches in a
+    component" mistake on the home page is now caught by the compiler.
+  - The package READMEs, the boundary's JSDoc example, and the decision in
+    `.agent-docs/decisions/atom-handles.md`.
+
+### Features
+
+* **raf-effect-atom:** add the next subpath ([92cacd8](https://github.com/KATT/raf-effect-atom/commit/92cacd86cb6d6e1784d9a07f71bd9fc3ec5ca0da))
+* **raf-effect-atom:** add the react-router subpath ([09b65dc](https://github.com/KATT/raf-effect-atom/commit/09b65dcbc6cfde2ae1ba2bb89e580746e9512f8b))
+* **raf-effect-atom:** add the tanstack-router subpath ([0189c83](https://github.com/KATT/raf-effect-atom/commit/0189c834cd46fc05ed866859e7527b3bd2ac47df))
+* **raf-effect-atom:** drop the claims overload and the effect-atom-boundary peer ([48fe91e](https://github.com/KATT/raf-effect-atom/commit/48fe91eabf71a0eb36b49c907fabae7afa5abd90))
+* **raf-effect-atom:** follow initialValueTarget in useAtomResult and throw defects ([7f577ea](https://github.com/KATT/raf-effect-atom/commit/7f577eabbdd567313b542db61d532bb36a2183ca))
+* **raf-effect-atom:** loader verbs return handles that components read ([52a4323](https://github.com/KATT/raf-effect-atom/commit/52a4323bae1507e6b5f524262b7ed1609b1ed5d6))
+* **raf-effect-atom:** loader verbs, streaming hydration and the read hook ([6870b1a](https://github.com/KATT/raf-effect-atom/commit/6870b1a9c7742d2fa15ce1391c8fdac66307d89e))
+* **raf-effect-atom:** make the browser registry's idle TTL configurable ([1c55d0e](https://github.com/KATT/raf-effect-atom/commit/1c55d0e74f54bed7cef895434357355229cff512))
+* **raf-effect-atom:** read the loader's registry under HydrationBoundary during server rendering ([6751792](https://github.com/KATT/raf-effect-atom/commit/675179254563b85c61f9a96e646fa9c72f47cc83))
+* **raf-effect-atom:** report request waterfalls in development, with useWaterfall as the escape hatch ([4b6fe2a](https://github.com/KATT/raf-effect-atom/commit/4b6fe2aebb939ea0a7095a5121558aa0cbc5bac5))
+* **raf-effect-atom:** type useAtomResult as a success when no typed failure is left ([aeb8dc6](https://github.com/KATT/raf-effect-atom/commit/aeb8dc63e0ad874a23c3a992afed540c27c9bb7d))
+
+### Bug Fixes
+
+* **raf-effect-atom:** call use() on a streamed result's promise on every render that reads it ([36d2aaa](https://github.com/KATT/raf-effect-atom/commit/36d2aaa8bacf18a60507e4997fd61476d7a908c0)), references [#41](https://github.com/KATT/raf-effect-atom/issues/41)
+* **raf-effect-atom:** point waterfall reports at the URL before the escape hatches ([0d127e3](https://github.com/KATT/raf-effect-atom/commit/0d127e38a10cb3a44340c5540c75b53491faceee))
+* **raf-effect-atom:** refresh the atom the registry runs for a key in Loader.fetch ([0b35c97](https://github.com/KATT/raf-effect-atom/commit/0b35c97b4de60de254c7fc921b89aed7be753ec8))
+* **raf-effect-atom:** wait for results streamed in a server component payload ([00cb981](https://github.com/KATT/raf-effect-atom/commit/00cb98125aad2cda70525fbfdedcd2b5a8f7fc79))
+
+### Code Refactoring
+
+* **examples:** read boundary claims through wrap ([ae92f67](https://github.com/KATT/raf-effect-atom/commit/ae92f67722417542ee06a7299b327a77a0597814))
+* **raf-effect-atom:** rename files to kebab-case ([285bf4b](https://github.com/KATT/raf-effect-atom/commit/285bf4b4e5e3184ac162129f51c04d9c96921650))
+* **raf-effect-atom:** restore Effect's file names ([92dc1d8](https://github.com/KATT/raf-effect-atom/commit/92dc1d8e52212c28042153cbd7b1146870839831))
+
+### Documentation
+
+* catch RpcClientError in an app boundary, and read fully claimed atoms as successes ([fe9b485](https://github.com/KATT/raf-effect-atom/commit/fe9b485fd19643a34f1709ebb5b66c90036eea47))
+* point coding agents at the rules from the READMEs ([e8d3047](https://github.com/KATT/raf-effect-atom/commit/e8d30477e840df83c0f47764bdf505bc61181f14))
+* **raf-effect-atom:** add the package README ([69c589e](https://github.com/KATT/raf-effect-atom/commit/69c589e020527ca087d7a54fb99544460ebc7774))
+
+### Tests
+
+* keep each package's Vitest module cache to itself ([be11618](https://github.com/KATT/raf-effect-atom/commit/be11618b41f9cecaba6968a356677a7dd3bfe734))
+
+### Continuous Integration
+
+* release each changed package after CI passes on main, and pack-check the tarballs on every push ([8ab3b90](https://github.com/KATT/raf-effect-atom/commit/8ab3b90e4ac2e7d6c25c028aace7167279bdb2b3))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex / KATT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,66 @@
-# Temporary Holding Version
+# raf-effect-atom
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Render-as-you-fetch for [Effect Atom](https://github.com/Effect-TS/effect/tree/main/packages/atom/react). Route loaders start atoms before anything renders, the server streams their results into the browser, and the browser reads them without requesting them again. Typed failures survive the trip: a server-side `IssueNotFound` is an `IssueNotFound` in the browser.
+
+**[GitHub](https://github.com/KATT/raf-effect-atom)**
+
+> [!NOTE]
+> raf-effect-atom is early. The API can still change between minor releases.
+
+## Install
+
+```bash
+npm install raf-effect-atom effect @effect/atom-react react
+```
+
+`effect`, `@effect/atom-react` and `react` (19.2 or newer) are peer dependencies.
+
+## Usage
+
+A loader starts atoms with a verb per call, given an atom family and its arguments. `prefetch` starts one and streams it, `ensure` waits for its first result, and `fetch` waits for a fresh one. Each returns a handle, plain data naming the atom, which the loader returns for the page to pass down. Typed failures come back as results, so a loader can redirect on a tag:
+
+```ts
+import { Loader } from "raf-effect-atom";
+
+// issue: (id: number) => an AtomRpc query with a serializationKey
+export async function loader(args: LoaderArgs) {
+	const id = Number(args.params.id);
+	const handles = {
+		comments: args.context.atoms.prefetch(comments, id),
+		issue: await args.context.atoms.ensure(issue, id),
+	};
+	const result = Loader.result(handles.issue);
+	if (AsyncResult.isFailure(result)) {
+		// result.cause holds IssueNotFound | Unauthorized | RpcClientError
+	}
+	return handles;
+}
+```
+
+A component takes the handle as a prop and reads it with `useAtomResult(source, handle)`, which waits for a streamed result instead of starting the atom again, and returns typed failures. Given a handle instead of an id, it can't start a request of its own. The source can be a family derived from the loader's, such as the one an [`effect-atom-boundary`](https://github.com/KATT/raf-effect-atom/tree/main/packages/effect-atom-boundary) boundary's `wrap` returns, which throws the errors that boundary claims to it:
+
+```tsx
+import { type Handle, useAtomResult } from "raf-effect-atom";
+
+function IssueTitle(props: { readonly issue: Handle<typeof issue> }) {
+	const result = useAtomResult(useIssueBoundary().wrap(issue), props.issue);
+	// Success<Issue, never>: its boundaries claim every failure
+	return <h1>{result.value.title}</h1>;
+}
+```
+
+Each framework has a subpath that gives every server request its own registry and sends it to the browser:
+
+- `raf-effect-atom/tanstack-router`, for TanStack Router and TanStack Start: `setupRouterAtoms({ router, registry })` in `getRouter`, with `Loader.make(registry)` on the router context.
+- `raf-effect-atom/next`, for the App Router: `prefetch`, `ensure` and `fetch` in server components, which pass the handles to client components as props, and `<HydrateAtoms state={dehydrate()}>` around them.
+- `raf-effect-atom/react-router`, for Framework Mode: `atomsMiddleware(atomsContext)` as the root middleware, loaders that return `atoms.dehydrate()` with their handles, and `HydrationBoundary` in the route component.
+
+In development, `useAtomResult` reports a read that starts an atom nothing started, a request waterfall. `<WaterfallDetection mode="throw">` at the root makes it throw to the nearest error boundary. `useWaterfall(source, ...args)` starts an atom whose input exists only in render, marks it as a known waterfall, and returns its handle.
+
+## For coding agents
+
+Start every atom in a loader or a server component, never in a component or `useEffect`, and put the state that picks data (pages, filters, open dialogs) in the URL so the loader can. Event handlers and `useWaterfall` are escape hatches for state that can't be in the URL. Pass components the handles the loader returns, not ids, and read them with `useAtomResult`, not `useAtomValue` or `useAtomSuspense`. Keep `<WaterfallDetection mode="throw">` at the root and fix what it reports instead of turning it off. The full rules, with the reason for each: [For coding agents](https://raf-effect-atom.katt.dev/docs/coding-agents). The docs as markdown: [llms.txt](https://raf-effect-atom.katt.dev/llms.txt).
+
+## License
+
+MIT

package/dist/Handle.d.mts

@@ -0,0 +1,90 @@
+import * as Atom from "effect/reactivity/Atom";
+import * as AsyncResult from "effect/reactivity/AsyncResult";
+/**
+ * What the verbs start and `useAtomResult` reads: an atom family, a function
+ * from arguments to an `AsyncResult` atom such as an `AtomRpc` query, or an
+ * `AsyncResult` atom that takes no arguments.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export type Source = Atom.Atom<AsyncResult.AsyncResult<any, any>> | ((...args: any) => Atom.Atom<AsyncResult.AsyncResult<any, any>>);
+/**
+ * The arguments a source takes: a family's parameters, or none for an atom.
+ *
+ * @stability unstable
+ * @category utility types
+ * @since 0.1.0
+ */
+export type ArgsOf<S> = S extends ((...args: infer Args) => unknown) ? Args : [];
+/**
+ * The success type of a source's `AsyncResult`.
+ *
+ * @stability unstable
+ * @category utility types
+ * @since 0.1.0
+ */
+export type SuccessOf<S> = ResultOf<S> extends AsyncResult.AsyncResult<infer A, infer _E> ? A : never;
+/**
+ * The error type of a source's `AsyncResult`.
+ *
+ * @stability unstable
+ * @category utility types
+ * @since 0.1.0
+ */
+export type ErrorOf<S> = ResultOf<S> extends AsyncResult.AsyncResult<infer _A, infer E> ? E : never;
+type ResultOf<S> = S extends ((...args: ReadonlyArray<never>) => infer Built) ? Built extends Atom.Atom<infer Result> ? Result : never : S extends Atom.Atom<infer Result> ? Result : never;
+declare const SourceType: unique symbol;
+/**
+ * A handle's serialization key, branded with its source. The brand sits on
+ * a string, so types that map loader data to what survives serialization,
+ * such as React Router's, keep it as is.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export type HandleKey<S> = string & {
+  /** Type-only: ties the handle to its source. Never present at runtime. */
+  readonly [SourceType]?: S;
+};
+/**
+ * An atom a loader started: its source's arguments, and the atom's
+ * serialization key. Its type names its source, so `useAtomResult` reads it
+ * only through a source with the same arguments and success type.
+ *
+ * **Details**
+ *
+ * `Loader.prefetch` and `useWaterfall` return it, without waiting: the
+ * component that reads it suspends until the result settles.
+ *
+ * @see {@link LoadedHandle} for the handle `ensure` and `fetch` return
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export interface Handle<S> {
+  readonly args: ArgsOf<S>;
+  /** The atom's serialization key; `undefined` for an atom without one. */
+  readonly key: HandleKey<S> | undefined;
+}
+/**
+ * A handle from `Loader.ensure` or `Loader.fetch`: they waited for the
+ * result, so the component that reads it renders without suspending.
+ *
+ * **Details**
+ *
+ * A `LoadedHandle` fits a `Handle` prop, and a `Handle` doesn't fit a
+ * `LoadedHandle` prop. In the loader that ran the verb, `Loader.result`
+ * returns the result it waited for.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.1.0
+ */
+export interface LoadedHandle<S> extends Handle<S> {
+  readonly loaded: true;
+}
+export {};

package/dist/Hooks.d.mts

@@ -0,0 +1,89 @@
+import { ErrorOf, Handle, Source, SuccessOf } from "./Handle.mjs";
+import { SettledResult } from "./Loader.mjs";
+import * as Atom from "effect/reactivity/Atom";
+import * as AsyncResult from "effect/reactivity/AsyncResult";
+/**
+ * A source with the same arguments and success type as `S`, and any error:
+ * the sources whose handles `S` reads, such as the source an error
+ * boundary's `wrap(S)` wraps.
+ */
+type Readable<S> = S extends ((...args: infer Args) => Atom.Atom<AsyncResult.AsyncResult<infer A, infer _E>>) ? (...args: Args) => Atom.Atom<AsyncResult.AsyncResult<A, unknown>> : S extends Atom.Atom<AsyncResult.AsyncResult<infer A, infer _E>> ? Atom.Atom<AsyncResult.AsyncResult<A, unknown>> : never;
+/**
+ * Reads a handle through React Suspense, through the source that made it: a
+ * result streamed from the server, a hydrated one, or one a loader started.
+ *
+ * **When to use**
+ *
+ * Use in the component a loader, a server component or `useWaterfall` gave
+ * the handle to. The source can be the one the verb started, or one derived
+ * from it whose atoms point at its atoms with `initialValueTarget`, such as
+ * an error boundary's `wrap(source)`.
+ *
+ * **Details**
+ *
+ * - The atom is `source(...handle.args)`, or `source` itself for an atom.
+ *   In development, the read throws when the atom it hydrates has another
+ *   serialization key than the handle's: the handle came from another
+ *   source.
+ * - A handle from `ensure` or `fetch` renders without suspending, unless
+ *   the registry dropped the result since; one from `prefetch` or
+ *   `useWaterfall` suspends until the result settles. The registry is the
+ *   source of truth either way: the read follows refreshes and mutations.
+ * - A result the server was still loading when it dehydrated is awaited
+ *   instead of started, so the browser doesn't request it a second time.
+ * - The atom is read through `hydrated`, so a hydrated result is kept.
+ * - Once the component mounts, the loader's lease ends and the component
+ *   keeps the atom mounted.
+ * - A derived atom is read through the first serializable atom its
+ *   `initialValueTarget` chain points at: that one is awaited, hydrated and
+ *   released, so the derived atom doesn't request it again.
+ * - The settled result is returned, typed failures included. A defect is
+ *   thrown to the error boundaries above. With no typed failures left, such
+ *   as an atom whose boundaries claim all of them, it's typed as a success.
+ * - While a failed atom refreshes, such as after a boundary's `reset`, the
+ *   read suspends instead of returning the old failure again.
+ *
+ * **Gotchas**
+ *
+ * A read of an atom that nothing started, such as one whose loader result the
+ * registry dropped, starts it, and its request waits for the render: a
+ * request waterfall. In development, the read reports it as
+ * `WaterfallDetection` says, by default with a warning. Start the atom in a
+ * loader or a server component, with the state that picks it in the URL,
+ * and pass its handle down. For state that can't be in the URL, start it in
+ * the event handler that changes the state, or make its handle with
+ * `useWaterfall` when only the render knows its input.
+ *
+ * Two sources with the same arguments and success type take each other's
+ * handles as far as the types go; the development check catches it.
+ *
+ * During server rendering, the registry must be a request registry (see
+ * `RequestRegistry.make`), or a module-level registry would share results
+ * between requests: in development, the hook throws without one.
+ *
+ * `Atom.transform`'s `initialValueTarget` option points at the end of the
+ * target's own chain, which for an AtomRpc query with `reactivityKeys` is an
+ * inner atom with no serialization key. A derived atom read here sets
+ * `initialValueTarget` to its source itself, as an error boundary's
+ * wrapper does, or it requests the source again after hydration.
+ *
+ * **Example**
+ *
+ * ```tsx
+ * import { AsyncResult } from "effect/reactivity"
+ * import { type Handle, useAtomResult } from "raf-effect-atom"
+ *
+ * function IssueTitle(props: { readonly issue: Handle<typeof issue> }) {
+ *   const result = useAtomResult(issue, props.issue)
+ *   return AsyncResult.isSuccess(result) ? <h1>{result.value.title}</h1> : null
+ * }
+ * ```
+ *
+ * @see {@link hydrated} for reading hydrated atoms with Atom's own hooks
+ *
+ * @stability unstable
+ * @category hooks
+ * @since 0.1.0
+ */
+export declare const useAtomResult: <S extends Source>(source: S, handle: NoInfer<Handle<Readable<S>>>) => [ErrorOf<S>] extends [never] ? AsyncResult.Success<SuccessOf<S>, never> : SettledResult<SuccessOf<S>, ErrorOf<S>>;
+export {};

package/dist/Hooks.mjs

@@ -0,0 +1,135 @@
+"use client";
+import { stream } from "./internal/pending.mjs";
+import { hydrated } from "./Hydration.mjs";
+import { isDevelopment } from "./internal/development.mjs";
+import { keyOf, release } from "./internal/leases.mjs";
+import { atomOf } from "./internal/handles.mjs";
+import { isRequestRegistry } from "./RequestRegistry.mjs";
+import { isServer } from "./internal/registry.mjs";
+import { ModeContext, check } from "./internal/waterfalls.mjs";
+import * as Atom from "effect/reactivity/Atom";
+import * as Predicate from "effect/Predicate";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as AsyncResult from "effect/reactivity/AsyncResult";
+import { RegistryContext, useAtomSuspense } from "@effect/atom-react";
+import * as React from "react";
+// src/Hooks.ts
+/**
+* The read hook for atoms started by loaders and streamed from the server.
+*
+* @stability unstable
+* @since 0.1.0
+*/
+/**
+* The atom the loader started and the server sent: the first serializable
+* atom in `atom`'s `initialValueTarget` chain, starting with `atom`. An
+* AtomRpc query is serializable itself, though it points at an inner atom.
+*/
+const sourceOf = (atom) => {
+	for (let target = atom; target !== void 0; target = target.initialValueTarget) if (Atom.isSerializable(target)) return target;
+	return atom;
+};
+/**
+* Reads a handle through React Suspense, through the source that made it: a
+* result streamed from the server, a hydrated one, or one a loader started.
+*
+* **When to use**
+*
+* Use in the component a loader, a server component or `useWaterfall` gave
+* the handle to. The source can be the one the verb started, or one derived
+* from it whose atoms point at its atoms with `initialValueTarget`, such as
+* an error boundary's `wrap(source)`.
+*
+* **Details**
+*
+* - The atom is `source(...handle.args)`, or `source` itself for an atom.
+*   In development, the read throws when the atom it hydrates has another
+*   serialization key than the handle's: the handle came from another
+*   source.
+* - A handle from `ensure` or `fetch` renders without suspending, unless
+*   the registry dropped the result since; one from `prefetch` or
+*   `useWaterfall` suspends until the result settles. The registry is the
+*   source of truth either way: the read follows refreshes and mutations.
+* - A result the server was still loading when it dehydrated is awaited
+*   instead of started, so the browser doesn't request it a second time.
+* - The atom is read through `hydrated`, so a hydrated result is kept.
+* - Once the component mounts, the loader's lease ends and the component
+*   keeps the atom mounted.
+* - A derived atom is read through the first serializable atom its
+*   `initialValueTarget` chain points at: that one is awaited, hydrated and
+*   released, so the derived atom doesn't request it again.
+* - The settled result is returned, typed failures included. A defect is
+*   thrown to the error boundaries above. With no typed failures left, such
+*   as an atom whose boundaries claim all of them, it's typed as a success.
+* - While a failed atom refreshes, such as after a boundary's `reset`, the
+*   read suspends instead of returning the old failure again.
+*
+* **Gotchas**
+*
+* A read of an atom that nothing started, such as one whose loader result the
+* registry dropped, starts it, and its request waits for the render: a
+* request waterfall. In development, the read reports it as
+* `WaterfallDetection` says, by default with a warning. Start the atom in a
+* loader or a server component, with the state that picks it in the URL,
+* and pass its handle down. For state that can't be in the URL, start it in
+* the event handler that changes the state, or make its handle with
+* `useWaterfall` when only the render knows its input.
+*
+* Two sources with the same arguments and success type take each other's
+* handles as far as the types go; the development check catches it.
+*
+* During server rendering, the registry must be a request registry (see
+* `RequestRegistry.make`), or a module-level registry would share results
+* between requests: in development, the hook throws without one.
+*
+* `Atom.transform`'s `initialValueTarget` option points at the end of the
+* target's own chain, which for an AtomRpc query with `reactivityKeys` is an
+* inner atom with no serialization key. A derived atom read here sets
+* `initialValueTarget` to its source itself, as an error boundary's
+* wrapper does, or it requests the source again after hydration.
+*
+* **Example**
+*
+* ```tsx
+* import { AsyncResult } from "effect/reactivity"
+* import { type Handle, useAtomResult } from "raf-effect-atom"
+*
+* function IssueTitle(props: { readonly issue: Handle<typeof issue> }) {
+*   const result = useAtomResult(issue, props.issue)
+*   return AsyncResult.isSuccess(result) ? <h1>{result.value.title}</h1> : null
+* }
+* ```
+*
+* @see {@link hydrated} for reading hydrated atoms with Atom's own hooks
+*
+* @stability unstable
+* @category hooks
+* @since 0.1.0
+*/
+const useAtomResult = (source, handle) => {
+	const registry = React.useContext(RegistryContext);
+	const atom = atomOf(source, handle.args);
+	if (isServer() && !isRequestRegistry(registry) && Effect.runSync(isDevelopment)) throw new Error("raf-effect-atom: useAtomResult rendered on the server without a request registry, so results would be shared between requests. Provide RequestRegistry.make() through RegistryContext, as the framework integrations do.");
+	const target = sourceOf(atom);
+	const started = hydrated(target);
+	const read = target === atom ? hydrated(atom) : atom;
+	const key = keyOf(started);
+	if (process.env.NODE_ENV !== "production" && handle.key !== void 0 && Predicate.isString(key) && handle.key !== key) throw new Error(`raf-effect-atom: useAtomResult read the handle of ${handle.key} through a source that makes ${key}. Read a handle through the source that made it.`);
+	const streamed = Predicate.isString(key) ? stream(registry, key) : void 0;
+	if (streamed !== void 0) React.use(streamed);
+	if (process.env.NODE_ENV !== "production") check(registry, started, React.use(ModeContext));
+	if (read !== started) registry.get(started);
+	const current = registry.get(read);
+	const result = useAtomSuspense(read, {
+		includeFailure: true,
+		suspendOnWaiting: AsyncResult.isFailure(current) && current.waiting
+	});
+	React.useEffect(() => {
+		release(registry, started);
+	}, [registry, started]);
+	if (AsyncResult.isFailure(result) && Option.isNone(Cause.findErrorOption(result.cause))) throw Cause.squash(result.cause);
+	return result;
+};
+export { useAtomResult };

package/dist/Hydration.d.mts

@@ -0,0 +1,93 @@
+import * as Atom from "effect/reactivity/Atom";
+import * as EffectHydration from "effect/reactivity/Hydration";
+import * as AtomRegistry from "effect/reactivity/AtomRegistry";
+declare namespace Hydration_d_exports {
+  export { dehydrate, hydrate, hydrated };
+}
+/**
+ * Returns a serializable atom that keeps its hydrated value on its first
+ * read, instead of running its effect again.
+ *
+ * **When to use**
+ *
+ * The loader verbs and `useAtomResult` already read through it. Use it when
+ * reading a hydrated atom with `@effect/atom-react`'s own hooks.
+ *
+ * **Details**
+ *
+ * The copy shares the atom's serialization key, so both read the same
+ * registry node. It sets `skipInitialRun` on the atom's `Serializable`
+ * metadata, and is memoized per atom, so every call returns the same copy.
+ * An atom that isn't serializable, or already skips its initial run, is
+ * returned as it is.
+ *
+ * **Gotchas**
+ *
+ * The copy keeps the hydrated value only for the first read: a refresh, or a
+ * change to a dependency, runs the effect as usual. An `Initial` value never
+ * skips the effect, which is why a result the server was still loading
+ * crosses as a promise that `useAtomResult` waits for.
+ *
+ * **Example**
+ *
+ * ```ts
+ * import { useAtomValue } from "@effect/atom-react"
+ * import { Hydration } from "raf-effect-atom"
+ *
+ * const result = useAtomValue(Hydration.hydrated(issue(1)))
+ * ```
+ *
+ * @see {@link Atom.serializable} for the metadata it copies
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 0.1.0
+ */
+export declare const hydrated: <Self extends Atom.Atom<unknown>>(atom: Self) => Self;
+/**
+ * Encodes a request registry's serializable atoms for the browser.
+ *
+ * **Details**
+ *
+ * `Hydration.dehydrate` with `encodeInitialAs: "promise"`: a settled result
+ * crosses as its encoded value, and a result still loading crosses as a
+ * promise of its encoded value, which resolves when it settles. The
+ * framework's serializer carries the promises (TanStack Router's dehydrated
+ * state, React's server component props, React Router's Single Fetch).
+ *
+ * **Gotchas**
+ *
+ * Only atoms in the registry when it's called are included, so call it once
+ * the loaders have started theirs.
+ *
+ * @see {@link hydrate} for the browser side
+ *
+ * @stability unstable
+ * @category dehydration
+ * @since 0.1.0
+ */
+export declare const dehydrate: (registry: AtomRegistry.AtomRegistry) => Array<EffectHydration.DehydratedAtom>;
+/**
+ * Applies dehydrated state to the browser's registry.
+ *
+ * **When to use**
+ *
+ * Use outside React, such as in a router's `hydrate` hook, before the app
+ * renders. Inside React, use `HydrationBoundary`.
+ *
+ * **Details**
+ *
+ * Settled values go through `Hydration.hydrate`. A streamed result is held
+ * until its promise resolves, then hydrated; until then `useAtomResult`
+ * suspends on it instead of starting the atom, which would request it again.
+ * A streamed result that can't be decoded, or whose promise rejects, is
+ * dropped, and the atom runs in the browser.
+ *
+ * @see {@link dehydrate} for the server side
+ *
+ * @stability unstable
+ * @category hydration
+ * @since 0.1.0
+ */
+export declare const hydrate: (registry: AtomRegistry.AtomRegistry, state: Iterable<EffectHydration.DehydratedAtom>) => void;
+export { Hydration_d_exports };