@k8ordo/state 0.1.0 → 1.0.0

package/README.md

@@ -0,0 +1,168 @@
+# @k8ordo/state
+
+Declare state by where it lives — URL search params, hidden history-entry
+state, localStorage, sessionStorage, a cookie, or memory. One zod schema per
+boundary place (URL, entry, Web Storage, cookie) derives the server-side
+read, canonical links, salvage of stale data, and a client subscription with exact per-key
+change detection; memory never crosses a boundary, so it is a typed shared
+box with no schema. Links and GET forms write the URL before JavaScript loads
+under any router (the server renders what they wrote wherever it reads the
+search); 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
+
+<!-- peers -->
+
+| Package          | Version | Required | Needed for                                              |
+| ---------------- | ------- | -------- | ------------------------------------------------------- |
+| `react`          | ≥19.3.0 | yes      | `useAppState`                                           |
+| `zod`            | ^4.4.3  | yes      | the schemas (`zod/mini` works, and is the lighter pick) |
+| `@k8ordo/router` | ^1.0.0  | optional | typed `href` paths from the app's route table           |
+| `typescript`     | ≥7.0.0  | optional | the shipped type declarations                           |
+| `@types/react`   | ≥19.3.0 | optional | the shipped type declarations                           |
+
+<!-- /peers -->
+
+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 — a Next.js 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>
+    </>
+  );
+}
+```
+
+`parseUrl` needs a router that hands the page its search, as Next.js does.
+In `@k8ordo/framework`'s server mode a page asks for it by exporting the url
+schema —
+`export const search = listState.url` — and receives the slot already parsed
+as its `search` prop, ready to pass as `initialUrl`. Static mode refuses that
+export at build time, since a file is the same whatever the search
+holds; there, and on any page that does not export `search`, `useAppState`
+reads the url slot in the browser. A preference the server should render goes
+in `defineCookieState` instead of `defineLocalState`: in server mode,
+`parseCookies(request.cookies)` reads it and `initialCookie` seeds the first
+render, so the default never flashes.
+
+`update()` applies synchronously, batches per handler into one write (memory
+applies per call), 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 places and when each
+fits, history-entry state, cookie state the server renders (and why it is
+never a secret), migrating stored rows with `version` and `migrate`,
+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, sessionStorage,
+cookie 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` / `defineSessionState` /
+`defineCookieState` / `defineMemoryState`) in a shared module, read the url slot with `parseUrl`
+where the router hands the page its search and a cookie state with
+`parseCookies` where it hands the page the request's cookies, build links
+with `href`, and subscribe on the client with `useAppState`. Every boundary
+field needs a default or `.optional()`; never put a secret in a cookie state
+(the browser writes it, so it cannot be `HttpOnly`); 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/base.d.mts

@@ -0,0 +1,9 @@
+//#region src/base.d.ts
+/**
+ * A path as the URL spells it: Vite's `base` in front, so `/products` is
+ * `/docs/products` under `base: '/docs/'` and `/` is `/docs/`. The same rule
+ * as `@k8ordo/router`'s `withBase` — not borrowed, because the router is an
+ * optional peer this package only reads types from.
+ */
+export declare const withBase: (path: string) => string;
+//#endregion

package/dist/base.mjs

@@ -0,0 +1,15 @@
+//#region src/base.ts
+/**
+* A path as the URL spells it: Vite's `base` in front, so `/products` is
+* `/docs/products` under `base: '/docs/'` and `/` is `/docs/`. The same rule
+* as `@k8ordo/router`'s `withBase` — not borrowed, because the router is an
+* optional peer this package only reads types from.
+*/
+const withBase = (path) => {
+	const base = import.meta.env === void 0 ? "/" : import.meta.env.BASE_URL;
+	if (!base.startsWith("/") || base === "/") return path;
+	const prefix = base.endsWith("/") ? base.slice(0, -1) : base;
+	return path === "/" ? `${prefix}/` : `${prefix}${path}`;
+};
+//#endregion
+export { withBase };

package/dist/cookie-state.d.mts

@@ -0,0 +1,38 @@
+import { StateSchema } from "./schema/object.mjs";
+import { RowCodec, Versioning } from "./row/codec.mjs";
+import { output } from "zod/v4/core";
+//#region src/cookie-state.d.ts
+/**
+ * App-scope state that lives in a cookie: device-persistent and shared across
+ * tabs like local state, and — unlike it — sent with every request, so a
+ * server that reads the request's cookies renders the real values instead of
+ * the defaults. The browser writes it, so it can never be `HttpOnly`: a
+ * preference, never a secret.
+ */
+export type CookieState<Schema extends StateSchema = StateSchema> = {
+  kind: 'cookie';
+  /** Identity of this state: the cookie name and the store registry slot. */
+  key: string;
+  /** The schema as passed. */
+  schema: Schema;
+  /** The cookie the values are written under: `k8ordo-state.<key>`. */
+  cookieName: string;
+  /**
+   * Reads the values out of a request's cookies on the server —
+   * `request.cookies` under `@k8ordo/framework`'s server mode, whose values arrive
+   * percent-decoded. Absent, corrupt, or rejected fields get their defaults.
+   */
+  parseCookies: (cookies: ReadonlyMap<string, string>) => output<Schema>;
+  /**
+   * The value to hand a server's cookie API when it writes the same cookie
+   * (`cookies().set` from `@k8ordo/framework/server`, Next.js's): the JSON of these
+   * values, left for that API to percent-encode, as the browser store
+   * encodes it before writing. Unspecified fields mean their default, and
+   * the values pass the schema first, as `update()` does.
+   */
+  cookieValue: (values?: Readonly<Partial<output<Schema>>>) => string;
+};
+export declare const parseCookieText: (text: string | undefined) => unknown;
+export declare const cookieCodecOf: (def: CookieState) => RowCodec;
+export declare const defineCookieState: <Schema extends StateSchema>(key: string, schema: Schema, versioning?: Versioning<Schema>) => CookieState<Schema>;
+//#endregion

package/dist/cookie-state.mjs

@@ -0,0 +1,35 @@
+import { createRowCodec } from "./row/codec.mjs";
+//#region src/cookie-state.ts
+const COOKIE_NAME_PREFIX = "k8ordo-state.";
+const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/u;
+const parseCookieText = (text) => {
+	if (text === void 0) return void 0;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+};
+const codecs = /* @__PURE__ */ new WeakMap();
+const cookieCodecOf = (def) => {
+	const codec = codecs.get(def);
+	if (codec === void 0) throw new TypeError(`"${def.key}" was not created by defineCookieState of this module instance`);
+	return codec;
+};
+const defineCookieState = (key, schema, versioning) => {
+	const cookieName = `${COOKIE_NAME_PREFIX}${key}`;
+	if (!TOKEN.test(cookieName)) throw new TypeError(`"${key}" cannot name a cookie — use letters, digits and !#$%&'*+-.^_\`|~`);
+	const codec = createRowCodec(schema, "cookie", key, versioning);
+	const def = {
+		kind: "cookie",
+		key,
+		schema,
+		cookieName,
+		parseCookies: (cookies) => codec.read(parseCookieText(cookies.get(cookieName))).values,
+		cookieValue: (values) => JSON.stringify(codec.row(codec.salvage(values ?? {})))
+	};
+	codecs.set(def, codec);
+	return def;
+};
+//#endregion
+export { cookieCodecOf, defineCookieState, parseCookieText };

package/dist/entry/codec.d.mts

@@ -1,6 +1,6 @@
 import { StateSchema, StateValues } from "../schema/object.mjs";
 //#region src/entry/codec.d.ts
-type StoredCodec = {
+export type StoredCodec = {
   keys: readonly string[];
   defaults: Readonly<StateValues>;
   parse: (stored: unknown) => StateValues;
@@ -13,6 +13,5 @@ type StoredCodec = {
  * that what comes back may have been written by an older schema, or by
  * nobody.
  */
-declare const createStoredCodec: (schema: StateSchema, slot: string) => StoredCodec;
-//#endregion
-export { StoredCodec, createStoredCodec };
+export declare const createStoredCodec: (schema: StateSchema, slot: string) => StoredCodec;
+//#endregion

package/dist/index.d.mts

@@ -1,11 +1,13 @@
 import { StateSchema } from "./schema/object.mjs";
+import { Versioning } from "./row/codec.mjs";
+import { CookieState, defineCookieState } from "./cookie-state.mjs";
 import { Register, RegisteredPath } from "./register.mjs";
 import { UrlInput } from "./url/codec.mjs";
-import { OutputOf, PageState, definePageState } from "./page-state.mjs";
-import { LocalState, defineLocalState } from "./local-state.mjs";
+import { OutputOf, PageState, definePageState, urlReader } from "./page-state.mjs";
+import { LocalState, SessionState, defineLocalState, defineSessionState } from "./storage-state.mjs";
 import { MemoryState, defineMemoryState } from "./memory-state.mjs";
 import { UpdateHandle } from "./store/core.mjs";
 import { UpdateOptions } from "./store/page-store.mjs";
 import { AnyState, useAppState } from "./use-app-state.mjs";
 import { resetStateRegistry } from "./store/registry.mjs";
-export { type AnyState, type LocalState, type MemoryState, type OutputOf, type PageState, type Register, type RegisteredPath, type StateSchema, type UpdateHandle, type UpdateOptions, type UrlInput, defineLocalState, defineMemoryState, definePageState, resetStateRegistry, useAppState };
+export { type AnyState, type CookieState, type LocalState, type MemoryState, type OutputOf, type PageState, type Register, type RegisteredPath, type SessionState, type StateSchema, type UpdateHandle, type UpdateOptions, type UrlInput, type Versioning, defineCookieState, defineLocalState, defineMemoryState, definePageState, defineSessionState, resetStateRegistry, urlReader, useAppState };

package/dist/index.mjs

@@ -1,6 +1,7 @@
-import { definePageState } from "./page-state.mjs";
-import { defineLocalState } from "./local-state.mjs";
+import { defineCookieState } from "./cookie-state.mjs";
+import { definePageState, urlReader } from "./page-state.mjs";
+import { defineLocalState, defineSessionState } from "./storage-state.mjs";
 import { defineMemoryState } from "./memory-state.mjs";
 import { resetStateRegistry } from "./store/registry.mjs";
 import { useAppState } from "./use-app-state.mjs";
-export { defineLocalState, defineMemoryState, definePageState, resetStateRegistry, useAppState };
+export { defineCookieState, defineLocalState, defineMemoryState, definePageState, defineSessionState, resetStateRegistry, urlReader, useAppState };

package/dist/memory-state.d.mts

@@ -5,13 +5,12 @@ import { StateValues } from "./schema/object.mjs";
  * The one kind with no schema: its values never leave the runtime, so there
  * is no boundary to re-validate at — a typed `update` is the only writer.
  */
-type MemoryState<Values extends StateValues = StateValues> = {
+export type MemoryState<Values extends StateValues = StateValues> = {
   kind: 'memory';
   /** Identity of this state: the store registry slot. */
   key: string;
   /** The initial values; also what SSR renders. */
   initial: Readonly<Values>;
 };
-declare const defineMemoryState: <Values extends StateValues>(key: string, initial: Values) => MemoryState<Values>;
-//#endregion
-export { MemoryState, defineMemoryState };
+export declare const defineMemoryState: <Values extends StateValues>(key: string, initial: Values) => MemoryState<Values>;
+//#endregion

package/dist/page-state.d.mts

@@ -4,8 +4,8 @@ import { RegisteredPath } from "./register.mjs";
 import { UrlCodec, UrlInput } from "./url/codec.mjs";
 import { output } from "zod/v4/core";
 //#region src/page-state.d.ts
-type OutputOf<Schema> = Schema extends StateSchema ? output<Schema> : Record<never, never>;
-type PageState<Url extends StateSchema | undefined = StateSchema | undefined, Entry extends StateSchema | undefined = StateSchema | undefined> = {
+export type OutputOf<Schema> = Schema extends StateSchema ? output<Schema> : Record<never, never>;
+export type PageState<Url extends StateSchema | undefined = StateSchema | undefined, Entry extends StateSchema | undefined = StateSchema | undefined> = {
   kind: 'page';
   /** Identity of this state: store registry slot, entry-state namespace. */
   key: string;
@@ -17,10 +17,11 @@ type PageState<Url extends StateSchema | undefined = StateSchema | undefined, En
   parseUrl: (input: UrlInput) => OutputOf<Url>;
   /**
    * Builds a link. Unspecified fields mean their default and defaults are
-   * omitted from the query, so canonical URLs stay short. The path literal
-   * survives in the type, which is what lets typed-route checks pass.
+   * omitted from the query, so canonical URLs stay short. The path is in the
+   * table's terms and the URL carries Vite's `base` in front of it; the path
+   * literal survives in the type, which is what lets typed-route checks pass.
    */
-  href: <Path extends RegisteredPath>(base: Path, values?: Readonly<Partial<OutputOf<Url>>>) => Path | `${Path}?${string}`;
+  href: <Path extends string>(path: RegisteredPath<Path>, values?: Readonly<Partial<OutputOf<Url>>>) => Path | `${Path}?${string}`;
   /** The query string alone (no `?`), for handrolled URL composition. */
   search: (values?: Readonly<Partial<OutputOf<Url>>>) => string;
 };
@@ -32,22 +33,30 @@ type SharedKeys<Url, Entry> = Extract<keyof OutputOf<Url>, keyof OutputOf<Entry>
 type DisjointGuard<Url, Entry> = SharedKeys<Url, Entry> extends never ? unknown : {
   entry: `field declared in both url and entry: ${SharedKeys<Url, Entry>}`;
 };
-type PageInternals = {
+export type PageInternals = {
   url: UrlCodec | null;
   entry: StoredCodec | null;
   /** url keys first, then entry keys — the flat snapshot's full key set. */
   keys: readonly string[];
 };
-declare const internalsOf: (def: PageState) => PageInternals;
-declare function definePageState<Url extends StateSchema>(key: string, config: {
+export declare const internalsOf: (def: PageState) => PageInternals;
+export declare function definePageState<Url extends StateSchema>(key: string, config: {
   url: Url;
 }): PageState<Url, undefined>;
-declare function definePageState<Entry extends StateSchema>(key: string, config: {
+export declare function definePageState<Entry extends StateSchema>(key: string, config: {
   entry: Entry;
 }): PageState<undefined, Entry>;
-declare function definePageState<Url extends StateSchema, Entry extends StateSchema>(key: string, config: {
+export declare function definePageState<Url extends StateSchema, Entry extends StateSchema>(key: string, config: {
   url: Url;
   entry: Entry;
 } & DisjointGuard<Url, Entry>): PageState<Url, Entry>;
-//#endregion
-export { OutputOf, PageInternals, PageState, definePageState, internalsOf };
+/**
+ * Reads the url slot a schema describes out of a URL's search, the way
+ * `parseUrl` reads it for the definition the schema came from — defaults
+ * applied, repeated params gathered, a rejected field salvaged to its
+ * default. For code handed the schema alone: `@k8ordo/framework` reads the
+ * search of a page that exports `search = listState.url` through it. The
+ * codec is built once, when this is called.
+ */
+export declare const urlReader: <Url extends StateSchema>(schema: Url) => ((input: UrlInput) => output<Url>);
+//#endregion

package/dist/page-state.mjs

@@ -1,3 +1,4 @@
+import { withBase } from "./base.mjs";
 import { createStoredCodec } from "./entry/codec.mjs";
 import { createUrlCodec } from "./url/codec.mjs";
 //#region src/page-state.ts
@@ -21,9 +22,10 @@ function definePageState(key, config) {
 		entry: config.entry,
 		parseUrl: (input) => url === null ? {} : url.parse(input),
 		search,
-		href: (base, values) => {
+		href: (path, values) => {
 			const query = search(values);
-			return query === "" ? base : `${base}?${query}`;
+			const link = withBase(path);
+			return query === "" ? link : `${link}?${query}`;
 		}
 	};
 	internals.set(def, {
@@ -33,5 +35,17 @@ function definePageState(key, config) {
 	});
 	return def;
 }
+/**
+* Reads the url slot a schema describes out of a URL's search, the way
+* `parseUrl` reads it for the definition the schema came from — defaults
+* applied, repeated params gathered, a rejected field salvaged to its
+* default. For code handed the schema alone: `@k8ordo/framework` reads the
+* search of a page that exports `search = listState.url` through it. The
+* codec is built once, when this is called.
+*/
+const urlReader = (schema) => {
+	const codec = createUrlCodec(schema);
+	return (input) => codec.parse(input);
+};
 //#endregion
-export { definePageState, internalsOf };
+export { definePageState, internalsOf, urlReader };

package/dist/register.d.mts

@@ -1,22 +1,41 @@
+import { NavigablePath, NavigablePatternOf, Routes, RoutesRecord } 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.
- * Declared as an interface — the one exception to the repository's type-only
- * rule — because declaration merging is the entire mechanism.
+ * and every `href()` in the app is checked against the table's linkable
+ * patterns. 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 {
+export interface Register {}
+type LinkablePatterns<D> = D extends Routes<infer R extends RoutesRecord> ? { [K in NavigablePatternOf<R>]: K; }[NavigablePatternOf<R>] : never;
+/**
+ * `Path` when the router a `Register` shape describes accepts it, and what
+ * that router accepts when it does not, so the type error names the
+ * alternatives: matched against the table's linkable patterns segment by
+ * segment when it carries `routes` (refused, the patterns themselves),
+ * against the union as given when it carries `path` (refused, that union),
+ * and any `/`-path when it carries neither (refused, `` `/${string}` ``). A
+ * union of paths is accepted only when every member is. `NavigablePath` is
+ * imported as a type only, so `@k8ordo/router` is never loaded at runtime
+ * and stays an optional peer.
+ */
+export type AcceptedPath<R, Path extends string> = R extends {
+  routes: infer Table;
+} ? [Path] extends [NavigablePath<Table, Path>] ? Path : LinkablePatterns<Table> : R extends {
   path: infer P extends string;
-} ? P : `/${string}`;
-//#endregion
-export { Register, RegisteredPath };
+} ? [Path] extends [P] ? Path : P : [Path] extends [`/${string}`] ? Path : `/${string}`;
+/** `href()`'s path check: `Path` when the registered router accepts it. */
+export type RegisteredPath<Path extends string> = AcceptedPath<Register, Path>;
+//#endregion

package/dist/row/codec.d.mts

@@ -0,0 +1,48 @@
+import { StateSchema, StateValues } from "../schema/object.mjs";
+import { StoredCodec } from "../entry/codec.mjs";
+import { input } from "zod/v4/core";
+//#region src/row/codec.d.ts
+/**
+ * How a local or cookie state reads rows an older version of its schema
+ * wrote. Without it, such a row salvages field by field and every field the
+ * schema no longer accepts lands on its default.
+ */
+export type Versioning<Schema extends StateSchema = StateSchema> = {
+  /**
+   * The version rows are written with now: a positive integer, raised when the
+   * stored shape changes in a way salvage cannot carry across.
+   */
+  version: number;
+  /**
+   * Turns the values a row of an older version held into this version's.
+   * `fromVersion` is the version the row was written with — `0` for a row
+   * written before the definition declared a version. The result passes the
+   * schema field by field like any read, so its keys are the schema's but its
+   * values may be anything: map what you can, hand old values over as they
+   * are, and leave the rest out. A throw reads as nothing stored and leaves
+   * the row as it was.
+   */
+  migrate: (old: Readonly<Record<string, unknown>>, fromVersion: number) => { readonly [Key in keyof input<Schema>]?: unknown; };
+};
+/**
+ * The codec of a stored row — a Web Storage row or a cookie value, JSON
+ * either way. A versioned row is the pair `[version, values]`: an array is
+ * never what an unversioned row holds (the values are always an object), so
+ * the two never read as each other.
+ */
+export type RowCodec = Omit<StoredCodec, 'parse'> & {
+  /**
+   * The values in a parsed row. `stale` when the row was written by an older
+   * version and migrated here, so the caller writes it back.
+   */
+  read: (row: unknown) => {
+    values: StateValues;
+    stale: boolean;
+  };
+  /** The JSON-ready row for these values. */
+  row: (values: Readonly<StateValues>) => unknown;
+  /** The version rows are written with, `undefined` when unversioned. */
+  version: number | undefined;
+};
+export declare const createRowCodec: (schema: StateSchema, slot: string, key: string, versioning: Versioning | undefined) => RowCodec;
+//#endregion

package/dist/row/codec.mjs

@@ -0,0 +1,60 @@
+import { isRecord } from "../schema/object.mjs";
+import { createStoredCodec } from "../entry/codec.mjs";
+//#region src/row/codec.ts
+const envelopeOf = (row) => {
+	if (isRecord(row)) return {
+		fromVersion: 0,
+		values: row
+	};
+	if (Array.isArray(row) && row.length === 2 && Number.isSafeInteger(row[0]) && isRecord(row[1])) return {
+		fromVersion: row[0],
+		values: row[1]
+	};
+	return null;
+};
+const createRowCodec = (schema, slot, key, versioning) => {
+	const stored = createStoredCodec(schema, slot);
+	if (versioning === void 0) return {
+		...stored,
+		read: (row) => ({
+			values: stored.parse(row),
+			stale: false
+		}),
+		row: (values) => values,
+		version: void 0
+	};
+	const { version, migrate } = versioning;
+	if (!Number.isSafeInteger(version) || version < 1) throw new TypeError(`"${key}" version must be a positive integer, got ${String(version)}`);
+	const read = (row) => {
+		const envelope = envelopeOf(row);
+		if (envelope === null) return {
+			values: stored.parse(void 0),
+			stale: false
+		};
+		if (envelope.fromVersion >= version) return {
+			values: stored.parse(envelope.values),
+			stale: false
+		};
+		let migrated;
+		try {
+			migrated = migrate(envelope.values, envelope.fromVersion);
+		} catch {
+			return {
+				values: stored.parse(void 0),
+				stale: false
+			};
+		}
+		return {
+			values: stored.parse(migrated),
+			stale: true
+		};
+	};
+	return {
+		...stored,
+		read,
+		row: (values) => [version, values],
+		version
+	};
+};
+//#endregion
+export { createRowCodec };

package/dist/schema/object.d.mts

@@ -5,17 +5,17 @@ import { $ZodObject, $ZodShape, $ZodType } from "zod/v4/core";
  * core object and both expose `shape`. Accepting this keeps the smaller entry
  * usable without losing the types.
  */
-type StateSchema<Shape extends $ZodShape = $ZodShape> = $ZodObject<Shape> & {
+export type StateSchema<Shape extends $ZodShape = $ZodShape> = $ZodObject<Shape> & {
   shape: Shape;
 };
-type StateValues = Record<string, unknown>;
-type SchemaInfo = {
+export type StateValues = Record<string, unknown>;
+export type SchemaInfo = {
   schema: StateSchema;
   shape: Readonly<Record<string, $ZodType>>;
   keys: readonly string[];
   defaults: Readonly<StateValues>;
 };
-declare const isRecord: (value: unknown) => value is StateValues;
+export declare const isRecord: (value: unknown) => value is StateValues;
 /**
  * Structural equality over what schemas produce: scalars via `Object.is`,
  * arrays and plain objects recursively. Anything else (Date, Map, class
@@ -23,13 +23,12 @@ declare const isRecord: (value: unknown) => value is StateValues;
  * two structurally silent objects can still differ (a Date's time lives in
  * an internal slot, not in enumerable keys).
  */
-declare const sameValue: (a: unknown, b: unknown) => boolean;
-declare const analyzeSchema: (schema: StateSchema, slot: string) => SchemaInfo;
+export declare const sameValue: (a: unknown, b: unknown) => boolean;
+export declare const analyzeSchema: (schema: StateSchema, slot: string) => SchemaInfo;
 /**
  * Whole-parse first; when that fails, the values are user-editable or stale
  * input, so one broken field falls back to its own default instead of taking
  * the rest down with it.
  */
-declare const parseWithSalvage: (info: SchemaInfo, raw: StateValues) => StateValues;
-//#endregion
-export { SchemaInfo, StateSchema, StateValues, analyzeSchema, isRecord, parseWithSalvage, sameValue };
+export declare const parseWithSalvage: (info: SchemaInfo, raw: StateValues) => StateValues;
+//#endregion