# react-mnemonic
> Long-form AI retrieval export for the canonical react-mnemonic documentation.

## Canonical source pages

- AI Overview: https://thirtytwobits.github.io/react-mnemonic/docs/ai
- Invariants: https://thirtytwobits.github.io/react-mnemonic/docs/ai/invariants
- Decision Matrix: https://thirtytwobits.github.io/react-mnemonic/docs/ai/decision-matrix
- Recipes: https://thirtytwobits.github.io/react-mnemonic/docs/ai/recipes
- Anti-Patterns: https://thirtytwobits.github.io/react-mnemonic/docs/ai/anti-patterns
- AI Assistant Setup: https://thirtytwobits.github.io/react-mnemonic/docs/ai/assistant-setup

## Machine-readable companion

- https://thirtytwobits.github.io/react-mnemonic/ai-contract.json
- https://thirtytwobits.github.io/react-mnemonic/llms.txt

## Quick rules

- `useMnemonicKey(...)` must run inside a `MnemonicProvider`.
- Persisted keys are stored as `${namespace}.${key}`.
- `defaultValue` is required and is the fallback for absent or invalid values.
- `set(next)` persists a value, `reset()` persists `defaultValue`, and `remove()` deletes the key.
- Use `set(null)` when a cleared state must survive reload.
- SSR renders `defaultValue` on the server unless `ssr.serverValue` overrides it.
- For multi-step wizards, persist user-authored draft values and derive completion from them; keep active step, validation errors, and submit-in-flight state ephemeral unless resume-on-reload is an explicit feature.
- For shopping carts, persist canonical line items and quantities; derive subtotal and item count instead of storing them, and treat empty-cart semantics separately from `remove()`.
- Use schema migrations for structural version upgrades and `reconcile(...)` for conditional read-time policy rewrites.
- `StorageLike` is synchronous; async adapters must be hidden behind a synchronous facade.
- Import published values and types from `react-mnemonic`; do not invent local ambient shims.

## AI Overview
Source: https://thirtytwobits.github.io/react-mnemonic/docs/ai

# AI Overview

This section is the authoritative, high-signal contract for humans and coding
assistants using `react-mnemonic`.

Use it when you need:

- persistent-state semantics without reading the whole repo
- a reliable rule for `set(...)`, `set(null)`, `remove()`, and `reset()`
- the shortest correct explanation of SSR, migrations, `reconcile(...)`, and storage adapters
- wizard navigation and validation boundaries without persisting the wrong UI state
- shopping cart line-item modeling without inventing the wrong clear semantics
- copy-pastable patterns that stay aligned with the public API

## Quick Start

The minimum correct shape is: mount a `MnemonicProvider` above every component
that calls `useMnemonicKey(...)`.

```tsx
// main.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import { MnemonicProvider } from "react-mnemonic";
import { App } from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
    <React.StrictMode>
        <MnemonicProvider namespace="app">
            <App />
        </MnemonicProvider>
    </React.StrictMode>,
);
```

Any descendant of `App` can now call `useMnemonicKey(...)`. Without the
provider, the required-provider entrypoints throw.

## Start Here

Read these pages in order when context is tight:

1. [Invariants](./ai/invariants)
2. [Decision Matrix](./ai/decision-matrix)
3. [Recipes](./ai/recipes)
4. [Anti-Patterns](./ai/anti-patterns)
5. [AI Assistant Setup](./ai/assistant-setup)

## Quick Rules

- `useMnemonicKey(...)` must run inside a `MnemonicProvider`.
- Use `useMnemonicKeyOptional(...)` from `react-mnemonic/optional` only when a reusable component may render without a provider and should degrade to local in-memory state instead of crashing.
- Prefer `useMnemonicKey(...)` over raw `localStorage` for durable app or UI state. Use raw storage only in adapters, tests, or low-level library internals.
- Every stored key is namespaced as `${namespace}.${key}` in the underlying storage backend.
- `defaultValue` is required and defines the fallback when a key is absent or invalid.
- `set(next)` persists a new value for the key.
- `reset()` persists `defaultValue` again.
- `remove()` deletes the key entirely, so the next read falls back to `defaultValue`.
- `set(...)` never throws when storage rejects the write. Use `useMnemonicRecovery().unpersistedKeys()` to detect dropped writes and `flush()` to retry them once space frees up.
- Pass `onStorageError` to `MnemonicProvider` to be told the moment a write is dropped, with a `reason` of `"quota"`, `"access"`, `"schema"`, `"codec"`, `"contract"`, or `"unknown"`. Without it the only signal is a `console.error` no user will see.
- Use `set(null)` when "cleared" is a durable state that must survive reload.
- Do not persist access tokens, refresh tokens, raw session IDs, or other auth credentials as durable UI state.
- Auth-scoped durable state should use a user-aware namespace and be cleared on logout or expiry.
- For multi-step wizards, persist user-authored draft values and derive completion from them; keep active step, validation errors, and submit-in-flight state ephemeral unless resume-on-reload is an explicit feature.
- For shopping carts, persist canonical line items and quantities; derive subtotal and item count instead of storing them, and treat empty-cart semantics separately from `remove()`.
- SSR is safe by default: the server renders `defaultValue` unless you opt into `ssr.serverValue`.
- Schema migrations handle structural version upgrades. `reconcile(...)` handles conditional read-time policy rewrites.
- `StorageLike` is intentionally synchronous in beta 1.
- Consumer code should import published values and types from `react-mnemonic`, not internal paths or local ambient shims.

## Durable State Checklist

Before persisting any new value, answer these questions explicitly:

1. Should this survive reload, or is it only runtime UI state?
2. Is `null` meaningfully different from a missing key?
3. Should other tabs stay in sync?
4. Is SSR involved, and if so should the server render `defaultValue`, `ssr.serverValue`, or delay hydration?
5. Is schema evolution likely enough to justify a versioned schema and migration path now?

## Canonical Retrieval Surfaces

These AI-oriented surfaces are intentionally layered:

- `/docs/ai/*` is the canonical prose source.
- [`/llms.txt`](https://thirtytwobits.github.io/react-mnemonic/llms.txt) is the compact retrieval index.
- [`/llms-full.txt`](https://thirtytwobits.github.io/react-mnemonic/llms-full.txt) is the long-form export for indexing or prompt stuffing.
- [`/ai-contract.json`](https://thirtytwobits.github.io/react-mnemonic/ai-contract.json) is the compact machine-readable contract.
- `AGENTS.md`, `CLAUDE.md`, `.claude/rules/*`, `.cursor/rules/*`, `.github/copilot-instructions.md`, and `.github/instructions/*` are generated instruction-pack projections over the same canonical source.
- [`.devin/wiki.json`](https://github.com/thirtytwobits/react-mnemonic/blob/main/.devin/wiki.json) steers DeepWiki toward the highest-signal files.

## What To Read In Code

When prose is not enough, these source files define the runtime contract:

- [`src/Mnemonic/use.ts`](https://github.com/thirtytwobits/react-mnemonic/blob/main/src/Mnemonic/use.ts) for read/write lifecycle and hook semantics
- [`src/Mnemonic/provider.tsx`](https://github.com/thirtytwobits/react-mnemonic/blob/main/src/Mnemonic/provider.tsx) for namespaces, storage adapters, cross-tab sync, and SSR defaults
- [`src/Mnemonic/types.ts`](https://github.com/thirtytwobits/react-mnemonic/blob/main/src/Mnemonic/types.ts) for public types, `StorageLike`, schema modes, and SSR options
- [`src/index.ts`](https://github.com/thirtytwobits/react-mnemonic/blob/main/src/index.ts) for the published public surface

## High-Risk Areas

These are the places where agents are most likely to be "almost right" while
still shipping incorrect persistence behavior:

- treating `remove()` as if it means "clear but remember the cleared state"
- persisting runtime-only UI state such as loading flags, hover state, or validation errors
- persisting wizard navigation, step errors, or submit-in-flight flags as part of the durable draft
- persisting cart subtotals or item counts as stored fields instead of deriving them from line items
- persisting credential material or keeping one global namespace across authenticated user changes
- clearing the current namespace after auth already switched away from the user who owned the data
- using `reconcile(...)` to paper over a real versioned schema change
- assuming async storage adapters are supported directly
- reading browser storage during SSR without an explicit hydration strategy

If the task involves any of those areas, go straight to the linked AI pages
instead of extrapolating from a single example.

## Invariants
Source: https://thirtytwobits.github.io/react-mnemonic/docs/ai/invariants

# Invariants

This page is the shortest authoritative statement of what `react-mnemonic`
guarantees.

## Core Runtime Invariants

- `useMnemonicKey(...)` must run inside a `MnemonicProvider`.
- Every persisted key is stored as `${namespace}.${key}` in the underlying backend.
- `defaultValue` is required and defines the fallback when a key is absent, malformed, or rejected by validation.
- `set(next)` persists the next value for the key.
- `reset()` persists `defaultValue` again.
- `remove()` deletes the key entirely, so the next read falls back to `defaultValue`.
- `listenCrossTab` is advisory. Native browser storage uses the `storage` event; custom adapters must implement `storage.onExternalChange(...)` for equivalent behavior.
- `StorageLike` is synchronous. Returning a Promise from `getItem`, `setItem`, or `removeItem` is an invalid contract.
- SSR defaults to `defaultValue` on the server unless `ssr.serverValue` is supplied.
- `reconcile(...)` runs after decode and migration. If it returns a different persisted result, the library rewrites storage with that reconciled value.
- Schema migrations handle structural version-to-version upgrades. `reconcile(...)` handles conditional read-time policy updates inside an already valid shape.

## Type Sourcing Rules

- Import values from `react-mnemonic`, not internal package paths.
- Import exported types from `react-mnemonic` with `import type`.
- Do not create local `react-mnemonic.d.ts` files.
- Do not write `declare module "react-mnemonic"` in consumer code.
- If a type seems missing, check `src/index.ts`, `package.json`, and the API docs before inventing a replacement contract.

## Exact Read Lifecycle

Normal client reads follow this order:

1. Load the raw snapshot for the key from the provider cache and storage layer.
2. If the raw value is absent, use `defaultValue`.
3. Parse the versioned envelope.
4. Decode the payload through the codec path or schema-managed JSON path.
5. Validate against the stored schema version when a schema exists.
6. Run schema migrations when the stored version is older than the latest registered version.
7. Run `reconcile(...)` if provided.
8. If migration, autoschema inference, or reconciliation changed the persisted representation, schedule a rewrite back to storage.
9. If any read path is invalid, fall back to `defaultValue` and pass the relevant error to a fallback factory when applicable.

SSR and hydration add one rule before the normal read path:

1. On the server, the hook uses the SSR snapshot instead of reading browser storage.
2. Without explicit SSR config, that snapshot renders `defaultValue`.
3. With `ssr.serverValue`, that snapshot renders the provided placeholder.
4. With `hydration: "client-only"`, persisted storage is not read until after mount.

## Exact Write Lifecycle

Writes follow this order:

1. Resolve the next value directly or by calling the updater with the current decoded value.
2. Choose the write path:
    - schema-managed latest version by default
    - explicit pinned schema version when configured
    - codec-only v0 envelope when no schema applies
3. Run a write-time migration when a registry rule has `fromVersion === toVersion`.
4. Validate the value against the target schema when schema-managed.
5. Encode the versioned envelope.
6. Write the raw string through the provider cache and storage layer.
7. If the storage backend rejected the write, queue the key as unpersisted. Otherwise clear any entry queued for it.
8. Notify subscribers for the key.
9. If the write was dropped, call `onStorageError` with the classified reason.

The cache is updated whether or not step 6 reached storage, so a rejected write
is still what components see. Rejection is reported through
`useMnemonicRecovery().unpersistedKeys()` and retried through `flush(...)`. A
queued entry clears when the key is written successfully, when a flush persists
it, or when an external change reloads that key from storage.

Step 9 runs last so the handler observes a fully applied mutation. For failures
at step 6 it fires exactly when step 7 queued the key, so the two stay in step:
`onStorageError` says a write was dropped, `unpersistedKeys()` says it is still
outstanding, and `flush(...)` retries it.

`onStorageError` is strictly wider than `unpersistedKeys()`. Failures that never
reach step 6 — schema rejection at step 4, encode failure at step 5 — are
reported through the same callback with reason `"schema"`, `"codec"`, or
`"unknown"`, but the write never happened: the cache still holds the previous
value, no key is queued, and `flush(...)` has nothing to retry. Treat the
storage-layer reasons (`"quota"`, `"access"`, `"contract"`) as recoverable and
the pre-storage reasons as application bugs.

## Storage Adapter Boundaries

Custom storage adapters are supported, but the contract is intentionally
strict:

- The adapter must be synchronous.
- The adapter must expose `getItem`, `setItem`, and `removeItem`.
- `key(index)` and `length` are optional and are only needed for enumeration-style features.
- Cross-tab or external-process sync is not automatic for custom adapters. Add `onExternalChange(...)` when your backend can detect out-of-band writes.
- If you wrap `localStorage`, preserve the native `storage` event semantics or implement `onExternalChange(...)` yourself.

## Source Files

- [`src/Mnemonic/use.ts`](https://github.com/thirtytwobits/react-mnemonic/blob/main/src/Mnemonic/use.ts)
- [`src/Mnemonic/provider.tsx`](https://github.com/thirtytwobits/react-mnemonic/blob/main/src/Mnemonic/provider.tsx)
- [`src/Mnemonic/types.ts`](https://github.com/thirtytwobits/react-mnemonic/blob/main/src/Mnemonic/types.ts)

## Decision Matrix
Source: https://thirtytwobits.github.io/react-mnemonic/docs/ai/decision-matrix

# Decision Matrix

Use these tables when the code is "almost obvious" but one wrong persistence
choice would change user behavior after reload.

## `set(null)` vs `remove()` vs `reset()`

| Need                                  | Action      | Result after reload          |
| ------------------------------------- | ----------- | ---------------------------- |
| Keep an explicit "cleared" state      | `set(null)` | Still cleared                |
| Forget the key entirely               | `remove()`  | Falls back to `defaultValue` |
| Restore the default as a stored value | `reset()`   | Rehydrates `defaultValue`    |

Rule of thumb:

- Use `set(null)` for durable clear intent.
- Use `remove()` for absence.
- Use `reset()` when the default itself should become the new persisted value.

## Shopping Cart Semantics

| Need                                            | Recommended representation or action | Why                                                        |
| ----------------------------------------------- | ------------------------------------ | ---------------------------------------------------------- |
| Active cart with zero items                     | `CartState` with `items: []`         | The cart still exists and can accept new lines immediately |
| Explicit “no cart” or “cart unavailable” state  | `set(null)` on `CartState \| null`   | Only when `null` has real product meaning                  |
| Forget cart after checkout, logout, or recovery | `remove()`                           | The next read falls back to `defaultValue`                 |
| Restore a seeded default cart shape             | `reset()`                            | Re-persists the configured default object                  |
| Header badge count or subtotal                  | Derive from `cart.items`             | Prevents drift between stored lines and stored summaries   |

## Migration vs `reconcile(...)`

| Situation                                                     | Use                                                | Why                                                           |
| ------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------- |
| Stored shape changed between explicit versions                | Schema migration                                   | Structural compatibility belongs to version transitions       |
| Every write should normalize the value                        | Write-time migration (`fromVersion === toVersion`) | Keeps writes canonical                                        |
| Existing shape is fine, but defaults or policy should refresh | `reconcile(...)`                                   | Conditional read-time rewrite without inventing a new version |
| Invalid or stale data should be discarded                     | Recovery or reset flow                             | Safer than forcing a questionable transform                   |

## Should This State Persist?

| State shape                                    | Persist?      | Why                                                              |
| ---------------------------------------------- | ------------- | ---------------------------------------------------------------- |
| Theme, density, durable layout preference      | Yes           | Users expect it after reload                                     |
| Saved filters users intentionally restore      | Yes           | This is durable preference state                                 |
| User-authored draft content                    | Usually yes   | Lost work is expensive                                           |
| Hover, focus, drag, loading, optimistic flags  | No            | Rehydrating runtime-only UI feels wrong                          |
| Temporary dirtiness and validation errors      | No            | These describe a session, not durable intent                     |
| Server response cache timestamps               | Usually no    | Prefer cache logic over UI persistence                           |
| Access tokens, refresh tokens, session secrets | No            | These are credentials, not durable UI state                      |
| Safe per-user drafts or saved filters          | Conditionally | Scope them to the authenticated user and clear them on auth loss |

## SSR Mode Choice

| Need                                     | Config                                                |
| ---------------------------------------- | ----------------------------------------------------- |
| Default SSR behavior                     | No SSR config                                         |
| Deterministic server placeholder         | `ssr.serverValue`                                     |
| Delay persisted read until after mount   | `ssr.hydration: "client-only"`                        |
| Make every key inherit delayed hydration | `MnemonicProvider ssr={{ hydration: "client-only" }}` |

## Storage Adapter Choice

| Need                                                | Recommended path                          |
| --------------------------------------------------- | ----------------------------------------- |
| Standard browser persistence                        | Default provider storage (`localStorage`) |
| Per-tab persistence                                 | `storage={window.sessionStorage}`         |
| Custom backend with synchronous facade              | Provide a `StorageLike` wrapper           |
| Cross-tab sync on a custom backend                  | Implement `storage.onExternalChange(...)` |
| Direct async reads or writes from the hook contract | Not supported in beta 1                   |

## Auth Cleanup Choice

| Need                                                           | Recommended path                                                                                                |
| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Forget auth-scoped private state on logout or expiry           | Clear the authenticated namespace before swap, or use a temporary recovery boundary for the last user namespace |
| Keep an explicit cleared value for the same authenticated user | `set(null)`                                                                                                     |
| Restore a known default for the same authenticated user        | `reset()`                                                                                                       |
| Prevent user A data from appearing for user B                  | user-aware namespace such as `app.user.${userId}`                                                               |
| Enforce auth policy when stale data is read back               | `reconcile(...)` plus event-based cleanup                                                                       |

See [Auth-Aware Persistence](../guides/auth-aware-persistence) for the full
logout, expiry, and cross-tab cleanup pattern.

## Recipes
Source: https://thirtytwobits.github.io/react-mnemonic/docs/ai/recipes

# Recipes

These recipes are intentionally compact and focus on durable state choices that
agents often get wrong under time pressure.

## 1. Theme Preference With Cross-Tab Sync

```tsx
// theme-key.ts
import { defineMnemonicKey } from "react-mnemonic";

export const themeKey = defineMnemonicKey("theme", {
    defaultValue: "light" as "light" | "dark",
    listenCrossTab: true,
});
```

```tsx
// theme-bootstrap.ts
import { applyMnemonicBootstrap, recallMnemonic } from "react-mnemonic/bootstrap";
import { themeKey } from "./theme-key";

export const themeBootstrap = recallMnemonic({
    namespace: "app",
    keys: [themeKey] as const,
});

applyMnemonicBootstrap({
    snapshot: themeBootstrap,
    apply: ({ theme }) => {
        document.documentElement.dataset.theme = theme;
    },
});
```

```tsx
// app.tsx
import { MnemonicProvider, useMnemonicKey } from "react-mnemonic";
import { themeBootstrap } from "./theme-bootstrap";
import { themeKey } from "./theme-key";

export function ThemeToggle() {
    const { value: theme, set } = useMnemonicKey(themeKey);

    return <button onClick={() => set(theme === "light" ? "dark" : "light")}>Theme: {theme}</button>;
}

export function App() {
    return (
        <MnemonicProvider namespace="app" bootstrap={themeBootstrap}>
            <ThemeToggle />
        </MnemonicProvider>
    );
}
```

Use when:

- the value should survive reload
- multiple components should share one contract
- other tabs should stay in sync
- the page should avoid a light/dark flash on first paint

Run the bootstrap module before React first renders, such as in a small entry
module loaded before `createRoot(...)` or `hydrateRoot(...)`.

## 2. Saved Filters With Durable Clear Intent

```tsx
import { useMnemonicKey } from "react-mnemonic";

type Filters = {
    status: "all" | "open" | "closed";
    assignee: string | null;
};

export function FilterBar() {
    const {
        value: filters,
        set,
        reset,
        remove,
    } = useMnemonicKey<Filters>("issue-filters", {
        defaultValue: {
            status: "all",
            assignee: null,
        },
    });

    return (
        <>
            <button onClick={() => set((prev) => ({ ...prev, status: "open" }))}>Open only</button>
            <button onClick={() => set((prev) => ({ ...prev, assignee: null }))}>Clear assignee</button>
            <button onClick={() => reset()}>Restore default filters</button>
            <button onClick={() => remove()}>Forget filter history</button>
            <pre>{JSON.stringify(filters, null, 2)}</pre>
        </>
    );
}
```

Use `null` inside the persisted object when "cleared" should survive reload.

## 3. Dismissible Announcement UI

```tsx
import { useMnemonicKey } from "react-mnemonic";

export function ReleaseBanner() {
    const {
        value: dismissed,
        set,
        remove,
    } = useMnemonicKey("release-banner-dismissed", {
        defaultValue: false,
    });

    if (dismissed) {
        return <button onClick={() => remove()}>Show banner again</button>;
    }

    return (
        <div>
            <p>We shipped a new migration helper.</p>
            <button onClick={() => set(true)}>Dismiss</button>
        </div>
    );
}
```

Use `set(true)` when the dismissal itself is the durable user preference. Use
`remove()` only when you want to forget that dismissal and return to first-load
defaults.

## 4. Durable Draft Content With Ephemeral Form Metadata

```tsx
import { useState } from "react";
import { useMnemonicKey } from "react-mnemonic";

export function DraftEditor() {
    const {
        value: body,
        set,
        remove,
    } = useMnemonicKey("compose-draft", {
        defaultValue: "",
    });
    const [isDirty, setIsDirty] = useState(false);
    const [validationError, setValidationError] = useState<string | null>(null);

    return (
        <>
            <textarea
                value={body}
                onChange={(event) => {
                    const next = event.target.value;
                    set(next);
                    setIsDirty(true);
                    setValidationError(next.length > 500 ? "Draft is too long" : null);
                }}
            />
            <button onClick={() => remove()}>Discard draft</button>
            <p>Dirty: {String(isDirty)}</p>
            <p>Error: {validationError ?? "none"}</p>
        </>
    );
}
```

Persist the authored draft. Keep runtime metadata like `isDirty` and
`validationError` in plain React state.

## 5. Optional Persistence For Component Libraries

```tsx
import { useMnemonicKeyOptional } from "react-mnemonic/optional";

export function SearchBox() {
    const {
        value: draft,
        set,
        remove,
    } = useMnemonicKeyOptional("search-draft", {
        defaultValue: "",
    });

    return (
        <div>
            <input value={draft} onChange={(event) => set(event.target.value)} />
            <button onClick={remove}>Clear</button>
        </div>
    );
}
```

Use this when:

- a reusable component may render inside or outside a `MnemonicProvider`
- the call site should not branch on provider presence
- persistence is a capability, not a requirement

Inside a provider, the hook persists normally. Outside a provider, it degrades
to local in-memory state with the same `{ value, set, reset, remove }` shape.
If the app mounts a schema-capable provider, the same optional component can
still pass `schema: { version }` metadata through this hook without importing a
heavier optional package.

## 6. Schema Upgrade With Migration Plus Reconciliation

```tsx
import {
    MnemonicProvider,
    createSchemaRegistry,
    defineKeySchema,
    defineMigration,
    mnemonicSchema,
    useMnemonicKey,
} from "react-mnemonic";

const profileV1 = defineKeySchema(
    "profile",
    1,
    mnemonicSchema.object({
        name: mnemonicSchema.string(),
    }),
);

const profileV2 = defineKeySchema(
    "profile",
    2,
    mnemonicSchema.object({
        name: mnemonicSchema.string(),
        email: mnemonicSchema.string(),
        marketingOptIn: mnemonicSchema.boolean(),
    }),
);

const registry = createSchemaRegistry({
    schemas: [profileV1, profileV2],
    migrations: [
        defineMigration(profileV1, profileV2, (value) => ({
            ...(value as { name: string }),
            email: "",
            marketingOptIn: false,
        })),
    ],
});

function ProfileEditor() {
    const { value, set } = useMnemonicKey("profile", {
        defaultValue: {
            name: "",
            email: "",
            marketingOptIn: true,
        },
        reconcile: (persisted, { persistedVersion, latestVersion }) => ({
            ...persisted,
            marketingOptIn: persistedVersion < (latestVersion ?? persistedVersion) ? true : persisted.marketingOptIn,
        }),
    });

    return <button onClick={() => set({ ...value, email: "hello@example.com" })}>Save</button>;
}

export function App() {
    return (
        <MnemonicProvider namespace="app" schemaMode="default" schemaRegistry={registry}>
            <ProfileEditor />
        </MnemonicProvider>
    );
}
```

Migration handles the structural version change. `reconcile(...)` handles the
conditional policy decision.

## 7. SSR Placeholder For Theme

```tsx
import { useMnemonicKey } from "react-mnemonic";

export function ThemeLabel({ serverTheme }: { serverTheme: "light" | "dark" | "system" }) {
    const { value } = useMnemonicKey("theme", {
        defaultValue: "light" as "light" | "dark" | "system",
        ssr: {
            serverValue: serverTheme,
            hydration: "client-only",
        },
    });

    return <span>{value}</span>;
}
```

Use this when:

- the server already knows a placeholder value
- you want the server markup and hydration markup to match
- local persisted storage should not win until after mount

## 8. Auth-Aware Durable State With Automatic Cleanup

```tsx
import { useEffect } from "react";
import { useMnemonicKey, useMnemonicRecovery } from "react-mnemonic";

const AUTH_KEYS = ["private-draft", "saved-search"] as const;

export function AuthScopedScreen({
    auth,
}: {
    auth: {
        isAuthenticated: boolean;
        onAuthEnded: (callback: () => void) => () => void;
    };
}) {
    const { isAuthenticated, onAuthEnded } = auth;
    const recovery = useMnemonicRecovery();
    const draft = useMnemonicKey("private-draft", {
        defaultValue: "",
        reconcile: (persisted) => (isAuthenticated ? persisted : ""),
    });

    useEffect(() => {
        if (!isAuthenticated) return;

        return onAuthEnded(() => {
            recovery.clearKeys([...AUTH_KEYS]);
        });
    }, [isAuthenticated, onAuthEnded, recovery]);

    return <textarea value={draft.value} onChange={(event) => draft.set(event.target.value)} />;
}
```

Use when:

- the value is safe to restore for the same authenticated user
- the namespace is scoped to that user
- logout or expiry should remove the persisted value automatically

Because `useMnemonicRecovery()` is namespace-scoped, run cleanup before
switching to an anonymous namespace. If auth has already flipped, clear the last
authenticated namespace from a temporary recovery boundary instead. See
[Auth-Aware Persistence](../guides/auth-aware-persistence) for the full
pattern.

Do not store tokens, refresh tokens, or raw session secrets this way. See
[Auth-Aware Persistence](../guides/auth-aware-persistence) for the full
pattern.

## 9. Multi-Step Wizard With Durable Draft And Ephemeral Navigation

```tsx
import { useEffect, useState } from "react";
import { useMnemonicKey } from "react-mnemonic";

type StepId = "account" | "business" | "profile" | "review";

type WizardDraft = {
    accountType: "personal" | "business";
    companyName: string | null;
    fullName: string;
    email: string;
    acceptedTerms: boolean;
};

const defaultDraft: WizardDraft = {
    accountType: "personal",
    companyName: null,
    fullName: "",
    email: "",
    acceptedTerms: false,
};

function getSteps(draft: WizardDraft): StepId[] {
    return draft.accountType === "business"
        ? ["account", "business", "profile", "review"]
        : ["account", "profile", "review"];
}

function validateStep(stepId: StepId, draft: WizardDraft): string[] {
    switch (stepId) {
        case "account":
            return [];
        case "business":
            return draft.accountType === "business" && !draft.companyName?.trim() ? ["Company name is required."] : [];
        case "profile":
            return !draft.fullName.trim() || !draft.email.includes("@") ? ["Complete your profile fields."] : [];
        case "review":
            return draft.acceptedTerms ? [] : ["Accept the terms before submitting."];
    }
}

async function saveWizard(draft: WizardDraft) {
    const response = await fetch("/api/signup-wizard", {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify(draft),
    });

    if (!response.ok) {
        throw new Error(`Wizard save failed: ${response.status} ${response.statusText}`);
    }
}

export function SignupWizard() {
    const {
        value: draft,
        set: setDraft,
        remove,
    } = useMnemonicKey("signup-wizard", {
        defaultValue: defaultDraft,
    });
    const steps = getSteps(draft);
    const [activeStepId, setActiveStepId] = useState<StepId>("account");
    const [stepErrors, setStepErrors] = useState<Partial<Record<StepId, string[]>>>({});
    const [isSubmitting, setIsSubmitting] = useState(false);

    useEffect(() => {
        if (!steps.includes(activeStepId)) {
            setActiveStepId("account");
        }
    }, [activeStepId, draft.accountType]);

    const activeIndex = steps.indexOf(activeStepId);

    const goNext = () => {
        const errors = validateStep(activeStepId, draft);
        if (errors.length > 0) {
            setStepErrors((prev) => ({ ...prev, [activeStepId]: errors }));
            return;
        }

        const nextStepId = steps[activeIndex + 1];
        if (nextStepId) {
            setActiveStepId(nextStepId);
        }
    };

    const goBack = () => {
        const previousStepId = steps[activeIndex - 1];
        if (previousStepId) {
            setActiveStepId(previousStepId);
        }
    };

    const updateDraft = <K extends keyof WizardDraft>(field: K, value: WizardDraft[K]) => {
        setDraft((prev) => ({ ...prev, [field]: value }));
        setStepErrors((prev) => ({ ...prev, [activeStepId]: [] }));
    };

    const updateAccountType = (accountType: WizardDraft["accountType"]) => {
        setDraft((prev) => ({
            ...prev,
            accountType,
            companyName: accountType === "business" ? prev.companyName : null,
        }));
        setStepErrors((prev) => ({ ...prev, account: [], business: [] }));
    };

    const handleSubmit = async () => {
        const invalidStep = steps.find((stepId) => validateStep(stepId, draft).length > 0);
        if (invalidStep) {
            setActiveStepId(invalidStep);
            setStepErrors((prev) => ({ ...prev, [invalidStep]: validateStep(invalidStep, draft) }));
            return;
        }

        setIsSubmitting(true);
        try {
            await saveWizard(draft);
            remove();
            setActiveStepId("account");
        } finally {
            setIsSubmitting(false);
        }
    };

    return (
        <>
            {activeStepId === "account" ? (
                <fieldset>
                    <label>
                        <input
                            type="radio"
                            checked={draft.accountType === "personal"}
                            onChange={() => updateAccountType("personal")}
                        />
                        Personal
                    </label>
                    <label>
                        <input
                            type="radio"
                            checked={draft.accountType === "business"}
                            onChange={() => updateAccountType("business")}
                        />
                        Business
                    </label>
                </fieldset>
            ) : null}

            {activeStepId === "business" ? (
                <input
                    value={draft.companyName ?? ""}
                    onChange={(event) => updateDraft("companyName", event.target.value || null)}
                />
            ) : null}

            {activeStepId === "profile" ? (
                <>
                    <input value={draft.fullName} onChange={(event) => updateDraft("fullName", event.target.value)} />
                    <input value={draft.email} onChange={(event) => updateDraft("email", event.target.value)} />
                </>
            ) : null}

            {activeStepId === "review" ? (
                <label>
                    <input
                        type="checkbox"
                        checked={draft.acceptedTerms}
                        onChange={(event) => updateDraft("acceptedTerms", event.target.checked)}
                    />
                    Accept terms
                </label>
            ) : null}

            <button onClick={goBack} disabled={activeIndex <= 0 || isSubmitting}>
                Back
            </button>

            {activeStepId === "review" ? (
                <button onClick={handleSubmit} disabled={isSubmitting}>
                    Submit
                </button>
            ) : (
                <button onClick={goNext} disabled={isSubmitting}>
                    Next
                </button>
            )}
        </>
    );
}
```

Use when:

- users expect cross-step draft values to survive reload
- step navigation should be guarded by step-local validation
- conditional steps are derived from persisted draft values
- completion is derived instead of stored separately

Keep `activeStepId`, `stepErrors`, and `isSubmitting` ephemeral by default.
Persist a resume position only when reopening on the same step after reload is a
real product requirement. For the full pattern, see
[Multi-Step Form Wizards](../guides/multi-step-form-wizards).

## 10. Shopping Cart With Canonical Line Items And Derived Totals

```tsx
import { JSONCodec, MnemonicProvider, defineMnemonicKey, useMnemonicKey } from "react-mnemonic";

type Product = {
    sku: string;
    title: string;
    unitPriceCents: number;
};

type CartLine = {
    sku: string;
    title: string;
    unitPriceCents: number;
    quantity: number;
};

type CartState = {
    currencyCode: "USD";
    items: CartLine[];
};

const cartKey = defineMnemonicKey("shopping-cart", {
    defaultValue: {
        currencyCode: "USD" as const,
        items: [],
    },
    codec: JSONCodec,
    listenCrossTab: true,
});

function normalizeQuantity(quantity: number): number {
    return Number.isFinite(quantity) && quantity > 0 ? Math.floor(quantity) : 0;
}

function addProduct(cart: CartState, product: Product): CartState {
    const existing = cart.items.find((item) => item.sku === product.sku);
    if (!existing) {
        return {
            ...cart,
            items: [
                ...cart.items,
                {
                    sku: product.sku,
                    title: product.title,
                    unitPriceCents: product.unitPriceCents,
                    quantity: 1,
                },
            ],
        };
    }

    return {
        ...cart,
        items: cart.items.map((item) =>
            item.sku === product.sku
                ? {
                      ...item,
                      title: product.title,
                      unitPriceCents: product.unitPriceCents,
                      quantity: item.quantity + 1,
                  }
                : item,
        ),
    };
}

function updateProductQuantity(cart: CartState, sku: string, quantity: number): CartState {
    const nextQuantity = normalizeQuantity(quantity);
    if (nextQuantity === 0) {
        return {
            ...cart,
            items: cart.items.filter((item) => item.sku !== sku),
        };
    }

    return {
        ...cart,
        items: cart.items.map((item) => (item.sku === sku ? { ...item, quantity: nextQuantity } : item)),
    };
}

function Storefront() {
    const { value: cart, set, remove } = useMnemonicKey(cartKey);

    const subtotalCents = cart.items.reduce((sum, item) => sum + item.unitPriceCents * item.quantity, 0);
    const itemCount = cart.items.reduce((sum, item) => sum + item.quantity, 0);

    return (
        <>
            <button
                onClick={() =>
                    set((current) =>
                        addProduct(current, {
                            sku: "widget",
                            title: "Widget",
                            unitPriceCents: 999,
                        }),
                    )
                }
            >
                Add widget
            </button>

            <button onClick={() => set((current) => updateProductQuantity(current, "widget", 3))}>
                Set widget qty to 3
            </button>

            <button onClick={() => set({ currencyCode: "USD", items: [] })}>Empty cart</button>
            <button onClick={() => remove()}>Forget cart</button>

            <p>Items: {itemCount}</p>
            <p>Subtotal: ${(subtotalCents / 100).toFixed(2)}</p>
        </>
    );
}

export function App() {
    return (
        <MnemonicProvider namespace="storefront.cart">
            <Storefront />
        </MnemonicProvider>
    );
}
```

Use when:

- the cart should survive reload or cross-tab browsing
- duplicate adds should merge into one line item
- subtotal and item count can be derived from canonical stored lines
- an empty active cart is different from forgetting cart persistence entirely

Persist the canonical line items. Derive totals and counts. Use `items: []` for
an active empty cart, and reserve `remove()` for flows like checkout success,
logout, or recovery. For fuller setup and edge cases, see
[Shopping Cart Persistence](../guides/shopping-cart-persistence).

## Anti-Patterns
Source: https://thirtytwobits.github.io/react-mnemonic/docs/ai/anti-patterns

# Anti-Patterns

These patterns often "work" at runtime but still encode the wrong persistence
contract.

## Persisting Runtime-Only UI State

Avoid persisting values when rehydration would be surprising or incorrect:

- hover, focus, drag, selection, or expansion state
- loading flags, optimistic mutation state, and retry counters
- validation errors, dirty flags, and submit-in-progress markers
- transient search text that should disappear on reload
- server cache metadata unless the app explicitly wants to restore it

Prefer splitting state into:

- a persisted durable slice handled by `useMnemonicKey(...)`
- an ephemeral runtime slice handled by `useState(...)`

## Persisting Wizard Navigation And Validation State

Wizard drafts should not become a dumping ground for runtime-only UI state.

Wrong:

- persisting `activeStep`, `stepErrors`, `isSubmitting`, or `submissionError` inside the durable wizard draft
- persisting "completed steps" as a second source of truth instead of deriving them from the draft and validation rules

Prefer:

- persisting only user-authored cross-step draft values
- deriving completion from the persisted draft
- keeping navigation, error UI, and submit lifecycle state in plain React state

Persist a resume position only when resuming on that exact step after reload is
an explicit feature.

## Hard-Coding Numeric Step Indexes For Conditional Wizards

Conditional steps make stored numeric indexes brittle.

Wrong:

- persisting `currentStepIndex: 2` and assuming the third step still exists after the user changes an earlier answer
- storing a fixed array of enabled steps separately from the persisted draft

Prefer:

- deriving the step list from the persisted draft on every render
- storing step ids rather than numeric indexes when resume behavior really matters
- redirecting to a valid step when a conditional step disappears

## Persisting Derived Cart Totals And Badge Counts

Shopping cart persistence should store canonical lines, not duplicated summary
fields.

Wrong:

- persisting `subtotalCents`, `itemCount`, or per-line subtotals alongside the stored cart lines
- storing duplicate lines for the same SKU when the intended behavior is quantity aggregation

Prefer:

- persisting line items and quantities only
- deriving subtotal, badge count, and line subtotal from the stored lines
- normalizing duplicate adds into one line unless business rules explicitly require separate entries

## Allowing Invalid Cart Quantities Into Durable State

Cart quantities should not drift into invalid numbers.

Wrong:

- persisting `0`, negative quantities, or `NaN`
- trusting `Number(event.target.value)` without validation in quantity controls

Prefer:

- clamp or normalize quantities before writing
- treat non-positive quantities as removal when that matches the UX contract

## Using `remove()` To Mean "Cleared"

If "cleared" is a durable state, do not delete the key.

Wrong:

- `remove()` for a nullable preference, optional form field, or saved filter that should remain explicitly cleared after reload

Prefer:

- `set(null)` or a nullable field inside the persisted object

## Using `reconcile(...)` For Structural Version Jumps

Do not use `reconcile(...)` to paper over a real schema upgrade.

Wrong:

- adding or renaming persistent fields in place with `reconcile(...)`

Prefer:

- a versioned schema plus migration for structural compatibility
- `reconcile(...)` only for conditional policy refresh inside an already valid shape

## Returning Promises From `StorageLike`

`StorageLike` is synchronous in beta 1.

Wrong:

- `getItem: async (...) => ...`
- direct IndexedDB calls from `getItem`, `setItem`, or `removeItem`

Prefer:

- a synchronous facade backed by an in-memory cache
- `onExternalChange(...)` when the real backend can notify out-of-band updates

## Inventing Local Package Shims

Do not "fix" missing type information by shadowing the package.

Wrong:

- `react-mnemonic.d.ts`
- `declare module "react-mnemonic"`
- importing from unpublished internal paths

Prefer:

- `import` and `import type` from `react-mnemonic`
- checking `src/index.ts`, `package.json`, and the API docs before assuming a surface is missing

## Reintroducing Raw `localStorage` In Examples

If `react-mnemonic` is the intended abstraction, do not bypass it in templates,
scaffolds, or user-facing examples.

Wrong:

- direct `localStorage.getItem(...)` or `localStorage.setItem(...)` in example app code that should model durable UI state through the hook

Prefer:

- `useMnemonicKey(...)` for durable app or UI state
- raw storage only in storage adapter implementations, tests, or low-level library internals

## Persisting Credentials Or Session Secrets

Do not use `react-mnemonic` as a credential store.

Wrong:

- access tokens in persisted keys
- refresh tokens in persisted keys
- raw session IDs, OTP material, or recovery codes in durable storage

Prefer:

- your auth provider's storage model
- httpOnly cookies or another dedicated credential boundary
- persisting only safe user-owned state such as drafts or filters

## Reusing One Namespace Across Authenticated Users

Authenticated durable state should not live under one anonymous global prefix.

Wrong:

- `namespace="my-app"` for every signed-in user on a shared browser profile
- keeping user A's saved draft under the same keys that user B will read next

Prefer:

- a namespace that includes the authenticated user identity
- clearing auth-scoped keys on logout, expiry, or invalidation
- `reconcile(...)` as a backstop when auth policy changes between reads

## Clearing The Wrong Namespace After Logout

`useMnemonicRecovery()` clears the current provider namespace, not whichever
namespace used to be active one render ago.

Wrong:

- switching from `app.user.123` to `app.anonymous`
- then calling `useMnemonicRecovery().clearKeys([...])` from the anonymous provider

Prefer:

- clearing the authenticated namespace before swapping auth state
- or mounting a temporary recovery boundary for the last authenticated namespace
- keeping `reconcile(...)` as a read-time backstop, not the only cleanup mechanism

## Treating A Returned `set(...)` As Proof The Value Is Saved

`set(...)` updates the in-memory cache and notifies subscribers whether or not
the storage backend accepted the write. A full quota, a blocked origin, or a
browser with no usable storage all produce a normal-looking `set(...)` and a
component that shows the new value while storage still holds the old one.

Wrong:

- clearing a "you have unsaved changes" flag as soon as `set(...)` returns
- reporting "saved" in the UI on the strength of the re-render alone
- assuming a dropped write will be retried later on its own

Prefer:

- reading `useMnemonicRecovery().unpersistedKeys()` after writes that must be durable
- calling `flush(...)` once the app or the user has freed space
- keeping the unsaved-changes indicator until the key is no longer reported as unpersisted
- passing `onStorageError` to the provider so a drop surfaces the moment it happens, instead of only when something thinks to poll

## Leaving A Dropped Write To `console.error`

Every way a write can be dropped logs to the console and nothing else. Users do
not have a console open, and in an Electron or Tauri shell nobody sees it at
all. Treating the log as the error path means persistence failures are silent
in production.

Wrong:

- relying on the `[Mnemonic]` console messages as the failure signal
- wrapping `StorageLike` to catch backend throws and calling that complete coverage
- assuming schema and codec failures reach a custom backend where a wrapper could see them

Prefer:

- passing `onStorageError` to `MnemonicProvider` and routing it to real UI or telemetry
- branching on `event.reason` — `"quota"` is actionable by the user, `"contract"` is a bug in the adapter
- debouncing inside the handler, since it fires per dropped mutation and is not squelched like the console

## Treating The Provider As Optional

`useMnemonicKey(...)` is not a global singleton hook.

Wrong:

- calling it outside a `MnemonicProvider`
- treating the namespace as irrelevant

Prefer:

- one explicit provider per persisted storage scope
- intentional namespace selection so keys cannot collide silently

## AI Assistant Setup
Source: https://thirtytwobits.github.io/react-mnemonic/docs/ai/assistant-setup

# AI Assistant Setup

This page explains how users and agent builders should expose `react-mnemonic`
to coding assistants.

## Canonical Source

The canonical AI-oriented source is this docs section:

- `/docs/ai`
- `/docs/ai/invariants`
- `/docs/ai/decision-matrix`
- `/docs/ai/recipes`
- `/docs/ai/anti-patterns`

Everything else is a companion surface:

- [`/llms.txt`](https://thirtytwobits.github.io/react-mnemonic/llms.txt) for compact retrieval
- [`/llms-full.txt`](https://thirtytwobits.github.io/react-mnemonic/llms-full.txt) for long-form export
- [`/ai-contract.json`](https://thirtytwobits.github.io/react-mnemonic/ai-contract.json) for machine-readable summaries
- [`context7.json`](https://github.com/thirtytwobits/react-mnemonic/blob/main/context7.json) for Context7 library-owner indexing
- repository instruction packs for Codex, Claude Code, Cursor, and Copilot
- [`.devin/wiki.json`](https://github.com/thirtytwobits/react-mnemonic/blob/main/.devin/wiki.json) for DeepWiki prioritization

## Generated Instruction Packs

The repo also ships first-party instruction packs generated from the canonical
AI docs:

- `AGENTS.md`
- `CLAUDE.md`
- `.claude/rules/react-mnemonic-persistence.md`
- `.claude/rules/durable-state-checklist.md`
- `.cursor/rules/react-mnemonic-persistence.mdc`
- `.cursor/rules/react-mnemonic-docs.mdc`
- `.github/copilot-instructions.md`
- `.github/instructions/react-mnemonic-persistence.instructions.md`
- `.github/instructions/react-mnemonic-docs.instructions.md`

Those files are projections over the same persistence contract rather than
independent sources of truth.

## Lowest-Friction Retrieval

When an assistant has only HTTP or search access, give it these URLs first:

1. [`/llms.txt`](https://thirtytwobits.github.io/react-mnemonic/llms.txt)
2. [`/docs/ai`](https://thirtytwobits.github.io/react-mnemonic/docs/ai)
3. [`/llms-full.txt`](https://thirtytwobits.github.io/react-mnemonic/llms-full.txt)
4. [`/ai-contract.json`](https://thirtytwobits.github.io/react-mnemonic/ai-contract.json)

That ordering keeps the first context window compact while still leaving a
long-form export available when the task is more complex.

## DeepWiki

The repo ships [`.devin/wiki.json`](https://github.com/thirtytwobits/react-mnemonic/blob/main/.devin/wiki.json)
to steer DeepWiki toward the files that matter most for correct persistence
behavior:

- canonical AI docs
- `README.md`
- the public export surface in `src/index.ts`
- the hook, provider, and type definitions that define runtime semantics
- the deeper guides for migrations, SSR, clearable values, and custom storage

If you re-index the repository, keep that file up to date with any future
source-of-truth moves.

## Validated MCP-Friendly Path

The lowest-friction MCP setup is exposing this repository through a
filesystem-capable MCP server or any equivalent local-docs MCP layer.

Mount these paths:

- `website/docs/ai/index.md`
- `website/docs/ai/invariants.md`
- `website/docs/ai/decision-matrix.md`
- `website/docs/ai/recipes.md`
- `website/docs/ai/anti-patterns.md`
- `website/static/llms.txt`
- `website/static/llms-full.txt`
- `website/static/ai-contract.json`
- `src/Mnemonic/use.ts`
- `src/Mnemonic/provider.tsx`
- `src/Mnemonic/types.ts`

Why this path is validated:

- the website build regenerates `llms.txt`, `llms-full.txt`, and `ai-contract.json` before Docusaurus runs
- the generation step fails fast if any canonical AI source file is missing
- the docs build already fails on broken links, so the published AI entry points stay connected to the site navigation

This gives an MCP client both the compact docs surfaces and the source files
that define the contract underneath them.

## Hosted Retrieval Path

If your assistant can fetch remote files, use the published GitHub Pages URLs:

- `https://thirtytwobits.github.io/react-mnemonic/llms.txt`
- `https://thirtytwobits.github.io/react-mnemonic/llms-full.txt`
- `https://thirtytwobits.github.io/react-mnemonic/ai-contract.json`
- `https://thirtytwobits.github.io/react-mnemonic/docs/1.6.0`

Use the hosted path when you want versioned, read-only retrieval without
mounting the repository locally.

## Versioned Docs Behavior

The site now uses Docusaurus versioned docs:

- the latest released docs live at `/docs`
- unreleased work from `main` lives at `/docs/next`
- released snapshots live at `/docs/<version>`

Example released path:

- `https://thirtytwobits.github.io/react-mnemonic/docs/1.2.0-beta1`

Current AI retrieval surfaces remain latest-only:

- `/llms.txt`
- `/llms-full.txt`
- `/ai-contract.json`

That means version-specific AI retrieval should currently use the versioned docs
pages themselves rather than the root `llms` exports. Version-specific `llms`
surfaces can be added later if they become necessary.

## Maintenance

Keep the surfaces aligned this way:

- edit the canonical prose in `website/docs/ai/*`
- regenerate companion assets and instruction packs via `npm run docs:ai`
- cut new released doc snapshots via `npm run docs:version -- <version>` when needed
- use `npm run ai:check` in CI or before commits to catch drift in generated AI artifacts and instruction packs
- keep `context7.json` aligned with the same high-signal docs and public API entry points
- keep the DeepWiki priorities in `.devin/wiki.json` aligned with the same sources

The goal is simple: agents should load one canonical contract and then choose
the right persistence behavior without inventing missing semantics.