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

package/dist/key-BvFvcKiR.d.cts

@@ -0,0 +1,1723 @@
+/**
+ * @fileoverview Codec implementations for encoding and decoding values to/from storage.
+ *
+ * This module provides the built-in JSON codec and a factory for creating custom
+ * codecs. Codecs handle the bidirectional transformation between typed JavaScript
+ * values and their string representations for storage.
+ *
+ * Codecs are a low-level mechanism for keys that opt out of the JSON Schema
+ * validation system. When a schema is registered for a key, the schema's
+ * JSON Schema is used for validation and the payload is stored as a JSON value
+ * directly (no codec encoding needed).
+ */
+
+/**
+ * Custom error class for codec encoding and decoding failures.
+ *
+ * Thrown when a codec cannot successfully encode a value to a string or
+ * decode a string back to its typed representation. This allows callers
+ * to distinguish codec errors from other types of errors.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const value = JSONCodec.decode('not-valid-json');
+ * } catch (error) {
+ *   if (error instanceof CodecError) {
+ *     console.error('Failed to decode:', error.message);
+ *   }
+ * }
+ * ```
+ */
+declare class CodecError extends Error {
+    /**
+     * The underlying error that caused the codec failure, if any.
+     *
+     * Useful for debugging when wrapping errors from JSON.parse or
+     * other parsing operations.
+     */
+    readonly cause?: unknown;
+    /**
+     * Creates a new CodecError.
+     *
+     * @param message - Human-readable error description
+     * @param cause - Optional underlying error that caused this failure
+     */
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * JSON codec for encoding and decoding JSON-serializable values.
+ *
+ * This is the default codec used by `useMnemonicKey` when no codec is specified.
+ * It uses `JSON.stringify` for encoding and `JSON.parse` for decoding, making it
+ * suitable for objects, arrays, and primitive values.
+ *
+ * @remarks
+ * - Supports any JSON-serializable type: objects, arrays, strings, numbers, booleans, null
+ * - Does not preserve JavaScript-specific types like Date, Map, Set, or undefined
+ * - Throws standard JSON parsing errors for malformed JSON strings
+ *
+ * @example
+ * ```typescript
+ * // Used automatically as the default
+ * const { value, set } = useMnemonicKey('userProfile', {
+ *   defaultValue: { name: 'Guest', preferences: { theme: 'dark' } }
+ *   // codec: JSONCodec is implicit
+ * });
+ *
+ * // Can be specified explicitly
+ * const { value, set } = useMnemonicKey('settings', {
+ *   defaultValue: { notifications: true },
+ *   codec: JSONCodec
+ * });
+ * ```
+ *
+ * @see {@link createCodec} - For custom encoding schemes
+ */
+declare const JSONCodec: Codec<any>;
+/**
+ * Factory function for creating custom codecs.
+ *
+ * Creates a `Codec<T>` from separate encode and decode functions. This is
+ * useful for implementing custom serialization strategies for types that
+ * aren't supported by JSONCodec. Using a custom codec on a key opts out
+ * of JSON Schema validation for that key.
+ *
+ * @template T - The TypeScript type of values to encode/decode
+ *
+ * @param encode - Function that converts a typed value to a string
+ * @param decode - Function that converts a string back to a typed value
+ * @returns A `Codec<T>` object compatible with useMnemonicKey
+ *
+ * @example
+ * ```typescript
+ * // Codec for Date objects
+ * const DateCodec = createCodec<Date>(
+ *   (date) => date.toISOString(),
+ *   (str) => new Date(str)
+ * );
+ *
+ * const { value, set } = useMnemonicKey('lastLogin', {
+ *   defaultValue: new Date(),
+ *   codec: DateCodec
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Codec for Set<string>
+ * const StringSetCodec = createCodec<Set<string>>(
+ *   (set) => JSON.stringify(Array.from(set)),
+ *   (str) => new Set(JSON.parse(str))
+ * );
+ *
+ * const { value, set } = useMnemonicKey('tags', {
+ *   defaultValue: new Set<string>(),
+ *   codec: StringSetCodec
+ * });
+ * ```
+ *
+ * @see {@link Codec} - The codec interface
+ * @see {@link CodecError} - Error to throw when encoding/decoding fails
+ * @see {@link JSONCodec} - Built-in codec for JSON values
+ */
+declare function createCodec<T>(encode: (value: T) => string, decode: (encoded: string) => T): Codec<T>;
+
+/**
+ * @fileoverview Schema versioning primitives for Mnemonic.
+ *
+ * This module defines the envelope format used to wrap every persisted value
+ * and the error class thrown when schema-related operations fail.
+ */
+/**
+ * Error thrown for schema registry, versioning, and migration failures.
+ *
+ * Each instance carries a machine-readable {@link code} that categorises
+ * the failure. When a `defaultValue` factory is provided to
+ * `useMnemonicKey`, the `SchemaError` is passed as the `error` argument
+ * so the factory can inspect the failure reason.
+ *
+ * Error codes:
+ *
+ * | Code                            | Meaning                                                         |
+ * | ------------------------------- | --------------------------------------------------------------- |
+ * | `INVALID_ENVELOPE`              | The raw stored value is not a valid `MnemonicEnvelope`.         |
+ * | `SCHEMA_NOT_FOUND`              | No schema registered for the stored key + version.              |
+ * | `WRITE_SCHEMA_REQUIRED`         | Strict mode requires a schema to write, but none was found.     |
+ * | `MIGRATION_PATH_NOT_FOUND`      | No contiguous migration path between the stored and latest version. |
+ * | `MIGRATION_FAILED`              | A migration step threw during execution.                        |
+ * | `MIGRATION_GRAPH_INVALID`       | The schema registry helper received an ambiguous or cyclic migration graph. |
+ * | `RECONCILE_FAILED`             | A read-time reconciliation hook threw or returned an unpersistable value. |
+ * | `SCHEMA_REGISTRATION_CONFLICT`  | `registerSchema` was called with a conflicting definition.      |
+ * | `TYPE_MISMATCH`                 | The decoded value failed JSON Schema validation.                |
+ * | `MODE_CONFIGURATION_INVALID`    | The schema mode requires a capability the registry doesn't provide. |
+ *
+ * @example
+ * ```typescript
+ * defaultValue: (error) => {
+ *   if (error instanceof SchemaError) {
+ *     console.warn(`Schema issue [${error.code}]:`, error.message);
+ *   }
+ *   return { name: "Guest" };
+ * }
+ * ```
+ *
+ * @see {@link SchemaMode} - How the provider uses schemas
+ * @see {@link SchemaRegistry} - Where schemas and migrations are registered
+ */
+declare class SchemaError extends Error {
+    /**
+     * Machine-readable code identifying the category of schema failure.
+     */
+    readonly code: "INVALID_ENVELOPE" | "SCHEMA_NOT_FOUND" | "WRITE_SCHEMA_REQUIRED" | "MIGRATION_PATH_NOT_FOUND" | "MIGRATION_FAILED" | "MIGRATION_GRAPH_INVALID" | "RECONCILE_FAILED" | "SCHEMA_REGISTRATION_CONFLICT" | "TYPE_MISMATCH" | "MODE_CONFIGURATION_INVALID";
+    /**
+     * The underlying error that caused this failure, if any.
+     */
+    readonly cause?: unknown;
+    /**
+     * Creates a new SchemaError.
+     *
+     * @param code - Machine-readable failure category
+     * @param message - Human-readable error description
+     * @param cause - Optional underlying error
+     */
+    constructor(code: SchemaError["code"], message: string, cause?: unknown);
+}
+
+/**
+ * @fileoverview JSON Schema subset validator for Mnemonic.
+ *
+ * This module implements a minimal JSON Schema validator sufficient for
+ * validating localStorage state. Only a subset of JSON Schema keywords
+ * are supported; see {@link JsonSchema} for the full list.
+ *
+ * JSON Schema documents are plain JSON objects (inherently serializable),
+ * making them suitable for storage alongside the data they describe.
+ */
+/**
+ * Supported JSON Schema type keywords.
+ *
+ * `"integer"` is a JSON Schema keyword meaning "a number that is a whole number."
+ */
+type JsonSchemaType = "string" | "number" | "integer" | "boolean" | "null" | "object" | "array";
+/**
+ * A subset of JSON Schema sufficient for localStorage state management.
+ *
+ * Supported keywords:
+ *   type, enum, const,
+ *   minimum, maximum, exclusiveMinimum, exclusiveMaximum,
+ *   minLength, maxLength,
+ *   properties, required, additionalProperties,
+ *   items, minItems, maxItems
+ *
+ * Deliberately omitted: $ref, $id, $schema, $defs, allOf, anyOf,
+ * oneOf, not, pattern, format, patternProperties, if/then/else,
+ * dependencies, uniqueItems, multipleOf, propertyNames.
+ *
+ * An empty schema `{}` accepts any value.
+ */
+interface JsonSchema {
+    /** The expected JSON type(s). An array form like `["string", "null"]` accepts either type. */
+    type?: JsonSchemaType | JsonSchemaType[];
+    /** The value must be deeply equal to one of these entries. */
+    enum?: readonly unknown[];
+    /** The value must be deeply equal to this exact value. */
+    const?: unknown;
+    /** Inclusive lower bound for numbers. */
+    minimum?: number;
+    /** Inclusive upper bound for numbers. */
+    maximum?: number;
+    /** Exclusive lower bound for numbers. */
+    exclusiveMinimum?: number;
+    /** Exclusive upper bound for numbers. */
+    exclusiveMaximum?: number;
+    /** Minimum string length (inclusive). */
+    minLength?: number;
+    /** Maximum string length (inclusive). */
+    maxLength?: number;
+    /** Property name to sub-schema mapping for objects. */
+    properties?: Record<string, JsonSchema>;
+    /** Properties that must be present on the object. */
+    required?: readonly string[];
+    /**
+     * Controls extra properties not listed in `properties`.
+     * `false` disallows them. A schema validates their values.
+     * `true` (or omitted) allows anything.
+     */
+    additionalProperties?: boolean | JsonSchema;
+    /** Schema applied to every element of an array. */
+    items?: JsonSchema;
+    /** Minimum array length (inclusive). */
+    minItems?: number;
+    /** Maximum array length (inclusive). */
+    maxItems?: number;
+}
+/**
+ * A single validation error produced by {@link validateJsonSchema}.
+ */
+type JsonSchemaValidationError = {
+    /** JSON Pointer path to the failing value (e.g., "/foo/bar/0"). Empty string for root. */
+    path: string;
+    /** Human-readable error description. */
+    message: string;
+    /** The JSON Schema keyword that failed. */
+    keyword: string;
+};
+/**
+ * A pre-compiled validation function generated by {@link compileSchema}.
+ *
+ * Accepts a value and an optional JSON Pointer path for error reporting.
+ * Returns an array of validation errors (empty = valid).
+ */
+type CompiledValidator = (value: unknown, path?: string) => JsonSchemaValidationError[];
+/**
+ * Pre-compiles a {@link JsonSchema} into a reusable validation function.
+ *
+ * Inspects the schema once and builds a specialized closure that
+ * eliminates runtime branching for unused keywords, pre-converts
+ * `required` arrays to `Set`s, recursively pre-compiles nested property
+ * and item schemas, and pre-builds primitive `Set`s for O(1) enum
+ * lookups when possible.
+ *
+ * Results are cached by schema object identity in a `WeakMap`, so
+ * calling `compileSchema` with the same schema reference is free
+ * after the first call.
+ *
+ * @param schema - The JSON Schema to compile
+ * @returns A compiled validation function
+ */
+declare function compileSchema(schema: JsonSchema): CompiledValidator;
+/**
+ * Validates a value against a {@link JsonSchema}.
+ *
+ * Returns an empty array when the value is valid.
+ * Returns one or more {@link JsonSchemaValidationError} entries on failure.
+ * Short-circuits on type mismatch (does not report downstream keyword errors).
+ *
+ * @param value - The value to validate
+ * @param schema - The JSON Schema to validate against
+ * @param path - Internal: JSON Pointer path for error reporting (default: `""`)
+ * @returns Array of validation errors (empty = valid)
+ */
+declare function validateJsonSchema(value: unknown, schema: JsonSchema, path?: string): JsonSchemaValidationError[];
+
+declare const typedSchemaBrand: unique symbol;
+declare const optionalSchemaBrand: unique symbol;
+type JsonPrimitive = string | number | boolean | null;
+type JsonConstValue = JsonPrimitive | readonly JsonConstValue[] | {
+    readonly [key: string]: JsonConstValue;
+};
+type TypedJsonSchema<T> = JsonSchema & {
+    readonly [typedSchemaBrand]?: T;
+};
+type OptionalTypedJsonSchema<T> = TypedJsonSchema<T> & {
+    readonly [optionalSchemaBrand]: true;
+};
+type InferJsonSchemaValue<TSchema> = TSchema extends TypedJsonSchema<infer TValue> ? TValue : unknown;
+type ObjectValueFromSchemas<TShape extends Record<string, TypedJsonSchema<unknown> | OptionalTypedJsonSchema<unknown>>> = {
+    [K in keyof TShape as TShape[K] extends OptionalTypedJsonSchema<unknown> ? never : K]: InferJsonSchemaValue<TShape[K]>;
+} & {
+    [K in keyof TShape as TShape[K] extends OptionalTypedJsonSchema<unknown> ? K : never]?: InferJsonSchemaValue<TShape[K]>;
+};
+type StringSchemaOptions = Pick<JsonSchema, "minLength" | "maxLength">;
+type NumberSchemaOptions = Pick<JsonSchema, "minimum" | "maximum" | "exclusiveMinimum" | "exclusiveMaximum">;
+type ArraySchemaOptions = Pick<JsonSchema, "minItems" | "maxItems">;
+type ObjectSchemaOptions = Pick<JsonSchema, "additionalProperties">;
+/**
+ * Builder helpers for strongly typed schemas backed by Mnemonic's built-in
+ * JSON Schema subset.
+ *
+ * The returned schemas are plain `JsonSchema` objects at runtime, so they can
+ * be registered directly in `createSchemaRegistry(...)` while also carrying a
+ * phantom TypeScript type for inference.
+ */
+declare const mnemonicSchema: {
+    string(options?: StringSchemaOptions): TypedJsonSchema<string>;
+    number(options?: NumberSchemaOptions): TypedJsonSchema<number>;
+    integer(options?: NumberSchemaOptions): TypedJsonSchema<number>;
+    boolean(): TypedJsonSchema<boolean>;
+    nullValue(): TypedJsonSchema<null>;
+    literal<const TValue extends JsonConstValue>(value: TValue): TypedJsonSchema<TValue>;
+    enum<const TValues extends readonly [JsonPrimitive, ...JsonPrimitive[]]>(values: TValues): TypedJsonSchema<TValues[number]>;
+    optional<T>(schema: TypedJsonSchema<T>): OptionalTypedJsonSchema<T>;
+    nullable<T>(schema: TypedJsonSchema<T>): TypedJsonSchema<T | null>;
+    array<TItemSchema extends TypedJsonSchema<unknown>>(itemSchema: TItemSchema, options?: ArraySchemaOptions): TypedJsonSchema<InferJsonSchemaValue<TItemSchema>[]>;
+    object<TShape extends Record<string, TypedJsonSchema<unknown> | OptionalTypedJsonSchema<unknown>>>(shape: TShape, options?: ObjectSchemaOptions): TypedJsonSchema<ObjectValueFromSchemas<TShape>>;
+    record<TValueSchema extends TypedJsonSchema<unknown>>(valueSchema: TValueSchema): TypedJsonSchema<Record<string, InferJsonSchemaValue<TValueSchema>>>;
+};
+
+/**
+ * @fileoverview Type definitions for the Mnemonic library.
+ *
+ * This module defines the core types and interfaces used throughout the Mnemonic
+ * library for type-safe, persistent state management in React applications.
+ */
+
+declare const keySchemaValueBrand: unique symbol;
+/**
+ * Codec for encoding and decoding values to and from storage.
+ *
+ * Codecs provide bidirectional transformations between typed values and their
+ * string representations suitable for storage in localStorage or similar backends.
+ *
+ * Using a codec on a key opts out of JSON Schema validation. Schema-managed
+ * keys store JSON values directly and are validated against their JSON Schema.
+ *
+ * @template T - The TypeScript type of the value to encode/decode
+ *
+ * @example
+ * ```typescript
+ * const DateCodec: Codec<Date> = {
+ *   encode: (date) => date.toISOString(),
+ *   decode: (str) => new Date(str)
+ * };
+ * ```
+ *
+ * @see {@link JSONCodec} - Default codec for JSON-serializable values
+ * @see {@link createCodec} - Helper function to create custom codecs
+ */
+interface Codec<T> {
+    /**
+     * Transforms a typed value into a string suitable for storage.
+     *
+     * @param value - The typed value to encode
+     * @returns A string representation of the value
+     * @throws {CodecError} If the value cannot be encoded
+     */
+    encode: (value: T) => string;
+    /**
+     * Transforms a stored string back into a typed value.
+     *
+     * @param encoded - The string representation from storage
+     * @returns The decoded typed value
+     * @throws {CodecError} If the string cannot be decoded
+     */
+    decode: (encoded: string) => T;
+}
+/**
+ * Configuration options for MnemonicProvider.
+ *
+ * These options configure the behavior of the storage provider, including
+ * namespace isolation, storage backend selection, cross-tab synchronization,
+ * and developer tools integration.
+ *
+ * @example
+ * ```tsx
+ * <MnemonicProvider
+ *   namespace="myApp"
+ *   storage={localStorage}
+ *   enableDevTools={process.env.NODE_ENV === 'development'}
+ * >
+ *   <App />
+ * </MnemonicProvider>
+ * ```
+ */
+interface MnemonicProviderOptions {
+    /**
+     * Namespace prefix for all storage keys.
+     *
+     * All keys stored by this provider will be prefixed with `${namespace}.`
+     * to avoid collisions between different parts of your application or
+     * different applications sharing the same storage backend.
+     *
+     * @example
+     * ```typescript
+     * // With namespace="myApp", a key "user" becomes "myApp.user" in storage
+     * namespace: "myApp"
+     * ```
+     */
+    namespace: string;
+    /**
+     * Storage backend to use for persistence.
+     *
+     * Defaults to `window.localStorage` in browser environments. You can provide
+     * a synchronous custom implementation (e.g., sessionStorage, an in-memory
+     * cache facade over IndexedDB, or a mock for testing).
+     *
+     * @default window.localStorage
+     *
+     * @example
+     * ```typescript
+     * // Use sessionStorage instead of localStorage
+     * storage: window.sessionStorage
+     *
+     * // Use a custom storage implementation
+     * storage: {
+     *   getItem: (key) => myCustomStore.get(key),
+     *   setItem: (key, value) => myCustomStore.set(key, value),
+     *   removeItem: (key) => myCustomStore.delete(key)
+     * }
+     * ```
+     */
+    storage?: StorageLike;
+    /**
+     * Enable DevTools debugging interface.
+     *
+     * When enabled, registers this provider in the global
+     * `window.__REACT_MNEMONIC_DEVTOOLS__` registry.
+     *
+     * The registry stores providers as weak references and exposes:
+     * - `resolve(namespace)` to strengthen a provider reference and access
+     *   inspection methods.
+     * - `list()` to enumerate provider availability.
+     *
+     * @default false
+     *
+     * @example
+     * ```typescript
+     * // Enable in development only
+     * enableDevTools: process.env.NODE_ENV === 'development'
+     *
+     * // Then in browser console:
+     * const provider = window.__REACT_MNEMONIC_DEVTOOLS__?.resolve('myApp')
+     * provider?.dump()
+     * provider?.get('user')
+     * provider?.set('user', { name: 'Test' })
+     * ```
+     */
+    enableDevTools?: boolean;
+    /**
+     * Versioning and schema enforcement mode.
+     *
+     * Controls whether stored values require a registered schema, and how
+     * missing schemas are handled. See {@link SchemaMode} for the behaviour
+     * of each mode.
+     *
+     * @default "default"
+     *
+     * @see {@link SchemaMode} - Detailed description of each mode
+     * @see {@link SchemaRegistry} - Registry supplied via `schemaRegistry`
+     */
+    schemaMode?: SchemaMode;
+    /**
+     * Schema registry used for version lookup and migration resolution.
+     *
+     * When provided, the library uses the registry to find the correct
+     * JSON Schema for each stored version, and to resolve migration paths
+     * when upgrading old data to the latest schema.
+     *
+     * Required when `schemaMode` is `"strict"` or `"autoschema"`.
+     * Optional (but recommended) in `"default"` mode.
+     *
+     * @remarks
+     * In `"default"` and `"strict"` modes, the registry is treated as
+     * immutable after the provider initializes. Updates should be shipped
+     * as part of a new app version and applied by remounting the provider.
+     * `"autoschema"` remains mutable so inferred schemas can be registered
+     * at runtime.
+     *
+     * @see {@link SchemaRegistry} - Interface the registry must implement
+     * @see {@link KeySchema} - Schema definition stored in the registry
+     */
+    schemaRegistry?: SchemaRegistry;
+    /**
+     * Server-rendering and hydration defaults for descendant hooks.
+     *
+     * Provider-level SSR settings establish the default hydration strategy for
+     * all `useMnemonicKey(...)` calls in this namespace. Individual hooks may
+     * still override the strategy when a specific key needs different behavior.
+     *
+     * @example
+     * ```tsx
+     * <MnemonicProvider
+     *   namespace="app"
+     *   ssr={{ hydration: "client-only" }}
+     * >
+     *   <App />
+     * </MnemonicProvider>
+     * ```
+     */
+    ssr?: MnemonicProviderSSRConfig;
+}
+/**
+ * Controls how the provider enforces versioned schemas on stored values.
+ *
+ * - `"default"` — Schemas are optional. When a schema exists for the stored
+ *   version it is used for validation; otherwise the hook's `codec` option is
+ *   used directly with no validation. This is the recommended starting mode.
+ *
+ * - `"strict"` — Every read and write **must** have a registered schema for
+ *   the stored version. If no matching schema is found the value falls back
+ *   to `defaultValue` with a `SchemaError` (`SCHEMA_NOT_FOUND` on reads,
+ *   `WRITE_SCHEMA_REQUIRED` on writes).
+ *   When no schemas are registered and no explicit schema is provided, writes
+ *   fall back to a codec-encoded (v0) envelope.
+ *
+ * - `"autoschema"` — Like `"default"`, but when a key has **no** schema
+ *   registered at all, the library infers a JSON Schema at version 1 from the
+ *   first successfully decoded value and registers it via
+ *   `SchemaRegistry.registerSchema`. Subsequent reads/writes for that key
+ *   then behave as if the schema had been registered manually.
+ *
+ * @remarks
+ * In `"default"` and `"strict"` modes, registry lookups are cached under the
+ * assumption that the schema registry is immutable for the lifetime of the
+ * provider. If you need to update schemas, publish a new app version and
+ * remount the provider. `"autoschema"` does not assume immutability.
+ *
+ * @default "default"
+ *
+ * @see {@link SchemaRegistry} - Registry that stores schemas and migrations
+ * @see {@link KeySchema} - Individual schema definition
+ */
+type SchemaMode = "strict" | "default" | "autoschema";
+/**
+ * Controls when a hook should read persisted storage during client rendering.
+ *
+ * - `"immediate"` — Default. The server snapshot is used during SSR/hydration,
+ *   and the hook reads persisted storage as soon as React switches to the
+ *   client snapshot.
+ *
+ * - `"client-only"` — Defers all storage reads until after the component has
+ *   mounted on the client. This is useful when you want a deterministic server
+ *   placeholder and prefer the persisted value to appear only after hydration
+ *   completes.
+ */
+type MnemonicHydrationMode = "immediate" | "client-only";
+/**
+ * Provider-level SSR defaults shared by descendant hooks.
+ */
+interface MnemonicProviderSSRConfig {
+    /**
+     * Default hydration strategy for descendant `useMnemonicKey(...)` hooks.
+     *
+     * @default "immediate"
+     */
+    hydration?: MnemonicHydrationMode;
+}
+/**
+ * Hook-level SSR controls for `useMnemonicKey(...)`.
+ *
+ * Lets a key render a deterministic server snapshot and optionally delay
+ * reading persisted storage until after client mount.
+ *
+ * @template T - The decoded value type for the key
+ */
+interface MnemonicKeySSRConfig<T> {
+    /**
+     * Value to expose during SSR and hydration instead of `defaultValue`.
+     *
+     * This value is not persisted automatically. Once hydration completes,
+     * the hook transitions to the stored value (if any) or back to
+     * `defaultValue`.
+     *
+     * Factory functions should be deterministic across server render and
+     * client hydration to avoid markup mismatches.
+     */
+    serverValue?: T | (() => T);
+    /**
+     * Hydration strategy for this key.
+     *
+     * When omitted, inherits the provider default.
+     */
+    hydration?: MnemonicHydrationMode;
+}
+/**
+ * Weak-reference shape used by the devtools registry.
+ *
+ * Matches the standard `WeakRef` API while keeping the public type surface
+ * compatible with ES2020 TypeScript lib targets.
+ */
+interface MnemonicDevToolsWeakRef<T extends object> {
+    /**
+     * Attempts to strengthen the weak reference.
+     *
+     * @returns The live object, or undefined if it was garbage-collected.
+     */
+    deref: () => T | undefined;
+}
+/**
+ * Provider inspection API exposed through devtools registry resolution.
+ *
+ * Resolve a provider from the registry, then invoke these methods for manual
+ * inspection/mutation from the browser console.
+ */
+interface MnemonicDevToolsProviderApi {
+    /** Access the underlying store instance. */
+    getStore: () => Mnemonic;
+    /** Dump all raw key-value pairs for the provider namespace. */
+    dump: () => Record<string, string>;
+    /** Read decoded value for an unprefixed key. */
+    get: (key: string) => unknown;
+    /** Write value for an unprefixed key (JSON-encoded). */
+    set: (key: string, value: unknown) => void;
+    /** Remove a single unprefixed key. */
+    remove: (key: string) => void;
+    /** Remove all keys in this provider namespace. */
+    clear: () => void;
+    /** List all unprefixed keys in this provider namespace. */
+    keys: () => string[];
+}
+/**
+ * Registry entry for a single provider namespace.
+ */
+interface MnemonicDevToolsProviderEntry {
+    /** Namespace key for this provider entry. */
+    namespace: string;
+    /** Weak reference to the provider inspection API. */
+    weakRef: MnemonicDevToolsWeakRef<MnemonicDevToolsProviderApi>;
+    /** Timestamp when this namespace was registered. */
+    registeredAt: number;
+    /** Timestamp when provider was last confirmed live. */
+    lastSeenAt: number;
+    /** Timestamp when provider was first observed unavailable, or null when live. */
+    staleSince: number | null;
+}
+/**
+ * Lightweight provider status returned by `list()`.
+ */
+interface MnemonicDevToolsProviderDescriptor {
+    /** Namespace registered by the provider. */
+    namespace: string;
+    /** Whether the provider can currently be resolved to a live API instance. */
+    available: boolean;
+    /** Timestamp when the provider namespace was first registered. */
+    registeredAt: number;
+    /** Timestamp when the provider was last observed as live. */
+    lastSeenAt: number;
+    /** Timestamp when the provider first became unavailable, or `null` when live. */
+    staleSince: number | null;
+}
+/**
+ * Environment capabilities reported by devtools registry.
+ */
+interface MnemonicDevToolsCapabilities {
+    /** Whether the runtime supports `WeakRef`. */
+    weakRef: boolean;
+    /** Whether the runtime supports `FinalizationRegistry`. */
+    finalizationRegistry: boolean;
+}
+/**
+ * Polling metadata for extension synchronization.
+ */
+interface MnemonicDevToolsMeta {
+    /** Monotonic registry version incremented on register and mutation events. */
+    version: number;
+    /** Timestamp of the most recent registry update. */
+    lastUpdated: number;
+    /** Short label describing the most recent registry change. */
+    lastChange: string;
+}
+/**
+ * Global devtools registry contract available on window.
+ *
+ * This is an advanced public API used by the browser console integration and
+ * extension tooling. Direct namespace access
+ * (`window.__REACT_MNEMONIC_DEVTOOLS__.myNamespace`) is not part of the
+ * public API.
+ */
+interface MnemonicDevToolsRegistry {
+    /** Provider entries keyed by namespace. */
+    providers: Record<string, MnemonicDevToolsProviderEntry>;
+    /** Resolve a namespace to a live provider API when one is available. */
+    resolve: (namespace: string) => MnemonicDevToolsProviderApi | null;
+    /** List provider availability without strengthening weak references manually. */
+    list: () => MnemonicDevToolsProviderDescriptor[];
+    /** Runtime capabilities relevant to the registry implementation. */
+    capabilities: MnemonicDevToolsCapabilities;
+    /** Versioning metadata used by polling devtools integrations. */
+    __meta: MnemonicDevToolsMeta;
+}
+/**
+ * Schema definition for a single key at a specific version.
+ *
+ * Each registered schema binds a storage key + version number to a
+ * JSON Schema that validates the payload. Schemas are fully serializable
+ * (no functions).
+ *
+ * When the provider reads a value whose envelope version matches a
+ * registered schema, the payload is validated against the schema's
+ * JSON Schema definition.
+ *
+ * @example
+ * ```typescript
+ * const userSchemaV1: KeySchema = {
+ *   key: "user",
+ *   version: 1,
+ *   schema: {
+ *     type: "object",
+ *     properties: {
+ *       name: { type: "string" },
+ *     },
+ *     required: ["name"],
+ *   },
+ * };
+ * ```
+ *
+ * @see {@link SchemaRegistry} - Where schemas are registered and looked up
+ * @see {@link MigrationRule} - How values migrate between schema versions
+ * @see {@link JsonSchema} - The JSON Schema subset used for validation
+ */
+type KeySchema<TValue = unknown, K extends string = string, TSchema extends JsonSchema = JsonSchema> = {
+    /**
+     * The unprefixed storage key this schema applies to.
+     */
+    key: K;
+    /**
+     * The version number for this schema.
+     *
+     * Must be a non-negative integer. Any version (including `0`) is valid.
+     */
+    version: number;
+    /**
+     * JSON Schema that validates the payload at this version.
+     *
+     * Only the subset of JSON Schema keywords defined in {@link JsonSchema}
+     * are supported. An empty schema `{}` accepts any value.
+     */
+    schema: TSchema;
+    /**
+     * Phantom type linking this runtime schema to its decoded TypeScript value.
+     *
+     * This field is never set at runtime. It exists only so helpers such as
+     * `defineKeySchema(...)`, `defineMnemonicKey(...)`, and `defineMigration(...)`
+     * can preserve a single source of truth between schema shape and value type.
+     */
+    readonly [keySchemaValueBrand]?: TValue;
+};
+/**
+ * A single migration step that transforms data from one schema version to
+ * another, or normalizes data at the same version.
+ *
+ * Migration rules are composed into a {@link MigrationPath} by the
+ * {@link SchemaRegistry} to upgrade stored data across multiple versions in
+ * sequence (e.g. v1 -> v2 -> v3).
+ *
+ * When `fromVersion === toVersion`, the rule is a **write-time normalizer**
+ * that runs on every write to that version. This is useful for data
+ * normalization (trimming strings, clamping values, injecting defaults).
+ *
+ * @example
+ * ```typescript
+ * // Version upgrade migration
+ * const userV1ToV2: MigrationRule = {
+ *   key: "user",
+ *   fromVersion: 1,
+ *   toVersion: 2,
+ *   migrate: (v1) => {
+ *     const old = v1 as { name: string };
+ *     return { firstName: old.name, lastName: "" };
+ *   },
+ * };
+ *
+ * // Write-time normalizer (same version)
+ * const trimUserV2: MigrationRule = {
+ *   key: "user",
+ *   fromVersion: 2,
+ *   toVersion: 2,
+ *   migrate: (v) => {
+ *     const user = v as { firstName: string; lastName: string };
+ *     return { firstName: user.firstName.trim(), lastName: user.lastName.trim() };
+ *   },
+ * };
+ * ```
+ *
+ * @see {@link MigrationPath} - Ordered list of rules applied in sequence
+ * @see {@link SchemaRegistry.getMigrationPath} - How the path is resolved
+ * @see {@link SchemaRegistry.getWriteMigration} - How write-time normalizers are resolved
+ */
+type MigrationRule<TFrom = unknown, TTo = unknown, K extends string = string> = {
+    /**
+     * The unprefixed storage key this rule applies to.
+     */
+    key: K;
+    /**
+     * The version the stored data is migrating **from**.
+     *
+     * Version `0` is allowed, enabling migrations from unversioned data.
+     */
+    fromVersion: number;
+    /**
+     * The version the stored data is migrating **to**.
+     *
+     * When equal to `fromVersion`, this rule is a write-time normalizer
+     * that runs on every write to that version.
+     */
+    toVersion: number;
+    /**
+     * Transformation function that converts data from `fromVersion`
+     * to `toVersion`.
+     *
+     * Receives the decoded value at `fromVersion` and must return
+     * the value in the shape expected by `toVersion`.
+     *
+     * @param value - The decoded value at `fromVersion`
+     * @returns The transformed value for `toVersion`
+     */
+    migrate(value: TFrom): TTo;
+};
+/**
+ * An ordered sequence of {@link MigrationRule} steps that upgrades stored
+ * data from an older schema version to a newer one.
+ *
+ * The rules are applied in array order. Each step's output becomes the
+ * next step's input. After the final step the result is validated against
+ * the target schema and persisted back to storage so the migration only
+ * runs once per key.
+ *
+ * @see {@link MigrationRule} - Individual migration step
+ * @see {@link SchemaRegistry.getMigrationPath} - Resolves a path between versions
+ */
+type MigrationPath<K extends string = string> = MigrationRule<unknown, unknown, K>[];
+/**
+ * Input options for {@link createSchemaRegistry}.
+ *
+ * Use this helper when your registry contents are known up front and do not
+ * need runtime mutation. The returned registry is immutable and optimized for
+ * the common `"default"` / `"strict"` setup.
+ *
+ * For most apps, this should be your default entry point for schema-managed
+ * persistence. Implement {@link SchemaRegistry} manually only when you need
+ * custom lookup behavior or runtime schema registration beyond autoschema mode.
+ */
+interface CreateSchemaRegistryOptions {
+    /**
+     * Versioned schemas to index by key and version.
+     *
+     * Duplicate `key + version` pairs are rejected up front with
+     * `SchemaError("SCHEMA_REGISTRATION_CONFLICT")`.
+     */
+    schemas?: readonly KeySchema[];
+    /**
+     * Migration rules to index by key and version edge.
+     *
+     * Write-time normalizers (`fromVersion === toVersion`) are indexed
+     * separately from read-time migration edges. Ambiguous outgoing edges,
+     * backward migrations, and duplicate write normalizers are rejected up
+     * front with `SchemaError("MIGRATION_GRAPH_INVALID")`.
+     */
+    migrations?: readonly MigrationRule[];
+}
+/**
+ * Lookup and registration API for key schemas and migration paths.
+ *
+ * Implementations of this interface are passed to `MnemonicProvider` via the
+ * `schemaRegistry` option. The provider calls these methods at read and write
+ * time to resolve the correct JSON Schema and migration chain for each
+ * stored value.
+ *
+ * In `"default"` and `"strict"` modes, callers should treat registry contents
+ * as immutable after provider initialization. The hook caches lookups to keep
+ * read/write hot paths fast. `"autoschema"` remains mutable to support
+ * inferred schema registration.
+ *
+ * Most applications should prefer {@link createSchemaRegistry} instead of
+ * implementing this interface manually. Manual implementations are mainly for
+ * advanced cases such as custom backing stores, dynamic schema discovery, or
+ * adapter layers around an existing registry system.
+ *
+ * @example
+ * ```typescript
+ * const registry = createSchemaRegistry({
+ *   schemas: [
+ *     { key: "settings", version: 1, schema: { type: "object", required: ["theme"] } },
+ *   ],
+ *   migrations: [],
+ * });
+ *
+ * <MnemonicProvider namespace="app" schemaRegistry={registry} schemaMode="strict">
+ *   <App />
+ * </MnemonicProvider>
+ * ```
+ *
+ * @see {@link KeySchema} - Schema definition
+ * @see {@link MigrationPath} - Migration chain returned by `getMigrationPath`
+ * @see {@link SchemaMode} - How the provider uses the registry
+ */
+interface SchemaRegistry {
+    /**
+     * Look up the schema registered for a specific key and version.
+     *
+     * @param key - The unprefixed storage key
+     * @param version - The version number to look up
+     * @returns The matching schema, or `undefined` if none is registered
+     */
+    getSchema(key: string, version: number): KeySchema | undefined;
+    /**
+     * Look up the highest-version schema registered for a key.
+     *
+     * Used by the write path to determine which version to stamp on new
+     * values, and by the read path to detect when a migration is needed.
+     *
+     * @param key - The unprefixed storage key
+     * @returns The latest schema, or `undefined` if none is registered
+     */
+    getLatestSchema(key: string): KeySchema | undefined;
+    /**
+     * Resolve an ordered migration path between two versions of a key.
+     *
+     * Returns `null` when no contiguous path exists. The returned rules
+     * are applied in order to transform data from `fromVersion` to
+     * `toVersion`.
+     *
+     * @param key - The unprefixed storage key
+     * @param fromVersion - The stored data's current version
+     * @param toVersion - The target version to migrate to
+     * @returns An ordered array of migration rules, or `null`
+     */
+    getMigrationPath(key: string, fromVersion: number, toVersion: number): MigrationPath | null;
+    /**
+     * Look up a write-time normalizer for a specific key and version.
+     *
+     * A write-time normalizer is a {@link MigrationRule} where
+     * `fromVersion === toVersion`. It runs on every write to that version,
+     * transforming the value before storage. The normalized value is
+     * re-validated against the schema after transformation.
+     *
+     * Optional. When not implemented or returns `undefined`, no write-time
+     * normalization is applied.
+     *
+     * @param key - The unprefixed storage key
+     * @param version - The target schema version
+     * @returns The normalizer rule, or `undefined` if none is registered
+     */
+    getWriteMigration?(key: string, version: number): MigrationRule | undefined;
+    /**
+     * Register a new schema.
+     *
+     * Optional. Required when `schemaMode` is `"autoschema"` so the
+     * library can persist inferred schemas. Implementations should throw
+     * if a schema already exists for the same key + version with a
+     * conflicting definition.
+     *
+     * @param schema - The schema to register
+     */
+    registerSchema?(schema: KeySchema): void;
+}
+/**
+ * Storage interface compatible with localStorage and synchronous custom storage implementations.
+ *
+ * Defines the minimum contract required for a storage backend. Compatible with
+ * browser Storage API (localStorage, sessionStorage) and custom implementations
+ * for testing or alternative storage solutions.
+ *
+ * All methods in this contract are intentionally synchronous. Promise-returning
+ * adapters such as React Native `AsyncStorage` are not directly supported by
+ * `StorageLike`; instead, keep a synchronous in-memory cache and flush to async
+ * persistence outside the hook contract.
+ *
+ * @remarks
+ * **Error handling contract**
+ *
+ * The library wraps every storage call in a try/catch. Errors are handled as
+ * follows:
+ *
+ * - **`DOMException` with `name === "QuotaExceededError"`** — Logged once via
+ *   `console.error` with the prefix `[Mnemonic] Storage quota exceeded`.
+ *   Squelched until a write succeeds, then the flag resets.
+ *
+ * - **Other `DOMException` errors (including `SecurityError`)** — Logged once
+ *   via `console.error` with the prefix `[Mnemonic] Storage access error`.
+ *   Squelched until any storage operation succeeds, then the flag resets.
+ *
+ * - **All other error types** — Silently suppressed.
+ *
+ * Custom `StorageLike` implementations are encouraged to throw `DOMException`
+ * for storage access failures so the library can surface diagnostics. Throwing
+ * non-`DOMException` errors is safe but results in silent suppression.
+ *
+ * In all error cases the library falls back to its in-memory cache, so
+ * components continue to function when the storage backend is unavailable.
+ *
+ * Promise-returning `getItem`, `setItem`, or `removeItem` implementations are
+ * treated as an invalid contract at runtime. Mnemonic logs the misuse once and
+ * falls back to its in-memory cache for safety.
+ *
+ * @example
+ * ```typescript
+ * // In-memory storage for testing
+ * const mockStorage: StorageLike = {
+ *   items: new Map<string, string>(),
+ *   getItem(key) { return this.items.get(key) ?? null; },
+ *   setItem(key, value) { this.items.set(key, value); },
+ *   removeItem(key) { this.items.delete(key); },
+ *   get length() { return this.items.size; },
+ *   key(index) {
+ *     return Array.from(this.items.keys())[index] ?? null;
+ *   }
+ * };
+ * ```
+ */
+type StorageLike = {
+    /**
+     * Retrieves the value associated with a key.
+     *
+     * @param key - The storage key to retrieve
+     * @returns The stored value as a string, or null if not found
+     *
+     * @remarks Must return synchronously. Returning a Promise is unsupported.
+     */
+    getItem(key: string): string | null;
+    /**
+     * Stores a key-value pair.
+     *
+     * @param key - The storage key
+     * @param value - The string value to store
+     *
+     * @remarks Must complete synchronously. Returning a Promise is unsupported.
+     */
+    setItem(key: string, value: string): void;
+    /**
+     * Removes a key-value pair from storage.
+     *
+     * @param key - The storage key to remove
+     *
+     * @remarks Must complete synchronously. Returning a Promise is unsupported.
+     */
+    removeItem(key: string): void;
+    /**
+     * Returns the key at the specified index in storage.
+     *
+     * Optional method for enumeration support.
+     *
+     * @param index - The numeric index
+     * @returns The key at the given index, or null if out of bounds
+     */
+    key?(index: number): string | null;
+    /**
+     * The number of items currently stored.
+     *
+     * Optional property for enumeration support.
+     */
+    readonly length?: number;
+    /**
+     * Subscribe to notifications when data changes externally.
+     *
+     * localStorage has built-in cross-tab notification via the browser's
+     * native `storage` event (used by the `listenCrossTab` hook option).
+     * Non-localStorage backends (IndexedDB, custom stores, etc.) lack this
+     * built-in mechanism. Implementing `onExternalChange` allows those
+     * adapters to provide equivalent cross-tab synchronization through
+     * their own transport (e.g., BroadcastChannel).
+     *
+     * The callback accepts an optional `changedKeys` parameter:
+     * - `callback()` or `callback(undefined)` triggers a blanket reload
+     *   of all actively subscribed keys.
+     * - `callback(["ns.key1", "ns.key2"])` reloads only the specified
+     *   fully-qualified keys, which is more efficient when the adapter
+     *   knows exactly which keys changed.
+     * - `callback([])` is a no-op.
+     *
+     * On a blanket reload the provider re-reads all actively subscribed
+     * keys from the storage backend and emits change notifications for
+     * any whose values differ from the cache.
+     *
+     * @param callback - Invoked when external data changes
+     * @returns An unsubscribe function that removes the callback
+     */
+    onExternalChange?: (callback: (changedKeys?: string[]) => void) => () => void;
+};
+/**
+ * Function type for unsubscribing from event listeners.
+ *
+ * Call this function to remove a subscription and stop receiving updates.
+ *
+ * @example
+ * ```typescript
+ * const unsubscribe = store.subscribeRaw('user', () => console.log('Updated!'));
+ * // Later...
+ * unsubscribe(); // Stop listening
+ * ```
+ */
+type Unsubscribe = () => void;
+/**
+ * Callback function invoked when a subscribed value changes.
+ *
+ * Used by the external store contract to notify React when state updates.
+ */
+type Listener = () => void;
+/**
+ * Low-level Mnemonic store API provided via React Context.
+ *
+ * This interface powers `MnemonicProvider` internally and is also exposed to
+ * advanced consumers through `MnemonicDevToolsProviderApi.getStore()`. Typical
+ * application code should still prefer `useMnemonicKey`.
+ *
+ * All keys passed to these methods should be **unprefixed**. The store
+ * automatically applies the namespace prefix internally.
+ *
+ * @remarks
+ * This implements the React `useSyncExternalStore` contract for efficient,
+ * tearing-free state synchronization. Most application code should still
+ * prefer `useMnemonicKey`; this type mainly appears in the DevTools API via
+ * `MnemonicDevToolsProviderApi.getStore()`.
+ */
+type Mnemonic = {
+    /**
+     * The namespace prefix applied to all keys in storage.
+     *
+     * Keys are stored as `${prefix}${key}` in the underlying storage backend.
+     */
+    prefix: string;
+    /**
+     * Whether the active storage backend can enumerate keys in this namespace.
+     *
+     * This is `true` for `localStorage`-like backends that implement both
+     * `length` and `key(index)`. Namespace-wide recovery helpers rely on this
+     * capability unless the caller supplies an explicit key list.
+     */
+    canEnumerateKeys: boolean;
+    /**
+     * Subscribe to changes for a specific key.
+     *
+     * Follows the React external store subscription contract. The listener
+     * will be called whenever the value for this key changes.
+     *
+     * @param key - The unprefixed storage key to subscribe to
+     * @param listener - Callback invoked when the value changes
+     * @returns Unsubscribe function to stop listening
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = store.subscribeRaw('user', () => {
+     *   console.log('User changed:', store.getRawSnapshot('user'));
+     * });
+     * ```
+     */
+    subscribeRaw: (key: string, listener: Listener) => Unsubscribe;
+    /**
+     * Get the current raw string value for a key.
+     *
+     * This is part of the external store snapshot contract. Values are
+     * cached in memory for stable snapshots.
+     *
+     * @param key - The unprefixed storage key
+     * @returns The raw string value, or null if not present
+     */
+    getRawSnapshot: (key: string) => string | null;
+    /**
+     * Write a raw string value to storage.
+     *
+     * Updates both the in-memory cache and the underlying storage backend,
+     * then notifies all subscribers for this key.
+     *
+     * @param key - The unprefixed storage key
+     * @param raw - The raw string value to store
+     */
+    setRaw: (key: string, raw: string) => void;
+    /**
+     * Remove a key from storage.
+     *
+     * Clears the value from both the cache and the underlying storage,
+     * then notifies all subscribers.
+     *
+     * @param key - The unprefixed storage key to remove
+     */
+    removeRaw: (key: string) => void;
+    /**
+     * Enumerate all keys in this namespace.
+     *
+     * Returns unprefixed keys that belong to this store's namespace.
+     *
+     * @returns Array of unprefixed key names
+     */
+    keys: () => string[];
+    /**
+     * Dump all key-value pairs in this namespace.
+     *
+     * Useful for debugging and DevTools integration.
+     *
+     * @returns Object mapping unprefixed keys to raw string values
+     */
+    dump: () => Record<string, string>;
+    /**
+     * The active schema enforcement mode for this provider.
+     *
+     * Propagated from the `schemaMode` provider option. Hooks read this
+     * to determine how to handle versioned envelopes.
+     *
+     * @see {@link SchemaMode}
+     */
+    schemaMode: SchemaMode;
+    /**
+     * Default hydration strategy inherited by descendant hooks.
+     */
+    ssrHydration: MnemonicHydrationMode;
+    /**
+     * How this provider can observe external changes from other tabs/processes.
+     *
+     * Hooks use this for development diagnostics when callers opt into
+     * cross-tab synchronization on a backend that cannot actually deliver it.
+     *
+     * When omitted, consumers should treat this as equivalent to `"none"`.
+     */
+    crossTabSyncMode?: "browser-storage-event" | "custom-external-change" | "none";
+    /**
+     * The schema registry for this provider, if one was supplied.
+     *
+     * Hooks use this to look up schemas, resolve migration paths, and
+     * (in autoschema mode) register inferred schemas.
+     *
+     * @see {@link SchemaRegistry}
+     */
+    schemaRegistry?: SchemaRegistry;
+};
+/**
+ * Recovery action names emitted by {@link useMnemonicRecovery}.
+ */
+type MnemonicRecoveryAction = "clear-all" | "clear-keys" | "clear-matching";
+/**
+ * Recovery event payload emitted after a namespace recovery action completes.
+ */
+interface MnemonicRecoveryEvent {
+    /**
+     * Recovery action that just ran.
+     */
+    action: MnemonicRecoveryAction;
+    /**
+     * Namespace where the recovery action ran.
+     */
+    namespace: string;
+    /**
+     * Unprefixed keys cleared by the action.
+     */
+    clearedKeys: string[];
+}
+/**
+ * Options for {@link useMnemonicRecovery}.
+ */
+interface UseMnemonicRecoveryOptions {
+    /**
+     * Optional callback invoked after a recovery action completes.
+     *
+     * Useful for analytics, audit trails, support diagnostics, or user-facing
+     * confirmation toasts.
+     */
+    onRecover?: (event: MnemonicRecoveryEvent) => void;
+}
+/**
+ * Namespace-scoped recovery helpers returned by {@link useMnemonicRecovery}.
+ *
+ * These helpers operate on the current provider namespace and are intended for
+ * user-facing recovery UX such as "reset app data" or "clear stale filters".
+ */
+interface MnemonicRecoveryHook {
+    /**
+     * Current provider namespace without the trailing storage prefix dot.
+     */
+    namespace: string;
+    /**
+     * Whether namespace keys can be enumerated automatically.
+     *
+     * `clearAll()` and `clearMatching()` require this to be `true`. If it is
+     * `false`, prefer `clearKeys([...])` with an explicit durable-key list.
+     */
+    canEnumerateKeys: boolean;
+    /**
+     * Lists all unprefixed keys currently visible in this namespace.
+     *
+     * Returns an empty array when no keys exist or when the storage backend
+     * cannot enumerate keys.
+     */
+    listKeys: () => string[];
+    /**
+     * Clears every key in the current namespace.
+     *
+     * @throws {Error} When the storage backend cannot enumerate namespace keys
+     */
+    clearAll: () => string[];
+    /**
+     * Clears a specific set of unprefixed keys in the current namespace.
+     *
+     * Duplicate keys are ignored.
+     */
+    clearKeys: (keys: readonly string[]) => string[];
+    /**
+     * Clears namespace keys whose names match the supplied predicate.
+     *
+     * @throws {Error} When the storage backend cannot enumerate namespace keys
+     */
+    clearMatching: (predicate: (key: string) => boolean) => string[];
+}
+/**
+ * Return shape from {@link useMnemonicKey}.
+ *
+ * This mirrors the familiar `useState` mental model while making the storage
+ * semantics explicit:
+ *
+ * - `set(...)` writes a new persisted value
+ * - `reset()` writes `defaultValue` back into storage
+ * - `remove()` deletes the key entirely so reads fall back to `defaultValue`
+ *
+ * See the
+ * [Clearable Persisted Values guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/clearable-persisted-values)
+ * for the semantic differences between clearing, resetting, and removing a key.
+ *
+ * @template T - The decoded value type for the key
+ *
+ * @see {@link UseMnemonicKeyOptions} - Hook configuration and lifecycle details
+ */
+interface MnemonicKeyState<T> {
+    /**
+     * Current decoded value, or the default when the key is absent or invalid.
+     */
+    value: T;
+    /**
+     * Persist a new value.
+     *
+     * Accepts either a direct replacement value or an updater function that
+     * receives the current decoded value.
+     */
+    set: (next: T | ((current: T) => T)) => void;
+    /**
+     * Reset the key back to `defaultValue` and persist that default.
+     */
+    reset: () => void;
+    /**
+     * Delete the key from storage entirely.
+     *
+     * Future reads will fall back to `defaultValue` until the key is written
+     * again.
+     */
+    remove: () => void;
+}
+/**
+ * Reusable, importable contract for a single persisted key.
+ *
+ * Descriptors package the key name and its `useMnemonicKey(...)` options into
+ * a stable object that can be defined once at module scope and reused across
+ * components. This helps keep persistence behavior explicit and consistent,
+ * especially when the same key appears in multiple parts of an application.
+ *
+ * @template T - The decoded value type for the key
+ * @template K - The literal key name
+ *
+ * @example
+ * ```typescript
+ * const themeKey = defineMnemonicKey("theme", {
+ *   defaultValue: "light" as "light" | "dark",
+ *   listenCrossTab: true,
+ * });
+ *
+ * const { value, set } = useMnemonicKey(themeKey);
+ * ```
+ *
+ * @see {@link defineMnemonicKey} - Helper for creating descriptors
+ * @see {@link useMnemonicKey} - Hook that consumes descriptors
+ */
+interface MnemonicKeyDescriptor<T, K extends string = string> {
+    /**
+     * Unprefixed storage key name.
+     */
+    readonly key: K;
+    /**
+     * Canonical options for this key.
+     */
+    readonly options: UseMnemonicKeyOptions<T>;
+}
+/**
+ * Key descriptor options inferred from a typed key schema.
+ *
+ * This mirrors `UseMnemonicKeyOptions<T>` but intentionally omits the `schema`
+ * override so the descriptor stays pinned to the supplied key schema version.
+ */
+type SchemaBoundKeyOptions<T> = Omit<UseMnemonicKeyOptions<T>, "schema">;
+/**
+ * Typed key schema shape inferred from a schema helper or branded JSON Schema.
+ *
+ * Useful when you want a versioned schema object to carry its decoded
+ * TypeScript value through registries, descriptors, and migration helpers.
+ */
+type TypedKeySchema<TSchema extends JsonSchema, K extends string = string> = KeySchema<InferJsonSchemaValue<TSchema>, K, TSchema>;
+/**
+ * Configuration options for the useMnemonicKey hook.
+ *
+ * These options control how a value is persisted, decoded, and
+ * synchronized across the application.
+ *
+ * @template T - The TypeScript type of the stored value
+ *
+ * @example
+ * ```typescript
+ * const { value, set } = useMnemonicKey<User>('currentUser', {
+ *   defaultValue: { name: 'Guest', id: null },
+ *   onMount: (user) => console.log('Loaded user:', user),
+ *   onChange: (current, previous) => {
+ *     console.log('User changed from', previous, 'to', current);
+ *   },
+ *   listenCrossTab: true
+ * });
+ * ```
+ */
+type UseMnemonicKeyOptions<T> = {
+    /**
+     * Default value to use when no stored value exists, or when decoding/validation fails.
+     *
+     * Can be a literal value or a factory function that returns the default.
+     * Factory functions receive an optional error argument describing why the
+     * fallback is being used:
+     *
+     * - `undefined` — Nominal path: no value exists in storage for this key.
+     * - `CodecError` — The stored value could not be decoded by the codec.
+     * - `SchemaError` — A schema, migration, or validation issue occurred
+     *   (e.g. missing schema, failed migration, JSON Schema validation failure).
+     *
+     * Static (non-function) default values ignore the error entirely.
+     *
+     * @remarks
+     * If a factory function is defined inline, it creates a new reference on
+     * every render, which forces internal memoization to recompute. For best
+     * performance, define the factory at module level or wrap it in `useCallback`:
+     *
+     * ```typescript
+     * // Module-level (stable reference, preferred)
+     * const getDefault = (error?: CodecError | SchemaError) => {
+     *     if (error) console.warn('Fallback:', error.message);
+     *     return { count: 0 };
+     * };
+     *
+     * // Or with useCallback inside a component
+     * const getDefault = useCallback(
+     *     (error?: CodecError | SchemaError) => ({ count: 0 }),
+     *     [],
+     * );
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Static default
+     * defaultValue: { count: 0 }
+     *
+     * // Factory with no error handling
+     * defaultValue: () => ({ timestamp: Date.now() })
+     *
+     * // Error-aware factory
+     * defaultValue: (error) => {
+     *     if (error instanceof CodecError) {
+     *         console.error('Corrupt data:', error.message);
+     *     }
+     *     if (error instanceof SchemaError) {
+     *         console.warn('Schema issue:', error.code, error.message);
+     *     }
+     *     return { count: 0 };
+     * }
+     * ```
+     */
+    defaultValue: T | ((error?: CodecError | SchemaError) => T);
+    /**
+     * Codec for encoding and decoding values to/from storage.
+     *
+     * Determines how the typed value is serialized to a string and
+     * deserialized back. Defaults to JSONCodec if not specified.
+     *
+     * Using a codec is a low-level option that bypasses JSON Schema
+     * validation. Schema-managed keys store JSON values directly and
+     * are validated against their registered JSON Schema.
+     *
+     * @default JSONCodec
+     *
+     * @example
+     * ```typescript
+     * // Custom codec for dates
+     * codec: createCodec(
+     *   (date) => date.toISOString(),
+     *   (str) => new Date(str)
+     * )
+     * ```
+     */
+    codec?: Codec<T>;
+    /**
+     * Optional read-time reconciliation hook for persisted values.
+     *
+     * Runs after a stored value has been decoded and any read-time migrations
+     * have completed, but before the hook exposes the value to React. This is
+     * useful for selectively enforcing newly shipped defaults or normalizing
+     * legacy persisted values without discarding the whole key.
+     *
+     * If the reconciled value would persist differently from the pre-reconcile
+     * value, the hook rewrites storage once using the normal write path.
+     *
+     * @remarks
+     * Prefer schema migrations for structural changes that must always happen
+     * between explicit versions. Use `reconcile` for conditional, field-level
+     * adjustments that depend on application policy rather than a strict schema
+     * upgrade step.
+     *
+     * See the Schema Migration guide for migration-vs-reconciliation guidance:
+     * https://thirtytwobits.github.io/react-mnemonic/docs/guides/schema-migration
+     *
+     * If `reconcile` throws a `SchemaError`, that error is preserved and passed
+     * to `defaultValue`. Any other thrown error is wrapped as
+     * `SchemaError("RECONCILE_FAILED")`.
+     *
+     * @param value - The decoded persisted value
+     * @param context - Metadata about the stored and latest schema versions
+     *
+     * @example
+     * ```typescript
+     * reconcile: (value, { persistedVersion }) => ({
+     *   ...value,
+     *   theme: persistedVersion < 2 ? "dark" : value.theme,
+     * })
+     * ```
+     */
+    reconcile?: (value: T, context: ReconcileContext) => T;
+    /**
+     * Callback invoked once when the hook is first mounted.
+     *
+     * Receives the initial value (either from storage or the default).
+     * Useful for triggering side effects based on the loaded state.
+     *
+     * @param value - The initial value loaded on mount
+     *
+     * @example
+     * ```typescript
+     * onMount: (theme) => {
+     *   document.body.className = theme;
+     *   console.log('Theme loaded:', theme);
+     * }
+     * ```
+     */
+    onMount?: (value: T) => void;
+    /**
+     * Callback invoked whenever the value changes.
+     *
+     * Receives both the new value and the previous value. This is called
+     * for all changes, including those triggered by other components or tabs.
+     *
+     * @param value - The new current value
+     * @param prev - The previous value
+     *
+     * @example
+     * ```typescript
+     * onChange: (newTheme, oldTheme) => {
+     *   document.body.classList.remove(oldTheme);
+     *   document.body.classList.add(newTheme);
+     *   console.log(`Theme changed: ${oldTheme} -> ${newTheme}`);
+     * }
+     * ```
+     */
+    onChange?: (value: T, prev: T) => void;
+    /**
+     * Enable listening for changes from other browser tabs.
+     *
+     * When true, uses the browser's `storage` event to detect changes
+     * made to localStorage in other tabs and synchronizes them to this component.
+     *
+     * Only effective when using localStorage as the storage backend.
+     *
+     * @default false
+     *
+     * @example
+     * ```typescript
+     * // Enable cross-tab sync for shared state
+     * listenCrossTab: true
+     * ```
+     *
+     * @remarks
+     * The `storage` event only fires for changes made in *other* tabs,
+     * not the current tab. Changes within the same tab are synchronized
+     * automatically via React's state management.
+     */
+    listenCrossTab?: boolean;
+    /**
+     * Server-rendering controls for this key.
+     *
+     * Use this when the server should render a value other than
+     * `defaultValue`, or when persisted storage should only be read after the
+     * component has mounted on the client.
+     *
+     * @example
+     * ```typescript
+     * ssr: {
+     *   serverValue: { theme: "system" },
+     *   hydration: "client-only",
+     * }
+     * ```
+     */
+    ssr?: MnemonicKeySSRConfig<T>;
+    /**
+     * Optional schema controls for this key.
+     *
+     * Allows overriding the version written by the `set` function. When
+     * omitted, the library writes using the highest registered schema for
+     * this key, or version `0` when no schemas are registered.
+     *
+     * @example
+     * ```typescript
+     * // Pin writes to schema version 2 even if version 3 exists
+     * const { value, set } = useMnemonicKey("user", {
+     *   defaultValue: { name: "" },
+     *   schema: { version: 2 },
+     * });
+     * ```
+     */
+    schema?: {
+        /**
+         * Explicit schema version to use when writing values.
+         *
+         * When set, the `set` and `reset` functions encode using the
+         * schema registered at this version instead of the latest. Useful
+         * during gradual rollouts where not all consumers have been
+         * updated yet.
+         *
+         * Must reference a version that exists in the `SchemaRegistry`.
+         * If not found the write falls back to the latest schema (default
+         * mode) or fails with a `SchemaError` (strict mode).
+         */
+        version?: number;
+    };
+};
+/**
+ * Metadata passed to `UseMnemonicKeyOptions.reconcile`.
+ */
+type ReconcileContext = {
+    /**
+     * The unprefixed storage key being reconciled.
+     */
+    key: string;
+    /**
+     * The version found in the persisted envelope that was read.
+     */
+    persistedVersion: number;
+    /**
+     * The latest registered schema version for the key, when available.
+     */
+    latestVersion?: number;
+};
+
+/**
+ * Hook for namespace-scoped recovery actions such as hard reset and selective clear.
+ *
+ * Applications can use this to offer self-service recovery UX for corrupt or
+ * legacy persisted state. The hook operates on the current provider namespace.
+ *
+ * See the
+ * [Reset and Recovery guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/reset-and-recovery)
+ * for soft-reset and hard-reset patterns.
+ *
+ * @param options - Optional recovery callback for telemetry/auditing
+ * @returns Namespace recovery helpers
+ *
+ * @throws {Error} If used outside of a MnemonicProvider
+ */
+declare function useMnemonicRecovery(options?: UseMnemonicRecoveryOptions): MnemonicRecoveryHook;
+
+/**
+ * Define a reusable, importable contract for a persisted key.
+ *
+ * This packages the storage key and the canonical `useMnemonicKey(...)`
+ * options into a single object that can be shared across components, docs,
+ * and generated code.
+ *
+ * @template K - The literal storage key name
+ * @template T - The decoded value type for the key
+ *
+ * @param key - The unprefixed storage key
+ * @param options - Canonical hook options for the key
+ * @returns A descriptor that can be passed directly to `useMnemonicKey(...)`
+ *
+ * @example
+ * ```typescript
+ * const themeKey = defineMnemonicKey("theme", {
+ *   defaultValue: "light" as "light" | "dark",
+ *   listenCrossTab: true,
+ * });
+ *
+ * const { value, set } = useMnemonicKey(themeKey);
+ * ```
+ */
+declare function defineMnemonicKey<const K extends string, T>(key: K, options: UseMnemonicKeyOptions<T>): MnemonicKeyDescriptor<T, K>;
+declare function defineMnemonicKey<const K extends string, TSchema extends KeySchema<unknown, K, JsonSchema>>(keySchema: TSchema, options: SchemaBoundKeyOptions<TSchema extends KeySchema<infer TValue, string, JsonSchema> ? TValue : never>): MnemonicKeyDescriptor<TSchema extends KeySchema<infer TValue, string, JsonSchema> ? TValue : never, TSchema["key"]>;
+
+export { type JsonSchema as A, type MigrationRule as B, type Codec as C, type CompiledValidator as D, type JsonSchemaType as E, type JsonSchemaValidationError as F, type MigrationPath as G, type SchemaBoundKeyOptions as H, type InferJsonSchemaValue as I, JSONCodec as J, type KeySchema as K, type Listener as L, type MnemonicProviderOptions as M, type TypedKeySchema as N, compileSchema as O, mnemonicSchema as P, validateJsonSchema as Q, type ReconcileContext as R, SchemaError as S, type TypedJsonSchema as T, type UseMnemonicKeyOptions as U, type MnemonicKeyDescriptor as a, type MnemonicKeyState as b, CodecError as c, type Mnemonic as d, type MnemonicDevToolsCapabilities as e, type MnemonicDevToolsMeta as f, type MnemonicDevToolsProviderApi as g, type MnemonicDevToolsProviderDescriptor as h, type MnemonicDevToolsProviderEntry as i, type MnemonicDevToolsRegistry as j, type MnemonicDevToolsWeakRef as k, type MnemonicHydrationMode as l, type MnemonicKeySSRConfig as m, type MnemonicProviderSSRConfig as n, type MnemonicRecoveryAction as o, type MnemonicRecoveryEvent as p, type MnemonicRecoveryHook as q, type SchemaMode as r, type StorageLike as s, type Unsubscribe as t, type UseMnemonicRecoveryOptions as u, createCodec as v, defineMnemonicKey as w, useMnemonicRecovery as x, type CreateSchemaRegistryOptions as y, type SchemaRegistry as z };