@k8ordo/state 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,143 @@
+# @k8ordo/state
+
+Declare state by where it lives — URL search params, hidden history-entry
+state, localStorage, or memory. One zod schema per place derives the
+server-side read, canonical links, salvage of stale data, and a client
+subscription with exact per-key change detection. Links and GET forms work
+before JavaScript loads; imperative URL updates ride the Navigation API.
+
+Like every [k8ordo](https://ordo.k8o.me) package it assumes React 19 and Server
+Components, uses only what has reached Baseline newly available, and ships no
+polyfills or legacy fallbacks.
+
+- **Documentation**: https://ordo.k8o.me/state
+- **Design guide**: [docs/GUIDE.md](docs/GUIDE.md) — shipped inside this package
+
+## Installation
+
+```bash
+npm install @k8ordo/state zod
+# or
+pnpm add @k8ordo/state zod
+```
+
+## Peer Dependencies
+
+| Package          | Version  | Needed for                                               |
+| ---------------- | -------- | -------------------------------------------------------- |
+| `react`          | ≥19.2.6  | `useAppState`                                            |
+| `zod`            | ^4.4.3   | the schemas (`zod/mini` works, and is the lighter pick)  |
+| `@k8ordo/router` | ^0.1.0   | optional — typed `href` paths from the app's route table |
+| `typescript`     | ≥7.0.2   | the shipped type declarations                            |
+| `@types/react`   | ≥19.2.18 | the shipped type declarations                            |
+
+The schema ships to the browser here — the client parses and serializes with
+it — so reach for `zod/mini` unless the app already pays for classic `zod`.
+`@k8ordo/router` is a type-only peer: it is never loaded at runtime.
+
+## Quick Start
+
+One definition per place, in a shared module with no `'use client'`:
+
+```ts
+// state.ts
+import { defineLocalState, definePageState } from '@k8ordo/state';
+import * as z from 'zod/mini';
+
+export const listState = definePageState('list', {
+  url: z.object({
+    q: z._default(z.string(), ''),
+    page: z._default(z.coerce.number(), 1),
+  }),
+});
+
+export const prefs = defineLocalState(
+  'prefs',
+  z.object({ view: z._default(z.enum(['grid', 'table']), 'grid') }),
+);
+```
+
+```tsx
+// page.tsx — Server Component
+import { listState } from './state';
+
+export default async function Page({ searchParams }: PageProps<'/products'>) {
+  const url = listState.parseUrl(await searchParams); // typed, defaults applied
+  const products = await fetchProducts(url);
+  return (
+    <>
+      <Filters initialUrl={url} />
+      <ProductList products={products} />
+      <a href={listState.href('/products', { ...url, page: url.page + 1 })}>
+        next
+      </a>
+    </>
+  );
+}
+```
+
+```tsx
+// filters.tsx
+'use client';
+import { useAppState } from '@k8ordo/state';
+import { listState, prefs } from './state';
+
+export function Filters({ initialUrl }: FiltersProps) {
+  const [{ q, page }, 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 })}>
+        next page
+      </button>
+      <button type="button" onClick={() => updatePrefs({ view: 'table' })}>
+        table view
+      </button>
+    </>
+  );
+}
+```
+
+`update()` applies synchronously, batches per handler into one write, and
+returns `{ committed, finished }` handles. `href` omits every field at its
+default, so every link is canonical. A value the schema rejects — a URL a
+user edited, a row an older schema wrote — falls back to its own default,
+field by field.
+
+The [design guide](docs/GUIDE.md) covers the rest: the four places and when
+each fits, history-entry state, batching and update handles, subscription
+granularity, router requirements, typed routes via `Register`, reading local
+state before hydration with `inlineRead()`, and GET forms with `@k8ordo/form`.
+
+## AI Agent Documentation
+
+The docs ship **inside the package**, so an agent always reads the exact
+version you installed — there is no snapshot to copy or re-sync on upgrade.
+
+Point your agent at them once by pasting this into your project's `CLAUDE.md` /
+`AGENTS.md`:
+
+```markdown
+Use `@k8ordo/state` for URL, history-entry, localStorage and shared memory
+state. Before adding or changing state, read
+`node_modules/@k8ordo/state/docs/GUIDE.md`. Declare each state by where it
+lives (`definePageState` / `defineLocalState` / `defineMemoryState`) in a
+shared module, read the url slot on the server with `parseUrl`, build links
+with `href`, and subscribe on the client with `useAppState`. Every boundary
+field needs a default or `.optional()`; never mirror a definition's values
+into React state.
+```
+
+What each surface gives an agent:
+
+| Surface                    | Where                                          |
+| -------------------------- | ---------------------------------------------- |
+| Design guide (entry point) | `node_modules/@k8ordo/state/docs/GUIDE.md`     |
+| Docs index for LLMs        | `docs/llms.txt` · https://ordo.k8o.me/llms.txt |
+| Markdown twin on the web   | https://ordo.k8o.me/state/docs/GUIDE.md        |
+
+## License
+
+MIT License - see [LICENSE](https://github.com/k35o/k8ordo/blob/main/LICENSE) for details.

package/dist/local-state.d.mts

@@ -12,6 +12,16 @@ type LocalState<Schema extends StateSchema = StateSchema> = {
   key: string;
   /** The schema as passed. */
   schema: Schema;
+  /** The localStorage 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, or storage cannot be read. The
+   * schema does not run there: treat the result as untrusted and read only
+   * the fields you need, each with its own fallback.
+   */
+  inlineRead: () => string;
 };
 declare const localCodecOf: (def: LocalState) => StoredCodec;
 declare const defineLocalState: <Schema extends StateSchema>(key: string, schema: Schema) => LocalState<Schema>;

package/dist/local-state.mjs

@@ -1,5 +1,13 @@
 import { createStoredCodec } from "./entry/codec.mjs";
 //#region src/local-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 inlineReadOf = (storageKey) => `(()=>{try{const v=JSON.parse(localStorage.getItem(${literalOf(storageKey)}));return v!==null&&typeof v==="object"&&!Array.isArray(v)?v:null}catch{return null}})()`;
 const codecs = /* @__PURE__ */ new WeakMap();
 const localCodecOf = (def) => {
 	const codec = codecs.get(def);
@@ -7,10 +15,13 @@ const localCodecOf = (def) => {
 	return codec;
 };
 const defineLocalState = (key, schema) => {
+	const storageKey = `${STORAGE_KEY_PREFIX}${key}`;
 	const def = {
 		kind: "local",
 		key,
-		schema
+		schema,
+		storageKey,
+		inlineRead: () => inlineReadOf(storageKey)
 	};
 	codecs.set(def, createStoredCodec(schema, "local"));
 	return def;

package/dist/register.d.mts

@@ -1,22 +1,36 @@
+import { RouteOf } from "@k8ordo/router";
 //#region src/register.d.ts
 /**
- * The app-side hook for typed route paths. An application augments this once:
+ * The app-side hook for typed route paths. An application augments this once,
+ * with the same line its `@k8ordo/router` augmentation uses:
  *
  * ```ts
- * import type { Route } from 'next';
+ * import type { routes } from './routes';
  * declare module '@k8ordo/state' {
- *   interface Register { path: Route }
+ *   interface Register { routes: typeof routes }
  * }
  * ```
  *
- * and every `href()` in the app is constrained to its router's route type.
+ * and every `href()` in the app is constrained to the table's linkable paths.
+ * A router that is not `@k8ordo/router` registers its path union directly —
+ * `interface Register { path: Route }` with `Route` from `next` — which is
+ * also what the framework's generator emitted before `routes` existed.
  * Declared as an interface — the one exception to the repository's type-only
  * rule — because declaration merging is the entire mechanism.
  */
 interface Register {}
-/** `href()`'s path constraint: the registered route type, or any `/`-path. */
-type RegisteredPath = Register extends {
+/**
+ * The path union a `Register` shape yields: the table's linkable paths when
+ * it carries `routes`, the union as given when it carries `path`, and any
+ * `/`-path when it carries neither. `RouteOf` is imported as a type only, so
+ * `@k8ordo/router` is never loaded at runtime and stays an optional peer.
+ */
+type PathFrom<R> = R extends {
+  routes: infer Routes;
+} ? RouteOf<Routes> : R extends {
   path: infer P extends string;
 } ? P : `/${string}`;
+/** `href()`'s path constraint: the registered route type, or any `/`-path. */
+type RegisteredPath = PathFrom<Register>;
 //#endregion
-export { Register, RegisteredPath };
+export { PathFrom, Register, RegisteredPath };

package/dist/store/local-store.mjs

@@ -2,10 +2,9 @@ import { localCodecOf } from "../local-state.mjs";
 import { createHandle, createStoreCore, resolvePatch } from "./core.mjs";
 import { getOrCreateStore } from "./registry.mjs";
 //#region src/store/local-store.ts
-const storageKeyOf = (def) => `k8ordo-state:${def.key}`;
 const createLocalStore = (def) => {
 	const codec = localCodecOf(def);
-	const storageKey = storageKeyOf(def);
+	const { storageKey } = def;
 	const read = () => {
 		const text = localStorage.getItem(storageKey);
 		if (text === null) return codec.parse(void 0);

package/dist/store/page-store.mjs

@@ -51,37 +51,33 @@ const createPageStore = (def) => {
 		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 {
+		try {
+			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) {
 				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);
 			}
-			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
@@ -92,6 +88,11 @@ const createPageStore = (def) => {
 	};
 	const update = (patch, options) => {
 		const resolved = resolvePatch(patch, core.snapshot(), page.keys, def.key);
+		const echoed = canonical({
+			...core.snapshot(),
+			...pending,
+			...resolved
+		});
 		if (pending === null) {
 			pending = {};
 			handle = createHandle();
@@ -99,10 +100,6 @@ const createPageStore = (def) => {
 		}
 		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;

package/dist/url/codec.mjs

@@ -25,7 +25,14 @@ const serializeValue = (key, value) => {
 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 multi = /* @__PURE__ */ new Set();
+	for (const key of keys) {
+		const base = baseDef(info.shape[key]).type;
+		if (base === "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 parse = (input) => {
 		const raw = {};
 		for (const key of keys) {
@@ -45,11 +52,16 @@ const createUrlCodec = (schema) => {
 		}
 		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);
-	};
+	/**
+	* The values as they will come back: written to a query string and read
+	* again. Going through the URL rather than handing the typed values
+	* straight to the schema is what makes a one-way spelling work — the
+	* `string → boolean` of `z.stringbool()` never sees a boolean, exactly as
+	* on arrival — and it is the only reading under which `update()` and a
+	* visitor's URL are the same path. A value with no URL spelling throws
+	* here, which is the earliest anyone can be told.
+	*/
+	const salvage = (values) => parse(new URLSearchParams(search(values)));
 	return {
 		keys,
 		defaults,

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

@@ -1,3 +1,4 @@
+import { StateSchema } from "./schema/object.mjs";
 import { OutputOf, PageState } from "./page-state.mjs";
 import { LocalState } from "./local-state.mjs";
 import { MemoryState } from "./memory-state.mjs";
@@ -9,7 +10,10 @@ 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 ? {
+type OptionsFor<Def> = Def extends {
+  kind: 'page';
+  url: StateSchema;
+} ? {
   /**
    * 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,
@@ -17,7 +21,7 @@ type OptionsFor<Def> = Def extends PageState ? {
    * server-side source, so it always starts from defaults there.
    */
   initialUrl?: Readonly<UrlStateOf<Def>>;
-} : Record<never, 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

package/docs/GUIDE.md

@@ -62,12 +62,30 @@ 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
+identity: the localStorage key (`k8ordo-state:<key>`, exposed as the
+definition's `storageKey`), 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.
 
+**A boundary schema must also accept what it produces.** `update()` re-reads
+its own values by the road they will come back on, so a field whose input and
+output sides disagree lands on its default instead of the value you wrote. For
+url that road is the query string, which is why two spellings are refused at
+module load rather than at the first click:
+
+| written                                       | use instead      |
+| --------------------------------------------- | ---------------- |
+| `z.boolean()` / `z.coerce.boolean()` in `url` | `z.stringbool()` |
+| a `url` array defaulting to anything but `[]` | `.default([])`   |
+
+A URL carries strings, and `"false"` is not `false` to a boolean schema; an
+absent param and an empty list are the same URL, so an array whose default is
+non-empty could never write `[]`. The same rule holds for values a URL cannot
+spell at all: a `z.date()` url field is refused the moment something writes
+one, naming the field.
+
 ## zod, or zod/mini
 
 Parsing runs on zod's shared core, so a schema written with either entry
@@ -96,6 +114,9 @@ localStorage — so there is nothing to scope.
 
 ## Server — read, and build links
 
+`parseUrl` reads the url slot wherever a router hands a page its search — for
+example Next.js:
+
 ```tsx
 export default async function Page({ searchParams }: PageProps<'/products'>) {
   const url = listState.parseUrl(await searchParams);
@@ -106,19 +127,28 @@ export default async function Page({ searchParams }: PageProps<'/products'>) {
     <>
       <Filters initialUrl={url} />
       <ProductList products={products} />
-      <Link href={listState.href('/products', { ...url, page: url.page + 1 })}>
+      <a href={listState.href('/products', { ...url, page: url.page + 1 })}>
         next
-      </Link>
+      </a>
     </>
   );
 }
 ```
 
+**Under `@k8ordo/static` and `@k8ordo/server` a page never sees the search.**
+Those pages receive `params` and `pathname` — the pathname axis is the
+router's, and the search is read in the browser by `useAppState`. The server
+render therefore shows the url slot's defaults and the live URL takes over one
+render after hydration. That is not a gap to route around: the router
+intercepts a same-pathname navigation without loading anything, so a server
+render keyed on the search would be right on the first load and stale after
+the first `update()`. Building links is unaffected — `href` and `search` are
+pure and run anywhere, including in a Server Component.
+
 `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.
+path should stay in the caller's hands.
 
 ## Client — subscribe and update
 
@@ -162,7 +192,7 @@ 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
+// finished:  whatever the router did after the write is done
 ```
 
 Ignoring the handle is the normal case and trips no floating-promise lint.
@@ -179,10 +209,12 @@ 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:
+- **Patches are validated on the spot.** The merged state goes through the
+  schema inside `update()` itself, by the road a URL arrival takes:
   `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.
+  `?page=0` would, and the echo never shows a value the schema rejects. A
+  value the URL cannot carry is refused there and then, before anything is
+  written — the call throws rather than rejecting a handle nobody awaits.
 - **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
@@ -220,15 +252,19 @@ 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
+| `parseUrl` on the server           | a router that hands the page its search     |
+
+A url `update()` calls `navigation.navigate()`. Under `@k8ordo/router` —
+including a page rendered by `@k8ordo/static` or `@k8ordo/server` — a
+navigation that keeps the pathname is a state change and not a page change:
+the router intercepts it without a load, nothing remounts, and scroll and
+focus stay where they are. `finished` therefore resolves once that navigation
+settles, with no fetch or render behind it, since `update()` already rendered
+the new values. On a router that does not intercept the Navigation API
+(Next.js today), the same call 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.
 
@@ -241,7 +277,34 @@ the same division `@k8ordo/form` draws.
 `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:
+once, with the same line the `@k8ordo/router` augmentation takes:
+
+```ts
+// e.g. types/k8ordo.d.ts
+import type { routes } from '../routes';
+
+declare module '@k8ordo/router' {
+  interface Register {
+    routes: typeof routes;
+  }
+}
+
+declare module '@k8ordo/state' {
+  interface Register {
+    routes: typeof routes;
+  }
+}
+```
+
+`href` then accepts exactly the table's linkable paths — a `:param` becomes
+`${string}`, a `*` wildcard is matched but never linked — derived through
+`RouteOf` from `@k8ordo/router` as a type only, so the router stays an
+optional peer and never loads at runtime. Under `@k8ordo/static` or
+`@k8ordo/server` this is generated for you into `.k8ordo/` from `routes/`,
+and hand-writing it is a mistake.
+
+A router that is not `@k8ordo/router` has no table to hand over; register its
+path union directly under `path` — `Route` from `next`, for instance:
 
 ```ts
 // e.g. types/k8ordo-state.d.ts
@@ -254,10 +317,34 @@ declare module '@k8ordo/state' {
 }
 ```
 
-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.
+When both are present, `routes` wins. 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.
+
+## Reading before hydration
+
+Some state has to be applied before the first paint: a theme class on
+`<html>`, say, or a colour scheme the browser must not flash the default of.
+`useAppState` runs after hydration, which is too late for that, and the
+alternative — an inline script with the storage key and the JSON envelope
+hard-coded in a string — drifts the moment either changes.
+
+A local definition carries both halves: `storageKey` is the key the store
+writes under, and `inlineRead()` returns 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,
+or storage cannot be read. The key is escaped for a script context, so any
+key is safe to emit.
+
+```tsx
+<script>{`const s = ${themeState.inlineRead()}; if (s && s.mode === 'dark') document.documentElement.classList.add('dark');`}</script>
+```
+
+The schema does not run there — no module has loaded yet — so what comes back
+is the raw row, not the salvaged state `useAppState` will show. Treat it as
+untrusted: read only the fields you need, each with its own fallback, and let
+the hydrated store be the source of truth from then on.
 
 ## What it guarantees
 
@@ -280,10 +367,12 @@ 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.
+**SSR sees real url values when your router hands you the search.** Pass the
+RSC-parsed url as `initialUrl` and the server render and the hydration render
+show the actual URL state. Where a page receives no search — `@k8ordo/static`
+and `@k8ordo/server` — the url slot renders its defaults and the live URL
+takes over on hydration. Everything else — entry, local, memory — renders its
+defaults on the server by construction: those places do not exist there.
 
 ## GET forms with @k8ordo/form
 

package/docs/llms.txt

@@ -20,17 +20,25 @@ When installed via npm, these docs live under `node_modules/@k8ordo/state/docs/`
 - [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.
+  routes via `Register`, reading local state before hydration, 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;
+  the url slot typed with defaults applied and per-field salvage (wherever the
+  router hands a page its search — under `@k8ordo/static` / `@k8ordo/server` a
+  page receives `params` and `pathname` only, and the url slot is read in the
+  browser);
   `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? })`
+  declare app-scope state; a local definition also exposes `storageKey` (the
+  localStorage key, `k8ordo-state:<key>`) and `inlineRead()`, a JavaScript
+  expression for an inline `<script>` that evaluates to the stored object or
+  `null` before hydration — unvalidated, so read only what you need with a
+  fallback. `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
@@ -38,5 +46,7 @@ When installed via npm, these docs live under `node_modules/@k8ordo/state/docs/`
   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.
+  `interface Register { routes: typeof routes }` — the same line as for
+  `@k8ordo/router` — to constrain `href` paths to the route table's linkable
+  paths; a router without a table registers its own path union as
+  `interface Register { path }` instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k8ordo/state",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Declare state by where it lives — URL search params, history-entry state, localStorage, or memory. One zod schema per place, over the Navigation API.",
   "keywords": [
     "localstorage",
@@ -40,9 +40,11 @@
     "registry": "https://registry.npmjs.org"
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
     "@types/react": "19.2.18",
     "@vitejs/plugin-react": "6.0.5",
     "@vitest/browser-playwright": "4.1.10",
+    "publint": "0.3.23",
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "typescript": "7.0.2",
@@ -50,15 +52,20 @@
     "vite-plus": "0.2.9",
     "vitest": "4.1.10",
     "vitest-browser-react": "2.2.0",
-    "zod": "4.4.3"
+    "zod": "4.4.3",
+    "@k8ordo/router": "^0.1.0"
   },
   "peerDependencies": {
     "@types/react": ">=19.2.18",
     "react": ">=19.2.6",
     "typescript": ">=7.0.2",
-    "zod": "^4.4.3"
+    "zod": "^4.4.3",
+    "@k8ordo/router": "^0.1.0"
   },
   "peerDependenciesMeta": {
+    "@k8ordo/router": {
+      "optional": true
+    },
     "@types/react": {
       "optional": true
     },
@@ -71,6 +78,7 @@
     "test": "vp test",
     "typecheck": "tsc --noEmit",
     "check": "vp check",
-    "check:write": "vp check --fix"
+    "check:write": "vp check --fix",
+    "check:package": "publint && attw --pack . --profile esm-only"
   }
 }