raf-effect-atom 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,10 +1,20 @@
 # 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
+- **raf-effect-atom:** `useAtomResult(atom, claims)` is gone. Read
   `useAtomResult(boundary.wrap(atom))` instead. `effect-atom-boundary` is no
   longer a peer dependency.
 
@@ -15,8 +25,9 @@
 
   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
+
+- **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
@@ -71,41 +82,41 @@
 
 ### 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))
+- **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))
+- **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))
+- **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))
+- 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))
+- 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))
+- 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

@@ -52,7 +52,7 @@ function IssueTitle(props: { readonly issue: Handle<typeof issue> }) {
 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/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(source, ...args)` starts an atom whose input exists only in render, marks it as a known waterfall, and returns its handle.

package/dist/Loader.d.mts

@@ -42,7 +42,8 @@ export declare const LeaseTTL: Context.Reference<Duration.Duration>;
  *
  * Starts the atom if it isn't in the registry, and leaves it alone if it is.
  * Takes a lease either way. The component that reads the handle suspends
- * until the result settles.
+ * until the result settles. On a request registry whose async seed is still
+ * running, it waits for the seed first.
  *
  * **Example**
  *
@@ -158,7 +159,11 @@ export interface Loader {
   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: <S extends Source>(source: S, ...args: ArgsOf<S>) => Promise<LoadedHandle<S>>;
-  /** {@link prefetch}, run at once. */
+  /**
+   * {@link prefetch}, run at once. On a request registry whose async seed is
+   * still running, it returns the handle at once and starts the atom once
+   * the seed resolves.
+   */
   readonly prefetch: <S extends Source>(source: S, ...args: ArgsOf<S>) => Handle<S>;
 }
 /**

package/dist/Loader.mjs

@@ -3,6 +3,7 @@ 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 { afterSeed, pending } from "./internal/seeds.mjs";
 import { isRequestRegistry } from "./RequestRegistry.mjs";
 import * as Atom from "effect/reactivity/Atom";
 import * as Predicate from "effect/Predicate";
@@ -66,6 +67,8 @@ var Loader_exports = /* @__PURE__ */ __exportAll({
 const LeaseTTL = Context.Reference("raf-effect-atom/Loader/LeaseTTL", { defaultValue: () => Duration.seconds(30) });
 const start = Effect.fnUntraced(function* (atom) {
 	const registry = yield* AtomRegistry.AtomRegistry;
+	const seed = pending(registry);
+	if (seed !== void 0) yield* Effect.promise(() => seed);
 	const request = isRequestRegistry(registry);
 	if (request && !Atom.isSerializable(atom) && (yield* isDevelopment)) return yield* Effect.die(/* @__PURE__ */ new Error(`raf-effect-atom: a loader started ${String(atom)}, which isn't serializable, so the browser would request it again. Give it a serialization key, such as AtomRpc's serializationKey option.`));
 	const ttl = request ? void 0 : Duration.toMillis(yield* LeaseTTL);
@@ -114,7 +117,8 @@ const rejectDefects = (result) => {
 *
 * Starts the atom if it isn't in the registry, and leaves it alone if it is.
 * Takes a lease either way. The component that reads the handle suspends
-* until the result settles.
+* until the result settles. On a request registry whose async seed is still
+* running, it waits for the seed first.
 *
 * **Example**
 *
@@ -280,7 +284,13 @@ const make = (registry, options) => {
 	return {
 		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)))
+		prefetch: (source, ...args) => {
+			const atom = atomOf(source, args);
+			afterSeed(registry, () => {
+				Effect.runSync(provide(start(atom)));
+			});
+			return make$1(args, atom);
+		}
 	};
 };
 export { LeaseTTL, Loader_exports, ensure, fetch, make, prefetch, result };

package/dist/Next.d.mts

@@ -1,8 +1,65 @@
 import { ArgsOf, Handle, LoadedHandle, Source } from "./Handle.mjs";
+import { Loader } from "./Loader.mjs";
+import { Options } from "./RequestRegistry.mjs";
 import { HydrateAtoms } from "./NextClient.mjs";
 import { RegistryProvider } from "./RegistryProvider.mjs";
 import * as EffectHydration from "effect/reactivity/Hydration";
 import * as AtomRegistry from "effect/reactivity/AtomRegistry";
+/**
+ * The loader verbs over the request registry of the server render in
+ * progress, with its registry and `dehydrate`.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export interface RequestAtoms extends Loader {
+  /**
+   * `Hydration.dehydrate` on the request's registry, for `HydrateAtoms`,
+   * once its seed has settled.
+   */
+  readonly dehydrate: () => Promise<Array<EffectHydration.DehydratedAtom>>;
+  /** The request registry of the server render in progress. */
+  readonly getRegistry: () => AtomRegistry.AtomRegistry;
+}
+/**
+ * Creates the verbs, `getRegistry` and `dehydrate` over a request registry
+ * that `seed` prepares.
+ *
+ * **When to use**
+ *
+ * Use when the request's atoms need something from the request before they
+ * run, such as an RPC protocol that forwards the page request's cookie. Make
+ * them once, in a server-only module, and call the verbs on them instead of
+ * the ones `raf-effect-atom/next` exports.
+ *
+ * **Details**
+ *
+ * The seed runs on each request's registry when a server component first
+ * uses it. It can be async, as `headers()` is: `ensure` and `fetch` wait
+ * for it, `prefetch` returns its handle at once and starts the atom once the
+ * seed resolves, and `dehydrate` waits for both.
+ *
+ * **Example**
+ *
+ * ```ts
+ * // src/atoms.server.ts
+ * import "server-only"
+ * import { headers } from "next/headers"
+ * import { makeRequestAtoms } from "raf-effect-atom/next"
+ *
+ * export const atoms = makeRequestAtoms({
+ *   seed: async (registry) => {
+ *     registry.set(requestCookie, (await headers()).get("cookie") ?? undefined)
+ *   }
+ * })
+ * ```
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 0.2.0
+ */
+export declare const makeRequestAtoms: (options?: Options) => RequestAtoms;
 /**
  * Returns the request registry of the server render in progress.
  *
@@ -57,9 +114,17 @@ export declare const fetch: <S extends Source>(source: S, ...args: ArgsOf<S>) =>
  * Includes the atoms started so far, so call it after the server component's
  * verbs. Each `HydrateAtoms` hydrates what its own `dehydrate()` saw.
  *
+ * **Example**
+ *
+ * ```tsx
+ * <HydrateAtoms state={await dehydrate()}>
+ *   <Issue issue={handle} />
+ * </HydrateAtoms>
+ * ```
+ *
  * @stability unstable
  * @category dehydration
  * @since 0.1.0
  */
-export declare const dehydrate: () => Array<EffectHydration.DehydratedAtom>;
+export declare const dehydrate: () => Promise<Array<EffectHydration.DehydratedAtom>>;
 export { HydrateAtoms, RegistryProvider };

package/dist/Next.mjs

@@ -1,8 +1,47 @@
-import { dehydrate as dehydrate$1, ensure as ensure$1, fetch as fetch$1, getRegistry as getRegistry$1, prefetch as prefetch$1 } from "./internal/next.mjs";
+import { make } from "./internal/next.mjs";
 import { HydrateAtoms } from "./NextClient.mjs";
 import { RegistryProvider } from "./RegistryProvider.mjs";
 // src/Next.ts
 /**
+* Creates the verbs, `getRegistry` and `dehydrate` over a request registry
+* that `seed` prepares.
+*
+* **When to use**
+*
+* Use when the request's atoms need something from the request before they
+* run, such as an RPC protocol that forwards the page request's cookie. Make
+* them once, in a server-only module, and call the verbs on them instead of
+* the ones `raf-effect-atom/next` exports.
+*
+* **Details**
+*
+* The seed runs on each request's registry when a server component first
+* uses it. It can be async, as `headers()` is: `ensure` and `fetch` wait
+* for it, `prefetch` returns its handle at once and starts the atom once the
+* seed resolves, and `dehydrate` waits for both.
+*
+* **Example**
+*
+* ```ts
+* // src/atoms.server.ts
+* import "server-only"
+* import { headers } from "next/headers"
+* import { makeRequestAtoms } from "raf-effect-atom/next"
+*
+* export const atoms = makeRequestAtoms({
+*   seed: async (registry) => {
+*     registry.set(requestCookie, (await headers()).get("cookie") ?? undefined)
+*   }
+* })
+* ```
+*
+* @stability unstable
+* @category constructors
+* @since 0.2.0
+*/
+const makeRequestAtoms = make;
+const atoms = make();
+/**
 * Returns the request registry of the server render in progress.
 *
 * **Details**
@@ -20,7 +59,7 @@ import { RegistryProvider } from "./RegistryProvider.mjs";
 * @category registry
 * @since 0.1.0
 */
-const getRegistry = getRegistry$1;
+const getRegistry = atoms.getRegistry;
 /**
 * `Loader.prefetch` on the request's registry: starts a source's atom, to
 * stream it, and returns its handle.
@@ -29,7 +68,7 @@ const getRegistry = getRegistry$1;
 * @category verbs
 * @since 0.1.0
 */
-const prefetch = prefetch$1;
+const prefetch = atoms.prefetch;
 /**
 * `Loader.ensure` on the request's registry: starts a source's atom, waits
 * for its result, and returns its handle.
@@ -38,7 +77,7 @@ const prefetch = prefetch$1;
 * @category verbs
 * @since 0.1.0
 */
-const ensure = ensure$1;
+const ensure = atoms.ensure;
 /**
 * `Loader.fetch` on the request's registry: starts or refreshes a source's
 * atom, waits for the new result, and returns its handle.
@@ -47,7 +86,7 @@ const ensure = ensure$1;
 * @category verbs
 * @since 0.1.0
 */
-const fetch = fetch$1;
+const fetch = atoms.fetch;
 /**
 * `Hydration.dehydrate` on the request's registry, for `HydrateAtoms`.
 *
@@ -56,9 +95,17 @@ const fetch = fetch$1;
 * Includes the atoms started so far, so call it after the server component's
 * verbs. Each `HydrateAtoms` hydrates what its own `dehydrate()` saw.
 *
+* **Example**
+*
+* ```tsx
+* <HydrateAtoms state={await dehydrate()}>
+*   <Issue issue={handle} />
+* </HydrateAtoms>
+* ```
+*
 * @stability unstable
 * @category dehydration
 * @since 0.1.0
 */
-const dehydrate = dehydrate$1;
-export { HydrateAtoms, RegistryProvider, dehydrate, ensure, fetch, getRegistry, prefetch };
+const dehydrate = atoms.dehydrate;
+export { HydrateAtoms, RegistryProvider, dehydrate, ensure, fetch, getRegistry, makeRequestAtoms, prefetch };

package/dist/NextClient.d.mts

@@ -1,7 +1,7 @@
 import { HydrationBoundaryProps } from "./ReactHydration.mjs";
 import * as React from "react";
 /**
- * Hydrates the state a server component dehydrated with `dehydrate()`,
+ * Hydrates the state a server component dehydrated with `await dehydrate()`,
  * streamed results included.
  *
  * **Details**
@@ -18,7 +18,7 @@ import * as React from "react";
  * export default async function IssuePage(props: { params: Promise<{ id: string }> }) {
  *   const handle = await ensure(issue, Number((await props.params).id))
  *   return (
- *     <HydrateAtoms state={dehydrate()}>
+ *     <HydrateAtoms state={await dehydrate()}>
  *       <Issue issue={handle} />
  *     </HydrateAtoms>
  *   )

package/dist/NextClient.mjs

@@ -9,7 +9,7 @@ import { jsx } from "react/jsx-runtime";
 * @since 0.1.0
 */
 /**
-* Hydrates the state a server component dehydrated with `dehydrate()`,
+* Hydrates the state a server component dehydrated with `await dehydrate()`,
 * streamed results included.
 *
 * **Details**
@@ -26,7 +26,7 @@ import { jsx } from "react/jsx-runtime";
 * export default async function IssuePage(props: { params: Promise<{ id: string }> }) {
 *   const handle = await ensure(issue, Number((await props.params).id))
 *   return (
-*     <HydrateAtoms state={dehydrate()}>
+*     <HydrateAtoms state={await dehydrate()}>
 *       <Issue issue={handle} />
 *     </HydrateAtoms>
 *   )

package/dist/ReactRouter.d.mts

@@ -1,5 +1,5 @@
-import { RegistryProvider } from "./RegistryProvider.mjs";
 import { Loader } from "./Loader.mjs";
+import { RegistryProvider } from "./RegistryProvider.mjs";
 import * as EffectHydration from "effect/reactivity/Hydration";
 import * as AtomRegistry from "effect/reactivity/AtomRegistry";
 /**
@@ -36,6 +36,22 @@ export interface MiddlewareArgs {
   readonly context: {
     readonly set: (context: AtomsContext, value: RequestAtoms) => void;
   };
+  readonly request: Request;
+}
+/**
+ * Options for `atomsMiddleware`.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export interface AtomsMiddlewareOptions {
+  /**
+   * Runs on each request's registry before the loaders, with the request,
+   * to set what its atoms need, such as its cookie. The middleware waits
+   * for one that returns a promise.
+   */
+  readonly seed?: ((registry: AtomRegistry.AtomRegistry, request: Request) => void | Promise<void>) | undefined;
 }
 /**
  * Creates a root middleware that gives each server request its own
@@ -49,15 +65,30 @@ export interface MiddlewareArgs {
  * then. When `next` doesn't return a `Response`, as Data Mode's
  * `query` can, the registry is left to be collected with the request.
  *
+ * `seed` runs on the new registry before `next`, so every loader's atoms
+ * start with what it sets.
+ *
  * **Gotchas**
  *
  * It's server middleware: export it as the root route's `middleware`, not
  * `clientMiddleware`. In the browser, the root's `RegistryProvider` holds
  * the registry.
  *
+ * **Example**
+ *
+ * ```ts
+ * export const middleware = [
+ *   atomsMiddleware(atomsContext, {
+ *     // In-process RPC calls send the page request's cookie.
+ *     seed: (registry, request) =>
+ *       registry.set(requestCookie, request.headers.get("cookie") ?? undefined)
+ *   })
+ * ]
+ * ```
+ *
  * @stability unstable
  * @category integrations
  * @since 0.1.0
  */
-export declare const atomsMiddleware: (context: AtomsContext) => <Result>(args: MiddlewareArgs, next: () => Promise<Result>) => Promise<Result>;
+export declare const atomsMiddleware: (context: AtomsContext, options?: AtomsMiddlewareOptions) => <Result>(args: MiddlewareArgs, next: () => Promise<Result>) => Promise<Result>;
 export { RegistryProvider };

package/dist/ReactRouter.mjs

@@ -1,5 +1,5 @@
 import { dehydrate } from "./Hydration.mjs";
-import { make } from "./RequestRegistry.mjs";
+import { make, settled } from "./RequestRegistry.mjs";
 import { make as make$1 } from "./Loader.mjs";
 import { RegistryProvider } from "./RegistryProvider.mjs";
 import * as Predicate from "effect/Predicate";
@@ -58,18 +58,40 @@ import * as Predicate from "effect/Predicate";
 * then. When `next` doesn't return a `Response`, as Data Mode's
 * `query` can, the registry is left to be collected with the request.
 *
+* `seed` runs on the new registry before `next`, so every loader's atoms
+* start with what it sets.
+*
 * **Gotchas**
 *
 * It's server middleware: export it as the root route's `middleware`, not
 * `clientMiddleware`. In the browser, the root's `RegistryProvider` holds
 * the registry.
 *
+* **Example**
+*
+* ```ts
+* export const middleware = [
+*   atomsMiddleware(atomsContext, {
+*     // In-process RPC calls send the page request's cookie.
+*     seed: (registry, request) =>
+*       registry.set(requestCookie, request.headers.get("cookie") ?? undefined)
+*   })
+* ]
+* ```
+*
 * @stability unstable
 * @category integrations
 * @since 0.1.0
 */
-const atomsMiddleware = (context) => async (args, next) => {
-	const registry = make();
+const atomsMiddleware = (context, options) => async (args, next) => {
+	const seed = options?.seed;
+	const registry = make({ seed: seed === void 0 ? void 0 : (created) => seed(created, args.request) });
+	try {
+		await settled(registry);
+	} catch (error) {
+		registry.dispose();
+		throw error;
+	}
 	const loader = make$1(registry);
 	args.context.set(context, {
 		...loader,

package/dist/RequestRegistry.d.mts

@@ -1,32 +1,88 @@
+import { Seed as Seed$1 } from "./internal/seeds.mjs";
 import * as AtomRegistry from "effect/reactivity/AtomRegistry";
 import * as Layer from "effect/Layer";
 declare namespace RequestRegistry_d_exports {
-  export { isRequestRegistry, layer, make };
+  export { Options, Seed, isRequestRegistry, layer, make, settled };
+}
+/**
+ * Prepares a request registry before the loader verbs start atoms in it,
+ * such as by setting an atom to the request's cookie.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export type Seed = Seed$1;
+/**
+ * Options for `make`.
+ *
+ * @stability unstable
+ * @category models
+ * @since 0.2.0
+ */
+export interface Options {
+  /**
+   * Runs on the new registry before any verb starts an atom in it. When it
+   * returns a promise, `ensure` and `fetch` wait for it, and `prefetch`
+   * returns its handle at once and starts the atom once it resolves.
+   */
+  readonly seed?: Seed | undefined;
 }
 /**
  * Creates the registry for one server request.
  *
  * **Details**
  *
- * It's an ordinary `AtomRegistry`, marked as a request registry. On a
- * request registry, `ensure` waits like `fetch` does, nothing revalidates in
- * the background, and a loader's lease lasts until the registry is disposed.
- * In development, the loader verbs refuse an atom that isn't serializable,
- * because the browser would request it again.
+ * - It's an ordinary `AtomRegistry`, marked as a request registry. On a
+ *   request registry, `ensure` waits like `fetch` does, nothing revalidates
+ *   in the background, and a loader's lease lasts until the registry is
+ *   disposed. In development, the loader verbs refuse an atom that isn't
+ *   serializable, because the browser would request it again.
+ * - `seed` sets what the request's atoms need before they run, such as the
+ *   page request's cookie for an RPC protocol that forwards it. It can be
+ *   async, for request data only a promise gives, such as Next.js's
+ *   `headers()`.
+ *
+ * **Gotchas**
+ *
+ * With an async seed, a `prefetch` before it settles starts its atom later,
+ * so `Hydration.dehydrate` would miss it: wait for `settled` first, as the
+ * framework integrations do.
  *
  * **Example**
  *
  * ```ts
  * import { RequestRegistry } from "raf-effect-atom"
  *
- * const registry = RequestRegistry.make()
+ * const registry = RequestRegistry.make({
+ *   seed: (registry) => registry.set(requestCookie, request.headers.get("cookie") ?? undefined)
+ * })
  * ```
  *
  * @stability unstable
  * @category constructors
  * @since 0.1.0
  */
-export declare const make: () => AtomRegistry.AtomRegistry;
+export declare const make: (options?: Options) => AtomRegistry.AtomRegistry;
+/**
+ * Waits until a request registry's seed has settled and every atom a verb
+ * started while it ran has started.
+ *
+ * **When to use**
+ *
+ * Use before `Hydration.dehydrate` on a registry with an async seed, outside
+ * the framework integrations, which call it for you.
+ *
+ * **Details**
+ *
+ * Resolves at once for a registry without a seed, or whose seed was
+ * synchronous. Rejects with the seed's error.
+ *
+ * @stability unstable
+ * @category getters
+ * @since 0.2.0
+ */
+export declare const settled: (registry: AtomRegistry.AtomRegistry) => Promise<void>;
 /**
  * A layer that provides a request registry as the `AtomRegistry`, disposed
  * when the layer's scope closes.

package/dist/RequestRegistry.mjs

@@ -1,4 +1,5 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.mjs";
+import { run, settled as settled$1 } from "./internal/seeds.mjs";
 import * as Effect from "effect/Effect";
 import * as AtomRegistry from "effect/reactivity/AtomRegistry";
 import * as Layer from "effect/Layer";
@@ -18,7 +19,8 @@ import * as Layer from "effect/Layer";
 var RequestRegistry_exports = /* @__PURE__ */ __exportAll({
 	isRequestRegistry: () => isRequestRegistry,
 	layer: () => layer,
-	make: () => make
+	make: () => make,
+	settled: () => settled
 });
 const requestRegistries = /* @__PURE__ */ new WeakSet();
 /**
@@ -26,30 +28,62 @@ const requestRegistries = /* @__PURE__ */ new WeakSet();
 *
 * **Details**
 *
-* It's an ordinary `AtomRegistry`, marked as a request registry. On a
-* request registry, `ensure` waits like `fetch` does, nothing revalidates in
-* the background, and a loader's lease lasts until the registry is disposed.
-* In development, the loader verbs refuse an atom that isn't serializable,
-* because the browser would request it again.
+* - It's an ordinary `AtomRegistry`, marked as a request registry. On a
+*   request registry, `ensure` waits like `fetch` does, nothing revalidates
+*   in the background, and a loader's lease lasts until the registry is
+*   disposed. In development, the loader verbs refuse an atom that isn't
+*   serializable, because the browser would request it again.
+* - `seed` sets what the request's atoms need before they run, such as the
+*   page request's cookie for an RPC protocol that forwards it. It can be
+*   async, for request data only a promise gives, such as Next.js's
+*   `headers()`.
+*
+* **Gotchas**
+*
+* With an async seed, a `prefetch` before it settles starts its atom later,
+* so `Hydration.dehydrate` would miss it: wait for `settled` first, as the
+* framework integrations do.
 *
 * **Example**
 *
 * ```ts
 * import { RequestRegistry } from "raf-effect-atom"
 *
-* const registry = RequestRegistry.make()
+* const registry = RequestRegistry.make({
+*   seed: (registry) => registry.set(requestCookie, request.headers.get("cookie") ?? undefined)
+* })
 * ```
 *
 * @stability unstable
 * @category constructors
 * @since 0.1.0
 */
-const make = () => {
+const make = (options) => {
 	const registry = AtomRegistry.make();
 	requestRegistries.add(registry);
+	if (options?.seed !== void 0) run(registry, options.seed);
 	return registry;
 };
 /**
+* Waits until a request registry's seed has settled and every atom a verb
+* started while it ran has started.
+*
+* **When to use**
+*
+* Use before `Hydration.dehydrate` on a registry with an async seed, outside
+* the framework integrations, which call it for you.
+*
+* **Details**
+*
+* Resolves at once for a registry without a seed, or whose seed was
+* synchronous. Rejects with the seed's error.
+*
+* @stability unstable
+* @category getters
+* @since 0.2.0
+*/
+const settled = (registry) => settled$1(registry);
+/**
 * A layer that provides a request registry as the `AtomRegistry`, disposed
 * when the layer's scope closes.
 *
@@ -73,4 +107,4 @@ const layer = Layer.effect(AtomRegistry.AtomRegistry, Effect.acquireRelease(Effe
 * @since 0.1.0
 */
 const isRequestRegistry = (registry) => requestRegistries.has(registry);
-export { RequestRegistry_exports, isRequestRegistry, layer, make };
+export { RequestRegistry_exports, isRequestRegistry, layer, make, settled };

package/dist/TanStackRouter.d.mts

@@ -1,3 +1,4 @@
+import { Seed } from "./RequestRegistry.mjs";
 import * as EffectHydration from "effect/reactivity/Hydration";
 import * as AtomRegistry from "effect/reactivity/AtomRegistry";
 import { AnyRouter } from "@tanstack/react-router";
@@ -38,14 +39,23 @@ export interface RouterAtomsOptions<TRouter extends AnyRouter> {
  *   default registry does. An atom's own `Atom.setIdleTTL` or
  *   `Atom.keepAlive` wins. The server's request registry lives for one
  *   request, so it has none.
+ * - `seed` runs on the server's request registry before the loaders start
+ *   atoms in it, as `RequestRegistry.make`'s does: set what the request's
+ *   atoms need, such as its cookie. It can be async. The browser's registry
+ *   isn't seeded.
  *
  * **Example**
  *
  * ```ts
+ * import { getRequestHeader } from "@tanstack/react-start/server"
  * import { makeRegistry } from "raf-effect-atom/tanstack-router"
  *
- * // Keeps an issue the user navigated away from for a minute.
- * const registry = makeRegistry({ defaultIdleTTL: 60_000 })
+ * const registry = makeRegistry({
+ *   // Keeps an issue the user navigated away from for a minute.
+ *   defaultIdleTTL: 60_000,
+ *   // In-process RPC calls send the page request's cookie.
+ *   seed: (registry) => registry.set(requestCookie, getRequestHeader("cookie"))
+ * })
  * ```
  *
  * @stability unstable
@@ -54,6 +64,7 @@ export interface RouterAtomsOptions<TRouter extends AnyRouter> {
  */
 export declare const makeRegistry: (options?: {
   readonly defaultIdleTTL?: number | undefined;
+  readonly seed?: Seed | undefined;
 }) => AtomRegistry.AtomRegistry;
 /**
  * Provides a registry to a TanStack router's app and streams it from the

package/dist/TanStackRouter.mjs

@@ -1,5 +1,5 @@
 import { dehydrate, hydrate } from "./Hydration.mjs";
-import { isRequestRegistry } from "./RequestRegistry.mjs";
+import { isRequestRegistry, settled } from "./RequestRegistry.mjs";
 import { make } from "./internal/registry.mjs";
 import * as Predicate from "effect/Predicate";
 import { RegistryContext } from "@effect/atom-react";
@@ -51,14 +51,23 @@ import { jsx } from "react/jsx-runtime";
 *   default registry does. An atom's own `Atom.setIdleTTL` or
 *   `Atom.keepAlive` wins. The server's request registry lives for one
 *   request, so it has none.
+* - `seed` runs on the server's request registry before the loaders start
+*   atoms in it, as `RequestRegistry.make`'s does: set what the request's
+*   atoms need, such as its cookie. It can be async. The browser's registry
+*   isn't seeded.
 *
 * **Example**
 *
 * ```ts
+* import { getRequestHeader } from "@tanstack/react-start/server"
 * import { makeRegistry } from "raf-effect-atom/tanstack-router"
 *
-* // Keeps an issue the user navigated away from for a minute.
-* const registry = makeRegistry({ defaultIdleTTL: 60_000 })
+* const registry = makeRegistry({
+*   // Keeps an issue the user navigated away from for a minute.
+*   defaultIdleTTL: 60_000,
+*   // In-process RPC calls send the page request's cookie.
+*   seed: (registry) => registry.set(requestCookie, getRequestHeader("cookie"))
+* })
 * ```
 *
 * @stability unstable
@@ -116,6 +125,7 @@ const setupRouterAtoms = (options) => {
 		const dehydrate$1 = router.options.dehydrate;
 		router.options.dehydrate = async () => {
 			const dehydrated = await dehydrate$1?.();
+			await settled(registry);
 			if (disposed) return dehydrated;
 			const atoms = { "raf-effect-atom": dehydrate(registry) };
 			return Predicate.isObject(dehydrated) ? {

package/dist/index.d.mts

@@ -1,8 +1,8 @@
 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 { HydrationBoundary, HydrationBoundaryProps } from "./ReactHydration.mjs";
+import { Hydration_d_exports } from "./Hydration.mjs";
 import { useAtomResult } from "./Hooks.mjs";
 import { WaterfallDetection, WaterfallMode, useWaterfall } from "./Waterfalls.mjs";
 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/next.mjs

@@ -1,16 +1,25 @@
-import { dehydrate as dehydrate$1 } from "../Hydration.mjs";
-import { make } from "../RequestRegistry.mjs";
-import { make as make$1 } from "../Loader.mjs";
+import { dehydrate } from "../Hydration.mjs";
+import { make as make$1, settled } from "../RequestRegistry.mjs";
+import { make as make$2 } from "../Loader.mjs";
 import * as React from "react";
 // src/internal/next.ts
-const getRegistry = React.cache(() => {
-	const registry = make();
-	React.cacheSignal()?.addEventListener("abort", () => registry.dispose(), { once: true });
-	return registry;
-});
-const getLoader = React.cache(() => make$1(getRegistry()));
-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 };
+const make = (options) => {
+	const getRegistry = React.cache(() => {
+		const registry = make$1(options);
+		React.cacheSignal()?.addEventListener("abort", () => registry.dispose(), { once: true });
+		return registry;
+	});
+	const getLoader = React.cache(() => make$2(getRegistry()));
+	return {
+		dehydrate: async () => {
+			const registry = getRegistry();
+			await settled(registry);
+			return dehydrate(registry);
+		},
+		ensure: (source, ...args) => getLoader().ensure(source, ...args),
+		fetch: (source, ...args) => getLoader().fetch(source, ...args),
+		getRegistry,
+		prefetch: (source, ...args) => getLoader().prefetch(source, ...args)
+	};
+};
+export { make };

package/dist/internal/registry.mjs

@@ -9,7 +9,7 @@ const defaultIdleTTL = 400;
 * A request registry on the server, and in the browser a registry like
 * `@effect/atom-react`'s `RegistryProvider` makes.
 */
-const make = (options) => isServer() ? make$1() : AtomRegistry.make({
+const make = (options) => isServer() ? make$1({ seed: options?.seed }) : AtomRegistry.make({
 	defaultIdleTTL: options?.defaultIdleTTL ?? defaultIdleTTL,
 	scheduleTask
 });

package/dist/internal/seeds.d.mts

@@ -0,0 +1,3 @@
+import * as AtomRegistry from "effect/reactivity/AtomRegistry";
+/** Prepares a request registry before any loader verb starts an atom in it. */
+export type Seed = (registry: AtomRegistry.AtomRegistry) => void | Promise<void>;

package/dist/internal/seeds.mjs

@@ -0,0 +1,56 @@
+import * as Predicate from "effect/Predicate";
+// src/internal/seeds.ts
+const seedings = /* @__PURE__ */ new WeakMap();
+const waiting = (registry) => {
+	const seeding = seedings.get(registry);
+	return seeding === void 0 || seeding.resolved ? void 0 : seeding;
+};
+/**
+* Runs `seed` on `registry`. Until a seed's promise settles, the verbs wait
+* for it.
+*/
+const run = (registry, seed) => {
+	const result = seed(registry);
+	if (!Predicate.isPromiseLike(result)) return;
+	const seeded = Promise.resolve(result);
+	const seeding = {
+		deferred: [],
+		resolved: false,
+		seeded
+	};
+	seeded.then(() => {
+		seeding.resolved = true;
+	}, () => void 0);
+	seedings.set(registry, seeding);
+};
+/**
+* The seed the verbs wait for: `undefined` once it has resolved, and the
+* rejected promise once it has failed.
+*/
+const pending = (registry) => waiting(registry)?.seeded;
+/**
+* Runs `start` once the registry's seed has resolved: at once, unless it's
+* still running. A seed that fails never runs it.
+*/
+const afterSeed = (registry, start) => {
+	const seeding = waiting(registry);
+	if (seeding === void 0) {
+		start();
+		return;
+	}
+	const started = seeding.seeded.then(start);
+	started.catch(() => void 0);
+	seeding.deferred.push(started);
+};
+/**
+* Waits for the registry's seed and the starts that waited for it, so
+* `Hydration.dehydrate` sees every atom the verbs started. Rejects with the
+* seed's error, or with a start's defect.
+*/
+const settled = async (registry) => {
+	const seeding = seedings.get(registry);
+	if (seeding === void 0) return;
+	await seeding.seeded;
+	await Promise.all(seeding.deferred);
+};
+export { afterSeed, pending, run, settled };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "raf-effect-atom",
-  "version": "0.1.0",
+  "version": "0.2.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",