@yakocloud/state-vocab 4.0.2 → 4.1.0

package/README.md

@@ -260,6 +260,81 @@ By default `ssr: true`:
 
 This guarantees the server and client produce identical markup, and the value from storage is applied without a visible flash.
 
+### Next.js Pages Router (SSR without RSC)
+
+If you use Next.js with the **Pages Router** (or any SSR setup without React Server Components), you still need `ssr: true` to prevent hydration mismatches — but you don't have server components to wrap with `StateVocabProvider` from `serverify`.
+
+In this case, wrap your app with `StateVocabClientProvider` from `@yakocloud/state-vocab/client`. It creates an isolated `VocabStore` per render, preventing state from leaking between concurrent SSR requests.
+
+```tsx
+// pages/_app.tsx
+import type { AppProps } from 'next/app'
+import { StateVocabClientProvider } from '@yakocloud/state-vocab/client'
+
+export default function App({ Component, pageProps }: AppProps) {
+  return (
+    <StateVocabClientProvider>
+      <Component {...pageProps} />
+    </StateVocabClientProvider>
+  )
+}
+```
+
+Storage is still configured with `ssr: true` (the default):
+
+```ts
+// lib/storage.ts
+import { setupStorage, defineState } from '@yakocloud/state-vocab'
+import { clientify } from '@yakocloud/state-vocab/client'
+
+const storage = setupStorage({
+  preference: {
+    theme: defineState<'Dark' | 'White' | 'System'>({
+      storage: localStorage,
+      defaultValue: 'Dark',
+    }),
+  },
+  // ssr: true is the default — storage reads are deferred until after hydration
+})
+
+export const clientStorage = clientify(storage)
+```
+
+Use `clientStorage` directly in any page or component — no additional wiring needed:
+
+```tsx
+// pages/settings.tsx
+import { clientStorage } from '@/lib/storage'
+
+export default function Settings() {
+  const [theme, setTheme] = clientStorage.preference.theme.useState()
+
+  return (
+    <select value={theme} onChange={(e) => setTheme(e.target.value as 'Dark' | 'White' | 'System')}>
+      <option value="Dark">Dark</option>
+      <option value="White">White</option>
+      <option value="System">System</option>
+    </select>
+  )
+}
+```
+
+`StateVocabClientProvider` also accepts an optional `value` prop to pre-seed the store with server-fetched data (e.g., from `getServerSideProps`):
+
+```tsx
+// pages/_app.tsx
+import type { AppProps } from 'next/app'
+import { StateVocabClientProvider } from '@yakocloud/state-vocab/client'
+
+export default function App({ Component, pageProps }: AppProps) {
+  return (
+    <StateVocabClientProvider value={pageProps.initialVocab}>
+      <Component {...pageProps} />
+    </StateVocabClientProvider>
+  )
+}
+```
+
 ### React Server Components (RSC)
 
 For Next.js apps using the App Router, state-vocab provides dedicated server and client entry points that let you read state in async server components and pass it down to client components via `StateVocabProvider`.
@@ -270,7 +345,7 @@ For Next.js apps using the App Router, state-vocab provides dedicated server and
 |---|---|
 | `@yakocloud/state-vocab` | Shared files — `defineState`, `setupStorage` |
 | `@yakocloud/state-vocab/server` | Server Components — `serverify` |
-| `@yakocloud/state-vocab/client` | Client Components — `clientify` |
+| `@yakocloud/state-vocab/client` | Client Components — `clientify`, `StateVocabClientProvider` |
 
 **1. Define the shared storage schema** (used on both server and client):
 
@@ -291,14 +366,28 @@ export const storage = setupStorage({
 })
 ```
 
-**2. Create server and client storage handles:**
+**2. Create a client context, then create server and client storage handles:**
+
+Each storage tree needs its own React context so that multiple independent providers can coexist on the same page without their state bleeding into each other.
+
+```ts
+// storage.context.client.ts  ("use client")
+"use client"
+
+import { createContext } from 'react'
+
+export const StorageClientContext = createContext({})
+```
 
 ```ts
 // storage.server.ts
 import { storage } from '@/storage'
 import { serverify } from '@yakocloud/state-vocab/server'
+import { StorageClientContext } from '@/storage.context.client'
 
-export const serverStorage = serverify(storage)
+export const serverStorage = serverify(storage, {
+  clientContext: StorageClientContext,
+})
 ```
 
 ```ts
@@ -307,8 +396,11 @@ export const serverStorage = serverify(storage)
 
 import { storage } from '@/storage'
 import { clientify } from '@yakocloud/state-vocab/client'
+import { StorageClientContext } from '@/storage.context.client'
 
-export const clientStorage = clientify(storage)
+export const clientStorage = clientify(storage, {
+  clientContext: StorageClientContext,
+})
 ```
 
 **3. Seed initial state in the server component and read it in Server and Client children:**
@@ -362,6 +454,40 @@ export default function UserInfoClient() {
 }
 ```
 
+#### Multiple independent storage trees
+
+Because each `serverify`/`clientify` pair is bound to its own context, you can have multiple independent providers active at the same time — for example, a layout-level store and a page-level store — without them interfering with each other:
+
+```ts
+// layout.context.client.ts ("use client")
+export const LayoutClientContext = createContext({})
+
+// page.context.client.ts ("use client")
+export const PageClientContext = createContext({})
+
+// layout.storage.server.ts
+export const layoutServerStorage = serverify(layoutStorage, { 
+  clientContext: LayoutClientContext 
+})
+
+// layout.storage.client.ts ("use client")
+export const layoutClientStorage = clientify(layoutStorage, { 
+  clientContext: LayoutClientContext 
+})
+
+// page.storage.server.ts
+export const pageServerStorage = serverify(pageStorage, { 
+  clientContext: PageClientContext 
+})
+
+// page.storage.client.ts ("use client")
+export const pageClientStorage = clientify(pageStorage, { 
+  clientContext: PageClientContext 
+})
+```
+
+Each `StateVocabProvider` wraps its own subtree; a component that calls `pageClientStorage.user.name.useState()` reads only from the nearest `pageServerStorage.StateVocabProvider`, not from the layout provider.
+
 #### `serverify(storage)`
 
 Converts a storage tree into its server-side counterpart. Each leaf gains a `.getState()` method that reads the value seeded into the nearest `StateVocabProvider`. Each namespace node (including the root) gains a `.seed()` method that returns the input wrapped under its full ancestor path. This method is optional for using. The result also exposes `StateVocabProvider` — a server-aware provider that accepts a plain object `value` prop to pre-seed the store.
@@ -607,15 +733,33 @@ const { StateVocabProvider } = serverStorage
 </StateVocabProvider>
 ```
 
-### `serverify<T>(storage: T)`
+### `StateVocabClientProvider`
+
+A client-only provider for SSR setups **without** React Server Components (e.g. Next.js Pages Router). Import from `@yakocloud/state-vocab/client` and place it at your app root to ensure per-request store isolation. Accepts an optional `value` prop to pre-seed the store.
+
+```tsx
+import { StateVocabClientProvider } from '@yakocloud/state-vocab/client'
+
+<StateVocabClientProvider value={initialVocab}>
+  <App />
+</StateVocabClientProvider>
+```
+
+### `serverify<T>(storage: T, options)`
 
 Converts a storage tree to its server-side counterpart. Available from `@yakocloud/state-vocab/server`.
 
+| Option | Type | Description |
+|---|---|---|
+| `clientContext` | `Context<object>` | **Required.** A React context created with `createContext({})` in a `"use client"` file. Must match the `clientContext` passed to `clientify` for the same storage tree. |
+
 Each leaf gains `.getState()` — reads the value from the nearest `StateVocabProvider`. Each namespace node gains `.seed()`, which returns the input wrapped under its full ancestor path. The result also includes `StateVocabProvider` — use it instead of importing from `@yakocloud/state-vocab/server`.
 
 ```ts
 import { serverify } from '@yakocloud/state-vocab/server'
-const serverStorage = serverify(storage)
+import { MyClientContext } from '@/storage.context.client'
+
+const serverStorage = serverify(storage, { clientContext: MyClientContext })
 
 const { StateVocabProvider } = serverStorage        // server-aware provider
 
@@ -625,15 +769,21 @@ serverStorage.person.address.seed({ city: 'NY' })   // → { person: { address:
 serverStorage.seed({ user: { name: 'Alice' } })     // → { user: { name: 'Alice' } } (identity)
 ```
 
-### `clientify<T>(storage: T)`
+### `clientify<T>(storage: T, options?)`
 
 Converts a storage tree to its client-side counterpart. Available from `@yakocloud/state-vocab/client`.
 
+| Option | Type | Description |
+|---|---|---|
+| `clientContext` | `Context<object> \| undefined` | The React context created with `createContext({})` for this storage tree. Must match the `clientContext` passed to `serverify`. Required when using RSC; omit for SPA-only setups. |
+
 Each leaf gains `.useState()` and `.useInitialState()`. The tree structure mirrors the original.
 
 ```ts
 import { clientify } from '@yakocloud/state-vocab/client'
-const clientStorage = clientify(storage)
+import { MyClientContext } from '@/storage.context.client'
+
+const clientStorage = clientify(storage, { clientContext: MyClientContext })
 
 // In a "use client" component:
 const [name] = clientStorage.user.name.useState()

package/dist/client.cjs.js

@@ -1 +1 @@
-"use client";"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const u=require("react"),v=require("./constants-CbsduCZ7.js"),a=require("./utils-0CTNJ4ZE.js"),y=require("./provider-client-B4XQ24JB.js");function D(t,e,n=[]){return u.useMemo(()=>a.debounce(t,e),n)}const g=t=>{const{vocabStore:e,storage:n,statePath:o,value:s,deserialize:S,serialize:l}=t,f=n.getItem(o);f===null?a.isValueDefined(s)&&n.setItem(o,l(s)):e.set(o,S(f))},z=typeof window>"u",m=z?u.useEffect:u.useLayoutEffect,A=new y.VocabStore,C="Make sure your component is wrapped in StateVocabProvider (RSC) or disable ssr option in setupStorage for SPA (RCC only)";function I(t){t??={};const e=z?void 0:a.valueOrFactory(t.storage),n=a.valueOrFactory(t.defaultValue),o=t.bidirectional,s=this[v.STATE_PATH],S=this[v.STATE_VERBOSE],l=this[v.STATE_VERBOSE_PATH],f=this[v.STATE_SSR];let i=y.useStateVocabClientContext({verbose:S});if(!(i instanceof y.VocabStore)){if(f)throw new Error(C);i=A}const d=t.serialize??JSON.stringify,c=t.deserialize??JSON.parse,V=D(t.onSet??(()=>{}),t.delayedSet,[]),E=u.useRef(void 0),w=u.useRef(!1);if(!w.current){w.current=!0;let r=i.get(s);a.isValueDefined(r)||(r=n,a.isValueDefined(r)&&i.set(s,r)),!f&&e&&g({vocabStore:i,storage:e,statePath:s,value:r,serialize:d,deserialize:c})}const h=u.useSyncExternalStore(i.subscribe.bind(i),i.getClientSnapshot.bind(i),i.getServerSnapshot.bind(i));if(S)if(l){const r=a.get(h,l);r&&a.logStyled(r)}else a.logStyled(h);const T=a.get(h,s,n);E.current=T,m(()=>{!f||!e||g({vocabStore:i,storage:e,statePath:s,value:T,serialize:d,deserialize:c})},[]);const O=u.useEffectEvent(r=>{if(r.key!==s)return;const b=r.newValue,R=(b===null?null:c(b))??n;a.isValueDefined(R)&&(i.set(s,R),V(R,E.current))});u.useEffect(()=>{if(o)return window.addEventListener("storage",O),()=>window.removeEventListener("storage",O)},[o]);const p=u.useCallback(r=>{const b=a.isTransformer(r)?r(E.current):r;i.set(s,b),V(b,E.current),e&&e.setItem(s,d(b))},[i,s,V,e,d]),_=u.useCallback(()=>{const r=n;if(!a.isValueDefined(r)){e?.removeItem(s);return}i.set(s,r),V(r,E.current),e&&e.setItem(s,d(r))},[n,i,s,V,e,d]);return[T,p,_]}function k(t){t??={};const e=z?void 0:a.valueOrFactory(t.storage),n=a.valueOrFactory(t.defaultValue),o=this[v.STATE_PATH],s=this[v.STATE_VERBOSE],S=this[v.STATE_SSR];let l=y.useStateVocabClientContext({verbose:s});if(!(l instanceof y.VocabStore)){if(S)throw new Error(C);l=A}const f=t.serialize??JSON.stringify,i=t.deserialize??JSON.parse,d=u.useRef(!1);let c;d.current||(d.current=!0,c=l.get(o),a.isValueDefined(c)||(c=n,a.isValueDefined(c)&&l.set(o,c)),!S&&e&&g({vocabStore:l,storage:e,statePath:o,value:c,serialize:f,deserialize:i})),m(()=>{!S||!e||g({vocabStore:l,storage:e,statePath:o,value:c,serialize:f,deserialize:i})},[])}function q(t){return typeof t=="object"&&t!==null&&"clientSlot"in t}function P(t){const e={};for(const n in t){const o=t[n];q(o)?(e[n]=o.clientSlot({useState(...s){return I.apply(this,s)},useInitialState(...s){k.apply(this,s)}}),delete e[n].serverSlot,delete e[n].clientSlot):o!==null&&typeof o=="object"?e[n]=P(o):e[n]=o}return e}exports.clientify=P;
+"use client";"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const f=require("react"),v=require("./constants-CbsduCZ7.js"),a=require("./utils-0CTNJ4ZE.js"),V=require("./provider-client-CAHe8VnM.js");function D(t,n,s=[]){return f.useMemo(()=>a.debounce(t,n),s)}const y=t=>{const{vocabStore:n,storage:s,statePath:o,value:e,deserialize:l,serialize:c}=t,d=s.getItem(o);d===null?a.isValueDefined(e)&&s.setItem(o,c(e)):n.set(o,l(d))},R=typeof window>"u",m=R?f.useEffect:f.useLayoutEffect,A=new V.VocabStore,P="Make sure your component is wrapped in StateVocabProvider (RSC) or disable ssr option in setupStorage for SPA (RCC only)";function I(t){const n=R?void 0:a.valueOrFactory(t.storage),s=a.valueOrFactory(t.defaultValue),o=t.bidirectional,e=this[v.STATE_PATH],l=this[v.STATE_VERBOSE],c=this[v.STATE_VERBOSE_PATH],d=this[v.STATE_SSR];let i=V.useStateVocabClientContext({clientContext:t.clientContext,verbose:l});if(!(i instanceof V.VocabStore)){if(d)throw new Error(P);i=A}const S=t.serialize??JSON.stringify,u=t.deserialize??JSON.parse,E=D(t.onSet??(()=>{}),t.delayedSet,[]),g=f.useRef(void 0),z=f.useRef(!1);if(!z.current){z.current=!0;let r=i.get(e);a.isValueDefined(r)||(r=s,a.isValueDefined(r)&&i.set(e,r)),!d&&n&&y({vocabStore:i,storage:n,statePath:e,value:r,serialize:S,deserialize:u})}const C=f.useSyncExternalStore(i.subscribe.bind(i),i.getClientSnapshot.bind(i),i.getServerSnapshot.bind(i));if(l)if(c){const r=a.get(C,c);r&&a.logStyled(r)}else a.logStyled(C);const h=a.get(C,e,s);g.current=h,m(()=>{!d||!n||y({vocabStore:i,storage:n,statePath:e,value:h,serialize:S,deserialize:u})},[]);const w=f.useEffectEvent(r=>{if(r.key!==e)return;const b=r.newValue,T=(b===null?null:u(b))??s;a.isValueDefined(T)&&(i.set(e,T),E(T,g.current))});f.useEffect(()=>{if(o)return window.addEventListener("storage",w),()=>window.removeEventListener("storage",w)},[o]);const x=f.useCallback(r=>{const b=a.isTransformer(r)?r(g.current):r;i.set(e,b),E(b,g.current),n&&n.setItem(e,S(b))},[i,e,E,n,S]),_=f.useCallback(()=>{const r=s;if(!a.isValueDefined(r)){n?.removeItem(e);return}i.set(e,r),E(r,g.current),n&&n.setItem(e,S(r))},[s,i,e,E,n,S]);return[h,x,_]}function p(t){const n=R?void 0:a.valueOrFactory(t.storage),s=a.valueOrFactory(t.defaultValue),o=this[v.STATE_PATH],e=this[v.STATE_VERBOSE],l=this[v.STATE_SSR];let c=V.useStateVocabClientContext({clientContext:t.clientContext,verbose:e});if(!(c instanceof V.VocabStore)){if(l)throw new Error(P);c=A}const d=t.serialize??JSON.stringify,i=t.deserialize??JSON.parse,S=f.useRef(!1);let u;S.current||(S.current=!0,u=c.get(o),a.isValueDefined(u)||(u=s,a.isValueDefined(u)&&c.set(o,u)),!l&&n&&y({vocabStore:c,storage:n,statePath:o,value:u,serialize:d,deserialize:i})),m(()=>{!l||!n||y({vocabStore:c,storage:n,statePath:o,value:u,serialize:d,deserialize:i})},[])}function k(t){return typeof t=="object"&&t!==null&&"clientSlot"in t}function O(t,n={}){const s={};for(const o in t){const e=t[o];k(e)?(s[o]=e.clientSlot({useState(l){return I.apply(this,[{clientContext:n.clientContext,...l}])},useInitialState(l){p.apply(this,[{clientContext:n.clientContext,...l}])}}),delete s[o].serverSlot,delete s[o].clientSlot):e!==null&&typeof e=="object"?s[o]=O(e,n):s[o]=e}return s}exports.StateVocabClientProvider=V.StateVocabClientProvider;exports.clientify=O;

package/dist/client.es.js

@@ -1,127 +1,132 @@
 "use client";
-import { useMemo as B, useRef as V, useSyncExternalStore as D, useEffectEvent as H, useEffect as I, useCallback as T, useLayoutEffect as x } from "react";
-import { S as O, a as P, b as _, c as F } from "./constants-BB1YAX6c.mjs";
-import { a as d, d as G, v as g, g as A, l as C, i as q } from "./utils-xV3x3fTc.mjs";
-import { V as z, u as k } from "./provider-client-C2Aw0Lmi.mjs";
-function K(t, e, n = []) {
-  return B(
-    () => G(t, e),
+import { useMemo as j, useRef as y, useSyncExternalStore as B, useEffectEvent as D, useEffect as P, useCallback as p, useLayoutEffect as H } from "react";
+import { S as A, a as I, b as O, c as F } from "./constants-BB1YAX6c.mjs";
+import { a as d, d as G, v as g, g as T, l as x, i as q } from "./utils-xV3x3fTc.mjs";
+import { V as C, u as _ } from "./provider-client-D0BmMWcY.mjs";
+import { S as ne } from "./provider-client-D0BmMWcY.mjs";
+function K(t, s, i = []) {
+  return j(
+    () => G(t, s),
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    n
+    i
   );
 }
 const E = (t) => {
   const {
-    vocabStore: e,
-    storage: n,
+    vocabStore: s,
+    storage: i,
     statePath: o,
-    value: s,
-    deserialize: f,
-    serialize: a
-  } = t, c = n.getItem(o);
-  c === null ? d(s) && n.setItem(o, a(s)) : e.set(o, f(c));
-}, w = typeof window > "u", J = w ? I : x, L = new z(), N = "Make sure your component is wrapped in StateVocabProvider (RSC) or disable ssr option in setupStorage for SPA (RCC only)";
+    value: e,
+    deserialize: a,
+    serialize: l
+  } = t, u = i.getItem(o);
+  u === null ? d(e) && i.setItem(o, l(e)) : s.set(o, a(u));
+}, z = typeof window > "u", k = z ? P : H, J = new C(), L = "Make sure your component is wrapped in StateVocabProvider (RSC) or disable ssr option in setupStorage for SPA (RCC only)";
 function Q(t) {
-  t ??= {};
-  const e = w ? void 0 : g(t.storage), n = g(t.defaultValue), o = t.bidirectional, s = this[O], f = this[P], a = this[F], c = this[_];
-  let r = k({ verbose: f });
-  if (!(r instanceof z)) {
-    if (c)
-      throw new Error(N);
-    r = L;
+  const s = z ? void 0 : g(t.storage), i = g(t.defaultValue), o = t.bidirectional, e = this[A], a = this[I], l = this[F], u = this[O];
+  let r = _({
+    clientContext: t.clientContext,
+    verbose: a
+  });
+  if (!(r instanceof C)) {
+    if (u)
+      throw new Error(L);
+    r = J;
   }
-  const u = t.serialize ?? JSON.stringify, l = t.deserialize ?? JSON.parse, v = K(
+  const f = t.serialize ?? JSON.stringify, c = t.deserialize ?? JSON.parse, v = K(
     t.onSet ?? (() => {
     }),
     t.delayedSet,
     []
-  ), b = V(void 0), p = V(!1);
-  if (!p.current) {
-    p.current = !0;
-    let i = r.get(s);
-    d(i) || (i = n, d(i) && r.set(s, i)), !c && e && E({
+  ), b = y(void 0), w = y(!1);
+  if (!w.current) {
+    w.current = !0;
+    let n = r.get(e);
+    d(n) || (n = i, d(n) && r.set(e, n)), !u && s && E({
       vocabStore: r,
-      storage: e,
-      statePath: s,
-      value: i,
-      serialize: u,
-      deserialize: l
+      storage: s,
+      statePath: e,
+      value: n,
+      serialize: f,
+      deserialize: c
     });
   }
-  const h = D(
+  const h = B(
     r.subscribe.bind(r),
     r.getClientSnapshot.bind(r),
     r.getServerSnapshot.bind(r)
   );
-  if (f)
-    if (a) {
-      const i = A(h, a);
-      i && C(i);
+  if (a)
+    if (l) {
+      const n = T(h, l);
+      n && x(n);
     } else
-      C(h);
-  const m = A(h, s, n);
-  b.current = m, J(() => {
-    !c || !e || E({
+      x(h);
+  const m = T(h, e, i);
+  b.current = m, k(() => {
+    !u || !s || E({
       vocabStore: r,
-      storage: e,
-      statePath: s,
+      storage: s,
+      statePath: e,
       value: m,
-      serialize: u,
-      deserialize: l
+      serialize: f,
+      deserialize: c
     });
   }, []);
-  const R = H((i) => {
-    if (i.key !== s)
+  const R = D((n) => {
+    if (n.key !== e)
       return;
-    const S = i.newValue, y = (S === null ? null : l(S)) ?? n;
-    d(y) && (r.set(s, y), v(y, b.current));
+    const S = n.newValue, V = (S === null ? null : c(S)) ?? i;
+    d(V) && (r.set(e, V), v(V, b.current));
   });
-  I(() => {
+  P(() => {
     if (o)
       return window.addEventListener("storage", R), () => window.removeEventListener("storage", R);
   }, [o]);
-  const M = T((i) => {
-    const S = q(i) ? i(b.current) : i;
-    r.set(s, S), v(S, b.current), e && e.setItem(s, u(S));
-  }, [r, s, v, e, u]), j = T(() => {
-    const i = n;
-    if (!d(i)) {
-      e?.removeItem(s);
+  const N = p((n) => {
+    const S = q(n) ? n(b.current) : n;
+    r.set(e, S), v(S, b.current), s && s.setItem(e, f(S));
+  }, [r, e, v, s, f]), M = p(() => {
+    const n = i;
+    if (!d(n)) {
+      s?.removeItem(e);
       return;
     }
-    r.set(s, i), v(i, b.current), e && e.setItem(s, u(i));
-  }, [n, r, s, v, e, u]);
+    r.set(e, n), v(n, b.current), s && s.setItem(e, f(n));
+  }, [i, r, e, v, s, f]);
   return [
     m,
-    M,
-    j
+    N,
+    M
   ];
 }
 function U(t) {
-  t ??= {};
-  const e = w ? void 0 : g(t.storage), n = g(t.defaultValue), o = this[O], s = this[P], f = this[_];
-  let a = k({ verbose: s });
-  if (!(a instanceof z)) {
-    if (f)
-      throw new Error(N);
-    a = L;
+  const s = z ? void 0 : g(t.storage), i = g(t.defaultValue), o = this[A], e = this[I], a = this[O];
+  let l = _({
+    clientContext: t.clientContext,
+    verbose: e
+  });
+  if (!(l instanceof C)) {
+    if (a)
+      throw new Error(L);
+    l = J;
   }
-  const c = t.serialize ?? JSON.stringify, r = t.deserialize ?? JSON.parse, u = V(!1);
-  let l;
-  u.current || (u.current = !0, l = a.get(o), d(l) || (l = n, d(l) && a.set(o, l)), !f && e && E({
-    vocabStore: a,
-    storage: e,
+  const u = t.serialize ?? JSON.stringify, r = t.deserialize ?? JSON.parse, f = y(!1);
+  let c;
+  f.current || (f.current = !0, c = l.get(o), d(c) || (c = i, d(c) && l.set(o, c)), !a && s && E({
+    vocabStore: l,
+    storage: s,
     statePath: o,
-    value: l,
-    serialize: c,
+    value: c,
+    serialize: u,
     deserialize: r
-  })), J(() => {
-    !f || !e || E({
-      vocabStore: a,
-      storage: e,
+  })), k(() => {
+    !a || !s || E({
+      vocabStore: l,
+      storage: s,
       statePath: o,
-      value: l,
-      serialize: c,
+      value: c,
+      serialize: u,
       deserialize: r
     });
   }, []);
@@ -129,21 +134,28 @@ function U(t) {
 function W(t) {
   return typeof t == "object" && t !== null && "clientSlot" in t;
 }
-function X(t) {
-  const e = {};
-  for (const n in t) {
-    const o = t[n];
-    W(o) ? (e[n] = o.clientSlot({
-      useState(...s) {
-        return Q.apply(this, s);
+function X(t, s = {}) {
+  const i = {};
+  for (const o in t) {
+    const e = t[o];
+    W(e) ? (i[o] = e.clientSlot({
+      useState(a) {
+        return Q.apply(this, [{
+          clientContext: s.clientContext,
+          ...a
+        }]);
       },
-      useInitialState(...s) {
-        U.apply(this, s);
+      useInitialState(a) {
+        U.apply(this, [{
+          clientContext: s.clientContext,
+          ...a
+        }]);
       }
-    }), delete e[n].serverSlot, delete e[n].clientSlot) : o !== null && typeof o == "object" ? e[n] = X(o) : e[n] = o;
+    }), delete i[o].serverSlot, delete i[o].clientSlot) : e !== null && typeof e == "object" ? i[o] = X(e, s) : i[o] = e;
   }
-  return e;
+  return i;
 }
 export {
+  ne as StateVocabClientProvider,
   X as clientify
 };

package/dist/provider-client-CAHe8VnM.js

@@ -0,0 +1 @@
+"use client";"use strict";const h=require("react/jsx-runtime"),c=require("react"),r=require("./utils-0CTNJ4ZE.js"),a=c.createContext({});function S(e){const t=c.useContext(e.clientContext??a);return e.verbose&&console.log(`[Store uid]: ${t.uid}`),t}class u{#t;#e;constructor(t){this.uid=Math.random().toString(36).slice(2),this.#t=t??{},this.#e=new Set}subscribe(t){return this.#e.add(t),()=>this.#e.delete(t)}getClientSnapshot(){return this.#t}getServerSnapshot(){return this.#t}get(t){return r.get(this.#t,t)}set(t,n){const s=r.get(this.#t,t),i=r.isTransformer(n)?n(s):n,o={...this.#t};r.set(o,t,i),this.#t=o,this.#e.forEach(l=>l())}}function b(e){const{clientContext:t,value:n,children:s}=e,[i]=c.useState(()=>new u(n)),o=t??a;return h.jsx(o.Provider,{value:i,children:s})}exports.StateVocabClientProvider=b;exports.VocabStore=u;exports.useStateVocabClientContext=S;

package/dist/provider-client-D0BmMWcY.mjs

@@ -0,0 +1,41 @@
+"use client";
+import { jsx as u } from "react/jsx-runtime";
+import { createContext as l, useContext as h, useState as S } from "react";
+import { g as i, i as C, s as b } from "./utils-xV3x3fTc.mjs";
+const c = l({});
+function m(e) {
+  const t = h(e.clientContext ?? c);
+  return e.verbose && console.log(`[Store uid]: ${t.uid}`), t;
+}
+class d {
+  #t;
+  #e;
+  constructor(t) {
+    this.uid = Math.random().toString(36).slice(2), this.#t = t ?? {}, this.#e = /* @__PURE__ */ new Set();
+  }
+  subscribe(t) {
+    return this.#e.add(t), () => this.#e.delete(t);
+  }
+  getClientSnapshot() {
+    return this.#t;
+  }
+  getServerSnapshot() {
+    return this.#t;
+  }
+  get(t) {
+    return i(this.#t, t);
+  }
+  set(t, o) {
+    const n = i(this.#t, t), s = C(o) ? o(n) : o, r = { ...this.#t };
+    b(r, t, s), this.#t = r, this.#e.forEach((a) => a());
+  }
+}
+function v(e) {
+  const { clientContext: t, value: o, children: n } = e, [s] = S(() => new d(o));
+  return /* @__PURE__ */ u((t ?? c).Provider, { value: s, children: n });
+}
+export {
+  v as S,
+  d as V,
+  m as u
+};

package/dist/server.cjs.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("react/jsx-runtime"),S=require("./constants-CbsduCZ7.js"),d=require("react"),v=require("node:async_hooks"),f=require("./provider-client-B4XQ24JB.js"),b=require("./utils-0CTNJ4ZE.js");function y(e){const t=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(e){for(const r in e)if(r!=="default"){const n=Object.getOwnPropertyDescriptor(e,r);Object.defineProperty(t,r,n.get?n:{enumerable:!0,get:()=>e[r]})}}return t.default=e,Object.freeze(t)}const p=y(v),a=e=>{if(d.useState)throw new Error(`${e} only intended for Server Components`)};let s=null;try{a("StateVocabServerContext"),s=new p.AsyncLocalStorage}catch{s=null}const g=({value:e})=>(s?.enterWith({value:e}),null),P=({children:e})=>e,j=async e=>{a("StateVocabServerContext.Provider");const{value:t,children:r}=e;return o.jsxs(o.Fragment,{children:[o.jsx(g,{value:t}),r]})},h=()=>(a("getStateVocab"),s?.getStore()?.value),x={Provider:s?j:P},V=({value:e,children:t})=>o.jsx(x.Provider,{value:e,children:t});function m(e){const{children:t,value:r={}}=e;return o.jsx(V,{value:r,children:o.jsx(f.StateVocabClientProvider,{value:r,children:t})})}const O="Make sure your component is wrapped in StateVocabProvider";function C(){const e=this[S.STATE_PATH],t=h();if(!t)throw new Error(O);return b.get(t,e)}function E(e){return typeof e=="object"&&e!==null&&"serverSlot"in e}function l(e,t){const r={};for(const n in e){const c=e[n];if(E(c))r[n]=c.serverSlot({getState(...i){return C.apply(this,i)}}),delete r[n].serverSlot,delete r[n].clientSlot;else if(c!==null&&typeof c=="object"){const i=u=>t({[n]:u});r[n]=l(c,i)}else r[n]=c}return r.seed=n=>t(n),r}function k(e){return{...l(e,t=>t),StateVocabProvider({children:t,value:r}){return o.jsx(m,{value:r,children:t})}}}exports.serverify=k;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("react/jsx-runtime"),S=require("./constants-CbsduCZ7.js"),c=require("react"),d=require("./provider-client-CAHe8VnM.js"),y=require("./utils-0CTNJ4ZE.js"),i=e=>{if(c.useState)throw new Error(`${e} only intended for Server Components`)},a=c.cache(()=>new Map),x=({children:e})=>e,C=async e=>{i("StateVocabServerContext.Provider");const{serverContextKey:n,value:t,children:r}=e;return a().set(n,t),r},f=e=>(i("getStateVocab"),a().get(e)),b={Provider:c.useState?x:C},p=e=>{const{serverContextKey:n,value:t,children:r}=e;return s.jsx(b.Provider,{serverContextKey:n,value:t,children:r})};function P(e){const{children:n,serverContextKey:t,clientContext:r,value:o={}}=e;return s.jsx(p,{serverContextKey:t,value:o,children:s.jsx(d.StateVocabClientProvider,{clientContext:r,value:o,children:n})})}const h="Make sure your component is wrapped in StateVocabProvider";function w(e){const n=this[S.STATE_PATH],t=f(e.serverContextKey);if(!t)throw new Error(h);return y.get(t,n)}function g(e){return typeof e=="object"&&e!==null&&"serverSlot"in e}function l(e,n){const t={};for(const r in e){const o=e[r];if(g(o))t[r]=o.serverSlot({getState(){return w.apply(this,[{serverContextKey:n.serverContextKey}])}}),delete t[r].serverSlot,delete t[r].clientSlot;else if(o!==null&&typeof o=="object"){const u=v=>n.wrap({[r]:v});t[r]=l(o,{serverContextKey:n.serverContextKey,wrap:u})}else t[r]=o}return t.seed=r=>n.wrap(r),t}function K(e,n){const t=Symbol();return{...l(e,{serverContextKey:t,wrap:r=>r}),StateVocabProvider({children:r,value:o}){return s.jsx(P,{clientContext:n.clientContext,serverContextKey:t,value:o,children:r})}}}exports.serverify=K;

package/dist/server.es.js

@@ -1,70 +1,104 @@
-import { jsxs as u, Fragment as v, jsx as c } from "react/jsx-runtime";
-import { S as d } from "./constants-BB1YAX6c.mjs";
-import f from "react";
-import * as p from "node:async_hooks";
-import { S as m } from "./provider-client-C2Aw0Lmi.mjs";
-import { g as b } from "./utils-xV3x3fTc.mjs";
-const i = (e) => {
-  if (f.useState)
+import { jsx as c } from "react/jsx-runtime";
+import { S as u } from "./constants-BB1YAX6c.mjs";
+import s, { cache as d } from "react";
+import { S as f } from "./provider-client-D0BmMWcY.mjs";
+import { g as y } from "./utils-xV3x3fTc.mjs";
+const a = (e) => {
+  if (s.useState)
     throw new Error(`${e} only intended for Server Components`);
+}, i = d(() => /* @__PURE__ */ new Map()), p = ({ children: e }) => e, C = async (e) => {
+  a("StateVocabServerContext.Provider");
+  const { serverContextKey: o, value: t, children: r } = e;
+  return i().set(o, t), r;
+}, x = (e) => (a("getStateVocab"), i().get(e)), b = {
+  Provider: s.useState ? p : C
+}, m = (e) => {
+  const { serverContextKey: o, value: t, children: r } = e;
+  return /* @__PURE__ */ c(
+    b.Provider,
+    {
+      serverContextKey: o,
+      value: t,
+      children: r
+    }
+  );
 };
-let s = null;
-try {
-  i("StateVocabServerContext"), s = new p.AsyncLocalStorage();
-} catch {
-  s = null;
-}
-const h = ({ value: e }) => (s?.enterWith({ value: e }), null), y = ({ children: e }) => e, P = async (e) => {
-  i("StateVocabServerContext.Provider");
-  const { value: t, children: r } = e;
-  return /* @__PURE__ */ u(v, { children: [
-    /* @__PURE__ */ c(h, { value: t }),
-    r
-  ] });
-}, g = () => (i("getStateVocab"), s?.getStore()?.value), V = {
-  Provider: s ? P : y
-}, E = ({ value: e, children: t }) => /* @__PURE__ */ c(V.Provider, { value: e, children: t });
-function x(e) {
-  const { children: t, value: r = {} } = e;
-  return /* @__PURE__ */ c(E, { value: r, children: /* @__PURE__ */ c(m, { value: r, children: t }) });
+function h(e) {
+  const {
+    children: o,
+    serverContextKey: t,
+    clientContext: r,
+    value: n = {}
+  } = e;
+  return /* @__PURE__ */ c(
+    m,
+    {
+      serverContextKey: t,
+      value: n,
+      children: /* @__PURE__ */ c(
+        f,
+        {
+          clientContext: r,
+          value: n,
+          children: o
+        }
+      )
+    }
+  );
 }
-const C = "Make sure your component is wrapped in StateVocabProvider";
-function w() {
-  const e = this[d], t = g();
+const P = "Make sure your component is wrapped in StateVocabProvider";
+function w(e) {
+  const o = this[u], t = x(e.serverContextKey);
   if (!t)
-    throw new Error(C);
-  return b(t, e);
+    throw new Error(P);
+  return y(t, o);
 }
-function R(e) {
+function K(e) {
   return typeof e == "object" && e !== null && "serverSlot" in e;
 }
-function l(e, t) {
-  const r = {};
-  for (const o in e) {
-    const n = e[o];
-    if (R(n))
-      r[o] = n.serverSlot({
-        // Slot definition
-        getState(...a) {
-          return w.apply(this, a);
+function v(e, o) {
+  const t = {};
+  for (const r in e) {
+    const n = e[r];
+    if (K(n))
+      t[r] = n.serverSlot({
+        getState() {
+          return w.apply(this, [{
+            serverContextKey: o.serverContextKey
+          }]);
         }
-      }), delete r[o].serverSlot, delete r[o].clientSlot;
+      }), delete t[r].serverSlot, delete t[r].clientSlot;
     else if (n !== null && typeof n == "object") {
-      const a = (S) => t({ [o]: S });
-      r[o] = l(n, a);
+      const l = (S) => o.wrap({ [r]: S });
+      t[r] = v(n, {
+        serverContextKey: o.serverContextKey,
+        wrap: l
+      });
     } else
-      r[o] = n;
+      t[r] = n;
   }
-  return r.seed = (o) => t(o), r;
+  return t.seed = (r) => o.wrap(r), t;
 }
-function M(e) {
+function k(e, o) {
+  const t = /* @__PURE__ */ Symbol();
   return {
-    ...l(e, (t) => t),
-    StateVocabProvider({ children: t, value: r }) {
-      return /* @__PURE__ */ c(x, { value: r, children: t });
+    ...v(e, {
+      serverContextKey: t,
+      wrap: (r) => r
+    }),
+    StateVocabProvider({ children: r, value: n }) {
+      return /* @__PURE__ */ c(
+        h,
+        {
+          clientContext: o.clientContext,
+          serverContextKey: t,
+          value: n,
+          children: r
+        }
+      );
     }
   };
 }
 export {
-  M as serverify
+  k as serverify
 };

package/dist/types/client.d.ts

@@ -1 +1,2 @@
 export { clientify } from "./setup.client";
+export { StateVocabClientProvider } from "./provider.client";

package/dist/types/context.client.d.ts

@@ -1,8 +1,10 @@
+import { type Context } from "react";
 import VocabStore from "./store";
-export declare const StateVocabClientContext: import("react").Context<VocabStore>;
+export declare const DefaultStateVocabClientContext: Context<VocabStore>;
 /**
  * @see method from from https://zustand.docs.pmnd.rs/learn/guides/nextjs
  */
 export declare function useStateVocabClientContext(options: {
+    clientContext: Context<VocabStore> | undefined;
     verbose: boolean;
 }): VocabStore;

package/dist/types/context.server.d.ts

@@ -1,10 +1,12 @@
+import React from "react";
 import type { PropsWithChildren, ReactNode } from "react";
 import type { Vocab } from "./state.types";
-export declare const getStateVocab: () => Vocab | undefined;
+export declare const getStateVocab: (serverContextKey: symbol) => Vocab | undefined;
 export declare const StateVocabServerContext: {
     Provider: (({ children }: PropsWithChildren<{
         value?: Vocab;
     }>) => ReactNode) | ((props: PropsWithChildren<{
+        serverContextKey: symbol;
         value: Vocab;
-    }>) => Promise<import("react/jsx-runtime").JSX.Element>);
+    }>) => Promise<React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | (string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined)>);
 };

package/dist/types/provider.client.d.ts

@@ -1,5 +1,7 @@
-import { type PropsWithChildren } from "react";
+import { type Context, type PropsWithChildren } from "react";
+import VocabStore from "./store";
 import type { Vocab } from "./state.types";
 export declare function StateVocabClientProvider(props: PropsWithChildren<{
+    clientContext?: Context<VocabStore>;
     value?: Vocab;
 }>): import("react/jsx-runtime").JSX.Element;

package/dist/types/provider.d.ts

@@ -1,5 +1,8 @@
-import type { PropsWithChildren } from "react";
+import type { Context, PropsWithChildren } from "react";
 import type { Vocab } from "./state.types";
+import VocabStore from "./store";
 export declare function StateVocabProvider(props: PropsWithChildren<{
     value?: Vocab;
+    serverContextKey: symbol;
+    clientContext: Context<VocabStore>;
 }>): import("react/jsx-runtime").JSX.Element;

package/dist/types/provider.server.d.ts

@@ -2,4 +2,5 @@ import type { Vocab } from "./state.types";
 import type { PropsWithChildren } from "react";
 export declare const StateVocabServerProvider: React.FC<PropsWithChildren<{
     value: Vocab;
+    serverContextKey: symbol;
 }>>;

package/dist/types/setup.client.d.ts

@@ -1,6 +1,10 @@
+import { type Context } from "react";
 import type { ValueOrTransformer, VocabThis } from "./state.types";
+import VocabStore from "./store";
 import type { UseInitialStateOptions, UseStateOptions } from "./setup.types";
-declare function useState<V>(this: VocabThis, options?: UseStateOptions<V>): readonly [V, (nextValue: ValueOrTransformer<V>) => void, () => void];
+declare function useState<V>(this: VocabThis, options: UseStateOptions<V> & {
+    clientContext: Context<VocabStore> | undefined;
+}): readonly [V, (nextValue: ValueOrTransformer<V>) => void, () => void];
 type Placeholder<V> = {
     useState(options?: UseStateOptions<V>): ReturnType<typeof useState<V>>;
     useInitialState(options?: UseInitialStateOptions<V>): void;
@@ -11,5 +15,7 @@ type Slot<V> = {
 type Clientified<R> = R extends Slot<infer TValue> ? Placeholder<TValue> : R extends object ? {
     [K in keyof R]: Clientified<R[K]>;
 } : R;
-export declare function clientify<R extends object>(tree: R): Clientified<R>;
+export declare function clientify<R extends object>(tree: R, clientifyOptions?: {
+    clientContext?: Context<object>;
+}): Clientified<R>;
 export {};

package/dist/types/setup.server.d.ts

@@ -1,4 +1,4 @@
-import type { PropsWithChildren, ReactNode } from "react";
+import type { Context, PropsWithChildren, ReactNode } from "react";
 import type { Vocab } from "./state.types";
 type Placeholder<V> = {
     getState(): V;
@@ -22,5 +22,7 @@ type ServerifyResult<R extends object> = {
 } & {
     [K in keyof R]: Serverified<R[K]>;
 };
-export declare function serverify<R extends object>(tree: R): ServerifyResult<R>;
+export declare function serverify<R extends object>(tree: R, serverifyOptions: {
+    clientContext: Context<object>;
+}): ServerifyResult<R>;
 export {};

package/dist/types/state.d.ts

@@ -51,7 +51,5 @@ export declare function defineState<V>(superOptions?: {
         }): void;
     };
     /** Returns the fully qualified state name (dot-separated path). */
-    toString(this: {
-        [STATE_PATH]: string;
-    }): string;
+    toString(this: VocabThis): string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yakocloud/state-vocab",
-  "version": "4.0.2",
+  "version": "4.1.0",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",
   "types": "dist/types/index.d.ts",

package/dist/provider-client-B4XQ24JB.js

@@ -1 +0,0 @@
-"use client";"use strict";const h=require("react/jsx-runtime"),r=require("react"),s=require("./utils-0CTNJ4ZE.js"),c=r.createContext({});function S(o){const t=r.useContext(c);return o.verbose&&console.log(`[Store uid]: ${t.uid}`),t}class u{#t;#e;constructor(t){this.uid=Math.random().toString(36).slice(2),this.#t=t??{},this.#e=new Set}subscribe(t){return this.#e.add(t),()=>this.#e.delete(t)}getClientSnapshot(){return this.#t}getServerSnapshot(){return this.#t}get(t){return s.get(this.#t,t)}set(t,e){const n=s.get(this.#t,t),a=s.isTransformer(e)?e(n):e,i={...this.#t};s.set(i,t,a),this.#t=i,this.#e.forEach(l=>l())}}function b(o){const{children:t,value:e}=o,[n]=r.useState(()=>new u(e));return h.jsx(c.Provider,{value:n,children:t})}exports.StateVocabClientProvider=b;exports.VocabStore=u;exports.useStateVocabClientContext=S;

package/dist/provider-client-C2Aw0Lmi.mjs

@@ -1,41 +0,0 @@
-"use client";
-import { jsx as u } from "react/jsx-runtime";
-import { createContext as h, useContext as l, useState as S } from "react";
-import { g as n, i as d, s as b } from "./utils-xV3x3fTc.mjs";
-const i = h({});
-function V(s) {
-  const t = l(i);
-  return s.verbose && console.log(`[Store uid]: ${t.uid}`), t;
-}
-class f {
-  #t;
-  #e;
-  constructor(t) {
-    this.uid = Math.random().toString(36).slice(2), this.#t = t ?? {}, this.#e = /* @__PURE__ */ new Set();
-  }
-  subscribe(t) {
-    return this.#e.add(t), () => this.#e.delete(t);
-  }
-  getClientSnapshot() {
-    return this.#t;
-  }
-  getServerSnapshot() {
-    return this.#t;
-  }
-  get(t) {
-    return n(this.#t, t);
-  }
-  set(t, e) {
-    const o = n(this.#t, t), c = d(e) ? e(o) : e, r = { ...this.#t };
-    b(r, t, c), this.#t = r, this.#e.forEach((a) => a());
-  }
-}
-function g(s) {
-  const { children: t, value: e } = s, [o] = S(() => new f(e));
-  return /* @__PURE__ */ u(i.Provider, { value: o, children: t });
-}
-export {
-  g as S,
-  f as V,
-  V as u
-};