react-mnemonic 1.1.0-beta0 → 1.2.0-beta1

package/dist/index.js

@@ -1,4 +1,4 @@
-import { createContext, useMemo, useEffect, useState, useCallback, useSyncExternalStore, useRef, useContext } from 'react';
+import { createContext, useMemo, useEffect, useCallback, useContext, useState, useSyncExternalStore, useRef } from 'react';
 import { jsx } from 'react/jsx-runtime';
 
 // src/Mnemonic/provider.tsx
@@ -1016,8 +1016,6 @@ function inferJsonSchema(sample) {
       return {};
   }
 }
-
-// src/Mnemonic/use.ts
 var SSR_SNAPSHOT_TOKEN = /* @__PURE__ */ Symbol("mnemonic:ssr-snapshot");
 var diagnosticContractRegistry = /* @__PURE__ */ new WeakMap();
 var diagnosticWarningRegistry = /* @__PURE__ */ new WeakMap();
@@ -1029,10 +1027,12 @@ function serializeEnvelope(version, payload) {
     payload
   });
 }
-function withReadMetadata(value, rewriteRaw, pendingSchema) {
+function withReadMetadata(value, rewriteRaw, extra) {
   const result = { value };
+  if (extra !== void 0) {
+    Object.assign(result, extra);
+  }
   if (rewriteRaw !== void 0) result.rewriteRaw = rewriteRaw;
-  if (pendingSchema !== void 0) result.pendingSchema = pendingSchema;
   return result;
 }
 function isDevelopmentRuntime() {
@@ -1093,7 +1093,7 @@ function buildContractFingerprint({
   key,
   defaultValue,
   codecOpt,
-  schema,
+  schemaVersion,
   reconcile,
   listenCrossTab,
   ssrOptions
@@ -1104,7 +1104,7 @@ function buildContractFingerprint({
     key,
     defaultValue: stableDiagnosticValue(defaultValue),
     codec: codecSignature,
-    schemaVersion: schema?.version ?? null,
+    schemaVersion: schemaVersion ?? null,
     listenCrossTab: Boolean(listenCrossTab),
     reconcile: reconcileSignature,
     ssrHydration: ssrOptions?.hydration ?? null,
@@ -1124,7 +1124,7 @@ function resolveMnemonicKeyArgs(keyOrDescriptor, options) {
     options
   };
 }
-function useMnemonicKey(keyOrDescriptor, options) {
+function useMnemonicKeyShared(keyOrDescriptor, options, schemaVersion) {
   const descriptor = resolveMnemonicKeyArgs(keyOrDescriptor, options);
   const key = descriptor.key;
   const resolvedOptions = descriptor.options;
@@ -1140,8 +1140,6 @@ function useMnemonicKey(keyOrDescriptor, options) {
     ssr: ssrOptions
   } = resolvedOptions;
   const codec = codecOpt ?? JSONCodec;
-  const schemaMode = api.schemaMode;
-  const schemaRegistry = api.schemaRegistry;
   const hydrationMode = ssrOptions?.hydration ?? api.ssrHydration;
   const [hasMounted, setHasMounted] = useState(hydrationMode !== "client-only");
   const developmentRuntime = isDevelopmentRuntime();
@@ -1151,7 +1149,7 @@ function useMnemonicKey(keyOrDescriptor, options) {
       key,
       defaultValue,
       codecOpt,
-      schema,
+      ...schemaVersion === void 0 ? {} : { schemaVersion },
       reconcile,
       listenCrossTab,
       ssrOptions
@@ -1162,7 +1160,7 @@ function useMnemonicKey(keyOrDescriptor, options) {
       key,
       defaultValue,
       codecOpt,
-      schema?.version,
+      schemaVersion,
       reconcile,
       listenCrossTab,
       ssrOptions?.hydration,
@@ -1210,9 +1208,282 @@ function useMnemonicKey(keyOrDescriptor, options) {
     },
     [key]
   );
+  const buildFallbackResult = useCallback(
+    (error, extra) => {
+      return withReadMetadata(getFallback(error), void 0, extra);
+    },
+    [getFallback]
+  );
+  return {
+    api,
+    key,
+    codec,
+    codecOpt,
+    schema,
+    reconcile,
+    onMount,
+    onChange,
+    listenCrossTab,
+    getFallback,
+    getServerValue,
+    parseEnvelope,
+    decodeStringPayload,
+    buildFallbackResult,
+    developmentRuntime,
+    contractFingerprint,
+    hasMounted,
+    setHasMounted,
+    hydrationMode,
+    ssrOptions
+  };
+}
+function useApplyReconcile({
+  key,
+  reconcile,
+  buildFallbackResult
+}) {
+  return useCallback(
+    ({
+      value,
+      rewriteRaw,
+      extra,
+      persistedVersion,
+      latestVersion,
+      serializeForPersist,
+      deriveExtra
+    }) => {
+      if (!reconcile) {
+        return withReadMetadata(value, rewriteRaw, extra);
+      }
+      const context = {
+        key,
+        persistedVersion
+      };
+      if (latestVersion !== void 0) {
+        context.latestVersion = latestVersion;
+      }
+      const baselineSerialized = (() => {
+        try {
+          return serializeForPersist(value);
+        } catch {
+          return rewriteRaw;
+        }
+      })();
+      try {
+        const reconciled = reconcile(value, context);
+        const nextExtra = deriveExtra ? deriveExtra(reconciled, extra) : extra;
+        const nextSerialized = serializeForPersist(reconciled);
+        const nextRewriteRaw = baselineSerialized === void 0 || nextSerialized !== baselineSerialized ? nextSerialized : rewriteRaw;
+        return withReadMetadata(reconciled, nextRewriteRaw, nextExtra);
+      } catch (err) {
+        const typedErr = err instanceof SchemaError ? err : new SchemaError("RECONCILE_FAILED", `Reconciliation failed for key "${key}"`, err);
+        return buildFallbackResult(typedErr, extra);
+      }
+    },
+    [buildFallbackResult, key, reconcile]
+  );
+}
+function useMnemonicKeyState(shared, config) {
+  const {
+    api,
+    key,
+    codecOpt,
+    schema,
+    onMount,
+    onChange,
+    listenCrossTab,
+    getFallback,
+    getServerValue,
+    developmentRuntime,
+    contractFingerprint,
+    hasMounted,
+    setHasMounted,
+    hydrationMode,
+    ssrOptions
+  } = shared;
+  const { decodeForRead, encodeForWrite, additionalDevWarnings, onDecodedEffect } = config;
+  const getServerRawSnapshot = useCallback(
+    () => ssrOptions?.serverValue === void 0 ? null : SSR_SNAPSHOT_TOKEN,
+    [ssrOptions?.serverValue]
+  );
+  const deferStorageRead = hydrationMode === "client-only" && !hasMounted;
+  const subscribe = useCallback(
+    (listener) => {
+      if (deferStorageRead) {
+        return () => void 0;
+      }
+      return api.subscribeRaw(key, listener);
+    },
+    [api, deferStorageRead, key]
+  );
+  const raw = useSyncExternalStore(
+    subscribe,
+    () => deferStorageRead ? getServerRawSnapshot() : api.getRawSnapshot(key),
+    getServerRawSnapshot
+  );
+  const decoded = useMemo(() => {
+    if (raw === SSR_SNAPSHOT_TOKEN) {
+      return withReadMetadata(getServerValue());
+    }
+    return decodeForRead(raw);
+  }, [decodeForRead, getServerValue, raw]);
+  const value = decoded.value;
+  useEffect(() => {
+    if (!developmentRuntime) return;
+    const globalWindow = globalThis.window;
+    if (listenCrossTab && (api.crossTabSyncMode ?? "none") === "none" && globalWindow !== void 0) {
+      warnOnce(
+        api,
+        `listenCrossTab:${key}`,
+        `[Mnemonic] useMnemonicKey("${key}") enabled listenCrossTab, but the active storage backend may not be able to notify external changes. If you're using a custom Storage-like wrapper around localStorage, ensure it forwards browser "storage" events or implements storage.onExternalChange(...); otherwise, use localStorage or implement storage.onExternalChange(...) on your custom backend.`
+      );
+    }
+    additionalDevWarnings?.({
+      api,
+      key,
+      listenCrossTab,
+      codecOpt,
+      schema,
+      warnOnce: (id, message) => warnOnce(api, id, message)
+    });
+    let keyContracts = diagnosticContractRegistry.get(api);
+    if (!keyContracts) {
+      keyContracts = /* @__PURE__ */ new Map();
+      diagnosticContractRegistry.set(api, keyContracts);
+    }
+    if (contractFingerprint === null) {
+      return;
+    }
+    const previousContract = keyContracts.get(key);
+    if (previousContract === void 0) {
+      keyContracts.set(key, contractFingerprint);
+      return;
+    }
+    if (previousContract === contractFingerprint) {
+      return;
+    }
+    warnOnce(
+      api,
+      `contract-conflict:${key}`,
+      `[Mnemonic] Conflicting useMnemonicKey contracts detected for key "${key}" in namespace "${api.prefix.slice(0, -1)}". Reuse a shared descriptor with defineMnemonicKey(...) or align defaultValue/codec/schema/reconcile options so every consumer describes the same persisted contract.`
+    );
+  }, [
+    additionalDevWarnings,
+    api,
+    key,
+    developmentRuntime,
+    contractFingerprint,
+    listenCrossTab,
+    codecOpt,
+    schema,
+    api.crossTabSyncMode
+  ]);
+  useEffect(() => {
+    if (hasMounted) return;
+    setHasMounted(true);
+  }, [hasMounted, setHasMounted]);
+  useEffect(() => {
+    if (decoded.rewriteRaw && decoded.rewriteRaw !== raw) {
+      api.setRaw(key, decoded.rewriteRaw);
+    }
+  }, [api, decoded.rewriteRaw, key, raw]);
+  useEffect(() => {
+    onDecodedEffect?.(decoded);
+  }, [decoded, onDecodedEffect]);
+  const prevRef = useRef(value);
+  const mounted = useRef(false);
+  useEffect(() => {
+    if (mounted.current) return;
+    mounted.current = true;
+    onMount?.(value);
+    prevRef.current = value;
+  }, []);
+  useEffect(() => {
+    const prev = prevRef.current;
+    if (Object.is(prev, value)) return;
+    prevRef.current = value;
+    onChange?.(value, prev);
+  }, [value, onChange]);
+  useEffect(() => {
+    if (!listenCrossTab) return;
+    const globalWindow = globalThis.window;
+    if (globalWindow === void 0) return;
+    const storageKey = api.prefix + key;
+    const handler = (e) => {
+      if (e.key === null) {
+        api.removeRaw(key);
+        return;
+      }
+      if (e.key !== storageKey) return;
+      if (e.newValue == null) {
+        api.removeRaw(key);
+        return;
+      }
+      api.setRaw(key, e.newValue);
+    };
+    globalWindow.addEventListener("storage", handler);
+    return () => globalWindow.removeEventListener("storage", handler);
+  }, [listenCrossTab, api, key]);
+  const set = useMemo(() => {
+    return (next) => {
+      const nextVal = typeof next === "function" ? next(decodeForRead(api.getRawSnapshot(key)).value) : next;
+      try {
+        const encoded = encodeForWrite(nextVal);
+        api.setRaw(key, encoded);
+      } catch (err) {
+        if (err instanceof SchemaError) {
+          console.error(`[Mnemonic] Schema error for key "${key}" (${err.code}):`, err.message);
+          return;
+        }
+        if (err instanceof CodecError) {
+          console.error(`[Mnemonic] Codec encode error for key "${key}":`, err.message);
+          return;
+        }
+        console.error(`[Mnemonic] Failed to persist key "${key}":`, err);
+      }
+    };
+  }, [api, key, decodeForRead, encodeForWrite]);
+  const reset = useMemo(() => {
+    return () => {
+      const v = getFallback();
+      try {
+        const encoded = encodeForWrite(v);
+        api.setRaw(key, encoded);
+      } catch (err) {
+        if (err instanceof SchemaError) {
+          console.error(`[Mnemonic] Schema error for key "${key}" (${err.code}):`, err.message);
+          return;
+        }
+        if (err instanceof CodecError) {
+          console.error(`[Mnemonic] Codec encode error for key "${key}":`, err.message);
+        }
+        return;
+      }
+    };
+  }, [api, key, getFallback, encodeForWrite]);
+  const remove = useMemo(() => {
+    return () => api.removeRaw(key);
+  }, [api, key]);
+  return useMemo(
+    () => ({
+      value,
+      set,
+      reset,
+      remove
+    }),
+    [value, set, reset, remove]
+  );
+}
+
+// src/Mnemonic/use.ts
+function useSchemaMnemonicKey(descriptor) {
+  const shared = useMnemonicKeyShared(descriptor, void 0, descriptor.options.schema?.version);
+  const { api, key, codec, codecOpt, schema, reconcile, parseEnvelope, decodeStringPayload, buildFallbackResult } = shared;
+  const schemaMode = api.schemaMode;
+  const schemaRegistry = api.schemaRegistry;
   const validateAgainstSchema = useCallback(
-    (value2, jsonSchema) => {
-      const errors = validateJsonSchema(value2, jsonSchema);
+    (value, jsonSchema) => {
+      const errors = validateJsonSchema(value, jsonSchema);
       if (errors.length > 0) {
         const message = errors.map((e) => `${e.path || "/"}: ${e.message}`).join("; ");
         throw new SchemaError("TYPE_MISMATCH", `Schema validation failed for key "${key}": ${message}`);
@@ -1236,9 +1507,9 @@ function useMnemonicKey(keyOrDescriptor, options) {
       if (registryCache.schemaByVersion.has(version)) {
         return registryCache.schemaByVersion.get(version);
       }
-      const s = schemaRegistry.getSchema(key, version);
-      registryCache.schemaByVersion.set(version, s);
-      return s;
+      const nextSchema = schemaRegistry.getSchema(key, version);
+      registryCache.schemaByVersion.set(version, nextSchema);
+      return nextSchema;
     },
     [schemaRegistry, registryCache, key]
   );
@@ -1246,10 +1517,10 @@ function useMnemonicKey(keyOrDescriptor, options) {
     if (!schemaRegistry) return void 0;
     if (!registryCache) return schemaRegistry.getLatestSchema(key);
     if (registryCache.latestSchemaSet) return registryCache.latestSchema;
-    const s = schemaRegistry.getLatestSchema(key);
-    registryCache.latestSchema = s;
+    const nextSchema = schemaRegistry.getLatestSchema(key);
+    registryCache.latestSchema = nextSchema;
     registryCache.latestSchemaSet = true;
-    return s;
+    return nextSchema;
   }, [schemaRegistry, registryCache, key]);
   const getMigrationPathForKey = useCallback(
     (fromVersion, toVersion) => {
@@ -1265,16 +1536,14 @@ function useMnemonicKey(keyOrDescriptor, options) {
     },
     [schemaRegistry, registryCache, key]
   );
-  const buildFallbackResult = useCallback(
-    (error) => ({
-      value: getFallback(error)
-    }),
-    [getFallback]
-  );
-  const buildSchemaManagedResult = useCallback(
-    (version, value2) => serializeEnvelope(version, value2),
-    []
-  );
+  const buildSchemaManagedResult = useCallback((version, value) => {
+    return serializeEnvelope(version, value);
+  }, []);
+  const applyReconcile = useApplyReconcile({
+    key,
+    reconcile,
+    buildFallbackResult
+  });
   const resolveTargetWriteSchema = useCallback(() => {
     const explicitVersion = schema?.version;
     const latestSchema = getLatestSchemaForKey();
@@ -1319,44 +1588,6 @@ function useMnemonicKey(keyOrDescriptor, options) {
       buildSchemaManagedResult
     ]
   );
-  const applyReconcile = useCallback(
-    ({
-      value: value2,
-      rewriteRaw,
-      pendingSchema,
-      persistedVersion,
-      latestVersion,
-      serializeForPersist,
-      derivePendingSchema
-    }) => {
-      if (!reconcile) {
-        return withReadMetadata(value2, rewriteRaw, pendingSchema);
-      }
-      const context = {
-        key,
-        persistedVersion,
-        ...latestVersion === void 0 ? {} : { latestVersion }
-      };
-      const baselineSerialized = (() => {
-        try {
-          return serializeForPersist(value2);
-        } catch {
-          return rewriteRaw;
-        }
-      })();
-      try {
-        const reconciled = reconcile(value2, context);
-        const nextPendingSchema = derivePendingSchema ? derivePendingSchema(reconciled) : pendingSchema;
-        const nextSerialized = serializeForPersist(reconciled);
-        const nextRewriteRaw = baselineSerialized === void 0 || nextSerialized !== baselineSerialized ? nextSerialized : rewriteRaw;
-        return withReadMetadata(reconciled, nextRewriteRaw, nextPendingSchema);
-      } catch (err) {
-        const typedErr = err instanceof SchemaError ? err : new SchemaError("RECONCILE_FAILED", `Reconciliation failed for key "${key}"`, err);
-        return buildFallbackResult(typedErr);
-      }
-    },
-    [buildFallbackResult, key, reconcile]
-  );
   const decodeAutoschemaEnvelope = useCallback(
     (envelope, latestSchema) => {
       if (latestSchema) {
@@ -1373,20 +1604,22 @@ function useMnemonicKey(keyOrDescriptor, options) {
         );
       }
       try {
-        const decoded2 = typeof envelope.payload === "string" ? decodeStringPayload(envelope.payload, codec) : envelope.payload;
-        const inferSchemaForValue = (value2) => ({
+        const decoded = typeof envelope.payload === "string" ? decodeStringPayload(envelope.payload, codec) : envelope.payload;
+        const inferSchemaForValue = (value) => ({
           key,
           version: 1,
-          schema: inferJsonSchema(value2)
+          schema: inferJsonSchema(value)
         });
-        const inferred = inferSchemaForValue(decoded2);
+        const inferred = inferSchemaForValue(decoded);
         return applyReconcile({
-          value: decoded2,
-          pendingSchema: inferred,
-          rewriteRaw: buildSchemaManagedResult(inferred.version, decoded2),
+          value: decoded,
+          extra: { pendingSchema: inferred },
+          rewriteRaw: buildSchemaManagedResult(inferred.version, decoded),
           persistedVersion: envelope.version,
-          serializeForPersist: (value2) => buildSchemaManagedResult(inferred.version, value2),
-          derivePendingSchema: inferSchemaForValue
+          serializeForPersist: (value) => buildSchemaManagedResult(inferred.version, value),
+          deriveExtra: (value) => ({
+            pendingSchema: inferSchemaForValue(value)
+          })
         });
       } catch (err) {
         const typedErr = err instanceof SchemaError || err instanceof CodecError ? err : new SchemaError("TYPE_MISMATCH", `Autoschema inference failed for key "${key}"`, err);
@@ -1414,9 +1647,9 @@ function useMnemonicKey(keyOrDescriptor, options) {
         });
       }
       try {
-        const decoded2 = decodeStringPayload(envelope.payload, codec);
+        const decoded = decodeStringPayload(envelope.payload, codec);
         return applyReconcile({
-          value: decoded2,
+          value: decoded,
           persistedVersion: envelope.version,
           ...latestSchema ? { latestVersion: latestSchema.version } : {},
           serializeForPersist: encodeForWrite
@@ -1511,194 +1744,40 @@ function useMnemonicKey(keyOrDescriptor, options) {
       parseEnvelope,
       schemaMode,
       getSchemaForVersion,
-      getLatestSchemaForKey
+      getLatestSchemaForKey,
+      key
     ]
   );
-  const getServerRawSnapshot = useCallback(
-    () => ssrOptions?.serverValue === void 0 ? null : SSR_SNAPSHOT_TOKEN,
-    [ssrOptions?.serverValue]
-  );
-  const deferStorageRead = hydrationMode === "client-only" && !hasMounted;
-  const subscribe = useCallback(
-    (listener) => {
-      if (deferStorageRead) {
-        return () => void 0;
-      }
-      return api.subscribeRaw(key, listener);
-    },
-    [api, deferStorageRead, key]
-  );
-  const raw = useSyncExternalStore(
-    subscribe,
-    () => deferStorageRead ? getServerRawSnapshot() : api.getRawSnapshot(key),
-    getServerRawSnapshot
-  );
-  const decoded = useMemo(() => {
-    if (raw === SSR_SNAPSHOT_TOKEN) {
-      return {
-        value: getServerValue(),
-        rewriteRaw: void 0,
-        pendingSchema: void 0
-      };
-    }
-    return decodeForRead(raw);
-  }, [decodeForRead, getServerValue, raw]);
-  const value = decoded.value;
-  useEffect(() => {
-    if (!developmentRuntime) return;
-    if (listenCrossTab && (api.crossTabSyncMode ?? "none") === "none" && globalThis.window !== void 0) {
-      warnOnce(
-        api,
-        `listenCrossTab:${key}`,
-        `[Mnemonic] useMnemonicKey("${key}") enabled listenCrossTab, but the active storage backend may not be able to notify external changes. If you're using a custom Storage-like wrapper around localStorage, ensure it forwards browser "storage" events or implements storage.onExternalChange(...); otherwise, use localStorage or implement storage.onExternalChange(...) on your custom backend.`
-      );
-    }
-    if (codecOpt && schema?.version !== void 0 && api.schemaRegistry) {
-      warnOnce(
-        api,
+  const additionalDevWarnings = useCallback(
+    ({ warnOnce: warnOnce2 }) => {
+      if (!codecOpt || schema?.version === void 0 || !api.schemaRegistry) return;
+      warnOnce2(
         `codec+schema:${key}`,
         `[Mnemonic] useMnemonicKey("${key}") received both a custom codec and schema.version. Schema-managed reads/writes do not use the codec path. Remove the codec for schema-managed storage, or remove schema.version if you intended codec-only persistence.`
       );
-    }
-    let keyContracts = diagnosticContractRegistry.get(api);
-    if (!keyContracts) {
-      keyContracts = /* @__PURE__ */ new Map();
-      diagnosticContractRegistry.set(api, keyContracts);
-    }
-    if (contractFingerprint === null) {
-      return;
-    }
-    const previousContract = keyContracts.get(key);
-    if (previousContract === void 0) {
-      keyContracts.set(key, contractFingerprint);
-      return;
-    }
-    if (previousContract === contractFingerprint) {
-      return;
-    }
-    warnOnce(
-      api,
-      `contract-conflict:${key}`,
-      `[Mnemonic] Conflicting useMnemonicKey contracts detected for key "${key}" in namespace "${api.prefix.slice(0, -1)}". Reuse a shared descriptor with defineMnemonicKey(...) or align defaultValue/codec/schema/reconcile options so every consumer describes the same persisted contract.`
-    );
-  }, [
-    api,
-    key,
-    developmentRuntime,
-    contractFingerprint,
-    listenCrossTab,
-    codecOpt,
-    schema?.version,
-    api.schemaRegistry,
-    api.crossTabSyncMode
-  ]);
-  useEffect(() => {
-    if (hasMounted) return;
-    setHasMounted(true);
-  }, [hasMounted]);
-  useEffect(() => {
-    if (decoded.rewriteRaw && decoded.rewriteRaw !== raw) {
-      api.setRaw(key, decoded.rewriteRaw);
-    }
-  }, [api, decoded.rewriteRaw, key, raw]);
-  useEffect(() => {
-    if (!decoded.pendingSchema || !schemaRegistry?.registerSchema) return;
-    if (schemaRegistry.getSchema(decoded.pendingSchema.key, decoded.pendingSchema.version)) return;
-    try {
-      schemaRegistry.registerSchema(decoded.pendingSchema);
-    } catch {
-    }
-  }, [decoded.pendingSchema, schemaRegistry]);
-  const prevRef = useRef(value);
-  const mounted = useRef(false);
-  useEffect(() => {
-    if (mounted.current) return;
-    mounted.current = true;
-    onMount?.(value);
-    prevRef.current = value;
-  }, []);
-  useEffect(() => {
-    const prev = prevRef.current;
-    if (Object.is(prev, value)) return;
-    prevRef.current = value;
-    onChange?.(value, prev);
-  }, [value, onChange]);
-  useEffect(() => {
-    if (!listenCrossTab) return;
-    const globalWindow = globalThis.window;
-    if (globalWindow === void 0) return;
-    const storageKey = api.prefix + key;
-    const handler = (e) => {
-      if (e.key === null) {
-        api.removeRaw(key);
-        return;
-      }
-      if (e.key !== storageKey) return;
-      if (e.newValue == null) {
-        api.removeRaw(key);
-        return;
-      }
-      api.setRaw(key, e.newValue);
-    };
-    globalWindow.addEventListener("storage", handler);
-    return () => globalWindow.removeEventListener("storage", handler);
-  }, [listenCrossTab, api, key]);
-  const set = useMemo(() => {
-    return (next) => {
-      const nextVal = typeof next === "function" ? next(decodeForRead(api.getRawSnapshot(key)).value) : next;
-      try {
-        const encoded = encodeForWrite(nextVal);
-        api.setRaw(key, encoded);
-      } catch (err) {
-        if (err instanceof SchemaError) {
-          console.error(`[Mnemonic] Schema error for key "${key}" (${err.code}):`, err.message);
-          return;
-        }
-        if (err instanceof CodecError) {
-          console.error(`[Mnemonic] Codec encode error for key "${key}":`, err.message);
-          return;
-        }
-        console.error(`[Mnemonic] Failed to persist key "${key}":`, err);
-      }
-    };
-  }, [api, key, decodeForRead, encodeForWrite]);
-  const reset = useMemo(() => {
-    return () => {
-      const v = getFallback();
+    },
+    [api.schemaRegistry, codecOpt, key, schema?.version]
+  );
+  const onDecodedEffect = useCallback(
+    (decoded) => {
+      if (!decoded.pendingSchema || !schemaRegistry?.registerSchema) return;
+      if (schemaRegistry.getSchema(decoded.pendingSchema.key, decoded.pendingSchema.version)) return;
       try {
-        const encoded = encodeForWrite(v);
-        api.setRaw(key, encoded);
-      } catch (err) {
-        if (err instanceof SchemaError) {
-          console.error(`[Mnemonic] Schema error for key "${key}" (${err.code}):`, err.message);
-          return;
-        }
-        if (err instanceof CodecError) {
-          console.error(`[Mnemonic] Codec encode error for key "${key}":`, err.message);
-        }
-        return;
+        schemaRegistry.registerSchema(decoded.pendingSchema);
+      } catch {
       }
-    };
-  }, [api, key, getFallback, encodeForWrite]);
-  const remove = useMemo(() => {
-    return () => api.removeRaw(key);
-  }, [api, key]);
-  return useMemo(
-    () => (
-      /** @see {@link UseMnemonicKeyOptions} for configuration details */
-      {
-        /** Current decoded value, or the default when the key is absent or invalid. */
-        value,
-        /** Persist a new value (direct or updater function). */
-        set,
-        /** Reset to `defaultValue` and persist it. */
-        reset,
-        /** Delete the key from storage entirely. */
-        remove
-      }
-    ),
-    [value, set, reset, remove]
+    },
+    [schemaRegistry]
   );
+  return useMnemonicKeyState(shared, {
+    decodeForRead,
+    encodeForWrite,
+    additionalDevWarnings,
+    onDecodedEffect
+  });
+}
+function useMnemonicKey(keyOrDescriptor, options) {
+  return useSchemaMnemonicKey(resolveMnemonicKeyArgs(keyOrDescriptor, options));
 }
 function uniqueKeys(keys) {
   return [...new Set(keys)];