react-mnemonic 0.1.1-alpha.0 → 1.0.0-beta.0

package/dist/index.cjs

@@ -41,6 +41,121 @@ function MnemonicProvider({
     const listeners = /* @__PURE__ */ new Map();
     let quotaErrorLogged = false;
     let accessErrorLogged = false;
+    const detectEnumerableStorage = () => {
+      if (!st) return false;
+      try {
+        return typeof st.length === "number" && typeof st.key === "function";
+      } catch {
+        return false;
+      }
+    };
+    const canEnumerateKeys = detectEnumerableStorage();
+    const isProductionRuntime = () => {
+      const env = globalThis?.process?.env?.NODE_ENV;
+      if (typeof env !== "string") {
+        return true;
+      }
+      return env === "production";
+    };
+    const weakRefConstructor = () => {
+      const ctor = globalThis?.WeakRef;
+      return typeof ctor === "function" ? ctor : null;
+    };
+    const hasFinalizationRegistry = () => typeof globalThis?.FinalizationRegistry === "function";
+    const ensureDevToolsRoot = () => {
+      if (!enableDevTools || typeof window === "undefined") return null;
+      const weakRefSupported = weakRefConstructor() !== null;
+      const finalizationRegistrySupported = hasFinalizationRegistry();
+      const globalWindow = window;
+      const rawExisting = globalWindow.__REACT_MNEMONIC_DEVTOOLS__;
+      const root = rawExisting && typeof rawExisting === "object" ? rawExisting : {};
+      const reserved = /* @__PURE__ */ new Set(["providers", "resolve", "list", "capabilities", "__meta"]);
+      for (const key of Object.keys(root)) {
+        if (!reserved.has(key)) {
+          const descriptor = Object.getOwnPropertyDescriptor(root, key);
+          if (!descriptor || descriptor.configurable) {
+            try {
+              delete root[key];
+            } catch {
+            }
+          }
+        }
+      }
+      if (!root.providers || typeof root.providers !== "object") {
+        root.providers = {};
+      }
+      if (!root.capabilities || typeof root.capabilities !== "object") {
+        root.capabilities = {};
+      }
+      root.capabilities.weakRef = weakRefSupported;
+      root.capabilities.finalizationRegistry = finalizationRegistrySupported;
+      if (!root.__meta || typeof root.__meta !== "object") {
+        root.__meta = {
+          version: 0,
+          lastUpdated: Date.now(),
+          lastChange: ""
+        };
+      }
+      if (typeof root.__meta.version !== "number" || !Number.isFinite(root.__meta.version)) {
+        root.__meta.version = 0;
+      }
+      if (typeof root.__meta.lastUpdated !== "number" || !Number.isFinite(root.__meta.lastUpdated)) {
+        root.__meta.lastUpdated = Date.now();
+      }
+      if (typeof root.__meta.lastChange !== "string") {
+        root.__meta.lastChange = "";
+      }
+      if (typeof root.resolve !== "function") {
+        root.resolve = (ns) => {
+          const entry = root.providers[ns];
+          if (!entry || !entry.weakRef || typeof entry.weakRef.deref !== "function") return null;
+          const live = entry.weakRef.deref();
+          if (live) {
+            entry.lastSeenAt = Date.now();
+            entry.staleSince = null;
+            return live;
+          }
+          if (entry.staleSince === null) {
+            entry.staleSince = Date.now();
+          }
+          return null;
+        };
+      }
+      if (typeof root.list !== "function") {
+        root.list = () => {
+          const entries = root.providers;
+          const out = [];
+          for (const [ns, entry] of Object.entries(entries)) {
+            const live = entry && entry.weakRef && typeof entry.weakRef.deref === "function" ? entry.weakRef.deref() : void 0;
+            const available = Boolean(live);
+            if (available) {
+              entry.lastSeenAt = Date.now();
+              entry.staleSince = null;
+            } else if (entry.staleSince === null) {
+              entry.staleSince = Date.now();
+            }
+            out.push({
+              namespace: ns,
+              available,
+              registeredAt: entry.registeredAt,
+              lastSeenAt: entry.lastSeenAt,
+              staleSince: entry.staleSince
+            });
+          }
+          out.sort((a, b) => a.namespace.localeCompare(b.namespace));
+          return out;
+        };
+      }
+      globalWindow.__REACT_MNEMONIC_DEVTOOLS__ = root;
+      return root;
+    };
+    const bumpDevToolsVersion = (reason) => {
+      const root = ensureDevToolsRoot();
+      if (!root) return;
+      root.__meta.version += 1;
+      root.__meta.lastUpdated = Date.now();
+      root.__meta.lastChange = `${namespace}.${reason}`;
+    };
     const fullKey = (key) => prefix + key;
     const emit = (key) => {
       const set = listeners.get(key);
@@ -90,6 +205,7 @@ function MnemonicProvider({
         }
       }
       emit(key);
+      bumpDevToolsVersion(`set:${key}`);
     };
     const removeRaw = (key) => {
       cache.set(key, null);
@@ -102,6 +218,7 @@ function MnemonicProvider({
         }
       }
       emit(key);
+      bumpDevToolsVersion(`remove:${key}`);
     };
     const subscribeRaw = (key, listener) => {
       let set = listeners.get(key);
@@ -120,11 +237,14 @@ function MnemonicProvider({
     };
     const getRawSnapshot = (key) => readThrough(key);
     const keys = () => {
-      if (!st || typeof st.length !== "number" || typeof st.key !== "function") return [];
+      if (!canEnumerateKeys || !st) return [];
       const out = [];
       try {
-        for (let i = 0; i < st.length; i++) {
-          const k = st.key(i);
+        const storageLength = st.length;
+        const getStorageKey = st.key;
+        if (typeof storageLength !== "number" || typeof getStorageKey !== "function") return [];
+        for (let i = 0; i < storageLength; i++) {
+          const k = getStorageKey.call(st, i);
           if (!k) continue;
           if (k.startsWith(prefix)) out.push(k.slice(prefix.length));
         }
@@ -144,6 +264,7 @@ function MnemonicProvider({
     };
     const reloadFromStorage = (changedKeys) => {
       if (!st) return;
+      let changed = false;
       if (changedKeys !== void 0 && changedKeys.length === 0) return;
       if (changedKeys !== void 0) {
         for (const fk of changedKeys) {
@@ -163,11 +284,15 @@ function MnemonicProvider({
             if (fresh !== cached) {
               cache.set(key, fresh);
               emit(key);
+              changed = true;
             }
           } else if (cache.has(key)) {
             cache.delete(key);
           }
         }
+        if (changed) {
+          bumpDevToolsVersion("reload:granular");
+        }
         return;
       }
       for (const [key, listenerSet] of listeners) {
@@ -184,6 +309,7 @@ function MnemonicProvider({
         if (fresh !== cached) {
           cache.set(key, fresh);
           emit(key);
+          changed = true;
         }
       }
       for (const key of cache.keys()) {
@@ -191,9 +317,13 @@ function MnemonicProvider({
           cache.delete(key);
         }
       }
+      if (changed) {
+        bumpDevToolsVersion("reload:full");
+      }
     };
     const store2 = {
       prefix,
+      canEnumerateKeys,
       subscribeRaw,
       getRawSnapshot,
       setRaw: writeRaw,
@@ -205,56 +335,86 @@ function MnemonicProvider({
       ...schemaRegistry ? { schemaRegistry } : {}
     };
     if (enableDevTools && typeof window !== "undefined") {
-      window.__REACT_MNEMONIC_DEVTOOLS__ = window.__REACT_MNEMONIC_DEVTOOLS__ || {};
-      window.__REACT_MNEMONIC_DEVTOOLS__[namespace] = {
-        /** Access the underlying store instance */
-        getStore: () => store2,
-        /** Dump all key-value pairs and display as a console table */
-        dump: () => {
-          const data = dump();
-          console.table(
-            Object.entries(data).map(([key, value]) => ({
-              key,
-              value,
-              decoded: (() => {
+      const root = ensureDevToolsRoot();
+      let infoMessage = `[Mnemonic DevTools] Namespace "${namespace}" available via window.__REACT_MNEMONIC_DEVTOOLS__.resolve("${namespace}")`;
+      if (root) {
+        if (!root.capabilities.weakRef) {
+          infoMessage = `[Mnemonic DevTools] WeakRef is not available; registry provider "${namespace}" was not registered.`;
+        } else {
+          const existingLive = root.resolve(namespace);
+          if (existingLive) {
+            const duplicateMessage = `[Mnemonic DevTools] Duplicate provider namespace "${namespace}" detected. Each window must have at most one live MnemonicProvider per namespace.`;
+            if (!isProductionRuntime()) {
+              throw new Error(duplicateMessage);
+            }
+            console.warn(`${duplicateMessage} Keeping the first provider and ignoring the duplicate.`);
+            infoMessage = `[Mnemonic DevTools] Namespace "${namespace}" already registered. Keeping existing provider reference.`;
+          } else {
+            const providerApi = {
+              /** Access the underlying store instance */
+              getStore: () => store2,
+              /** Dump all key-value pairs and display as a console table */
+              dump: () => {
+                const data = dump();
+                console.table(
+                  Object.entries(data).map(([key, value]) => ({
+                    key,
+                    value,
+                    decoded: (() => {
+                      try {
+                        return JSON.parse(value);
+                      } catch {
+                        return value;
+                      }
+                    })()
+                  }))
+                );
+                return data;
+              },
+              /** Get a decoded value by key */
+              get: (key) => {
+                const raw = readThrough(key);
+                if (raw == null) return void 0;
                 try {
-                  return JSON.parse(value);
+                  return JSON.parse(raw);
                 } catch {
-                  return value;
+                  return raw;
                 }
-              })()
-            }))
-          );
-          return data;
-        },
-        /** Get a decoded value by key */
-        get: (key) => {
-          const raw = readThrough(key);
-          if (raw == null) return void 0;
-          try {
-            return JSON.parse(raw);
-          } catch {
-            return raw;
-          }
-        },
-        /** Set a value by key (automatically JSON-encoded) */
-        set: (key, value) => {
-          writeRaw(key, JSON.stringify(value));
-        },
-        /** Remove a key from storage */
-        remove: (key) => removeRaw(key),
-        /** Clear all keys in this namespace */
-        clear: () => {
-          for (const k of keys()) {
-            removeRaw(k);
+              },
+              /** Set a value by key (automatically JSON-encoded) */
+              set: (key, value) => {
+                writeRaw(key, JSON.stringify(value));
+              },
+              /** Remove a key from storage */
+              remove: (key) => removeRaw(key),
+              /** Clear all keys in this namespace */
+              clear: () => {
+                for (const k of keys()) {
+                  removeRaw(k);
+                }
+              },
+              /** List all keys in this namespace */
+              keys
+            };
+            const WeakRefCtor = weakRefConstructor();
+            if (!WeakRefCtor) {
+              infoMessage = `[Mnemonic DevTools] WeakRef became unavailable while registering "${namespace}".`;
+            } else {
+              store2.__devToolsProviderApiHold = providerApi;
+              root.providers[namespace] = {
+                namespace,
+                weakRef: new WeakRefCtor(providerApi),
+                registeredAt: Date.now(),
+                lastSeenAt: Date.now(),
+                staleSince: null
+              };
+              bumpDevToolsVersion("registry:namespace-registered");
+              infoMessage = `[Mnemonic DevTools] Namespace "${namespace}" available via window.__REACT_MNEMONIC_DEVTOOLS__.resolve("${namespace}")`;
+            }
           }
-        },
-        /** List all keys in this namespace */
-        keys
-      };
-      console.info(
-        `[Mnemonic DevTools] Namespace "${namespace}" available at window.__REACT_MNEMONIC_DEVTOOLS__.${namespace}`
-      );
+        }
+      }
+      console.info(infoMessage);
     }
     return store2;
   }, [namespace, storage, enableDevTools, schemaMode, schemaRegistry]);
@@ -596,7 +756,7 @@ function inferJsonSchema(sample) {
 // src/Mnemonic/use.ts
 function useMnemonicKey(key, options) {
   const api = useMnemonic();
-  const { defaultValue, onMount, onChange, listenCrossTab, codec: codecOpt, schema } = options;
+  const { defaultValue, onMount, onChange, listenCrossTab, codec: codecOpt, schema, reconcile } = options;
   const codec = codecOpt ?? JSONCodec;
   const schemaMode = api.schemaMode;
   const schemaRegistry = api.schemaRegistry;
@@ -695,6 +855,112 @@ function useMnemonicKey(key, options) {
     },
     [schemaRegistry, registryCache, key]
   );
+  const encodeForWrite = react.useCallback(
+    (nextValue) => {
+      const explicitVersion = schema?.version;
+      const latestSchema = getLatestSchemaForKey();
+      const explicitSchema = explicitVersion !== void 0 ? getSchemaForVersion(explicitVersion) : void 0;
+      let targetSchema = explicitSchema;
+      if (!targetSchema) {
+        if (explicitVersion !== void 0) {
+          if (schemaMode !== "strict") {
+            targetSchema = latestSchema;
+          }
+        } else {
+          targetSchema = latestSchema;
+        }
+      }
+      if (!targetSchema) {
+        if (explicitVersion !== void 0 && schemaMode === "strict") {
+          throw new SchemaError(
+            "WRITE_SCHEMA_REQUIRED",
+            `Write requires schema for key "${key}" in strict mode`
+          );
+        }
+        const envelope2 = {
+          version: 0,
+          payload: codec.encode(nextValue)
+        };
+        return JSON.stringify(envelope2);
+      }
+      let valueToStore = nextValue;
+      const writeMigration = schemaRegistry?.getWriteMigration?.(key, targetSchema.version);
+      if (writeMigration) {
+        try {
+          valueToStore = writeMigration.migrate(valueToStore);
+        } catch (err) {
+          throw err instanceof SchemaError ? err : new SchemaError("MIGRATION_FAILED", `Write-time migration failed for key "${key}"`, err);
+        }
+      }
+      validateAgainstSchema(valueToStore, targetSchema.schema);
+      const envelope = {
+        version: targetSchema.version,
+        payload: valueToStore
+      };
+      return JSON.stringify(envelope);
+    },
+    [
+      schema?.version,
+      key,
+      schemaMode,
+      codec,
+      schemaRegistry,
+      validateAgainstSchema,
+      getLatestSchemaForKey,
+      getSchemaForVersion
+    ]
+  );
+  const applyReconcile = react.useCallback(
+    ({
+      value: value2,
+      rewriteRaw,
+      pendingSchema,
+      persistedVersion,
+      latestVersion,
+      serializeForPersist,
+      derivePendingSchema
+    }) => {
+      if (!reconcile) {
+        const result = { value: value2 };
+        if (rewriteRaw !== void 0) result.rewriteRaw = rewriteRaw;
+        if (pendingSchema !== void 0) result.pendingSchema = pendingSchema;
+        return result;
+      }
+      const context = {
+        key,
+        persistedVersion,
+        ...latestVersion === void 0 ? {} : { latestVersion }
+      };
+      let baselineSerialized;
+      if (serializeForPersist) {
+        try {
+          baselineSerialized = serializeForPersist(value2);
+        } catch {
+          baselineSerialized = rewriteRaw;
+        }
+      }
+      try {
+        const reconciled = reconcile(value2, context);
+        const nextPendingSchema = derivePendingSchema ? derivePendingSchema(reconciled) : pendingSchema;
+        if (!serializeForPersist) {
+          const result2 = { value: reconciled };
+          if (rewriteRaw !== void 0) result2.rewriteRaw = rewriteRaw;
+          if (nextPendingSchema !== void 0) result2.pendingSchema = nextPendingSchema;
+          return result2;
+        }
+        const nextSerialized = serializeForPersist(reconciled);
+        const nextRewriteRaw = baselineSerialized === void 0 || nextSerialized !== baselineSerialized ? nextSerialized : rewriteRaw;
+        const result = { value: reconciled };
+        if (nextRewriteRaw !== void 0) result.rewriteRaw = nextRewriteRaw;
+        if (nextPendingSchema !== void 0) result.pendingSchema = nextPendingSchema;
+        return result;
+      } catch (err) {
+        const typedErr = err instanceof SchemaError ? err : new SchemaError("RECONCILE_FAILED", `Reconciliation failed for key "${key}"`, err);
+        return { value: getFallback(typedErr) };
+      }
+    },
+    [getFallback, key, reconcile]
+  );
   const decodeForRead = react.useCallback(
     (rawText) => {
       if (rawText == null) return { value: getFallback() };
@@ -730,21 +996,26 @@ function useMnemonicKey(key, options) {
         }
         try {
           const decoded2 = typeof envelope.payload === "string" ? decodeStringPayload(envelope.payload, codec) : envelope.payload;
-          const inferredJsonSchema = inferJsonSchema(decoded2);
-          const inferred = {
+          const inferSchemaForValue = (value2) => ({
             key,
             version: 1,
-            schema: inferredJsonSchema
-          };
-          const rewriteEnvelope = {
-            version: inferred.version,
-            payload: decoded2
-          };
-          return {
+            schema: inferJsonSchema(value2)
+          });
+          const inferred = inferSchemaForValue(decoded2);
+          return applyReconcile({
             value: decoded2,
             pendingSchema: inferred,
-            rewriteRaw: JSON.stringify(rewriteEnvelope)
-          };
+            rewriteRaw: JSON.stringify({
+              version: inferred.version,
+              payload: decoded2
+            }),
+            persistedVersion: envelope.version,
+            serializeForPersist: (value2) => JSON.stringify({
+              version: inferred.version,
+              payload: value2
+            }),
+            derivePendingSchema: inferSchemaForValue
+          });
         } catch (err) {
           const typedErr = err instanceof SchemaError || err instanceof CodecError ? err : new SchemaError("TYPE_MISMATCH", `Autoschema inference failed for key "${key}"`, err);
           return { value: getFallback(typedErr) };
@@ -752,11 +1023,21 @@ function useMnemonicKey(key, options) {
       }
       if (!schemaForVersion) {
         if (typeof envelope.payload !== "string") {
-          return { value: envelope.payload };
+          return applyReconcile({
+            value: envelope.payload,
+            persistedVersion: envelope.version,
+            ...latestSchema ? { latestVersion: latestSchema.version } : {},
+            serializeForPersist: encodeForWrite
+          });
         }
         try {
           const decoded2 = decodeStringPayload(envelope.payload, codec);
-          return { value: decoded2 };
+          return applyReconcile({
+            value: decoded2,
+            persistedVersion: envelope.version,
+            ...latestSchema ? { latestVersion: latestSchema.version } : {},
+            serializeForPersist: encodeForWrite
+          });
         } catch (err) {
           const typedErr = err instanceof SchemaError || err instanceof CodecError ? err : new CodecError(`Codec decode failed for key "${key}"`, err);
           return { value: getFallback(typedErr) };
@@ -771,7 +1052,12 @@ function useMnemonicKey(key, options) {
         return { value: getFallback(typedErr) };
       }
       if (!latestSchema || envelope.version >= latestSchema.version) {
-        return { value: current };
+        return applyReconcile({
+          value: current,
+          persistedVersion: envelope.version,
+          ...latestSchema ? { latestVersion: latestSchema.version } : {},
+          serializeForPersist: encodeForWrite
+        });
       }
       const path = getMigrationPathForKey(envelope.version, latestSchema.version);
       if (!path) {
@@ -790,22 +1076,26 @@ function useMnemonicKey(key, options) {
           migrated = step.migrate(migrated);
         }
         validateAgainstSchema(migrated, latestSchema.schema);
-        const rewriteEnvelope = {
-          version: latestSchema.version,
-          payload: migrated
-        };
-        return {
+        return applyReconcile({
           value: migrated,
-          rewriteRaw: JSON.stringify(rewriteEnvelope)
-        };
+          rewriteRaw: JSON.stringify({
+            version: latestSchema.version,
+            payload: migrated
+          }),
+          persistedVersion: envelope.version,
+          latestVersion: latestSchema.version,
+          serializeForPersist: encodeForWrite
+        });
       } catch (err) {
         const typedErr = err instanceof SchemaError || err instanceof CodecError ? err : new SchemaError("MIGRATION_FAILED", `Migration failed for key "${key}"`, err);
         return { value: getFallback(typedErr) };
       }
     },
     [
+      applyReconcile,
       codec,
       decodeStringPayload,
+      encodeForWrite,
       getFallback,
       key,
       parseEnvelope,
@@ -817,61 +1107,6 @@ function useMnemonicKey(key, options) {
       validateAgainstSchema
     ]
   );
-  const encodeForWrite = react.useCallback(
-    (nextValue) => {
-      const explicitVersion = schema?.version;
-      const latestSchema = getLatestSchemaForKey();
-      const explicitSchema = explicitVersion !== void 0 ? getSchemaForVersion(explicitVersion) : void 0;
-      let targetSchema = explicitSchema;
-      if (!targetSchema) {
-        if (explicitVersion !== void 0) {
-          if (schemaMode !== "strict") {
-            targetSchema = latestSchema;
-          }
-        } else {
-          targetSchema = latestSchema;
-        }
-      }
-      if (!targetSchema) {
-        if (explicitVersion !== void 0 && schemaMode === "strict") {
-          throw new SchemaError(
-            "WRITE_SCHEMA_REQUIRED",
-            `Write requires schema for key "${key}" in strict mode`
-          );
-        }
-        const envelope2 = {
-          version: 0,
-          payload: codec.encode(nextValue)
-        };
-        return JSON.stringify(envelope2);
-      }
-      let valueToStore = nextValue;
-      const writeMigration = schemaRegistry?.getWriteMigration?.(key, targetSchema.version);
-      if (writeMigration) {
-        try {
-          valueToStore = writeMigration.migrate(valueToStore);
-        } catch (err) {
-          throw err instanceof SchemaError ? err : new SchemaError("MIGRATION_FAILED", `Write-time migration failed for key "${key}"`, err);
-        }
-      }
-      validateAgainstSchema(valueToStore, targetSchema.schema);
-      const envelope = {
-        version: targetSchema.version,
-        payload: valueToStore
-      };
-      return JSON.stringify(envelope);
-    },
-    [
-      schema?.version,
-      key,
-      schemaMode,
-      codec,
-      schemaRegistry,
-      validateAgainstSchema,
-      getLatestSchemaForKey,
-      getSchemaForVersion
-    ]
-  );
   const raw = react.useSyncExternalStore(
     (listener) => api.subscribeRaw(key, listener),
     () => api.getRawSnapshot(key),
@@ -983,6 +1218,254 @@ function useMnemonicKey(key, options) {
     [value, set, reset, remove]
   );
 }
+function uniqueKeys(keys) {
+  return [...new Set(keys)];
+}
+function useMnemonicRecovery(options = {}) {
+  const api = useMnemonic();
+  const { onRecover } = options;
+  const namespace = react.useMemo(() => api.prefix.endsWith(".") ? api.prefix.slice(0, -1) : api.prefix, [api.prefix]);
+  const emitRecovery = react.useCallback(
+    (action, clearedKeys) => {
+      const event = {
+        action,
+        namespace,
+        clearedKeys
+      };
+      onRecover?.(event);
+    },
+    [namespace, onRecover]
+  );
+  const listKeys = react.useCallback(() => api.keys(), [api]);
+  const clearResolvedKeys = react.useCallback(
+    (action, keys) => {
+      const clearedKeys = uniqueKeys(keys);
+      for (const key of clearedKeys) {
+        api.removeRaw(key);
+      }
+      emitRecovery(action, clearedKeys);
+      return clearedKeys;
+    },
+    [api, emitRecovery]
+  );
+  const clearKeys = react.useCallback(
+    (keys) => clearResolvedKeys("clear-keys", keys),
+    [clearResolvedKeys]
+  );
+  const clearAll = react.useCallback(() => {
+    if (!api.canEnumerateKeys) {
+      throw new Error(
+        "clearAll requires an enumerable storage backend. Use clearKeys([...]) with an explicit key list instead."
+      );
+    }
+    return clearResolvedKeys("clear-all", api.keys());
+  }, [api, clearResolvedKeys]);
+  const clearMatching = react.useCallback(
+    (predicate) => {
+      if (!api.canEnumerateKeys) {
+        throw new Error(
+          "clearMatching requires an enumerable storage backend. Use clearKeys([...]) with an explicit key list instead."
+        );
+      }
+      return clearResolvedKeys(
+        "clear-matching",
+        api.keys().filter((key) => predicate(key))
+      );
+    },
+    [api, clearResolvedKeys]
+  );
+  return react.useMemo(
+    () => ({
+      namespace,
+      canEnumerateKeys: api.canEnumerateKeys,
+      listKeys,
+      clearAll,
+      clearKeys,
+      clearMatching
+    }),
+    [namespace, api.canEnumerateKeys, listKeys, clearAll, clearKeys, clearMatching]
+  );
+}
+
+// src/Mnemonic/schema-registry.ts
+function schemaVersionKey(key, version) {
+  return `${key}:${version}`;
+}
+function migrationVersionKey(key, fromVersion) {
+  return `${key}:${fromVersion}`;
+}
+function validateVersion(value, label) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new SchemaError("MIGRATION_GRAPH_INVALID", `${label} must be a non-negative integer`);
+  }
+}
+function createSchemaRegistry(options = {}) {
+  const { schemas = [], migrations = [] } = options;
+  const schemasByKeyAndVersion = /* @__PURE__ */ new Map();
+  const latestSchemaByKey = /* @__PURE__ */ new Map();
+  const writeMigrationsByKeyAndVersion = /* @__PURE__ */ new Map();
+  const migrationsByKeyAndFromVersion = /* @__PURE__ */ new Map();
+  for (const schema of schemas) {
+    validateVersion(schema.version, `Schema version for key "${schema.key}"`);
+    const id = schemaVersionKey(schema.key, schema.version);
+    if (schemasByKeyAndVersion.has(id)) {
+      throw new SchemaError(
+        "SCHEMA_REGISTRATION_CONFLICT",
+        `Duplicate schema registered for key "${schema.key}" version ${schema.version}`
+      );
+    }
+    schemasByKeyAndVersion.set(id, schema);
+    const currentLatest = latestSchemaByKey.get(schema.key);
+    if (!currentLatest || schema.version > currentLatest.version) {
+      latestSchemaByKey.set(schema.key, schema);
+    }
+  }
+  for (const migration of migrations) {
+    validateVersion(migration.fromVersion, `Migration fromVersion for key "${migration.key}"`);
+    validateVersion(migration.toVersion, `Migration toVersion for key "${migration.key}"`);
+    if (migration.toVersion < migration.fromVersion) {
+      throw new SchemaError(
+        "MIGRATION_GRAPH_INVALID",
+        `Backward migration "${migration.key}" ${migration.fromVersion} -> ${migration.toVersion} is not supported`
+      );
+    }
+    if (migration.fromVersion === migration.toVersion) {
+      const id = schemaVersionKey(migration.key, migration.fromVersion);
+      if (writeMigrationsByKeyAndVersion.has(id)) {
+        throw new SchemaError(
+          "MIGRATION_GRAPH_INVALID",
+          `Duplicate write migration registered for key "${migration.key}" version ${migration.fromVersion}`
+        );
+      }
+      writeMigrationsByKeyAndVersion.set(id, migration);
+      continue;
+    }
+    const edgeKey = migrationVersionKey(migration.key, migration.fromVersion);
+    if (migrationsByKeyAndFromVersion.has(edgeKey)) {
+      const existing = migrationsByKeyAndFromVersion.get(edgeKey);
+      throw new SchemaError(
+        "MIGRATION_GRAPH_INVALID",
+        `Ambiguous migration graph for key "${migration.key}" at version ${migration.fromVersion}: ${existing.fromVersion} -> ${existing.toVersion} conflicts with ${migration.fromVersion} -> ${migration.toVersion}`
+      );
+    }
+    migrationsByKeyAndFromVersion.set(edgeKey, migration);
+  }
+  return {
+    getSchema(key, version) {
+      return schemasByKeyAndVersion.get(schemaVersionKey(key, version));
+    },
+    getLatestSchema(key) {
+      return latestSchemaByKey.get(key);
+    },
+    getMigrationPath(key, fromVersion, toVersion) {
+      if (fromVersion === toVersion) return [];
+      if (toVersion < fromVersion) return null;
+      const path = [];
+      let currentVersion = fromVersion;
+      while (currentVersion < toVersion) {
+        const next = migrationsByKeyAndFromVersion.get(migrationVersionKey(key, currentVersion));
+        if (!next) return null;
+        path.push(next);
+        currentVersion = next.toVersion;
+      }
+      return currentVersion === toVersion ? path : null;
+    },
+    getWriteMigration(key, version) {
+      return writeMigrationsByKeyAndVersion.get(schemaVersionKey(key, version));
+    }
+  };
+}
+
+// src/Mnemonic/structural-migrations.ts
+function resolveHelpers(helpers) {
+  if (helpers) return helpers;
+  return {
+    getId: (node) => node.id,
+    getChildren: (node) => node.children,
+    withChildren: (node, children) => ({ ...node, children }),
+    withId: (node, id) => ({ ...node, id })
+  };
+}
+function findNodeById(root, id, helpers) {
+  const tree = resolveHelpers(helpers);
+  if (tree.getId(root) === id) return root;
+  for (const child of tree.getChildren(root) ?? []) {
+    const match = findNodeById(child, id, tree);
+    if (match) return match;
+  }
+  return void 0;
+}
+function insertChildIfMissing(root, parentId, child, helpers) {
+  const tree = resolveHelpers(helpers);
+  const childId = tree.getId(child);
+  const visit = (node) => {
+    if (tree.getId(node) === parentId) {
+      const children2 = [...tree.getChildren(node) ?? []];
+      if (children2.some((existing) => tree.getId(existing) === childId)) {
+        return [node, false];
+      }
+      return [tree.withChildren(node, [...children2, child]), true];
+    }
+    const children = tree.getChildren(node);
+    if (!children?.length) return [node, false];
+    let inserted = false;
+    let changed = false;
+    const nextChildren = children.map((existingChild) => {
+      if (inserted) return existingChild;
+      const [nextChild, didInsert] = visit(existingChild);
+      inserted || (inserted = didInsert);
+      changed || (changed = nextChild !== existingChild);
+      return nextChild;
+    });
+    if (!changed) return [node, inserted];
+    return [tree.withChildren(node, nextChildren), inserted];
+  };
+  return visit(root)[0];
+}
+function renameNode(root, currentId, nextId, helpers) {
+  const tree = resolveHelpers(helpers);
+  if (currentId === nextId) return root;
+  if (!findNodeById(root, currentId, tree)) return root;
+  if (findNodeById(root, nextId, tree)) return root;
+  const visit = (node) => {
+    let nextNode = tree.getId(node) === currentId ? tree.withId(node, nextId) : node;
+    const children = tree.getChildren(nextNode);
+    if (!children?.length) return nextNode;
+    let changed = nextNode !== node;
+    const nextChildren = children.map((child) => {
+      const nextChild = visit(child);
+      changed || (changed = nextChild !== child);
+      return nextChild;
+    });
+    if (!changed) return node;
+    return tree.withChildren(nextNode, nextChildren);
+  };
+  return visit(root);
+}
+function dedupeChildrenBy(root, getKey, helpers) {
+  const tree = resolveHelpers(helpers);
+  const visit = (node) => {
+    const children = tree.getChildren(node);
+    if (!children?.length) return node;
+    let changed = false;
+    const seen = /* @__PURE__ */ new Set();
+    const nextChildren = [];
+    for (const child of children) {
+      const normalizedChild = visit(child);
+      changed || (changed = normalizedChild !== child);
+      const key = getKey(normalizedChild);
+      if (seen.has(key)) {
+        changed = true;
+        continue;
+      }
+      seen.add(key);
+      nextChildren.push(normalizedChild);
+    }
+    if (!changed && nextChildren.length === children.length) return node;
+    return tree.withChildren(node, nextChildren);
+  };
+  return visit(root);
+}
 
 exports.CodecError = CodecError;
 exports.JSONCodec = JSONCodec;
@@ -990,7 +1473,13 @@ exports.MnemonicProvider = MnemonicProvider;
 exports.SchemaError = SchemaError;
 exports.compileSchema = compileSchema;
 exports.createCodec = createCodec;
+exports.createSchemaRegistry = createSchemaRegistry;
+exports.dedupeChildrenBy = dedupeChildrenBy;
+exports.findNodeById = findNodeById;
+exports.insertChildIfMissing = insertChildIfMissing;
+exports.renameNode = renameNode;
 exports.useMnemonicKey = useMnemonicKey;
+exports.useMnemonicRecovery = useMnemonicRecovery;
 exports.validateJsonSchema = validateJsonSchema;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map