@effect/atom-react 4.0.0-beta.7 → 4.0.0-beta.70

package/dist/ScopedAtom.d.ts

@@ -1,37 +1,34 @@
 import type * as Atom from "effect/unstable/reactivity/Atom";
 import * as React from "react";
 /**
- * @since 1.0.0
- * @category Type IDs
- *
  * Type identifier for ScopedAtom.
+ *
+ * @category type IDs
+ * @since 4.0.0
  */
 export type TypeId = "~@effect/atom-react/ScopedAtom";
 /**
- * @since 1.0.0
- * @category Type IDs
- *
  * Type identifier for ScopedAtom.
+ *
+ * @category type IDs
+ * @since 4.0.0
  */
 export declare const TypeId: TypeId;
 /**
- * @since 1.0.0
- * @category models
- *
  * Scoped Atom interface with a provider-backed instance.
  *
- * @example
+ * **Example** (Providing and reading a scoped atom)
+ *
  * ```ts
- * import * as Atom from "effect/unstable/reactivity/Atom"
+ * import * as AtomReact from "@effect/atom-react"
+ * import { Atom } from "effect/unstable/reactivity"
  * import * as React from "react"
- * import * as ScopedAtom from "@effect/atom-react/ScopedAtom"
- * import { useAtomValue } from "@effect/atom-react"
  *
- * const Counter = ScopedAtom.make(() => Atom.make(0))
+ * const Counter = AtomReact.make(() => Atom.make(0))
  *
  * function View() {
  *   const atom = Counter.use()
- *   const value = useAtomValue(atom)
+ *   const value = AtomReact.useAtomValue(atom)
  *   return React.createElement("div", null, value)
  * }
  *
@@ -39,11 +36,14 @@ export declare const TypeId: TypeId;
  *   return React.createElement(Counter.Provider, null, React.createElement(View))
  * }
  * ```
+ *
+ * @category models
+ * @since 4.0.0
  */
 export interface ScopedAtom<A extends Atom.Atom<any>, Input = never> {
     readonly [TypeId]: TypeId;
     use(): A;
-    Provider: Input extends never ? React.FC<{
+    Provider: [Input] extends [never] ? React.FC<{
         readonly children?: React.ReactNode | undefined;
     }> : React.FC<{
         readonly children?: React.ReactNode | undefined;
@@ -52,23 +52,20 @@ export interface ScopedAtom<A extends Atom.Atom<any>, Input = never> {
     Context: React.Context<A>;
 }
 /**
- * @since 1.0.0
- * @category constructors
- *
  * Creates a ScopedAtom from a factory function.
  *
- * @example
+ * **Example** (Creating a scoped atom with input)
+ *
  * ```ts
- * import * as Atom from "effect/unstable/reactivity/Atom"
+ * import * as AtomReact from "@effect/atom-react"
+ * import { Atom } from "effect/unstable/reactivity"
  * import * as React from "react"
- * import * as ScopedAtom from "@effect/atom-react/ScopedAtom"
- * import { useAtomValue } from "@effect/atom-react"
  *
- * const User = ScopedAtom.make((name: string) => Atom.make(name))
+ * const User = AtomReact.make((name: string) => Atom.make(name))
  *
  * function UserName() {
  *   const atom = User.use()
- *   const value = useAtomValue(atom)
+ *   const value = AtomReact.useAtomValue(atom)
  *   return React.createElement("span", null, value)
  * }
  *
@@ -80,6 +77,9 @@ export interface ScopedAtom<A extends Atom.Atom<any>, Input = never> {
  *   )
  * }
  * ```
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export declare const make: <A extends Atom.Atom<any>, Input = never>(f: (() => A) | ((input: Input) => A)) => ScopedAtom<A, Input>;
 //# sourceMappingURL=ScopedAtom.d.ts.map

package/dist/ScopedAtom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ScopedAtom.d.ts","sourceRoot":"","sources":["../src/ScopedAtom.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,KAAK,IAAI,MAAM,iCAAiC,CAAA;AAC5D,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,gCAAgC,CAAA;AAErD;;;;;GAKG;AACH,eAAO,MAAM,MAAM,EAAE,MAAyC,CAAA;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK;IACjE,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACzB,GAAG,IAAI,CAAC,CAAA;IACR,QAAQ,EAAE,KAAK,SAAS,KAAK,GAAG,KAAK,CAAC,EAAE,CAAC;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,SAAS,CAAA;KAAE,CAAC,GACzF,KAAK,CAAC,EAAE,CAAC;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC,CAAA;IACxF,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,EAC1D,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,CAAC,CAAC,KACnC,UAAU,CAAC,CAAC,EAAE,KAAK,CA6BrB,CAAA"}
+{"version":3,"file":"ScopedAtom.d.ts","sourceRoot":"","sources":["../src/ScopedAtom.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,KAAK,IAAI,MAAM,iCAAiC,CAAA;AAC5D,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,gCAAgC,CAAA;AAErD;;;;;GAKG;AACH,eAAO,MAAM,MAAM,EAAE,MAAyC,CAAA;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK;IACjE,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACzB,GAAG,IAAI,CAAC,CAAA;IACR,QAAQ,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,EAAE,CAAC;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,SAAS,CAAA;KAAE,CAAC,GAC7F,KAAK,CAAC,EAAE,CAAC;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC,CAAA;IACxF,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,EAC1D,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,CAAC,CAAC,KACnC,UAAU,CAAC,CAAC,EAAE,KAAK,CA6BrB,CAAA"}

package/dist/ScopedAtom.js

@@ -1,34 +1,48 @@
 /**
- * @since 1.0.0
+ * The `ScopedAtom` module provides a small React integration for creating atom
+ * instances that are scoped to a component subtree. A scoped atom bundles a
+ * React provider, context, and `use` accessor so each mounted provider owns its
+ * own atom instance instead of sharing a single module-level atom.
+ *
+ * Use `ScopedAtom` when an atom needs to be isolated per feature, route,
+ * component instance, test harness, or provider input. The provider may receive
+ * an initial `value` that is passed to the atom factory, making it useful for
+ * state that should be seeded from React props while still being consumed by the
+ * atom hooks in descendants.
+ *
+ * **Gotchas**
+ *
+ * - `use` must be called under the matching provider or it throws.
+ * - The provider creates the atom once for its lifetime; changing the provider
+ *   `value` prop after mount does not recreate the atom.
+ *
+ * @since 4.0.0
  */
 "use client";
 
 import * as React from "react";
 /**
- * @since 1.0.0
- * @category Type IDs
- *
  * Type identifier for ScopedAtom.
+ *
+ * @category type IDs
+ * @since 4.0.0
  */
 export const TypeId = "~@effect/atom-react/ScopedAtom";
 /**
- * @since 1.0.0
- * @category constructors
- *
  * Creates a ScopedAtom from a factory function.
  *
- * @example
+ * **Example** (Creating a scoped atom with input)
+ *
  * ```ts
- * import * as Atom from "effect/unstable/reactivity/Atom"
+ * import * as AtomReact from "@effect/atom-react"
+ * import { Atom } from "effect/unstable/reactivity"
  * import * as React from "react"
- * import * as ScopedAtom from "@effect/atom-react/ScopedAtom"
- * import { useAtomValue } from "@effect/atom-react"
  *
- * const User = ScopedAtom.make((name: string) => Atom.make(name))
+ * const User = AtomReact.make((name: string) => Atom.make(name))
  *
  * function UserName() {
  *   const atom = User.use()
- *   const value = useAtomValue(atom)
+ *   const value = AtomReact.useAtomValue(atom)
  *   return React.createElement("span", null, value)
  * }
  *
@@ -40,6 +54,9 @@ export const TypeId = "~@effect/atom-react/ScopedAtom";
  *   )
  * }
  * ```
+ *
+ * @category constructors
+ * @since 4.0.0
  */
 export const make = f => {
   const Context = React.createContext(undefined);

package/dist/ScopedAtom.js.map

@@ -1 +1 @@
-{"version":3,"file":"ScopedAtom.js","names":["React","TypeId","make","f","Context","createContext","undefined","use","atom","useContext","Error","Provider","props","useRef","current","value","createElement","children"],"sources":["../src/ScopedAtom.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAGA,YAAY;;AAGZ,OAAO,KAAKA,KAAK,MAAM,OAAO;AAU9B;;;;;;AAMA,OAAO,MAAMC,MAAM,GAAW,gCAAgC;AAoC9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,OAAO,MAAMC,IAAI,GACfC,CAAoC,IACZ;EACxB,MAAMC,OAAO,GAAGJ,KAAK,CAACK,aAAa,CAAIC,SAAyB,CAAC;EAEjE,MAAMC,GAAG,GAAGA,CAAA,KAAQ;IAClB,MAAMC,IAAI,GAAGR,KAAK,CAACS,UAAU,CAACL,OAAO,CAAC;IACtC,IAAII,IAAI,KAAKF,SAAS,EAAE;MACtB,MAAM,IAAII,KAAK,CAAC,yCAAyC,CAAC;IAC5D;IACA,OAAOF,IAAI;EACb,CAAC;EAED,MAAMG,QAAQ,GAA2FC,KAAK,IAAI;IAChH,MAAMJ,IAAI,GAAGR,KAAK,CAACa,MAAM,CAAW,IAAI,CAAC;IACzC,IAAIL,IAAI,CAACM,OAAO,KAAK,IAAI,EAAE;MACzB,IAAI,OAAO,IAAIF,KAAK,EAAE;QACpBJ,IAAI,CAACM,OAAO,GAAIX,CAAyB,CAACS,KAAK,CAACG,KAAc,CAAC;MACjE,CAAC,MAAM;QACLP,IAAI,CAACM,OAAO,GAAIX,CAAa,EAAE;MACjC;IACF;IACA,OAAOH,KAAK,CAACgB,aAAa,CAACZ,OAAO,CAACO,QAAQ,EAAE;MAAEI,KAAK,EAAEP,IAAI,CAACM;IAAO,CAAE,EAAEF,KAAK,CAACK,QAAQ,CAAC;EACvF,CAAC;EAED,OAAO;IACL,CAAChB,MAAM,GAAGA,MAAM;IAChBM,GAAG;IACHI,QAAQ,EAAEA,QAAe;IACzBP;GACD;AACH,CAAC","ignoreList":[]}
+{"version":3,"file":"ScopedAtom.js","names":["React","TypeId","make","f","Context","createContext","undefined","use","atom","useContext","Error","Provider","props","useRef","current","value","createElement","children"],"sources":["../src/ScopedAtom.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;AAoBA,YAAY;;AAGZ,OAAO,KAAKA,KAAK,MAAM,OAAO;AAU9B;;;;;;AAMA,OAAO,MAAMC,MAAM,GAAW,gCAAgC;AAoC9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,OAAO,MAAMC,IAAI,GACfC,CAAoC,IACZ;EACxB,MAAMC,OAAO,GAAGJ,KAAK,CAACK,aAAa,CAAIC,SAAyB,CAAC;EAEjE,MAAMC,GAAG,GAAGA,CAAA,KAAQ;IAClB,MAAMC,IAAI,GAAGR,KAAK,CAACS,UAAU,CAACL,OAAO,CAAC;IACtC,IAAII,IAAI,KAAKF,SAAS,EAAE;MACtB,MAAM,IAAII,KAAK,CAAC,yCAAyC,CAAC;IAC5D;IACA,OAAOF,IAAI;EACb,CAAC;EAED,MAAMG,QAAQ,GAA2FC,KAAK,IAAI;IAChH,MAAMJ,IAAI,GAAGR,KAAK,CAACa,MAAM,CAAW,IAAI,CAAC;IACzC,IAAIL,IAAI,CAACM,OAAO,KAAK,IAAI,EAAE;MACzB,IAAI,OAAO,IAAIF,KAAK,EAAE;QACpBJ,IAAI,CAACM,OAAO,GAAIX,CAAyB,CAACS,KAAK,CAACG,KAAc,CAAC;MACjE,CAAC,MAAM;QACLP,IAAI,CAACM,OAAO,GAAIX,CAAa,EAAE;MACjC;IACF;IACA,OAAOH,KAAK,CAACgB,aAAa,CAACZ,OAAO,CAACO,QAAQ,EAAE;MAAEI,KAAK,EAAEP,IAAI,CAACM;IAAO,CAAE,EAAEF,KAAK,CAACK,QAAQ,CAAC;EACvF,CAAC;EAED,OAAO;IACL,CAAChB,MAAM,GAAGA,MAAM;IAChBM,GAAG;IACHI,QAAQ,EAAEA,QAAe;IACzBP;GACD;AACH,CAAC","ignoreList":[]}

package/dist/index.d.ts

@@ -1,20 +1,20 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "./Hooks.ts";
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "./RegistryContext.ts";
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "./ReactHydration.ts";
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "./ScopedAtom.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,20 +1,20 @@
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "./Hooks.js";
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "./RegistryContext.js";
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "./ReactHydration.js";
 /**
- * @since 1.0.0
+ * @since 4.0.0
  */
 export * from "./ScopedAtom.js";
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect/atom-react",
-  "version": "4.0.0-beta.7",
+  "version": "4.0.0-beta.70",
   "type": "module",
   "license": "MIT",
   "description": "React bindings for the Effect Atom modules",
@@ -45,21 +45,21 @@
   "peerDependencies": {
     "react": "^19.2.4",
     "scheduler": "*",
-    "effect": "^4.0.0-beta.7"
+    "effect": "^4.0.0-beta.70"
   },
   "devDependencies": {
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^16.3.0",
-    "@types/react": "^19.2.2",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.2",
     "@types/scheduler": "^0.26.0",
-    "jsdom": "^27.1.0",
-    "react": "19.2.3",
-    "react-dom": "19.2.3",
-    "react-error-boundary": "^6.0.0",
+    "jsdom": "^29.1.1",
+    "react": "19.2.6",
+    "react-dom": "19.2.6",
+    "react-error-boundary": "^6.1.1",
     "scheduler": "^0.27.0",
-    "effect": "^4.0.0-beta.7"
+    "effect": "^4.0.0-beta.70"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json && pnpm babel",

package/src/Hooks.ts

@@ -1,5 +1,23 @@
 /**
- * @since 1.0.0
+ * React hooks for reading, writing, mounting, refreshing, and subscribing to
+ * Effect atoms from the registry provided by `RegistryContext`.
+ *
+ * **Common tasks**
+ *
+ * - Read atom values in React components with {@link useAtomValue}
+ * - Read and write writable atoms with {@link useAtom}
+ * - Write without subscribing to the value with {@link useAtomSet}
+ * - Seed registry-local initial values with {@link useAtomInitialValues}
+ * - Integrate `AsyncResult` atoms with React Suspense through {@link useAtomSuspense}
+ * - Subscribe to atom changes or derive stable `AtomRef` properties
+ *
+ * **Gotchas**
+ *
+ * - Hooks use the current `RegistryContext`, so each provider has an independent atom registry
+ * - Writable atoms are mounted by the write-oriented hooks before updates are sent
+ * - Suspense support throws promises for initial or waiting `AsyncResult` values and defects for failures unless `includeFailure` is enabled
+ *
+ * @since 4.0.0
  */
 "use client"
 
@@ -55,8 +73,15 @@ function useStore<A>(registry: AtomRegistry.AtomRegistry, atom: Atom.Atom<A>): A
 const initialValuesSet = new WeakMap<AtomRegistry.AtomRegistry, WeakSet<Atom.Atom<any>>>()
 
 /**
- * @since 1.0.0
+ * Seeds initial atom values in the current React atom registry.
+ *
+ * **Details**
+ *
+ * Each atom is initialized at most once for a given registry, so subsequent
+ * renders do not overwrite values that have already been established.
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomInitialValues = (initialValues: Iterable<readonly [Atom.Atom<any>, any]>): void => {
   const registry = React.useContext(RegistryContext)
@@ -74,18 +99,27 @@ export const useAtomInitialValues = (initialValues: Iterable<readonly [Atom.Atom
 }
 
 /**
- * @since 1.0.0
+ * Subscribes to an atom in the current React registry and returns its current
+ * value, optionally mapped through a selector.
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomValue: {
   /**
-   * @since 1.0.0
+   * Subscribes to an atom in the current React registry and returns its current
+   * value, optionally mapped through a selector.
+   *
    * @category hooks
+   * @since 4.0.0
    */
   <A>(atom: Atom.Atom<A>): A
   /**
-   * @since 1.0.0
+   * Subscribes to an atom in the current React registry and returns its current
+   * value, optionally mapped through a selector.
+   *
    * @category hooks
+   * @since 4.0.0
    */
   <A, B>(atom: Atom.Atom<A>, f: (_: A) => B): B
 } = <A>(atom: Atom.Atom<A>, f?: (_: A) => A): A => {
@@ -137,8 +171,11 @@ const flattenExit = <A, E>(exit: Exit.Exit<A, E>): A => {
 }
 
 /**
- * @since 1.0.0
+ * Mounts an atom in the current React registry for the lifetime of the
+ * component.
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomMount = <A>(atom: Atom.Atom<A>): void => {
   const registry = React.useContext(RegistryContext)
@@ -146,8 +183,10 @@ export const useAtomMount = <A>(atom: Atom.Atom<A>): void => {
 }
 
 /**
- * @since 1.0.0
+ * Mounts a writable atom and returns a setter without subscribing to its value.
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomSet = <
   R,
@@ -172,8 +211,11 @@ export const useAtomSet = <
 }
 
 /**
- * @since 1.0.0
+ * Mounts an atom and returns a callback that refreshes it in the current React
+ * registry.
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomRefresh = <A>(atom: Atom.Atom<A>): () => void => {
   const registry = React.useContext(RegistryContext)
@@ -184,8 +226,11 @@ export const useAtomRefresh = <A>(atom: Atom.Atom<A>): () => void => {
 }
 
 /**
- * @since 1.0.0
+ * Subscribes to a writable atom and returns its current value together with a
+ * setter for updating it.
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtom = <R, W, const Mode extends "value" | "promise" | "promiseExit" = never>(
   atom: Atom.Writable<R, W>,
@@ -251,8 +296,11 @@ function atomResultOrSuspend<A, E>(
 }
 
 /**
- * @since 1.0.0
+ * Reads an `AsyncResult` atom through React Suspense, suspending while the
+ * result is initial or configured as waiting.
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomSuspense = <A, E, const IncludeFailure extends boolean = false>(
   atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>,
@@ -270,8 +318,11 @@ export const useAtomSuspense = <A, E, const IncludeFailure extends boolean = fal
 }
 
 /**
- * @since 1.0.0
+ * Subscribes a callback to an atom in the current React registry for the
+ * component lifetime.
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomSubscribe = <A>(
   atom: Atom.Atom<A>,
@@ -286,8 +337,10 @@ export const useAtomSubscribe = <A>(
 }
 
 /**
- * @since 1.0.0
+ * Subscribes to an atom ref and returns its latest value.
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomRef = <A>(ref: AtomRef.ReadonlyRef<A>): A => {
   const [, setValue] = React.useState(ref.value)
@@ -296,15 +349,20 @@ export const useAtomRef = <A>(ref: AtomRef.ReadonlyRef<A>): A => {
 }
 
 /**
- * @since 1.0.0
+ * Returns a memoized atom ref for a property of another atom ref.
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomRefProp = <A, K extends keyof A>(ref: AtomRef.AtomRef<A>, prop: K): AtomRef.AtomRef<A[K]> =>
   React.useMemo(() => ref.prop(prop), [ref, prop])
 
 /**
- * @since 1.0.0
+ * Subscribes to a property ref derived from an atom ref and returns its current
+ * value.
+ *
  * @category hooks
+ * @since 4.0.0
  */
 export const useAtomRefPropValue = <A, K extends keyof A>(ref: AtomRef.AtomRef<A>, prop: K): A[K] =>
   useAtomRef(useAtomRefProp(ref, prop))

package/src/ReactHydration.ts

@@ -1,5 +1,26 @@
 /**
- * @since 1.0.0
+ * React helpers for hydrating Atom registry state that was serialized on the
+ * server or produced by a previous render. This module exposes
+ * {@link HydrationBoundary}, a client component that receives dehydrated Atom
+ * values and applies them to the nearest {@link RegistryContext} before
+ * rendering children when it is safe to do so.
+ *
+ * **Common use cases**
+ *
+ * - Reusing Atom values that were collected during server rendering
+ * - Restoring client-side Atom state around a routed subtree
+ * - Keeping Atom-backed React trees consistent during hydration and transitions
+ *
+ * **React gotchas**
+ *
+ * - New Atom values can be hydrated during render so children see them
+ *   immediately.
+ * - Existing Atom values are queued until after commit to avoid updating the
+ *   current UI with transition data that might later be discarded.
+ * - Hydration is idempotent, so repeated or older dehydrated values are safe to
+ *   pass through the boundary.
+ *
+ * @since 4.0.0
  */
 "use client"
 import * as Hydration from "effect/unstable/reactivity/Hydration"
@@ -7,8 +28,11 @@ import * as React from "react"
 import { RegistryContext } from "./RegistryContext.ts"
 
 /**
- * @since 1.0.0
+ * Props for a boundary that applies dehydrated Atom values to the nearest
+ * {@link RegistryContext} while rendering its children.
+ *
  * @category components
+ * @since 4.0.0
  */
 export interface HydrationBoundaryProps {
   state?: Iterable<Hydration.DehydratedAtom>
@@ -16,8 +40,17 @@ export interface HydrationBoundaryProps {
 }
 
 /**
- * @since 1.0.0
+ * Hydrates dehydrated Atom values into the current Atom registry for a React
+ * subtree.
+ *
+ * **Details**
+ *
+ * New Atom values are hydrated during render so descendants can read them
+ * immediately, while values for existing Atoms are deferred until after commit
+ * so transition data does not update the current UI before React accepts it.
+ *
  * @category components
+ * @since 4.0.0
  */
 export const HydrationBoundary: React.FC<HydrationBoundaryProps> = ({
   children,

package/src/RegistryContext.ts

@@ -1,5 +1,27 @@
 /**
- * @since 1.0.0
+ * The `RegistryContext` module provides the React context used by Effect Atom
+ * hooks to share an `AtomRegistry` across a component tree. The registry owns
+ * atom state, scheduling, and idle cleanup, so components that read or write
+ * atoms can coordinate through the same runtime instead of each creating an
+ * isolated registry.
+ *
+ * **Common tasks**
+ *
+ * - Use {@link RegistryProvider} to scope atom state to a React subtree
+ * - Seed atoms for tests, stories, or server-provided data with `initialValues`
+ * - Override scheduling or idle timing for custom rendering environments
+ * - Read {@link RegistryContext} when integrating lower-level atom APIs
+ *
+ * **Gotchas**
+ *
+ * - This is a client module because it depends on React runtime hooks and the
+ *   scheduler package
+ * - A provider keeps the registry stable across renders and disposes it shortly
+ *   after unmount, allowing React remounts to reuse the same registry
+ * - Overriding `scheduleTask` changes when atom work is flushed, so it should
+ *   return a cancellation function compatible with React unmounts
+ *
+ * @since 4.0.0
  */
 "use client"
 
@@ -9,8 +31,11 @@ import * as React from "react"
 import * as Scheduler from "scheduler"
 
 /**
- * @since 1.0.0
+ * Schedules Atom registry work with React's scheduler at low priority and
+ * returns a cancellation function for the scheduled task.
+ *
  * @category context
+ * @since 4.0.0
  */
 export function scheduleTask(f: () => void): () => void {
   const node = Scheduler.unstable_scheduleCallback(Scheduler.unstable_LowPriority, f)
@@ -18,8 +43,12 @@ export function scheduleTask(f: () => void): () => void {
 }
 
 /**
- * @since 1.0.0
+ * React context that supplies the `AtomRegistry` used by Atom hooks and
+ * hydration helpers, defaulting to a standalone registry when no provider is
+ * present.
+ *
  * @category context
+ * @since 4.0.0
  */
 export const RegistryContext = React.createContext<AtomRegistry.AtomRegistry>(AtomRegistry.make({
   scheduleTask,
@@ -27,8 +56,11 @@ export const RegistryContext = React.createContext<AtomRegistry.AtomRegistry>(At
 }))
 
 /**
- * @since 1.0.0
+ * Provides a stable `AtomRegistry` to a React subtree, optionally seeding
+ * initial atom values and overriding registry scheduling or idle settings.
+ *
  * @category context
+ * @since 4.0.0
  */
 export const RegistryProvider = (options: {
   readonly children?: React.ReactNode | undefined