react-mnemonic 1.1.0-beta0 → 1.2.0-beta1

package/dist/schema.d.cts

@@ -0,0 +1,317 @@
+import { M as MnemonicProviderOptions, a as MnemonicKeyDescriptor, b as MnemonicKeyState, U as UseMnemonicKeyOptions, y as CreateSchemaRegistryOptions, z as SchemaRegistry, A as JsonSchema, K as KeySchema, I as InferJsonSchemaValue, B as MigrationRule } from './key-BvFvcKiR.cjs';
+export { C as Codec, c as CodecError, D as CompiledValidator, J as JSONCodec, E as JsonSchemaType, F as JsonSchemaValidationError, L as Listener, G as MigrationPath, d as Mnemonic, e as MnemonicDevToolsCapabilities, f as MnemonicDevToolsMeta, g as MnemonicDevToolsProviderApi, h as MnemonicDevToolsProviderDescriptor, i as MnemonicDevToolsProviderEntry, j as MnemonicDevToolsRegistry, k as MnemonicDevToolsWeakRef, l as MnemonicHydrationMode, m as MnemonicKeySSRConfig, n as MnemonicProviderSSRConfig, o as MnemonicRecoveryAction, p as MnemonicRecoveryEvent, q as MnemonicRecoveryHook, R as ReconcileContext, H as SchemaBoundKeyOptions, S as SchemaError, r as SchemaMode, s as StorageLike, T as TypedJsonSchema, N as TypedKeySchema, t as Unsubscribe, u as UseMnemonicRecoveryOptions, O as compileSchema, v as createCodec, w as defineMnemonicKey, P as mnemonicSchema, x as useMnemonicRecovery, Q as validateJsonSchema } from './key-BvFvcKiR.cjs';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * Props for the MnemonicProvider component.
+ *
+ * Extends MnemonicProviderOptions with required children prop.
+ *
+ * @see {@link MnemonicProviderOptions} - Configuration options
+ * @see {@link MnemonicProvider} - Provider component
+ */
+interface MnemonicProviderProps extends Readonly<MnemonicProviderOptions> {
+    /**
+     * React children to render within the provider.
+     */
+    readonly children: ReactNode;
+}
+/**
+ * React Context provider for namespace-isolated persistent state.
+ *
+ * Creates a scoped storage environment where all keys are automatically prefixed
+ * with the namespace to prevent collisions. Implements an in-memory cache with
+ * read-through behavior to the underlying storage backend (localStorage by default).
+ *
+ * This provider must wrap any components that use `useMnemonicKey`. Multiple
+ * providers with different namespaces can coexist in the same application.
+ *
+ * @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 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
+ * // Basic usage with default settings
+ * function App() {
+ *   return (
+ *     <MnemonicProvider namespace="myApp">
+ *       <MyComponents />
+ *     </MnemonicProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With a synchronous custom storage backend
+ * function App() {
+ *   return (
+ *     <MnemonicProvider
+ *       namespace="myApp"
+ *       storage={window.sessionStorage}
+ *     >
+ *       <MyComponents />
+ *     </MnemonicProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With DevTools enabled (development only)
+ * function App() {
+ *   return (
+ *     <MnemonicProvider
+ *       namespace="myApp"
+ *       enableDevTools={process.env.NODE_ENV === 'development'}
+ *     >
+ *       <MyComponents />
+ *     </MnemonicProvider>
+ *   );
+ * }
+ *
+ * // Then in browser console:
+ * const dt = window.__REACT_MNEMONIC_DEVTOOLS__.resolve('myApp')
+ * dt?.dump()
+ * dt?.get('user')
+ * dt?.set('theme', 'dark')
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple providers with different namespaces
+ * function App() {
+ *   return (
+ *     <MnemonicProvider namespace="user-prefs">
+ *       <UserSettings />
+ *       <MnemonicProvider namespace="app-state">
+ *         <Dashboard />
+ *       </MnemonicProvider>
+ *     </MnemonicProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @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)
+ * - `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, ssr, }: MnemonicProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * React hook for persistent, type-safe state management.
+ */
+declare function useMnemonicKey<T, K extends string>(descriptor: MnemonicKeyDescriptor<T, K>): MnemonicKeyState<T>;
+declare function useMnemonicKey<T>(key: string, options: UseMnemonicKeyOptions<T>): MnemonicKeyState<T>;
+
+/**
+ * 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 { CreateSchemaRegistryOptions, InferJsonSchemaValue, JsonSchema, KeySchema, MigrationRule, MnemonicKeyDescriptor, MnemonicKeyState, MnemonicProvider, MnemonicProviderOptions, type MnemonicProviderProps, SchemaRegistry, type StructuralNode, type StructuralTreeHelpers, UseMnemonicKeyOptions, createSchemaRegistry, dedupeChildrenBy, defineKeySchema, defineMigration, defineWriteMigration, findNodeById, insertChildIfMissing, renameNode, useMnemonicKey };

package/dist/schema.d.ts

@@ -0,0 +1,317 @@
+import { M as MnemonicProviderOptions, a as MnemonicKeyDescriptor, b as MnemonicKeyState, U as UseMnemonicKeyOptions, y as CreateSchemaRegistryOptions, z as SchemaRegistry, A as JsonSchema, K as KeySchema, I as InferJsonSchemaValue, B as MigrationRule } from './key-BvFvcKiR.js';
+export { C as Codec, c as CodecError, D as CompiledValidator, J as JSONCodec, E as JsonSchemaType, F as JsonSchemaValidationError, L as Listener, G as MigrationPath, d as Mnemonic, e as MnemonicDevToolsCapabilities, f as MnemonicDevToolsMeta, g as MnemonicDevToolsProviderApi, h as MnemonicDevToolsProviderDescriptor, i as MnemonicDevToolsProviderEntry, j as MnemonicDevToolsRegistry, k as MnemonicDevToolsWeakRef, l as MnemonicHydrationMode, m as MnemonicKeySSRConfig, n as MnemonicProviderSSRConfig, o as MnemonicRecoveryAction, p as MnemonicRecoveryEvent, q as MnemonicRecoveryHook, R as ReconcileContext, H as SchemaBoundKeyOptions, S as SchemaError, r as SchemaMode, s as StorageLike, T as TypedJsonSchema, N as TypedKeySchema, t as Unsubscribe, u as UseMnemonicRecoveryOptions, O as compileSchema, v as createCodec, w as defineMnemonicKey, P as mnemonicSchema, x as useMnemonicRecovery, Q as validateJsonSchema } from './key-BvFvcKiR.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * Props for the MnemonicProvider component.
+ *
+ * Extends MnemonicProviderOptions with required children prop.
+ *
+ * @see {@link MnemonicProviderOptions} - Configuration options
+ * @see {@link MnemonicProvider} - Provider component
+ */
+interface MnemonicProviderProps extends Readonly<MnemonicProviderOptions> {
+    /**
+     * React children to render within the provider.
+     */
+    readonly children: ReactNode;
+}
+/**
+ * React Context provider for namespace-isolated persistent state.
+ *
+ * Creates a scoped storage environment where all keys are automatically prefixed
+ * with the namespace to prevent collisions. Implements an in-memory cache with
+ * read-through behavior to the underlying storage backend (localStorage by default).
+ *
+ * This provider must wrap any components that use `useMnemonicKey`. Multiple
+ * providers with different namespaces can coexist in the same application.
+ *
+ * @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 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
+ * // Basic usage with default settings
+ * function App() {
+ *   return (
+ *     <MnemonicProvider namespace="myApp">
+ *       <MyComponents />
+ *     </MnemonicProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With a synchronous custom storage backend
+ * function App() {
+ *   return (
+ *     <MnemonicProvider
+ *       namespace="myApp"
+ *       storage={window.sessionStorage}
+ *     >
+ *       <MyComponents />
+ *     </MnemonicProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With DevTools enabled (development only)
+ * function App() {
+ *   return (
+ *     <MnemonicProvider
+ *       namespace="myApp"
+ *       enableDevTools={process.env.NODE_ENV === 'development'}
+ *     >
+ *       <MyComponents />
+ *     </MnemonicProvider>
+ *   );
+ * }
+ *
+ * // Then in browser console:
+ * const dt = window.__REACT_MNEMONIC_DEVTOOLS__.resolve('myApp')
+ * dt?.dump()
+ * dt?.get('user')
+ * dt?.set('theme', 'dark')
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple providers with different namespaces
+ * function App() {
+ *   return (
+ *     <MnemonicProvider namespace="user-prefs">
+ *       <UserSettings />
+ *       <MnemonicProvider namespace="app-state">
+ *         <Dashboard />
+ *       </MnemonicProvider>
+ *     </MnemonicProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @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)
+ * - `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, ssr, }: MnemonicProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * React hook for persistent, type-safe state management.
+ */
+declare function useMnemonicKey<T, K extends string>(descriptor: MnemonicKeyDescriptor<T, K>): MnemonicKeyState<T>;
+declare function useMnemonicKey<T>(key: string, options: UseMnemonicKeyOptions<T>): MnemonicKeyState<T>;
+
+/**
+ * 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 { CreateSchemaRegistryOptions, InferJsonSchemaValue, JsonSchema, KeySchema, MigrationRule, MnemonicKeyDescriptor, MnemonicKeyState, MnemonicProvider, MnemonicProviderOptions, type MnemonicProviderProps, SchemaRegistry, type StructuralNode, type StructuralTreeHelpers, UseMnemonicKeyOptions, createSchemaRegistry, dedupeChildrenBy, defineKeySchema, defineMigration, defineWriteMigration, findNodeById, insertChildIfMissing, renameNode, useMnemonicKey };