@k8ordo/state 0.2.0 → 1.1.0

package/dist/storage-state.d.mts

@@ -0,0 +1,38 @@
+import { StateSchema } from "./schema/object.mjs";
+import { RowCodec, Versioning } from "./row/codec.mjs";
+//#region src/storage-state.d.ts
+type StorageState<Kind extends 'local' | 'session', Schema extends StateSchema> = {
+  kind: Kind;
+  /** Identity of this state: the storage key and the store registry slot. */
+  key: string;
+  /** The schema as passed. */
+  schema: Schema;
+  /** The Web Storage key the values are written under: `k8ordo-state:<key>`. */
+  storageKey: string;
+  /**
+   * A JavaScript expression, for an inline `<script>`, that evaluates in the
+   * browser to the stored object — or `null` when nothing is stored, the JSON
+   * is corrupt, the value is not an object, storage cannot be read, or (for a
+   * versioned local state) the row was written by another version. Neither
+   * the schema nor `migrate` runs there: treat the result as untrusted and
+   * read only the fields you need, each with its own fallback.
+   */
+  inlineRead: () => string;
+};
+/**
+ * App-scope state that lives in localStorage: device-persistent, shared
+ * across tabs, never page-bound — which is why it is its own definition kind
+ * instead of a slot on a page state.
+ */
+export type LocalState<Schema extends StateSchema = StateSchema> = StorageState<'local', Schema>;
+/**
+ * App-scope state that lives in sessionStorage: kept through reloads of the
+ * tab and gone when the tab closes, shared with no other tab — built the way
+ * local state is, over the other Web Storage area.
+ */
+export type SessionState<Schema extends StateSchema = StateSchema> = StorageState<'session', Schema>;
+export declare const storageCodecOf: (def: LocalState | SessionState) => RowCodec;
+export declare const defineLocalState: <Schema extends StateSchema>(key: string, schema: Schema, versioning?: Versioning<Schema>) => LocalState<Schema>;
+export declare const defineSessionState: <Schema extends StateSchema>(key: string, schema: Schema) => SessionState<Schema>;
+//#endregion
+export {};

package/dist/storage-state.mjs

@@ -0,0 +1,37 @@
+import { createRowCodec } from "./row/codec.mjs";
+//#region src/storage-state.ts
+const STORAGE_KEY_PREFIX = "k8ordo-state:";
+/**
+* The key as a JavaScript string literal. `JSON.stringify` escapes it for
+* JavaScript; `<` is escaped on top so the literal can never close the inline
+* `<script>` it is written into, whatever the key contains.
+*/
+const literalOf = (text) => JSON.stringify(text).replaceAll("<", String.raw`\u003c`);
+const isObjectExpression = (value) => `${value}!==null&&typeof ${value}==="object"&&!Array.isArray(${value})`;
+const inlineReadOf = (area, storageKey, version) => {
+	const row = `JSON.parse(${area}.getItem(${literalOf(storageKey)}))`;
+	return version === void 0 ? `(()=>{try{const v=${row};return ${isObjectExpression("v")}?v:null}catch{return null}})()` : `(()=>{try{const r=${row};const v=Array.isArray(r)&&r.length===2&&r[0]===${String(version)}?r[1]:null;return ${isObjectExpression("v")}?v:null}catch{return null}})()`;
+};
+const codecs = /* @__PURE__ */ new WeakMap();
+const storageCodecOf = (def) => {
+	const codec = codecs.get(def);
+	if (codec === void 0) throw new TypeError(`"${def.key}" was not created by ${def.kind === "local" ? "defineLocalState" : "defineSessionState"} of this module instance`);
+	return codec;
+};
+const defineStorageState = (kind, area, key, schema, versioning) => {
+	const storageKey = `${STORAGE_KEY_PREFIX}${key}`;
+	const codec = createRowCodec(schema, kind, key, versioning);
+	const def = {
+		kind,
+		key,
+		schema,
+		storageKey,
+		inlineRead: () => inlineReadOf(area, storageKey, codec.version)
+	};
+	codecs.set(def, codec);
+	return def;
+};
+const defineLocalState = (key, schema, versioning) => defineStorageState("local", "localStorage", key, schema, versioning);
+const defineSessionState = (key, schema) => defineStorageState("session", "sessionStorage", key, schema, void 0);
+//#endregion
+export { defineLocalState, defineSessionState, storageCodecOf };

package/dist/store/cookie-store.d.mts

@@ -0,0 +1,12 @@
+import { StateValues } from "../schema/object.mjs";
+import { CookieState } from "../cookie-state.mjs";
+import { Store } from "./core.mjs";
+//#region src/store/cookie-store.d.ts
+export declare const cookieStoreOf: (def: CookieState) => Store;
+/**
+ * What SSR and the hydration render see: the values the server read from the
+ * request's cookies when the caller passed them down; the defaults otherwise.
+ * Pure on purpose: the server must never touch `document` or create a store.
+ */
+export declare const cookieInitialSnapshot: (def: CookieState, initialCookie: Readonly<StateValues> | undefined) => StateValues;
+//#endregion

package/dist/store/cookie-store.mjs

@@ -0,0 +1,129 @@
+import { cookieCodecOf, parseCookieText } from "../cookie-state.mjs";
+import { createHandle, createStoreCore, resolvePatch } from "./core.mjs";
+import { getOrCreateStore } from "./registry.mjs";
+//#region src/store/cookie-store.ts
+const MAX_AGE = 3456e4;
+const rawCookie = (name) => {
+	for (const part of document.cookie.split(";")) {
+		const at = part.indexOf("=");
+		if (at !== -1 && part.slice(0, at).trim() === name) return part.slice(at + 1).trim();
+	}
+};
+const decoded = (raw) => {
+	if (raw === void 0) return void 0;
+	try {
+		return decodeURIComponent(raw);
+	} catch {
+		return;
+	}
+};
+const createCookieStore = (def) => {
+	const codec = cookieCodecOf(def);
+	const { cookieName } = def;
+	const readRow = () => codec.read(parseCookieText(decoded(rawCookie(cookieName))));
+	const read = () => readRow().values;
+	let pending = null;
+	let handle = null;
+	let writing = 0;
+	let missed = false;
+	const sync = () => {
+		if (writing > 0) {
+			missed = true;
+			return;
+		}
+		missed = false;
+		const { values: fresh, stale } = readRow();
+		if (stale) writeBack();
+		core.applyNext(pending === null ? fresh : {
+			...fresh,
+			...pending
+		});
+	};
+	const onChange = (event) => {
+		if ([...event.changed, ...event.deleted].some((cookie) => cookie.name === cookieName)) sync();
+	};
+	cookieStore.addEventListener("change", onChange);
+	const write = async (patch, current) => {
+		try {
+			const target = codec.salvage({
+				...read(),
+				...patch
+			});
+			const init = {
+				name: cookieName,
+				value: encodeURIComponent(JSON.stringify(codec.row(target))),
+				path: "/",
+				sameSite: "lax",
+				maxAge: MAX_AGE
+			};
+			await cookieStore.set(init);
+		} catch (error) {
+			writing -= 1;
+			if (missed) sync();
+			current.fail(error);
+			return;
+		}
+		writing -= 1;
+		sync();
+		current.settle();
+	};
+	let writes = Promise.resolve();
+	const enqueue = (patch, current) => {
+		writing += 1;
+		writes = writes.then(() => write(patch, current));
+	};
+	const flush = () => {
+		const patch = pending;
+		const current = handle;
+		pending = null;
+		handle = null;
+		enqueue(patch, current);
+	};
+	function writeBack() {
+		enqueue({}, createHandle());
+	}
+	const first = readRow();
+	const core = createStoreCore(codec.keys, first.values);
+	if (first.stale) writeBack();
+	const update = (patch) => {
+		const resolved = resolvePatch(patch, core.snapshot(), codec.keys, def.key);
+		if (pending === null) {
+			pending = {};
+			handle = createHandle();
+			queueMicrotask(flush);
+		}
+		Object.assign(pending, resolved);
+		const echoed = codec.salvage({
+			...core.snapshot(),
+			...pending
+		});
+		for (const key of Object.keys(pending)) pending[key] = echoed[key];
+		core.applyNext(echoed);
+		return handle.external;
+	};
+	return {
+		subscribe: core.subscribe,
+		getSnapshot: core.getSnapshot,
+		update,
+		dispose: () => {
+			cookieStore.removeEventListener("change", onChange);
+			core.clear();
+		}
+	};
+};
+const cookieStoreOf = (def) => getOrCreateStore("cookie", def.key, () => createCookieStore(def));
+/**
+* What SSR and the hydration render see: the values the server read from the
+* request's cookies when the caller passed them down; the defaults otherwise.
+* Pure on purpose: the server must never touch `document` or create a store.
+*/
+const cookieInitialSnapshot = (def, initialCookie) => {
+	const codec = cookieCodecOf(def);
+	const base = { ...codec.defaults };
+	if (initialCookie !== void 0) {
+		for (const key of codec.keys) if (key in initialCookie) base[key] = initialCookie[key];
+	}
+	return base;
+};
+//#endregion
+export { cookieInitialSnapshot, cookieStoreOf };

package/dist/store/core.d.mts

@@ -4,17 +4,18 @@ import { StateValues } from "../schema/object.mjs";
  * Mirrors `navigation.navigate()`'s own return shape: an object holding the
  * promises rather than a promise, so fire-and-forget callers ignore it
  * without tripping no-floating-promises, and the 5% that await pick a stage.
- * Slots with no navigation behind them return both promises pre-settled —
- * the type stays uniform across every kind of state.
+ * Slots with no navigation behind them return the same pair, settled or
+ * rejected by the store itself — the type stays uniform across every kind of
+ * state.
  */
-type UpdateHandle = {
+export type UpdateHandle = {
   /** The write is in its home (history entry, storage, memory). */
   committed: Promise<void>;
   /** All downstream work (a router's intercept fetch/render) is done. */
   finished: Promise<void>;
 };
-type Patch = StateValues | ((current: StateValues) => StateValues);
-type Store = {
+export type Patch = StateValues | ((current: StateValues) => StateValues);
+export type Store = {
   subscribe: (keys: readonly string[] | null, notify: () => void) => () => void;
   getSnapshot: (sig: string, keys: readonly string[] | null) => StateValues;
   update: (patch: Patch, options?: {
@@ -22,7 +23,7 @@ type Store = {
   }) => UpdateHandle;
   dispose: () => void;
 };
-type Handle = {
+export type Handle = {
   external: UpdateHandle;
   settle: () => void;
   fail: (error: unknown) => void;
@@ -31,8 +32,8 @@ type Handle = {
     finished?: Promise<unknown> | undefined;
   }) => void;
 };
-declare const createHandle: () => Handle;
-type StoreCore = {
+export declare const createHandle: () => Handle;
+export type StoreCore = {
   snapshot: () => StateValues;
   applyNext: (next: StateValues) => void;
   subscribe: Store['subscribe'];
@@ -44,11 +45,10 @@ type StoreCore = {
  * exact per-key change detection, and notification only to the listeners
  * whose subscribed keys actually changed.
  */
-declare const createStoreCore: (keys: readonly string[], initial: StateValues) => StoreCore;
+export declare const createStoreCore: (keys: readonly string[], initial: StateValues) => StoreCore;
 /**
  * The unknown-field guard every store shares: the typed API already prevents
  * this, so reaching it means an untyped caller — fail loudly, not silently.
  */
-declare const resolvePatch: (patch: Patch, current: StateValues, keys: readonly string[], label: string) => StateValues;
-//#endregion
-export { Handle, Patch, Store, StoreCore, UpdateHandle, createHandle, createStoreCore, resolvePatch };
+export declare const resolvePatch: (patch: Patch, current: StateValues, keys: readonly string[], label: string) => StateValues;
+//#endregion

package/dist/store/memory-store.d.mts

@@ -2,8 +2,7 @@ import { StateValues } from "../schema/object.mjs";
 import { MemoryState } from "../memory-state.mjs";
 import { Store } from "./core.mjs";
 //#region src/store/memory-store.d.ts
-declare const memoryStoreOf: (def: MemoryState) => Store;
+export declare const memoryStoreOf: (def: MemoryState) => Store;
 /** SSR renders the initial values — static, so no cross-request concern. */
-declare const memoryInitialSnapshot: (def: MemoryState) => StateValues;
-//#endregion
-export { memoryInitialSnapshot, memoryStoreOf };
+export declare const memoryInitialSnapshot: (def: MemoryState) => StateValues;
+//#endregion

package/dist/store/page-store.d.mts

@@ -2,20 +2,21 @@ import { StateValues } from "../schema/object.mjs";
 import { PageState } from "../page-state.mjs";
 import { Store } from "./core.mjs";
 //#region src/store/page-store.d.ts
-type UpdateOptions = {
+export type UpdateOptions = {
   /**
    * `replace` by default: an update is a refinement of the current entry.
-   * Opt into `push` for the updates the back button should undo.
+   * Opt into `push` for the updates the back button should undo. It applies
+   * only when a url value changes; an entry-only write rewrites the current
+   * entry in place.
    */
   history?: 'push' | 'replace';
 };
-declare const pageStoreOf: (def: PageState) => Store;
+export declare const pageStoreOf: (def: PageState) => Store;
 /**
  * What SSR and the hydration render see: the RSC-parsed url when the caller
  * passed one down; defaults for everything else — the entry slot never
  * reaches the server. Pure on purpose: the server must never touch
  * `navigation` or create a store.
  */
-declare const pageInitialSnapshot: (def: PageState, initialUrl: Readonly<StateValues> | undefined) => StateValues;
-//#endregion
-export { UpdateOptions, pageInitialSnapshot, pageStoreOf };
+export declare const pageInitialSnapshot: (def: PageState, initialUrl: Readonly<StateValues> | undefined) => StateValues;
+//#endregion

package/dist/store/registry.d.mts

@@ -1,5 +1,5 @@
 //#region src/store/registry.d.ts
-declare const getOrCreateStore: <Store extends {
+export declare const getOrCreateStore: <Store extends {
   dispose?: () => void;
 }>(scope: string, key: string, create: () => Store) => Store;
 /**
@@ -7,6 +7,5 @@ declare const getOrCreateStore: <Store extends {
  * would carry state from one test into the next. Unmount components first —
  * mounted hooks keep their old store through closures.
  */
-declare const resetStateRegistry: () => void;
-//#endregion
-export { getOrCreateStore, resetStateRegistry };
+export declare const resetStateRegistry: () => void;
+//#endregion

package/dist/store/storage-store.d.mts

@@ -0,0 +1,9 @@
+import { StateValues } from "../schema/object.mjs";
+import { LocalState, SessionState } from "../storage-state.mjs";
+import { Store } from "./core.mjs";
+//#region src/store/storage-store.d.ts
+export declare const localStoreOf: (def: LocalState) => Store;
+export declare const sessionStoreOf: (def: SessionState) => Store;
+/** SSR and hydration see the defaults — the server has no Web Storage. */
+export declare const storageInitialSnapshot: (def: LocalState | SessionState) => StateValues;
+//#endregion

package/dist/store/storage-store.mjs

@@ -0,0 +1,97 @@
+import { storageCodecOf } from "../storage-state.mjs";
+import { createHandle, createStoreCore, resolvePatch } from "./core.mjs";
+import { getOrCreateStore } from "./registry.mjs";
+//#region src/store/storage-store.ts
+const createStorageStore = (def, storage) => {
+	const codec = storageCodecOf(def);
+	const { storageKey } = def;
+	const write = (values) => {
+		storage.setItem(storageKey, JSON.stringify(codec.row(values)));
+	};
+	const readRow = () => {
+		const text = storage.getItem(storageKey);
+		let row;
+		try {
+			row = text === null ? void 0 : JSON.parse(text);
+		} catch {
+			row = void 0;
+		}
+		return codec.read(row);
+	};
+	const read = () => readRow().values;
+	const upgrade = () => {
+		queueMicrotask(() => {
+			const { values, stale } = readRow();
+			if (!stale) return;
+			try {
+				write(values);
+			} catch {}
+		});
+	};
+	const first = readRow();
+	const core = createStoreCore(codec.keys, first.values);
+	if (first.stale) upgrade();
+	let pending = null;
+	let handle = null;
+	const onStorage = (event) => {
+		if (event.storageArea !== storage) return;
+		if (event.key !== storageKey && event.key !== null) return;
+		const { values: fresh, stale } = readRow();
+		if (stale) upgrade();
+		core.applyNext(pending === null ? fresh : {
+			...fresh,
+			...pending
+		});
+	};
+	window.addEventListener("storage", onStorage);
+	const flush = () => {
+		const patch = pending;
+		const current = handle;
+		pending = null;
+		handle = null;
+		try {
+			const target = codec.salvage({
+				...read(),
+				...patch
+			});
+			const values = {};
+			for (const key of codec.keys) values[key] = target[key];
+			write(values);
+			core.applyNext(target);
+			current.settle();
+		} catch (error) {
+			current.fail(error);
+		}
+	};
+	const update = (patch) => {
+		const resolved = resolvePatch(patch, core.snapshot(), codec.keys, def.key);
+		if (pending === null) {
+			pending = {};
+			handle = createHandle();
+			queueMicrotask(flush);
+		}
+		Object.assign(pending, resolved);
+		const echoed = codec.salvage({
+			...core.snapshot(),
+			...pending
+		});
+		for (const key of Object.keys(pending)) pending[key] = echoed[key];
+		core.applyNext(echoed);
+		return handle.external;
+	};
+	return {
+		subscribe: core.subscribe,
+		getSnapshot: core.getSnapshot,
+		update,
+		dispose: () => {
+			window.removeEventListener("storage", onStorage);
+			core.clear();
+		}
+	};
+};
+const localStoreOf = (def) => getOrCreateStore("local", def.key, () => createStorageStore(def, localStorage));
+const sessionStoreOf = (def) => getOrCreateStore("session", def.key, () => createStorageStore(def, sessionStorage));
+/** SSR and hydration see the defaults — the server has no Web Storage. */
+const storageInitialSnapshot = (def) => ({ ...storageCodecOf(def).defaults });
+//#endregion
+export { localStoreOf, sessionStoreOf, storageInitialSnapshot };

package/dist/url/codec.d.mts

@@ -1,8 +1,8 @@
 import { StateSchema, StateValues } from "../schema/object.mjs";
 //#region src/url/codec.d.ts
 /** `URLSearchParams`, or the object shape frameworks hand to a page. */
-type UrlInput = URLSearchParams | Readonly<Record<string, string | readonly string[] | undefined>>;
-type UrlCodec = {
+export type UrlInput = URLSearchParams | Readonly<Record<string, string | readonly string[] | undefined>>;
+export type UrlCodec = {
   keys: readonly string[];
   defaults: Readonly<StateValues>;
   parse: (input: UrlInput) => StateValues;
@@ -10,6 +10,5 @@ type UrlCodec = {
   /** Runs already-typed values through the schema, salvage included. */
   salvage: (values: Readonly<StateValues>) => StateValues;
 };
-declare const createUrlCodec: (schema: StateSchema) => UrlCodec;
-//#endregion
-export { UrlCodec, UrlInput, createUrlCodec };
+export declare const createUrlCodec: (schema: StateSchema) => UrlCodec;
+//#endregion

package/dist/url/codec.mjs

@@ -1,4 +1,5 @@
 import { analyzeSchema, parseWithSalvage, sameValue } from "../schema/object.mjs";
+import { safeEncode } from "zod/v4/core";
 //#region src/url/codec.ts
 const defOf = (schema) => schema._zod.def;
 /**
@@ -17,28 +18,45 @@ const readAll = (input, key) => {
 	if (value === void 0) return [];
 	return typeof value === "string" ? [value] : value;
 };
-const serializeValue = (key, value) => {
+/**
+* 真偽値は、フィールド（配列なら要素）のスキーマ自身が encode した綴りで書く。`String(true)` の
+* `"true"` は `z.stringbool({ truthy: ['yes'] })` が読み返せず、既定値に落ちる。
+*/
+const spellBoolean = (schema, value) => {
+	try {
+		const encoded = safeEncode(schema, value);
+		if (encoded.success && typeof encoded.data === "string") return encoded.data;
+	} catch {}
+	return String(value);
+};
+const serializeValue = (schema, key, value) => {
 	if (typeof value === "string") return value;
-	if (typeof value === "number" || typeof value === "bigint" || typeof value === "boolean") return String(value);
-	throw new TypeError(`url field "${key}" holds a ${typeof value}, which has no URL serialization`);
+	if (typeof value === "boolean") return spellBoolean(schema, value);
+	if (typeof value === "number" || typeof value === "bigint") return String(value);
+	throw new TypeError(`url field "${key}" holds a value of type ${typeof value}, which has no URL serialization`);
+};
+const refuseBoolean = (schema, name) => {
+	if (baseDef(schema).type === "boolean") throw new TypeError(`url boolean fields must use z.stringbool() — a URL carries strings, and "false" is not false to z.boolean() or z.coerce.boolean(): ${name}`);
 };
 const createUrlCodec = (schema) => {
 	const info = analyzeSchema(schema, "url");
 	const { keys, defaults } = info;
-	const multi = /* @__PURE__ */ new Set();
+	const items = /* @__PURE__ */ new Map();
 	for (const key of keys) {
-		const base = baseDef(info.shape[key]).type;
-		if (base === "array") {
+		const base = baseDef(info.shape[key]);
+		if (base.type === "array") {
 			if (!sameValue(defaults[key], [])) throw new TypeError(`url array fields must default to [] — an absent param and an empty list are the same URL: ${key}`);
-			multi.add(key);
-		} else if (base === "boolean") throw new TypeError(`url boolean fields must use z.stringbool() — a URL carries strings, and "false" is not false to z.boolean() or z.coerce.boolean(): ${key}`);
+			const item = base.element;
+			refuseBoolean(item, `${key}[]`);
+			items.set(key, item);
+		} else refuseBoolean(info.shape[key], key);
 	}
 	const parse = (input) => {
 		const raw = {};
 		for (const key of keys) {
 			const got = readAll(input, key);
 			if (got.length === 0) continue;
-			raw[key] = multi.has(key) ? got : got[0];
+			raw[key] = items.has(key) ? got : got[0];
 		}
 		return parseWithSalvage(info, raw);
 	};
@@ -47,8 +65,11 @@ const createUrlCodec = (schema) => {
 		for (const key of keys) {
 			const value = key in values ? values[key] : defaults[key];
 			if (value === void 0 || sameValue(defaults[key], value)) continue;
-			if (Array.isArray(value)) for (const item of value) params.append(key, serializeValue(key, item));
-			else params.append(key, serializeValue(key, value));
+			const field = info.shape[key];
+			if (Array.isArray(value)) {
+				const item = items.get(key) ?? field;
+				for (const each of value) params.append(key, serializeValue(item, key, each));
+			} else params.append(key, serializeValue(field, key, value));
 		}
 		return params.toString();
 	};

package/dist/use-app-state.d.mts

@@ -1,13 +1,14 @@
 import { StateSchema } from "./schema/object.mjs";
+import { CookieState } from "./cookie-state.mjs";
 import { OutputOf, PageState } from "./page-state.mjs";
-import { LocalState } from "./local-state.mjs";
+import { LocalState, SessionState } from "./storage-state.mjs";
 import { MemoryState } from "./memory-state.mjs";
 import { UpdateHandle } from "./store/core.mjs";
 import { UpdateOptions } from "./store/page-store.mjs";
 import { output } from "zod/v4/core";
 //#region src/use-app-state.d.ts
-type AnyState = PageState | LocalState | MemoryState;
-type StateOf<Def> = Def extends PageState<infer Url, infer Entry> ? OutputOf<Url> & OutputOf<Entry> : Def extends LocalState<infer Schema> ? output<Schema> : Def extends MemoryState<infer Values> ? Values : never;
+export type AnyState = PageState | LocalState | SessionState | CookieState | MemoryState;
+type StateOf<Def> = Def extends PageState<infer Url, infer Entry> ? OutputOf<Url> & OutputOf<Entry> : Def extends LocalState<infer Schema> ? output<Schema> : Def extends SessionState<infer Schema> ? output<Schema> : Def extends CookieState<infer Schema> ? output<Schema> : Def extends MemoryState<infer Values> ? Values : never;
 type UrlStateOf<Def> = Def extends PageState<infer Url> ? OutputOf<Url> : never;
 type UpdateFn<Def> = (patch: Readonly<Partial<StateOf<Def>>> | ((current: StateOf<Def>) => Partial<StateOf<Def>>), ...rest: Def extends PageState ? [options?: UpdateOptions] : []) => UpdateHandle;
 type OptionsFor<Def> = Def extends {
@@ -21,8 +22,16 @@ type OptionsFor<Def> = Def extends {
    * server-side source, so it always starts from defaults there.
    */
   initialUrl?: Readonly<UrlStateOf<Def>>;
+} : Def extends CookieState<infer Schema> ? {
+  /**
+   * What `parseCookies(request.cookies)` returned on the server, passed
+   * down as a prop. It seeds SSR and the hydration render; without it
+   * those two renders see the defaults, which flashes once the cookie
+   * is read in the browser.
+   */
+  initialCookie?: Readonly<output<Schema>>;
 } : never;
-declare function useAppState<Def extends AnyState>(def: Def, options?: OptionsFor<Def>): [StateOf<Def>, UpdateFn<Def>];
-declare function useAppState<Def extends AnyState, const Key extends Extract<keyof StateOf<Def>, string>>(def: Def, keys: readonly Key[], options?: OptionsFor<Def>): [Pick<StateOf<Def>, Key>, UpdateFn<Def>];
+export declare function useAppState<Def extends AnyState>(def: Def, options?: OptionsFor<Def>): [StateOf<Def>, UpdateFn<Def>];
+export declare function useAppState<Def extends AnyState, const Key extends Extract<keyof StateOf<Def>, string>>(def: Def, keys: readonly Key[], options?: OptionsFor<Def>): [Pick<StateOf<Def>, Key>, UpdateFn<Def>];
 //#endregion
-export { AnyState, useAppState };
+export {};

package/dist/use-app-state.mjs

@@ -1,11 +1,12 @@
 "use client";
-import { localInitialSnapshot, localStoreOf } from "./store/local-store.mjs";
+import { cookieInitialSnapshot, cookieStoreOf } from "./store/cookie-store.mjs";
 import { memoryInitialSnapshot, memoryStoreOf } from "./store/memory-store.mjs";
 import { pageInitialSnapshot, pageStoreOf } from "./store/page-store.mjs";
+import { localStoreOf, sessionStoreOf, storageInitialSnapshot } from "./store/storage-store.mjs";
 import { useCallback, useMemo, useSyncExternalStore } from "react";
 //#region src/use-app-state.ts
-const storeOf = (def) => def.kind === "page" ? pageStoreOf(def) : def.kind === "local" ? localStoreOf(def) : memoryStoreOf(def);
-const initialOf = (def, initialUrl) => def.kind === "page" ? pageInitialSnapshot(def, initialUrl) : def.kind === "local" ? localInitialSnapshot(def) : memoryInitialSnapshot(def);
+const storeOf = (def) => def.kind === "page" ? pageStoreOf(def) : def.kind === "local" ? localStoreOf(def) : def.kind === "session" ? sessionStoreOf(def) : def.kind === "cookie" ? cookieStoreOf(def) : memoryStoreOf(def);
+const initialOf = (def, options) => def.kind === "page" ? pageInitialSnapshot(def, options?.initialUrl) : def.kind === "local" || def.kind === "session" ? storageInitialSnapshot(def) : def.kind === "cookie" ? cookieInitialSnapshot(def, options?.initialCookie) : memoryInitialSnapshot(def);
 const FULL = "*";
 function useAppState(def, keysOrOptions, maybeOptions) {
 	const gotKeys = Array.isArray(keysOrOptions);
@@ -19,25 +20,23 @@ function useAppState(def, keysOrOptions, maybeOptions) {
 		keys
 	]);
 	const initialUrl = options?.initialUrl;
-	const getServerSnapshot = useMemo(() => {
-		let cached;
-		return () => {
-			if (cached === void 0) {
-				const base = initialOf(def, initialUrl);
-				if (keys === null) cached = base;
-				else {
-					const pick = {};
-					for (const key of keys) pick[key] = base[key];
-					cached = pick;
-				}
-			}
-			return cached;
-		};
+	const initialCookie = options?.initialCookie;
+	const serverSnapshot = useMemo(() => {
+		const base = initialOf(def, {
+			initialUrl,
+			initialCookie
+		});
+		if (keys === null) return base;
+		const pick = {};
+		for (const key of keys) pick[key] = base[key];
+		return pick;
 	}, [
 		def,
 		initialUrl,
+		initialCookie,
 		keys
 	]);
+	const getServerSnapshot = useCallback(() => serverSnapshot, [serverSnapshot]);
 	return [useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot), useCallback((patch, updateOptions) => storeOf(def).update(patch, updateOptions), [def])];
 }
 //#endregion