React Mnemonic

https://github.com/thirtytwobits/react-mnemonic
Admin
React Mnemonic is an AI-friendly, type-safe, persistent state management library for React that...
Tokens:37,752
Snippets:221
Trust Score:8.3
License:MIT
Update:7 months ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- Prefer website/docs/ai as the canonical source for persistence semantics, invariants, and decision rules.
- Treat README.md and src/index.ts as the public package surface and prefer published entrypoints over internal paths.
- Use react-mnemonic/core for the lean persisted-state path and react-mnemonic/schema when validation, versioning, or migrations are required.
- Durable app state should use MnemonicProvider and useMnemonicKey rather than raw localStorage in consumer-facing code.
- Treat excluded build outputs as derived artifacts rather than source-of-truth documentation.

================
CODE SNIPPETS
================
### Install react-mnemonic package

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/getting-started/installation.md

Command to install the beta version of the react-mnemonic library using npm.

```bash
npm install react-mnemonic@beta
```

--------------------------------

### Implement Persistent State with MnemonicProvider and useMnemonicKey

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/getting-started/quick-start.md

This example shows how to wrap a React application with MnemonicProvider to create a namespaced storage scope and use the useMnemonicKey hook to manage and persist component state in localStorage.

```tsx
import { MnemonicProvider, useMnemonicKey } from "react-mnemonic/core";

function Counter() {
    const { value: count, set } = useMnemonicKey("count", {
        defaultValue: 0,
    });

    return (
        <div>
            <p>Count: {count}</p>
            <button onClick={() => set((c) => c + 1)}>Increment</button>
        </div>
    );
}

export default function App() {
    return (
        <MnemonicProvider namespace="my-app">
            <Counter />
        </MnemonicProvider>
    );
}
```

--------------------------------

### Define peer dependencies

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/getting-started/installation.md

Configuration snippet for package.json to specify required React versions for the library.

```json
{
    "peerDependencies": {
        "react": ">=18",
        "react-dom": ">=18"
    }
}
```

--------------------------------

### Install react-mnemonic

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/README.md

Installs the react-mnemonic package using npm. React 18 or later is a prerequisite for using this package.

```bash
npm install react-mnemonic
```

--------------------------------

### SessionStorage Example for Custom Storage

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/custom-storage.md

Shows how to use the built-in sessionStorage object as a custom storage backend for react-mnemonic. This is suitable for session-scoped persistence needs.

```jsx
<MnemonicProvider namespace="session" storage={sessionStorage}>
    <App />
</MnemonicProvider>
```

--------------------------------

### IndexedDB with BroadcastChannel Example for Custom Storage

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/custom-storage.md

Demonstrates a custom storage implementation using IndexedDB for durability and BroadcastChannel for cross-tab synchronization. This pattern maintains a synchronous interface for react-mnemonic while handling asynchronous operations in the background.

```tsx
import { MnemonicProvider } from "react-mnemonic";
import type { StorageLike } from "react-mnemonic";

const idbStorage: StorageLike = {
    getItem: (key) => {
        // synchronous read from an in-memory cache
        // populated from IndexedDB on startup
        return cache.get(key) ?? null;
    },
    setItem: (key, value) => {
        cache.set(key, value);
        // async write to IDB in background
        idb.put("store", value, key);
    },
    removeItem: (key) => {
        cache.delete(key);
        idb.delete("store", key);
    },
    onExternalChange: (cb) => {
        const bc = new BroadcastChannel("my-app-sync");
        bc.onmessage = (e) => cb(e.data.keys);
        return () => bc.close();
    },
};

function App() {
    return (
        <MnemonicProvider namespace="my-app" storage={idbStorage}> 
            {/* components */}
        </MnemonicProvider>
    );
}
```

--------------------------------

### Implement Persistent Shopping Cart with react-mnemonic

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/static/llms-full.txt

This example demonstrates a shopping cart implementation that persists state across reloads and browser tabs. It uses canonical line items to derive totals and item counts, while providing distinct methods for clearing versus removing the cart state.

```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>
    );
}
```

--------------------------------

### Structural Migration Helpers - TypeScript

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/schema-migration.md

Demonstrates using structural migration helpers like `insertChildIfMissing`, `renameNode`, and `dedupeChildrenBy` for complex tree-like data structures. This example migrates a 'layout' schema from version 2 to 3.

```typescript
type LayoutNode = {
    id: string;
    title: string;
    children?: LayoutNode[];
};

const layoutMigration: MigrationRule = {
    key: "layout",
    fromVersion: 2,
    toVersion: 3,
    migrate: (value) => {
        const layout = value as LayoutNode;
        return dedupeChildrenBy(
            renameNode(
                insertChildIfMissing(layout, "sidebar", {
                    id: "search",
                    title: "Search",
                }),
                "prefs",
                "preferences",
            ),
            (node) => node.id,
        );
    },
};

```

--------------------------------

### Reconciliation with Defaults - TypeScript

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/schema-migration.md

Illustrates using the `reconcile` option within `useMnemonicKey` to enforce newer application defaults or normalize fields after decoding and migration. This example adds a `marketingOptIn` field if it's missing or outdated.

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

--------------------------------

### Custom Structural Tree Adapter - TypeScript

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/schema-migration.md

Shows how to provide a custom `StructuralTreeHelpers` adapter when the data structure deviates from the default 'id' and 'children' fields. This example uses 'key' and 'nodes' for a 'WidgetNode' type.

```typescript
type WidgetNode = {
    key: string;
    label: string;
    nodes?: WidgetNode[];
};

const widgetTree: StructuralTreeHelpers<WidgetNode> = {
    getId: (node) => node.key,
    getChildren: (node) => node.nodes,
    withChildren: (node, children) => ({ ...node, nodes: children }),
    withId: (node, id) => ({ ...node, key: id }),
};

const migrated = renameNode(oldTree, "prefs", "preferences", widgetTree);
```

--------------------------------

### Basic Mnemonic Key Usage - TypeScript

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/canonical-key-definitions.md

A simple example demonstrating the basic usage of `useMnemonicKey` for a one-off persisted state. It shows how to declare a key with a default value and access its value and setter function directly.

```typescript
const { value, set } = useMnemonicKey("sidebarOpen", {
    defaultValue: false,
});
```

--------------------------------

### Integrate MnemonicProvider with Schema (JSX)

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/schema-migration.md

Demonstrates how to wire up the MnemonicProvider component in a React application. This component is essential for managing mnemonic data, providing the namespace, schema mode, and registry to its children. The example shows its usage with a ProfileEditor component.

```jsx
<MnemonicProvider namespace="app" schemaMode="default" schemaRegistry={registry}>
    <ProfileEditor />
</MnemonicProvider>
```

--------------------------------

### React Mnemonic End-To-End Example with Auth Scoping

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/auth-aware-persistence.md

This TypeScript React component demonstrates end-to-end usage of react-mnemonic for managing application state based on user authentication status. It utilizes hooks like `useMnemonicKey` and `useMnemonicRecovery` to handle scoped namespaces, temporary data, and cleanup logic. Dependencies include 'react' and 'react-mnemonic'.

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

type Session = { status: "anonymous" } | { status: "authenticated"; userId: string };

type SavedSearch = {
    query: string;
    tags: string[];
};

const AUTH_SCOPED_KEYS = ["saved-search", "private-draft"] as const;
const DEFAULT_SEARCH: SavedSearch = { query: "", tags: [] };
const ANONYMOUS_NAMESPACE = "my-app.anonymous";

function namespaceForSession(session: Session): string {
    return session.status === "authenticated" ? `my-app.user.${session.userId}` : ANONYMOUS_NAMESPACE;
}

function NamespaceCleanupBridge({ namespace, onComplete }: { namespace: string; onComplete: () => void }) {
    return (
        <MnemonicProvider namespace={namespace}>
            <NamespaceCleanupRunner onComplete={onComplete} />
        </MnemonicProvider>
    );
}

function NamespaceCleanupRunner({ onComplete }: { onComplete: () => void }) {
    const recovery = useMnemonicRecovery();

    useEffect(() => {
        recovery.clearKeys([...AUTH_SCOPED_KEYS]);
        onComplete();
    }, [onComplete, recovery]);

    return null;
}

function AuthScopedWorkspace({ isAuthenticated }: { isAuthenticated: boolean }) {
    const savedSearch = useMnemonicKey<SavedSearch>("saved-search", {
        defaultValue: DEFAULT_SEARCH,
        listenCrossTab: true,
        reconcile: (persisted) => (isAuthenticated ? persisted : DEFAULT_SEARCH),
    });

    const draft = useMnemonicKey<string>("private-draft", {
        defaultValue: "",
        listenCrossTab: true,
        reconcile: (persisted) => (isAuthenticated ? persisted : ""),
    });

    return (
        <>
            <input
                value={savedSearch.value.query}
                onChange={(event) =>
                    savedSearch.set((prev) => ({
                        ...prev,
                        query: event.target.value,
                    }))
                }
            />

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

            <button onClick={() => draft.remove()}>Discard private draft</button>
        </>
    );
}

export function AuthAwareApp({
    session,
    authEvents,
}: {
    session: Session;
    authEvents: {
        onExpired: (callback: () => void) => () => void;
        onLogout: (callback: () => void) => () => void;
    };
}) {
    const isAuthenticated = session.status === "authenticated";
    const lastAuthenticatedNamespace = useRef<string | null>(null);
    const [namespacePendingCleanup, setNamespacePendingCleanup] = useState<string | null>(null);
    const currentNamespace = namespaceForSession(session);

    useEffect(() => {
        if (session.status === "authenticated") {
            lastAuthenticatedNamespace.current = namespaceForSession(session);
        }
    }, [session]);

    useEffect(() => {
        const scheduleCleanup = () => {
            if (lastAuthenticatedNamespace.current) {
                setNamespacePendingCleanup(lastAuthenticatedNamespace.current);
            }
        };

        const unsubscribeExpired = authEvents.onExpired(scheduleCleanup);
        const unsubscribeLogout = authEvents.onLogout(scheduleCleanup);

        return () => {
            unsubscribeExpired();
            unsubscribeLogout();
        };
    }, [authEvents]);

    return (
        <>
            {namespacePendingCleanup ? (
                <NamespaceCleanupBridge
                    namespace={namespacePendingCleanup}
                    onComplete={() => {
                        lastAuthenticatedNamespace.current = null;
                        setNamespacePendingCleanup(null);
                    }}
                />
            ) : null}

            <MnemonicProvider namespace={currentNamespace}>
                <AuthScopedWorkspace isAuthenticated={isAuthenticated} />
            </MnemonicProvider>
        </>
    );
}

```

--------------------------------

### Use Custom Date Codec with useMnemonicKey (TypeScript)

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/custom-codecs.md

Shows how to integrate a custom codec, like `DateCodec`, into the `useMnemonicKey` hook. By passing the codec in the `codec` option, Mnemonic will use it for serialization and deserialization of the associated key's value. This example initializes the key with a default Date value.

```typescript
const { value, set } = useMnemonicKey<Date>("lastVisit", {
    defaultValue: new Date(),
    codec: DateCodec,
});

```

--------------------------------

### Implement Wizard Navigation and Provider

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/multi-step-form-wizards.md

Demonstrates the UI structure for a multi-step wizard including navigation buttons and the integration of the MnemonicProvider to manage the onboarding state.

```tsx
<button type="button" onClick={goBack} disabled={activeIndex <= 0 || isSubmitting}>
    Back
</button>

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

export function App() {
    return (
        <MnemonicProvider namespace="signup">
            <OnboardingWizard />
        </MnemonicProvider>
    );
}
```

--------------------------------

### Onboarding Wizard Implementation in React

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/multi-step-form-wizards.md

This TypeScript React component implements an onboarding wizard using the react-mnemonic library. It manages wizard state, step navigation, validation, and data persistence for an onboarding process. Dependencies include React hooks and the react-mnemonic library.

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

type StepId = "account" | "business" | "profile" | "plan" | "review";
type AccountType = "personal" | "business";
type Plan = "starter" | "growth";

type OnboardingDraft = {
    accountType: AccountType;
    companyName: string | null;
    fullName: string;
    email: string;
    teamSize: number;
    plan: Plan;
    acceptedTerms: boolean;
};

const onboardingDraftKey = defineMnemonicKey("onboarding-draft", {
    defaultValue: {
        accountType: "personal" as AccountType,
        companyName: null,
        fullName: "",
        email: "",
        teamSize: 1,
        plan: "starter" as Plan,
        acceptedTerms: false,
    },
    listenCrossTab: true,
});

const stepLabels: Record<StepId, string> = {
    account: "Account",
    business: "Business details",
    profile: "Profile",
    plan: "Plan",
    review: "Review",
};

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

function validateStep(stepId: StepId, draft: OnboardingDraft): string[] {
    switch (stepId) {
        case "account":
            return [];
        case "business":
            return draft.accountType === "business" && !draft.companyName?.trim()
                ? ["Company name is required for business accounts."]
                : [];
        case "profile": {
            const errors: string[] = [];
            if (!draft.fullName.trim()) {
                errors.push("Full name is required.");
            }
            if (!draft.email.includes("@")) {
                errors.push("Email must look valid.");
            }
            return errors;
        }
        case "plan":
            return draft.plan === "growth" && draft.teamSize < 3 ? ["Growth plan requires at least 3 seats."] : [];
        case "review":
            return draft.acceptedTerms ? [] : ["Accept the terms before submitting."];
    }
}

function validateAll(steps: StepId[], draft: OnboardingDraft): Partial<Record<StepId, string[]>> {
    return steps.reduce<Partial<Record<StepId, string[]>>>((errorsByStep, stepId) => {
        const errors = validateStep(stepId, draft);
        if (errors.length > 0) {
            errorsByStep[stepId] = errors;
        }
        return errorsByStep;
    }, {});
}

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

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

function OnboardingWizard() {
    const { value: draft, set: setDraft, remove: removeDraft } = useMnemonicKey(onboardingDraftKey);
    const steps = getSteps(draft);
    const [activeStepId, setActiveStepId] = useState<StepId>("account");
    const [stepErrors, setStepErrors] = useState<Partial<Record<StepId, string[]>>>({});
    const [submissionError, setSubmissionError] = useState<string | null>(null);
    const [isSubmitting, setIsSubmitting] = useState(false);

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

    const activeIndex = steps.indexOf(activeStepId);
    const currentErrors = stepErrors[activeStepId] ?? [];
    const completedSteps = steps.filter((stepId) => validateStep(stepId, draft).length === 0);

    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 OnboardingDraft>(field: K, value: OnboardingDraft[K]) => {
        setDraft((prev) => ({ ...prev, [field]: value }));
        setStepErrors((prev) => ({ ...prev, [activeStepId]: [] }));
        setSubmissionError(null);
    };

    const updateAccountType = (accountType: AccountType) => {
        setDraft((prev) => ({
            ...prev,
            accountType,
            companyName: accountType === "business" ? prev.companyName : null,

```

--------------------------------

### Initialize useMnemonicKey with default values

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/server-rendering.md

Demonstrates the default behavior of useMnemonicKey where the server renders the defaultValue and the client hydrates it before checking persisted storage.

```typescript
const { value } = useMnemonicKey("theme", {
    defaultValue: "light" as "light" | "dark",
});
```

--------------------------------

### Define nullable schema

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/clearable-persisted-values.mdx

Example of a JSON schema configuration that allows both string values and null for persisted keys.

```ts
{
    type: ["string", "null"];
}
```

--------------------------------

### Mnemonic Hook Return Object Signature

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/getting-started/quick-start.md

The useMnemonicKey hook returns an object containing the current value and methods to manage the persisted state, including updating, resetting, and removing the key.

```ts
const { value, set, reset, remove } = useMnemonicKey<T>(key, options);
```

--------------------------------

### Implement Multi-Step Wizard with Durable State using React Mnemonic

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/static/llms-full.txt

This component demonstrates a multi-step signup process where form data is persisted using the useMnemonicKey hook. It features dynamic step navigation based on user input, field-level validation, and a final submission handler that clears the persisted state.

```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}
        </>
    );
}
```

--------------------------------

### Define Versioned Schemas and Migrations

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/multi-step-form-wizards.md

Shows how to define versioned schemas for the wizard draft and implement migration logic to handle structural changes in the persisted data over time.

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

const onboardingDraftV1 = defineKeySchema(
    "onboarding-draft",
    1,
    mnemonicSchema.object({
        accountType: mnemonicSchema.enum(["personal", "business"] as const),
        companyName: mnemonicSchema.nullable(mnemonicSchema.string()),
        fullName: mnemonicSchema.string(),
        email: mnemonicSchema.string(),
        teamSize: mnemonicSchema.number(),
        plan: mnemonicSchema.enum(["starter", "growth"] as const),
        acceptedTerms: mnemonicSchema.boolean(),
    }),
);

const onboardingDraftV2 = defineKeySchema(
    "onboarding-draft",
    2,
    mnemonicSchema.object({
        accountType: mnemonicSchema.enum(["personal", "business"] as const),
        companyName: mnemonicSchema.nullable(mnemonicSchema.string()),
        workspaceName: mnemonicSchema.string(),
        fullName: mnemonicSchema.string(),
        email: mnemonicSchema.string(),
        teamSize: mnemonicSchema.number(),
        plan: mnemonicSchema.enum(["starter", "growth"] as const),
        acceptedTerms: mnemonicSchema.boolean(),
    }),
);

const registry = createSchemaRegistry({
    schemas: [onboardingDraftV1, onboardingDraftV2],
    migrations: [
        defineMigration(onboardingDraftV1, onboardingDraftV2, (value) => {
            const draft = value as any;
            return {
                ...draft,
                workspaceName: draft.companyName ?? `${draft.fullName}'s workspace`,
            };
        }),
    ],
});

export function App() {
    return (
        <MnemonicProvider namespace="signup" schemaRegistry={registry}>
            <OnboardingWizard />
        </MnemonicProvider>
    );
}
```

--------------------------------

### Implement Theme Preference With Cross-Tab Sync in React

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/ai/recipes.md

Demonstrates how to synchronize theme state across multiple browser tabs using defineMnemonicKey with the listenCrossTab option enabled.

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

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

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

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

--------------------------------

### Define Key Schemas - TypeScript

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/schema-migration.md

Defines an array of KeySchema objects, specifying the structure and version for different data keys. This example shows two versions for a 'profile' key, with version 2 adding a 'migratedAt' field.

```typescript
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"],
        },
    },
];
```

--------------------------------

### Configure SSR Placeholder for Theme Hydration

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/ai/recipes.md

Shows how to configure useMnemonicKey for server-side rendering scenarios. This ensures the server-provided value is used initially and prevents hydration mismatches until the client mounts.

```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>;
}
```

--------------------------------

### Define Migration Rules - TypeScript

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/schema-migration.md

Defines an array of MigrationRule objects to specify how to transform data between schema versions. This example shows a migration from version 1 to version 2 of the 'profile' schema, adding the 'migratedAt' timestamp.

```typescript
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() };
        },
    },
];

const registry = createSchemaRegistry({
    schemas,
    migrations,
});
```

--------------------------------

### Using defineMnemonicKey for descriptor inference

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/typescript.md

Demonstrates how to package key contracts into reusable objects while preserving inferred value types.

```typescript
import { defineMnemonicKey, useMnemonicKey } from "react-mnemonic";

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

const { value, set } = useMnemonicKey(themeKey);
```

--------------------------------

### Importing react-mnemonic types

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/typescript.md

Demonstrates how to import public types and helper functions from the react-mnemonic package root.

```typescript
import type {
    Codec,
    StorageLike,
    MnemonicKeyDescriptor,
    TypedJsonSchema,
    InferJsonSchemaValue,
    MnemonicProviderOptions,
    MnemonicProviderProps,
    UseMnemonicKeyOptions,
    KeySchema,
    MigrationRule,
    MigrationPath,
    SchemaRegistry,
    StructuralTreeHelpers,
    SchemaMode,
    JsonSchema,
    JsonSchemaType,
    JsonSchemaValidationError,
    CompiledValidator,
} from "react-mnemonic";
```

--------------------------------

### Use useMnemonicRecovery Hook for Reset Flows

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/reset-and-recovery.md

Demonstrates the basic API shape of the `useMnemonicRecovery` hook, including namespace enumeration, clearing specific keys, clearing matching keys, and clearing all persisted state. It also shows how to handle recovery events.

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

function RecoveryMenu() {
    const { namespace, canEnumerateKeys, listKeys, clearAll, clearKeys, clearMatching } = useMnemonicRecovery({
        onRecover: (event) => {
            console.info("Recovery action", event.action, event.namespace, event.clearedKeys);
        },
    });

    return (
        <div>
            <p>Namespace: {namespace}</p>
            <p>Keys: {canEnumerateKeys ? listKeys().join(", ") : "manual list required"}</p>
            <button onClick={() => clearMatching((key) => key.startsWith("filters."))}>Clear filters</button>
            <button onClick={() => clearAll()}>Reset all persisted state</button>
        </div>
    );
}
```

--------------------------------

### Integrate MnemonicProvider in Next.js

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/server-rendering.md

Shows how to wrap an application with MnemonicProvider in a Next.js client component and pass server-derived data to the hook.

```typescript
// app/providers.tsx
"use client";
import { MnemonicProvider } from "react-mnemonic";

export function Providers({ children }: { children: React.ReactNode }) {
    return <MnemonicProvider namespace="app">{children}</MnemonicProvider>;
}

// app/theme-toggle.tsx
"use client";
import { useMnemonicKey } from "react-mnemonic";

export function ThemeToggle({ serverTheme }: { serverTheme: "light" | "dark" | "system" }) {
    const { value, set } = useMnemonicKey("theme", {
        defaultValue: "light",
        ssr: {
            serverValue: serverTheme,
        },
    });
    return <button onClick={() => set(value === "dark" ? "light" : "dark")}>{value}</button>;
}
```

--------------------------------

### Handling Non-Enumerable Custom Storage with react-mnemonic

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/reset-and-recovery.md

Illustrates the limitations and patterns for using `react-mnemonic` with custom storage backends that do not support key enumeration. In such cases, `clearAll()` and `clearMatching()` will throw errors, and `clearKeys([...])` must be used with an explicit list of durable keys.

```ts
interface CustomStorage {
    getItem(key: string): string | null;
    setItem(key: string, value: string): void;
    removeItem(key: string): void;
}
```

--------------------------------

### Multi-Step Wizard Component with Durable Draft (React)

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/ai/recipes.md

Implements a multi-step signup wizard using React and the `useMnemonicKey` hook from `react-mnemonic`. It manages form state, validation, and navigation between steps, persisting draft data.

```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
                        type="email"
                        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)}
                    />
                    I accept the terms and conditions.
                </label>
            ) : null}

            {stepErrors[activeStepId]?.map((error) => (
                <p key={error} style={{ color: "red" }}>
                    {error}
                </p>
            ))}

            <div>
                {activeIndex > 0 && <button onClick={goBack}>Back</button>}
                {activeIndex < steps.length - 1 && (
                    <button onClick={goNext}>Next</button>
                )}
                {activeIndex === steps.length - 1 && (
                    <button onClick={handleSubmit} disabled={isSubmitting}>
                        {isSubmitting ? "Submitting..." : "Submit"}
                    </button>
                )}
            </div>
        </>
    );
}

```

--------------------------------

### Iterate Over Multiple Mnemonic Providers

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/devtools.md

Demonstrates how to list all registered providers and iterate through them to access their respective namespaces and data.

```javascript
const providers = __REACT_MNEMONIC_DEVTOOLS__.list();
for (const provider of providers) {
    const api = __REACT_MNEMONIC_DEVTOOLS__.resolve(provider.namespace);
    console.log(provider.namespace, provider.available, api?.dump());
}
```

--------------------------------

### Handle Onboarding Form Submission in React

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/multi-step-form-wizards.md

The handleSubmit function validates the current draft against defined steps, manages loading states, and executes the onboarding submission. It handles errors by updating the UI and navigating to the first invalid step if validation fails.

```javascript
const handleSubmit = async () => {
    const errorsByStep = validateAll(steps, draft);
    if (Object.keys(errorsByStep).length > 0) {
        setStepErrors(errorsByStep);
        const firstInvalidStep = steps.find((stepId) => errorsByStep[stepId]?.length);
        if (firstInvalidStep) {
            setActiveStepId(firstInvalidStep);
        }
        return;
    }

    setIsSubmitting(true);
    setSubmissionError(null);

    try {
        await submitOnboarding(draft);
        removeDraft();
        setActiveStepId("account");
    } catch (error) {
        setSubmissionError(error instanceof Error ? error.message : "Could not finish onboarding.");
    } finally {
        setIsSubmitting(false);
    }
};
```

--------------------------------

### Recovery Telemetry with useMnemonicRecovery

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/reset-and-recovery.md

Shows how to integrate recovery telemetry using the `onRecover` callback provided by `useMnemonicRecovery`. This allows tracking recovery actions, affected namespaces, and cleared keys for analytics.

```tsx
const recovery = useMnemonicRecovery({
    onRecover: ({ action, namespace, clearedKeys }) => {
        analytics.track("mnemonic_recovery", {
            action,
            namespace,
            clearedKeys,
        });
    },
});
```

--------------------------------

### React Form Wizard UI Logic

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/ai/recipes.md

This React code snippet demonstrates the UI logic for a multi-step form wizard. It conditionally renders input fields and buttons based on the active step (`activeStepId`). It utilizes draft state (`draft`) and functions like `updateDraft`, `goBack`, `goNext`, and `handleSubmit` to manage user input and navigation. The UI also includes submission state (`isSubmitting`) and basic navigation guards.

```jsx
/>
            ) : 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>
            )}
        </>
    );
}
```
```

--------------------------------

### Implement Custom Backend Cross-Tab Sync with BroadcastChannel

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/cross-tab-sync.md

Demonstrates implementing cross-tab synchronization for custom storage backends, such as IndexedDB. It utilizes the `onExternalChange` method and the BroadcastChannel API to communicate changes between tabs.

```ts
const idbStorage: StorageLike = {
    // ... getItem, setItem, removeItem ...
    onExternalChange: (cb) => {
        const bc = new BroadcastChannel("my-app-sync");
        bc.onmessage = (e) => cb(e.data.keys);
        return () => bc.close();
    },
};
```

--------------------------------

### Implement Auth-Aware Namespace Strategy

Source: https://github.com/thirtytwobits/react-mnemonic/blob/main/website/docs/guides/auth-aware-persistence.md

Demonstrates how to dynamically scope the MnemonicProvider namespace based on the user's authentication status. This ensures that persisted data is isolated to specific user IDs, preventing cross-user data contamination.

```tsx
import type { ReactNode } from "react";
import { MnemonicProvider } from "react-mnemonic";

type Session = { status: "anonymous" } | { status: "authenticated"; userId: string };

function AppPersistenceBoundary({ session, children }: { session: Session; children: ReactNode }) {
    const namespace = session.status === "authenticated" ? `my-app.user.${session.userId}` : "my-app.anonymous";

    return <MnemonicProvider namespace={namespace}>{children}</MnemonicProvider>;
}
```
Tokens:
Raw