raf-effect-atom 0.0.0 → 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/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={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(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;
 };

package/dist/Loader.d.mts

@@ -1,11 +1,11 @@
-import * as Atom from "effect/reactivity/Atom";
+import { ArgsOf, ErrorOf, Handle, LoadedHandle, Source, SuccessOf } from "./Handle.mjs";
 import * as Context from "effect/Context";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import * as AsyncResult from "effect/reactivity/AsyncResult";
 import * as AtomRegistry from "effect/reactivity/AtomRegistry";
 declare namespace Loader_d_exports {
-  export { LeaseTTL, Loader, SettledResult, ensure, fetch, make, prefetch };
+  export { LeaseTTL, Loader, SettledResult, ensure, fetch, make, prefetch, result };
 }
 /**
  * A settled `AsyncResult`: what `ensure` and `fetch` return.
@@ -31,7 +31,7 @@ export type SettledResult<A, E> = AsyncResult.Failure<A, E> | AsyncResult.Succes
  */
 export declare const LeaseTTL: Context.Reference<Duration.Duration>;
 /**
- * Starts an atom without waiting for it.
+ * Starts a source's atom without waiting for it, and returns its handle.
  *
  * **When to use**
  *
@@ -41,7 +41,8 @@ export declare const LeaseTTL: Context.Reference<Duration.Duration>;
  * **Details**
  *
  * Starts the atom if it isn't in the registry, and leaves it alone if it is.
- * Takes a lease either way.
+ * Takes a lease either way. The component that reads the handle suspends
+ * until the result settles.
  *
  * **Example**
  *
@@ -49,17 +50,17 @@ export declare const LeaseTTL: Context.Reference<Duration.Duration>;
  * import { Effect } from "effect"
  * import { Loader } from "raf-effect-atom"
  *
- * const program = Loader.prefetch(comments(1))
+ * const program = Loader.prefetch(commentPage, issueId, 0)
  * ```
  *
  * @stability unstable
  * @category verbs
  * @since 0.1.0
  */
-export declare const prefetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => Effect.Effect<void, never, AtomRegistry.AtomRegistry>;
+export declare const prefetch: <S extends Source>(source: S, ...args: ArgsOf<S>) => Effect.Effect<Handle<S>, never, AtomRegistry.AtomRegistry>;
 /**
- * Starts an atom and returns its settled result, waiting only while it has
- * none.
+ * Starts a source's atom, waits only while it has no result, and returns a
+ * handle whose reader renders without suspending.
  *
  * **When to use**
  *
@@ -68,10 +69,11 @@ export declare const prefetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A,
  *
  * **Details**
  *
- * An atom with a result returns it at once, without refetching. On a request
+ * An atom with a result returns at once, without refetching. On a request
  * registry, it also waits out a refresh in flight, so the server never
- * renders a result that's about to change. A typed failure is returned as
- * the result; a defect or an interruption fails the Effect.
+ * renders a result that's about to change. A typed failure settles it like
+ * a success: `result` returns it. A defect or an interruption fails the
+ * Effect.
  *
  * **Example**
  *
@@ -81,7 +83,8 @@ export declare const prefetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A,
  * import { Loader } from "raf-effect-atom"
  *
  * const program = Effect.gen(function* () {
- *   const result = yield* Loader.ensure(issue(1))
+ *   const handle = yield* Loader.ensure(issue, 1)
+ *   const result = Loader.result(handle)
  *   return AsyncResult.isSuccess(result) ? result.value.title : "missing"
  * })
  * ```
@@ -90,10 +93,11 @@ export declare const prefetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A,
  * @category verbs
  * @since 0.1.0
  */
-export declare const ensure: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => Effect.Effect<SettledResult<A, E>, never, AtomRegistry.AtomRegistry>;
+export declare const ensure: <S extends Source>(source: S, ...args: ArgsOf<S>) => Effect.Effect<LoadedHandle<S>, never, AtomRegistry.AtomRegistry>;
 /**
- * Starts an atom, or refreshes it if it has a result, and returns the new
- * settled result.
+ * Starts a source's atom, or refreshes it if it has a result, waits for the
+ * new result to settle, and returns a handle whose reader renders without
+ * suspending.
  *
  * **When to use**
  *
@@ -102,14 +106,45 @@ export declare const ensure: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E
  *
  * **Details**
  *
- * Waits until the result settles and isn't refreshing. A typed failure is
- * returned as the result; a defect or an interruption fails the Effect.
+ * Waits until the result settles and isn't refreshing. A typed failure
+ * settles it like a success: `result` returns it. A defect or an
+ * interruption fails the Effect.
  *
  * @stability unstable
  * @category verbs
  * @since 0.1.0
  */
-export declare const fetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => Effect.Effect<SettledResult<A, E>, never, AtomRegistry.AtomRegistry>;
+export declare const fetch: <S extends Source>(source: S, ...args: ArgsOf<S>) => Effect.Effect<LoadedHandle<S>, never, AtomRegistry.AtomRegistry>;
+/**
+ * Returns the settled result `ensure` or `fetch` waited for.
+ *
+ * **When to use**
+ *
+ * Use in the loader that ran the verb, to branch on the result: redirect on
+ * a tag, or build another atom's arguments from it. Components read the
+ * handle with `useAtomResult`, which follows the registry.
+ *
+ * **Gotchas**
+ *
+ * Only the handle object the verb returned has it: a handle that crossed
+ * the network, as loader data or a server component's prop, is a copy, and
+ * this throws for it.
+ *
+ * **Example**
+ *
+ * ```ts
+ * import { AsyncResult } from "effect/reactivity"
+ * import { Loader } from "raf-effect-atom"
+ *
+ * const handle = await atoms.ensure(issue, id)
+ * const error = AsyncResult.error(Loader.result(handle))
+ * ```
+ *
+ * @stability unstable
+ * @category getters
+ * @since 0.1.0
+ */
+export declare const result: <S extends Source>(handle: LoadedHandle<S>) => SettledResult<SuccessOf<S>, ErrorOf<S>>;
 /**
  * The loader verbs as Promises over one registry, as the framework
  * integrations put them on the router context.
@@ -120,11 +155,11 @@ export declare const fetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>
  */
 export interface Loader {
   /** {@link ensure}, as a Promise that rejects only on a defect. */
-  readonly ensure: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => Promise<SettledResult<A, E>>;
+  readonly ensure: <S extends Source>(source: S, ...args: ArgsOf<S>) => Promise<LoadedHandle<S>>;
   /** {@link fetch}, as a Promise that rejects only on a defect. */
-  readonly fetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => Promise<SettledResult<A, E>>;
+  readonly fetch: <S extends Source>(source: S, ...args: ArgsOf<S>) => Promise<LoadedHandle<S>>;
   /** {@link prefetch}, run at once. */
-  readonly prefetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => void;
+  readonly prefetch: <S extends Source>(source: S, ...args: ArgsOf<S>) => Handle<S>;
 }
 /**
  * Creates the Promise verbs over one registry.
@@ -143,8 +178,8 @@ export interface Loader {
  * import { Loader, RequestRegistry } from "raf-effect-atom"
  *
  * const loader = Loader.make(RequestRegistry.make())
- * loader.prefetch(comments(1))
- * const result = await loader.ensure(issue(1))
+ * const comments = loader.prefetch(commentPage, 1, 0)
+ * const issueHandle = await loader.ensure(issue, 1)
  * ```
  *
  * @stability unstable

package/dist/Loader.mjs

@@ -2,6 +2,7 @@ import { __exportAll } from "./_virtual/_rolldown/runtime.mjs";
 import { hydrated } from "./Hydration.mjs";
 import { isDevelopment } from "./internal/development.mjs";
 import { keyOf, take } from "./internal/leases.mjs";
+import { atomOf, loaded as loaded$1, make as make$1 } from "./internal/handles.mjs";
 import { isRequestRegistry } from "./RequestRegistry.mjs";
 import * as Atom from "effect/reactivity/Atom";
 import * as Predicate from "effect/Predicate";
@@ -17,9 +18,11 @@ import * as AtomRegistry from "effect/reactivity/AtomRegistry";
 * Starts atoms from route loaders, before anything renders, so nothing
 * waterfalls.
 *
-* Each verb starts an `AsyncResult` atom in the registry and takes a lease
-* on it, so the registry's idle TTL can't evict it before the route renders
-* and `useAtomResult` takes it over:
+* Each verb takes a source, an atom family or an `AsyncResult` atom, with its
+* arguments. It starts the atom in the registry, takes a lease on it, so the
+* registry's idle TTL can't evict it before the route renders and
+* `useAtomResult` takes it over, and returns its handle for the component
+* that reads it:
 *
 * | Verb       | Starts the atom                 | Waits                         | Has a value already   |
 * | ---------- | ------------------------------- | ----------------------------- | --------------------- |
@@ -27,9 +30,10 @@ import * as AtomRegistry from "effect/reactivity/AtomRegistry";
 * | `ensure`   | if it isn't in the registry     | only while it's `Initial`     | returns it at once    |
 * | `fetch`    | if it isn't, or refreshes it    | until the new result settles  | refreshes, then waits |
 *
-* Typed failures don't reject: `ensure` and `fetch` return the settled
-* `AsyncResult`, so a loader can redirect on a tag and otherwise let a
-* boundary render the failure. Only defects and interruptions reject.
+* Typed failures don't reject: `ensure` and `fetch` settle on them, and
+* `result` returns the settled `AsyncResult`, so a loader can redirect on a
+* tag and otherwise let a boundary render the failure. Only defects and
+* interruptions reject.
 *
 * The verbs are Effects that need the `AtomRegistry`; `make` gives the same
 * verbs as Promises over one registry, for loaders that are async functions.
@@ -42,7 +46,8 @@ var Loader_exports = /* @__PURE__ */ __exportAll({
 	ensure: () => ensure,
 	fetch: () => fetch,
 	make: () => make,
-	prefetch: () => prefetch
+	prefetch: () => prefetch,
+	result: () => result
 });
 /**
 * How long a loader's lease keeps an atom mounted when no component takes it
@@ -98,7 +103,7 @@ const rejectDefects = (result) => {
 	return Effect.succeed(result);
 };
 /**
-* Starts an atom without waiting for it.
+* Starts a source's atom without waiting for it, and returns its handle.
 *
 * **When to use**
 *
@@ -108,7 +113,8 @@ const rejectDefects = (result) => {
 * **Details**
 *
 * Starts the atom if it isn't in the registry, and leaves it alone if it is.
-* Takes a lease either way.
+* Takes a lease either way. The component that reads the handle suspends
+* until the result settles.
 *
 * **Example**
 *
@@ -116,19 +122,26 @@ const rejectDefects = (result) => {
 * import { Effect } from "effect"
 * import { Loader } from "raf-effect-atom"
 *
-* const program = Loader.prefetch(comments(1))
+* const program = Loader.prefetch(commentPage, issueId, 0)
 * ```
 *
 * @stability unstable
 * @category verbs
 * @since 0.1.0
 */
-const prefetch = Effect.fnUntraced(function* (atom) {
+const prefetch = (source, ...args) => Effect.gen(function* () {
+	const atom = atomOf(source, args);
 	yield* start(atom);
+	return make$1(args, atom);
 });
+const loaded = (args, atom, result) => {
+	const handle = loaded$1(args, atom);
+	results.set(handle, result);
+	return handle;
+};
 /**
-* Starts an atom and returns its settled result, waiting only while it has
-* none.
+* Starts a source's atom, waits only while it has no result, and returns a
+* handle whose reader renders without suspending.
 *
 * **When to use**
 *
@@ -137,10 +150,11 @@ const prefetch = Effect.fnUntraced(function* (atom) {
 *
 * **Details**
 *
-* An atom with a result returns it at once, without refetching. On a request
+* An atom with a result returns at once, without refetching. On a request
 * registry, it also waits out a refresh in flight, so the server never
-* renders a result that's about to change. A typed failure is returned as
-* the result; a defect or an interruption fails the Effect.
+* renders a result that's about to change. A typed failure settles it like
+* a success: `result` returns it. A defect or an interruption fails the
+* Effect.
 *
 * **Example**
 *
@@ -150,7 +164,8 @@ const prefetch = Effect.fnUntraced(function* (atom) {
 * import { Loader } from "raf-effect-atom"
 *
 * const program = Effect.gen(function* () {
-*   const result = yield* Loader.ensure(issue(1))
+*   const handle = yield* Loader.ensure(issue, 1)
+*   const result = Loader.result(handle)
 *   return AsyncResult.isSuccess(result) ? result.value.title : "missing"
 * })
 * ```
@@ -159,13 +174,16 @@ const prefetch = Effect.fnUntraced(function* (atom) {
 * @category verbs
 * @since 0.1.0
 */
-const ensure = Effect.fnUntraced(function* (atom) {
+const ensure = (source, ...args) => Effect.gen(function* () {
+	const atom = atomOf(source, args);
 	const started = yield* start(atom);
-	return yield* settled(started.registry, started.target, started.request ? isSettled : AsyncResult.isNotInitial);
+	const result = yield* settled(started.registry, started.target, started.request ? isSettled : AsyncResult.isNotInitial);
+	return loaded(args, atom, result);
 });
 /**
-* Starts an atom, or refreshes it if it has a result, and returns the new
-* settled result.
+* Starts a source's atom, or refreshes it if it has a result, waits for the
+* new result to settle, and returns a handle whose reader renders without
+* suspending.
 *
 * **When to use**
 *
@@ -174,22 +192,60 @@ const ensure = Effect.fnUntraced(function* (atom) {
 *
 * **Details**
 *
-* Waits until the result settles and isn't refreshing. A typed failure is
-* returned as the result; a defect or an interruption fails the Effect.
+* Waits until the result settles and isn't refreshing. A typed failure
+* settles it like a success: `result` returns it. A defect or an
+* interruption fails the Effect.
 *
 * @stability unstable
 * @category verbs
 * @since 0.1.0
 */
-const fetch = Effect.fnUntraced(function* (atom) {
+const fetch = (source, ...args) => Effect.gen(function* () {
+	const atom = atomOf(source, args);
 	const started = yield* start(atom);
 	const { registry, target } = started;
 	if (started.existed && isSettled(registry.get(target))) {
 		const node = registry.getNodes().get(keyOf(target));
 		registry.refresh(node?.atom ?? target);
 	}
-	return yield* settled(registry, target, isSettled);
+	const result = yield* settled(registry, target, isSettled);
+	return loaded(args, atom, result);
 });
+const results = /* @__PURE__ */ new WeakMap();
+/**
+* Returns the settled result `ensure` or `fetch` waited for.
+*
+* **When to use**
+*
+* Use in the loader that ran the verb, to branch on the result: redirect on
+* a tag, or build another atom's arguments from it. Components read the
+* handle with `useAtomResult`, which follows the registry.
+*
+* **Gotchas**
+*
+* Only the handle object the verb returned has it: a handle that crossed
+* the network, as loader data or a server component's prop, is a copy, and
+* this throws for it.
+*
+* **Example**
+*
+* ```ts
+* import { AsyncResult } from "effect/reactivity"
+* import { Loader } from "raf-effect-atom"
+*
+* const handle = await atoms.ensure(issue, id)
+* const error = AsyncResult.error(Loader.result(handle))
+* ```
+*
+* @stability unstable
+* @category getters
+* @since 0.1.0
+*/
+const result = (handle) => {
+	const settledResult = results.get(handle);
+	if (settledResult === void 0) throw new Error("raf-effect-atom: Loader.result got a handle that no ensure or fetch returned here. Only the code that ran the verb has its result: a handle that crossed the network is a copy. Read it with useAtomResult instead.");
+	return settledResult;
+};
 /**
 * Creates the Promise verbs over one registry.
 *
@@ -207,8 +263,8 @@ const fetch = Effect.fnUntraced(function* (atom) {
 * import { Loader, RequestRegistry } from "raf-effect-atom"
 *
 * const loader = Loader.make(RequestRegistry.make())
-* loader.prefetch(comments(1))
-* const result = await loader.ensure(issue(1))
+* const comments = loader.prefetch(commentPage, 1, 0)
+* const issueHandle = await loader.ensure(issue, 1)
 * ```
 *
 * @stability unstable
@@ -222,11 +278,9 @@ const make = (registry, options) => {
 		return leaseTTL === void 0 ? provided : Effect.provideService(provided, LeaseTTL, leaseTTL);
 	};
 	return {
-		ensure: (atom) => Effect.runPromise(provide(ensure(atom))),
-		fetch: (atom) => Effect.runPromise(provide(fetch(atom))),
-		prefetch: (atom) => {
-			Effect.runSync(provide(prefetch(atom)));
-		}
+		ensure: (source, ...args) => Effect.runPromise(provide(ensure(source, ...args))),
+		fetch: (source, ...args) => Effect.runPromise(provide(fetch(source, ...args))),
+		prefetch: (source, ...args) => Effect.runSync(provide(prefetch(source, ...args)))
 	};
 };
-export { LeaseTTL, Loader_exports, ensure, fetch, make, prefetch };
+export { LeaseTTL, Loader_exports, ensure, fetch, make, prefetch, result };

package/dist/Next.d.mts

@@ -1,9 +1,7 @@
-import { SettledResult } from "./Loader.mjs";
+import { ArgsOf, Handle, LoadedHandle, Source } from "./Handle.mjs";
 import { HydrateAtoms } from "./NextClient.mjs";
 import { RegistryProvider } from "./RegistryProvider.mjs";
-import * as Atom from "effect/reactivity/Atom";
 import * as EffectHydration from "effect/reactivity/Hydration";
-import * as AsyncResult from "effect/reactivity/AsyncResult";
 import * as AtomRegistry from "effect/reactivity/AtomRegistry";
 /**
  * Returns the request registry of the server render in progress.
@@ -25,31 +23,32 @@ import * as AtomRegistry from "effect/reactivity/AtomRegistry";
  */
 export declare const getRegistry: () => AtomRegistry.AtomRegistry;
 /**
- * `Loader.prefetch` on the request's registry: starts an atom, to stream it.
+ * `Loader.prefetch` on the request's registry: starts a source's atom, to
+ * stream it, and returns its handle.
  *
  * @stability unstable
  * @category verbs
  * @since 0.1.0
  */
-export declare const prefetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => void;
+export declare const prefetch: <S extends Source>(source: S, ...args: ArgsOf<S>) => Handle<S>;
 /**
- * `Loader.ensure` on the request's registry: starts an atom and returns its
- * settled result.
+ * `Loader.ensure` on the request's registry: starts a source's atom, waits
+ * for its result, and returns its handle.
  *
  * @stability unstable
  * @category verbs
  * @since 0.1.0
  */
-export declare const ensure: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => Promise<SettledResult<A, E>>;
+export declare const ensure: <S extends Source>(source: S, ...args: ArgsOf<S>) => Promise<LoadedHandle<S>>;
 /**
- * `Loader.fetch` on the request's registry: starts or refreshes an atom and
- * returns the new settled result.
+ * `Loader.fetch` on the request's registry: starts or refreshes a source's
+ * atom, waits for the new result, and returns its handle.
  *
  * @stability unstable
  * @category verbs
  * @since 0.1.0
  */
-export declare const fetch: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => Promise<SettledResult<A, E>>;
+export declare const fetch: <S extends Source>(source: S, ...args: ArgsOf<S>) => Promise<LoadedHandle<S>>;
 /**
  * `Hydration.dehydrate` on the request's registry, for `HydrateAtoms`.
  *

package/dist/Next.mjs

@@ -22,7 +22,8 @@ import { RegistryProvider } from "./RegistryProvider.mjs";
 */
 const getRegistry = getRegistry$1;
 /**
-* `Loader.prefetch` on the request's registry: starts an atom, to stream it.
+* `Loader.prefetch` on the request's registry: starts a source's atom, to
+* stream it, and returns its handle.
 *
 * @stability unstable
 * @category verbs
@@ -30,8 +31,8 @@ const getRegistry = getRegistry$1;
 */
 const prefetch = prefetch$1;
 /**
-* `Loader.ensure` on the request's registry: starts an atom and returns its
-* settled result.
+* `Loader.ensure` on the request's registry: starts a source's atom, waits
+* for its result, and returns its handle.
 *
 * @stability unstable
 * @category verbs
@@ -39,8 +40,8 @@ const prefetch = prefetch$1;
 */
 const ensure = ensure$1;
 /**
-* `Loader.fetch` on the request's registry: starts or refreshes an atom and
-* returns the new settled result.
+* `Loader.fetch` on the request's registry: starts or refreshes a source's
+* atom, waits for the new result, and returns its handle.
 *
 * @stability unstable
 * @category verbs

package/dist/NextClient.d.mts

@@ -16,11 +16,10 @@ import * as React from "react";
  * import { dehydrate, ensure, HydrateAtoms } from "raf-effect-atom/next"
  *
  * export default async function IssuePage(props: { params: Promise<{ id: string }> }) {
- *   const id = Number((await props.params).id)
- *   await ensure(issue(id))
+ *   const handle = await ensure(issue, Number((await props.params).id))
  *   return (
  *     <HydrateAtoms state={dehydrate()}>
- *       <Issue id={id} />
+ *       <Issue issue={handle} />
  *     </HydrateAtoms>
  *   )
  * }

package/dist/NextClient.mjs

@@ -24,11 +24,10 @@ import { jsx } from "react/jsx-runtime";
 * import { dehydrate, ensure, HydrateAtoms } from "raf-effect-atom/next"
 *
 * export default async function IssuePage(props: { params: Promise<{ id: string }> }) {
-*   const id = Number((await props.params).id)
-*   await ensure(issue(id))
+*   const handle = await ensure(issue, Number((await props.params).id))
 *   return (
 *     <HydrateAtoms state={dehydrate()}>
-*       <Issue id={id} />
+*       <Issue issue={handle} />
 *     </HydrateAtoms>
 *   )
 * }

package/dist/ReactHydration.d.mts

@@ -41,7 +41,7 @@ export interface HydrationBoundaryProps {
  * import { HydrationBoundary } from "raf-effect-atom"
  *
  * <HydrationBoundary state={loaderData.atoms}>
- *   <IssuePage id={id} />
+ *   <IssuePage issue={loaderData.issue} />
  * </HydrationBoundary>
  * ```
  *

package/dist/ReactHydration.mjs

@@ -42,7 +42,7 @@ import { jsx } from "react/jsx-runtime";
 * import { HydrationBoundary } from "raf-effect-atom"
 *
 * <HydrationBoundary state={loaderData.atoms}>
-*   <IssuePage id={id} />
+*   <IssuePage issue={loaderData.issue} />
 * </HydrationBoundary>
 * ```
 *

package/dist/ReactRouter.d.mts

@@ -1,5 +1,5 @@
-import { Loader } from "./Loader.mjs";
 import { RegistryProvider } from "./RegistryProvider.mjs";
+import { Loader } from "./Loader.mjs";
 import * as EffectHydration from "effect/reactivity/Hydration";
 import * as AtomRegistry from "effect/reactivity/AtomRegistry";
 /**

package/dist/ReactRouter.mjs

@@ -30,14 +30,14 @@ import * as Predicate from "effect/Predicate";
 * // app/routes/issue.tsx
 * export async function loader(args: Route.LoaderArgs) {
 *   const atoms = args.context.get(atomsContext)
-*   await atoms.ensure(issue(Number(args.params.id)))
-*   return { atoms: atoms.dehydrate() }
+*   const handle = await atoms.ensure(issue, Number(args.params.id))
+*   return { atoms: atoms.dehydrate(), issue: handle }
 * }
 *
 * export default function IssueRoute(props: Route.ComponentProps) {
 *   return (
 *     <HydrationBoundary state={props.loaderData.atoms}>
-*       <Issue id={Number(props.params.id)} />
+*       <Issue issue={props.loaderData.issue} />
 *     </HydrationBoundary>
 *   )
 * }

package/dist/Waterfalls.d.mts

@@ -1,6 +1,5 @@
+import { ArgsOf, Handle, Source } from "./Handle.mjs";
 import { Mode } from "./internal/waterfalls.mjs";
-import * as Atom from "effect/reactivity/Atom";
-import * as AsyncResult from "effect/reactivity/AsyncResult";
 import * as React from "react";
 /**
  * What `useAtomResult` does in development when a read starts an atom that
@@ -51,8 +50,8 @@ export declare const WaterfallDetection: (props: {
   readonly mode: WaterfallMode;
 }) => React.ReactNode;
 /**
- * Starts an atom during render and returns it, for an input only a render
- * knows, such as a debounced search query.
+ * Starts a source's atom during render and returns its handle, for an input
+ * only a render knows, such as a debounced search query.
  *
  * **When to use**
  *
@@ -71,12 +70,14 @@ export declare const WaterfallDetection: (props: {
  * - A result the server is still streaming is awaited by `useAtomResult`,
  *   not started again.
  * - `useAtomResult` doesn't report an atom started this way.
+ * - The handle is a prefetched one: its reader suspends until the result
+ *   settles, as for a handle from a loader's `prefetch`.
  *
  * **Gotchas**
  *
- * Pass it the atom a loader would start, inside an error boundary's `wrap`:
- * `useAtomResult(boundary.wrap(useWaterfall(user(id))))`. The wrapper isn't
- * serializable, so the server couldn't send it to the browser.
+ * Pass it the source a loader would start, not an error boundary's
+ * `wrap(source)`: the wrapper's atoms aren't serializable, so the server
+ * couldn't send them to the browser. Read the handle through the wrapper.
  *
  * **Example**
  *
@@ -84,7 +85,7 @@ export declare const WaterfallDetection: (props: {
  * import { useAtomResult, useWaterfall } from "raf-effect-atom"
  *
  * function Author(props: { readonly userId: UserId }) {
- *   const result = useAtomResult(useWaterfall(user(props.userId)))
+ *   const result = useAtomResult(user, useWaterfall(user, props.userId))
  *   // ...
  * }
  * ```
@@ -95,4 +96,4 @@ export declare const WaterfallDetection: (props: {
  * @category hooks
  * @since 0.1.0
  */
-export declare const useWaterfall: <Self extends Atom.Atom<AsyncResult.AsyncResult<unknown, unknown>>>(atom: Self) => Self;
+export declare const useWaterfall: <S extends Source>(source: S, ...args: ArgsOf<S>) => Handle<S>;

package/dist/Waterfalls.mjs

@@ -2,6 +2,7 @@
 import { get } from "./internal/pending.mjs";
 import { hydrated } from "./Hydration.mjs";
 import { keyOf } from "./internal/leases.mjs";
+import { atomOf, make } from "./internal/handles.mjs";
 import { prefetch } from "./Loader.mjs";
 import { ModeContext, isStarted } from "./internal/waterfalls.mjs";
 import * as Predicate from "effect/Predicate";
@@ -53,8 +54,8 @@ const WaterfallDetection = (props) => process.env.NODE_ENV === "production" ? pr
 	children: props.children
 });
 /**
-* Starts an atom during render and returns it, for an input only a render
-* knows, such as a debounced search query.
+* Starts a source's atom during render and returns its handle, for an input
+* only a render knows, such as a debounced search query.
 *
 * **When to use**
 *
@@ -73,12 +74,14 @@ const WaterfallDetection = (props) => process.env.NODE_ENV === "production" ? pr
 * - A result the server is still streaming is awaited by `useAtomResult`,
 *   not started again.
 * - `useAtomResult` doesn't report an atom started this way.
+* - The handle is a prefetched one: its reader suspends until the result
+*   settles, as for a handle from a loader's `prefetch`.
 *
 * **Gotchas**
 *
-* Pass it the atom a loader would start, inside an error boundary's `wrap`:
-* `useAtomResult(boundary.wrap(useWaterfall(user(id))))`. The wrapper isn't
-* serializable, so the server couldn't send it to the browser.
+* Pass it the source a loader would start, not an error boundary's
+* `wrap(source)`: the wrapper's atoms aren't serializable, so the server
+* couldn't send them to the browser. Read the handle through the wrapper.
 *
 * **Example**
 *
@@ -86,7 +89,7 @@ const WaterfallDetection = (props) => process.env.NODE_ENV === "production" ? pr
 * import { useAtomResult, useWaterfall } from "raf-effect-atom"
 *
 * function Author(props: { readonly userId: UserId }) {
-*   const result = useAtomResult(useWaterfall(user(props.userId)))
+*   const result = useAtomResult(user, useWaterfall(user, props.userId))
 *   // ...
 * }
 * ```
@@ -97,11 +100,12 @@ const WaterfallDetection = (props) => process.env.NODE_ENV === "production" ? pr
 * @category hooks
 * @since 0.1.0
 */
-const useWaterfall = (atom) => {
+const useWaterfall = (source, ...args) => {
 	const registry = React.useContext(RegistryContext);
+	const atom = atomOf(source, args);
 	const target = hydrated(atom);
 	const key = keyOf(target);
-	if (!(Predicate.isString(key) && get(registry, key) !== void 0) && !isStarted(registry, target)) Effect.runSync(Effect.provideService(prefetch(atom), AtomRegistry.AtomRegistry, registry));
-	return atom;
+	if (!(Predicate.isString(key) && get(registry, key) !== void 0) && !isStarted(registry, target)) return Effect.runSync(Effect.provideService(prefetch(source, ...args), AtomRegistry.AtomRegistry, registry));
+	return make(args, atom);
 };
 export { WaterfallDetection, useWaterfall };

package/dist/index.d.mts

@@ -1,7 +1,8 @@
-import { Loader_d_exports } from "./Loader.mjs";
+import { ArgsOf, ErrorOf, Handle, HandleKey, LoadedHandle, Source, SuccessOf } from "./Handle.mjs";
 import { HydrationBoundary, HydrationBoundaryProps } from "./ReactHydration.mjs";
+import { Loader_d_exports } from "./Loader.mjs";
 import { Hydration_d_exports } from "./Hydration.mjs";
 import { RequestRegistry_d_exports } from "./RequestRegistry.mjs";
 import { useAtomResult } from "./Hooks.mjs";
 import { WaterfallDetection, WaterfallMode, useWaterfall } from "./Waterfalls.mjs";
-export { Hydration_d_exports as Hydration, HydrationBoundary, HydrationBoundaryProps, Loader_d_exports as Loader, RequestRegistry_d_exports as RequestRegistry, WaterfallDetection, WaterfallMode, useAtomResult, useWaterfall };
+export { ArgsOf, ErrorOf, Handle, HandleKey, Hydration_d_exports as Hydration, HydrationBoundary, HydrationBoundaryProps, LoadedHandle, Loader_d_exports as Loader, RequestRegistry_d_exports as RequestRegistry, Source, SuccessOf, WaterfallDetection, WaterfallMode, useAtomResult, useWaterfall };

package/dist/internal/handles.mjs

@@ -0,0 +1,22 @@
+import { keyOf as keyOf$1 } from "./leases.mjs";
+import * as Atom from "effect/reactivity/Atom";
+import * as Predicate from "effect/Predicate";
+// src/internal/handles.ts
+/** The atom a source makes for its arguments. */
+const atomOf = (source, args) => Atom.isAtom(source) ? source : source(...args);
+/** The registry key a handle records: the atom's serialization key. */
+const keyOf = (atom) => {
+	const key = keyOf$1(atom);
+	if (!Predicate.isString(key)) return;
+	return key;
+};
+const make = (args, atom) => ({
+	args,
+	key: keyOf(atom)
+});
+const loaded = (args, atom) => ({
+	args,
+	key: keyOf(atom),
+	loaded: true
+});
+export { atomOf, loaded, make };

package/dist/internal/next.mjs

@@ -9,8 +9,8 @@ const getRegistry = React.cache(() => {
 	return registry;
 });
 const getLoader = React.cache(() => make$1(getRegistry()));
-const prefetch = (atom) => getLoader().prefetch(atom);
-const ensure = (atom) => getLoader().ensure(atom);
-const fetch = (atom) => getLoader().fetch(atom);
+const prefetch = (source, ...args) => getLoader().prefetch(source, ...args);
+const ensure = (source, ...args) => getLoader().ensure(source, ...args);
+const fetch = (source, ...args) => getLoader().fetch(source, ...args);
 const dehydrate = () => dehydrate$1(getRegistry());
 export { dehydrate, ensure, fetch, getRegistry, prefetch };

package/dist/internal/waterfalls.mjs

@@ -38,7 +38,7 @@ const nameOf = (atom) => {
 	const key = keyOf(atom);
 	return atom.label?.[0] ?? (Predicate.isString(key) ? key : "an atom");
 };
-const message = (read, started) => `raf-effect-atom: rendering ${read === started ? `read ${read}` : `read ${read}, which started ${started}`} before anything else had started it, so its request waits for this render: a request waterfall. Start it before render, in the route's loader or the server component (atoms.prefetch or atoms.ensure). If the state that picks it, such as a page, a filter or an open dialog, isn't in the URL, put it there so the loader can. As escape hatches for state that can't be in the URL: start it in the event handler that changes the state (Loader.make(registry).prefetch), or, if its input only exists in render, read it with useAtomResult(useWaterfall(atom)). ${docs}`;
+const message = (read, started) => `raf-effect-atom: rendering ${read === started ? `read ${read}` : `read ${read}, which started ${started}`} before anything else had started it, so its request waits for this render: a request waterfall. Start it before render and pass its handle down, from the route's loader or the server component (atoms.prefetch(source, ...args) or atoms.ensure). If the state that picks it, such as a page, a filter or an open dialog, isn't in the URL, put it there so the loader can. As escape hatches for state that can't be in the URL: start it in the event handler that changes the state (Loader.make(registry).prefetch), or, if its input only exists in render, read it with useAtomResult(source, useWaterfall(source, ...args)). ${docs}`;
 const warned = /* @__PURE__ */ new WeakMap();
 /**
 * The nodes a read started in throw mode, with the error. React renders a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "raf-effect-atom",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "Render-as-you-fetch for Effect Atom: start atoms from route loaders and stream them into the browser, typed failures intact",
   "keywords": [
     "effect",
@@ -58,7 +58,7 @@
     "@types/react-dom": "19.3.0",
     "@vitest/coverage-v8": "5.0.5",
     "effect": "4.0.6",
-    "effect-atom-boundary": "0.0.0",
+    "effect-atom-boundary": "0.1.0",
     "happy-dom": "21.0.4",
     "react": "19.3.1",
     "react-dom": "19.3.1",