@k8ordo/state 0.1.0 → 1.0.0

package/docs/GUIDE.md

@@ -1,35 +1,47 @@
 # @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
+history entry, localStorage, sessionStorage, a cookie, memory — and one zod
+schema per boundary place (URL, entry, Web Storage, cookie) derives
 everything else: the server-side read, canonical link building, salvage of
 stale data, and a client subscription with exact per-key change detection.
+Memory never crosses a boundary, so it is a typed box with no schema.
 
 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
+## The 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              | —      |
+| definition                  | lives in            | survives                 | shared with           | server                                         |
+| --------------------------- | ------------------- | ------------------------ | --------------------- | ---------------------------------------------- |
+| `definePageState` — `url`   | searchParams        | back/forward, sharing    | anyone given the URL  | reads, where the router passes the search      |
+| `definePageState` — `entry` | history entry state | back/forward, reload     | that tab's entry      | —                                              |
+| `defineLocalState`          | localStorage        | until deleted            | every tab, one device | —                                              |
+| `defineSessionState`        | sessionStorage      | reload, until tab closes | that tab              | —                                              |
+| `defineCookieState`         | a cookie            | 400 days from last write | every tab, one device | reads, where the page receives request cookies |
+| `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.
+atomically. Web Storage, cookies 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. sessionStorage is localStorage's per-tab twin,
+built the same way: it survives a reload of the tab — unlike memory — and
+goes when the tab does, seen by no other tab — unlike localStorage. A
+cookie and localStorage hold the same kind of thing — a preference of
+whoever uses the device — and differ in who can read it: every request
+carries the cookie, so the server renders the real value instead of the
+default.
 
 ```ts
 import {
+  defineCookieState,
   defineLocalState,
   defineMemoryState,
   definePageState,
+  defineSessionState,
 } from '@k8ordo/state';
 import * as z from 'zod/mini';
 
@@ -38,6 +50,7 @@ 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),
+    inStock: z._default(z.stringbool(), false),
   }),
   entry: z.object({
     expanded: z._default(z.array(z.string()), []),
@@ -50,6 +63,20 @@ export const prefs = defineLocalState(
   z.object({ view: z._default(z.enum(['grid', 'table']), 'grid') }),
 );
 
+// This tab's visit: kept through a reload, gone with the tab.
+export const notices = defineSessionState(
+  'notices',
+  z.object({ dismissed: z._default(z.array(z.string()), []) }),
+);
+
+// A preference the server renders: every request carries it.
+export const density = defineCookieState(
+  'density',
+  z.object({
+    density: z._default(z.enum(['comfortable', 'compact']), 'comfortable'),
+  }),
+);
+
 // 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
@@ -58,74 +85,335 @@ 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:
+a user can edit, Web Storage or cookie 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.
+identity: the Web Storage key (`k8ordo-state:<key>` in localStorage or
+sessionStorage, exposed as the definition's `storageKey`), the cookie name (`k8ordo-state.<key>`, exposed as
+`cookieName` — a cookie name is an HTTP token, so a cookie key is refused at
+module load when it holds anything but letters, digits and ``!#$%&'*+-.^_`|~``),
+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, session
+and cookie state, one stored row). Different kinds never collide: a local and
+a session definition under the same key are two places. The module system
+cannot enforce this, so treat the key like a global name.
+
+**A boundary schema must read back what it writes.** `update()` runs the
+merged values through the schema before anything is written, and a field that
+fails there lands on its default instead of the value you wrote. A url value
+is written into a query string and read again — the road a visitor's URL
+takes — so a url field must read back its own query-string spelling. A boolean
+is written in its schema's own spelling — `"true"`, or the first of a
+`z.stringbool()`'s `truthy` — which is what lets `z.stringbool()` turn it back
+into `true`; an array's booleans are each written in the item schema's. Two
+spellings that cannot are refused at module load rather than at the first
+click:
+
+| written                                                                   | use instead      |
+| ------------------------------------------------------------------------- | ---------------- |
+| `z.boolean()` / `z.coerce.boolean()` in `url`, or as a `url` array's item | `z.stringbool()` |
+| a `url` array that is `.optional()` or defaults 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
+not `[]` — non-empty, or `undefined` from `.optional()` — 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.
+
+Entry, local, session and cookie values are handed back to the schema as the
+typed values they are, so there the schema must accept its own output: a
+`z.stringbool()` or a type-changing transform never survives a write — use
+`z.boolean()` and plain types. `update()` does not round-trip the JSON that
+Web Storage and the cookie hold, so keep those fields to what JSON
+represents: a `z.date()` shows its `Date` after the write and falls back to
+its default on the next load.
+
+## When a stored shape changes
+
+A localStorage row or a cookie outlives the code that wrote it. On its own, a
+row an older schema wrote salvages field by field: every field the schema
+still accepts keeps its value and the rest land on their defaults — right for
+an added field or a tightened constraint, wrong for a renamed field or a
+changed meaning, which reset without a word. For those, give
+`defineLocalState` or `defineCookieState` a version and a migration:
+
+```ts
+export const prefs = defineLocalState(
+  'prefs',
+  z.object({
+    view: z._default(z.enum(['grid', 'table']), 'grid'),
+    pageSize: z._default(z.number(), 20),
+  }),
+  {
+    version: 1,
+    // Rows from before the version stored { layout: 'list' | 'cards' }.
+    migrate: (old) => ({
+      view: old['layout'] === 'list' ? 'table' : 'grid',
+      pageSize: old['pageSize'],
+    }),
+  },
+);
+```
+
+- **A versioned row is `[version, values]`.** A row with no version — written
+  before the definition declared one — reads as version `0`, so a definition
+  adopts a version when its shape first changes and migrates its existing
+  rows from `0`. Raise the version on the next change and branch on
+  `migrate`'s second argument, `fromVersion`.
+- **Older rows are migrated, then read, then written back.** A row older than
+  `version` goes through `migrate(old, fromVersion)` and then through the
+  schema, field by field like any read: `migrate` returns the schema's keys
+  (another key is a type error) with whatever values it has — hand old
+  values over as they are, and the schema rejects what does not fit. The
+  browser store writes the result back in the current version. The server's
+  `parseCookies` migrates too but never writes (a page cannot answer with
+  `Set-Cookie`); the browser writes back after hydration, and both read the
+  same values, so nothing flashes.
+- **A newer row is left alone.** A row a newer version wrote — a tab that
+  loaded the next deploy first — is salvaged without `migrate` and never
+  written back, so it stays the newer tab's.
+- **A throwing `migrate` loses nothing.** It reads as nothing stored: the
+  defaults show, and the row stays as it was for a fixed `migrate` to try
+  again.
+- **Adopting a version changes the row's shape.** A tab still running code
+  from before reads `[version, values]` as nothing stored until it reloads.
+- **`inlineRead()` hands out only the current version.** Neither the schema
+  nor `migrate` can run before a module loads, so a row of any other version
+  evaluates to `null` until a store has migrated it.
+- **Without the option, nothing changes:** a row is the bare values object,
+  salvaged field by field. `defineSessionState` takes no version — its rows
+  go with the tab, and salvage covers the rare one kept open across a deploy.
 
 ## 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.
+ships to the browser. Reach for `zod/mini` (a typical definition module
+bundles to about a third of classic `zod`'s gzipped size) unless the app
+already pays for classic `zod` elsewhere.
 
 ## The shape of it
 
 ```
-shared    definePageState / defineLocalState / defineMemoryState     no 'use client'
+shared    definePageState / defineLocalState / defineSessionState
+          defineCookieState / defineMemoryState — no 'use client'
             ↓ import                              ↓ import
 server    listState.parseUrl(searchParams)     client    useAppState(def, ['q', 'page'])
-          listState.href('/products', {...})             → [state, update]
+          density.parseCookies(request.cookies)          → [state, update]
+          listState.href('/products', {...})
           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.
+A definition is pure data — schemas (or a memory state's initial values) 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, Web Storage, the
+cookie jar — 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);
-  //    ^ { q: string; page: number } — typed, defaults applied
+  //    ^ { q: string; page: number; inStock: boolean } — 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 })}>
+      <a href={listState.href('/products', { ...url, page: url.page + 1 })}>
         next
-      </Link>
+      </a>
     </>
   );
 }
 ```
 
+**In `@k8ordo/framework`'s server mode a page says what of the search it
+reads.** A page
+exports the url schema it reads, and receives that slot, parsed, as `search`:
+
+```tsx
+// src/routes/products/page.tsx
+import type { PageProps } from '@k8ordo/framework';
+
+import { listState } from '../../state';
+
+export const search = listState.url;
+
+export default async function ProductsPage({ search }: PageProps<'/products'>) {
+  //                                          ^ { q: string; page: number }
+  const products = await fetchProducts(search);
+  return <ProductList products={products} />;
+}
+```
+
+The framework reads it the way `parseUrl` does — defaults applied, a
+rejected field salvaged — and, because the page is rendered for the search it
+was given, a navigation that moves the search loads that page again: a GET
+form, a link, or a url `update()`. That load is a state change otherwise — no
+scroll, no focus reset, nothing remounts — and `update().finished` settles
+once the page is on screen with the new search. The router's usual shortcut,
+a same-pathname navigation that loads nothing, still holds for every page
+that did not declare `search`, and for a search that did not move.
+
+A page that does not export `search` never sees the search, and neither does
+a layout: the pathname axis is the router's, and the search is read in the
+browser by `useAppState`, so such a server render shows the url slot's
+defaults and the live URL takes over one render after hydration.
+Static mode refuses the export: a file is the same whatever the search
+holds. Building links is unaffected — `href` and `search` are pure and run
+anywhere, including in a Server Component.
+
+`urlReader(schema)` is that reading on its own — a url schema in,
+`(input) => values` out, the codec built once — for code handed the schema
+without its definition; the framework's generated table calls it.
+
 `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.
+
+The path `href` takes is written from the application's root, the way the
+route table is, and the link it returns carries Vite's `base` in front of it:
+under `base: '/docs/'`, `listState.href('/products', { page: 2 })` is
+`/docs/products?page=2`. Hand it a path, then — not what `@k8ordo/router`'s
+`href` returned, which carries the base already. Outside Vite (Next.js, say)
+there is no `import.meta.env` to read, nothing is added, and a `basePath` is
+the framework's own `<Link>`'s to add.
+
+## Cookie state — preferences the server renders
+
+localStorage never reaches the server, so a preference kept there renders its
+default on the server and flips to the real value after hydration. A cookie
+goes with every request: where the page receives the request's cookies —
+`request.cookies` in `@k8ordo/framework`'s server mode — `parseCookies` reads
+the values
+and `initialCookie` seeds the server render and the hydration render with
+them, so the default never flashes.
+
+```tsx
+// src/routes/layout.tsx — server mode
+import type { LayoutProps } from '@k8ordo/framework';
+
+import { Shell } from '../components/shell';
+import { density } from '../state';
+
+export default function Layout({ request, children }: LayoutProps<'/'>) {
+  return (
+    <Shell initialCookie={density.parseCookies(request.cookies)}>
+      {children}
+    </Shell>
+  );
+}
+```
+
+```tsx
+// src/components/shell.tsx
+'use client';
+import { useAppState } from '@k8ordo/state';
+import type { OutputOf } from '@k8ordo/state';
+import type { ReactNode } from 'react';
+
+import { density } from '../state';
+
+type ShellProps = {
+  initialCookie: OutputOf<typeof density.schema>;
+  children: ReactNode;
+};
+
+export function Shell({ initialCookie, children }: ShellProps) {
+  const [values, update] = useAppState(density, { initialCookie });
+  // …
+}
+```
+
+- **One cookie per definition.** The values are one cookie named
+  `k8ordo-state.<key>` (`cookieName`), holding the percent-encoded JSON of the
+  declared fields. `parseCookies(cookies)` takes the request's cookies as a
+  `ReadonlyMap<string, string>` of percent-decoded values — what
+  `request.cookies` is — and salvages field by field like every other read:
+  absent, corrupt or rejected values land on their defaults.
+- **Seed every renderer.** Like `initialUrl`, `initialCookie` seeds only the
+  `useAppState` call it is passed to: a component that renders on the server
+  without it shows the defaults there. Read the cookie once, high up — a
+  layout receives `request` too — and pass the result down.
+- **Without the request, it is local state.** In static mode there is no
+  request: the server render shows the defaults and hydration takes the
+  cookie over, exactly as localStorage does.
+- **The browser writes it with the Cookie Store API** (Baseline since Firefox
+  140 shipped it in June 2025): `Path=/`, `SameSite=Lax`, `Max-Age` of 400
+  days — the longest a browser keeps a cookie — renewed by every write, and
+  `Secure`, which the API always sets, so the page must be on HTTPS —
+  Chromium and Firefox also keep it on `http://localhost`, but Safari drops a
+  `Secure` cookie there, so develop over HTTPS to see it persist in Safari.
+  `Lax` rather than the API's default `Strict` is what makes the
+  first request from a link on another site carry the cookie; under `Strict`
+  the server would render the defaults exactly there. A read is synchronous
+  (`document.cookie`), because a render cannot wait for the API's promise.
+- **Tabs agree.** The API's `change` event reaches every open tab, and it
+  reports a cookie a server response set as well as one a script wrote.
+- **Keep it small.** Every byte rides every request, and a cookie over 4 KB
+  (name and value together) is refused: the handle rejects with the API's
+  `TypeError` while the rendered value stays, as with a full localStorage.
+
+**Not a secret.** A cookie the browser writes can never be `HttpOnly`: any
+script on the page reads and rewrites it, and a visitor can edit it as freely
+as a URL. Keep sessions, tokens and anything else that must not leak or be
+forged out of it — and on the server, treat what `parseCookies` returns as
+input, which is why it passes the schema before you see it.
+
+**Cookies the server writes are a different tool.** A page is a render and
+never writes the response; in server mode the framework's
+`cookies()` writes cookies from the places that answer a request — `guard.ts`,
+`route.ts` and Server Actions. That is where a session cookie belongs, as
+`HttpOnly`, and this package never sees it. The same `cookies()` can also
+write a cookie state, for a form that sets a preference without JavaScript,
+say: write `cookieName` with the value `cookieValue(values)` returns — the
+values pass the schema, unspecified fields mean their default — and the
+attributes above (`Path=/`, `SameSite=Lax`, `Max-Age=34560000`), never
+`HttpOnly`, or the browser store can no longer see it. Open tabs take the new
+values in through the `change` event.
+
+```ts
+// src/lib/actions.ts
+'use server';
+import { cookies } from '@k8ordo/framework/server';
+
+import { density } from '../state';
+
+export async function compact() {
+  cookies().set(
+    density.cookieName,
+    density.cookieValue({ density: 'compact' }),
+    { httpOnly: false, maxAge: 34_560_000 },
+  );
+}
+```
+
+`cookieValue` returns the JSON unencoded: `cookies().set` percent-encodes the
+value on its way out (so does Next.js's), which is the one encoding
+`parseCookies` expects undone. Writing a `Set-Cookie` header by hand, pass
+the value through `encodeURIComponent` yourself — once.
 
 ## Client — subscribe and update
 
 ```tsx
+// src/components/filters.tsx
 'use client';
 import { useAppState } from '@k8ordo/state';
-import { listState, prefs } from './state';
+
+import { listState, prefs } from '../state';
 
 export function Filters({ initialUrl }: FiltersProps) {
   const [{ q, page, expanded }, update] = useAppState(listState, {
@@ -151,8 +439,9 @@ export function Filters({ initialUrl }: FiltersProps) {
 ```
 
 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.
+definition's two slots — moving a field between `url` and `entry` changes the
+definition and nothing at the call sites. The field's spelling follows its
+slot, though: `z.stringbool()` in `url` is `z.boolean()` in `entry`.
 
 ## Updates
 
@@ -162,37 +451,63 @@ 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.
-Awaiting `finished` composes with React 19 async transitions:
+Code that has to wait for the write awaits `finished`:
 
 ```tsx
-const [isPending, startTransition] = useTransition();
-startTransition(async () => {
+const onNext = async () => {
   await update({ page: 2 }).finished;
-});
+  heading.current?.focus();
+};
 ```
 
-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.
+An async action — `startTransition(async …)`, `useTransition`'s included, or
+`@k8ordo/ui`'s `Button` `onAction` — can await it the same way. Under
+`@k8ordo/router` a url update issued while another page is still loading is a
+page change, and a page change never joins the action, so `finished` settles
+once that page is on screen rather than waiting for the action to end.
+
+A navigation overtaken by a later one — another page state's write from the
+same handler, say — rejects the handle with an `AbortError`; unawaited calls
+never surface it. Updates with no navigation behind them return the same
+shape: entry-only, local, session and no-change page handles settle once the
+batch is flushed, cookie handles once the Cookie Store API has written it,
+memory handles on the spot. A local, session or cookie write that fails —
+the browser refuses it (a full quota, a cookie over 4 KB), or the schema
+throws on the values it was about to write — rejects the handle with that
+error while the rendered value stays.
+
+- **Patches are validated on the spot.** The merged state goes through the
+  schema inside `update()` itself, url fields 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. 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 what changed.** One patch may span both faces of a page
+  state: a batch that changes a url field travels, with any entry changes, in
+  a single `navigation.navigate()`, atomically. A batch that changes entry
+  values but no url value uses `updateCurrentEntry()` — no navigation, works
+  under any router — even when the patch names url fields. Local and session
+  state are one `setItem` on their storage, cookie state one
+  `cookieStore.set()`.
 - **`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.
+  option exists only on page state, the one kind with a navigation behind it,
+  and takes effect only when a url value changes: an entry-only write
+  rewrites the current entry in place.
+- **One handler, one write.** Several `update()` calls on a page, local,
+  session or cookie state made synchronously in one event handler collapse
+  into a single write — one navigation, entry update, storage write or cookie
+  write — and share one handle; an `await` between two calls starts a new
+  batch with its own write and handle. For page state, a batch that ends where
+  it started neither navigates nor touches the entry; local, session and
+  cookie state still write their row (creating one if none was stored).
+  Memory has nothing to batch: each call applies on the spot and returns its
+  own settled handle.
 - **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
@@ -201,7 +516,8 @@ behind them — entry-only, local, memory — return the same shape, settled.
 
 ## Subscription granularity
 
-The schema fixes the key set, so change detection is exact, per key:
+The definition fixes the key set — its schemas' keys, or a memory state's
+initial values — so change detection is exact, per key:
 
 ```tsx
 useAppState(listState); // any declared field re-renders this
@@ -216,19 +532,25 @@ 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
+Two operations depend on the router; everything else works under any router:
+
+| operation                                                               | needs                                                                                               |
+| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `href` / `search` links, GET forms                                      | nothing — the router or the browser handles the click or the submission                             |
+| updates that change only entry, local, session, cookie or memory values | nothing — no navigation is involved                                                                 |
+| url `update()` on the client                                            | a router that intercepts the Navigation API                                                         |
+| `parseUrl` on the server                                                | a router that hands the page its search (`@k8ordo/framework` in server mode: `export const search`) |
+
+A url `update()` calls `navigation.navigate()`. Under `@k8ordo/router` —
+including a page rendered by `@k8ordo/framework` — 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 — unless the page showing exports `search` in
+server mode and the search moved: then the page loads again, in place,
+and `finished` waits for it to be on screen. 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 +563,52 @@ 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
+// src/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 checks the path it is handed against the table's linkable
+patterns, segment by segment: a literal segment must be spelled as the pattern
+spells it, a `:param` takes any one non-empty segment — a `${string}` from a
+template literal such as `` `/${locale}/products` `` included — and a `*`
+wildcard is matched but never linked. A path no pattern matches is a type
+error, a `/:locale` table included: `'/ja/nowhere'` is refused even though
+`/:locale` takes any first segment. The error lists what would be accepted —
+the table's linkable patterns. With a table of `/`, `/members` and
+`/posts/:id`, `listState.href('/membrs')` reports:
+
+```
+Argument of type '"/membrs"' is not assignable to parameter of type '"/" | "/members" | "/posts/:id"'.
+```
+
+The check is exported as `RegisteredPath<Path>`: `Path` when accepted, and
+that union of patterns when refused. Each pattern's own spelling is a path
+the table accepts, so the union lets nothing through that the check refuses.
+It goes through `NavigablePath`
+from `@k8ordo/router` as a type only, so the router stays an optional peer and
+never loads at runtime. Under `@k8ordo/framework` this is generated for you into `.k8ordo/register.gen.ts` from
+`routes/` when the application's own `package.json` lists `@k8ordo/state` in
+`dependencies` or `devDependencies` — a transitive dependency does not count.
+Do not hand-write it in such an application: it would duplicate the generated
+declaration.
+
+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,20 +621,50 @@ 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, and the error lists the registered union.
+Without the augmentation the constraint is any `/`-prefixed string, and a path
+without the leading `/` is reported against `` `/${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 or session 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 object stored
+in its own storage area — localStorage or sessionStorage — or
+`null` when nothing is stored, the JSON is corrupt, the value is not an object,
+or storage cannot be read — and, for a versioned local state, when the row was
+written by another version. 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. The script changes
+`<html>` before React hydrates it, so render that element with
+`suppressHydrationWarning`.
 
 ## 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.
+Web Storage row or a cookie 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 does not take the rest down, and
+nothing throws at read time. An array field collects repeated params and is salvaged as one
+field: one rejected element resets the whole array to `[]`. 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
@@ -278,12 +675,27 @@ 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.
+`storage` event, cookie state through the Cookie Store API's `change` event;
+the same keyed subscription granularity applies. sessionStorage belongs to one
+tab, so its `storage` event reaches only other frames of that tab.
+
+**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. In `@k8ordo/framework`'s server mode a page that
+exports
+`search = listState.url` receives it already parsed — pass that as
+`initialUrl`. Where a page receives no search — any other page, and every page
+in static mode — the url slot renders its defaults and the live URL
+takes over on hydration.
+
+**SSR sees real cookie values when the page receives the request.** Pass what
+`parseCookies(request.cookies)` returned as `initialCookie` — in
+`@k8ordo/framework`'s server mode, say — and neither render shows the
+defaults. Without a request (static mode), the cookie takes over on
+hydration.
+
+Everything else — entry, local, session, memory — renders its defaults on the
+server by construction: those places do not exist there.
 
 ## GET forms with @k8ordo/form
 
@@ -296,13 +708,25 @@ 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.
+A `z.stringbool()` field derives a checkbox whose `value` is the same spelling
+of `true` that `update()` writes, so a checked box submits `inStock=true` —
+the URL state itself would write. The form submits as GET, which writes the
+URL with or without JavaScript.
+Where the router hands the page its search, the RSC reads it back with
+`parseUrl` and the whole loop works before JavaScript loads — in
+`@k8ordo/framework`'s server mode, a page that exports `search = listState.url` is that page,
+and with JavaScript the submission loads it again in place. Anywhere else
+(static mode, a page that does not declare `search`) the server render
+shows the defaults, and the submitted values appear once the page hydrates.
 
 ## Testing
 
 `resetStateRegistry()` clears the provider-less store registry between tests.
 Unmount components first — mounted hooks keep their store through closures.
+Clear stored rows by the definition's `storageKey` (in its own storage area)
+or `cookieName` (`await cookieStore.delete(def.cookieName)`); the Cookie
+Store API's `change` event fires in the same tab too, so a test that writes
+the cookie itself stands in for another tab.
 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.