@k8ordo/state 0.1.0

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

@@ -0,0 +1,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 = {
+  /**
+   * `replace` by default: an update is a refinement of the current entry.
+   * Opt into `push` for the updates the back button should undo.
+   */
+  history?: 'push' | 'replace';
+};
+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 };

package/dist/store/page-store.mjs

@@ -0,0 +1,137 @@
+import { isRecord, sameValue } from "../schema/object.mjs";
+import { internalsOf } from "../page-state.mjs";
+import { createHandle, createStoreCore, resolvePatch } from "./core.mjs";
+import { getOrCreateStore } from "./registry.mjs";
+//#region src/store/page-store.ts
+const storedEntryState = () => navigation.currentEntry?.getState();
+const readLive = (def, page) => {
+	const live = {};
+	if (page.url !== null) Object.assign(live, page.url.parse(new URL(location.href).searchParams));
+	if (page.entry !== null) {
+		const stored = storedEntryState();
+		Object.assign(live, page.entry.parse(isRecord(stored) ? stored[def.key] : void 0));
+	}
+	return live;
+};
+const createPageStore = (def) => {
+	const page = internalsOf(def);
+	const core = createStoreCore(page.keys, readLive(def, page));
+	let pending = null;
+	let pendingPush = false;
+	let handle = null;
+	const sync = () => {
+		const live = readLive(def, page);
+		core.applyNext(pending === null ? live : {
+			...live,
+			...pending
+		});
+	};
+	navigation.addEventListener("currententrychange", sync);
+	/**
+	* The whole navigation state travels with every write we make: the entry
+	* state object is shared ground (the router's own state, other page
+	* states), and a navigate that dropped it would wipe the neighbours.
+	*/
+	const canonical = (values) => ({
+		...page.url === null ? {} : page.url.salvage(values),
+		...page.entry === null ? {} : page.entry.salvage(values)
+	});
+	const carryState = (stored, target) => {
+		if (page.entry === null) return stored;
+		const base = isRecord(stored) ? { ...stored } : {};
+		const own = {};
+		for (const key of page.entry.keys) own[key] = target[key];
+		base[def.key] = own;
+		return base;
+	};
+	const flush = () => {
+		const patch = pending;
+		const push = pendingPush;
+		const current = handle;
+		pending = null;
+		pendingPush = false;
+		handle = null;
+		const url = new URL(location.href);
+		const stored = storedEntryState();
+		const liveUrl = page.url === null ? {} : page.url.parse(url.searchParams);
+		const liveEntry = page.entry === null ? {} : page.entry.parse(isRecord(stored) ? stored[def.key] : void 0);
+		const target = canonical({
+			...liveUrl,
+			...liveEntry,
+			...patch
+		});
+		const urlChanged = page.url?.keys.some((key) => !sameValue(liveUrl[key], target[key])) ?? false;
+		const entryChanged = page.entry?.keys.some((key) => !sameValue(liveEntry[key], target[key])) ?? false;
+		if (!urlChanged && !entryChanged) {
+			core.applyNext(target);
+			current.settle();
+			return;
+		}
+		const state = carryState(stored, target);
+		if (!urlChanged) {
+			try {
+				navigation.updateCurrentEntry({ state });
+				current.settle();
+			} catch (error) {
+				current.fail(error);
+			}
+			return;
+		}
+		if (page.url !== null) {
+			for (const key of page.url.keys) url.searchParams.delete(key);
+			for (const [key, value] of new URLSearchParams(page.url.search(target))) url.searchParams.append(key, value);
+		}
+		try {
+			current.adopt(navigation.navigate(url.href, {
+				history: push ? "push" : "replace",
+				state
+			}));
+		} catch (error) {
+			current.fail(error);
+		}
+	};
+	const update = (patch, options) => {
+		const resolved = resolvePatch(patch, core.snapshot(), page.keys, def.key);
+		if (pending === null) {
+			pending = {};
+			handle = createHandle();
+			queueMicrotask(flush);
+		}
+		Object.assign(pending, resolved);
+		if (options?.history === "push") pendingPush = true;
+		const echoed = canonical({
+			...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: () => {
+			navigation.removeEventListener("currententrychange", sync);
+			core.clear();
+		}
+	};
+};
+const pageStoreOf = (def) => getOrCreateStore("page", def.key, () => createPageStore(def));
+/**
+* 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.
+*/
+const pageInitialSnapshot = (def, initialUrl) => {
+	const page = internalsOf(def);
+	const base = {};
+	for (const codec of [page.url, page.entry]) if (codec !== null) for (const key of codec.keys) base[key] = codec.defaults[key];
+	if (page.url !== null && initialUrl !== void 0) {
+		for (const key of page.url.keys) if (key in initialUrl) base[key] = initialUrl[key];
+	}
+	return base;
+};
+//#endregion
+export { pageInitialSnapshot, pageStoreOf };

package/dist/store/registry.d.mts

@@ -0,0 +1,12 @@
+//#region src/store/registry.d.ts
+declare const getOrCreateStore: <Store extends {
+  dispose?: () => void;
+}>(scope: string, key: string, create: () => Store) => Store;
+/**
+ * Test-only escape hatch for the provider-less design: without it, stores
+ * 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 };

package/dist/url/codec.d.mts

@@ -0,0 +1,15 @@
+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 = {
+  keys: readonly string[];
+  defaults: Readonly<StateValues>;
+  parse: (input: UrlInput) => StateValues;
+  search: (values: Readonly<Partial<StateValues>>) => string;
+  /** 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 };

package/dist/url/codec.mjs

@@ -0,0 +1,62 @@
+import { analyzeSchema, parseWithSalvage, sameValue } from "../schema/object.mjs";
+//#region src/url/codec.ts
+const defOf = (schema) => schema._zod.def;
+/**
+* Peels wrappers (`default`, `optional`, `catch`, …) and pipes down to the
+* type that decides how many values a param carries. Only the input side of a
+* pipe matters here — that is the side the URL string enters through.
+*/
+const baseDef = (schema) => {
+	let def = defOf(schema);
+	while (def.innerType !== void 0 || def.type === "pipe" && def.in !== void 0) def = defOf(def.innerType ?? def.in);
+	return def;
+};
+const readAll = (input, key) => {
+	if (input instanceof URLSearchParams) return input.getAll(key);
+	const value = input[key];
+	if (value === void 0) return [];
+	return typeof value === "string" ? [value] : value;
+};
+const serializeValue = (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`);
+};
+const createUrlCodec = (schema) => {
+	const info = analyzeSchema(schema, "url");
+	const { keys, defaults } = info;
+	const multi = new Set(keys.filter((key) => baseDef(info.shape[key]).type === "array"));
+	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];
+		}
+		return parseWithSalvage(info, raw);
+	};
+	const search = (values) => {
+		const params = new URLSearchParams();
+		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));
+		}
+		return params.toString();
+	};
+	const salvage = (values) => {
+		const own = {};
+		for (const key of keys) if (key in values) own[key] = values[key];
+		return parseWithSalvage(info, own);
+	};
+	return {
+		keys,
+		defaults,
+		parse,
+		search,
+		salvage
+	};
+};
+//#endregion
+export { createUrlCodec };

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

@@ -0,0 +1,24 @@
+import { OutputOf, PageState } from "./page-state.mjs";
+import { LocalState } from "./local-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;
+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 PageState ? {
+  /**
+   * The RSC-parsed url state, passed down as a prop. It seeds SSR and
+   * the hydration render; without it those two renders see the defaults,
+   * which flashes once the live URL takes over. The entry slot has no
+   * server-side source, so it always starts from defaults there.
+   */
+  initialUrl?: Readonly<UrlStateOf<Def>>;
+} : Record<never, 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>];
+//#endregion
+export { AnyState, useAppState };

package/dist/use-app-state.mjs

@@ -0,0 +1,44 @@
+"use client";
+import { localInitialSnapshot, localStoreOf } from "./store/local-store.mjs";
+import { memoryInitialSnapshot, memoryStoreOf } from "./store/memory-store.mjs";
+import { pageInitialSnapshot, pageStoreOf } from "./store/page-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 FULL = "*";
+function useAppState(def, keysOrOptions, maybeOptions) {
+	const gotKeys = Array.isArray(keysOrOptions);
+	const options = gotKeys ? maybeOptions : keysOrOptions;
+	const sig = gotKeys ? JSON.stringify(keysOrOptions.toSorted()) : FULL;
+	const keys = useMemo(() => sig === FULL ? null : JSON.parse(sig), [sig]);
+	const subscribe = useCallback((notify) => storeOf(def).subscribe(keys, notify), [def, keys]);
+	const getSnapshot = useCallback(() => storeOf(def).getSnapshot(sig, keys), [
+		def,
+		sig,
+		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;
+		};
+	}, [
+		def,
+		initialUrl,
+		keys
+	]);
+	return [useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot), useCallback((patch, updateOptions) => storeOf(def).update(patch, updateOptions), [def])];
+}
+//#endregion
+export { useAppState };

package/docs/GUIDE.md

@@ -0,0 +1,308 @@
+# @k8ordo/state
+
+Declare state by where it lives. A definition names a place — the URL, the
+history entry, localStorage, memory — and one zod schema per place derives
+everything else: the server-side read, canonical link building, salvage of
+stale data, and a client subscription with exact per-key change detection.
+
+Like every k8ordo package it assumes React 19 and Server Components, uses only
+what has reached Baseline newly available, and ships no polyfills or legacy
+fallbacks. The Navigation API reached Baseline in January 2026; this package
+treats it as simply present.
+
+## The four places
+
+| definition                  | lives in            | survives              | shared with           | server |
+| --------------------------- | ------------------- | --------------------- | --------------------- | ------ |
+| `definePageState` — `url`   | searchParams        | back/forward, sharing | anyone given the URL  | reads  |
+| `definePageState` — `entry` | history entry state | back/forward, reload  | that tab's entry      | —      |
+| `defineLocalState`          | localStorage        | until deleted         | every tab, one device | —      |
+| `defineMemoryState`         | the JS runtime      | until reload          | that tab              | —      |
+
+`url` and `entry` are the two faces of one history entry — one visible and
+shareable, one hidden — which is why they share a definition and update
+atomically. localStorage and memory are app-scope, not page-scope, which is
+why they are their own kinds: the grouping difference is real, so the API
+makes it visible.
+
+```ts
+import {
+  defineLocalState,
+  defineMemoryState,
+  definePageState,
+} from '@k8ordo/state';
+import * as z from 'zod/mini';
+
+// Page state: colocate with the feature that owns it.
+export const listState = definePageState('product-list', {
+  url: z.object({
+    q: z._default(z.string(), ''),
+    page: z._default(z.coerce.number().check(z.int(), z.gte(1)), 1),
+  }),
+  entry: z.object({
+    expanded: z._default(z.array(z.string()), []),
+  }),
+});
+
+// App state: lives in a shared module.
+export const prefs = defineLocalState(
+  'prefs',
+  z.object({ view: z._default(z.enum(['grid', 'table']), 'grid') }),
+);
+
+// A typed shared box. No schema: these values never cross a boundary,
+// so there is nothing to re-validate — the typed update is the only writer.
+// Treat the values as immutable: replace fields through update(); a nested
+// reference mutated in place bypasses change detection.
+export const debugPanel = defineMemoryState('debug-panel', { open: false });
+```
+
+Schemas appear exactly where data comes back across a boundary — URL strings
+a user can edit, localStorage JSON an older schema wrote, entry state a
+session restore revived — and every such field must tolerate absence:
+`.default()` (`z._default()` in mini) or `.optional()`. Definitions throw at
+module load naming the fields that do not. The first argument is the state's
+identity: the localStorage key (`k8ordo-state:<key>`), the entry-state
+namespace, and the store-registry slot. Renaming it renames the data — and
+the key must be app-unique per kind: two definitions of the same kind sharing
+a key silently share one store (and, for local, one storage row). The module
+system cannot enforce this, so treat the key like a global name.
+
+## zod, or zod/mini
+
+Parsing runs on zod's shared core, so a schema written with either entry
+works. Unlike `@k8ordo/form` — where the schema stays on the server — the
+client here parses and serializes with the schema itself, so the schema module
+ships to the browser. Reach for `zod/mini` (10 kB gzipped vs 63 kB) unless the
+app already pays for classic `zod` elsewhere.
+
+## The shape of it
+
+```
+shared    definePageState / defineLocalState / defineMemoryState     no 'use client'
+            ↓ import                              ↓ import
+server    listState.parseUrl(searchParams)     client    useAppState(def, ['q', 'page'])
+          listState.href('/products', {...})             → [state, update]
+          RSC, Server Action
+```
+
+A definition is pure data — schemas and pure functions. No store lives inside
+it, so a Server Component imports it without creating server-side mutable
+state. The live store exists only in the browser, created lazily by the first
+`useAppState`, keyed by the definition's string key (which is what lets state
+survive HMR re-evaluation of the definition module). There is no Provider:
+the stores mirror browser-wide singletons — the URL, the history entry,
+localStorage — so there is nothing to scope.
+
+## Server — read, and build links
+
+```tsx
+export default async function Page({ searchParams }: PageProps<'/products'>) {
+  const url = listState.parseUrl(await searchParams);
+  //    ^ { q: string; page: number } — typed, defaults applied
+
+  const products = await fetchProducts(url);
+  return (
+    <>
+      <Filters initialUrl={url} />
+      <ProductList products={products} />
+      <Link href={listState.href('/products', { ...url, page: url.page + 1 })}>
+        next
+      </Link>
+    </>
+  );
+}
+```
+
+`href` and `search` are pure: unspecified fields mean their default, and
+default values are omitted from the query, so every link is canonical and as
+short as it can be. `search` returns the query string alone (no `?`) when the
+path should stay in the caller's hands. Only the url slot exists on the
+server; entry, local and memory state render as their defaults there.
+
+## Client — subscribe and update
+
+```tsx
+'use client';
+import { useAppState } from '@k8ordo/state';
+import { listState, prefs } from './state';
+
+export function Filters({ initialUrl }: FiltersProps) {
+  const [{ q, page, expanded }, update] = useAppState(listState, {
+    initialUrl,
+  });
+  const [{ view }, updatePrefs] = useAppState(prefs, ['view']);
+
+  return (
+    <>
+      <p>{q === '' ? 'all products' : `searching “${q}”`}</p>
+      <button
+        type="button"
+        onClick={() => update({ page: page + 1 }, { history: 'push' })}
+      >
+        next page
+      </button>
+      <button type="button" onClick={() => updatePrefs({ view: 'table' })}>
+        table view
+      </button>
+    </>
+  );
+}
+```
+
+The hook is the same for every kind. State is the flat merge of a page
+definition's two slots — moving a field between `url` and `entry` is a
+one-line change in the definition and no change at the call sites.
+
+## Updates
+
+`update()` applies synchronously — the next render sees the new value — and
+returns the Navigation API's own shape, an object holding two promises:
+
+```ts
+const { committed, finished } = update({ page: 2 });
+// committed: the write is in its home
+// finished:  the router's intercept work (fetch, render) is done
+```
+
+Ignoring the handle is the normal case and trips no floating-promise lint.
+Awaiting `finished` composes with React 19 async transitions:
+
+```tsx
+const [isPending, startTransition] = useTransition();
+startTransition(async () => {
+  await update({ page: 2 }).finished;
+});
+```
+
+A superseded navigation (the user clicked again) rejects the handle with an
+`AbortError`; unawaited calls never surface it. Updates with no navigation
+behind them — entry-only, local, memory — return the same shape, settled.
+
+- **Patches are validated on the spot.** The merged state passes the schema
+  inside `update()` itself, with the same salvage as a URL arrival:
+  `update({ page: 0 })` on a `min(1)` field lands on the default exactly as
+  `?page=0` would, and the echo never shows a value the schema rejects.
+- **Routing is by field.** One patch may span both faces of a page state:
+  url + entry changes travel in a single `navigation.navigate()`, atomically.
+  A patch touching only entry fields uses `updateCurrentEntry()` — no
+  navigation, works under any router.
+- **`replace` by default.** An update refines the current entry. Pass
+  `{ history: 'push' }` only for updates the back button should undo — the
+  option exists only on page state, the one kind with a navigation behind it.
+- **One handler, one write.** Several `update()` calls in the same event
+  handler collapse into a single navigation (or storage write); they share
+  one handle. A batch that ends where it started does not write at all.
+- **Functional form.** `update((current) => ({ page: current.page + 1 }))`
+  reads the batched state, not the committed one.
+- **Shared ground stays shared.** A page state rewrites only its own params
+  in the URL and only its own namespace in the entry state; params and state
+  owned by other definitions — or by nobody — survive every write.
+
+## Subscription granularity
+
+The schema fixes the key set, so change detection is exact, per key:
+
+```tsx
+useAppState(listState); // any declared field re-renders this
+useAppState(listState, ['q']); // only q changes re-render this
+useAppState(listState, []); // write-only: subscribe to nothing
+```
+
+A `page` change never re-renders a `['q']` subscriber. Inline key arrays are
+normalized internally — no `useMemo` at the call site. When two pieces of
+state update at very different rates, give them separate definitions; the
+definition is the subscription boundary.
+
+## Routers
+
+Everything except one operation works under any router:
+
+| operation                          | needs                                       |
+| ---------------------------------- | ------------------------------------------- |
+| `parseUrl` on the server           | nothing                                     |
+| `href` / `search` links, GET forms | nothing — the router handles the click      |
+| entry / local / memory updates     | nothing — no navigation is involved         |
+| url `update()` on the client       | a router that intercepts the Navigation API |
+
+A url `update()` calls `navigation.navigate()`. On a router that intercepts
+the `navigate` event, that is a same-document update flowing through the
+router's own pipeline — transitions, scroll handling and all. On a router
+that does not (Next.js today), it is a full document load: use links and GET
+forms for url changes there, which is this package's preferred grain anyway.
+There is deliberately no history-API fallback.
+
+Keystrokes do not belong in the URL. Let the DOM or local React state hold
+the draft and call `update()` at commit points — submit, blur, pagination —
+the same division `@k8ordo/form` draws.
+
+## Typed routes
+
+`href` keeps the path literal alive in the type
+(``'/products' | `/products?${string}` ``), which is what typed-route checks
+strip a query from and verify. To constrain paths app-wide, augment `Register`
+once:
+
+```ts
+// e.g. types/k8ordo-state.d.ts
+import type { Route } from 'next';
+
+declare module '@k8ordo/state' {
+  interface Register {
+    path: Route;
+  }
+}
+```
+
+Every `href` in the app now rejects a path its router does not know. Without
+the augmentation the constraint is any `/`-prefixed string. Augment only in an
+application — a shared library augmenting `Register` leaks the constraint to
+every consumer.
+
+## What it guarantees
+
+**Boundary data is input, not trusted state.** A URL param a user edited, a
+localStorage row an older schema wrote, a restored entry state — anything the
+schema rejects falls back to that field's own default, field by field, and a
+combination an object-level `refine` forbids falls back to the defaults as a
+whole. One broken value never takes the rest down, and nothing throws at read
+time. An array field collects repeated params; a repeated param on a scalar
+field takes the first value.
+
+**Canonical URLs.** Serialization omits every field sitting at its default, so
+the same state always produces the same, shortest URL — links, bookmarks and
+caches agree.
+
+**Back means back.** Both faces of a page state live on the history entry via
+the platform, not in a parallel store, so back/forward restore them together
+with no library bookkeeping.
+
+**Tabs agree.** localStorage state propagates across tabs through the
+`storage` event; the same keyed subscription granularity applies.
+
+**SSR sees real url values when you hand them over.** Pass the RSC-parsed url
+as `initialUrl` and the server render and hydration render show the actual
+URL state. Everything else — entry, local, memory — renders its defaults on
+the server by construction: those places do not exist there.
+
+## GET forms with @k8ordo/form
+
+A search or filter form is a GET form, and its constraints and its URL state
+are the same schema:
+
+```tsx
+import { formFields } from '@k8ordo/form/server';
+
+const filterFields = formFields(listState.url); // one schema, both jobs
+```
+
+The form submits as GET, the RSC reads it back with `parseUrl`, and the whole
+loop works before JavaScript loads.
+
+## Testing
+
+`resetStateRegistry()` clears the provider-less store registry between tests.
+Unmount components first — mounted hooks keep their store through closures.
+When testing url updates, intercept the `navigate` event in the test itself
+(as a router would); an unintercepted `navigation.navigate()` is a
+cross-document load.

package/docs/llms.txt

@@ -0,0 +1,42 @@
+# @k8ordo/state
+
+> Declare state by where it lives: `definePageState` (typed URL search params
+> plus hidden history-entry state — the two faces of one entry, updated
+> atomically over the Navigation API), `defineLocalState` (localStorage,
+> cross-tab), `defineMemoryState` (a typed shared box, resets on reload).
+> One zod schema per place derives the server read, canonical links, salvage
+> of stale data, and a client subscription with exact per-key change
+> detection. Works through links and GET forms before JavaScript loads;
+> imperative url updates ride a Navigation-API-intercepting router.
+>
+> Like every k8ordo package it assumes React 19 and Server Components, uses
+> only what has reached Baseline newly available, and ships no polyfills or
+> legacy fallbacks.
+
+When installed via npm, these docs live under `node_modules/@k8ordo/state/docs/`.
+
+## Guide
+
+- [Design Guide](GUIDE.md): the four places and when each fits, the shared
+  definition module, reading on the server, updating on the client, batching
+  and update handles, subscription granularity, router requirements, typed
+  routes via `Register`, and pairing with `@k8ordo/form` for GET forms.
+
+## Entry point
+
+- `@k8ordo/state` — `definePageState(key, { url?, entry? })` returns a pure
+  definition usable from server and client: `parseUrl(searchParams)` reads
+  the url slot typed with defaults applied and per-field salvage;
+  `href(base, values?)` builds a canonical link keeping the path literal in
+  the type; `search(values?)` returns the query string alone.
+  `defineLocalState(key, schema)` and `defineMemoryState(key, initial)`
+  declare app-scope state. `useAppState(definition, keys?, { initialUrl? })`
+  (client) works on any kind and returns `[state, update]` — state is the
+  flat merge of a page definition's slots; `update(patch)` applies
+  synchronously, batches per handler into one write (url+entry atomically via
+  `navigation.navigate()`, entry-only via `updateCurrentEntry()`, local via
+  one `setItem`), and returns `{ committed, finished }` promise handles
+  (settled for non-navigating kinds; `{ history: 'push' }` exists only on
+  page state). `resetStateRegistry()` clears stores between tests. Augment
+  `interface Register { path }` to constrain `href` paths to the app's typed
+  routes.