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

package/dist/Hooks.d.ts

@@ -5,10 +5,15 @@ import type * as AtomRef from "effect/unstable/reactivity/AtomRef";
 /**
  * Seeds initial atom values in the current React atom registry.
  *
- * **Details**
+ * **When to use**
+ *
+ * Use to seed atom values from a React component after the current registry
+ * already exists.
+ *
+ * **Gotchas**
  *
- * Each atom is initialized at most once for a given registry, so subsequent
- * renders do not overwrite values that have already been established.
+ * Each atom is initialized at most once for a given registry by this hook, so
+ * later calls for the same atom in that registry are ignored.
  *
  * @category hooks
  * @since 4.0.0
@@ -18,6 +23,19 @@ export declare const useAtomInitialValues: (initialValues: Iterable<readonly [At
  * Subscribes to an atom in the current React registry and returns its current
  * value, optionally mapped through a selector.
  *
+ * **When to use**
+ *
+ * Use when a React component needs to render from an atom value without also
+ * returning a setter.
+ *
+ * **Details**
+ *
+ * When a selector is provided, the hook maps the atom before subscribing so the
+ * component reads the selected value from the current `RegistryContext`.
+ *
+ * @see {@link useAtom} for reading and updating a writable atom from one component
+ * @see {@link useAtomRef} for reading an `AtomRef` directly
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -26,6 +44,19 @@ export declare const useAtomValue: {
      * Subscribes to an atom in the current React registry and returns its current
      * value, optionally mapped through a selector.
      *
+     * **When to use**
+     *
+     * Use when a React component needs to render from an atom value without also
+     * returning a setter.
+     *
+     * **Details**
+     *
+     * When a selector is provided, the hook maps the atom before subscribing so the
+     * component reads the selected value from the current `RegistryContext`.
+     *
+     * @see {@link useAtom} for reading and updating a writable atom from one component
+     * @see {@link useAtomRef} for reading an `AtomRef` directly
+     *
      * @category hooks
      * @since 4.0.0
      */
@@ -34,6 +65,19 @@ export declare const useAtomValue: {
      * Subscribes to an atom in the current React registry and returns its current
      * value, optionally mapped through a selector.
      *
+     * **When to use**
+     *
+     * Use when a React component needs to render from an atom value without also
+     * returning a setter.
+     *
+     * **Details**
+     *
+     * When a selector is provided, the hook maps the atom before subscribing so the
+     * component reads the selected value from the current `RegistryContext`.
+     *
+     * @see {@link useAtom} for reading and updating a writable atom from one component
+     * @see {@link useAtomRef} for reading an `AtomRef` directly
+     *
      * @category hooks
      * @since 4.0.0
      */
@@ -43,6 +87,20 @@ export declare const useAtomValue: {
  * Mounts an atom in the current React registry for the lifetime of the
  * component.
  *
+ * **When to use**
+ *
+ * Use to keep an atom mounted from a React component without reading, writing,
+ * or refreshing it.
+ *
+ * **Details**
+ *
+ * The hook uses the current `RegistryContext` and releases the mount through
+ * React effect cleanup when the component unmounts or when the registry or atom
+ * dependency changes.
+ *
+ * @see {@link useAtomSet} for mounting a writable atom while returning a setter
+ * @see {@link useAtomRefresh} for mounting an atom while returning a refresh callback
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -50,6 +108,19 @@ export declare const useAtomMount: <A>(atom: Atom.Atom<A>) => void;
 /**
  * Mounts a writable atom and returns a setter without subscribing to its value.
  *
+ * **When to use**
+ *
+ * Use when a React component needs to update a writable atom without rendering
+ * from that atom's value.
+ *
+ * **Details**
+ *
+ * The hook mounts the atom and returns a setter. In value mode the setter
+ * accepts a write value or updater function; for `AsyncResult` atoms, `promise`
+ * and `promiseExit` modes return a promise for the success value or full `Exit`.
+ *
+ * @see {@link useAtom} for reading and updating the same writable atom
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -60,6 +131,18 @@ export declare const useAtomSet: <R, W, Mode extends "value" | "promise" | "prom
  * Mounts an atom and returns a callback that refreshes it in the current React
  * registry.
  *
+ * **When to use**
+ *
+ * Use to expose a React callback that requests a refresh for an atom without
+ * reading or writing its value.
+ *
+ * **Details**
+ *
+ * The hook uses the current `RegistryContext`, mounts the atom for the
+ * component lifetime, and returns a callback that calls `registry.refresh`.
+ *
+ * @see {@link useAtomMount} for mounting an atom without returning a refresh callback
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -68,6 +151,14 @@ export declare const useAtomRefresh: <A>(atom: Atom.Atom<A>) => () => void;
  * Subscribes to a writable atom and returns its current value together with a
  * setter for updating it.
  *
+ * **When to use**
+ *
+ * Use when a React component needs both to render the current value of a
+ * writable atom and update it from the same component.
+ *
+ * @see {@link useAtomValue} for subscribing to an atom without a setter
+ * @see {@link useAtomSet} for updating a writable atom without subscribing to its value
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -78,6 +169,23 @@ export declare const useAtom: <R, W, const Mode extends "value" | "promise" | "p
  * Reads an `AsyncResult` atom through React Suspense, suspending while the
  * result is initial or configured as waiting.
  *
+ * **When to use**
+ *
+ * Use when a React component should render only after an `AsyncResult` atom has
+ * left its initial state, with loading delegated to a Suspense boundary.
+ *
+ * **Details**
+ *
+ * `suspendOnWaiting` defaults to `false`. When `includeFailure` is `true`, a
+ * failure result is returned instead of being thrown.
+ *
+ * **Gotchas**
+ *
+ * Without `includeFailure`, failure results are thrown with
+ * `Cause.squash(result.cause)`, so callers need an error boundary for failures.
+ *
+ * @see {@link useAtomValue} for reading the raw `AsyncResult` value without Suspense
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -89,6 +197,19 @@ export declare const useAtomSuspense: <A, E, const IncludeFailure extends boolea
  * Subscribes a callback to an atom in the current React registry for the
  * component lifetime.
  *
+ * **When to use**
+ *
+ * Use when a React component needs to run a callback for atom changes without
+ * reading the atom value during render.
+ *
+ * **Details**
+ *
+ * The subscription is installed in a React effect and cleaned up on unmount or
+ * dependency change. When `options.immediate` is enabled, the callback receives
+ * the current value when the effect subscribes.
+ *
+ * @see {@link useAtomValue} for reading an atom value during render instead of running a callback
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -98,6 +219,19 @@ export declare const useAtomSubscribe: <A>(atom: Atom.Atom<A>, f: (_: A) => void
 /**
  * Subscribes to an atom ref and returns its latest value.
  *
+ * **When to use**
+ *
+ * Use when a React component should render from an `AtomRef.ReadonlyRef`
+ * directly instead of reading an atom through the current registry.
+ *
+ * **Details**
+ *
+ * The hook subscribes with `ref.subscribe`, triggers re-renders through React
+ * state, and returns the current `ref.value`.
+ *
+ * @see {@link useAtomValue} for reading an `Atom` from the current registry
+ * @see {@link useAtomRefPropValue} for reading a property ref value
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -105,6 +239,19 @@ export declare const useAtomRef: <A>(ref: AtomRef.ReadonlyRef<A>) => A;
 /**
  * Returns a memoized atom ref for a property of another atom ref.
  *
+ * **When to use**
+ *
+ * Use to derive an `AtomRef` for one property of an object-shaped atom ref.
+ *
+ * **Details**
+ *
+ * The hook memoizes `ref.prop(prop)` for the `[ref, prop]` dependency pair and
+ * returns the property ref so callers can read, set, update, or subscribe to
+ * that nested property.
+ *
+ * @see {@link useAtomRef} for subscribing to an atom ref value
+ * @see {@link useAtomRefPropValue} for subscribing directly to a property value
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -113,6 +260,20 @@ export declare const useAtomRefProp: <A, K extends keyof A>(ref: AtomRef.AtomRef
  * Subscribes to a property ref derived from an atom ref and returns its current
  * value.
  *
+ * **When to use**
+ *
+ * Use when a React component needs only the current value of one property from
+ * an object-shaped `AtomRef`.
+ *
+ * **Details**
+ *
+ * The hook composes `useAtomRefProp(ref, prop)` with `useAtomRef`, so the
+ * property ref is memoized for the `[ref, prop]` pair and then subscribed
+ * through `ref.subscribe`.
+ *
+ * @see {@link useAtomRefProp} for returning the property ref directly
+ * @see {@link useAtomRef} for subscribing to a whole atom ref value
+ *
  * @category hooks
  * @since 4.0.0
  */

package/dist/Hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Hooks.d.ts","sourceRoot":"","sources":["../src/Hooks.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Hooks.d.ts","sourceRoot":"","sources":["../src/Hooks.ts"],"names":[],"mappings":"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"}

package/dist/Hooks.js

@@ -61,10 +61,15 @@ const initialValuesSet = /*#__PURE__*/new WeakMap();
 /**
  * Seeds initial atom values in the current React atom registry.
  *
- * **Details**
+ * **When to use**
+ *
+ * Use to seed atom values from a React component after the current registry
+ * already exists.
+ *
+ * **Gotchas**
  *
- * Each atom is initialized at most once for a given registry, so subsequent
- * renders do not overwrite values that have already been established.
+ * Each atom is initialized at most once for a given registry by this hook, so
+ * later calls for the same atom in that registry are ignored.
  *
  * @category hooks
  * @since 4.0.0
@@ -87,6 +92,19 @@ export const useAtomInitialValues = initialValues => {
  * Subscribes to an atom in the current React registry and returns its current
  * value, optionally mapped through a selector.
  *
+ * **When to use**
+ *
+ * Use when a React component needs to render from an atom value without also
+ * returning a setter.
+ *
+ * **Details**
+ *
+ * When a selector is provided, the hook maps the atom before subscribing so the
+ * component reads the selected value from the current `RegistryContext`.
+ *
+ * @see {@link useAtom} for reading and updating a writable atom from one component
+ * @see {@link useAtomRef} for reading an `AtomRef` directly
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -123,6 +141,20 @@ const flattenExit = exit => {
  * Mounts an atom in the current React registry for the lifetime of the
  * component.
  *
+ * **When to use**
+ *
+ * Use to keep an atom mounted from a React component without reading, writing,
+ * or refreshing it.
+ *
+ * **Details**
+ *
+ * The hook uses the current `RegistryContext` and releases the mount through
+ * React effect cleanup when the component unmounts or when the registry or atom
+ * dependency changes.
+ *
+ * @see {@link useAtomSet} for mounting a writable atom while returning a setter
+ * @see {@link useAtomRefresh} for mounting an atom while returning a refresh callback
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -133,6 +165,19 @@ export const useAtomMount = atom => {
 /**
  * Mounts a writable atom and returns a setter without subscribing to its value.
  *
+ * **When to use**
+ *
+ * Use when a React component needs to update a writable atom without rendering
+ * from that atom's value.
+ *
+ * **Details**
+ *
+ * The hook mounts the atom and returns a setter. In value mode the setter
+ * accepts a write value or updater function; for `AsyncResult` atoms, `promise`
+ * and `promiseExit` modes return a promise for the success value or full `Exit`.
+ *
+ * @see {@link useAtom} for reading and updating the same writable atom
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -145,6 +190,18 @@ export const useAtomSet = (atom, options) => {
  * Mounts an atom and returns a callback that refreshes it in the current React
  * registry.
  *
+ * **When to use**
+ *
+ * Use to expose a React callback that requests a refresh for an atom without
+ * reading or writing its value.
+ *
+ * **Details**
+ *
+ * The hook uses the current `RegistryContext`, mounts the atom for the
+ * component lifetime, and returns a callback that calls `registry.refresh`.
+ *
+ * @see {@link useAtomMount} for mounting an atom without returning a refresh callback
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -159,6 +216,14 @@ export const useAtomRefresh = atom => {
  * Subscribes to a writable atom and returns its current value together with a
  * setter for updating it.
  *
+ * **When to use**
+ *
+ * Use when a React component needs both to render the current value of a
+ * writable atom and update it from the same component.
+ *
+ * @see {@link useAtomValue} for subscribing to an atom without a setter
+ * @see {@link useAtomSet} for updating a writable atom without subscribing to its value
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -200,6 +265,23 @@ function atomResultOrSuspend(registry, atom, suspendOnWaiting) {
  * Reads an `AsyncResult` atom through React Suspense, suspending while the
  * result is initial or configured as waiting.
  *
+ * **When to use**
+ *
+ * Use when a React component should render only after an `AsyncResult` atom has
+ * left its initial state, with loading delegated to a Suspense boundary.
+ *
+ * **Details**
+ *
+ * `suspendOnWaiting` defaults to `false`. When `includeFailure` is `true`, a
+ * failure result is returned instead of being thrown.
+ *
+ * **Gotchas**
+ *
+ * Without `includeFailure`, failure results are thrown with
+ * `Cause.squash(result.cause)`, so callers need an error boundary for failures.
+ *
+ * @see {@link useAtomValue} for reading the raw `AsyncResult` value without Suspense
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -215,6 +297,19 @@ export const useAtomSuspense = (atom, options) => {
  * Subscribes a callback to an atom in the current React registry for the
  * component lifetime.
  *
+ * **When to use**
+ *
+ * Use when a React component needs to run a callback for atom changes without
+ * reading the atom value during render.
+ *
+ * **Details**
+ *
+ * The subscription is installed in a React effect and cleaned up on unmount or
+ * dependency change. When `options.immediate` is enabled, the callback receives
+ * the current value when the effect subscribes.
+ *
+ * @see {@link useAtomValue} for reading an atom value during render instead of running a callback
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -225,6 +320,19 @@ export const useAtomSubscribe = (atom, f, options) => {
 /**
  * Subscribes to an atom ref and returns its latest value.
  *
+ * **When to use**
+ *
+ * Use when a React component should render from an `AtomRef.ReadonlyRef`
+ * directly instead of reading an atom through the current registry.
+ *
+ * **Details**
+ *
+ * The hook subscribes with `ref.subscribe`, triggers re-renders through React
+ * state, and returns the current `ref.value`.
+ *
+ * @see {@link useAtomValue} for reading an `Atom` from the current registry
+ * @see {@link useAtomRefPropValue} for reading a property ref value
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -236,6 +344,19 @@ export const useAtomRef = ref => {
 /**
  * Returns a memoized atom ref for a property of another atom ref.
  *
+ * **When to use**
+ *
+ * Use to derive an `AtomRef` for one property of an object-shaped atom ref.
+ *
+ * **Details**
+ *
+ * The hook memoizes `ref.prop(prop)` for the `[ref, prop]` dependency pair and
+ * returns the property ref so callers can read, set, update, or subscribe to
+ * that nested property.
+ *
+ * @see {@link useAtomRef} for subscribing to an atom ref value
+ * @see {@link useAtomRefPropValue} for subscribing directly to a property value
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -244,6 +365,20 @@ export const useAtomRefProp = (ref, prop) => React.useMemo(() => ref.prop(prop),
  * Subscribes to a property ref derived from an atom ref and returns its current
  * value.
  *
+ * **When to use**
+ *
+ * Use when a React component needs only the current value of one property from
+ * an object-shaped `AtomRef`.
+ *
+ * **Details**
+ *
+ * The hook composes `useAtomRefProp(ref, prop)` with `useAtomRef`, so the
+ * property ref is memoized for the `[ref, prop]` pair and then subscribed
+ * through `ref.subscribe`.
+ *
+ * @see {@link useAtomRefProp} for returning the property ref directly
+ * @see {@link useAtomRef} for subscribing to a whole atom ref value
+ *
  * @category hooks
  * @since 4.0.0
  */

package/dist/Hooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"Hooks.js","names":["Cause","Effect","Exit","Atom","AtomRegistry","React","RegistryContext","storeRegistry","WeakMap","makeStore","registry","atom","stores","get","undefined","set","store","newStore","subscribe","f","snapshot","getServerSnapshot","getServerValue","useStore","useSyncExternalStore","initialValuesSet","useAtomInitialValues","initialValues","useContext","WeakSet","value","has","add","ensureNode","setValue","useAtomValue","atomB","useMemo","map","mountAtom","useEffect","mount","setAtom","options","mode","useCallback","promise","runPromiseExit","getResult","suspendOnWaiting","then","flattenExit","exit","isSuccess","squash","cause","useAtomMount","useAtomSet","useAtomRefresh","refresh","useAtom","atomPromiseMap","Map","default","atomToPromise","Promise","resolve","dispose","result","_tag","waiting","setTimeout","delete","atomResultOrSuspend","useAtomSuspense","includeFailure","useAtomSubscribe","immediate","useAtomRef","ref","useState","useAtomRefProp","prop","useAtomRefPropValue"],"sources":["../src/Hooks.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"Hooks.js","names":["Cause","Effect","Exit","Atom","AtomRegistry","React","RegistryContext","storeRegistry","WeakMap","makeStore","registry","atom","stores","get","undefined","set","store","newStore","subscribe","f","snapshot","getServerSnapshot","getServerValue","useStore","useSyncExternalStore","initialValuesSet","useAtomInitialValues","initialValues","useContext","WeakSet","value","has","add","ensureNode","setValue","useAtomValue","atomB","useMemo","map","mountAtom","useEffect","mount","setAtom","options","mode","useCallback","promise","runPromiseExit","getResult","suspendOnWaiting","then","flattenExit","exit","isSuccess","squash","cause","useAtomMount","useAtomSet","useAtomRefresh","refresh","useAtom","atomPromiseMap","Map","default","atomToPromise","Promise","resolve","dispose","result","_tag","waiting","setTimeout","delete","atomResultOrSuspend","useAtomSuspense","includeFailure","useAtomSubscribe","immediate","useAtomRef","ref","useState","useAtomRefProp","prop","useAtomRefPropValue"],"sources":["../src/Hooks.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/ReactHydration.d.ts

@@ -15,12 +15,20 @@ export interface HydrationBoundaryProps {
  * Hydrates dehydrated Atom values into the current Atom registry for a React
  * subtree.
  *
+ * **When to use**
+ *
+ * Use to apply dehydrated Atom state to a React subtree that reads from the
+ * nearest `RegistryContext`.
+ *
  * **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.
  *
+ * @see {@link Hydration.dehydrate} for producing dehydrated Atom state
+ * @see {@link Hydration.hydrate} for lower-level non-React hydration
+ *
  * @category components
  * @since 4.0.0
  */

package/dist/ReactHydration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ReactHydration.d.ts","sourceRoot":"","sources":["../src/ReactHydration.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,SAAS,MAAM,sCAAsC,CAAA;AACjE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,QAAQ,CAAC,SAAS,CAAC,cAAc,CAAC,CAAA;IAC1C,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,EAAE,CAAC,sBAAsB,CA6D9D,CAAA"}
+{"version":3,"file":"ReactHydration.d.ts","sourceRoot":"","sources":["../src/ReactHydration.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,SAAS,MAAM,sCAAsC,CAAA;AACjE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,QAAQ,CAAC,SAAS,CAAC,cAAc,CAAC,CAAA;IAC1C,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,EAAE,CAAC,sBAAsB,CA6D9D,CAAA"}

package/dist/ReactHydration.js

@@ -31,12 +31,20 @@ import { RegistryContext } from "./RegistryContext.js";
  * Hydrates dehydrated Atom values into the current Atom registry for a React
  * subtree.
  *
+ * **When to use**
+ *
+ * Use to apply dehydrated Atom state to a React subtree that reads from the
+ * nearest `RegistryContext`.
+ *
  * **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.
  *
+ * @see {@link Hydration.dehydrate} for producing dehydrated Atom state
+ * @see {@link Hydration.hydrate} for lower-level non-React hydration
+ *
  * @category components
  * @since 4.0.0
  */

package/dist/ReactHydration.js.map

@@ -1 +1 @@
-{"version":3,"file":"ReactHydration.js","names":["Hydration","React","RegistryContext","HydrationBoundary","children","state","registry","useContext","hydrationQueue","useMemo","dehydratedAtoms","Array","from","nodes","getNodes","newDehydratedAtoms","existingDehydratedAtoms","dehydratedAtom","existingNode","get","key","push","length","hydrate","undefined","useEffect","createElement","Fragment"],"sources":["../src/ReactHydration.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,YAAY;;AACZ,OAAO,KAAKA,SAAS,MAAM,sCAAsC;AACjE,OAAO,KAAKC,KAAK,MAAM,OAAO;AAC9B,SAASC,eAAe,QAAQ,sBAAsB;AActD;;;;;;;;;;;;;AAaA,OAAO,MAAMC,iBAAiB,GAAqCA,CAAC;EAClEC,QAAQ;EACRC;AAAK,CACN,KAAI;EACH,MAAMC,QAAQ,GAAGL,KAAK,CAACM,UAAU,CAACL,eAAe,CAAC;EAElD;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,MAAMM,cAAc,GAAqDP,KAAK,CAACQ,OAAO,CAAC,MAAK;IAC1F,IAAIJ,KAAK,EAAE;MACT,MAAMK,eAAe,GAAGC,KAAK,CAACC,IAAI,CAACP,KAAK,CAAyC;MACjF,MAAMQ,KAAK,GAAGP,QAAQ,CAACQ,QAAQ,EAAE;MAEjC,MAAMC,kBAAkB,GAAyC,EAAE;MACnE,MAAMC,uBAAuB,GAAyC,EAAE;MAExE,KAAK,MAAMC,cAAc,IAAIP,eAAe,EAAE;QAC5C,MAAMQ,YAAY,GAAGL,KAAK,CAACM,GAAG,CAACF,cAAc,CAACG,GAAG,CAAC;QAElD,IAAI,CAACF,YAAY,EAAE;UACjB;UACAH,kBAAkB,CAACM,IAAI,CAACJ,cAAc,CAAC;QACzC,CAAC,MAAM;UACL;UACAD,uBAAuB,CAACK,IAAI,CAACJ,cAAc,CAAC;QAC9C;MACF;MAEA,IAAIF,kBAAkB,CAACO,MAAM,GAAG,CAAC,EAAE;QACjC;QACA;QACAtB,SAAS,CAACuB,OAAO,CAACjB,QAAQ,EAAES,kBAAkB,CAAC;MACjD;MAEA,IAAIC,uBAAuB,CAACM,MAAM,GAAG,CAAC,EAAE;QACtC,OAAON,uBAAuB;MAChC;IACF;IACA,OAAOQ,SAAS;EAClB,CAAC,EAAE,CAAClB,QAAQ,EAAED,KAAK,CAAC,CAAC;EAErBJ,KAAK,CAACwB,SAAS,CAAC,MAAK;IACnB,IAAIjB,cAAc,EAAE;MAClBR,SAAS,CAACuB,OAAO,CAACjB,QAAQ,EAAEE,cAAc,CAAC;IAC7C;EACF,CAAC,EAAE,CAACF,QAAQ,EAAEE,cAAc,CAAC,CAAC;EAE9B,OAAOP,KAAK,CAACyB,aAAa,CAACzB,KAAK,CAAC0B,QAAQ,EAAE,EAAE,EAAEvB,QAAQ,CAAC;AAC1D,CAAC","ignoreList":[]}
+{"version":3,"file":"ReactHydration.js","names":["Hydration","React","RegistryContext","HydrationBoundary","children","state","registry","useContext","hydrationQueue","useMemo","dehydratedAtoms","Array","from","nodes","getNodes","newDehydratedAtoms","existingDehydratedAtoms","dehydratedAtom","existingNode","get","key","push","length","hydrate","undefined","useEffect","createElement","Fragment"],"sources":["../src/ReactHydration.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,YAAY;;AACZ,OAAO,KAAKA,SAAS,MAAM,sCAAsC;AACjE,OAAO,KAAKC,KAAK,MAAM,OAAO;AAC9B,SAASC,eAAe,QAAQ,sBAAsB;AActD;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAO,MAAMC,iBAAiB,GAAqCA,CAAC;EAClEC,QAAQ;EACRC;AAAK,CACN,KAAI;EACH,MAAMC,QAAQ,GAAGL,KAAK,CAACM,UAAU,CAACL,eAAe,CAAC;EAElD;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,MAAMM,cAAc,GAAqDP,KAAK,CAACQ,OAAO,CAAC,MAAK;IAC1F,IAAIJ,KAAK,EAAE;MACT,MAAMK,eAAe,GAAGC,KAAK,CAACC,IAAI,CAACP,KAAK,CAAyC;MACjF,MAAMQ,KAAK,GAAGP,QAAQ,CAACQ,QAAQ,EAAE;MAEjC,MAAMC,kBAAkB,GAAyC,EAAE;MACnE,MAAMC,uBAAuB,GAAyC,EAAE;MAExE,KAAK,MAAMC,cAAc,IAAIP,eAAe,EAAE;QAC5C,MAAMQ,YAAY,GAAGL,KAAK,CAACM,GAAG,CAACF,cAAc,CAACG,GAAG,CAAC;QAElD,IAAI,CAACF,YAAY,EAAE;UACjB;UACAH,kBAAkB,CAACM,IAAI,CAACJ,cAAc,CAAC;QACzC,CAAC,MAAM;UACL;UACAD,uBAAuB,CAACK,IAAI,CAACJ,cAAc,CAAC;QAC9C;MACF;MAEA,IAAIF,kBAAkB,CAACO,MAAM,GAAG,CAAC,EAAE;QACjC;QACA;QACAtB,SAAS,CAACuB,OAAO,CAACjB,QAAQ,EAAES,kBAAkB,CAAC;MACjD;MAEA,IAAIC,uBAAuB,CAACM,MAAM,GAAG,CAAC,EAAE;QACtC,OAAON,uBAAuB;MAChC;IACF;IACA,OAAOQ,SAAS;EAClB,CAAC,EAAE,CAAClB,QAAQ,EAAED,KAAK,CAAC,CAAC;EAErBJ,KAAK,CAACwB,SAAS,CAAC,MAAK;IACnB,IAAIjB,cAAc,EAAE;MAClBR,SAAS,CAACuB,OAAO,CAACjB,QAAQ,EAAEE,cAAc,CAAC;IAC7C;EACF,CAAC,EAAE,CAACF,QAAQ,EAAEE,cAAc,CAAC,CAAC;EAE9B,OAAOP,KAAK,CAACyB,aAAa,CAACzB,KAAK,CAAC0B,QAAQ,EAAE,EAAE,EAAEvB,QAAQ,CAAC;AAC1D,CAAC","ignoreList":[]}

package/dist/RegistryContext.d.ts

@@ -14,6 +14,14 @@ export declare function scheduleTask(f: () => void): () => void;
  * hydration helpers, defaulting to a standalone registry when no provider is
  * present.
  *
+ * **When to use**
+ *
+ * Use to supply an existing `AtomRegistry` through React context when hooks or
+ * hydration helpers need to share registry state that is managed outside
+ * `RegistryProvider`.
+ *
+ * @see {@link RegistryProvider} for creating and providing a registry for a React subtree
+ *
  * @category context
  * @since 4.0.0
  */
@@ -22,6 +30,25 @@ export declare const RegistryContext: React.Context<AtomRegistry.AtomRegistry>;
  * Provides a stable `AtomRegistry` to a React subtree, optionally seeding
  * initial atom values and overriding registry scheduling or idle settings.
  *
+ * **When to use**
+ *
+ * Use to scope atom state, scheduling, and idle cleanup to a React subtree.
+ *
+ * **Details**
+ *
+ * The provider creates one `AtomRegistry` with `AtomRegistry.make`, passes it
+ * through `RegistryContext.Provider`, and forwards `initialValues`,
+ * `scheduleTask`, `timeoutResolution`, and `defaultIdleTTL` only when that
+ * registry is created.
+ *
+ * **Gotchas**
+ *
+ * Option changes after the first render do not rebuild the registry. When the
+ * provider unmounts, registry disposal is delayed briefly and canceled if the
+ * provider remounts before the timeout fires.
+ *
+ * @see {@link RegistryContext} for the React context supplied by this provider
+ *
  * @category context
  * @since 4.0.0
  */

package/dist/RegistryContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RegistryContext.d.ts","sourceRoot":"","sources":["../src/RegistryContext.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,KAAK,IAAI,MAAM,iCAAiC,CAAA;AAC5D,OAAO,KAAK,YAAY,MAAM,yCAAyC,CAAA;AACvE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAGtD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,0CAGzB,CAAA;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,SAAS,CAAA;IAC/C,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,SAAS,CAAA;IAC7E,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC,GAAG,SAAS,CAAA;IACnE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC7C,mFA2BA,CAAA"}
+{"version":3,"file":"RegistryContext.d.ts","sourceRoot":"","sources":["../src/RegistryContext.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,KAAK,IAAI,MAAM,iCAAiC,CAAA;AAC5D,OAAO,KAAK,YAAY,MAAM,yCAAyC,CAAA;AACvE,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAGtD;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,0CAGzB,CAAA;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,SAAS,CAAA;IAC/C,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,SAAS,CAAA;IAC7E,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC,GAAG,SAAS,CAAA;IACnE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC7C,mFA2BA,CAAA"}

package/dist/RegistryContext.js

@@ -44,6 +44,14 @@ export function scheduleTask(f) {
  * hydration helpers, defaulting to a standalone registry when no provider is
  * present.
  *
+ * **When to use**
+ *
+ * Use to supply an existing `AtomRegistry` through React context when hooks or
+ * hydration helpers need to share registry state that is managed outside
+ * `RegistryProvider`.
+ *
+ * @see {@link RegistryProvider} for creating and providing a registry for a React subtree
+ *
  * @category context
  * @since 4.0.0
  */
@@ -55,6 +63,25 @@ export const RegistryContext = /*#__PURE__*/React.createContext(/*#__PURE__*/Ato
  * Provides a stable `AtomRegistry` to a React subtree, optionally seeding
  * initial atom values and overriding registry scheduling or idle settings.
  *
+ * **When to use**
+ *
+ * Use to scope atom state, scheduling, and idle cleanup to a React subtree.
+ *
+ * **Details**
+ *
+ * The provider creates one `AtomRegistry` with `AtomRegistry.make`, passes it
+ * through `RegistryContext.Provider`, and forwards `initialValues`,
+ * `scheduleTask`, `timeoutResolution`, and `defaultIdleTTL` only when that
+ * registry is created.
+ *
+ * **Gotchas**
+ *
+ * Option changes after the first render do not rebuild the registry. When the
+ * provider unmounts, registry disposal is delayed briefly and canceled if the
+ * provider remounts before the timeout fires.
+ *
+ * @see {@link RegistryContext} for the React context supplied by this provider
+ *
  * @category context
  * @since 4.0.0
  */

package/dist/RegistryContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"RegistryContext.js","names":["AtomRegistry","React","Scheduler","scheduleTask","f","node","unstable_scheduleCallback","unstable_LowPriority","unstable_cancelCallback","RegistryContext","createContext","make","defaultIdleTTL","RegistryProvider","options","ref","useRef","current","registry","initialValues","timeoutResolution","useEffect","timeout","undefined","clearTimeout","setTimeout","dispose","createElement","Provider","value","children"],"sources":["../src/RegistryContext.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,YAAY;;AAGZ,OAAO,KAAKA,YAAY,MAAM,yCAAyC;AACvE,OAAO,KAAKC,KAAK,MAAM,OAAO;AAC9B,OAAO,KAAKC,SAAS,MAAM,WAAW;AAEtC;;;;;;;AAOA,OAAM,SAAUC,YAAYA,CAACC,CAAa;EACxC,MAAMC,IAAI,GAAGH,SAAS,CAACI,yBAAyB,CAACJ,SAAS,CAACK,oBAAoB,EAAEH,CAAC,CAAC;EACnF,OAAO,MAAMF,SAAS,CAACM,uBAAuB,CAACH,IAAI,CAAC;AACtD;AAEA;;;;;;;;AAQA,OAAO,MAAMI,eAAe,gBAAGR,KAAK,CAACS,aAAa,cAA4BV,YAAY,CAACW,IAAI,CAAC;EAC9FR,YAAY;EACZS,cAAc,EAAE;CACjB,CAAC,CAAC;AAEH;;;;;;;AAOA,OAAO,MAAMC,gBAAgB,GAAIC,OAMhC,IAAI;EACH,MAAMC,GAAG,GAAGd,KAAK,CAACe,MAAM,CAGrB,IAAI,CAAC;EACR,IAAID,GAAG,CAACE,OAAO,KAAK,IAAI,EAAE;IACxBF,GAAG,CAACE,OAAO,GAAG;MACZC,QAAQ,EAAElB,YAAY,CAACW,IAAI,CAAC;QAC1BR,YAAY,EAAEW,OAAO,CAACX,YAAY,IAAIA,YAAY;QAClDgB,aAAa,EAAEL,OAAO,CAACK,aAAa;QACpCC,iBAAiB,EAAEN,OAAO,CAACM,iBAAiB;QAC5CR,cAAc,EAAEE,OAAO,CAACF;OACzB;KACF;EACH;EACAX,KAAK,CAACoB,SAAS,CAAC,MAAK;IACnB,IAAIN,GAAG,CAACE,OAAO,EAAEK,OAAO,KAAKC,SAAS,EAAE;MACtCC,YAAY,CAACT,GAAG,CAACE,OAAO,CAACK,OAAO,CAAC;IACnC;IACA,OAAO,MAAK;MACVP,GAAG,CAACE,OAAQ,CAACK,OAAO,GAAGG,UAAU,CAAC,MAAK;QACrCV,GAAG,CAACE,OAAO,EAAEC,QAAQ,CAACQ,OAAO,EAAE;QAC/BX,GAAG,CAACE,OAAO,GAAG,IAAI;MACpB,CAAC,EAAE,GAAG,CAAQ;IAChB,CAAC;EACH,CAAC,EAAE,CAACF,GAAG,CAAC,CAAC;EACT,OAAOd,KAAK,CAAC0B,aAAa,CAAClB,eAAe,CAACmB,QAAQ,EAAE;IAAEC,KAAK,EAAEd,GAAG,CAACE,OAAO,CAACC;EAAQ,CAAE,EAAEJ,OAAO,EAAEgB,QAAQ,CAAC;AAC1G,CAAC","ignoreList":[]}
+{"version":3,"file":"RegistryContext.js","names":["AtomRegistry","React","Scheduler","scheduleTask","f","node","unstable_scheduleCallback","unstable_LowPriority","unstable_cancelCallback","RegistryContext","createContext","make","defaultIdleTTL","RegistryProvider","options","ref","useRef","current","registry","initialValues","timeoutResolution","useEffect","timeout","undefined","clearTimeout","setTimeout","dispose","createElement","Provider","value","children"],"sources":["../src/RegistryContext.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,YAAY;;AAGZ,OAAO,KAAKA,YAAY,MAAM,yCAAyC;AACvE,OAAO,KAAKC,KAAK,MAAM,OAAO;AAC9B,OAAO,KAAKC,SAAS,MAAM,WAAW;AAEtC;;;;;;;AAOA,OAAM,SAAUC,YAAYA,CAACC,CAAa;EACxC,MAAMC,IAAI,GAAGH,SAAS,CAACI,yBAAyB,CAACJ,SAAS,CAACK,oBAAoB,EAAEH,CAAC,CAAC;EACnF,OAAO,MAAMF,SAAS,CAACM,uBAAuB,CAACH,IAAI,CAAC;AACtD;AAEA;;;;;;;;;;;;;;;;AAgBA,OAAO,MAAMI,eAAe,gBAAGR,KAAK,CAACS,aAAa,cAA4BV,YAAY,CAACW,IAAI,CAAC;EAC9FR,YAAY;EACZS,cAAc,EAAE;CACjB,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,OAAO,MAAMC,gBAAgB,GAAIC,OAMhC,IAAI;EACH,MAAMC,GAAG,GAAGd,KAAK,CAACe,MAAM,CAGrB,IAAI,CAAC;EACR,IAAID,GAAG,CAACE,OAAO,KAAK,IAAI,EAAE;IACxBF,GAAG,CAACE,OAAO,GAAG;MACZC,QAAQ,EAAElB,YAAY,CAACW,IAAI,CAAC;QAC1BR,YAAY,EAAEW,OAAO,CAACX,YAAY,IAAIA,YAAY;QAClDgB,aAAa,EAAEL,OAAO,CAACK,aAAa;QACpCC,iBAAiB,EAAEN,OAAO,CAACM,iBAAiB;QAC5CR,cAAc,EAAEE,OAAO,CAACF;OACzB;KACF;EACH;EACAX,KAAK,CAACoB,SAAS,CAAC,MAAK;IACnB,IAAIN,GAAG,CAACE,OAAO,EAAEK,OAAO,KAAKC,SAAS,EAAE;MACtCC,YAAY,CAACT,GAAG,CAACE,OAAO,CAACK,OAAO,CAAC;IACnC;IACA,OAAO,MAAK;MACVP,GAAG,CAACE,OAAQ,CAACK,OAAO,GAAGG,UAAU,CAAC,MAAK;QACrCV,GAAG,CAACE,OAAO,EAAEC,QAAQ,CAACQ,OAAO,EAAE;QAC/BX,GAAG,CAACE,OAAO,GAAG,IAAI;MACpB,CAAC,EAAE,GAAG,CAAQ;IAChB,CAAC;EACH,CAAC,EAAE,CAACF,GAAG,CAAC,CAAC;EACT,OAAOd,KAAK,CAAC0B,aAAa,CAAClB,eAAe,CAACmB,QAAQ,EAAE;IAAEC,KAAK,EAAEd,GAAG,CAACE,OAAO,CAACC;EAAQ,CAAE,EAAEJ,OAAO,EAAEgB,QAAQ,CAAC;AAC1G,CAAC","ignoreList":[]}

package/dist/ScopedAtom.d.ts

@@ -1,7 +1,12 @@
 import type * as Atom from "effect/unstable/reactivity/Atom";
 import * as React from "react";
 /**
- * Type identifier for ScopedAtom.
+ * Literal type used as the `ScopedAtom` type identifier.
+ *
+ * **Details**
+ *
+ * Used as the computed property key and marker value stored on `ScopedAtom`
+ * objects.
  *
  * @category type IDs
  * @since 4.0.0
@@ -10,6 +15,11 @@ export type TypeId = "~@effect/atom-react/ScopedAtom";
 /**
  * Type identifier for ScopedAtom.
  *
+ * **Details**
+ *
+ * Used as the computed property key and marker value stored on `ScopedAtom`
+ * objects.
+ *
  * @category type IDs
  * @since 4.0.0
  */
@@ -20,15 +30,15 @@ export declare const TypeId: TypeId;
  * **Example** (Providing and reading a scoped atom)
  *
  * ```ts
- * import * as AtomReact from "@effect/atom-react"
+ * import { make, useAtomValue } from "@effect/atom-react"
  * import { Atom } from "effect/unstable/reactivity"
  * import * as React from "react"
  *
- * const Counter = AtomReact.make(() => Atom.make(0))
+ * const Counter = make(() => Atom.make(0))
  *
  * function View() {
  *   const atom = Counter.use()
- *   const value = AtomReact.useAtomValue(atom)
+ *   const value = useAtomValue(atom)
  *   return React.createElement("div", null, value)
  * }
  *
@@ -54,18 +64,34 @@ export interface ScopedAtom<A extends Atom.Atom<any>, Input = never> {
 /**
  * Creates a ScopedAtom from a factory function.
  *
+ * **When to use**
+ *
+ * Use to create an atom instance that is owned by a React provider and scoped
+ * to a component subtree.
+ *
+ * **Details**
+ *
+ * The returned scoped atom includes a `Provider`, `Context`, and `use`
+ * accessor. The provider creates the atom once for its lifetime, passing the
+ * `value` prop to the factory when the scoped atom expects input.
+ *
+ * **Gotchas**
+ *
+ * `use` must run under the matching provider. Changing the provider `value`
+ * prop after mount does not recreate the atom.
+ *
  * **Example** (Creating a scoped atom with input)
  *
  * ```ts
- * import * as AtomReact from "@effect/atom-react"
+ * import { make, useAtomValue } from "@effect/atom-react"
  * import { Atom } from "effect/unstable/reactivity"
  * import * as React from "react"
  *
- * const User = AtomReact.make((name: string) => Atom.make(name))
+ * const User = make((name: string) => Atom.make(name))
  *
  * function UserName() {
  *   const atom = User.use()
- *   const value = AtomReact.useAtomValue(atom)
+ *   const value = useAtomValue(atom)
  *   return React.createElement("span", null, value)
  * }
  *

package/dist/ScopedAtom.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"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;;;;;;;;;;GAUG;AACH,MAAM,MAAM,MAAM,GAAG,gCAAgC,CAAA;AAErD;;;;;;;;;;GAUG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;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

@@ -24,6 +24,11 @@ import * as React from "react";
 /**
  * Type identifier for ScopedAtom.
  *
+ * **Details**
+ *
+ * Used as the computed property key and marker value stored on `ScopedAtom`
+ * objects.
+ *
  * @category type IDs
  * @since 4.0.0
  */
@@ -31,18 +36,34 @@ export const TypeId = "~@effect/atom-react/ScopedAtom";
 /**
  * Creates a ScopedAtom from a factory function.
  *
+ * **When to use**
+ *
+ * Use to create an atom instance that is owned by a React provider and scoped
+ * to a component subtree.
+ *
+ * **Details**
+ *
+ * The returned scoped atom includes a `Provider`, `Context`, and `use`
+ * accessor. The provider creates the atom once for its lifetime, passing the
+ * `value` prop to the factory when the scoped atom expects input.
+ *
+ * **Gotchas**
+ *
+ * `use` must run under the matching provider. Changing the provider `value`
+ * prop after mount does not recreate the atom.
+ *
  * **Example** (Creating a scoped atom with input)
  *
  * ```ts
- * import * as AtomReact from "@effect/atom-react"
+ * import { make, useAtomValue } from "@effect/atom-react"
  * import { Atom } from "effect/unstable/reactivity"
  * import * as React from "react"
  *
- * const User = AtomReact.make((name: string) => Atom.make(name))
+ * const User = make((name: string) => Atom.make(name))
  *
  * function UserName() {
  *   const atom = User.use()
- *   const value = AtomReact.useAtomValue(atom)
+ *   const value = useAtomValue(atom)
  *   return React.createElement("span", null, value)
  * }
  *

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;;;;;;;;;;;;;;;;;;;;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":[]}
+{"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;AAe9B;;;;;;;;;;;AAWA,OAAO,MAAMC,MAAM,GAAW,gCAAgC;AAoC9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8CA,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect/atom-react",
-  "version": "4.0.0-beta.70",
+  "version": "4.0.0-beta.71",
   "type": "module",
   "license": "MIT",
   "description": "React bindings for the Effect Atom modules",
@@ -45,7 +45,7 @@
   "peerDependencies": {
     "react": "^19.2.4",
     "scheduler": "*",
-    "effect": "^4.0.0-beta.70"
+    "effect": "^4.0.0-beta.71"
   },
   "devDependencies": {
     "@testing-library/dom": "^10.4.1",
@@ -59,7 +59,7 @@
     "react-dom": "19.2.6",
     "react-error-boundary": "^6.1.1",
     "scheduler": "^0.27.0",
-    "effect": "^4.0.0-beta.70"
+    "effect": "^4.0.0-beta.71"
   },
   "scripts": {
     "build": "tsc -b tsconfig.json && pnpm babel",

package/src/Hooks.ts

@@ -75,10 +75,15 @@ const initialValuesSet = new WeakMap<AtomRegistry.AtomRegistry, WeakSet<Atom.Ato
 /**
  * Seeds initial atom values in the current React atom registry.
  *
- * **Details**
+ * **When to use**
+ *
+ * Use to seed atom values from a React component after the current registry
+ * already exists.
  *
- * Each atom is initialized at most once for a given registry, so subsequent
- * renders do not overwrite values that have already been established.
+ * **Gotchas**
+ *
+ * Each atom is initialized at most once for a given registry by this hook, so
+ * later calls for the same atom in that registry are ignored.
  *
  * @category hooks
  * @since 4.0.0
@@ -102,6 +107,19 @@ export const useAtomInitialValues = (initialValues: Iterable<readonly [Atom.Atom
  * Subscribes to an atom in the current React registry and returns its current
  * value, optionally mapped through a selector.
  *
+ * **When to use**
+ *
+ * Use when a React component needs to render from an atom value without also
+ * returning a setter.
+ *
+ * **Details**
+ *
+ * When a selector is provided, the hook maps the atom before subscribing so the
+ * component reads the selected value from the current `RegistryContext`.
+ *
+ * @see {@link useAtom} for reading and updating a writable atom from one component
+ * @see {@link useAtomRef} for reading an `AtomRef` directly
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -110,6 +128,19 @@ export const useAtomValue: {
    * Subscribes to an atom in the current React registry and returns its current
    * value, optionally mapped through a selector.
    *
+   * **When to use**
+   *
+   * Use when a React component needs to render from an atom value without also
+   * returning a setter.
+   *
+   * **Details**
+   *
+   * When a selector is provided, the hook maps the atom before subscribing so the
+   * component reads the selected value from the current `RegistryContext`.
+   *
+   * @see {@link useAtom} for reading and updating a writable atom from one component
+   * @see {@link useAtomRef} for reading an `AtomRef` directly
+   *
    * @category hooks
    * @since 4.0.0
    */
@@ -118,6 +149,19 @@ export const useAtomValue: {
    * Subscribes to an atom in the current React registry and returns its current
    * value, optionally mapped through a selector.
    *
+   * **When to use**
+   *
+   * Use when a React component needs to render from an atom value without also
+   * returning a setter.
+   *
+   * **Details**
+   *
+   * When a selector is provided, the hook maps the atom before subscribing so the
+   * component reads the selected value from the current `RegistryContext`.
+   *
+   * @see {@link useAtom} for reading and updating a writable atom from one component
+   * @see {@link useAtomRef} for reading an `AtomRef` directly
+   *
    * @category hooks
    * @since 4.0.0
    */
@@ -174,6 +218,20 @@ const flattenExit = <A, E>(exit: Exit.Exit<A, E>): A => {
  * Mounts an atom in the current React registry for the lifetime of the
  * component.
  *
+ * **When to use**
+ *
+ * Use to keep an atom mounted from a React component without reading, writing,
+ * or refreshing it.
+ *
+ * **Details**
+ *
+ * The hook uses the current `RegistryContext` and releases the mount through
+ * React effect cleanup when the component unmounts or when the registry or atom
+ * dependency changes.
+ *
+ * @see {@link useAtomSet} for mounting a writable atom while returning a setter
+ * @see {@link useAtomRefresh} for mounting an atom while returning a refresh callback
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -185,6 +243,19 @@ export const useAtomMount = <A>(atom: Atom.Atom<A>): void => {
 /**
  * Mounts a writable atom and returns a setter without subscribing to its value.
  *
+ * **When to use**
+ *
+ * Use when a React component needs to update a writable atom without rendering
+ * from that atom's value.
+ *
+ * **Details**
+ *
+ * The hook mounts the atom and returns a setter. In value mode the setter
+ * accepts a write value or updater function; for `AsyncResult` atoms, `promise`
+ * and `promiseExit` modes return a promise for the success value or full `Exit`.
+ *
+ * @see {@link useAtom} for reading and updating the same writable atom
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -214,6 +285,18 @@ export const useAtomSet = <
  * Mounts an atom and returns a callback that refreshes it in the current React
  * registry.
  *
+ * **When to use**
+ *
+ * Use to expose a React callback that requests a refresh for an atom without
+ * reading or writing its value.
+ *
+ * **Details**
+ *
+ * The hook uses the current `RegistryContext`, mounts the atom for the
+ * component lifetime, and returns a callback that calls `registry.refresh`.
+ *
+ * @see {@link useAtomMount} for mounting an atom without returning a refresh callback
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -229,6 +312,14 @@ export const useAtomRefresh = <A>(atom: Atom.Atom<A>): () => void => {
  * Subscribes to a writable atom and returns its current value together with a
  * setter for updating it.
  *
+ * **When to use**
+ *
+ * Use when a React component needs both to render the current value of a
+ * writable atom and update it from the same component.
+ *
+ * @see {@link useAtomValue} for subscribing to an atom without a setter
+ * @see {@link useAtomSet} for updating a writable atom without subscribing to its value
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -299,6 +390,23 @@ function atomResultOrSuspend<A, E>(
  * Reads an `AsyncResult` atom through React Suspense, suspending while the
  * result is initial or configured as waiting.
  *
+ * **When to use**
+ *
+ * Use when a React component should render only after an `AsyncResult` atom has
+ * left its initial state, with loading delegated to a Suspense boundary.
+ *
+ * **Details**
+ *
+ * `suspendOnWaiting` defaults to `false`. When `includeFailure` is `true`, a
+ * failure result is returned instead of being thrown.
+ *
+ * **Gotchas**
+ *
+ * Without `includeFailure`, failure results are thrown with
+ * `Cause.squash(result.cause)`, so callers need an error boundary for failures.
+ *
+ * @see {@link useAtomValue} for reading the raw `AsyncResult` value without Suspense
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -321,6 +429,19 @@ export const useAtomSuspense = <A, E, const IncludeFailure extends boolean = fal
  * Subscribes a callback to an atom in the current React registry for the
  * component lifetime.
  *
+ * **When to use**
+ *
+ * Use when a React component needs to run a callback for atom changes without
+ * reading the atom value during render.
+ *
+ * **Details**
+ *
+ * The subscription is installed in a React effect and cleaned up on unmount or
+ * dependency change. When `options.immediate` is enabled, the callback receives
+ * the current value when the effect subscribes.
+ *
+ * @see {@link useAtomValue} for reading an atom value during render instead of running a callback
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -339,6 +460,19 @@ export const useAtomSubscribe = <A>(
 /**
  * Subscribes to an atom ref and returns its latest value.
  *
+ * **When to use**
+ *
+ * Use when a React component should render from an `AtomRef.ReadonlyRef`
+ * directly instead of reading an atom through the current registry.
+ *
+ * **Details**
+ *
+ * The hook subscribes with `ref.subscribe`, triggers re-renders through React
+ * state, and returns the current `ref.value`.
+ *
+ * @see {@link useAtomValue} for reading an `Atom` from the current registry
+ * @see {@link useAtomRefPropValue} for reading a property ref value
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -351,6 +485,19 @@ export const useAtomRef = <A>(ref: AtomRef.ReadonlyRef<A>): A => {
 /**
  * Returns a memoized atom ref for a property of another atom ref.
  *
+ * **When to use**
+ *
+ * Use to derive an `AtomRef` for one property of an object-shaped atom ref.
+ *
+ * **Details**
+ *
+ * The hook memoizes `ref.prop(prop)` for the `[ref, prop]` dependency pair and
+ * returns the property ref so callers can read, set, update, or subscribe to
+ * that nested property.
+ *
+ * @see {@link useAtomRef} for subscribing to an atom ref value
+ * @see {@link useAtomRefPropValue} for subscribing directly to a property value
+ *
  * @category hooks
  * @since 4.0.0
  */
@@ -361,6 +508,20 @@ export const useAtomRefProp = <A, K extends keyof A>(ref: AtomRef.AtomRef<A>, pr
  * Subscribes to a property ref derived from an atom ref and returns its current
  * value.
  *
+ * **When to use**
+ *
+ * Use when a React component needs only the current value of one property from
+ * an object-shaped `AtomRef`.
+ *
+ * **Details**
+ *
+ * The hook composes `useAtomRefProp(ref, prop)` with `useAtomRef`, so the
+ * property ref is memoized for the `[ref, prop]` pair and then subscribed
+ * through `ref.subscribe`.
+ *
+ * @see {@link useAtomRefProp} for returning the property ref directly
+ * @see {@link useAtomRef} for subscribing to a whole atom ref value
+ *
  * @category hooks
  * @since 4.0.0
  */

package/src/ReactHydration.ts

@@ -43,12 +43,20 @@ export interface HydrationBoundaryProps {
  * Hydrates dehydrated Atom values into the current Atom registry for a React
  * subtree.
  *
+ * **When to use**
+ *
+ * Use to apply dehydrated Atom state to a React subtree that reads from the
+ * nearest `RegistryContext`.
+ *
  * **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.
  *
+ * @see {@link Hydration.dehydrate} for producing dehydrated Atom state
+ * @see {@link Hydration.hydrate} for lower-level non-React hydration
+ *
  * @category components
  * @since 4.0.0
  */

package/src/RegistryContext.ts

@@ -47,6 +47,14 @@ export function scheduleTask(f: () => void): () => void {
  * hydration helpers, defaulting to a standalone registry when no provider is
  * present.
  *
+ * **When to use**
+ *
+ * Use to supply an existing `AtomRegistry` through React context when hooks or
+ * hydration helpers need to share registry state that is managed outside
+ * `RegistryProvider`.
+ *
+ * @see {@link RegistryProvider} for creating and providing a registry for a React subtree
+ *
  * @category context
  * @since 4.0.0
  */
@@ -59,6 +67,25 @@ export const RegistryContext = React.createContext<AtomRegistry.AtomRegistry>(At
  * Provides a stable `AtomRegistry` to a React subtree, optionally seeding
  * initial atom values and overriding registry scheduling or idle settings.
  *
+ * **When to use**
+ *
+ * Use to scope atom state, scheduling, and idle cleanup to a React subtree.
+ *
+ * **Details**
+ *
+ * The provider creates one `AtomRegistry` with `AtomRegistry.make`, passes it
+ * through `RegistryContext.Provider`, and forwards `initialValues`,
+ * `scheduleTask`, `timeoutResolution`, and `defaultIdleTTL` only when that
+ * registry is created.
+ *
+ * **Gotchas**
+ *
+ * Option changes after the first render do not rebuild the registry. When the
+ * provider unmounts, registry disposal is delayed briefly and canceled if the
+ * provider remounts before the timeout fires.
+ *
+ * @see {@link RegistryContext} for the React context supplied by this provider
+ *
  * @category context
  * @since 4.0.0
  */

package/src/ScopedAtom.ts

@@ -24,7 +24,12 @@ import type * as Atom from "effect/unstable/reactivity/Atom"
 import * as React from "react"
 
 /**
- * Type identifier for ScopedAtom.
+ * Literal type used as the `ScopedAtom` type identifier.
+ *
+ * **Details**
+ *
+ * Used as the computed property key and marker value stored on `ScopedAtom`
+ * objects.
  *
  * @category type IDs
  * @since 4.0.0
@@ -34,6 +39,11 @@ export type TypeId = "~@effect/atom-react/ScopedAtom"
 /**
  * Type identifier for ScopedAtom.
  *
+ * **Details**
+ *
+ * Used as the computed property key and marker value stored on `ScopedAtom`
+ * objects.
+ *
  * @category type IDs
  * @since 4.0.0
  */
@@ -45,15 +55,15 @@ export const TypeId: TypeId = "~@effect/atom-react/ScopedAtom"
  * **Example** (Providing and reading a scoped atom)
  *
  * ```ts
- * import * as AtomReact from "@effect/atom-react"
+ * import { make, useAtomValue } from "@effect/atom-react"
  * import { Atom } from "effect/unstable/reactivity"
  * import * as React from "react"
  *
- * const Counter = AtomReact.make(() => Atom.make(0))
+ * const Counter = make(() => Atom.make(0))
  *
  * function View() {
  *   const atom = Counter.use()
- *   const value = AtomReact.useAtomValue(atom)
+ *   const value = useAtomValue(atom)
  *   return React.createElement("div", null, value)
  * }
  *
@@ -76,18 +86,34 @@ export interface ScopedAtom<A extends Atom.Atom<any>, Input = never> {
 /**
  * Creates a ScopedAtom from a factory function.
  *
+ * **When to use**
+ *
+ * Use to create an atom instance that is owned by a React provider and scoped
+ * to a component subtree.
+ *
+ * **Details**
+ *
+ * The returned scoped atom includes a `Provider`, `Context`, and `use`
+ * accessor. The provider creates the atom once for its lifetime, passing the
+ * `value` prop to the factory when the scoped atom expects input.
+ *
+ * **Gotchas**
+ *
+ * `use` must run under the matching provider. Changing the provider `value`
+ * prop after mount does not recreate the atom.
+ *
  * **Example** (Creating a scoped atom with input)
  *
  * ```ts
- * import * as AtomReact from "@effect/atom-react"
+ * import { make, useAtomValue } from "@effect/atom-react"
  * import { Atom } from "effect/unstable/reactivity"
  * import * as React from "react"
  *
- * const User = AtomReact.make((name: string) => Atom.make(name))
+ * const User = make((name: string) => Atom.make(name))
  *
  * function UserName() {
  *   const atom = User.use()
- *   const value = AtomReact.useAtomValue(atom)
+ *   const value = useAtomValue(atom)
  *   return React.createElement("span", null, value)
  * }
  *