react-mnemonic 0.1.1-alpha.0 → 1.1.0-beta0

package/README.md

@@ -3,32 +3,44 @@
 Persistent, type-safe state management for React.
 
 [![npm version](https://img.shields.io/npm/v/react-mnemonic.svg)](https://www.npmjs.com/package/react-mnemonic)
-[![bundle size](https://img.shields.io/bundlephobia/minzip/react-mnemonic)](https://bundlephobia.com/package/react-mnemonic)
+[![docs](https://img.shields.io/badge/docs-online-0A7EA4.svg)](https://thirtytwobits.github.io/react-mnemonic/)
+[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=thirtytwobits_react-mnemonic&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=thirtytwobits_react-mnemonic)
+[![dependencies](https://img.shields.io/badge/dependencies-0-success.svg)](https://www.npmjs.com/package/react-mnemonic)
 [![license](https://img.shields.io/npm/l/react-mnemonic.svg)](./LICENSE.md)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
 
-> **⚠️ Alpha Software** — This library is in active development. APIs may
-> change between releases without prior notice. Use in production at your own
-> risk.
-
----
-
 **react-mnemonic** gives your React components persistent memory. Values survive
 page refreshes, synchronize across tabs, and stay type-safe end-to-end -- all
 through a single hook that works like `useState`.
 
+`1.1.0-beta0` is the current prerelease on the npm `latest` dist-tag. This minor
+`beta0` cut lands ahead of the `beta1` stabilization milestone, which is
+expected to receive only fixes and polish before the first production release.
+
+If you are evaluating alternatives, see the
+[Comparison Guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/comparisons-and-benchmarks).
+It publishes reproducible bundle measurements, an AI-friendliness benchmark
+built around one-shot app-building prompts, and controlled SSR/API tradeoff
+notes for `react-mnemonic`, Zustand persist, Jotai `atomWithStorage`,
+`use-local-storage-state`, and `usehooks-ts`.
+
 ## Features
 
 - **`useState`-like API** -- `useMnemonicKey` returns `{ value, set, reset, remove }`
 - **JSON Schema validation** -- optional schema-based validation using a built-in JSON Schema subset
 - **Namespace isolation** -- `MnemonicProvider` prefixes every key to prevent collisions
 - **Cross-tab sync** -- opt-in `listenCrossTab` uses the browser `storage` event
-- **Pluggable storage** -- bring your own backend via the `StorageLike` interface (IndexedDB, sessionStorage, etc.)
+- **Pluggable storage** -- use `localStorage`, `sessionStorage`, or a synchronous `StorageLike` facade over custom persistence
 - **Schema versioning and migration** -- upgrade stored data with versioned schemas and migration rules
+- **Typed schema cohesion helpers** -- define one schema object and reuse it across runtime validation, key descriptors, and migrations
+- **Structural migration helpers** -- optional tree utilities for idempotent insert/rename/dedupe migration steps
+- **Read-time reconciliation** -- selectively enforce new defaults on persisted values without clearing the whole key
+- **Recovery helpers** -- build user-facing soft reset and hard reset flows with namespace-scoped clear helpers
 - **Write-time normalization** -- migrations where `fromVersion === toVersion` run on every write
+- **First-class key descriptors** -- define canonical, reusable key contracts once with `defineMnemonicKey(...)`
 - **Lifecycle callbacks** -- `onMount` and `onChange` hooks
 - **DevTools** -- inspect and mutate state from the browser console
-- **SSR-safe** -- returns defaults when `window` is unavailable
+- **SSR-safe with explicit controls** -- defaults to `defaultValue` on the server, with optional `ssr.serverValue` and `client-only` hydration
 - **Tree-shakeable, zero dependencies** -- ships ESM + CJS with full TypeScript declarations
 
 ## Installation
@@ -47,7 +59,8 @@ pnpm add react-mnemonic
 
 ### Peer dependencies
 
-React 18 or later is required.
+React 18 or later is required. CI verifies packaged-consumer installs against
+React 18 and React 19.
 
 ```json
 {
@@ -90,6 +103,173 @@ export default function App() {
 The counter value persists in `localStorage` under the key `my-app.count` and
 survives full page reloads.
 
+In server-rendered apps, `useMnemonicKey(...)` renders `defaultValue` on the
+server by default and then hydrates to persisted storage on the client. When
+you need a deterministic server placeholder or want to delay storage reads
+until after mount, use `ssr.serverValue` and `ssr.hydration: "client-only"`.
+See the
+[Server Rendering guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/server-rendering)
+for Next.js and Remix examples.
+
+If the same key is used in multiple components, consider defining it once with
+`defineMnemonicKey(...)` and reusing that descriptor everywhere. This keeps the
+contract importable and explicit for both humans and AI-assisted tooling.
+
+For a deterministic implementation reference aimed at AI agents and advanced
+users, see the
+[AI docs overview](https://thirtytwobits.github.io/react-mnemonic/docs/ai).
+The canonical agent-facing prose lives under
+[`website/docs/ai/`](https://github.com/thirtytwobits/react-mnemonic/tree/main/website/docs/ai),
+with compact retrieval surfaces published as
+[`llms.txt`](https://thirtytwobits.github.io/react-mnemonic/llms.txt),
+[`llms-full.txt`](https://thirtytwobits.github.io/react-mnemonic/llms-full.txt),
+and
+[`ai-contract.json`](https://thirtytwobits.github.io/react-mnemonic/ai-contract.json).
+Agents should import published types from `react-mnemonic` and must not invent
+local `.d.ts` shims for the package.
+
+If you need evidence for where `react-mnemonic` is heavier, more explicit, or
+better suited to SSR-sensitive persistence than lighter hooks, see the
+[Comparison Guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/comparisons-and-benchmarks).
+
+Persist only the durable slice of your app state. `useMnemonicKey` stores
+whatever you pass to `set`, so keep transient UI state like loading flags,
+hover state, and draft search text in plain React state unless you explicitly
+want them to rehydrate after reload. See the
+[Persisted vs Ephemeral State guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/persisted-vs-ephemeral-state)
+for patterns and an interactive example.
+
+For self-service recovery UX, pair your per-key hooks with
+`useMnemonicRecovery` so users can clear stale filters, reset broken settings,
+or fully wipe a namespace without opening DevTools. See the
+[Reset and Recovery guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/reset-and-recovery)
+for soft-reset and hard-reset recipes.
+
+If a field must stay cleared across reloads, model it as nullable and persist
+`null` explicitly. `remove()` deletes the key and falls back to `defaultValue`,
+while `reset()` writes the default again. See the
+[Clearable Persisted Values guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/clearable-persisted-values)
+for the canonical nullable pattern.
+
+## Canonical key definitions
+
+When the same persisted key appears in more than one component, define it once
+and reuse it:
+
+```tsx
+import { defineMnemonicKey, useMnemonicKey } from "react-mnemonic";
+
+export const themeKey = defineMnemonicKey("theme", {
+    defaultValue: "light" as "light" | "dark",
+    listenCrossTab: true,
+});
+
+function ThemeToggle() {
+    const { value: theme, set } = useMnemonicKey(themeKey);
+    return <button onClick={() => set(theme === "light" ? "dark" : "light")}>{theme}</button>;
+}
+
+function ThemePreview() {
+    const { value: theme } = useMnemonicKey(themeKey);
+    return <p>Current theme: {theme}</p>;
+}
+```
+
+Descriptors help with:
+
+- keeping one canonical key contract per persisted value
+- reusing the same `defaultValue`, `schema`, `codec`, and `reconcile` logic
+- making AI-assisted code generation and refactors less ambiguous
+
+The original lightweight form still works:
+
+```ts
+const { value, set } = useMnemonicKey("theme", {
+    defaultValue: "light" as "light" | "dark",
+});
+```
+
+## Single source of truth schemas
+
+If you want the same schema object to drive both runtime validation and
+TypeScript inference, use the typed schema helpers:
+
+```tsx
+import {
+    MnemonicProvider,
+    createSchemaRegistry,
+    defineKeySchema,
+    defineMnemonicKey,
+    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(),
+    }),
+);
+
+const profileKey = defineMnemonicKey(profileV2, {
+    defaultValue: { name: "", email: "" },
+    reconcile: (value) => ({
+        ...value,
+        email: value.email.trim().toLowerCase(),
+    }),
+});
+
+const registry = createSchemaRegistry({
+    schemas: [profileV1, profileV2],
+    migrations: [
+        defineMigration(profileV1, profileV2, (value) => ({
+            ...value,
+            email: "",
+        })),
+    ],
+});
+
+function ProfileForm() {
+    const { value: profile, set } = useMnemonicKey(profileKey);
+    return <button onClick={() => set({ ...profile, email: "hello@example.com" })}>Save</button>;
+}
+
+export default function App() {
+    return (
+        <MnemonicProvider namespace="my-app" schemaMode="default" schemaRegistry={registry}>
+            <ProfileForm />
+        </MnemonicProvider>
+    );
+}
+```
+
+This path gives you:
+
+- one schema object reused in the registry, key descriptor, and migrations
+- inferred types for `defaultValue`, `value`, `set`, and `reconcile`
+- typed migration callbacks via `defineMigration(...)`
+
+Tradeoffs versus the lightweight JSON-only path:
+
+- more setup upfront
+- best fit when a key is schema-managed and long-lived
+- not necessary for simple keys where `defaultValue` inference is already enough
+
+For a side-by-side comparison against competing persistence libraries, including
+bundle-size measurements and qualitative SSR/API notes, see the
+[Comparison Guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/comparisons-and-benchmarks).
+
 ## API
 
 ### `<MnemonicProvider>`
@@ -110,11 +290,42 @@ Context provider that scopes storage keys under a namespace.
 
 Multiple providers with different namespaces can coexist in the same app.
 
-### `useMnemonicKey<T>(key, options)`
+### `defineMnemonicKey(key, options)`
+
+Define a reusable descriptor for a single persisted key.
+
+```ts
+const themeKey = defineMnemonicKey("theme", {
+    defaultValue: "light" as "light" | "dark",
+    listenCrossTab: true,
+});
+```
+
+The returned descriptor can be imported and passed directly to `useMnemonicKey`.
+
+### `mnemonicSchema`, `defineKeySchema`, and `defineMigration`
+
+Use these helpers when you want a schema-managed key to have one source of
+truth for runtime validation and TypeScript inference.
+
+```ts
+const themeSchema = defineKeySchema("theme", 1, mnemonicSchema.enum(["light", "dark"] as const));
+
+const themeKey = defineMnemonicKey(themeSchema, {
+    defaultValue: "light",
+});
+```
+
+`defineMigration(fromSchema, toSchema, migrate)` infers the migration callback
+from the source and target schemas, while `defineWriteMigration(schema, migrate)`
+creates a typed same-version normalizer.
+
+### `useMnemonicKey<T>(descriptor)` / `useMnemonicKey<T>(key, options)`
 
 Hook for reading and writing a single persistent value.
 
 ```ts
+const { value, set, reset, remove } = useMnemonicKey(themeKey);
 const { value, set, reset, remove } = useMnemonicKey<T>(key, options);
 ```
 
@@ -125,16 +336,48 @@ const { value, set, reset, remove } = useMnemonicKey<T>(key, options);
 | `reset`  | `() => void`                         | Reset to `defaultValue` and persist it        |
 | `remove` | `() => void`                         | Delete the key from storage entirely          |
 
+For clearable fields, remember the semantic split:
+
+- `set(null)` persists a cleared value and stays cleared after reload
+- `remove()` deletes the key, so the next read falls back to `defaultValue`
+- `reset()` persists `defaultValue`
+
 #### Options
 
-| Option           | Type                                              | Default     | Description                                         |
-| ---------------- | ------------------------------------------------- | ----------- | --------------------------------------------------- |
-| `defaultValue`   | `T \| ((error?: CodecError \| SchemaError) => T)` | _required_  | Fallback value or error-aware factory               |
-| `codec`          | `Codec<T>`                                        | `JSONCodec` | Encode/decode strategy (bypasses schema validation) |
-| `onMount`        | `(value: T) => void`                              | --          | Called once with the initial value                  |
-| `onChange`       | `(value: T, prev: T) => void`                     | --          | Called on every value change                        |
-| `listenCrossTab` | `boolean`                                         | `false`     | Sync via the browser `storage` event                |
-| `schema`         | `{ version?: number }`                            | --          | Pin writes to a specific schema version             |
+| Option           | Type                                              | Default     | Description                                                   |
+| ---------------- | ------------------------------------------------- | ----------- | ------------------------------------------------------------- |
+| `defaultValue`   | `T \| ((error?: CodecError \| SchemaError) => T)` | _required_  | Fallback value or error-aware factory                         |
+| `codec`          | `Codec<T>`                                        | `JSONCodec` | Encode/decode strategy (bypasses schema validation)           |
+| `reconcile`      | `(value: T, context: ReconcileContext) => T`      | --          | Adjust a persisted value after read and persist if it changes |
+| `onMount`        | `(value: T) => void`                              | --          | Called once with the initial value                            |
+| `onChange`       | `(value: T, prev: T) => void`                     | --          | Called on every value change                                  |
+| `listenCrossTab` | `boolean`                                         | `false`     | Sync via the browser `storage` event                          |
+| `schema`         | `{ version?: number }`                            | --          | Pin writes to a specific schema version                       |
+
+### `useMnemonicRecovery(options)`
+
+Hook for namespace-scoped recovery actions such as "clear saved filters" or
+"reset all persisted app data".
+
+```ts
+const { namespace, canEnumerateKeys, listKeys, clearAll, clearKeys, clearMatching } = useMnemonicRecovery({
+    onRecover: (event) => console.log(event.action, event.clearedKeys),
+});
+```
+
+| Return             | Type                                                | Description                                           |
+| ------------------ | --------------------------------------------------- | ----------------------------------------------------- |
+| `namespace`        | `string`                                            | Current provider namespace                            |
+| `canEnumerateKeys` | `boolean`                                           | Whether the storage backend can list namespace keys   |
+| `listKeys`         | `() => string[]`                                    | List visible unprefixed keys in the current namespace |
+| `clearAll`         | `() => string[]`                                    | Clear every key in the namespace                      |
+| `clearKeys`        | `(keys: readonly string[]) => string[]`             | Clear an explicit set of unprefixed keys              |
+| `clearMatching`    | `(predicate: (key: string) => boolean) => string[]` | Clear keys whose names match a predicate              |
+
+`clearAll()` and `clearMatching()` require an enumerable storage backend such
+as `localStorage` or `sessionStorage`. If your custom storage does not support
+`length` and `key(index)`, use `clearKeys([...])` with the explicit durable-key
+list your app owns.
 
 ### Codecs
 
@@ -169,9 +412,18 @@ interface StorageLike {
 }
 ```
 
+`StorageLike` is intentionally synchronous in v1 because Mnemonic's core
+store is built on React's synchronous snapshot contract. Async backends are
+still possible, but they need a synchronous facade: keep an in-memory cache for
+`getItem`/`setItem`/`removeItem`, then flush to IndexedDB or another async
+system outside the hook contract. Promise-returning `StorageLike` methods are
+unsupported and are treated as a storage misuse fallback at runtime.
+
 `onExternalChange` enables cross-tab sync for non-localStorage backends (e.g.
 IndexedDB over `BroadcastChannel`). The library handles all error cases
 internally -- see the `StorageLike` JSDoc for the full error-handling contract.
+Namespace-wide recovery helpers can only enumerate keys when the backend also
+implements `length` and `key(index)`.
 
 ### `validateJsonSchema(schema, value)`
 
@@ -318,84 +570,109 @@ const normalizer: MigrationRule = {
 };
 ```
 
+### Reconciliation
+
+Use `reconcile` when you want to keep persisted data but selectively enforce
+new application defaults after the value has been decoded and any read-time
+migrations have already run.
+
+```ts
+const { value } = useMnemonicKey("preferences", {
+    defaultValue: { theme: "dark", density: "comfortable", accents: true },
+    reconcile: (persisted, { persistedVersion }) => ({
+        ...persisted,
+        accents: persistedVersion === 0 ? true : persisted.accents,
+    }),
+});
+```
+
+Use a schema migration when the stored shape must move from one explicit version
+to another. Use `reconcile` for conditional, field-level policy changes such as
+rolling out a new default while preserving the rest of a user's stored data.
+
+### Structural migration helpers
+
+For layout-like data that already uses `id` and `children`, Mnemonic ships
+optional pure helpers for common idempotent migration steps:
+
+```ts
+import { insertChildIfMissing, renameNode, dedupeChildrenBy } from "react-mnemonic";
+
+const migrated = dedupeChildrenBy(
+    renameNode(insertChildIfMissing(layout, "sidebar", { id: "search", title: "Search" }), "prefs", "preferences"),
+    (node) => node.id,
+);
+```
+
+Use these inside your `MigrationRule.migrate` functions when you want repeatable
+tree edits without hand-writing the same traversal logic each time. See the
+[Schema Migration guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/schema-migration)
+for a cookbook example and custom adapter usage.
+
 ### Example schema registry
 
 A schema registry stores versioned schemas for each key, and resolves migration
-paths to upgrade stored data. Schemas are plain JSON (serializable); migrations
-are procedural functions.
+paths to upgrade stored data. For the common immutable case, use
+`createSchemaRegistry(...)` instead of hand-rolling the indexing boilerplate.
 
 ```tsx
 import {
+    createSchemaRegistry,
     MnemonicProvider,
     useMnemonicKey,
-    type SchemaRegistry,
     type KeySchema,
     type MigrationRule,
 } from "react-mnemonic";
 
-const schemas = new Map<string, KeySchema>();
-const migrations: MigrationRule[] = [];
-
-const registry: SchemaRegistry = {
-    getSchema: (key, version) => schemas.get(`${key}:${version}`),
-    getLatestSchema: (key) =>
-        Array.from(schemas.values())
-            .filter((schema) => schema.key === key)
-            .sort((a, b) => b.version - a.version)[0],
-    getMigrationPath: (key, fromVersion, toVersion) => {
-        const byKey = migrations.filter((rule) => rule.key === key);
-        const path: MigrationRule[] = [];
-        let cur = fromVersion;
-        while (cur < toVersion) {
-            const next = byKey.find((rule) => rule.fromVersion === cur);
-            if (!next) return null;
-            path.push(next);
-            cur = next.toVersion;
-        }
-        return path;
-    },
-    getWriteMigration: (key, version) => {
-        return migrations.find((r) => r.key === key && r.fromVersion === version && r.toVersion === version);
-    },
-    registerSchema: (schema) => {
-        const id = `${schema.key}:${schema.version}`;
-        if (schemas.has(id)) throw new Error(`Schema already registered for ${id}`);
-        schemas.set(id, schema);
+const schemas: KeySchema[] = [
+    {
+        key: "profile",
+        version: 1,
+        schema: {
+            type: "object",
+            properties: { name: { type: "string" }, email: { type: "string" } },
+            required: ["name", "email"],
+        },
     },
-};
-
-registry.registerSchema({
-    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"],
+        },
     },
-});
-
-migrations.push({
-    key: "profile",
-    fromVersion: 1,
-    toVersion: 2,
-    migrate: (value) => {
-        const v1 = value as { name: string; email: string };
-        return { ...v1, migratedAt: new Date().toISOString() };
+];
+
+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() };
+        },
     },
-});
-
-registry.registerSchema({
-    key: "profile",
-    version: 2,
-    schema: {
-        type: "object",
-        properties: {
-            name: { type: "string" },
-            email: { type: "string" },
-            migratedAt: { type: "string" },
+    {
+        key: "profile",
+        fromVersion: 2,
+        toVersion: 2,
+        migrate: (value) => {
+            const profile = value as { name: string; email: string; migratedAt: string };
+            return { ...profile, email: profile.email.trim().toLowerCase() };
         },
-        required: ["name", "email", "migratedAt"],
     },
+];
+
+const registry = createSchemaRegistry({
+    schemas,
+    migrations,
 });
 
 function ProfileEditor() {
@@ -410,6 +687,11 @@ function ProfileEditor() {
 </MnemonicProvider>;
 ```
 
+`createSchemaRegistry` validates duplicate schemas and ambiguous migration
+graphs up front. If you need runtime schema registration for
+`schemaMode="autoschema"`, keep a custom mutable `SchemaRegistry`
+implementation.
+
 ### Registry immutability
 
 In `default` and `strict` modes, the schema registry is treated as immutable for
@@ -425,22 +707,40 @@ version and remount the provider.
 import { MnemonicProvider } from "react-mnemonic";
 import type { StorageLike } from "react-mnemonic";
 
+const cache = new Map<string, string>();
+const queueIndexedDbWrite = (key: string, value: string) => {
+    // application-specific async persistence
+};
+const queueIndexedDbDelete = (key: string) => {
+    // application-specific async persistence
+};
+
 const idbStorage: StorageLike = {
-  getItem: (key) => /* read from IndexedDB */,
-  setItem: (key, value) => /* write to IndexedDB */,
-  removeItem: (key) => /* delete from IndexedDB */,
-  onExternalChange: (cb) => {
-    const bc = new BroadcastChannel("my-app-sync");
-    bc.onmessage = (e) => cb(e.data.keys);
-    return () => bc.close();
-  },
+    getItem: (key) => cache.get(key) ?? null,
+    setItem: (key, value) => {
+        cache.set(key, value);
+        queueIndexedDbWrite(key, value);
+    },
+    removeItem: (key) => {
+        cache.delete(key);
+        queueIndexedDbDelete(key);
+    },
+    onExternalChange: (cb) => {
+        const bc = new BroadcastChannel("my-app-sync");
+        bc.onmessage = (e) => cb(e.data.keys);
+        return () => bc.close();
+    },
 };
 
 <MnemonicProvider namespace="my-app" storage={idbStorage}>
-  <App />
-</MnemonicProvider>
+    <App />
+</MnemonicProvider>;
 ```
 
+If your real persistence layer is async, initialize that adapter before
+rendering the provider and return a synchronous `StorageLike` facade, like the
+IndexedDB demo in the docs site.
+
 ### DevTools
 
 Enable the console inspector in development:
@@ -452,12 +752,14 @@ Enable the console inspector in development:
 Then in the browser console:
 
 ```js
-__REACT_MNEMONIC_DEVTOOLS__.app.dump(); // table of all keys
-__REACT_MNEMONIC_DEVTOOLS__.app.get("theme"); // read a decoded value
-__REACT_MNEMONIC_DEVTOOLS__.app.set("theme", "dark"); // write
-__REACT_MNEMONIC_DEVTOOLS__.app.remove("theme"); // delete
-__REACT_MNEMONIC_DEVTOOLS__.app.keys(); // list all keys
-__REACT_MNEMONIC_DEVTOOLS__.app.clear(); // remove all keys
+const app = window.__REACT_MNEMONIC_DEVTOOLS__?.resolve("app");
+
+app?.dump(); // table of all keys
+app?.get("theme"); // read a decoded value
+app?.set("theme", "dark"); // write
+app?.remove("theme"); // delete
+app?.keys(); // list all keys
+app?.clear(); // remove all keys
 ```
 
 ## TypeScript
@@ -469,6 +771,7 @@ All public types are re-exported from the package root:
 import type {
     Codec,
     StorageLike,
+    MnemonicKeyDescriptor,
     MnemonicProviderOptions,
     MnemonicProviderProps,
     UseMnemonicKeyOptions,