@octanejs/jotai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# @octanejs/jotai
+
+[jotai](https://github.com/pmndrs/jotai) for the [octane](https://github.com/octanejs/octane) UI framework.
+
+jotai separates a framework-agnostic **vanilla core** (`atom`, `createStore`,
+`getDefaultStore` + all of `vanilla/utils`) from a small **React binding**
+(`Provider`, `useStore`, `useAtom`, `useAtomValue`, `useSetAtom`). This package
+reuses the vanilla core unchanged (re-exported verbatim from `jotai/vanilla`) and
+reimplements only the binding on octane's hooks — deliberately preserving
+upstream's implementation shape (a force-update `useReducer` + effect
+subscription, not `useSyncExternalStore`), so re-render behavior matches jotai on
+React. The public surface matches jotai 1:1 — existing jotai code works by
+changing the import.
+
+```tsx
+// before
+import { atom, useAtom } from 'jotai';
+// after
+import { atom, useAtom } from '@octanejs/jotai';
+
+const countAtom = atom(0);
+
+function Counter() @{
+  const [count, setCount] = useAtom(countAtom);
+  <button onClick={() => setCount((c) => c + 1)}>count is {count as string}</button>
+}
+```
+
+## Entry points
+
+| import | what you get | notes |
+| --- | --- | --- |
+| `@octanejs/jotai` | `atom`, `createStore`, `getDefaultStore`, `Provider`, `useStore`, `useAtom`, `useAtomValue`, `useSetAtom` | vanilla verbatim + the octane-bound binding |
+| `@octanejs/jotai/vanilla` | `atom`, `createStore`, `getDefaultStore` + types | re-exported verbatim from jotai |
+| `@octanejs/jotai/vanilla/utils` | `RESET`, `atomWithReset`, `atomWithStorage`, `atomWithReducer`, `atomFamily`, `selectAtom`, `splitAtom`, `loadable`, `unwrap`, … | re-exported verbatim (all framework-agnostic) |
+| `@octanejs/jotai/vanilla/internals` | `INTERNAL_*` store building blocks | re-exported verbatim; unstable by upstream contract |
+| `@octanejs/jotai/react` | `Provider`, `useStore`, `useAtom`, `useAtomValue`, `useSetAtom` | the binding, ported to octane hooks |
+| `@octanejs/jotai/react/utils` | `useResetAtom`, `useAtomCallback`, `useHydrateAtoms`, `useReducerAtom` | ported to octane hooks |
+| `@octanejs/jotai/utils` | everything from `vanilla/utils` + `react/utils` | mirror of `jotai/utils` |
+
+`jotai/babel/*` (React-specific compile-time plugins) is not shipped.
+
+## How it works
+
+octane keys hooks by a compiler-injected per-call-site `Symbol`, appended as the
+last argument of every `use*` call. The hooks here **forward** that slot to the
+base hooks they compose (deriving a stable sub-slot per composed base hook), so
+`useAtom(a)` and `useAtom(b)` in one component — or the same atom used twice —
+stay independent, exactly like distinct call sites in React.
+
+The binding is a line-for-line port of `jotai/react`: a reader holds a
+`[value, store, atom]` tuple in a force-update reducer and subscribes to the
+store in an effect. That means the same observable behavior as jotai on React,
+including:
+
+- **`useSetAtom` never re-renders the writer.** A component that only writes an
+  atom doesn't subscribe to it.
+- **Derived atoms bail out.** A dependency write that recomputes to an
+  `Object.is`-equal value never notifies readers.
+- **Readers mount with two renders** (the subscription effect re-checks the
+  value after subscribing) — same as upstream.
+
+## Async atoms + Suspense
+
+An atom whose value is a promise suspends the reader through octane's `use()`
+(React-19 parity) on jotai's identity-stable *continuable promise*. Use a
+suspense boundary (`@try { } @pending { } @catch (e) { }` or `<Suspense>`), or
+skip suspending entirely with the vanilla `loadable`/`unwrap` escape hatches:
+
+```tsx
+const userAtom = atom(async () => (await fetch('/api/user')).json());
+
+function Profile() @{
+  <div>
+    @try {
+      <UserName />
+    } @pending {
+      <span>loading…</span>
+    } @catch (e) {
+      <span>failed: {(e as Error).message}</span>
+    }
+  </div>
+}
+```
+
+## Status
+
+Current scope, known divergences, and verification status are tracked in the
+generated [bindings status table](../../docs/bindings-status.md), sourced from
+this package's [`status.json`](./status.json).

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@octanejs/jotai",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "description": "jotai bindings for the octane renderer — reuses jotai's framework-agnostic vanilla atoms/store and swaps the React binding for an octane port of jotai/react.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/jotai"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./vanilla": "./src/vanilla.ts",
+    "./vanilla/utils": "./src/vanilla/utils.ts",
+    "./vanilla/internals": "./src/vanilla/internals.ts",
+    "./react": "./src/react.ts",
+    "./react/utils": "./src/react/utils.ts",
+    "./utils": "./src/utils.ts"
+  },
+  "dependencies": {
+    "jotai": "^2.20.1",
+    "octane": "0.1.3"
+  },
+  "devDependencies": {
+    "@tsrx/react": "^0.2.37",
+    "esbuild": "^0.28.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+// @octanejs/jotai — jotai for the octane renderer.
+//
+// jotai cleanly separates a framework-agnostic vanilla core (`atom`,
+// `createStore`, `getDefaultStore` + all of vanilla/utils) from a small React
+// binding (`Provider`, `useStore`, `useAtom`, `useAtomValue`, `useSetAtom`).
+// This package reuses the vanilla core UNCHANGED (re-exported verbatim from
+// `jotai/vanilla`) and reimplements only the binding on octane's hooks —
+// preserving upstream's useReducer-force-update implementation rather than
+// rewriting it on useSyncExternalStore, so re-render behavior matches jotai on
+// React. The public surface matches jotai 1:1: existing jotai code works by
+// changing the import from `jotai` to `@octanejs/jotai`.
+//
+// The one octane-specific detail is hook slots: octane keys hooks by a
+// compiler-injected per-call-site Symbol, appended as the LAST argument of
+// every `use*` call. The hooks here FORWARD that slot (deriving stable
+// sub-slots when one hook composes several base hooks — see internal.ts), so
+// `useAtom(a)` and `useAtom(b)` in one component stay independent, just like
+// in React.
+export * from './vanilla';
+export * from './react';

package/src/internal.ts

@@ -0,0 +1,37 @@
+// Slot mechanics shared by the binding's plain-`.ts` hooks (same helper as
+// @octanejs/tanstack-query). The octane compiler injects a per-call-site Symbol slot into
+// every hook call in compiled files; these binding files are NOT compiled, so a
+// hook here receives the caller's slot as its trailing argument and derives a
+// distinct sub-slot for each base hook it composes.
+
+// Memoized: subSlot runs on EVERY hook call every render; the cache returns the
+// identical Symbol.for-interned value without the concat + registry lookup.
+const subSlotCache = new Map<symbol, Map<string, symbol>>();
+// Tag-only symbols for the slotless-caller case (see below).
+const bareTagCache = new Map<string, symbol>();
+
+export function subSlot(slot: symbol | undefined, tag: string): symbol {
+	// No inherited slot (the caller was NOT compiled — e.g. a vendored wrapper
+	// hook): return a stable TAG-ONLY symbol rather than undefined. The runtime
+	// combines it with the ambient withSlot path, so sibling base hooks inside
+	// one composed hook stay DISTINCT per tag. Returning undefined here made
+	// them all resolve to the bare path — one shared slot, state collision.
+	if (slot === undefined) {
+		let bare = bareTagCache.get(tag);
+		if (bare === undefined) bareTagCache.set(tag, (bare = Symbol.for(':' + tag)));
+		return bare;
+	}
+	let byTag = subSlotCache.get(slot);
+	if (byTag === undefined) subSlotCache.set(slot, (byTag = new Map()));
+	let sym = byTag.get(tag);
+	if (sym === undefined) byTag.set(tag, (sym = Symbol.for((slot.description ?? '') + ':' + tag)));
+	return sym;
+}
+
+// Split the compiler-injected trailing slot off a hook's runtime args, returning
+// the user args (everything before it) and the slot.
+export function splitSlot(args: any[]): [any[], symbol | undefined] {
+	const tail = args[args.length - 1];
+	const slot = typeof tail === 'symbol' ? (tail as symbol) : undefined;
+	return [slot !== undefined ? args.slice(0, -1) : args, slot];
+}

package/src/react/Provider.tsrx

@@ -0,0 +1,19 @@
+// Provider — port of the component half of jotai's react/Provider.ts. Upstream
+// only allocates a store when no `store` prop is given (the useRef stays null
+// otherwise); the port keeps that laziness but renders through a SINGLE JSX
+// path instead of upstream's two createElement returns — the children
+// descriptor shape must stay stable across renders for octane's reconciler.
+import { useRef } from 'octane';
+import { createStore } from 'jotai/vanilla';
+import { StoreContext } from './store.ts';
+
+export function Provider(props) @{
+	const { children, store } = props;
+
+	const storeRef = useRef(null);
+	if (!store && storeRef.current === null) {
+		storeRef.current = createStore();
+	}
+
+	<StoreContext.Provider value={store || storeRef.current}>{children}</StoreContext.Provider>
+}

package/src/react/Provider.tsrx.d.ts

@@ -0,0 +1,4 @@
+// Type declaration for the .tsrx component (resolved by relative path).
+import type { Store } from './store';
+
+export declare const Provider: (props: { children?: unknown; store?: Store }) => unknown;

package/src/react/store.ts

@@ -0,0 +1,41 @@
+// The store context + `useStore` — port of the context half of jotai's
+// react/Provider.ts. The context instance is deduped across duplicate module
+// instances via a globalThis map keyed by octane's createContext (the same
+// hazard exists under Vite dev — duplicate module instances — see
+// @octanejs/redux's Context.ts, which this mirrors).
+import { createContext, useContext } from 'octane';
+import { createStore, getDefaultStore } from 'jotai/vanilla';
+import { splitSlot } from '../internal';
+
+export type Store = ReturnType<typeof createStore>;
+
+const ContextKey = Symbol.for('octane-jotai-store-context');
+const gT: any = typeof globalThis !== 'undefined' ? globalThis : {};
+
+function getContext() {
+	const contextMap: Map<typeof createContext, any> = (gT[ContextKey] ??= new Map());
+	let realContext = contextMap.get(createContext);
+	if (!realContext) {
+		realContext = createContext<Store | undefined>(undefined);
+		contextMap.set(createContext, realContext);
+	}
+	return realContext as ReturnType<typeof createContext<Store | undefined>>;
+}
+
+export const StoreContext = getContext();
+
+type Options = {
+	store?: Store;
+};
+
+// Resolution order (upstream parity): an explicit `options.store` wins, then
+// the nearest <Provider>'s store, then the module-global default store. The
+// context read is keyed by context identity in octane, so no slot is needed —
+// the trailing compiler-injected slot is stripped and dropped.
+export function useStore(options?: Options): Store;
+export function useStore(...rest: [options?: Options, slot?: symbol]): Store {
+	const [user] = splitSlot(rest);
+	const options = user[0] as Options | undefined;
+	const store = useContext(StoreContext);
+	return options?.store || store || getDefaultStore();
+}

package/src/react/useAtom.ts

@@ -0,0 +1,66 @@
+// useAtom — port of jotai's react/useAtom.ts: a tuple of the two base hooks.
+// Each half gets its own stable sub-slot so `useAtom(a)` and `useAtom(b)` in
+// one component (or the same atom twice) keep independent reducer/effect/
+// callback state, exactly like distinct call sites in React.
+import type {
+	Atom,
+	ExtractAtomArgs,
+	ExtractAtomResult,
+	ExtractAtomValue,
+	PrimitiveAtom,
+	SetStateAction,
+	WritableAtom,
+} from 'jotai/vanilla';
+import { useAtomValue } from './useAtomValue';
+import { useSetAtom } from './useSetAtom';
+import { splitSlot, subSlot } from '../internal';
+
+type SetAtom<Args extends unknown[], Result> = (...args: Args) => Result;
+
+type Options = Parameters<typeof useAtomValue>[1];
+
+export function useAtom<Value, Args extends unknown[], Result>(
+	atom: WritableAtom<Value, Args, Result>,
+	options?: Options,
+): [Awaited<Value>, SetAtom<Args, Result>];
+
+export function useAtom<Value>(
+	atom: PrimitiveAtom<Value>,
+	options?: Options,
+): [Awaited<Value>, SetAtom<[SetStateAction<Value>], void>];
+
+export function useAtom<Value>(atom: Atom<Value>, options?: Options): [Awaited<Value>, never];
+
+export function useAtom<AtomType extends WritableAtom<unknown, never[], unknown>>(
+	atom: AtomType,
+	options?: Options,
+): [
+	Awaited<ExtractAtomValue<AtomType>>,
+	SetAtom<ExtractAtomArgs<AtomType>, ExtractAtomResult<AtomType>>,
+];
+
+export function useAtom<AtomType extends Atom<unknown>>(
+	atom: AtomType,
+	options?: Options,
+): [Awaited<ExtractAtomValue<AtomType>>, never];
+
+export function useAtom<Value, Args extends unknown[], Result>(
+	atom: Atom<Value> | WritableAtom<Value, Args, Result>,
+	...rest: [options?: Options, slot?: symbol]
+) {
+	const [user, slot] = splitSlot(rest);
+	const options = user[0] as Options | undefined;
+	return [
+		(useAtomValue as (a: unknown, o?: unknown, s?: symbol) => unknown)(
+			atom,
+			options,
+			subSlot(slot, 'ua:v'),
+		),
+		// We do wrong type assertion here, which results in throwing an error.
+		(useSetAtom as (a: unknown, o?: unknown, s?: symbol) => unknown)(
+			atom,
+			options,
+			subSlot(slot, 'ua:s'),
+		),
+	];
+}

package/src/react/useAtomValue.ts

@@ -0,0 +1,183 @@
+// useAtomValue — port of jotai's react/useAtomValue.ts. Upstream reads the
+// atom through a force-update reducer holding a `[value, store, atom]` tuple
+// and subscribes in an effect (re-render on store notify; an unconditional
+// post-subscribe rerender catches updates that raced between render and
+// effect — so mounting renders twice, in React and here alike). The port keeps
+// that shape exactly: octane's `useReducer` has React's semantics (lazy init;
+// a no-op dispatch still renders once with children bailing), and a
+// render-phase `rerender()` on store/atom swap mutates the reducer state
+// synchronously and schedules a self-quiescing re-render while THIS render
+// uses the locally-computed value.
+//
+// Async atom values suspend through octane's `use()` on a "continuable"
+// promise: a wrapper whose identity is WeakMap-stable across atom
+// recomputations (aborted fetches chain into it via the store's abort-handler
+// registry). That stability is what lets octane's thenable replay see the SAME
+// promise on every re-render until it settles — do not simplify it away.
+import { use, useDebugValue, useEffect, useReducer } from 'octane';
+import { INTERNAL_getBuildingBlocksRev3 as INTERNAL_getBuildingBlocks } from 'jotai/vanilla/internals';
+import type { Atom, ExtractAtomValue } from 'jotai/vanilla';
+import { useStore, type Store } from './store';
+import { splitSlot, subSlot } from '../internal';
+
+const isPromiseLike = (x: unknown): x is PromiseLike<unknown> =>
+	typeof (x as PromiseLike<unknown>)?.then === 'function';
+
+// Opt-in (`unstable_promiseStatus`) decoration of the suspended promise with
+// React 19's `status`/`value`/`reason` convention. Upstream defaults this to
+// "React.use is missing"; octane always has `use`, so it defaults to false.
+const attachPromiseStatus = <T>(
+	promise: PromiseLike<T> & {
+		status?: 'pending' | 'fulfilled' | 'rejected';
+		value?: T;
+		reason?: unknown;
+	},
+) => {
+	if (!promise.status) {
+		promise.status = 'pending';
+		promise.then(
+			(v) => {
+				promise.status = 'fulfilled';
+				promise.value = v;
+			},
+			(e) => {
+				promise.status = 'rejected';
+				promise.reason = e;
+			},
+		);
+	}
+};
+
+const continuablePromiseMap = new WeakMap<PromiseLike<unknown>, Promise<unknown>>();
+
+const createContinuablePromise = <T>(
+	store: Store,
+	promise: PromiseLike<T>,
+	getValue: () => PromiseLike<T> | T,
+) => {
+	const buildingBlocks = INTERNAL_getBuildingBlocks(store);
+	const registerAbortHandler = buildingBlocks[26];
+	let continuablePromise = continuablePromiseMap.get(promise);
+	if (!continuablePromise) {
+		continuablePromise = new Promise<T>((resolve, reject) => {
+			let curr = promise;
+			const onFulfilled = (me: PromiseLike<T>) => (v: T) => {
+				if (curr === me) {
+					resolve(v);
+				}
+			};
+			const onRejected = (me: PromiseLike<T>) => (e: unknown) => {
+				if (curr === me) {
+					reject(e);
+				}
+			};
+			const onAbort = () => {
+				try {
+					const nextValue = getValue();
+					if (isPromiseLike(nextValue)) {
+						continuablePromiseMap.set(nextValue, continuablePromise!);
+						curr = nextValue;
+						nextValue.then(onFulfilled(nextValue), onRejected(nextValue));
+						registerAbortHandler(buildingBlocks, store, nextValue, onAbort);
+					} else {
+						resolve(nextValue);
+					}
+				} catch (e) {
+					reject(e);
+				}
+			};
+			promise.then(onFulfilled(promise), onRejected(promise));
+			registerAbortHandler(buildingBlocks, store, promise, onAbort);
+		});
+		continuablePromiseMap.set(promise, continuablePromise);
+	}
+	return continuablePromise;
+};
+
+type Options = Parameters<typeof useStore>[0] & {
+	/** @deprecated delay option is deprecated and will be removed in v3. https://github.com/pmndrs/jotai/pull/3264 */
+	delay?: number;
+	unstable_promiseStatus?: boolean;
+};
+
+export function useAtomValue<Value>(atom: Atom<Value>, options?: Options): Awaited<Value>;
+
+export function useAtomValue<AtomType extends Atom<unknown>>(
+	atom: AtomType,
+	options?: Options,
+): Awaited<ExtractAtomValue<AtomType>>;
+
+export function useAtomValue<Value>(
+	atom: Atom<Value>,
+	...rest: [options?: Options, slot?: symbol]
+) {
+	const [user, slot] = splitSlot(rest);
+	const options = user[0] as Options | undefined;
+	const { delay, unstable_promiseStatus: promiseStatus = false } = options || {};
+	const store = useStore(options);
+
+	const [[valueFromReducer, storeFromReducer, atomFromReducer], rerender] = useReducer<
+		readonly [Value, Store, Atom<Value>],
+		void,
+		undefined
+	>(
+		(prev) => {
+			const nextValue = store.get(atom);
+			if (Object.is(prev[0], nextValue) && prev[1] === store && prev[2] === atom) {
+				return prev;
+			}
+			return [nextValue, store, atom];
+		},
+		undefined,
+		() => [store.get(atom), store, atom],
+		subSlot(slot, 'uav:r'),
+	);
+
+	let value = valueFromReducer;
+	if (storeFromReducer !== store || atomFromReducer !== atom) {
+		rerender();
+		value = store.get(atom);
+	}
+
+	useEffect(
+		() => {
+			const unsub = store.sub(atom, () => {
+				if (promiseStatus) {
+					try {
+						const value = store.get(atom);
+						if (isPromiseLike(value)) {
+							attachPromiseStatus(createContinuablePromise(store, value, () => store.get(atom)));
+						}
+					} catch {
+						// ignore
+					}
+				}
+				if (typeof delay === 'number') {
+					if (process.env.NODE_ENV !== 'production') {
+						console.warn(
+							'[DEPRECATED] delay option is deprecated and will be removed in v3. https://github.com/pmndrs/jotai/pull/3264',
+						);
+					}
+					// delay rerendering to wait a promise possibly to resolve
+					setTimeout(rerender, delay);
+					return;
+				}
+				rerender();
+			});
+			rerender();
+			return unsub;
+		},
+		[store, atom, delay, promiseStatus],
+		subSlot(slot, 'uav:e'),
+	);
+
+	useDebugValue(value);
+	if (isPromiseLike(value)) {
+		const promise = createContinuablePromise(store, value, () => store.get(atom));
+		if (promiseStatus) {
+			attachPromiseStatus(promise);
+		}
+		return use(promise);
+	}
+	return value as Awaited<Value>;
+}

package/src/react/useSetAtom.ts

@@ -0,0 +1,42 @@
+// useSetAtom — port of jotai's react/useSetAtom.ts. Write-only: no reducer, no
+// subscription — a component using only the setter never re-renders on atom
+// writes. The setter is memoized per [store, atom].
+import { useCallback } from 'octane';
+import type { ExtractAtomArgs, ExtractAtomResult, WritableAtom } from 'jotai/vanilla';
+import { useStore, type Store } from './store';
+import { splitSlot, subSlot } from '../internal';
+
+type SetAtom<Args extends unknown[], Result> = (...args: Args) => Result;
+type Options = Parameters<typeof useStore>[0];
+
+export function useSetAtom<Value, Args extends unknown[], Result>(
+	atom: WritableAtom<Value, Args, Result>,
+	options?: Options,
+): SetAtom<Args, Result>;
+
+export function useSetAtom<AtomType extends WritableAtom<unknown, never[], unknown>>(
+	atom: AtomType,
+	options?: Options,
+): SetAtom<ExtractAtomArgs<AtomType>, ExtractAtomResult<AtomType>>;
+
+export function useSetAtom<Value, Args extends unknown[], Result>(
+	atom: WritableAtom<Value, Args, Result>,
+	...rest: [options?: Options, slot?: symbol]
+) {
+	const [user, slot] = splitSlot(rest);
+	const options = user[0] as Options | undefined;
+	const store = useStore(options);
+	const setAtom = useCallback(
+		(...args: Args) => {
+			if (process.env.NODE_ENV !== 'production' && !('write' in atom)) {
+				// useAtom can pass non writable atom with wrong type assertion,
+				// so we should check here.
+				throw new Error('not writable atom');
+			}
+			return store.set(atom, ...args);
+		},
+		[store, atom],
+		subSlot(slot, 'usa:cb'),
+	);
+	return setAtom;
+}

package/src/react/utils.ts

@@ -0,0 +1,170 @@
+// `@octanejs/jotai/react/utils` — port of jotai's react/utils/*.ts (the four
+// binding-side utils; everything else in `jotai/utils` is vanilla and reused
+// verbatim). Each hook derives stable sub-slots for the base hooks it
+// composes, so multiple uses in one component stay independent.
+import { useCallback, useMemo } from 'octane';
+import { atom } from 'jotai/vanilla';
+import type { Getter, PrimitiveAtom, Setter, WritableAtom } from 'jotai/vanilla';
+import { RESET } from 'jotai/vanilla/utils';
+import { useStore, type Store } from './store';
+import { useSetAtom } from './useSetAtom';
+import { useAtom } from './useAtom';
+import { splitSlot, subSlot } from '../internal';
+
+type SetAtomOptions = Parameters<typeof useSetAtom>[1];
+
+// useResetAtom — port of react/utils/useResetAtom.ts.
+export function useResetAtom<T>(
+	anAtom: WritableAtom<unknown, [typeof RESET], T>,
+	options?: SetAtomOptions,
+): () => T;
+export function useResetAtom<T>(
+	anAtom: WritableAtom<unknown, [typeof RESET], T>,
+	...rest: [options?: SetAtomOptions, slot?: symbol]
+) {
+	const [user, slot] = splitSlot(rest);
+	const options = user[0] as SetAtomOptions;
+	const setAtom = (useSetAtom as (a: unknown, o?: unknown, s?: symbol) => (v: unknown) => T)(
+		anAtom,
+		options,
+		subSlot(slot, 'ura:set'),
+	);
+	const resetAtom = useCallback(() => setAtom(RESET), [setAtom], subSlot(slot, 'ura:cb'));
+	return resetAtom;
+}
+
+type AtomOptions = Parameters<typeof useAtom>[1];
+
+/**
+ * @deprecated please use a recipe instead
+ * https://github.com/pmndrs/jotai/pull/2467
+ */
+export function useReducerAtom<Value, Action>(
+	anAtom: PrimitiveAtom<Value>,
+	reducer: (v: Value, a?: Action) => Value,
+	options?: AtomOptions,
+): [Value, (action?: Action) => void];
+/**
+ * @deprecated please use a recipe instead
+ * https://github.com/pmndrs/jotai/pull/2467
+ */
+export function useReducerAtom<Value, Action>(
+	anAtom: PrimitiveAtom<Value>,
+	reducer: (v: Value, a: Action) => Value,
+	options?: AtomOptions,
+): [Value, (action: Action) => void];
+export function useReducerAtom<Value, Action>(
+	anAtom: PrimitiveAtom<Value>,
+	reducer: (v: Value, a: Action) => Value,
+	...rest: [options?: AtomOptions, slot?: symbol]
+) {
+	const [user, slot] = splitSlot(rest);
+	const options = user[0] as AtomOptions;
+	if (process.env.NODE_ENV !== 'production') {
+		console.warn(
+			'[DEPRECATED] useReducerAtom is deprecated and will be removed in the future. Please create your own version using the recipe. https://github.com/pmndrs/jotai/pull/2467',
+		);
+	}
+	const [state, setState] = (
+		useAtom as (
+			a: unknown,
+			o?: unknown,
+			s?: symbol,
+		) => [Value, (update: (prev: Value) => Value) => void]
+	)(anAtom, options, subSlot(slot, 'urda:a'));
+	const dispatch = useCallback(
+		(action: Action) => {
+			setState((prev) => reducer(prev, action));
+		},
+		[setState, reducer],
+		subSlot(slot, 'urda:cb'),
+	);
+	return [state, dispatch];
+}
+
+// useAtomCallback — port of react/utils/useAtomCallback.ts: an ephemeral
+// write-only atom memoized per callback, exposed through useSetAtom.
+export function useAtomCallback<Result, Args extends unknown[]>(
+	callback: (get: Getter, set: Setter, ...arg: Args) => Result,
+	options?: SetAtomOptions,
+): (...args: Args) => Result;
+export function useAtomCallback<Result, Args extends unknown[]>(
+	callback: (get: Getter, set: Setter, ...arg: Args) => Result,
+	...rest: [options?: SetAtomOptions, slot?: symbol]
+) {
+	const [user, slot] = splitSlot(rest);
+	const options = user[0] as SetAtomOptions;
+	const anAtom = useMemo(
+		() => atom(null, (get, set, ...args: Args) => callback(get, set, ...args)),
+		[callback],
+		subSlot(slot, 'uac:m'),
+	);
+	return (useSetAtom as (a: unknown, o?: unknown, s?: symbol) => (...args: Args) => Result)(
+		anAtom,
+		options,
+		subSlot(slot, 'uac:set'),
+	);
+}
+
+type HydrateOptions = Parameters<typeof useStore>[0] & {
+	dangerouslyForceHydrate?: boolean;
+};
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyWritableAtom = WritableAtom<any, any[], any>;
+
+type InferAtomTuples<T> = {
+	[K in keyof T]: T[K] extends readonly [infer A, ...infer Rest]
+		? A extends WritableAtom<unknown, infer Args, unknown>
+			? Rest extends Args
+				? readonly [A, ...Rest]
+				: never
+			: T[K]
+		: never;
+};
+
+// For internal use only
+// This can be changed without notice.
+export type INTERNAL_InferAtomTuples<T> = InferAtomTuples<T>;
+
+const hydratedMap: WeakMap<Store, WeakSet<AnyWritableAtom>> = new WeakMap();
+
+// useHydrateAtoms — port of react/utils/useHydrateAtoms.ts. Writes each
+// [atom, value] into the resolved store DURING render, once per (store, atom)
+// unless dangerouslyForceHydrate. No slotted hooks — only the context read.
+export function useHydrateAtoms<T extends (readonly [AnyWritableAtom, ...unknown[]])[]>(
+	values: InferAtomTuples<T>,
+	options?: HydrateOptions,
+): void;
+export function useHydrateAtoms<T extends Map<AnyWritableAtom, unknown>>(
+	values: T,
+	options?: HydrateOptions,
+): void;
+export function useHydrateAtoms<T extends Iterable<readonly [AnyWritableAtom, ...unknown[]]>>(
+	values: InferAtomTuples<T>,
+	options?: HydrateOptions,
+): void;
+export function useHydrateAtoms<T extends Iterable<readonly [AnyWritableAtom, ...unknown[]]>>(
+	values: T,
+	...rest: [options?: HydrateOptions, slot?: symbol]
+) {
+	const [user] = splitSlot(rest);
+	const options = user[0] as HydrateOptions | undefined;
+	const store = useStore(options);
+
+	const hydratedSet = getHydratedSet(store);
+	for (const [atom, ...args] of values) {
+		if (!hydratedSet.has(atom) || options?.dangerouslyForceHydrate) {
+			hydratedSet.add(atom);
+			store.set(atom, ...args);
+		}
+	}
+}
+
+const getHydratedSet = (store: Store) => {
+	let hydratedSet = hydratedMap.get(store);
+	if (!hydratedSet) {
+		hydratedSet = new WeakSet();
+		hydratedMap.set(store, hydratedSet);
+	}
+	return hydratedSet;
+};

package/src/react.ts

@@ -0,0 +1,10 @@
+// `@octanejs/jotai/react` — the binding layer, ported from jotai's react.ts.
+// Upstream's implementation shape is kept deliberately (a force-update
+// useReducer + effect subscription, NOT useSyncExternalStore) so behavior —
+// including re-render timing and write-only non-re-rendering — matches jotai
+// on React.
+export { Provider } from './react/Provider.tsrx';
+export { useStore } from './react/store';
+export { useAtomValue } from './react/useAtomValue';
+export { useSetAtom } from './react/useSetAtom';
+export { useAtom } from './react/useAtom';

package/src/utils.ts

@@ -0,0 +1,4 @@
+// `@octanejs/jotai/utils` — mirror of upstream jotai's utils.ts: the vanilla
+// utils (re-exported verbatim from jotai) plus the ported binding-side utils.
+export * from './vanilla/utils';
+export * from './react/utils';

package/src/vanilla/internals.ts

@@ -0,0 +1,6 @@
+// `@octanejs/jotai/vanilla/internals` — re-exported verbatim from jotai.
+//
+// The INTERNAL_* store building blocks are framework-agnostic and unstable by
+// contract upstream; they're re-exported unchanged for surface parity (and used
+// by this package's own async-atom plumbing, see react/useAtomValue.ts).
+export * from 'jotai/vanilla/internals';

package/src/vanilla/utils.ts

@@ -0,0 +1,8 @@
+// `@octanejs/jotai/vanilla/utils` — re-exported verbatim from jotai.
+//
+// Every vanilla util (RESET, atomWithReset, atomWithDefault, atomWithStorage,
+// atomWithReducer, atomWithRefresh, atomWithLazy, atomWithObservable, atomFamily,
+// selectAtom, splitAtom, loadable, unwrap, freezeAtom, …) is a framework-agnostic
+// atom factory or store helper — it composes with octane's `useAtom`/`useAtomValue`
+// unchanged, so we re-export it as-is (mirroring src/vanilla.ts).
+export * from 'jotai/vanilla/utils';

package/src/vanilla.ts

@@ -0,0 +1,6 @@
+// The framework-agnostic core, re-exported verbatim from jotai. `atom`,
+// `createStore`, and `getDefaultStore` are pure JS with no React import — only
+// the React binding (see react.ts) is swapped for one built on octane's hooks.
+// Authors who only need atoms + a store (no component binding) can import from
+// `@octanejs/jotai/vanilla` exactly as they would from `jotai/vanilla`.
+export * from 'jotai/vanilla';