react-mnemonic 1.0.0-beta.0 → 1.2.0-beta1

package/README.md

@@ -1,70 +1,28 @@
 # react-mnemonic
 
-Persistent, type-safe state management for React.
+AI-friendly, persistent, type-safe state for React.
 
 [![npm version](https://img.shields.io/npm/v/react-mnemonic.svg)](https://www.npmjs.com/package/react-mnemonic)
-[![bundle size](https://img.shields.io/bundlephobia/minzip/react-mnemonic)](https://bundlephobia.com/package/react-mnemonic)
-[![license](https://img.shields.io/npm/l/react-mnemonic.svg)](./LICENSE.md)
-[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
+[![docs](https://img.shields.io/badge/docs-online-0A7EA4.svg)](https://thirtytwobits.github.io/react-mnemonic/)
+[![license](https://img.shields.io/npm/l/react-mnemonic.svg)](https://github.com/thirtytwobits/react-mnemonic/blob/main/LICENSE.md)
 
-**react-mnemonic** gives your React components persistent memory. Values survive
-page refreshes, synchronize across tabs, and stay type-safe end-to-end -- all
-through a single hook that works like `useState`.
-
-`1.0.0` is currently being shipped as a beta on the npm `beta` dist-tag while
-the release candidate hardening work finishes.
-
-## Features
-
-- **`useState`-like API** -- `useMnemonicKey` returns `{ value, set, reset, remove }`
-- **JSON Schema validation** -- optional schema-based validation using a built-in JSON Schema subset
-- **Namespace isolation** -- `MnemonicProvider` prefixes every key to prevent collisions
-- **Cross-tab sync** -- opt-in `listenCrossTab` uses the browser `storage` event
-- **Pluggable storage** -- bring your own backend via the `StorageLike` interface (IndexedDB, sessionStorage, etc.)
-- **Schema versioning and migration** -- upgrade stored data with versioned schemas and migration rules
-- **Structural migration helpers** -- optional tree utilities for idempotent insert/rename/dedupe migration steps
-- **Read-time reconciliation** -- selectively enforce new defaults on persisted values without clearing the whole key
-- **Recovery helpers** -- build user-facing soft reset and hard reset flows with namespace-scoped clear helpers
-- **Write-time normalization** -- migrations where `fromVersion === toVersion` run on every write
-- **Lifecycle callbacks** -- `onMount` and `onChange` hooks
-- **DevTools** -- inspect and mutate state from the browser console
-- **SSR-safe** -- returns defaults when `window` is unavailable
-- **Tree-shakeable, zero dependencies** -- ships ESM + CJS with full TypeScript declarations
+`react-mnemonic` gives your components persistent memory through a hook that feels like `useState`. Values survive reloads, can stay in sync across tabs, and remain SSR-safe by default. It is designed to be AI-friendly, prioritizing visible structure and unambiguous specifications. When you need more than raw storage, the package can validate, version, and migrate persisted data.
 
 ## Installation
 
 ```bash
-npm install react-mnemonic@beta
-```
-
-```bash
-yarn add react-mnemonic@beta
-```
-
-```bash
-pnpm add react-mnemonic@beta
+npm install react-mnemonic
 ```
 
-### Peer dependencies
-
-React 18 or later is required. CI verifies packaged-consumer installs against
-React 18 and React 19.
-
-```json
-{
-    "peerDependencies": {
-        "react": ">=18",
-        "react-dom": ">=18"
-    }
-}
-```
+React 18 or later is required.
 
 ## Quick start
 
-Wrap your app in a `MnemonicProvider`, then call `useMnemonicKey` anywhere inside it.
+Wrap your app in a `MnemonicProvider`, then call `useMnemonicKey` anywhere
+inside it.
 
 ```tsx
-import { MnemonicProvider, useMnemonicKey } from "react-mnemonic";
+import { MnemonicProvider, useMnemonicKey } from "react-mnemonic/core";
 
 function Counter() {
     const { value: count, set } = useMnemonicKey("count", {
@@ -88,496 +46,48 @@ export default function App() {
 }
 ```
 
-The counter value persists in `localStorage` under the key `my-app.count` and
-survives full page reloads.
-
-Persist only the durable slice of your app state. `useMnemonicKey` stores
-whatever you pass to `set`, so keep transient UI state like loading flags,
-hover state, and draft search text in plain React state unless you explicitly
-want them to rehydrate after reload. See the
-[Persisted vs Ephemeral State guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/persisted-vs-ephemeral-state)
-for patterns and an interactive example.
-
-For self-service recovery UX, pair your per-key hooks with
-`useMnemonicRecovery` so users can clear stale filters, reset broken settings,
-or fully wipe a namespace without opening DevTools. See the
-[Reset and Recovery guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/reset-and-recovery)
-for soft-reset and hard-reset recipes.
-
-If a field must stay cleared across reloads, model it as nullable and persist
-`null` explicitly. `remove()` deletes the key and falls back to `defaultValue`,
-while `reset()` writes the default again. See the
-[Clearable Persisted Values guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/clearable-persisted-values)
-for the canonical nullable pattern.
-
-## API
+This persists the counter in `localStorage` as `my-app.count`, so the value
+survives a full page reload.
 
-### `<MnemonicProvider>`
+## Why use it
 
-Context provider that scopes storage keys under a namespace.
+- `useState`-like API: `useMnemonicKey` returns `{ value, set, reset, remove }`
+- Namespaced persistence through `MnemonicProvider`
+- Optional cross-tab synchronization
+- SSR-safe defaults for server-rendered React apps
+- Optional schema validation, versioning, migrations, and reconciliation
+- Zero runtime dependencies with published TypeScript types
 
-```tsx
-<MnemonicProvider
-    namespace="my-app" // key prefix (required)
-    storage={localStorage} // StorageLike backend (default: localStorage)
-    schemaMode="default" // "default" | "strict" | "autoschema" (default: "default")
-    schemaRegistry={registry} // optional SchemaRegistry for versioned schemas
-    enableDevTools={false} // expose console helpers (default: false)
->
-    {children}
-</MnemonicProvider>
-```
-
-Multiple providers with different namespaces can coexist in the same app.
-
-### `useMnemonicKey<T>(key, options)`
-
-Hook for reading and writing a single persistent value.
-
-```ts
-const { value, set, reset, remove } = useMnemonicKey<T>(key, options);
-```
-
-| Return   | Type                                 | Description                                   |
-| -------- | ------------------------------------ | --------------------------------------------- |
-| `value`  | `T`                                  | Current decoded value (or default)            |
-| `set`    | `(next: T \| (cur: T) => T) => void` | Update the value (direct or updater function) |
-| `reset`  | `() => void`                         | Reset to `defaultValue` and persist it        |
-| `remove` | `() => void`                         | Delete the key from storage entirely          |
-
-For clearable fields, remember the semantic split:
-
-- `set(null)` persists a cleared value and stays cleared after reload
-- `remove()` deletes the key, so the next read falls back to `defaultValue`
-- `reset()` persists `defaultValue`
-
-#### Options
-
-| Option           | Type                                              | Default     | Description                                                   |
-| ---------------- | ------------------------------------------------- | ----------- | ------------------------------------------------------------- |
-| `defaultValue`   | `T \| ((error?: CodecError \| SchemaError) => T)` | _required_  | Fallback value or error-aware factory                         |
-| `codec`          | `Codec<T>`                                        | `JSONCodec` | Encode/decode strategy (bypasses schema validation)           |
-| `reconcile`      | `(value: T, context: ReconcileContext) => T`      | --          | Adjust a persisted value after read and persist if it changes |
-| `onMount`        | `(value: T) => void`                              | --          | Called once with the initial value                            |
-| `onChange`       | `(value: T, prev: T) => void`                     | --          | Called on every value change                                  |
-| `listenCrossTab` | `boolean`                                         | `false`     | Sync via the browser `storage` event                          |
-| `schema`         | `{ version?: number }`                            | --          | Pin writes to a specific schema version                       |
-
-### `useMnemonicRecovery(options)`
-
-Hook for namespace-scoped recovery actions such as "clear saved filters" or
-"reset all persisted app data".
-
-```ts
-const { namespace, canEnumerateKeys, listKeys, clearAll, clearKeys, clearMatching } = useMnemonicRecovery({
-    onRecover: (event) => console.log(event.action, event.clearedKeys),
-});
-```
+## Pick the right entrypoint
 
-| Return             | Type                                                | Description                                           |
-| ------------------ | --------------------------------------------------- | ----------------------------------------------------- |
-| `namespace`        | `string`                                            | Current provider namespace                            |
-| `canEnumerateKeys` | `boolean`                                           | Whether the storage backend can list namespace keys   |
-| `listKeys`         | `() => string[]`                                    | List visible unprefixed keys in the current namespace |
-| `clearAll`         | `() => string[]`                                    | Clear every key in the namespace                      |
-| `clearKeys`        | `(keys: readonly string[]) => string[]`             | Clear an explicit set of unprefixed keys              |
-| `clearMatching`    | `(predicate: (key: string) => boolean) => string[]` | Clear keys whose names match a predicate              |
+- `react-mnemonic/core` for the lean persisted-state path
+- `react-mnemonic/schema` when you want schemas, validation, and migrations
+- `react-mnemonic` if you need the backward-compatible root entrypoint
 
-`clearAll()` and `clearMatching()` require an enumerable storage backend such
-as `localStorage` or `sessionStorage`. If your custom storage does not support
-`length` and `key(index)`, use `clearKeys([...])` with the explicit durable-key
-list your app owns.
-
-### Codecs
-
-The default codec is `JSONCodec`, which handles all JSON-serializable values.
-You can create custom codecs using `createCodec` for types that need special
-serialization (e.g., `Date`, `Set`, `Map`).
-
-Using a custom codec bypasses JSON Schema validation -- the codec is a low-level
-escape hatch for when you need full control over serialization.
-
-```ts
-import { createCodec } from "react-mnemonic";
-
-const DateCodec = createCodec<Date>(
-    (date) => date.toISOString(),
-    (str) => new Date(str),
-);
-```
-
-### `StorageLike`
-
-The interface your custom storage backend must satisfy.
-
-```ts
-interface StorageLike {
-    getItem(key: string): string | null;
-    setItem(key: string, value: string): void;
-    removeItem(key: string): void;
-    key?(index: number): string | null;
-    readonly length?: number;
-    onExternalChange?: (callback: (changedKeys?: string[]) => void) => () => void;
-}
-```
-
-`onExternalChange` enables cross-tab sync for non-localStorage backends (e.g.
-IndexedDB over `BroadcastChannel`). The library handles all error cases
-internally -- see the `StorageLike` JSDoc for the full error-handling contract.
-Namespace-wide recovery helpers can only enumerate keys when the backend also
-implements `length` and `key(index)`.
-
-### `validateJsonSchema(schema, value)`
-
-Validate an arbitrary value against a JSON Schema (the same subset used by the
-hook). Returns an array of validation errors, empty when the value is valid.
-
-```ts
-import { validateJsonSchema } from "react-mnemonic";
-
-const errors = validateJsonSchema(
-    { type: "object", properties: { name: { type: "string" } }, required: ["name"] },
-    { name: 42 },
-);
-// [{ path: ".name", message: 'Expected type "string"' }]
-```
-
-### `compileSchema(schema)`
-
-Pre-compile a JSON Schema into a reusable validator function. The compiled
-validator is cached by schema reference (via `WeakMap`), so calling
-`compileSchema` twice with the same object returns the identical function.
-
-```ts
-import { compileSchema } from "react-mnemonic";
-import type { CompiledValidator } from "react-mnemonic";
-
-const validate: CompiledValidator = compileSchema({
-    type: "object",
-    properties: {
-        name: { type: "string", minLength: 1 },
-        age: { type: "number", minimum: 0 },
-    },
-    required: ["name"],
-});
-
-validate({ name: "Alice", age: 30 }); // []
-validate({ age: -1 }); // [{ path: "", … }, { path: ".age", … }]
-```
-
-This is useful when you validate the same schema frequently outside of the hook
-(e.g. in form validation or server responses).
-
-### Error classes
-
-| Class         | Thrown when                          |
-| ------------- | ------------------------------------ |
-| `CodecError`  | Encoding or decoding fails           |
-| `SchemaError` | Schema validation or migration fails |
-
-Both are passed to `defaultValue` factories so you can inspect or log the
-failure reason.
-
-## Usage examples
-
-### Cross-tab theme sync
-
-```tsx
-const { value: theme, set } = useMnemonicKey<"light" | "dark">("theme", {
-    defaultValue: "light",
-    listenCrossTab: true,
-    onChange: (t) => {
-        document.documentElement.setAttribute("data-theme", t);
-    },
-});
-```
+## AI resources
 
-### Error-aware defaults
-
-```tsx
-import { useMnemonicKey, CodecError, SchemaError } from "react-mnemonic";
-
-const getDefault = (error?: CodecError | SchemaError) => {
-    if (error instanceof CodecError) {
-        console.warn("Corrupt stored data:", error.message);
-    }
-    if (error instanceof SchemaError) {
-        console.warn("Schema validation failed:", error.message);
-    }
-    return { count: 0 };
-};
-
-const { value } = useMnemonicKey("counter", { defaultValue: getDefault });
-```
-
-## Schema modes and versioning
-
-Mnemonic supports optional schema versioning through `schemaMode` and an
-optional `schemaRegistry`.
-
-- `default`: Schemas are optional. Reads use a schema when one exists for the
-  stored version, otherwise the hook codec. Writes use the highest registered
-  schema for the key; if no schemas are registered, writes use an unversioned
-  (v0) envelope.
-- `strict`: Every stored version must have a registered schema. Reads without a
-  matching schema fall back to `defaultValue` with a `SchemaError`.
-  Writes require a registered schema when any schemas exist, but fall back to
-  a v0 envelope when the registry has none.
-- `autoschema`: Like `default`, but if no schema exists for a key, the first
-  successful read infers and registers a v1 schema. Subsequent reads/writes use
-  that schema.
-
-Version `0` is valid for schemas and migrations. Schemas at version `0` are
-treated like any other version.
-
-### JSON Schema validation
-
-Schemas use a subset of JSON Schema for validation. The supported keywords are:
-
-- `type` (including array form for nullable types, e.g., `["string", "null"]`)
-- `enum`, `const`
-- `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`
-- `minLength`, `maxLength`
-- `properties`, `required`, `additionalProperties`
-- `items`, `minItems`, `maxItems`
-
-```ts
-// Schema definition -- fully serializable JSON, no functions
-const schema: KeySchema = {
-    key: "profile",
-    version: 1,
-    schema: {
-        type: "object",
-        properties: {
-            name: { type: "string", minLength: 1 },
-            email: { type: "string" },
-            age: { type: "number", minimum: 0 },
-        },
-        required: ["name", "email"],
-    },
-};
-```
-
-### Write-time migrations (normalizers)
-
-A migration where `fromVersion === toVersion` runs on every write, acting as a
-normalizer. This is useful for trimming whitespace, lowercasing strings, etc.
-
-```ts
-const normalizer: MigrationRule = {
-    key: "name",
-    fromVersion: 1,
-    toVersion: 1,
-    migrate: (value) => String(value).trim().toLowerCase(),
-};
-```
-
-### Reconciliation
-
-Use `reconcile` when you want to keep persisted data but selectively enforce
-new application defaults after the value has been decoded and any read-time
-migrations have already run.
-
-```ts
-const { value } = useMnemonicKey("preferences", {
-    defaultValue: { theme: "dark", density: "comfortable", accents: true },
-    reconcile: (persisted, { persistedVersion }) => ({
-        ...persisted,
-        accents: persistedVersion === 0 ? true : persisted.accents,
-    }),
-});
-```
-
-Use a schema migration when the stored shape must move from one explicit version
-to another. Use `reconcile` for conditional, field-level policy changes such as
-rolling out a new default while preserving the rest of a user's stored data.
-
-### Structural migration helpers
-
-For layout-like data that already uses `id` and `children`, Mnemonic ships
-optional pure helpers for common idempotent migration steps:
-
-```ts
-import { insertChildIfMissing, renameNode, dedupeChildrenBy } from "react-mnemonic";
-
-const migrated = dedupeChildrenBy(
-    renameNode(insertChildIfMissing(layout, "sidebar", { id: "search", title: "Search" }), "prefs", "preferences"),
-    (node) => node.id,
-);
-```
-
-Use these inside your `MigrationRule.migrate` functions when you want repeatable
-tree edits without hand-writing the same traversal logic each time. See the
-[Schema Migration guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/schema-migration)
-for a cookbook example and custom adapter usage.
-
-### Example schema registry
-
-A schema registry stores versioned schemas for each key, and resolves migration
-paths to upgrade stored data. For the common immutable case, use
-`createSchemaRegistry(...)` instead of hand-rolling the indexing boilerplate.
-
-```tsx
-import {
-    createSchemaRegistry,
-    MnemonicProvider,
-    useMnemonicKey,
-    type KeySchema,
-    type MigrationRule,
-} from "react-mnemonic";
-
-const schemas: KeySchema[] = [
-    {
-        key: "profile",
-        version: 1,
-        schema: {
-            type: "object",
-            properties: { name: { type: "string" }, email: { type: "string" } },
-            required: ["name", "email"],
-        },
-    },
-    {
-        key: "profile",
-        version: 2,
-        schema: {
-            type: "object",
-            properties: {
-                name: { type: "string" },
-                email: { type: "string" },
-                migratedAt: { type: "string" },
-            },
-            required: ["name", "email", "migratedAt"],
-        },
-    },
-];
-
-const migrations: MigrationRule[] = [
-    {
-        key: "profile",
-        fromVersion: 1,
-        toVersion: 2,
-        migrate: (value) => {
-            const v1 = value as { name: string; email: string };
-            return { ...v1, migratedAt: new Date().toISOString() };
-        },
-    },
-    {
-        key: "profile",
-        fromVersion: 2,
-        toVersion: 2,
-        migrate: (value) => {
-            const profile = value as { name: string; email: string; migratedAt: string };
-            return { ...profile, email: profile.email.trim().toLowerCase() };
-        },
-    },
-];
-
-const registry = createSchemaRegistry({
-    schemas,
-    migrations,
-});
-
-function ProfileEditor() {
-    const { value, set } = useMnemonicKey<{ name: string; email: string; migratedAt: string }>("profile", {
-        defaultValue: { name: "", email: "", migratedAt: "" },
-    });
-    return <input value={value.name} onChange={(e) => set({ ...value, name: e.target.value })} />;
-}
-
-<MnemonicProvider namespace="app" schemaMode="default" schemaRegistry={registry}>
-    <ProfileEditor />
-</MnemonicProvider>;
-```
-
-`createSchemaRegistry` validates duplicate schemas and ambiguous migration
-graphs up front. If you need runtime schema registration for
-`schemaMode="autoschema"`, keep a custom mutable `SchemaRegistry`
-implementation.
-
-### Registry immutability
-
-In `default` and `strict` modes, the schema registry is treated as immutable for
-the lifetime of the provider. The hook caches registry lookups to keep read and
-write hot paths fast. To ship new schemas or migrations, publish a new app
-version and remount the provider.
-
-`autoschema` remains mutable because inferred schemas are registered at runtime.
-
-### Custom storage backend
-
-```tsx
-import { MnemonicProvider } from "react-mnemonic";
-import type { StorageLike } from "react-mnemonic";
-
-const idbStorage: StorageLike = {
-  getItem: (key) => /* read from IndexedDB */,
-  setItem: (key, value) => /* write to IndexedDB */,
-  removeItem: (key) => /* delete from IndexedDB */,
-  onExternalChange: (cb) => {
-    const bc = new BroadcastChannel("my-app-sync");
-    bc.onmessage = (e) => cb(e.data.keys);
-    return () => bc.close();
-  },
-};
-
-<MnemonicProvider namespace="my-app" storage={idbStorage}>
-  <App />
-</MnemonicProvider>
-```
-
-### DevTools
-
-Enable the console inspector in development:
-
-```tsx
-<MnemonicProvider namespace="app" enableDevTools={process.env.NODE_ENV === "development"}>
-```
-
-Then in the browser console:
-
-```js
-const app = window.__REACT_MNEMONIC_DEVTOOLS__?.resolve("app");
-
-app?.dump(); // table of all keys
-app?.get("theme"); // read a decoded value
-app?.set("theme", "dark"); // write
-app?.remove("theme"); // delete
-app?.keys(); // list all keys
-app?.clear(); // remove all keys
-```
-
-## TypeScript
-
-The library is written in strict TypeScript and ships its own declarations.
-All public types are re-exported from the package root:
-
-```ts
-import type {
-    Codec,
-    StorageLike,
-    MnemonicProviderOptions,
-    MnemonicProviderProps,
-    UseMnemonicKeyOptions,
-    KeySchema,
-    MigrationRule,
-    MigrationPath,
-    SchemaRegistry,
-    SchemaMode,
-    JsonSchema,
-    JsonSchemaType,
-    JsonSchemaValidationError,
-    CompiledValidator,
-} from "react-mnemonic";
-```
+| Resource                                                                                          | Purpose                                                                           |
+| ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| [AI Docs](https://thirtytwobits.github.io/react-mnemonic/docs/ai)                                 | Canonical invariants, decision matrix, recipes, anti-patterns, and setup guidance |
+| [`llms.txt`](https://thirtytwobits.github.io/react-mnemonic/llms.txt)                             | Compact retrieval index for tight context windows                                 |
+| [`llms-full.txt`](https://thirtytwobits.github.io/react-mnemonic/llms-full.txt)                   | Long-form export for indexing and larger prompt contexts                          |
+| [`ai-contract.json`](https://thirtytwobits.github.io/react-mnemonic/ai-contract.json)             | Machine-readable persistence contract for tooling and agent integrations          |
+| [DeepWiki priorities](https://github.com/thirtytwobits/react-mnemonic/blob/main/.devin/wiki.json) | Steering file that points DeepWiki toward the highest-signal sources              |
+| [AI Assistant Setup](https://thirtytwobits.github.io/react-mnemonic/docs/ai/assistant-setup)      | Generated instruction packs plus the documented MCP-friendly retrieval path       |
 
-## Disclaimer
+## Learn more
 
-THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. The authors make no guarantees
-regarding the reliability, availability, or suitability of this library for any
-particular use case. See the [MIT License](./LICENSE.md) for full terms.
+- [Documentation home](https://thirtytwobits.github.io/react-mnemonic/)
+- [Quick Start](https://thirtytwobits.github.io/react-mnemonic/docs/getting-started/quick-start)
+- [Server Rendering](https://thirtytwobits.github.io/react-mnemonic/docs/guides/server-rendering)
+- [Canonical Key Definitions](https://thirtytwobits.github.io/react-mnemonic/docs/guides/canonical-key-definitions)
+- [Single Source of Truth Schemas](https://thirtytwobits.github.io/react-mnemonic/docs/guides/single-source-of-truth-schemas)
+- [Schema Migration](https://thirtytwobits.github.io/react-mnemonic/docs/guides/schema-migration)
+- [Auth-Aware Persistence](https://thirtytwobits.github.io/react-mnemonic/docs/guides/auth-aware-persistence)
+- [Context7 Rankings](https://thirtytwobits.github.io/react-mnemonic/docs/guides/context7-rankings)
+- [API Reference](https://thirtytwobits.github.io/react-mnemonic/docs/api)
+- [AI Overview](https://thirtytwobits.github.io/react-mnemonic/docs/ai)
 
 ## License
 
-[MIT](./LICENSE.md) -- Copyright Scott Dixon
+[MIT](https://github.com/thirtytwobits/react-mnemonic/blob/main/LICENSE.md)