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

package/dist/index.d.ts

@@ -149,6 +149,8 @@ declare function createCodec<T>(encode: (value: T) => string, decode: (encoded:
  * | `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. |
@@ -170,7 +172,7 @@ 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" | "SCHEMA_REGISTRATION_CONFLICT" | "TYPE_MISMATCH" | "MODE_CONFIGURATION_INVALID";
+    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.
      */
@@ -302,6 +304,51 @@ declare function compileSchema(schema: JsonSchema): CompiledValidator;
  */
 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.
  *
@@ -309,6 +356,7 @@ declare function validateJsonSchema(value: unknown, schema: JsonSchema, path?: s
  * 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.
  *
@@ -386,7 +434,8 @@ interface MnemonicProviderOptions {
      * Storage backend to use for persistence.
      *
      * Defaults to `window.localStorage` in browser environments. You can provide
-     * a custom implementation (e.g., sessionStorage, AsyncStorage, or a mock for testing).
+     * a synchronous custom implementation (e.g., sessionStorage, an in-memory
+     * cache facade over IndexedDB, or a mock for testing).
      *
      * @default window.localStorage
      *
@@ -407,8 +456,13 @@ interface MnemonicProviderOptions {
     /**
      * Enable DevTools debugging interface.
      *
-     * When enabled, exposes the store on `window.__REACT_MNEMONIC_DEVTOOLS__[namespace]`
-     * with methods to inspect, modify, and dump storage state from the console.
+     * 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
      *
@@ -418,9 +472,10 @@ interface MnemonicProviderOptions {
      * enableDevTools: process.env.NODE_ENV === 'development'
      *
      * // Then in browser console:
-     * window.__REACT_MNEMONIC_DEVTOOLS__.myApp.dump()
-     * window.__REACT_MNEMONIC_DEVTOOLS__.myApp.get('user')
-     * window.__REACT_MNEMONIC_DEVTOOLS__.myApp.set('user', { name: 'Test' })
+     * const provider = window.__REACT_MNEMONIC_DEVTOOLS__?.resolve('myApp')
+     * provider?.dump()
+     * provider?.get('user')
+     * provider?.set('user', { name: 'Test' })
      * ```
      */
     enableDevTools?: boolean;
@@ -458,6 +513,24 @@ interface MnemonicProviderOptions {
      * @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.
@@ -491,6 +564,163 @@ interface MnemonicProviderOptions {
  * @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.
  *
@@ -521,11 +751,11 @@ type SchemaMode = "strict" | "default" | "autoschema";
  * @see {@link MigrationRule} - How values migrate between schema versions
  * @see {@link JsonSchema} - The JSON Schema subset used for validation
  */
-type KeySchema = {
+type KeySchema<TValue = unknown, K extends string = string, TSchema extends JsonSchema = JsonSchema> = {
     /**
      * The unprefixed storage key this schema applies to.
      */
-    key: string;
+    key: K;
     /**
      * The version number for this schema.
      *
@@ -538,7 +768,15 @@ type KeySchema = {
      * Only the subset of JSON Schema keywords defined in {@link JsonSchema}
      * are supported. An empty schema `{}` accepts any value.
      */
-    schema: JsonSchema;
+    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
@@ -581,11 +819,11 @@ type KeySchema = {
  * @see {@link SchemaRegistry.getMigrationPath} - How the path is resolved
  * @see {@link SchemaRegistry.getWriteMigration} - How write-time normalizers are resolved
  */
-type MigrationRule = {
+type MigrationRule<TFrom = unknown, TTo = unknown, K extends string = string> = {
     /**
      * The unprefixed storage key this rule applies to.
      */
-    key: string;
+    key: K;
     /**
      * The version the stored data is migrating **from**.
      *
@@ -609,7 +847,7 @@ type MigrationRule = {
      * @param value - The decoded value at `fromVersion`
      * @returns The transformed value for `toVersion`
      */
-    migrate: (value: unknown) => unknown;
+    migrate(value: TFrom): TTo;
 };
 /**
  * An ordered sequence of {@link MigrationRule} steps that upgrades stored
@@ -623,7 +861,36 @@ type MigrationRule = {
  * @see {@link MigrationRule} - Individual migration step
  * @see {@link SchemaRegistry.getMigrationPath} - Resolves a path between versions
  */
-type MigrationPath = MigrationRule[];
+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.
  *
@@ -637,15 +904,19 @@ type MigrationPath = MigrationRule[];
  * 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: SchemaRegistry = {
- *   getSchema: (key, version) => schemas.get(`${key}@${version}`),
- *   getLatestSchema: (key) => latestByKey.get(key),
- *   getMigrationPath: (key, from, to) => buildPath(key, from, to),
- *   getWriteMigration: (key, version) => normalizers.get(`${key}@${version}`),
- *   registerSchema: (schema) => { schemas.set(`${schema.key}@${schema.version}`, schema); },
- * };
+ * const registry = createSchemaRegistry({
+ *   schemas: [
+ *     { key: "settings", version: 1, schema: { type: "object", required: ["theme"] } },
+ *   ],
+ *   migrations: [],
+ * });
  *
  * <MnemonicProvider namespace="app" schemaRegistry={registry} schemaMode="strict">
  *   <App />
@@ -717,12 +988,17 @@ interface SchemaRegistry {
     registerSchema?(schema: KeySchema): void;
 }
 /**
- * Storage interface compatible with localStorage and custom storage implementations.
+ * 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**
  *
@@ -746,6 +1022,10 @@ interface SchemaRegistry {
  * 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
@@ -767,6 +1047,8 @@ type StorageLike = {
      *
      * @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;
     /**
@@ -774,12 +1056,16 @@ type StorageLike = {
      *
      * @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;
     /**
@@ -824,6 +1110,318 @@ type StorageLike = {
      */
     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.
  *
@@ -921,6 +1519,42 @@ type UseMnemonicKeyOptions<T> = {
      * ```
      */
     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.
      *
@@ -979,6 +1613,22 @@ type UseMnemonicKeyOptions<T> = {
      * 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.
      *
@@ -1011,6 +1661,23 @@ type UseMnemonicKeyOptions<T> = {
         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;
+};
 
 /**
  * Props for the MnemonicProvider component.
@@ -1020,11 +1687,11 @@ type UseMnemonicKeyOptions<T> = {
  * @see {@link MnemonicProviderOptions} - Configuration options
  * @see {@link MnemonicProvider} - Provider component
  */
-interface MnemonicProviderProps extends MnemonicProviderOptions {
+interface MnemonicProviderProps extends Readonly<MnemonicProviderOptions> {
     /**
      * React children to render within the provider.
      */
-    children: ReactNode;
+    readonly children: ReactNode;
 }
 /**
  * React Context provider for namespace-isolated persistent state.
@@ -1039,10 +1706,11 @@ interface MnemonicProviderProps extends MnemonicProviderOptions {
  * @param props - Provider configuration and children
  * @param props.children - React children to render within the provider
  * @param props.namespace - Unique namespace for isolating storage keys
- * @param props.storage - Optional custom storage backend (defaults to localStorage)
+ * @param props.storage - Optional synchronous custom storage backend (defaults to localStorage)
  * @param props.enableDevTools - Enable DevTools debugging interface (defaults to false)
  * @param props.schemaMode - Schema enforcement mode (default: "default")
  * @param props.schemaRegistry - Optional schema registry for storing schemas and migrations
+ * @param props.ssr - Optional SSR defaults for descendant hooks
  *
  * @example
  * ```tsx
@@ -1058,7 +1726,7 @@ interface MnemonicProviderProps extends MnemonicProviderOptions {
  *
  * @example
  * ```tsx
- * // With custom storage backend
+ * // With a synchronous custom storage backend
  * function App() {
  *   return (
  *     <MnemonicProvider
@@ -1086,9 +1754,10 @@ interface MnemonicProviderProps extends MnemonicProviderOptions {
  * }
  *
  * // Then in browser console:
- * window.__REACT_MNEMONIC_DEVTOOLS__.myApp.dump()
- * window.__REACT_MNEMONIC_DEVTOOLS__.myApp.get('user')
- * window.__REACT_MNEMONIC_DEVTOOLS__.myApp.set('theme', 'dark')
+ * const dt = window.__REACT_MNEMONIC_DEVTOOLS__.resolve('myApp')
+ * dt?.dump()
+ * dt?.get('user')
+ * dt?.set('theme', 'dark')
  * ```
  *
  * @example
@@ -1106,17 +1775,34 @@ interface MnemonicProviderProps extends MnemonicProviderOptions {
  * }
  * ```
  *
+ * @example
+ * ```tsx
+ * // Delay persisted storage reads until after client mount
+ * function App() {
+ *   return (
+ *     <MnemonicProvider
+ *       namespace="myApp"
+ *       ssr={{ hydration: "client-only" }}
+ *     >
+ *       <MyComponents />
+ *     </MnemonicProvider>
+ *   );
+ * }
+ * ```
+ *
  * @remarks
  * - Creates a stable store instance that only recreates when namespace, storage, or enableDevTools change
  * - All storage operations are cached in memory for fast reads
  * - Storage failures are handled gracefully (logged but not thrown)
- * - In SSR environments, the provider works but no storage persistence occurs
+ * - `StorageLike` is intentionally synchronous for v1; async persistence must sit behind a sync facade
+ * - In SSR environments, the provider is safe by default: hooks render
+ *   `defaultValue` unless configured with an explicit `ssr.serverValue`
  * - The store implements React's useSyncExternalStore contract for efficient updates
  *
  * @see {@link useMnemonicKey} - Hook for using persistent state
  * @see {@link MnemonicProviderOptions} - Configuration options
  */
-declare function MnemonicProvider({ children, namespace, storage, enableDevTools, schemaMode, schemaRegistry, }: MnemonicProviderProps): react_jsx_runtime.JSX.Element;
+declare function MnemonicProvider({ children, namespace, storage, enableDevTools, schemaMode, schemaRegistry, ssr, }: MnemonicProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * React hook for persistent, type-safe state management.
@@ -1128,24 +1814,256 @@ declare function MnemonicProvider({ children, namespace, storage, enableDevTools
  * Must be used within a `MnemonicProvider`. Uses React's `useSyncExternalStore`
  * internally for efficient, tearing-free state synchronization.
  *
+ * Read lifecycle, in order:
+ * 1. Load the raw stored envelope for `key`
+ * 2. Decode the payload (codec or schema-managed JSON)
+ * 3. Validate and migrate when schemas are registered
+ * 4. Run `reconcile(...)` if provided
+ * 5. Fall back to `defaultValue` when the key is absent or invalid
+ *
+ * Write semantics:
+ * - `set(...)` persists a new value
+ * - `reset()` persists `defaultValue`
+ * - `remove()` deletes the key entirely so future reads fall back to `defaultValue`
+ *
+ * For guide-level background, see the
+ * [Schema Migration guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/schema-migration)
+ * and the
+ * [Clearable Persisted Values guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/clearable-persisted-values).
+ *
  * @template T - The TypeScript type of the stored value
  *
- * @param key - The storage key (unprefixed, namespace is applied automatically)
- * @param options - Configuration options controlling persistence, encoding, and behavior
+ * @returns Persistent state handle with the current value and mutation helpers
  *
- * @returns Object with the current value and methods to update it
+ * @see {@link UseMnemonicKeyOptions} - Hook configuration and lifecycle details
  *
  * @throws {Error} If used outside of a MnemonicProvider
  */
-declare function useMnemonicKey<T>(key: string, options: UseMnemonicKeyOptions<T>): {
-    /** Current decoded value, or the default when the key is absent or invalid. */
-    value: T;
-    /** Persist a new value (direct or updater function). */
-    set: (next: T | ((cur: T) => T)) => void;
-    /** Reset to `defaultValue` and persist it. */
-    reset: () => void;
-    /** Delete the key from storage entirely. */
-    remove: () => void;
-};
+declare function useMnemonicKey<T, K extends string>(descriptor: MnemonicKeyDescriptor<T, K>): MnemonicKeyState<T>;
+declare function useMnemonicKey<T>(key: string, options: UseMnemonicKeyOptions<T>): MnemonicKeyState<T>;
+
+/**
+ * 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"]>;
+
+/**
+ * Create an immutable schema registry for common default/strict-mode setups.
+ *
+ * The helper indexes schemas and migrations up front, validates duplicate and
+ * ambiguous definitions, and returns a {@link SchemaRegistry} ready to pass to
+ * `MnemonicProvider`.
+ *
+ * Most applications should prefer this helper over manually implementing
+ * {@link SchemaRegistry}.
+ *
+ * See the
+ * [Schema Migration guide](https://thirtytwobits.github.io/react-mnemonic/docs/guides/schema-migration)
+ * for end-to-end registry and migration patterns.
+ *
+ * @param options - Initial schema and migration definitions
+ * @returns An indexed immutable schema registry
+ *
+ * @throws {SchemaError} With `SCHEMA_REGISTRATION_CONFLICT` for duplicate
+ *   schemas, or `MIGRATION_GRAPH_INVALID` for invalid migration graphs
+ */
+declare function createSchemaRegistry(options?: CreateSchemaRegistryOptions): SchemaRegistry;
+
+/**
+ * Create a versioned key schema that preserves the decoded value type inferred
+ * from a typed schema helper.
+ */
+declare function defineKeySchema<const K extends string, TSchema extends JsonSchema>(key: K, version: number, schema: TSchema): KeySchema<InferJsonSchemaValue<TSchema>, K, TSchema>;
+/**
+ * Create a typed migration rule between two key schema versions.
+ *
+ * The `migrate(...)` callback is inferred from the source and target schemas,
+ * which keeps migration logic aligned with the registered runtime schemas.
+ */
+declare function defineMigration<const K extends string, TFrom, TTo>(fromSchema: KeySchema<TFrom, K>, toSchema: KeySchema<TTo, K>, migrate: (value: TFrom) => TTo): MigrationRule<TFrom, TTo, K>;
+/**
+ * Create a typed write-time normalization rule for a single key schema.
+ */
+declare function defineWriteMigration<const K extends string, TValue>(schema: KeySchema<TValue, K>, migrate: (value: TValue) => TValue): MigrationRule<TValue, TValue, K>;
+
+/**
+ * Adapter functions for structural migration helpers.
+ *
+ * These helpers assume tree-like data, but not a specific node shape. Supply a
+ * `StructuralTreeHelpers<T>` when your nodes use custom field names. When your
+ * nodes already look like `{ id, children }`, the exported helpers work without
+ * any adapter configuration.
+ *
+ * @template T - Tree node type
+ */
+interface StructuralTreeHelpers<T> {
+    /**
+     * Returns the stable identifier for a node.
+     */
+    getId: (node: T) => string;
+    /**
+     * Returns the node's child list, or `undefined` when it has no children.
+     */
+    getChildren: (node: T) => readonly T[] | undefined;
+    /**
+     * Returns a copy of the node with a new child list.
+     */
+    withChildren: (node: T, children: T[]) => T;
+    /**
+     * Returns a copy of the node with a new identifier.
+     */
+    withId: (node: T, id: string) => T;
+}
+/**
+ * Default tree node shape supported by the structural migration helpers.
+ *
+ * If your nodes already use `id` and `children`, you can call the helpers
+ * directly without supplying `StructuralTreeHelpers`.
+ *
+ * @template T - Tree node type
+ */
+interface StructuralNode<T> {
+    /**
+     * Stable node identifier used for lookup and rename operations.
+     */
+    id: string;
+    /**
+     * Optional child nodes.
+     */
+    children?: readonly T[];
+}
+/**
+ * Finds the first node with the requested id using depth-first traversal.
+ *
+ * @template T - Tree node type (must extend `{ id: string; children?: readonly T[] }` when `helpers` is omitted)
+ * @param root - Root node to search
+ * @param id - Target node id
+ * @returns The matching node, or `undefined`
+ */
+declare function findNodeById<T extends StructuralNode<T>>(root: T, id: string): T | undefined;
+/**
+ * Finds the first node with the requested id using depth-first traversal.
+ *
+ * @template T - Tree node type
+ * @param root - Root node to search
+ * @param id - Target node id
+ * @param helpers - Adapter for custom node shapes
+ * @returns The matching node, or `undefined`
+ */
+declare function findNodeById<T>(root: T, id: string, helpers: StructuralTreeHelpers<T>): T | undefined;
+/**
+ * Inserts a child under the target parent when none of that parent's existing
+ * direct children share the same id. Returns the original tree when the parent
+ * is missing or the child is already present as a direct child.
+ *
+ * @template T - Tree node type (must extend `{ id: string; children?: readonly T[] }` when `helpers` is omitted)
+ * @param root - Root node to update
+ * @param parentId - Parent node that should receive the child
+ * @param child - Child node to append
+ * @returns Updated tree with the child inserted once
+ */
+declare function insertChildIfMissing<T extends StructuralNode<T>>(root: T, parentId: string, child: T): T;
+/**
+ * Inserts a child under the target parent when no existing child shares the
+ * same id. Returns the original tree when the parent is missing or the child is
+ * already present.
+ *
+ * @template T - Tree node type
+ * @param root - Root node to update
+ * @param parentId - Parent node that should receive the child
+ * @param child - Child node to append
+ * @param helpers - Adapter for custom node shapes
+ * @returns Updated tree with the child inserted once
+ */
+declare function insertChildIfMissing<T>(root: T, parentId: string, child: T, helpers: StructuralTreeHelpers<T>): T;
+/**
+ * Renames every node with the source id while preserving tree structure.
+ * Returns the original tree when the source id is missing or the target id
+ * already exists elsewhere.
+ *
+ * @template T - Tree node type (must extend `{ id: string; children?: readonly T[] }` when `helpers` is omitted)
+ * @param root - Root node to update
+ * @param currentId - Existing id to rename
+ * @param nextId - Replacement id
+ * @returns Updated tree with matching node ids renamed
+ */
+declare function renameNode<T extends StructuralNode<T>>(root: T, currentId: string, nextId: string): T;
+/**
+ * Renames every node with the source id while preserving tree structure.
+ * Returns the original tree when the source id is missing or the target id
+ * already exists elsewhere.
+ *
+ * @template T - Tree node type
+ * @param root - Root node to update
+ * @param currentId - Existing id to rename
+ * @param nextId - Replacement id
+ * @param helpers - Adapter for custom node shapes
+ * @returns Updated tree with matching node ids renamed
+ */
+declare function renameNode<T>(root: T, currentId: string, nextId: string, helpers: StructuralTreeHelpers<T>): T;
+/**
+ * Deduplicates each node's immediate children while preserving the first child
+ * encountered for each key. The helper traverses the full tree and returns the
+ * original root when no duplicates are removed.
+ *
+ * @template T - Tree node type (must extend `{ id: string; children?: readonly T[] }` when `helpers` is omitted)
+ * @template K - Deduplication key type
+ * @param root - Root node to normalize
+ * @param getKey - Function that computes a dedupe key for each child
+ * @returns Updated tree with duplicate siblings removed
+ */
+declare function dedupeChildrenBy<T extends StructuralNode<T>, K>(root: T, getKey: (node: T) => K): T;
+/**
+ * Deduplicates each node's immediate children while preserving the first child
+ * encountered for each key. The helper traverses the full tree and returns the
+ * original root when no duplicates are removed.
+ *
+ * @template T - Tree node type
+ * @template K - Deduplication key type
+ * @param root - Root node to normalize
+ * @param getKey - Function that computes a dedupe key for each child
+ * @param helpers - Adapter for custom node shapes
+ * @returns Updated tree with duplicate siblings removed
+ */
+declare function dedupeChildrenBy<T, K>(root: T, getKey: (node: T) => K, helpers: StructuralTreeHelpers<T>): T;
 
-export { type Codec, CodecError, type CompiledValidator, JSONCodec, type JsonSchema, type JsonSchemaType, type JsonSchemaValidationError, type KeySchema, type MigrationPath, type MigrationRule, MnemonicProvider, type MnemonicProviderOptions, type MnemonicProviderProps, SchemaError, type SchemaMode, type SchemaRegistry, type StorageLike, type UseMnemonicKeyOptions, compileSchema, createCodec, useMnemonicKey, validateJsonSchema };
+export { type Codec, CodecError, type CompiledValidator, type CreateSchemaRegistryOptions, type InferJsonSchemaValue, JSONCodec, type JsonSchema, type JsonSchemaType, type JsonSchemaValidationError, type KeySchema, type Listener, type MigrationPath, type MigrationRule, type Mnemonic, type MnemonicDevToolsCapabilities, type MnemonicDevToolsMeta, type MnemonicDevToolsProviderApi, type MnemonicDevToolsProviderDescriptor, type MnemonicDevToolsProviderEntry, type MnemonicDevToolsRegistry, type MnemonicDevToolsWeakRef, type MnemonicHydrationMode, type MnemonicKeyDescriptor, type MnemonicKeySSRConfig, type MnemonicKeyState, MnemonicProvider, type MnemonicProviderOptions, type MnemonicProviderProps, type MnemonicProviderSSRConfig, type MnemonicRecoveryAction, type MnemonicRecoveryEvent, type MnemonicRecoveryHook, type ReconcileContext, type SchemaBoundKeyOptions, SchemaError, type SchemaMode, type SchemaRegistry, type StorageLike, type StructuralNode, type StructuralTreeHelpers, type TypedJsonSchema, type TypedKeySchema, type Unsubscribe, type UseMnemonicKeyOptions, type UseMnemonicRecoveryOptions, compileSchema, createCodec, createSchemaRegistry, dedupeChildrenBy, defineKeySchema, defineMigration, defineMnemonicKey, defineWriteMigration, findNodeById, insertChildIfMissing, mnemonicSchema, renameNode, useMnemonicKey, useMnemonicRecovery, validateJsonSchema };