@plitzi/nexus 0.31.1 → 0.31.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @plitzi/nexus
 
+## 0.31.2
+
+### Patch Changes
+
+- v0.31.2
+
 ## 0.31.1
 
 ### Patch Changes

package/README.md

@@ -1,6 +1,10 @@
+<p align="center">
+  <img src="./logo.svg" alt="@plitzi/nexus" width="640" />
+</p>
+
 # @plitzi/nexus
 
-A lightweight, type-safe React store built on `useSyncExternalStore`. You subscribe to **dot-notation paths** and re-render only when that exact value changes — no selectors, no reducers, no action types. On top of that core it ships scoped stores, time-travel, derived values, an entity adapter, and a middleware pipeline (logger / persist / history).
+A lightweight, type-safe React store built on `useSyncExternalStore`. You subscribe to **dot-notation paths** and re-render only when that exact value changes — no selectors, no reducers, no action types. On top of that core it ships scoped stores, time-travel, derived values, an entity adapter, and a middleware pipeline (logger / persist / history). Fully compatible with SSR, React Server Components, and Next.js App Router.
 
 ```bash
 npm install @plitzi/nexus   # peer deps: react@^18 || ^19, react-dom@^18 || ^19
@@ -33,6 +37,10 @@ function Counter() {
 | `createDerived` / `useDerived` | A memoized value computed from store paths (reselect-style). |
 | `createEntityAdapter` | CRUD updaters + selectors for a normalized `Record<id, T>` map. |
 | `loggerMiddleware` / `persistMiddleware` / `historyMiddleware` / `reduxDevToolsMiddleware` | Middlewares: log, persist to storage, record time-travel, connect to Redux DevTools. |
+| `setCodegenEnabled` | Force on/off the `new Function` codegen path (auto-detects CSP/SSR). |
+| `createServerSnapshot` | Mark server-fetched data for RSC → Client handoff. |
+| `isServerSnapshot` | Check if a value has the SSR marker flag. |
+| `bindServerAction` | Optimistic updates + revalidation for Next.js Server Actions. |
 | `getStoreHistory` / `useStoreHistory` | Undo / redo / jump-to-snapshot action log (enabled by `historyMiddleware`). |
 
 ## Architecture
@@ -528,6 +536,194 @@ setCodegenEnabled(false);
 
 Call `setCodegenEnabled(undefined)` to restore auto-detection.
 
+## Server Components & SSR
+
+Nexus supports React Server Components (App Router) and server-side rendering (Pages Router) with no additional setup.
+
+### Auto-detected SSR safety
+
+When a store is created on the server (`typeof window === 'undefined'`), Nexus automatically:
+
+- **Disables codegen** — `new Function` is never called, so a strict Content-Security-Policy won't break SSR. Falls back to the recursive writer with identical behaviour.
+- **Disables localStorage** — `persistMiddleware` falls back to a no-op storage so `getItem`/`setItem` never throw.
+- **Defers hydration** — `StoreProvider` runs `persistMiddleware` hydration in a `useEffect` after React hydration, preventing hydration mismatches.
+
+You don't need to configure anything for SSR to work.
+
+### Server Components → Client data handoff
+
+Wrap server-fetched data with `createServerSnapshot` to mark it as coming from the server:
+
+```tsx
+// app/page.tsx — Server Component (App Router)
+import { StoreProvider } from '@plitzi/nexus';
+import { createServerSnapshot } from '@plitzi/nexus/rsc';
+
+export default async function Page() {
+  const posts = await fetch('https://api.example.com/posts').then(r => r.json());
+
+  return (
+    <StoreProvider value={createServerSnapshot({ posts })}>
+      <ClientContent />
+    </StoreProvider>
+  );
+}
+```
+
+```tsx
+// app/ClientContent.tsx — Client Component
+'use client';
+const { useStore } = createStoreHook<{ posts: Post[] }>();
+
+function ClientContent() {
+  const [posts] = useStore('posts');
+  // posts is available without a loading state — it was already fetched on the server
+}
+```
+
+The SSR flag is a non-enumerable Symbol — invisible in spread/JSON. Using `createServerSnapshot` is optional; plain objects work too.
+
+### `rsc` subpath exports
+
+| Import | What it's for |
+|---|---|
+| `createServerSnapshot` | Mark data as server-fetched (type-level marker) |
+| `isServerSnapshot` | Check if a value has the SSR flag |
+| `stripServerFlag` | Remove the SSR flag from a value |
+
+Import from `@plitzi/nexus/rsc` or from the main entry.
+
+### App Router — full pattern
+
+```tsx
+// app/providers.tsx
+'use client';
+import { StoreProvider, createServerSnapshot } from '@plitzi/nexus';
+import type { ReactNode } from 'react';
+
+type AppState = {
+  user: { name: string; email: string } | null;
+  theme: 'light' | 'dark';
+  posts: Array<{ id: string; title: string }>;
+};
+
+export function AppProviders({
+  children,
+  initialState
+}: {
+  children: ReactNode;
+  initialState: AppState;
+}) {
+  return (
+    <StoreProvider value={createServerSnapshot(initialState)}>
+      {children}
+    </StoreProvider>
+  );
+}
+
+// app/layout.tsx — Server Component
+import { AppProviders } from './providers';
+
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  const user = await getServerSession();
+  return (
+    <html>
+      <body>
+        <AppProviders initialState={{ user, theme: 'light', posts: [] }}>
+          {children}
+        </AppProviders>
+      </body>
+    </html>
+  );
+}
+
+// app/dashboard/page.tsx — Server Component
+export default async function DashboardPage() {
+  const posts = await db.posts.findMany();
+  return <DashboardClient posts={posts} />;
+}
+
+// app/dashboard/DashboardClient.tsx — Client Component
+'use client';
+import { useStoreSync, createStoreHook } from '@plitzi/nexus';
+
+type State = { posts: Array<{ id: string; title: string }> };
+const { useStore } = createStoreHook<State>();
+
+export function DashboardClient({ posts }: { posts: State['posts'] }) {
+  // Sync server data on mount — avoids overwriting user edits on re-renders
+  useStoreSync('posts', posts, { mode: 'mount' });
+  const [localPosts] = useStore('posts');
+
+  return (
+    <div>
+      {localPosts.map(post => <div key={post.id}>{post.title}</div>)}
+    </div>
+  );
+}
+```
+
+### Pages Router — full pattern
+
+```tsx
+// pages/dashboard.tsx
+import { createStoreHook, StoreProvider } from '@plitzi/nexus';
+import type { InferGetServerSidePropsType } from 'next';
+
+type State = { count: number; user: { name: string } };
+
+export const getServerSideProps = async () => {
+  const user = await api.getUser();
+  return { props: { user } };
+};
+
+export default function DashboardPage({
+  user
+}: InferGetServerSidePropsType<typeof getServerSideProps>) {
+  return (
+    <StoreProvider value={{ user, count: 0 }}>
+      <Dashboard />
+    </StoreProvider>
+  );
+}
+
+// components/Dashboard.tsx
+'use client';
+const { useStore } = createStoreHook<State>();
+
+function Dashboard() {
+  const [user] = useStore('user');
+  const [count, setCount] = useStore('count');
+  return <div>...</div>;
+}
+```
+
+### Server Actions (`@plitzi/nexus/next`)
+
+The `@plitzi/nexus/next` subpath exports a `bindServerAction` helper for optimistic updates
+with automatic revalidation:
+
+```tsx
+'use client';
+import { useStore } from '@plitzi/nexus';
+import { bindServerAction } from '@plitzi/nexus/next';
+
+function Likes({ store, updateLikes }: { store: StoreApi<State>; updateLikes: ServerAction }) {
+  const [likes, setLikes] = useStore('likes');
+  const syncLikes = bindServerAction(store, 'likes', updateLikes, { revalidatePath: '/dashboard' });
+
+  return <button onClick={() => syncLikes(n => n + 1)}>{likes}</button>;
+}
+```
+
+| Import | What it's for |
+|---|---|
+| `bindServerAction` | Optimistic update + rollback + revalidation for Next.js Server Actions |
+| `ServerActionResult` | Return type of `bindServerAction` |
+
+This module dynamically imports from `next/cache` — it only works within Next.js App Router.
+It is **not** a peer dependency, just a compatibility layer.
+
 ## Performance
 
 Notification is `O(depth)` — a few `Map` lookups for the changed path's prefixes — **regardless of how many subscribers exist**, so a million watchers cost the same as one for an unrelated change. The *write* copies the containers on the changed path (immutable structural sharing, the same cost Redux / Zustand / Jotai pay), so model state as a **tree / normalized map** to keep each write touching a small path. Single-segment writes mutate the live working copy in place (O(1)); snapshots from `getState()` are always distinct clones, so they stay immutable for React.

package/dist/StoreProvider.mjs

@@ -1,51 +1,57 @@
 import { StoreContext as e, StoreRegistryContext as t } from "./StoreContext.mjs";
 import n from "./createStore/hooks/useStoreSync.mjs";
 import r from "./createStore/index.mjs";
-import { createContext as i, useContext as a, useEffect as o, useMemo as s, useRef as c } from "react";
-import { jsx as l } from "react/jsx-runtime";
+import { isServerSnapshot as i, stripServerFlag as a } from "./rsc/index.mjs";
+import { createContext as o, useContext as s, useEffect as c, useMemo as l, useRef as u } from "react";
+import { jsx as d } from "react/jsx-runtime";
 //#region src/StoreProvider.tsx
-var u = i(void 0), d = (e) => e.cascade === !0, f = ({ store: i, id: f, path: p, value: m, inherit: h, autoSync: g = !0, middlewares: _, children: v }) => {
-	let y = a(e), b = a(u), x = a(t), S = c(void 0), C = h === "live", w = s(() => {
-		let e = h === "snapshot" && y ? y.getState() : {};
-		return typeof m == "function" ? m(e) : {
+var f = o(void 0), p = (e) => e.cascade === !0, m = ({ store: o, id: m, path: h, value: g, inherit: _, autoSync: v = !0, middlewares: y, children: b }) => {
+	let x = s(e), S = s(f), C = s(t), w = u(void 0), T = _ === "live", E = l(() => {
+		let e = _ === "snapshot" && x ? x.getState() : {}, t = typeof g == "function" ? g(e) : {
 			...e,
-			...m
+			...g
 		};
+		return i(t) ? a(t) : t;
 	}, [
-		h,
-		y,
-		m
-	]), T = _ ?? [], E = b ? [...b, ...T] : T, D = s(() => [...b ?? [], ...T.filter(d)], [b, _]);
-	S.current ||= i ?? r(() => w, {
-		id: f,
-		parent: C ? y : void 0,
-		middlewares: E.length > 0 ? E : void 0
+		_,
+		x,
+		g
+	]), D = y ?? [], O = S ? [...S, ...D] : D, k = l(() => [...S ?? [], ...D.filter(p)], [S, y]);
+	w.current ||= o ?? r(() => E, {
+		id: m,
+		parent: T ? x : void 0,
+		middlewares: O.length > 0 ? O : void 0,
+		deferHydrate: !0
 	});
-	let O = s(() => f ? {
-		id: f,
-		store: S.current,
-		parent: x
-	} : x, [f, x]);
-	c(!1), o(() => {}, [f, x]), o(() => (C && !i && S.current?.reconnect?.(), () => {
-		C && !i && S.current?.destroy?.();
-	}), [C, i]);
-	let k = !!m && g;
-	return n(p, p ? m : w, {
-		enabled: k && !!p,
-		store: S.current
-	}), n(void 0, w, {
-		enabled: k && !p,
-		store: S.current
-	}), /* @__PURE__ */ l(u, {
-		value: D.length > 0 ? D : void 0,
-		children: /* @__PURE__ */ l(t, {
-			value: O,
-			children: /* @__PURE__ */ l(e, {
-				value: S.current,
-				children: v
+	let A = l(() => m ? {
+		id: m,
+		store: w.current,
+		parent: C
+	} : C, [m, C]);
+	u(!1), c(() => {}, [m, C]), c(() => (T && !o && w.current?.reconnect?.(), () => {
+		T && !o && w.current?.destroy?.();
+	}), [T, o]);
+	let j = u(!1);
+	c(() => {
+		!j.current && w.current?.hydrate && (w.current.hydrate(), j.current = !0);
+	}, []);
+	let M = !!g && v;
+	return n(h, h ? g : E, {
+		enabled: M && !!h,
+		store: w.current
+	}), n(void 0, E, {
+		enabled: M && !h,
+		store: w.current
+	}), /* @__PURE__ */ d(f, {
+		value: k.length > 0 ? k : void 0,
+		children: /* @__PURE__ */ d(t, {
+			value: A,
+			children: /* @__PURE__ */ d(e, {
+				value: w.current,
+				children: b
 			})
 		})
 	});
 };
 //#endregion
-export { f as default };
+export { m as default };

package/dist/createStore/createStore.d.ts

@@ -1,9 +1,14 @@
 import { GetState, GetterTuple, GetValueFn, GetValueFromBaseFn, GetValueFromBaseWithDefaultFn, MultiPathReturn, PathOf, PathOrFn, PathOrFnSetters, PathOrFnValue, PathOrFnValues, PathSetters, PathSetter, PathValue, PathValues, SetFromBaseFn, SetState, SetStateFn, StoreApi, StoreMiddleware, UseStoreGetterOptions, UseStoreMultiOptions, UseStoreOptions, UseStoreSetterOptions, UseStoreSyncMultiOptions, UseStoreSyncOptions } from '../types';
-declare function createStore<TState extends object>(initializer: Partial<TState> | ((set: SetState<TState>, get: GetState<TState>) => Partial<TState>), storeOptions?: {
+export type CreateStoreOptions<TState extends object> = {
     id?: string;
     parent?: StoreApi<TState>;
     middlewares?: StoreMiddleware<TState>[];
-}): StoreApi<TState>;
+    /** When true, hydrate handlers are collected but NOT run during creation.
+     *  Call `store.hydrate()` manually (StoreProvider does this in a useEffect).
+     *  Defaults to false (backward-compatible: standalone usage hydrates synchronously). */
+    deferHydrate?: boolean;
+};
+declare function createStore<TState extends object>(initializer: Partial<TState> | ((set: SetState<TState>, get: GetState<TState>) => Partial<TState>), storeOptions?: CreateStoreOptions<TState>): StoreApi<TState>;
 export declare const createStoreHook: <TState extends object>() => {
     useStore: {
         (options?: UseStoreOptions<TState, TState>): [TState, StoreApi<TState>["setState"]];

package/dist/createStore/createStore.mjs

@@ -13,9 +13,9 @@ var l = 0;
 function u(a, o) {
 	let s = {}, c, u = new r(), d = new r(), f = new i(), p = new r(), m = () => {
 		p.forEach((e) => e());
-	}, h = [], g = [], _ = o?.parent;
+	}, h = [], g = [], _ = [], v = o?.parent;
 	++l;
-	let v = (e, t, n) => {
+	let y = (e, t, n) => {
 		if (g.length === 0) throw e;
 		let r = {
 			error: e,
@@ -23,62 +23,67 @@ function u(a, o) {
 			path: n
 		};
 		for (let e = 0, t = g.length; e < t; e++) g[e](r);
-	}, y = () => s, b = () => c ??= { ...s }, { getState: x, getPath: S, invalidate: C, setActive: w, getMergeCount: T } = e(y, b, _);
-	_ && w(!1);
-	let { setState: E, batch: D } = t({
-		getOwnState: y,
-		getOwnSnapshot: b,
+	}, b = () => s, x = () => c ??= { ...s }, { getState: S, getPath: C, invalidate: w, setActive: T, getMergeCount: E } = e(b, x, v);
+	v && T(!1);
+	let { setState: D, batch: O } = t({
+		getOwnState: b,
+		getOwnSnapshot: x,
 		setOwnState: (e) => {
-			s = e, c = void 0, C();
+			s = e, c = void 0, w();
 		},
 		mutateOwnKey: (e, t) => {
-			s[e] = t, C(), c = void 0;
+			s[e] = t, w(), c = void 0;
 		},
-		parent: _,
+		parent: v,
 		listeners: u,
 		pathListeners: f,
 		changeListeners: d,
 		interceptors: h,
-		reportError: v,
+		reportError: y,
 		invalidateDescendants: m,
 		onDelegateToParent: void 0
-	}), O = () => {
-		C(), m();
-	}, k, A, j = !1, M = () => u.length > 0 || f.size > 0 || d.length > 0, N = () => {
-		k || !_ || (C(), w(!0), k = n(_, u, f, d, x, v, C), A = _.subscribeInvalidate?.(O), d.length > 0 && k.seedBaseline());
-	}, P = () => {
-		k && (k.unsubscribe(), k = void 0, A?.(), A = void 0, w(!1));
+	}), k = () => {
+		w(), m();
+	}, A, j, M = !1, N = () => u.length > 0 || f.size > 0 || d.length > 0, P = () => {
+		A || !v || (w(), T(!0), A = n(v, u, f, d, S, y, w), j = v.subscribeInvalidate?.(k), d.length > 0 && A.seedBaseline());
 	}, F = () => {
-		_ && (!j && M() ? N() : P());
-	}, I = (e) => (F(), () => {
-		e(), F();
-	}), L = (e) => I(u.add(e)), R = (e, t) => I(f.add(e, t)), z = (e) => {
-		let t = I(d.add(e));
-		return k?.seedBaseline(), t;
+		A && (A.unsubscribe(), A = void 0, j?.(), j = void 0, T(!1));
+	}, I = () => {
+		v && (!M && N() ? P() : F());
+	}, L = (e) => (I(), () => {
+		e(), I();
+	}), R = (e) => L(u.add(e)), z = (e, t) => L(f.add(e, t)), B = (e) => {
+		let t = L(d.add(e));
+		return A?.seedBaseline(), t;
 	};
-	s = typeof a == "function" ? a(E, x) : a;
-	let B = {
+	s = typeof a == "function" ? a(D, S) : a;
+	let V = {
 		id: o?.id,
-		getState: x,
-		getPath: S,
-		setState: E,
-		batch: D,
-		subscribe: L,
-		subscribePath: R,
-		subscribeChange: z,
+		getState: S,
+		getPath: C,
+		setState: D,
+		batch: O,
+		subscribe: R,
+		subscribePath: z,
+		subscribeChange: B,
 		destroy: () => {
-			j = !0, P(), u.clear(), f.clear(), d.clear(), p.clear();
+			M = !0, F(), u.clear(), f.clear(), d.clear(), p.clear();
 		},
 		reconnect: () => {
-			j = !1, F();
+			M = !1, I();
 		},
-		subscribeInvalidate: (e) => p.add(e)
+		subscribeInvalidate: (e) => p.add(e),
+		hydrate: () => {
+			for (let e of _) e();
+		}
 	};
 	if (o?.middlewares) for (let e of o.middlewares) {
-		let t = e(B);
-		t?.beforeChange && h.push(t.beforeChange), t?.onChange && z(t.onChange), t?.onError && g.push(t.onError);
+		let t = e(V);
+		t?.beforeChange && h.push(t.beforeChange), t?.onChange && B(t.onChange), t?.onError && g.push(t.onError);
+		let n = t?.hydrate;
+		n && (o.deferHydrate ? _.push(() => n(V)) : n(V));
 	}
-	return B;
+	return V;
 }
 var d = () => {
 	function e(e, t) {

package/dist/createStore/helpers/writeByPath.mjs

@@ -24,6 +24,7 @@ var e = Symbol("unchanged"), t = (e) => /^\d+$/.test(e), n = (e) => Array.isArra
 	return n += `return ${i};`, Function("o", "v", "f", n);
 }, c, l, u = () => {
 	if (l !== void 0) return l;
+	if (typeof window > "u") return !1;
 	if (c === void 0) try {
 		s(["x", "y"])({ x: {} }, 1, !1), c = !0;
 	} catch {

package/dist/index.d.ts

@@ -14,3 +14,4 @@ export * from './createStore/hooks/useStoreById';
 export * from './types';
 export { createStore, StoreProvider, useStoreById, useStoreSetter };
 export { setCodegenEnabled } from './createStore/helpers/writeByPath';
+export { createServerSnapshot, isServerSnapshot } from './rsc';

package/dist/index.mjs

@@ -13,9 +13,10 @@ import { createEntityAdapter as f } from "./entities/createEntityAdapter.mjs";
 import { getStoreHistory as p, historyMiddleware as m } from "./middleware/historyMiddleware.mjs";
 import { useStoreHistory as h } from "./history/hooks/useStoreHistory.mjs";
 import g from "./createStore/hooks/useStoreById.mjs";
-import _ from "./StoreProvider.mjs";
-import { loggerMiddleware as v } from "./middleware/loggerMiddleware.mjs";
-import { persistMiddleware as y } from "./middleware/persistMiddleware.mjs";
-import { reduxDevToolsMiddleware as b } from "./middleware/reduxDevToolsMiddleware.mjs";
-import { cascade as x } from "./middleware/cascade.mjs";
-export { i as CANCEL, a as StoreContext, _ as StoreProvider, o as StoreRegistryContext, x as cascade, e as createAsync, u as createDerived, f as createEntityAdapter, l as createStore, c as createStoreHook, p as getStoreHistory, m as historyMiddleware, v as loggerMiddleware, y as persistMiddleware, b as reduxDevToolsMiddleware, r as setCodegenEnabled, t as useAsync, n as useAsyncValue, d as useDerived, g as useStoreById, h as useStoreHistory, s as useStoreSetter };
+import { createServerSnapshot as _, isServerSnapshot as v } from "./rsc/index.mjs";
+import y from "./StoreProvider.mjs";
+import { loggerMiddleware as b } from "./middleware/loggerMiddleware.mjs";
+import { persistMiddleware as x } from "./middleware/persistMiddleware.mjs";
+import { reduxDevToolsMiddleware as S } from "./middleware/reduxDevToolsMiddleware.mjs";
+import { cascade as C } from "./middleware/cascade.mjs";
+export { i as CANCEL, a as StoreContext, y as StoreProvider, o as StoreRegistryContext, C as cascade, e as createAsync, u as createDerived, f as createEntityAdapter, _ as createServerSnapshot, l as createStore, c as createStoreHook, p as getStoreHistory, m as historyMiddleware, v as isServerSnapshot, b as loggerMiddleware, x as persistMiddleware, S as reduxDevToolsMiddleware, r as setCodegenEnabled, t as useAsync, n as useAsyncValue, d as useDerived, g as useStoreById, h as useStoreHistory, s as useStoreSetter };

package/dist/middleware/persistMiddleware.mjs

@@ -12,15 +12,19 @@ var e = {
 		i.setItem(n, JSON.stringify(r));
 	};
 	return (e) => {
-		r(e, n, i, o, s, c);
 		let t;
-		return { onChange: () => {
-			if (l <= 0) {
-				u(e);
-				return;
+		return {
+			hydrate: (e) => {
+				r(e, n, i, o, s, c);
+			},
+			onChange: () => {
+				if (l <= 0) {
+					u(e);
+					return;
+				}
+				clearTimeout(t), t = setTimeout(() => u(e), l);
 			}
-			clearTimeout(t), t = setTimeout(() => u(e), l);
-		} };
+		};
 	};
 };
 function r(e, t, n, r, i, a) {

package/dist/next/index.d.ts

@@ -0,0 +1,26 @@
+import { PathOf, PathValue, StoreApi } from '../types';
+export type ServerActionResult<TState extends object, P extends PathOf<TState>> = (value: PathValue<TState, P> | ((prev: PathValue<TState, P>) => PathValue<TState, P>)) => Promise<void>;
+/**
+ * Binds a Nexus store path to a Next.js Server Action, giving you
+ * optimistic updates + automatic revalidation.
+ *
+ * ```ts
+ * 'use client';
+ * import { useStore } from '@plitzi/nexus';
+ * import { bindServerAction } from '@plitzi/nexus/next';
+ *
+ * function Likes({ store, updateLikes }: { store: StoreApi<State>; updateLikes: ServerAction }) {
+ *   const [likes, setLikes] = useStore('likes');
+ *   const syncLikes = bindServerAction(store, 'likes', updateLikes, { revalidatePath: '/dashboard' });
+ *
+ *   return <button onClick={() => syncLikes(n => n + 1)}>{likes}</button>;
+ * }
+ * ```
+ *
+ * ⚠️ This file imports from `next/cache` dynamically. It only works within
+ * Next.js App Router — not a peer dependency, just a compatibility layer.
+ */
+export declare function bindServerAction<TState extends object, P extends PathOf<TState>>(store: StoreApi<TState>, path: P, action: (value: PathValue<TState, P>) => Promise<PathValue<TState, P>>, options?: {
+    revalidatePath?: string;
+    revalidateTag?: string;
+}): ServerActionResult<TState, P>;

package/dist/next/index.mjs

@@ -0,0 +1,18 @@
+//#region src/next/index.ts
+function e(e, t, n, r) {
+	let i = r?.revalidatePath || r?.revalidateTag;
+	return async (a) => {
+		let o = e.getPath(t), s = typeof a == "function" ? a(o) : a;
+		e.setState(t, s);
+		try {
+			if (await n(s), i) {
+				let e = await import("next/cache");
+				r.revalidatePath && e.revalidatePath(r.revalidatePath), r.revalidateTag && e.revalidateTag(r.revalidateTag);
+			}
+		} catch (n) {
+			throw e.setState(t, o), n;
+		}
+	};
+}
+//#endregion
+export { e as bindServerAction };

package/dist/rsc/index.d.ts

@@ -0,0 +1,29 @@
+declare const SSR_FLAG: unique symbol;
+type WithSsrFlag<T> = T & {
+    readonly [SSR_FLAG]: true;
+};
+/**
+ * Wraps server-fetched data so Nexus knows it came from SSR.
+ *
+ * Usage in a Server Component (App Router):
+ *
+ * ```tsx
+ * import { createServerSnapshot } from '@plitzi/nexus/rsc';
+ * import { StoreProvider } from '@plitzi/nexus';
+ *
+ * export default async function Page() {
+ *   const data = await fetch('https://api.example.com/user');
+ *   return (
+ *     <StoreProvider value={createServerSnapshot(data)}>
+ *       <ClientComponent />
+ *     </StoreProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function createServerSnapshot<T extends object>(data: T): WithSsrFlag<T>;
+/** @internal */
+export declare function isServerSnapshot<T>(value: T): value is WithSsrFlag<T>;
+/** @internal Strip the SSR flag from a snapshot (returns a plain object). */
+export declare function stripServerFlag<T extends object>(value: T): T;
+export {};

package/dist/rsc/index.mjs

@@ -0,0 +1,18 @@
+//#region src/rsc/index.ts
+var e = Symbol("@plitzi/nexus/ssr-snapshot");
+function t(t) {
+	return e in t ? t : Object.defineProperty(t, e, {
+		value: !0,
+		enumerable: !1,
+		writable: !1,
+		configurable: !1
+	});
+}
+function n(t) {
+	return typeof t == "object" && !!t && e in t;
+}
+function r(e) {
+	return n(e) ? { ...e } : e;
+}
+//#endregion
+export { t as createServerSnapshot, n as isServerSnapshot, r as stripServerFlag };

package/dist/types/StoreTypes.d.ts

@@ -51,6 +51,7 @@ export type StoreMiddlewareHandlers<T> = {
     beforeChange?: WriteInterceptor<T>;
     onChange?: ChangeListener<T>;
     onError?: StoreErrorHandler<T>;
+    hydrate?: (api: StoreApi<T>) => void;
 };
 export type StoreMiddleware<T extends object> = (api: StoreApi<T>) => StoreMiddlewareHandlers<T> | void;
 export type Listener = (changedPath?: Path) => void;
@@ -71,6 +72,7 @@ export type StoreApi<T> = {
     destroy?: () => void;
     reconnect?: () => void;
     subscribeInvalidate?: (listener: () => void) => () => void;
+    hydrate?: () => void;
 };
 export type StoreApiInternal<T> = StoreApi<T> & {
     listeners: Subscribers<Listener>;

package/logo.svg

@@ -0,0 +1,57 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="640" height="180" viewBox="0 0 640 180" fill="none" role="img" aria-label="@plitzi/nexus">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="640" y2="180" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#0c0c12" />
+      <stop offset="1" stop-color="#16161f" />
+    </linearGradient>
+    <linearGradient id="mark" x1="0" y1="0" x2="1" y2="1">
+      <stop stop-color="#a78bfa" />
+      <stop offset="1" stop-color="#7c3aed" />
+    </linearGradient>
+    <linearGradient id="word" x1="150" y1="0" x2="560" y2="0" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#ede9fe" />
+      <stop offset="1" stop-color="#a78bfa" />
+    </linearGradient>
+  </defs>
+
+  <rect width="640" height="180" rx="20" fill="url(#bg)" />
+  <rect x="0.5" y="0.5" width="639" height="179" rx="19.5" fill="none" stroke="#2a2a38" />
+
+  <circle cx="96" cy="90" r="130" fill="#7c3aed" opacity="0.10" />
+
+  <!-- nexus mark -->
+  <g transform="translate(90 90)">
+    <rect x="-36" y="-36" width="72" height="72" rx="18" fill="url(#mark)" />
+    <g transform="scale(2.0)" stroke="#fff" stroke-linecap="round" stroke-linejoin="round">
+      <path d="M0 -8.5 7.4 -4.25 7.4 4.25 0 8.5 -7.4 4.25 -7.4 -4.25 Z" stroke-width="1.3" stroke-opacity="0.45" />
+      <g stroke-width="1.5">
+        <path d="M0 0 0 -8.5" />
+        <path d="M0 0 7.4 -4.25" />
+        <path d="M0 0 7.4 4.25" />
+        <path d="M0 0 0 8.5" />
+        <path d="M0 0 -7.4 4.25" />
+        <path d="M0 0 -7.4 -4.25" />
+      </g>
+    </g>
+    <g transform="scale(2.0)" fill="#fff">
+      <circle cx="0" cy="-8.5" r="1.7" />
+      <circle cx="7.4" cy="-4.25" r="1.7" />
+      <circle cx="7.4" cy="4.25" r="1.7" />
+      <circle cx="0" cy="8.5" r="1.7" />
+      <circle cx="-7.4" cy="4.25" r="1.7" />
+      <circle cx="-7.4" cy="-4.25" r="1.7" />
+      <circle cx="0" cy="0" r="2.6" />
+    </g>
+  </g>
+
+  <!-- wordmark -->
+  <text x="158" y="86" font-family="'Inter', system-ui, sans-serif" font-size="46" font-weight="800" letter-spacing="-1" fill="url(#word)">
+    @plitzi/nexus
+  </text>
+  <text x="160" y="120" font-family="'Inter', system-ui, sans-serif" font-size="20" font-weight="500" fill="#a1a1aa">
+    A tiny, type-safe React store
+  </text>
+  <text x="160" y="146" font-family="'JetBrains Mono', ui-monospace, monospace" font-size="15" fill="#8b5cf6">
+    path subscriptions · scoped stores · time-travel
+  </text>
+</svg>

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@plitzi/nexus",
-  "version": "0.31.1",
+  "version": "0.31.2",
   "license": "Apache-2.0",
   "files": [
-    "dist"
+    "dist",
+    "logo.svg"
   ],
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -86,14 +87,6 @@
       "types": "./dist/createStore/helpers/createChainReads.d.ts",
       "import": "./dist/createStore/helpers/createChainReads.mjs"
     },
-    "./createStore/helpers/createGetPath": {
-      "types": "./dist/createStore/helpers/createGetPath.d.ts",
-      "import": "./dist/createStore/helpers/createGetPath.mjs"
-    },
-    "./createStore/helpers/createGetState": {
-      "types": "./dist/createStore/helpers/createGetState.d.ts",
-      "import": "./dist/createStore/helpers/createGetState.mjs"
-    },
     "./createStore/helpers/createSetState": {
       "types": "./dist/createStore/helpers/createSetState.d.ts",
       "import": "./dist/createStore/helpers/createSetState.mjs"
@@ -242,6 +235,17 @@
       "types": "./dist/middleware/reduxDevToolsMiddleware.d.ts",
       "import": "./dist/middleware/reduxDevToolsMiddleware.mjs"
     },
+    "./next": {
+      "types": "./dist/next/index.d.ts",
+      "import": "./dist/next/index.mjs"
+    },
+    "./next/index": {
+      "types": "./dist/next/index.d.ts",
+      "import": "./dist/next/index.mjs"
+    },
+    "./rsc/index": {
+      "import": "./dist/rsc/index.mjs"
+    },
     "./types": {
       "types": "./dist/types/index.d.ts",
       "import": "./dist/types/index.mjs"