@octanejs/jotai 0.1.49 → 0.1.51

package/LICENSE.upstream

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Poimandres
+
+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

@@ -1,6 +1,6 @@
 # @octanejs/jotai
 
-[jotai](https://github.com/pmndrs/jotai) for the [octane](https://github.com/octanejs/octane) UI framework.
+Jotai 3 atoms and stores for Octane. The package imports Jotai's vanilla core and ports its React hooks and provider to Octane.
 
 ## Installation
 
@@ -9,89 +9,48 @@ npm install @octanejs/jotai
 pnpm add @octanejs/jotai
 ```
 
-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>
+  <button onClick={() => setCount((value) => value + 1)}>{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:
+| Import | Surface |
+| --- | --- |
+| `@octanejs/jotai` | Vanilla atoms/stores, `Provider`, `useStore`, `useAtom`, `useSetAtom`, `useAtomValue`, `useAtomValueRaw`, `useAtomValueRawSync` |
+| `@octanejs/jotai/react` | Provider and hooks |
+| `@octanejs/jotai/react/utils` | `useResetAtom`, `useReducerAtom`, `useAtomCallback`, `useHydrateAtoms` |
+| `@octanejs/jotai/vanilla` | Direct re-exports of `jotai/vanilla` |
+| `@octanejs/jotai/vanilla/utils` | Direct re-exports of `jotai/vanilla/utils` |
+| `@octanejs/jotai/vanilla/internals` | Upstream's unstable store building blocks |
+| `@octanejs/jotai/utils` | Vanilla utilities and hook utilities |
 
-```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>
-}
-```
+Framework-neutral callers can import directly from `jotai/vanilla` and `jotai/vanilla/utils`. These imports share the same atoms and stores with the Octane binding.
+
+## Jotai 3 migration
+
+- `useAtomValueRaw` returns the atom value without unwrapping promises or suspending. It subscribes through an effect.
+- `useAtomValueRawSync` also returns the raw value and uses `useSyncExternalStore` for synchronous store consistency.
+- `useAtomValue` and `useAtom` retain Suspense integration. Their obsolete `delay` option is removed.
+- `loadable` is removed. Use the retained `unwrap` utility or read raw promise values for non-suspending reads.
+- `atomFamily` moves to `jotai-family`; install that package and import `atomFamily` directly from it.
+- The atom read function's `setSelf` option is removed. Its replacement depends on the use case; see the [upstream migration guide](https://github.com/pmndrs/jotai/blob/89d4fddd1949628e50952fc8ac1b09786248dfca/docs/guides/migrating-to-v3.mdx).
+- Upstream's internal store API advances from Rev3 to Rev4. It remains unstable.
+- The existing `INTERNAL_InferAtomTuples` type remains available from both utility entry points for compatibility.
+
+Readers no longer force a second render immediately after subscribing. `useSetAtom` still does not subscribe the writer. Hook slots are forwarded to keep multiple atom hooks in one component independent.
+
+## Async atoms and server rendering
+
+`useAtomValue` unwraps Jotai's stable continuable promises through Octane's `use()`. Use a Suspense boundary for pending values. Both raw hooks preserve the promise as a value.
 
-## Status
+Create a store per server request and pass it to `Provider`. Server rendering does not mount atom subscriptions. The hydration conformance test checks reuse of the server DOM, live client updates, and subscription teardown.
 
-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).
+See [UPSTREAM.md](./UPSTREAM.md) for the immutable source pin, API crosswalk, test adaptation, and recorded evidence.

package/UPSTREAM.md

@@ -0,0 +1,69 @@
+# Jotai upstream
+
+`@octanejs/jotai` ports the provider and React hooks from Jotai 3.0.0 and imports the framework-neutral core from `jotai/vanilla`, `/vanilla/utils`, and `/vanilla/internals`.
+
+## Immutable identity and license
+
+- Release: `jotai@3.0.0`
+- Commit: `89d4fddd1949628e50952fc8ac1b09786248dfca`
+- Source: https://github.com/pmndrs/jotai/tree/89d4fddd1949628e50952fc8ac1b09786248dfca
+- MIT license: exact upstream bytes in packaged `LICENSE.upstream`; SHA-256 `0530d5d58026f4bb73367d195946f6a516a648ea62dd8b84763318f64d3cb3e2`.
+- npm integrity: `sha512-KxhbmsJUp/tmrv6aZgO+nzB3H9K8C0xmk5i3aGkwy/EANg73DVBkggv3zVHaAi5PlNlQgTgP4uiVepo+JC+wSA==`.
+- npm archive SHA-256: `dc9cfb4c901424eea4be448048a274c56472ab0956ee4e4e7d1623bc98e4ef00`.
+- Signed npm provenance resolves the release tag to this commit; npm does not publish a `gitHead` for this release.
+- Tested dependency: 3.0.0; supported catalog range: `^3.0.0`.
+- React runtime oracle: React and React DOM 19.2.7. Original type compiler: TypeScript 6.0.3, with React types 19.2.18 and React DOM types 19.2.7.
+
+`audit/upstream.lock.json` authenticates the byte-exact repository source and tests under `upstream/`. The npm artifact is retained for published-declaration verification. Neither tree is published. Vanilla source appears only in the pristine test environment; runtime code imports the installed upstream dependency.
+
+## Complete export crosswalk
+
+The table includes runtime and type exports from every published runtime entry. Root and vanilla utilities import the same upstream implementation. Provider/hooks and the four hook utilities are adapted to Octane. All seven entries have exact runtime export-set checks and positive public type assertions in `tests/types/public.ts`, including upstream's unstable `INTERNAL_*` exports. Package metadata describes the Octane package itself.
+
+| Entry | Exports | Disposition |
+| --- | --- | --- |
+| `@octanejs/jotai` | `Atom`, `ExtractAtomArgs`, `ExtractAtomResult`, `ExtractAtomValue`, `Getter`, `INTERNAL_overrideCreateStore`, `PrimitiveAtom`, `Provider`, `SetStateAction`, `Setter`, `WritableAtom`, `atom`, `createStore`, `getDefaultStore`, `useAtom`, `useAtomValue`, `useAtomValueRaw`, `useAtomValueRawSync`, `useSetAtom`, `useStore` | Imported vanilla exports plus ported hooks/provider. |
+| `@octanejs/jotai/utils` | `RESET`, `atomWithDefault`, `atomWithLazy`, `atomWithObservable`, `atomWithReducer`, `atomWithRefresh`, `atomWithReset`, `atomWithStorage`, `createJSONStorage`, `freezeAtom`, `freezeAtomCreator`, `selectAtom`, `splitAtom`, `unstable_withStorageValidator`, `unwrap`, `useAtomCallback`, `useHydrateAtoms`, `useReducerAtom`, `useResetAtom` | Imported vanilla exports plus ported hooks/provider. |
+| `@octanejs/jotai/vanilla` | `Atom`, `ExtractAtomArgs`, `ExtractAtomResult`, `ExtractAtomValue`, `Getter`, `INTERNAL_overrideCreateStore`, `PrimitiveAtom`, `SetStateAction`, `Setter`, `WritableAtom`, `atom`, `createStore`, `getDefaultStore` | Imported from the matching Jotai vanilla entry. |
+| `@octanejs/jotai/vanilla/utils` | `RESET`, `atomWithDefault`, `atomWithLazy`, `atomWithObservable`, `atomWithReducer`, `atomWithRefresh`, `atomWithReset`, `atomWithStorage`, `createJSONStorage`, `freezeAtom`, `freezeAtomCreator`, `selectAtom`, `splitAtom`, `unstable_withStorageValidator`, `unwrap` | Imported from the matching Jotai vanilla entry. |
+| `@octanejs/jotai/vanilla/internals` | `INTERNAL_AtomOnInit`, `INTERNAL_AtomOnMount`, `INTERNAL_AtomRead`, `INTERNAL_AtomState`, `INTERNAL_AtomStateMap`, `INTERNAL_AtomWrite`, `INTERNAL_BuildingBlocks`, `INTERNAL_Callbacks`, `INTERNAL_ChangedAtoms`, `INTERNAL_EnsureAtomState`, `INTERNAL_FlushCallbacks`, `INTERNAL_InvalidateDependents`, `INTERNAL_InvalidatedAtoms`, `INTERNAL_KEY_abortHandlersMap`, `INTERNAL_KEY_abortPromise`, `INTERNAL_KEY_atomOnInit`, `INTERNAL_KEY_atomOnMount`, `INTERNAL_KEY_atomRead`, `INTERNAL_KEY_atomStateMap`, `INTERNAL_KEY_atomWrite`, `INTERNAL_KEY_changedAtoms`, `INTERNAL_KEY_enhanceBuildingBlocks`, `INTERNAL_KEY_ensureAtomState`, `INTERNAL_KEY_flushCallbacks`, `INTERNAL_KEY_invalidateDependents`, `INTERNAL_KEY_invalidatedAtoms`, `INTERNAL_KEY_mountAtom`, `INTERNAL_KEY_mountCallbacks`, `INTERNAL_KEY_mountDependencies`, `INTERNAL_KEY_mountedMap`, `INTERNAL_KEY_readAtomState`, `INTERNAL_KEY_recomputeInvalidatedAtoms`, `INTERNAL_KEY_registerAbortHandler`, `INTERNAL_KEY_setAtomStateValueOrPromise`, `INTERNAL_KEY_storeEpochHolder`, `INTERNAL_KEY_storeGet`, `INTERNAL_KEY_storeHooks`, `INTERNAL_KEY_storeSet`, `INTERNAL_KEY_storeSub`, `INTERNAL_KEY_unmountAtom`, `INTERNAL_KEY_unmountCallbacks`, `INTERNAL_KEY_writeAtomState`, `INTERNAL_MountAtom`, `INTERNAL_MountDependencies`, `INTERNAL_Mounted`, `INTERNAL_MountedMap`, `INTERNAL_ReadAtomState`, `INTERNAL_RecomputeInvalidatedAtoms`, `INTERNAL_Store`, `INTERNAL_StoreHooks`, `INTERNAL_UnmountAtom`, `INTERNAL_WriteAtomState`, `INTERNAL_addPendingPromiseToDependency`, `INTERNAL_buildStoreRev4`, `INTERNAL_getBuildingBlocksRev4`, `INTERNAL_getMountedOrPendingDependents`, `INTERNAL_hasInitialValue`, `INTERNAL_initializeStoreHooksRev4`, `INTERNAL_isActuallyWritableAtom`, `INTERNAL_isAtomStateInitialized`, `INTERNAL_isPromiseLike`, `INTERNAL_returnAtomValue`, `INTERNAL_shouldThrowSynchronously` | Imported from the matching Jotai vanilla entry. |
+| `@octanejs/jotai/react` | `Provider`, `useAtom`, `useAtomValue`, `useAtomValueRaw`, `useAtomValueRawSync`, `useSetAtom`, `useStore` | Ported hooks/provider. |
+| `@octanejs/jotai/react/utils` | `useAtomCallback`, `useHydrateAtoms`, `useReducerAtom`, `useResetAtom` | Ported hooks/provider. |
+
+## Source boundary
+
+`src/react/Provider.tsrx` and `src/react/store.ts` correspond to upstream `src/react/Provider.ts`. `src/react/utils.ts` retains the four modules under upstream `src/react/utils/`. Other hook and continuable-promise modules preserve upstream layout. `src/internal.ts` supplies the Octane call-site slot adaptation. `audit/source-ledger.json` records hashes for the complete shipped closure and identifies the adapted boundary.
+
+Octane's `use()` handles Suspense; React 18's fallback is unnecessary. Raw hook subscriptions and the Rev4 abort-handler protocol follow Jotai 3. Provider context is deduplicated by renderer identity, retaining the existing Octane binding contract. Providers render one stable JSX shape when the store prop changes.
+
+The migration removes `delay`, `loadable`, `atomFamily`, the atom-read `setSelf` option, and Rev3 internals, as upstream did. The existing `INTERNAL_InferAtomTuples` utility export is retained for compatibility and checked against Jotai's published `dist/react/utils/useHydrateAtoms.d.ts` declaration. See README for consumer guidance.
+
+## Complete upstream test crosswalk
+
+`audit/registrations.json` preserves all 404 immutable registrations across 44 test files. `audit/crosswalk.json` maps each registration to its generated Octane test file. Both pristine and adapted runtime suites execute all 404 registrations without skips. Eleven registrations in the four explicit type-test files are additionally compiled in separate pristine and adapted programs; the hydration utility suite's negative type controls are also compiled.
+
+The committed lock generates ignored `tests/upstream/`. Import repointing and the Octane JSX pragma are mechanical rewrites. Committed patches contain only these test adaptations:
+
+- React class error boundaries become functional Octane error boundaries, preserving the error, fallback and retry assertions.
+- Commit-count hooks move from JSX child expressions into component setup so they observe the owning component. Their effects use explicit `null` dependencies for the original every-render observation.
+- The observable error-boundary fixture moves to module scope for Octane compilation.
+
+The pristine type lane preserves upstream's `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes`. The adapted lane uses the repository's strict configuration without these additional flags because imported Octane runtime source does not satisfy them. Both lanes retain `strict: true`, `skipLibCheck: false`, every upstream positive assertion, and every negative control.
+
+`audit/react-parity.json` registers pristine/adapted runtime and type lanes, the four existing React/Octane differential scenarios, and the SSR/hydration conformance scenario. The latter proves no server subscriptions, existing DOM adoption, click/external-store updates, and teardown. Conformance checks additionally cover slot identity, provider scope/swap, subscription cleanup, async rejection/resolution and utilities.
+
+## Reproduce evidence
+
+```sh
+node scripts/react-port/materialize.mjs run --package-dir packages/jotai
+node scripts/react-parity/verify-provenance.mjs --package-dir packages/jotai
+pnpm --dir packages/jotai test
+node scripts/react-parity/harness.mjs run-required --manifest packages/jotai/audit/react-parity.json
+./packages/jotai/node_modules/.bin/tsc --noEmit -p packages/jotai/tsconfig.pristine.json
+pnpm exec tsrx-tsc --noEmit -p packages/jotai/tsconfig.adapted.json
+pnpm exec tsrx-tsc --noEmit -p packages/jotai/tsconfig.json
+pnpm exec tsrx-tsc --noEmit -p packages/jotai/tests/types/tsconfig.json
+pnpm packages:pack:check
+```
+
+The shared port evidence gate records the actual commands and verifies the package contract, licenses, crosswalk, and shipped closure. The declared imported surfaces retain dependency, exports, public types and consumer checks; copied React surfaces retain their full upstream suite obligations. The ownership declaration does not remove prior evidence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/jotai",
-  "version": "0.1.49",
+  "version": "0.1.51",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -31,7 +31,10 @@
   "types": "src/index.ts",
   "files": [
     "src",
-    "README.md"
+    "README.md",
+    "UPSTREAM.md",
+    "LICENSE",
+    "LICENSE.upstream"
   ],
   "exports": {
     ".": "./src/index.ts",
@@ -43,20 +46,34 @@
     "./utils": "./src/utils.ts"
   },
   "dependencies": {
-    "jotai": "^2.20.2"
+    "jotai": "^3.0.0"
   },
   "peerDependencies": {
-    "octane": "^0.1.51 || ^0.2.0"
+    "octane": "^0.1.51 || ^0.2.0 || ^0.3.0"
   },
   "devDependencies": {
-    "@tsrx/react": "^0.2.63",
+    "@tsrx/react": "^0.3.0",
     "esbuild": "^0.28.1",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
     "vitest": "^4.1.10",
-    "octane": "0.2.0"
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/jest-dom": "^6.9.1",
+    "rxjs": "^7.8.2",
+    "wonka": "6.3.6",
+    "jest-leak-detector": "30.5.1",
+    "@types/node": "^24.13.3",
+    "vite": "^8.1.5",
+    "typescript": "6.0.3",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.7",
+    "@octanejs/testing-library": "0.1.52",
+    "octane": "0.3.0"
   },
   "scripts": {
-    "test": "vitest run"
+    "test": "vitest run --root ../.. --config vitest.config.js --project jotai --project jotai-differential --project jotai-pristine --project jotai-hydration",
+    "upstream:check": "node ../../scripts/react-port/materialize.mjs run --check --package-dir .",
+    "upstream:test": "node ../../scripts/react-parity/run-pristine.mjs jotai",
+    "upstream:verify": "node ../../scripts/react-parity/verify-provenance.mjs --package-dir ."
   }
 }

package/src/index.ts

@@ -1,20 +1,3 @@
-// @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.
+// Jotai 3 vanilla exports and Octane provider/hooks.
 export * from './vanilla';
 export * from './react';

package/src/react/Provider.tsrx

@@ -7,7 +7,7 @@ import { useRef, type OctaneNode } from 'octane';
 import { createStore } from 'jotai/vanilla';
 import { StoreContext, type Store } from './store.ts';
 
-export function Provider(props: { children?: OctaneNode; store?: Store }) @{
+export function Provider(props: { children?: OctaneNode; store?: Store }) {
 	const { children, store } = props;
 
 	const storeRef = useRef<Store | null>(null);
@@ -15,5 +15,5 @@ export function Provider(props: { children?: OctaneNode; store?: Store }) @{
 		storeRef.current = createStore();
 	}
 
-	<StoreContext.Provider value={store || storeRef.current!}>{children}</StoreContext.Provider>
+	return <StoreContext value={store || storeRef.current!}>{children}</StoreContext>;
 }

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

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

package/src/react/continuablePromise.ts

@@ -0,0 +1,54 @@
+import {
+	INTERNAL_getBuildingBlocksRev4 as INTERNAL_getBuildingBlocks,
+	INTERNAL_KEY_registerAbortHandler as KEY_registerAbortHandler,
+} from 'jotai/vanilla/internals';
+import type { INTERNAL_Store as Store } from 'jotai/vanilla/internals';
+
+export const isPromiseLike = (x: unknown): x is PromiseLike<unknown> =>
+	typeof (x as PromiseLike<unknown>)?.then === 'function';
+
+const continuablePromiseMap = new WeakMap<PromiseLike<unknown>, Promise<unknown>>();
+
+export const createContinuablePromise = <T>(
+	store: Store,
+	promise: PromiseLike<T>,
+	getValue: () => PromiseLike<T> | T,
+): Promise<unknown> => {
+	const buildingBlocks = INTERNAL_getBuildingBlocks(store);
+	const registerAbortHandler = buildingBlocks[KEY_registerAbortHandler];
+	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;
+};

package/src/react/useAtomValue.ts

@@ -1,37 +1,10 @@
-// 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';
+// Jotai 3 separates the concurrent raw subscription from Suspense unwrapping.
+import { use } from 'octane';
 import type { Atom, ExtractAtomValue } from 'jotai/vanilla';
-import { useStore, type Store } from './store';
+import { isPromiseLike } from './continuablePromise';
+import { useAtomValueRaw } from './useAtomValueRaw';
 import { splitSlot, subSlot } from '../internal';
 
-// The consumer's bundler substitutes the whole `process.env.NODE_ENV` expression
-// below, so it must stay written out literally. Declared module-locally — never
-// `declare global`, which would ship in the tarball — so this file type-checks in
-// a browser app that has no `@types/node`.
-declare const process: { env: { NODE_ENV?: string } };
-
-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';
@@ -54,136 +27,30 @@ const attachPromiseStatus = <T>(
 	}
 };
 
-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;
+type Options = Parameters<typeof useAtomValueRaw>[1] & {
 	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'),
+	const value = (useAtomValueRaw as <T>(a: Atom<T>, o?: Options, s?: symbol) => T)(
+		atom,
+		options,
+		subSlot(slot, 'value:raw'),
 	);
-
-	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);
+		// Octane always provides use(); upstream's React 18 fallback is unnecessary.
+		if (options?.unstable_promiseStatus) attachPromiseStatus(value);
+		return use(value);
 	}
 	return value as Awaited<Value>;
 }

package/src/react/useAtomValueRaw.ts

@@ -0,0 +1,53 @@
+import { useDebugValue, useEffect, useReducer } from 'octane';
+import type { Atom, ExtractAtomValue } from 'jotai/vanilla';
+import { createContinuablePromise, isPromiseLike } from './continuablePromise';
+import { useStore } from './store';
+
+import { splitSlot, subSlot } from '../internal';
+
+type Store = ReturnType<typeof useStore>;
+
+type Options = Parameters<typeof useStore>[0];
+
+export function useAtomValueRaw<Value>(atom: Atom<Value>, options?: Options): Value;
+
+export function useAtomValueRaw<AtomType extends Atom<unknown>>(
+	atom: AtomType,
+	options?: Options,
+): ExtractAtomValue<AtomType>;
+
+export function useAtomValueRaw<Value>(
+	atom: Atom<Value>,
+	...rest: [options?: Options, slot?: symbol]
+) {
+	const [user, slot] = splitSlot(rest);
+	const options = user[0] as Options | undefined;
+	const store = useStore(options);
+	const [[valueFromReducer, storeFromReducer, atomFromReducer], rerender] = useReducer<
+		readonly [Value, Store, typeof atom],
+		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, 'raw:reducer'),
+	);
+	let value = valueFromReducer;
+	if (storeFromReducer !== store || atomFromReducer !== atom) {
+		rerender();
+		value = store.get(atom);
+	}
+	useEffect(() => store.sub(atom, rerender), [store, atom], subSlot(slot, 'raw:effect'));
+	useDebugValue(value);
+	if (isPromiseLike(value)) {
+		return createContinuablePromise(store, value, () => store.get(atom));
+	}
+	return value;
+}

package/src/react/useAtomValueRawSync.ts

@@ -0,0 +1,47 @@
+import { useCallback, useDebugValue, useSyncExternalStore } from 'octane';
+import type { Atom, ExtractAtomValue } from 'jotai/vanilla';
+import { createContinuablePromise, isPromiseLike } from './continuablePromise';
+import { useStore } from './store';
+
+import { splitSlot, subSlot } from '../internal';
+
+type Options = Parameters<typeof useStore>[0];
+
+export function useAtomValueRawSync<Value>(atom: Atom<Value>, options?: Options): Value;
+
+export function useAtomValueRawSync<AtomType extends Atom<unknown>>(
+	atom: AtomType,
+	options?: Options,
+): ExtractAtomValue<AtomType>;
+
+export function useAtomValueRawSync<Value>(
+	atom: Atom<Value>,
+	...rest: [options?: Options, slot?: symbol]
+) {
+	const [user, slot] = splitSlot(rest);
+	const options = user[0] as Options | undefined;
+	const store = useStore(options);
+	const getSnapshot = useCallback(
+		() => {
+			const value = store.get(atom);
+			if (isPromiseLike(value)) {
+				return createContinuablePromise(store, value, () => store.get(atom));
+			}
+			return value;
+		},
+		[store, atom],
+		subSlot(slot, 'sync:snapshot'),
+	);
+	const value = useSyncExternalStore(
+		useCallback(
+			(callback: () => void) => store.sub(atom, callback),
+			[store, atom],
+			subSlot(slot, 'sync:subscribe'),
+		),
+		getSnapshot,
+		getSnapshot,
+		subSlot(slot, 'sync:store'),
+	);
+	useDebugValue(value);
+	return value;
+}

package/src/react/utils.ts

@@ -128,8 +128,6 @@ type InferAtomTuples<T> = {
 		: 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();

package/src/react.ts

@@ -1,10 +1,7 @@
-// `@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';
+export { useAtomValueRaw } from './react/useAtomValueRaw';
+export { useAtomValueRawSync } from './react/useAtomValueRawSync';

package/src/vanilla/utils.ts

@@ -1,8 +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
+// atomWithReducer, atomWithRefresh, atomWithLazy, atomWithObservable,
+// selectAtom, splitAtom, 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';