@pumped-fn/lite-react 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# @pumped-fn/lite-react
+
+## 1.0.0
+
+### Major Changes
+
+- 236aa4a: Rename packages to follow `lite-` prefix convention
+
+  **Breaking Change:** Package names have been renamed:
+
+  - `@pumped-fn/devtools` → `@pumped-fn/lite-devtools`
+  - `@pumped-fn/react-lite` → `@pumped-fn/lite-react`
+  - `@pumped-fn/vite-hmr` → `@pumped-fn/lite-hmr`
+
+  This establishes a consistent naming convention where all packages in the lite ecosystem use the `lite-` prefix.
+
+  **Migration:**
+
+  ```bash
+  # Update your dependencies
+  pnpm remove @pumped-fn/devtools @pumped-fn/react-lite @pumped-fn/vite-hmr
+  pnpm add @pumped-fn/lite-devtools @pumped-fn/lite-react @pumped-fn/lite-hmr
+  ```
+
+  ```typescript
+  // Update imports
+  - import { createDevtools } from '@pumped-fn/devtools'
+  + import { createDevtools } from '@pumped-fn/lite-devtools'
+
+  - import { ScopeProvider, useAtom } from '@pumped-fn/react-lite'
+  + import { ScopeProvider, useAtom } from '@pumped-fn/lite-react'
+
+  - import { pumpedHmr } from '@pumped-fn/vite-hmr'
+  + import { pumpedHmr } from '@pumped-fn/lite-hmr'
+  ```
+
+## 0.3.0
+
+### Minor Changes
+
+- a0362d7: ### Features
+
+  - Re-export `createScope`, `atom`, `flow`, `preset` from `@pumped-fn/lite` for convenience
+  - Update React peer dependency to support both React 18 and React 19 (`^18.0.0 || ^19.0.0`)
+
+  ### Bug Fixes
+
+  - **Critical**: Fix Suspense infinite loop by caching pending promises (React expects same promise during re-renders)
+  - Auto-resolve idle atoms lazily instead of throwing error (more ergonomic)
+  - Subscribe only to `resolved` events instead of `*` to avoid unnecessary re-renders
+
+## 0.2.0
+
+### Minor Changes
+
+- 1587c37: feat(lite-react): initial release of React integration for @pumped-fn/lite
+
+  Adds minimal React bindings with Suspense and ErrorBoundary integration:
+
+  - ScopeProvider and ScopeContext for scope provisioning
+  - useScope hook for accessing scope from context
+  - useController hook for obtaining memoized controllers
+  - useAtom hook with full Suspense/ErrorBoundary integration
+  - useSelect hook for fine-grained reactivity with custom equality
+
+  SSR-compatible, zero-tolerance for `any` types, comprehensive TSDoc.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License Copyright (c) 2025 Duke
+
+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
+(including the next paragraph) 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,192 @@
+# @pumped-fn/lite-react
+
+React bindings for `@pumped-fn/lite` with Suspense and ErrorBoundary integration.
+
+**Zero dependencies** · **<2KB bundle** · **React 18+**
+
+## How It Works
+
+```mermaid
+sequenceDiagram
+    participant App
+    participant ScopeProvider
+    participant useAtom
+    participant Controller
+
+    App->>App: scope.resolve(atom)
+    App->>ScopeProvider: <ScopeProvider scope={scope}>
+
+    useAtom->>Controller: check ctrl.state
+    alt resolved
+        Controller-->>useAtom: value
+        useAtom->>Controller: subscribe to changes
+    else resolving
+        useAtom-->>App: throw Promise (Suspense)
+    else failed
+        useAtom-->>App: throw Error (ErrorBoundary)
+    else idle
+        useAtom-->>App: throw Error (not resolved)
+    end
+```
+
+## State Handling
+
+```mermaid
+flowchart TD
+    Hook[useAtom/useSelect]
+    Hook --> State{ctrl.state?}
+
+    State -->|idle| AutoResolve[Auto-resolve + Throw Promise]
+    State -->|resolving| Promise[Throw cached Promise]
+    State -->|resolved| Value[Return value]
+    State -->|failed| Stored[Throw stored error]
+
+    AutoResolve --> Suspense[Suspense catches]
+    Promise --> Suspense
+    Stored --> ErrorBoundary[ErrorBoundary catches]
+```
+
+| State | Hook Behavior |
+|-------|---------------|
+| `idle` | Auto-resolves and suspends — Suspense shows fallback |
+| `resolving` | Throws cached promise — Suspense shows fallback |
+| `resolved` | Returns value, subscribes to changes |
+| `failed` | Throws stored error — ErrorBoundary catches |
+
+## API
+
+### ScopeProvider
+
+Provides scope to component tree.
+
+```tsx
+import { createScope } from '@pumped-fn/lite'
+import { ScopeProvider } from '@pumped-fn/lite-react'
+
+const scope = createScope()
+await scope.resolve(userAtom)
+
+<ScopeProvider scope={scope}>
+  <App />
+</ScopeProvider>
+```
+
+### useScope
+
+Access scope from context.
+
+```tsx
+const scope = useScope()
+await scope.resolve(someAtom)
+```
+
+### useController
+
+Get memoized controller for imperative operations.
+
+```tsx
+const ctrl = useController(counterAtom)
+ctrl.set(10)
+ctrl.update(n => n + 1)
+ctrl.invalidate()
+```
+
+### useAtom
+
+Subscribe to atom value with Suspense integration.
+
+```tsx
+function UserProfile() {
+  const user = useAtom(userAtom)
+  return <div>{user.name}</div>
+}
+
+// Wrap with Suspense + ErrorBoundary
+<ErrorBoundary fallback={<Error />}>
+  <Suspense fallback={<Loading />}>
+    <UserProfile />
+  </Suspense>
+</ErrorBoundary>
+```
+
+### useSelect
+
+Fine-grained selection — only re-renders when selected value changes.
+
+```tsx
+const name = useSelect(userAtom, user => user.name)
+const count = useSelect(todosAtom, todos => todos.length, (a, b) => a === b)
+```
+
+## Invalidation
+
+When an atom is invalidated, hooks automatically suspend during re-resolution:
+
+```mermaid
+sequenceDiagram
+    participant Component
+    participant useAtom
+    participant Controller
+
+    Note over Controller: state = resolved
+    Component->>useAtom: render (value)
+
+    Note over Controller: ctrl.invalidate()
+    Controller->>Controller: state = resolving
+    useAtom-->>Component: throw Promise
+    Note over Component: Suspense fallback
+
+    Controller->>Controller: factory runs
+    Controller->>Controller: state = resolved
+    useAtom->>Component: re-render (new value)
+```
+
+## Testing
+
+Use presets for test isolation:
+
+```tsx
+import { createScope, preset } from '@pumped-fn/lite'
+import { ScopeProvider } from '@pumped-fn/lite-react'
+
+const scope = createScope({
+  presets: [preset(userAtom, { name: 'Test User' })]
+})
+await scope.resolve(userAtom)
+
+render(
+  <ScopeProvider scope={scope}>
+    <UserProfile />
+  </ScopeProvider>
+)
+```
+
+## SSR
+
+SSR-compatible by design:
+
+- No side effects on import
+- Uses `useSyncExternalStore` with server snapshot
+- Scope passed as prop (no global state)
+
+```tsx
+// Server
+const scope = createScope()
+await scope.resolve(dataAtom)
+const html = renderToString(<ScopeProvider scope={scope}><App /></ScopeProvider>)
+
+// Client
+const clientScope = createScope({
+  presets: [preset(dataAtom, window.__DATA__)]
+})
+await clientScope.resolve(dataAtom)
+hydrateRoot(root, <ScopeProvider scope={clientScope}><App /></ScopeProvider>)
+```
+
+## Full API
+
+See [`dist/index.d.mts`](./dist/index.d.mts) for complete type definitions.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,173 @@
+let __pumped_fn_lite = require("@pumped-fn/lite");
+let react = require("react");
+let react_jsx_runtime = require("react/jsx-runtime");
+
+//#region src/context.tsx
+/**
+* React context for Lite.Scope.
+*/
+const ScopeContext = (0, react.createContext)(null);
+/**
+* Provider component for Lite.Scope.
+*
+* @example
+* ```tsx
+* <ScopeProvider scope={scope}>
+*   <App />
+* </ScopeProvider>
+* ```
+*/
+function ScopeProvider({ scope, children }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ScopeContext.Provider, {
+		value: scope,
+		children
+	});
+}
+
+//#endregion
+//#region src/hooks.ts
+const pendingPromises = /* @__PURE__ */ new WeakMap();
+function getOrCreatePendingPromise(atom$1, ctrl) {
+	let pending = pendingPromises.get(atom$1);
+	if (!pending) {
+		pending = ctrl.resolve();
+		pendingPromises.set(atom$1, pending);
+		pending.finally(() => pendingPromises.delete(atom$1));
+	}
+	return pending;
+}
+/**
+* Access the current Lite.Scope from context.
+*
+* @returns The current Lite.Scope instance from context
+* @throws When called outside of a ScopeProvider
+*
+* @example
+* ```tsx
+* const scope = useScope()
+* await scope.resolve(myAtom)
+* ```
+*/
+function useScope() {
+	const scope = (0, react.useContext)(ScopeContext);
+	if (!scope) throw new Error("useScope must be used within a ScopeProvider");
+	return scope;
+}
+/**
+* Get a memoized controller for an atom.
+*
+* @param atom - The atom to create a controller for
+* @returns A memoized Lite.Controller instance
+*
+* @example
+* ```tsx
+* const ctrl = useController(counterAtom)
+* ctrl.set(ctrl.get() + 1)
+* ```
+*/
+function useController(atom$1) {
+	const scope = useScope();
+	return (0, react.useMemo)(() => scope.controller(atom$1), [scope, atom$1]);
+}
+/**
+* Subscribe to atom value with Suspense/ErrorBoundary integration.
+* Auto-resolves atoms lazily and throws cached Promise for Suspense.
+*
+* @param atom - The atom to read
+* @returns The current value of the atom
+*
+* @example
+* ```tsx
+* function UserProfile() {
+*   const user = useAtom(userAtom)
+*   return <div>{user.name}</div>
+* }
+* ```
+*/
+function useAtom(atom$1) {
+	const ctrl = useController(atom$1);
+	const atomRef = (0, react.useRef)(atom$1);
+	atomRef.current = atom$1;
+	const getSnapshot = (0, react.useCallback)(() => {
+		const state = ctrl.state;
+		if (state === "idle" || state === "resolving") throw getOrCreatePendingPromise(atomRef.current, ctrl);
+		if (state === "failed") throw ctrl.get();
+		return ctrl.get();
+	}, [ctrl]);
+	return (0, react.useSyncExternalStore)((0, react.useCallback)((onStoreChange) => ctrl.on("resolved", onStoreChange), [ctrl]), getSnapshot, getSnapshot);
+}
+/**
+* Select a derived value from an atom with fine-grained reactivity.
+* Only re-renders when the selected value changes per equality function.
+*
+* @param atom - The atom to select from
+* @param selector - Function to extract a derived value
+* @param eq - Optional equality function
+* @returns The selected value
+*
+* @example
+* ```tsx
+* const name = useSelect(userAtom, user => user.name)
+* ```
+*/
+function useSelect(atom$1, selector, eq) {
+	const scope = useScope();
+	const ctrl = useController(atom$1);
+	const atomRef = (0, react.useRef)(atom$1);
+	atomRef.current = atom$1;
+	const selectorRef = (0, react.useRef)(selector);
+	const eqRef = (0, react.useRef)(eq);
+	selectorRef.current = selector;
+	eqRef.current = eq;
+	const handleRef = (0, react.useRef)(null);
+	const getOrCreateHandle = (0, react.useCallback)(() => {
+		if (!handleRef.current || handleRef.current.scope !== scope || handleRef.current.atom !== atom$1) handleRef.current = {
+			scope,
+			atom: atom$1,
+			handle: scope.select(atom$1, selectorRef.current, { eq: eqRef.current })
+		};
+		return handleRef.current.handle;
+	}, [scope, atom$1]);
+	const getSnapshot = (0, react.useCallback)(() => {
+		const state = ctrl.state;
+		if (state === "idle" || state === "resolving") throw getOrCreatePendingPromise(atomRef.current, ctrl);
+		if (state === "failed") throw ctrl.get();
+		return getOrCreateHandle().get();
+	}, [ctrl, getOrCreateHandle]);
+	return (0, react.useSyncExternalStore)((0, react.useCallback)((onStoreChange) => {
+		if (ctrl.state !== "resolved") return () => {};
+		return getOrCreateHandle().subscribe(onStoreChange);
+	}, [ctrl, getOrCreateHandle]), getSnapshot, getSnapshot);
+}
+
+//#endregion
+exports.ScopeContext = ScopeContext;
+exports.ScopeProvider = ScopeProvider;
+Object.defineProperty(exports, 'atom', {
+  enumerable: true,
+  get: function () {
+    return __pumped_fn_lite.atom;
+  }
+});
+Object.defineProperty(exports, 'createScope', {
+  enumerable: true,
+  get: function () {
+    return __pumped_fn_lite.createScope;
+  }
+});
+Object.defineProperty(exports, 'flow', {
+  enumerable: true,
+  get: function () {
+    return __pumped_fn_lite.flow;
+  }
+});
+Object.defineProperty(exports, 'preset', {
+  enumerable: true,
+  get: function () {
+    return __pumped_fn_lite.preset;
+  }
+});
+exports.useAtom = useAtom;
+exports.useController = useController;
+exports.useScope = useScope;
+exports.useSelect = useSelect;

package/dist/index.d.cts

@@ -0,0 +1,90 @@
+import { Lite, Lite as Lite$1, atom, createScope, flow, preset } from "@pumped-fn/lite";
+import * as react0 from "react";
+import { ReactNode } from "react";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/context.d.ts
+/**
+ * React context for Lite.Scope.
+ */
+declare const ScopeContext: react0.Context<Lite$1.Scope | null>;
+interface ScopeProviderProps {
+  scope: Lite$1.Scope;
+  children: ReactNode;
+}
+/**
+ * Provider component for Lite.Scope.
+ *
+ * @example
+ * ```tsx
+ * <ScopeProvider scope={scope}>
+ *   <App />
+ * </ScopeProvider>
+ * ```
+ */
+declare function ScopeProvider({
+  scope,
+  children
+}: ScopeProviderProps): react_jsx_runtime0.JSX.Element;
+//#endregion
+//#region src/hooks.d.ts
+/**
+ * Access the current Lite.Scope from context.
+ *
+ * @returns The current Lite.Scope instance from context
+ * @throws When called outside of a ScopeProvider
+ *
+ * @example
+ * ```tsx
+ * const scope = useScope()
+ * await scope.resolve(myAtom)
+ * ```
+ */
+declare function useScope(): Lite$1.Scope;
+/**
+ * Get a memoized controller for an atom.
+ *
+ * @param atom - The atom to create a controller for
+ * @returns A memoized Lite.Controller instance
+ *
+ * @example
+ * ```tsx
+ * const ctrl = useController(counterAtom)
+ * ctrl.set(ctrl.get() + 1)
+ * ```
+ */
+declare function useController<T>(atom: Lite$1.Atom<T>): Lite$1.Controller<T>;
+/**
+ * Subscribe to atom value with Suspense/ErrorBoundary integration.
+ * Auto-resolves atoms lazily and throws cached Promise for Suspense.
+ *
+ * @param atom - The atom to read
+ * @returns The current value of the atom
+ *
+ * @example
+ * ```tsx
+ * function UserProfile() {
+ *   const user = useAtom(userAtom)
+ *   return <div>{user.name}</div>
+ * }
+ * ```
+ */
+declare function useAtom<T>(atom: Lite$1.Atom<T>): T;
+/**
+ * Select a derived value from an atom with fine-grained reactivity.
+ * Only re-renders when the selected value changes per equality function.
+ *
+ * @param atom - The atom to select from
+ * @param selector - Function to extract a derived value
+ * @param eq - Optional equality function
+ * @returns The selected value
+ *
+ * @example
+ * ```tsx
+ * const name = useSelect(userAtom, user => user.name)
+ * ```
+ */
+declare function useSelect<T, S>(atom: Lite$1.Atom<T>, selector: (value: T) => S, eq?: (a: S, b: S) => boolean): S;
+//#endregion
+export { type Lite, ScopeContext, ScopeProvider, type ScopeProviderProps, atom, createScope, flow, preset, useAtom, useController, useScope, useSelect };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/context.tsx","../src/hooks.ts"],"sourcesContent":[],"mappings":";;;;;;;;;cAMM,cAAY,MAAA,CAAA,QAAA,MAAA,CAAA;AALyB,UAOjC,kBAAA,CAFiD;EAEjD,KAAA,EACD,MAAA,CAAK,KADJ;EAeD,QAAA,EAbG,SAaU;;;;;;;;;ACtBqB;AA2BZ;;iBDLtB,aAAA,CCyB4B;EAAA,KAAA;EAAA;AAAA,CAAA,EDzBO,kBCyBP,CAAA,EDzByB,kBAAA,CAAA,GAAA,CAAA,OCyBzB;;;;;;;;AD/CM;AAKzB;AAIG;;;;;iBCkBZ,QAAA,CAAA,CDLqD,ECKzC,MAAA,CAAK,KDLoC;;;;ACtBnB;AA2BZ;;;;;;AAoB+B;;iBAArD,aAoBsB,CAAA,CAAA,CAAA,CAAA,IAAA,EApBC,MAAA,CAAK,IAoBN,CApBW,CAoBX,CAAA,CAAA,EApBgB,MAAA,CAAK,UAoBrB,CApBgC,CAoBhC,CAAA;;;AAAW;;;;;;;;;;;;;iBAAjC,iBAAiB,MAAA,CAAK,KAAK,KAAK;;;;;;;;;;;;;;;iBAsChC,sBACD,MAAA,CAAK,KAAK,sBACE,MAAM,YACf,MAAM,gBACd"}

package/dist/index.d.mts

@@ -0,0 +1,90 @@
+import { Lite, Lite as Lite$1, atom, createScope, flow, preset } from "@pumped-fn/lite";
+import * as react0 from "react";
+import { ReactNode } from "react";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/context.d.ts
+/**
+ * React context for Lite.Scope.
+ */
+declare const ScopeContext: react0.Context<Lite$1.Scope | null>;
+interface ScopeProviderProps {
+  scope: Lite$1.Scope;
+  children: ReactNode;
+}
+/**
+ * Provider component for Lite.Scope.
+ *
+ * @example
+ * ```tsx
+ * <ScopeProvider scope={scope}>
+ *   <App />
+ * </ScopeProvider>
+ * ```
+ */
+declare function ScopeProvider({
+  scope,
+  children
+}: ScopeProviderProps): react_jsx_runtime0.JSX.Element;
+//#endregion
+//#region src/hooks.d.ts
+/**
+ * Access the current Lite.Scope from context.
+ *
+ * @returns The current Lite.Scope instance from context
+ * @throws When called outside of a ScopeProvider
+ *
+ * @example
+ * ```tsx
+ * const scope = useScope()
+ * await scope.resolve(myAtom)
+ * ```
+ */
+declare function useScope(): Lite$1.Scope;
+/**
+ * Get a memoized controller for an atom.
+ *
+ * @param atom - The atom to create a controller for
+ * @returns A memoized Lite.Controller instance
+ *
+ * @example
+ * ```tsx
+ * const ctrl = useController(counterAtom)
+ * ctrl.set(ctrl.get() + 1)
+ * ```
+ */
+declare function useController<T>(atom: Lite$1.Atom<T>): Lite$1.Controller<T>;
+/**
+ * Subscribe to atom value with Suspense/ErrorBoundary integration.
+ * Auto-resolves atoms lazily and throws cached Promise for Suspense.
+ *
+ * @param atom - The atom to read
+ * @returns The current value of the atom
+ *
+ * @example
+ * ```tsx
+ * function UserProfile() {
+ *   const user = useAtom(userAtom)
+ *   return <div>{user.name}</div>
+ * }
+ * ```
+ */
+declare function useAtom<T>(atom: Lite$1.Atom<T>): T;
+/**
+ * Select a derived value from an atom with fine-grained reactivity.
+ * Only re-renders when the selected value changes per equality function.
+ *
+ * @param atom - The atom to select from
+ * @param selector - Function to extract a derived value
+ * @param eq - Optional equality function
+ * @returns The selected value
+ *
+ * @example
+ * ```tsx
+ * const name = useSelect(userAtom, user => user.name)
+ * ```
+ */
+declare function useSelect<T, S>(atom: Lite$1.Atom<T>, selector: (value: T) => S, eq?: (a: S, b: S) => boolean): S;
+//#endregion
+export { type Lite, ScopeContext, ScopeProvider, type ScopeProviderProps, atom, createScope, flow, preset, useAtom, useController, useScope, useSelect };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/context.tsx","../src/hooks.ts"],"sourcesContent":[],"mappings":";;;;;;;;;cAMM,cAAY,MAAA,CAAA,QAAA,MAAA,CAAA;AALyB,UAOjC,kBAAA,CAFiD;EAEjD,KAAA,EACD,MAAA,CAAK,KADJ;EAeD,QAAA,EAbG,SAaU;;;;;;;;;ACtBqB;AA2BZ;;iBDLtB,aAAA,CCyB4B;EAAA,KAAA;EAAA;AAAA,CAAA,EDzBO,kBCyBP,CAAA,EDzByB,kBAAA,CAAA,GAAA,CAAA,OCyBzB;;;;;;;;AD/CM;AAKzB;AAIG;;;;;iBCkBZ,QAAA,CAAA,CDLqD,ECKzC,MAAA,CAAK,KDLoC;;;;ACtBnB;AA2BZ;;;;;;AAoB+B;;iBAArD,aAoBsB,CAAA,CAAA,CAAA,CAAA,IAAA,EApBC,MAAA,CAAK,IAoBN,CApBW,CAoBX,CAAA,CAAA,EApBgB,MAAA,CAAK,UAoBrB,CApBgC,CAoBhC,CAAA;;;AAAW;;;;;;;;;;;;;iBAAjC,iBAAiB,MAAA,CAAK,KAAK,KAAK;;;;;;;;;;;;;;;iBAsChC,sBACD,MAAA,CAAK,KAAK,sBACE,MAAM,YACf,MAAM,gBACd"}

package/dist/index.mjs

@@ -0,0 +1,145 @@
+import { atom, createScope, flow, preset } from "@pumped-fn/lite";
+import { createContext, useCallback, useContext, useMemo, useRef, useSyncExternalStore } from "react";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/context.tsx
+/**
+* React context for Lite.Scope.
+*/
+const ScopeContext = createContext(null);
+/**
+* Provider component for Lite.Scope.
+*
+* @example
+* ```tsx
+* <ScopeProvider scope={scope}>
+*   <App />
+* </ScopeProvider>
+* ```
+*/
+function ScopeProvider({ scope, children }) {
+	return /* @__PURE__ */ jsx(ScopeContext.Provider, {
+		value: scope,
+		children
+	});
+}
+
+//#endregion
+//#region src/hooks.ts
+const pendingPromises = /* @__PURE__ */ new WeakMap();
+function getOrCreatePendingPromise(atom$1, ctrl) {
+	let pending = pendingPromises.get(atom$1);
+	if (!pending) {
+		pending = ctrl.resolve();
+		pendingPromises.set(atom$1, pending);
+		pending.finally(() => pendingPromises.delete(atom$1));
+	}
+	return pending;
+}
+/**
+* Access the current Lite.Scope from context.
+*
+* @returns The current Lite.Scope instance from context
+* @throws When called outside of a ScopeProvider
+*
+* @example
+* ```tsx
+* const scope = useScope()
+* await scope.resolve(myAtom)
+* ```
+*/
+function useScope() {
+	const scope = useContext(ScopeContext);
+	if (!scope) throw new Error("useScope must be used within a ScopeProvider");
+	return scope;
+}
+/**
+* Get a memoized controller for an atom.
+*
+* @param atom - The atom to create a controller for
+* @returns A memoized Lite.Controller instance
+*
+* @example
+* ```tsx
+* const ctrl = useController(counterAtom)
+* ctrl.set(ctrl.get() + 1)
+* ```
+*/
+function useController(atom$1) {
+	const scope = useScope();
+	return useMemo(() => scope.controller(atom$1), [scope, atom$1]);
+}
+/**
+* Subscribe to atom value with Suspense/ErrorBoundary integration.
+* Auto-resolves atoms lazily and throws cached Promise for Suspense.
+*
+* @param atom - The atom to read
+* @returns The current value of the atom
+*
+* @example
+* ```tsx
+* function UserProfile() {
+*   const user = useAtom(userAtom)
+*   return <div>{user.name}</div>
+* }
+* ```
+*/
+function useAtom(atom$1) {
+	const ctrl = useController(atom$1);
+	const atomRef = useRef(atom$1);
+	atomRef.current = atom$1;
+	const getSnapshot = useCallback(() => {
+		const state = ctrl.state;
+		if (state === "idle" || state === "resolving") throw getOrCreatePendingPromise(atomRef.current, ctrl);
+		if (state === "failed") throw ctrl.get();
+		return ctrl.get();
+	}, [ctrl]);
+	return useSyncExternalStore(useCallback((onStoreChange) => ctrl.on("resolved", onStoreChange), [ctrl]), getSnapshot, getSnapshot);
+}
+/**
+* Select a derived value from an atom with fine-grained reactivity.
+* Only re-renders when the selected value changes per equality function.
+*
+* @param atom - The atom to select from
+* @param selector - Function to extract a derived value
+* @param eq - Optional equality function
+* @returns The selected value
+*
+* @example
+* ```tsx
+* const name = useSelect(userAtom, user => user.name)
+* ```
+*/
+function useSelect(atom$1, selector, eq) {
+	const scope = useScope();
+	const ctrl = useController(atom$1);
+	const atomRef = useRef(atom$1);
+	atomRef.current = atom$1;
+	const selectorRef = useRef(selector);
+	const eqRef = useRef(eq);
+	selectorRef.current = selector;
+	eqRef.current = eq;
+	const handleRef = useRef(null);
+	const getOrCreateHandle = useCallback(() => {
+		if (!handleRef.current || handleRef.current.scope !== scope || handleRef.current.atom !== atom$1) handleRef.current = {
+			scope,
+			atom: atom$1,
+			handle: scope.select(atom$1, selectorRef.current, { eq: eqRef.current })
+		};
+		return handleRef.current.handle;
+	}, [scope, atom$1]);
+	const getSnapshot = useCallback(() => {
+		const state = ctrl.state;
+		if (state === "idle" || state === "resolving") throw getOrCreatePendingPromise(atomRef.current, ctrl);
+		if (state === "failed") throw ctrl.get();
+		return getOrCreateHandle().get();
+	}, [ctrl, getOrCreateHandle]);
+	return useSyncExternalStore(useCallback((onStoreChange) => {
+		if (ctrl.state !== "resolved") return () => {};
+		return getOrCreateHandle().subscribe(onStoreChange);
+	}, [ctrl, getOrCreateHandle]), getSnapshot, getSnapshot);
+}
+
+//#endregion
+export { ScopeContext, ScopeProvider, atom, createScope, flow, preset, useAtom, useController, useScope, useSelect };
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":["atom"],"sources":["../src/context.tsx","../src/hooks.ts"],"sourcesContent":["import { createContext, type ReactNode } from 'react'\nimport { type Lite } from '@pumped-fn/lite'\n\n/**\n * React context for Lite.Scope.\n */\nconst ScopeContext = createContext<Lite.Scope | null>(null)\n\ninterface ScopeProviderProps {\n  scope: Lite.Scope\n  children: ReactNode\n}\n\n/**\n * Provider component for Lite.Scope.\n *\n * @example\n * ```tsx\n * <ScopeProvider scope={scope}>\n *   <App />\n * </ScopeProvider>\n * ```\n */\nfunction ScopeProvider({ scope, children }: ScopeProviderProps) {\n  return (\n    <ScopeContext.Provider value={scope}>\n      {children}\n    </ScopeContext.Provider>\n  )\n}\n\nexport { ScopeContext, ScopeProvider }\nexport type { ScopeProviderProps }\n","import { useCallback, useContext, useMemo, useRef, useSyncExternalStore } from 'react'\nimport { type Lite } from '@pumped-fn/lite'\nimport { ScopeContext } from './context'\n\nconst pendingPromises = new WeakMap<Lite.Atom<unknown>, Promise<unknown>>()\n\nfunction getOrCreatePendingPromise<T>(atom: Lite.Atom<T>, ctrl: Lite.Controller<T>): Promise<T> {\n  let pending = pendingPromises.get(atom) as Promise<T> | undefined\n  if (!pending) {\n    pending = ctrl.resolve()\n    pendingPromises.set(atom, pending)\n    pending.finally(() => pendingPromises.delete(atom))\n  }\n  return pending\n}\n\n/**\n * Access the current Lite.Scope from context.\n *\n * @returns The current Lite.Scope instance from context\n * @throws When called outside of a ScopeProvider\n *\n * @example\n * ```tsx\n * const scope = useScope()\n * await scope.resolve(myAtom)\n * ```\n */\nfunction useScope(): Lite.Scope {\n  const scope = useContext(ScopeContext)\n  if (!scope) {\n    throw new Error(\"useScope must be used within a ScopeProvider\")\n  }\n  return scope\n}\n\n/**\n * Get a memoized controller for an atom.\n *\n * @param atom - The atom to create a controller for\n * @returns A memoized Lite.Controller instance\n *\n * @example\n * ```tsx\n * const ctrl = useController(counterAtom)\n * ctrl.set(ctrl.get() + 1)\n * ```\n */\nfunction useController<T>(atom: Lite.Atom<T>): Lite.Controller<T> {\n  const scope = useScope()\n  return useMemo(() => scope.controller(atom), [scope, atom])\n}\n\n/**\n * Subscribe to atom value with Suspense/ErrorBoundary integration.\n * Auto-resolves atoms lazily and throws cached Promise for Suspense.\n *\n * @param atom - The atom to read\n * @returns The current value of the atom\n *\n * @example\n * ```tsx\n * function UserProfile() {\n *   const user = useAtom(userAtom)\n *   return <div>{user.name}</div>\n * }\n * ```\n */\nfunction useAtom<T>(atom: Lite.Atom<T>): T {\n  const ctrl = useController(atom)\n  const atomRef = useRef(atom)\n  atomRef.current = atom\n\n  const getSnapshot = useCallback((): T => {\n    const state = ctrl.state\n    if (state === 'idle' || state === 'resolving') {\n      throw getOrCreatePendingPromise(atomRef.current, ctrl)\n    }\n    if (state === 'failed') {\n      throw ctrl.get()\n    }\n    return ctrl.get()\n  }, [ctrl])\n\n  const subscribe = useCallback(\n    (onStoreChange: () => void) => ctrl.on('resolved', onStoreChange),\n    [ctrl]\n  )\n\n  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)\n}\n\n/**\n * Select a derived value from an atom with fine-grained reactivity.\n * Only re-renders when the selected value changes per equality function.\n *\n * @param atom - The atom to select from\n * @param selector - Function to extract a derived value\n * @param eq - Optional equality function\n * @returns The selected value\n *\n * @example\n * ```tsx\n * const name = useSelect(userAtom, user => user.name)\n * ```\n */\nfunction useSelect<T, S>(\n  atom: Lite.Atom<T>,\n  selector: (value: T) => S,\n  eq?: (a: S, b: S) => boolean\n): S {\n  const scope = useScope()\n  const ctrl = useController(atom)\n\n  const atomRef = useRef(atom)\n  atomRef.current = atom\n\n  const selectorRef = useRef(selector)\n  const eqRef = useRef(eq)\n  selectorRef.current = selector\n  eqRef.current = eq\n\n  const handleRef = useRef<{\n    scope: Lite.Scope\n    atom: Lite.Atom<T>\n    handle: Lite.SelectHandle<S>\n  } | null>(null)\n\n  const getOrCreateHandle = useCallback(() => {\n    if (\n      !handleRef.current ||\n      handleRef.current.scope !== scope ||\n      handleRef.current.atom !== atom\n    ) {\n      const handle = scope.select(atom, selectorRef.current, { eq: eqRef.current })\n      handleRef.current = { scope, atom, handle }\n    }\n    return handleRef.current.handle\n  }, [scope, atom])\n\n  const getSnapshot = useCallback((): S => {\n    const state = ctrl.state\n    if (state === 'idle' || state === 'resolving') {\n      throw getOrCreatePendingPromise(atomRef.current, ctrl)\n    }\n    if (state === 'failed') {\n      throw ctrl.get()\n    }\n    return getOrCreateHandle().get()\n  }, [ctrl, getOrCreateHandle])\n\n  const subscribe = useCallback((onStoreChange: () => void) => {\n    if (ctrl.state !== 'resolved') {\n      return () => {}\n    }\n    return getOrCreateHandle().subscribe(onStoreChange)\n  }, [ctrl, getOrCreateHandle])\n\n  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)\n}\n\nexport { useScope, useController, useAtom, useSelect }\n"],"mappings":";;;;;;;;AAMA,MAAM,eAAe,cAAiC,KAAK;;;;;;;;;;;AAiB3D,SAAS,cAAc,EAAE,OAAO,YAAgC;AAC9D,QACE,oBAAC,aAAa;EAAS,OAAO;EAC3B;GACqB;;;;;ACvB5B,MAAM,kCAAkB,IAAI,SAA+C;AAE3E,SAAS,0BAA6B,QAAoB,MAAsC;CAC9F,IAAI,UAAU,gBAAgB,IAAIA,OAAK;AACvC,KAAI,CAAC,SAAS;AACZ,YAAU,KAAK,SAAS;AACxB,kBAAgB,IAAIA,QAAM,QAAQ;AAClC,UAAQ,cAAc,gBAAgB,OAAOA,OAAK,CAAC;;AAErD,QAAO;;;;;;;;;;;;;;AAeT,SAAS,WAAuB;CAC9B,MAAM,QAAQ,WAAW,aAAa;AACtC,KAAI,CAAC,MACH,OAAM,IAAI,MAAM,+CAA+C;AAEjE,QAAO;;;;;;;;;;;;;;AAeT,SAAS,cAAiB,QAAwC;CAChE,MAAM,QAAQ,UAAU;AACxB,QAAO,cAAc,MAAM,WAAWA,OAAK,EAAE,CAAC,OAAOA,OAAK,CAAC;;;;;;;;;;;;;;;;;AAkB7D,SAAS,QAAW,QAAuB;CACzC,MAAM,OAAO,cAAcA,OAAK;CAChC,MAAM,UAAU,OAAOA,OAAK;AAC5B,SAAQ,UAAUA;CAElB,MAAM,cAAc,kBAAqB;EACvC,MAAM,QAAQ,KAAK;AACnB,MAAI,UAAU,UAAU,UAAU,YAChC,OAAM,0BAA0B,QAAQ,SAAS,KAAK;AAExD,MAAI,UAAU,SACZ,OAAM,KAAK,KAAK;AAElB,SAAO,KAAK,KAAK;IAChB,CAAC,KAAK,CAAC;AAOV,QAAO,qBALW,aACf,kBAA8B,KAAK,GAAG,YAAY,cAAc,EACjE,CAAC,KAAK,CACP,EAEsC,aAAa,YAAY;;;;;;;;;;;;;;;;AAiBlE,SAAS,UACP,QACA,UACA,IACG;CACH,MAAM,QAAQ,UAAU;CACxB,MAAM,OAAO,cAAcA,OAAK;CAEhC,MAAM,UAAU,OAAOA,OAAK;AAC5B,SAAQ,UAAUA;CAElB,MAAM,cAAc,OAAO,SAAS;CACpC,MAAM,QAAQ,OAAO,GAAG;AACxB,aAAY,UAAU;AACtB,OAAM,UAAU;CAEhB,MAAM,YAAY,OAIR,KAAK;CAEf,MAAM,oBAAoB,kBAAkB;AAC1C,MACE,CAAC,UAAU,WACX,UAAU,QAAQ,UAAU,SAC5B,UAAU,QAAQ,SAASA,OAG3B,WAAU,UAAU;GAAE;GAAO;GAAM,QADpB,MAAM,OAAOA,QAAM,YAAY,SAAS,EAAE,IAAI,MAAM,SAAS,CAAC;GAClC;AAE7C,SAAO,UAAU,QAAQ;IACxB,CAAC,OAAOA,OAAK,CAAC;CAEjB,MAAM,cAAc,kBAAqB;EACvC,MAAM,QAAQ,KAAK;AACnB,MAAI,UAAU,UAAU,UAAU,YAChC,OAAM,0BAA0B,QAAQ,SAAS,KAAK;AAExD,MAAI,UAAU,SACZ,OAAM,KAAK,KAAK;AAElB,SAAO,mBAAmB,CAAC,KAAK;IAC/B,CAAC,MAAM,kBAAkB,CAAC;AAS7B,QAAO,qBAPW,aAAa,kBAA8B;AAC3D,MAAI,KAAK,UAAU,WACjB,cAAa;AAEf,SAAO,mBAAmB,CAAC,UAAU,cAAc;IAClD,CAAC,MAAM,kBAAkB,CAAC,EAEU,aAAa,YAAY"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@pumped-fn/lite-react",
+  "version": "1.0.0",
+  "description": "React integration for @pumped-fn/lite",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "peerDependencies": {
+    "@pumped-fn/lite": ">=1.4.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^18.3.18",
+    "jsdom": "^27.2.0",
+    "react": "^18.3.1",
+    "tsdown": "^0.16.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.5",
+    "@pumped-fn/lite": "1.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "directory": "packages/lite-react",
+    "url": "git+https://github.com/pumped-fn/pumped-fn.git"
+  },
+  "keywords": [
+    "react",
+    "hooks",
+    "dependency-injection",
+    "di",
+    "lite",
+    "lite-react",
+    "reactivity",
+    "typescript"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "typecheck:full": "tsc --noEmit -p tsconfig.test.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}