raf-effect-atom 0.0.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,122 @@
+# Changelog
+
+## [0.2.0](https://github.com/KATT/raf-effect-atom/compare/raf-effect-atom%400.1.0...raf-effect-atom%400.2.0) (2026-10-23)
+
+### ⚠ BREAKING CHANGES
+
+* **raf-effect-atom:** `dehydrate()` from `raf-effect-atom/next` returns a
+
+### Features
+
+* **raf-effect-atom:** seed each request registry, async seeds included ([62b6180](https://github.com/KATT/raf-effect-atom/commit/62b618098df87e711ddb4c1d633e191ba3353438))
+
+## 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/README.md

@@ -17,27 +17,33 @@ npm install raf-effect-atom effect @effect/atom-react react
 
 ## Usage
 
-A loader starts atoms with a verb per call. `prefetch` starts one and streams it, `ensure` waits for its first result, and `fetch` waits for a fresh one. Typed failures come back as results, so a loader can redirect on a tag:
+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);
-	args.context.atoms.prefetch(comments(id));
-	const result = await args.context.atoms.ensure(issue(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 reads the atom with `useAtomResult`, which waits for a streamed result instead of starting the atom again, and returns typed failures. It also reads an atom derived from one, such as the atom 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:
+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 { useAtomResult } from "raf-effect-atom";
+import { type Handle, useAtomResult } from "raf-effect-atom";
 
-function IssueTitle(props: { readonly id: number }) {
-	const result = useAtomResult(useIssueBoundary().wrap(issue(props.id)));
+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>;
 }
@@ -46,14 +52,14 @@ function IssueTitle(props: { readonly id: number }) {
 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, and `<HydrateAtoms state={dehydrate()}>` around the client components that read them.
-- `raf-effect-atom/react-router`, for Framework Mode: `atomsMiddleware(atomsContext)` as the root middleware, loaders that return `atoms.dehydrate()`, and `HydrationBoundary` in the route component.
+- `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={await dehydrate()}>` around them. `makeRequestAtoms({ seed })` makes the same functions over a registry seeded from the request, such as with its cookie.
+- `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(atom)` starts an atom whose input exists only in render, and marks it as a known waterfall.
+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. Read atoms 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).
+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
 

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

@@ -1,18 +1,34 @@
+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";
 /**
- * Reads an `AsyncResult` atom through React Suspense: a result streamed from
- * the server, a hydrated one, or one a loader started.
+ * 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 for every atom a loader starts or the server renders, or for an atom
- * derived from one with `initialValueTarget` pointing at it, such as an error
- * boundary's wrapper.
+ * 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.
@@ -29,13 +45,17 @@ import * as AsyncResult from "effect/reactivity/AsyncResult";
  *
  * **Gotchas**
  *
- * A read of an atom that nothing started 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.
- * For state that can't be in the URL, start it in the event handler that
- * changes the state, or read it through `useWaterfall` when only the render
- * knows its input.
+ * 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
@@ -51,10 +71,10 @@ import * as AsyncResult from "effect/reactivity/AsyncResult";
  *
  * ```tsx
  * import { AsyncResult } from "effect/reactivity"
- * import { useAtomResult } from "raf-effect-atom"
+ * import { type Handle, useAtomResult } from "raf-effect-atom"
  *
- * function IssueTitle(props: { readonly id: number }) {
- *   const result = useAtomResult(issue(props.id))
+ * function IssueTitle(props: { readonly issue: Handle<typeof issue> }) {
+ *   const result = useAtomResult(issue, props.issue)
  *   return AsyncResult.isSuccess(result) ? <h1>{result.value.title}</h1> : null
  * }
  * ```
@@ -65,4 +85,5 @@ import * as AsyncResult from "effect/reactivity/AsyncResult";
  * @category hooks
  * @since 0.1.0
  */
-export declare const useAtomResult: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => [E] extends [never] ? AsyncResult.Success<A, never> : SettledResult<A, E>;
+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

@@ -3,6 +3,7 @@ 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";
@@ -31,17 +32,26 @@ const sourceOf = (atom) => {
 	return atom;
 };
 /**
-* Reads an `AsyncResult` atom through React Suspense: a result streamed from
-* the server, a hydrated one, or one a loader started.
+* 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 for every atom a loader starts or the server renders, or for an atom
-* derived from one with `initialValueTarget` pointing at it, such as an error
-* boundary's wrapper.
+* 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.
@@ -58,13 +68,17 @@ const sourceOf = (atom) => {
 *
 * **Gotchas**
 *
-* A read of an atom that nothing started 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.
-* For state that can't be in the URL, start it in the event handler that
-* changes the state, or read it through `useWaterfall` when only the render
-* knows its input.
+* 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
@@ -80,10 +94,10 @@ const sourceOf = (atom) => {
 *
 * ```tsx
 * import { AsyncResult } from "effect/reactivity"
-* import { useAtomResult } from "raf-effect-atom"
+* import { type Handle, useAtomResult } from "raf-effect-atom"
 *
-* function IssueTitle(props: { readonly id: number }) {
-*   const result = useAtomResult(issue(props.id))
+* function IssueTitle(props: { readonly issue: Handle<typeof issue> }) {
+*   const result = useAtomResult(issue, props.issue)
 *   return AsyncResult.isSuccess(result) ? <h1>{result.value.title}</h1> : null
 * }
 * ```
@@ -94,25 +108,27 @@ const sourceOf = (atom) => {
 * @category hooks
 * @since 0.1.0
 */
-const useAtomResult = (atom) => {
+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 source = hydrated(target);
+	const started = hydrated(target);
 	const read = target === atom ? hydrated(atom) : atom;
-	const key = keyOf(source);
+	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, source, React.use(ModeContext));
-	if (read !== source) registry.get(source);
+	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, source);
-	}, [registry, source]);
+		release(registry, started);
+	}, [registry, started]);
 	if (AsyncResult.isFailure(result) && Option.isNone(Cause.findErrorOption(result.cause))) throw Cause.squash(result.cause);
 	return result;
 };