react-mnemonic 1.0.0-beta.0 → 1.1.0-beta0

package/dist/index.js

@@ -1,7 +1,33 @@
-import { createContext, useMemo, useEffect, useCallback, useSyncExternalStore, useRef, useContext } from 'react';
+import { createContext, useMemo, useEffect, useState, useCallback, useSyncExternalStore, useRef, useContext } from 'react';
 import { jsx } from 'react/jsx-runtime';
 
 // src/Mnemonic/provider.tsx
+
+// src/Mnemonic/runtime.ts
+function getGlobalProcess() {
+  return globalThis.process;
+}
+function getRuntimeNodeEnv() {
+  const runtimeProcess = getGlobalProcess();
+  if (runtimeProcess?.env?.NODE_ENV !== void 0) {
+    return runtimeProcess.env.NODE_ENV;
+  }
+  return void 0;
+}
+function getNativeBrowserStorages() {
+  const globalWindow = globalThis.window;
+  if (!globalWindow) return [];
+  const storages = [];
+  const addStorage = (getter) => {
+    try {
+      storages.push(getter());
+    } catch {
+    }
+  };
+  addStorage(() => globalWindow.localStorage);
+  addStorage(() => globalWindow.sessionStorage);
+  return storages;
+}
 var MnemonicContext = createContext(null);
 function useMnemonic() {
   const context = useContext(MnemonicContext);
@@ -11,20 +37,399 @@ function useMnemonic() {
   return context;
 }
 function defaultBrowserStorage() {
-  if (typeof window === "undefined") return void 0;
+  const globalWindow = globalThis.window;
+  if (globalWindow === void 0) return void 0;
   try {
-    return window.localStorage;
+    return globalWindow.localStorage;
   } catch {
     return void 0;
   }
 }
+function detectEnumerableStorage(storage) {
+  if (!storage) return false;
+  try {
+    return typeof storage.length === "number" && typeof storage.key === "function";
+  } catch {
+    return false;
+  }
+}
+function isProductionRuntime() {
+  const env = getRuntimeNodeEnv();
+  if (env === void 0) {
+    return true;
+  }
+  return env === "production";
+}
+function weakRefConstructor() {
+  const ctor = globalThis.WeakRef;
+  return typeof ctor === "function" ? ctor : null;
+}
+function hasFinalizationRegistry() {
+  return typeof globalThis.FinalizationRegistry === "function";
+}
+function isPromiseLike(value) {
+  if (value == null) return false;
+  if (typeof value !== "object" && typeof value !== "function") return false;
+  return typeof value.then === "function";
+}
+function getCrossTabSyncMode(requestedStorage, activeStorage) {
+  const isExplicitNativeBrowserStorage = activeStorage !== void 0 && requestedStorage !== void 0 && getNativeBrowserStorages().includes(activeStorage);
+  if (requestedStorage === void 0 && activeStorage !== void 0 || isExplicitNativeBrowserStorage) {
+    return "browser-storage-event";
+  }
+  if (typeof activeStorage?.onExternalChange === "function") {
+    return "custom-external-change";
+  }
+  return "none";
+}
+function getDevToolsWindow() {
+  return globalThis.window;
+}
+function sanitizeDevToolsRoot(root) {
+  const reserved = /* @__PURE__ */ new Set(["providers", "resolve", "list", "capabilities", "__meta"]);
+  for (const key of Object.keys(root)) {
+    if (reserved.has(key)) continue;
+    const descriptor = Object.getOwnPropertyDescriptor(root, key);
+    if (descriptor && !descriptor.configurable) continue;
+    try {
+      delete root[key];
+    } catch {
+    }
+  }
+}
+function ensureDevToolsRoot(enableDevTools) {
+  if (!enableDevTools) return null;
+  const globalWindow = getDevToolsWindow();
+  if (!globalWindow) return null;
+  const weakRefSupported = weakRefConstructor() !== null;
+  const finalizationRegistrySupported = hasFinalizationRegistry();
+  const existing = globalWindow.__REACT_MNEMONIC_DEVTOOLS__;
+  const root = existing && typeof existing === "object" ? existing : {};
+  sanitizeDevToolsRoot(root);
+  if (!root.providers || typeof root.providers !== "object") {
+    root.providers = {};
+  }
+  if (!root.capabilities || typeof root.capabilities !== "object") {
+    root.capabilities = {};
+  }
+  const capabilities = root.capabilities;
+  capabilities.weakRef = weakRefSupported;
+  capabilities.finalizationRegistry = finalizationRegistrySupported;
+  if (!root.__meta || typeof root.__meta !== "object") {
+    root.__meta = {
+      version: 0,
+      lastUpdated: Date.now(),
+      lastChange: ""
+    };
+  }
+  const meta = root.__meta;
+  if (typeof meta.version !== "number" || !Number.isFinite(meta.version)) {
+    meta.version = 0;
+  }
+  if (typeof meta.lastUpdated !== "number" || !Number.isFinite(meta.lastUpdated)) {
+    meta.lastUpdated = Date.now();
+  }
+  if (typeof meta.lastChange !== "string") {
+    meta.lastChange = "";
+  }
+  const providers = root.providers;
+  if (typeof root.resolve !== "function") {
+    root.resolve = (namespace) => {
+      const entry = providers[namespace];
+      if (!entry || typeof entry.weakRef?.deref !== "function") return null;
+      const live = entry.weakRef.deref();
+      if (live) {
+        entry.lastSeenAt = Date.now();
+        entry.staleSince = null;
+        return live;
+      }
+      entry.staleSince ?? (entry.staleSince = Date.now());
+      return null;
+    };
+  }
+  if (typeof root.list !== "function") {
+    root.list = () => Object.entries(providers).map(([namespace, entry]) => {
+      const live = typeof entry.weakRef?.deref === "function" ? entry.weakRef.deref() : void 0;
+      const available = Boolean(live);
+      if (available) {
+        entry.lastSeenAt = Date.now();
+        entry.staleSince = null;
+      } else {
+        entry.staleSince ?? (entry.staleSince = Date.now());
+      }
+      return {
+        namespace,
+        available,
+        registeredAt: entry.registeredAt,
+        lastSeenAt: entry.lastSeenAt,
+        staleSince: entry.staleSince
+      };
+    }).sort((left, right) => left.namespace.localeCompare(right.namespace));
+  }
+  globalWindow.__REACT_MNEMONIC_DEVTOOLS__ = root;
+  return root;
+}
+function bumpDevToolsVersion(root, namespace, reason) {
+  if (!root) return;
+  root.__meta.version += 1;
+  root.__meta.lastUpdated = Date.now();
+  root.__meta.lastChange = `${namespace}.${reason}`;
+}
+function decodeDevToolsValue(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+function readStorageRaw(storage, storageKey, callbacks) {
+  if (!storage) return null;
+  try {
+    const raw = storage.getItem(storageKey);
+    if (isPromiseLike(raw)) {
+      callbacks.onAsyncViolation("getItem", raw);
+      return null;
+    }
+    callbacks.onAccessSuccess();
+    return raw;
+  } catch (error) {
+    callbacks.onAccessError(error);
+    return null;
+  }
+}
+function enumerateNamespaceKeys(storage, prefix, callbacks) {
+  if (!storage) {
+    return [];
+  }
+  const keys = [];
+  try {
+    const storageLength = storage.length;
+    const getStorageKey = storage.key;
+    if (typeof storageLength !== "number" || typeof getStorageKey !== "function") {
+      return [];
+    }
+    for (let index = 0; index < storageLength; index++) {
+      const fullKey = getStorageKey.call(storage, index);
+      if (!fullKey?.startsWith(prefix)) continue;
+      keys.push(fullKey.slice(prefix.length));
+    }
+    callbacks.onAccessSuccess();
+  } catch (error) {
+    callbacks.onAccessError(error);
+  }
+  return keys;
+}
+function syncCacheEntryFromStorage({
+  key,
+  storageKey,
+  storage,
+  cache,
+  emit,
+  callbacks
+}) {
+  const fresh = readStorageRaw(storage, storageKey, callbacks);
+  const cached = cache.get(key) ?? null;
+  if (fresh === cached) {
+    return false;
+  }
+  cache.set(key, fresh);
+  emit(key);
+  return true;
+}
+function reloadNamedKeysFromStorage({
+  changedKeys,
+  prefix,
+  storage,
+  listeners,
+  cache,
+  emit,
+  callbacks
+}) {
+  let changed = false;
+  for (const fullStorageKey of changedKeys) {
+    if (!fullStorageKey.startsWith(prefix)) continue;
+    const key = fullStorageKey.slice(prefix.length);
+    const listenerSet = listeners.get(key);
+    if (listenerSet && listenerSet.size > 0) {
+      changed = syncCacheEntryFromStorage({
+        key,
+        storageKey: fullStorageKey,
+        storage,
+        cache,
+        emit,
+        callbacks
+      }) || changed;
+      continue;
+    }
+    if (cache.has(key)) {
+      cache.delete(key);
+    }
+  }
+  return changed;
+}
+function reloadSubscribedKeysFromStorage({
+  prefix,
+  storage,
+  listeners,
+  cache,
+  emit,
+  callbacks
+}) {
+  let changed = false;
+  for (const [key, listenerSet] of listeners) {
+    if (listenerSet.size === 0) continue;
+    changed = syncCacheEntryFromStorage({
+      key,
+      storageKey: `${prefix}${key}`,
+      storage,
+      cache,
+      emit,
+      callbacks
+    }) || changed;
+  }
+  for (const key of cache.keys()) {
+    const listenerSet = listeners.get(key);
+    if (listenerSet && listenerSet.size > 0) continue;
+    cache.delete(key);
+  }
+  return changed;
+}
+function createDevToolsProviderApi({
+  store,
+  dump,
+  keys,
+  readThrough,
+  writeRaw,
+  removeRaw
+}) {
+  return {
+    getStore: () => store,
+    dump: () => {
+      const data = dump();
+      console.table(
+        Object.entries(data).map(([key, value]) => ({
+          key,
+          value,
+          decoded: decodeDevToolsValue(value)
+        }))
+      );
+      return data;
+    },
+    get: (key) => {
+      const raw = readThrough(key);
+      if (raw == null) return void 0;
+      return decodeDevToolsValue(raw);
+    },
+    set: (key, value) => {
+      writeRaw(key, JSON.stringify(value));
+    },
+    remove: (key) => removeRaw(key),
+    clear: () => {
+      for (const key of keys()) {
+        removeRaw(key);
+      }
+    },
+    keys
+  };
+}
+function createReloadFromStorage({
+  storage,
+  hasAsyncContractViolation,
+  prefix,
+  listeners,
+  cache,
+  emit,
+  callbacks,
+  devToolsRoot,
+  namespace
+}) {
+  return (changedKeys) => {
+    if (!storage || hasAsyncContractViolation()) return;
+    if (changedKeys?.length === 0) return;
+    const isFullReload = changedKeys === void 0;
+    const changed = isFullReload ? reloadSubscribedKeysFromStorage({
+      prefix,
+      storage,
+      listeners,
+      cache,
+      emit,
+      callbacks
+    }) : reloadNamedKeysFromStorage({
+      changedKeys,
+      prefix,
+      storage,
+      listeners,
+      cache,
+      emit,
+      callbacks
+    });
+    if (changed) {
+      bumpDevToolsVersion(devToolsRoot, namespace, isFullReload ? "reload:full" : "reload:granular");
+    }
+  };
+}
+function registerDevToolsProvider({
+  devToolsRoot,
+  namespace,
+  store,
+  dump,
+  keys,
+  readThrough,
+  writeRaw,
+  removeRaw
+}) {
+  let infoMessage = `[Mnemonic DevTools] Namespace "${namespace}" available via window.__REACT_MNEMONIC_DEVTOOLS__.resolve("${namespace}")`;
+  if (!devToolsRoot.capabilities.weakRef) {
+    console.info(
+      `[Mnemonic DevTools] WeakRef is not available; registry provider "${namespace}" was not registered.`
+    );
+    return;
+  }
+  const existingLive = devToolsRoot.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.`);
+    console.info(
+      `[Mnemonic DevTools] Namespace "${namespace}" already registered. Keeping existing provider reference.`
+    );
+    return;
+  }
+  const providerApi = createDevToolsProviderApi({
+    store,
+    dump,
+    keys,
+    readThrough,
+    writeRaw,
+    removeRaw
+  });
+  const WeakRefCtor = weakRefConstructor();
+  if (!WeakRefCtor) {
+    console.info(`[Mnemonic DevTools] WeakRef became unavailable while registering "${namespace}".`);
+    return;
+  }
+  store.__devToolsProviderApiHold = providerApi;
+  const now = Date.now();
+  devToolsRoot.providers[namespace] = {
+    namespace,
+    weakRef: new WeakRefCtor(providerApi),
+    registeredAt: now,
+    lastSeenAt: now,
+    staleSince: null
+  };
+  bumpDevToolsVersion(devToolsRoot, namespace, "registry:namespace-registered");
+  console.info(infoMessage);
+}
 function MnemonicProvider({
   children,
   namespace,
   storage,
   enableDevTools = false,
   schemaMode = "default",
-  schemaRegistry
+  schemaRegistry,
+  ssr
 }) {
   if (schemaMode === "strict" && !schemaRegistry) {
     throw new Error("MnemonicProvider strict mode requires schemaRegistry");
@@ -35,124 +440,21 @@ function MnemonicProvider({
   const store = useMemo(() => {
     const prefix = `${namespace}.`;
     const st = storage ?? defaultBrowserStorage();
+    const ssrHydration = ssr?.hydration ?? "immediate";
+    const devToolsRoot = ensureDevToolsRoot(enableDevTools);
+    const canEnumerateKeys = detectEnumerableStorage(st);
+    const crossTabSyncMode = getCrossTabSyncMode(storage, st);
     const cache = /* @__PURE__ */ new Map();
     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}`;
+    let asyncContractViolationDetected = false;
+    const storageAccessCallbacks = {
+      onAccessError: (err) => logAccessError(err),
+      onAccessSuccess: () => {
+        accessErrorLogged = false;
+      },
+      onAsyncViolation: (method, thenable) => handleAsyncStorageContractViolation(method, thenable)
     };
     const fullKey = (key) => prefix + key;
     const emit = (key) => {
@@ -168,30 +470,36 @@ function MnemonicProvider({
         accessErrorLogged = true;
       }
     };
+    const handleAsyncStorageContractViolation = (method, thenable) => {
+      asyncContractViolationDetected = true;
+      void Promise.resolve(thenable).catch(() => void 0);
+      if (accessErrorLogged) return;
+      console.error(
+        `[Mnemonic] StorageLike.${method} returned a Promise. StorageLike must remain synchronous for react-mnemonic v1. Wrap async persistence behind a synchronous cache facade instead.`
+      );
+      accessErrorLogged = true;
+    };
     const readThrough = (key) => {
       if (cache.has(key)) return cache.get(key) ?? null;
-      if (!st) {
-        cache.set(key, null);
-        return null;
-      }
-      try {
-        const raw = st.getItem(fullKey(key));
-        cache.set(key, raw);
-        accessErrorLogged = false;
-        return raw;
-      } catch (err) {
-        logAccessError(err);
+      if (!st || asyncContractViolationDetected) {
         cache.set(key, null);
         return null;
       }
+      const raw = readStorageRaw(st, fullKey(key), storageAccessCallbacks);
+      cache.set(key, raw);
+      return raw;
     };
     const writeRaw = (key, raw) => {
       cache.set(key, raw);
-      if (st) {
+      if (st && !asyncContractViolationDetected) {
         try {
-          st.setItem(fullKey(key), raw);
-          quotaErrorLogged = false;
-          accessErrorLogged = false;
+          const result = st.setItem(fullKey(key), raw);
+          if (isPromiseLike(result)) {
+            handleAsyncStorageContractViolation("setItem", result);
+          } else {
+            quotaErrorLogged = false;
+            accessErrorLogged = false;
+          }
         } catch (err) {
           if (!quotaErrorLogged && err instanceof DOMException && err.name === "QuotaExceededError") {
             console.error(
@@ -203,20 +511,24 @@ function MnemonicProvider({
         }
       }
       emit(key);
-      bumpDevToolsVersion(`set:${key}`);
+      bumpDevToolsVersion(devToolsRoot, namespace, `set:${key}`);
     };
     const removeRaw = (key) => {
       cache.set(key, null);
-      if (st) {
+      if (st && !asyncContractViolationDetected) {
         try {
-          st.removeItem(fullKey(key));
-          accessErrorLogged = false;
+          const result = st.removeItem(fullKey(key));
+          if (isPromiseLike(result)) {
+            handleAsyncStorageContractViolation("removeItem", result);
+          } else {
+            accessErrorLogged = false;
+          }
         } catch (err) {
           logAccessError(err);
         }
       }
       emit(key);
-      bumpDevToolsVersion(`remove:${key}`);
+      bumpDevToolsVersion(devToolsRoot, namespace, `remove:${key}`);
     };
     const subscribeRaw = (key, listener) => {
       let set = listeners.get(key);
@@ -235,22 +547,11 @@ function MnemonicProvider({
     };
     const getRawSnapshot = (key) => readThrough(key);
     const keys = () => {
-      if (!canEnumerateKeys || !st) return [];
-      const out = [];
-      try {
-        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));
-        }
-        accessErrorLogged = false;
-      } catch (err) {
-        logAccessError(err);
+      if (asyncContractViolationDetected) {
+        return Array.from(cache.entries()).filter(([, value]) => value != null).map(([key]) => key);
       }
-      return out;
+      if (!canEnumerateKeys) return [];
+      return enumerateNamespaceKeys(st, prefix, storageAccessCallbacks);
     };
     const dump = () => {
       const out = {};
@@ -260,65 +561,17 @@ function MnemonicProvider({
       }
       return out;
     };
-    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) {
-          if (!fk.startsWith(prefix)) continue;
-          const key = fk.slice(prefix.length);
-          const listenerSet = listeners.get(key);
-          if (listenerSet && listenerSet.size > 0) {
-            let fresh;
-            try {
-              fresh = st.getItem(fk);
-              accessErrorLogged = false;
-            } catch (err) {
-              logAccessError(err);
-              fresh = null;
-            }
-            const cached = cache.get(key) ?? null;
-            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) {
-        if (listenerSet.size === 0) continue;
-        let fresh;
-        try {
-          fresh = st.getItem(fullKey(key));
-          accessErrorLogged = false;
-        } catch (err) {
-          logAccessError(err);
-          fresh = null;
-        }
-        const cached = cache.get(key) ?? null;
-        if (fresh !== cached) {
-          cache.set(key, fresh);
-          emit(key);
-          changed = true;
-        }
-      }
-      for (const key of cache.keys()) {
-        if (!listeners.has(key) || listeners.get(key).size === 0) {
-          cache.delete(key);
-        }
-      }
-      if (changed) {
-        bumpDevToolsVersion("reload:full");
-      }
-    };
+    const reloadFromStorage = createReloadFromStorage({
+      storage: st,
+      hasAsyncContractViolation: () => asyncContractViolationDetected,
+      prefix,
+      listeners,
+      cache,
+      emit,
+      callbacks: storageAccessCallbacks,
+      devToolsRoot,
+      namespace
+    });
     const store2 = {
       prefix,
       canEnumerateKeys,
@@ -330,92 +583,24 @@ function MnemonicProvider({
       dump,
       reloadFromStorage,
       schemaMode,
+      ssrHydration,
+      crossTabSyncMode,
       ...schemaRegistry ? { schemaRegistry } : {}
     };
-    if (enableDevTools && typeof window !== "undefined") {
-      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(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);
-                }
-              },
-              /** 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}")`;
-            }
-          }
-        }
-      }
-      console.info(infoMessage);
+    if (devToolsRoot) {
+      registerDevToolsProvider({
+        devToolsRoot,
+        namespace,
+        store: store2,
+        dump,
+        keys,
+        readThrough,
+        writeRaw,
+        removeRaw
+      });
     }
     return store2;
-  }, [namespace, storage, enableDevTools, schemaMode, schemaRegistry]);
+  }, [namespace, storage, enableDevTools, schemaMode, schemaRegistry, ssr?.hydration]);
   useEffect(() => {
     if (!storage?.onExternalChange) return;
     return storage.onExternalChange((changedKeys) => store.reloadFromStorage(changedKeys));
@@ -485,30 +670,34 @@ function matchesType(value, type) {
       return false;
   }
 }
+function jsonDeepEqualArray(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (!jsonDeepEqual(a[i], b[i])) return false;
+  }
+  return true;
+}
+function jsonDeepEqualObject(a, b) {
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    if (!objectHasOwn(b, key)) return false;
+    if (!jsonDeepEqual(a[key], b[key])) return false;
+  }
+  return true;
+}
 function jsonDeepEqual(a, b) {
   if (a === b) return true;
   if (a === null || b === null) return false;
   if (typeof a !== typeof b) return false;
   if (Array.isArray(a)) {
     if (!Array.isArray(b)) return false;
-    if (a.length !== b.length) return false;
-    for (let i = 0; i < a.length; i++) {
-      if (!jsonDeepEqual(a[i], b[i])) return false;
-    }
-    return true;
+    return jsonDeepEqualArray(a, b);
   }
   if (typeof a === "object") {
     if (Array.isArray(b)) return false;
-    const aObj = a;
-    const bObj = b;
-    const aKeys = Object.keys(aObj);
-    const bKeys = Object.keys(bObj);
-    if (aKeys.length !== bKeys.length) return false;
-    for (const key of aKeys) {
-      if (!Object.prototype.hasOwnProperty.call(bObj, key)) return false;
-      if (!jsonDeepEqual(aObj[key], bObj[key])) return false;
-    }
-    return true;
+    return jsonDeepEqualObject(a, b);
   }
   return false;
 }
@@ -523,206 +712,283 @@ function compileSchema(schema) {
 function isJsonPrimitive(value) {
   return value === null || typeof value !== "object";
 }
+function isJsonObjectRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function objectHasOwn(value, property) {
+  const hasOwn = Object.hasOwn;
+  if (typeof hasOwn === "function") {
+    return hasOwn(value, property);
+  }
+  return Object.getOwnPropertyDescriptor(value, property) !== void 0;
+}
 function buildValidator(schema) {
-  const resolvedTypes = schema.type !== void 0 ? Array.isArray(schema.type) ? schema.type : [schema.type] : null;
-  const typeLabel = resolvedTypes !== null ? JSON.stringify(schema.type) : "";
-  const enumMembers = schema.enum;
-  let enumPrimitiveSet = null;
-  let enumComplexMembers = null;
-  if (enumMembers !== void 0) {
-    const primitives = [];
-    const complex = [];
-    for (const member of enumMembers) {
-      if (isJsonPrimitive(member)) {
-        primitives.push(member);
-      } else {
-        complex.push(member);
-      }
+  const typeStep = buildTypeValidationStep(schema);
+  const validationSteps = [
+    buildEnumValidationStep(schema),
+    buildConstValidationStep(schema),
+    buildNumberValidationStep(schema),
+    buildStringValidationStep(schema),
+    buildObjectValidationStep(schema),
+    buildArrayValidationStep(schema)
+  ].filter((step) => step !== null);
+  if (typeStep === null && validationSteps.length === 0) {
+    return (_value, _path) => [];
+  }
+  return (value, path = "") => {
+    const errors = [];
+    if (typeStep && !typeStep(value, path, errors)) {
+      return errors;
+    }
+    for (const step of validationSteps) {
+      step(value, path, errors);
+    }
+    return errors;
+  };
+}
+function buildTypeValidationStep(schema) {
+  if (schema.type === void 0) {
+    return null;
+  }
+  const resolvedTypes = Array.isArray(schema.type) ? schema.type : [schema.type];
+  const typeLabel = JSON.stringify(schema.type);
+  return (value, path, errors) => {
+    if (resolvedTypes.some((type) => matchesType(value, type))) {
+      return true;
+    }
+    errors.push({
+      path,
+      message: `Expected type ${typeLabel}, got ${jsonTypeLabel(value)}`,
+      keyword: "type"
+    });
+    return false;
+  };
+}
+function buildEnumValidationStep(schema) {
+  if (schema.enum === void 0) {
+    return null;
+  }
+  const enumPrimitiveSet = new Set(schema.enum.filter((member) => isJsonPrimitive(member)));
+  const enumComplexMembers = schema.enum.filter((member) => !isJsonPrimitive(member));
+  return (value, path, errors) => {
+    const primitiveMatch = isJsonPrimitive(value) && enumPrimitiveSet.has(value);
+    const complexMatch = !primitiveMatch && enumComplexMembers.some((entry) => jsonDeepEqual(value, entry));
+    if (primitiveMatch || complexMatch) {
+      return;
     }
-    if (primitives.length > 0) enumPrimitiveSet = new Set(primitives);
-    if (complex.length > 0) enumComplexMembers = complex;
+    errors.push({
+      path,
+      message: `Value does not match any enum member`,
+      keyword: "enum"
+    });
+  };
+}
+function buildConstValidationStep(schema) {
+  if (!("const" in schema)) {
+    return null;
   }
-  const hasConst = "const" in schema;
-  const constValue = schema.const;
+  return (value, path, errors) => {
+    if (jsonDeepEqual(value, schema.const)) {
+      return;
+    }
+    errors.push({
+      path,
+      message: `Value does not match const`,
+      keyword: "const"
+    });
+  };
+}
+function buildNumberValidationStep(schema) {
   const hasMinimum = schema.minimum !== void 0;
-  const minimum = schema.minimum;
   const hasMaximum = schema.maximum !== void 0;
-  const maximum = schema.maximum;
   const hasExMin = schema.exclusiveMinimum !== void 0;
-  const exMin = schema.exclusiveMinimum;
   const hasExMax = schema.exclusiveMaximum !== void 0;
+  if (!hasMinimum && !hasMaximum && !hasExMin && !hasExMax) {
+    return null;
+  }
+  const minimum = schema.minimum;
+  const maximum = schema.maximum;
+  const exMin = schema.exclusiveMinimum;
   const exMax = schema.exclusiveMaximum;
-  const hasNumberConstraints = hasMinimum || hasMaximum || hasExMin || hasExMax;
+  return (value, path, errors) => {
+    if (typeof value !== "number") {
+      return;
+    }
+    if (hasMinimum && value < minimum) {
+      errors.push({
+        path,
+        message: `Value ${value} is less than minimum ${minimum}`,
+        keyword: "minimum"
+      });
+    }
+    if (hasMaximum && value > maximum) {
+      errors.push({
+        path,
+        message: `Value ${value} is greater than maximum ${maximum}`,
+        keyword: "maximum"
+      });
+    }
+    if (hasExMin && value <= exMin) {
+      errors.push({
+        path,
+        message: `Value ${value} is not greater than exclusiveMinimum ${exMin}`,
+        keyword: "exclusiveMinimum"
+      });
+    }
+    if (hasExMax && value >= exMax) {
+      errors.push({
+        path,
+        message: `Value ${value} is not less than exclusiveMaximum ${exMax}`,
+        keyword: "exclusiveMaximum"
+      });
+    }
+  };
+}
+function buildStringValidationStep(schema) {
   const hasMinLength = schema.minLength !== void 0;
-  const minLen = schema.minLength;
   const hasMaxLength = schema.maxLength !== void 0;
-  const maxLen = schema.maxLength;
-  const hasStringConstraints = hasMinLength || hasMaxLength;
-  const requiredKeys = schema.required;
-  const hasRequired = requiredKeys !== void 0 && requiredKeys.length > 0;
-  const hasProperties = schema.properties !== void 0;
-  const propertyValidators = hasProperties ? Object.entries(schema.properties).map(
-    ([name, propSchema]) => [name, compileSchema(propSchema)]
-  ) : null;
+  if (!hasMinLength && !hasMaxLength) {
+    return null;
+  }
+  const minLength = schema.minLength;
+  const maxLength = schema.maxLength;
+  return (value, path, errors) => {
+    if (typeof value !== "string") {
+      return;
+    }
+    if (hasMinLength && value.length < minLength) {
+      errors.push({
+        path,
+        message: `String length ${value.length} is less than minLength ${minLength}`,
+        keyword: "minLength"
+      });
+    }
+    if (hasMaxLength && value.length > maxLength) {
+      errors.push({
+        path,
+        message: `String length ${value.length} is greater than maxLength ${maxLength}`,
+        keyword: "maxLength"
+      });
+    }
+  };
+}
+function buildObjectValidationStep(schema) {
+  const requiredKeys = schema.required ?? [];
+  const propertyValidators = schema.properties ? Object.entries(schema.properties).map(([name, propertySchema]) => [
+    name,
+    compileSchema(propertySchema)
+  ]) : null;
   const checkAdditional = schema.additionalProperties !== void 0 && schema.additionalProperties !== true;
   const additionalIsFalse = schema.additionalProperties === false;
   const additionalValidator = checkAdditional && !additionalIsFalse ? compileSchema(schema.additionalProperties) : null;
-  const definedPropKeys = checkAdditional ? new Set(schema.properties ? Object.keys(schema.properties) : []) : null;
-  const hasObjectConstraints = hasRequired || hasProperties || checkAdditional;
-  const hasMinItems = schema.minItems !== void 0;
-  const minItems = schema.minItems;
-  const hasMaxItems = schema.maxItems !== void 0;
-  const maxItems = schema.maxItems;
-  const itemsValidator = schema.items !== void 0 ? compileSchema(schema.items) : null;
-  const hasArrayConstraints = hasMinItems || hasMaxItems || itemsValidator !== null;
-  if (resolvedTypes === null && enumMembers === void 0 && !hasConst && !hasNumberConstraints && !hasStringConstraints && !hasObjectConstraints && !hasArrayConstraints) {
-    return (_value, _path) => [];
+  const definedPropKeys = checkAdditional ? new Set(Object.keys(schema.properties ?? {})) : null;
+  const objectValidationSteps = [];
+  if (requiredKeys.length > 0) {
+    objectValidationSteps.push(createRequiredPropertyStep(requiredKeys));
   }
-  return (value, path = "") => {
-    const errors = [];
-    if (resolvedTypes !== null) {
-      const matched = resolvedTypes.some((t) => matchesType(value, t));
-      if (!matched) {
-        errors.push({
-          path,
-          message: `Expected type ${typeLabel}, got ${jsonTypeLabel(value)}`,
-          keyword: "type"
-        });
-        return errors;
-      }
+  if (propertyValidators !== null) {
+    objectValidationSteps.push(createDeclaredPropertyStep(propertyValidators));
+  }
+  if (checkAdditional) {
+    objectValidationSteps.push(
+      createAdditionalPropertyStep({
+        additionalIsFalse,
+        additionalValidator,
+        definedPropKeys: definedPropKeys ?? /* @__PURE__ */ new Set()
+      })
+    );
+  }
+  if (objectValidationSteps.length === 0) {
+    return null;
+  }
+  return (value, path, errors) => {
+    if (!isJsonObjectRecord(value)) {
+      return;
     }
-    if (enumMembers !== void 0) {
-      let matched = false;
-      if (enumPrimitiveSet !== null && isJsonPrimitive(value)) {
-        matched = enumPrimitiveSet.has(value);
-      }
-      if (!matched && enumComplexMembers !== null) {
-        matched = enumComplexMembers.some((entry) => jsonDeepEqual(value, entry));
-      }
-      if (!matched) {
-        errors.push({
-          path,
-          message: `Value does not match any enum member`,
-          keyword: "enum"
-        });
-      }
+    for (const step of objectValidationSteps) {
+      step(value, path, errors);
     }
-    if (hasConst) {
-      if (!jsonDeepEqual(value, constValue)) {
-        errors.push({
-          path,
-          message: `Value does not match const`,
-          keyword: "const"
-        });
+  };
+}
+function createRequiredPropertyStep(requiredKeys) {
+  return (value, path, errors) => {
+    for (const requiredKey of requiredKeys) {
+      if (objectHasOwn(value, requiredKey)) {
+        continue;
       }
+      errors.push({
+        path,
+        message: `Missing required property "${requiredKey}"`,
+        keyword: "required"
+      });
     }
-    if (hasNumberConstraints && typeof value === "number") {
-      if (hasMinimum && value < minimum) {
-        errors.push({
-          path,
-          message: `Value ${value} is less than minimum ${minimum}`,
-          keyword: "minimum"
-        });
-      }
-      if (hasMaximum && value > maximum) {
-        errors.push({
-          path,
-          message: `Value ${value} is greater than maximum ${maximum}`,
-          keyword: "maximum"
-        });
-      }
-      if (hasExMin && value <= exMin) {
-        errors.push({
-          path,
-          message: `Value ${value} is not greater than exclusiveMinimum ${exMin}`,
-          keyword: "exclusiveMinimum"
-        });
-      }
-      if (hasExMax && value >= exMax) {
-        errors.push({
-          path,
-          message: `Value ${value} is not less than exclusiveMaximum ${exMax}`,
-          keyword: "exclusiveMaximum"
-        });
+  };
+}
+function createDeclaredPropertyStep(propertyValidators) {
+  return (value, path, errors) => {
+    for (const [propertyName, validator] of propertyValidators) {
+      if (!objectHasOwn(value, propertyName)) {
+        continue;
       }
+      errors.push(...validator(value[propertyName], `${path}/${propertyName}`));
     }
-    if (hasStringConstraints && typeof value === "string") {
-      if (hasMinLength && value.length < minLen) {
-        errors.push({
-          path,
-          message: `String length ${value.length} is less than minLength ${minLen}`,
-          keyword: "minLength"
-        });
+  };
+}
+function createAdditionalPropertyStep({
+  additionalIsFalse,
+  additionalValidator,
+  definedPropKeys
+}) {
+  return (value, path, errors) => {
+    for (const objectKey of Object.keys(value)) {
+      if (definedPropKeys.has(objectKey)) {
+        continue;
       }
-      if (hasMaxLength && value.length > maxLen) {
+      if (additionalIsFalse) {
         errors.push({
           path,
-          message: `String length ${value.length} is greater than maxLength ${maxLen}`,
-          keyword: "maxLength"
+          message: `Additional property "${objectKey}" is not allowed`,
+          keyword: "additionalProperties"
         });
+        continue;
       }
+      errors.push(...additionalValidator(value[objectKey], `${path}/${objectKey}`));
     }
-    if (hasObjectConstraints && typeof value === "object" && value !== null && !Array.isArray(value)) {
-      const obj = value;
-      if (hasRequired) {
-        for (const reqKey of requiredKeys) {
-          if (!Object.prototype.hasOwnProperty.call(obj, reqKey)) {
-            errors.push({
-              path,
-              message: `Missing required property "${reqKey}"`,
-              keyword: "required"
-            });
-          }
-        }
-      }
-      if (propertyValidators !== null) {
-        for (const [propName, propValidator] of propertyValidators) {
-          if (Object.prototype.hasOwnProperty.call(obj, propName)) {
-            const propErrors = propValidator(obj[propName], `${path}/${propName}`);
-            errors.push(...propErrors);
-          }
-        }
-      }
-      if (checkAdditional) {
-        for (const objKey of Object.keys(obj)) {
-          if (!definedPropKeys.has(objKey)) {
-            if (additionalIsFalse) {
-              errors.push({
-                path,
-                message: `Additional property "${objKey}" is not allowed`,
-                keyword: "additionalProperties"
-              });
-            } else {
-              const propErrors = additionalValidator(obj[objKey], `${path}/${objKey}`);
-              errors.push(...propErrors);
-            }
-          }
-        }
-      }
+  };
+}
+function buildArrayValidationStep(schema) {
+  const hasMinItems = schema.minItems !== void 0;
+  const hasMaxItems = schema.maxItems !== void 0;
+  const itemsValidator = schema.items ? compileSchema(schema.items) : null;
+  if (!hasMinItems && !hasMaxItems && itemsValidator === null) {
+    return null;
+  }
+  const minItems = schema.minItems;
+  const maxItems = schema.maxItems;
+  return (value, path, errors) => {
+    if (!Array.isArray(value)) {
+      return;
     }
-    if (hasArrayConstraints && Array.isArray(value)) {
-      if (hasMinItems && value.length < minItems) {
-        errors.push({
-          path,
-          message: `Array length ${value.length} is less than minItems ${minItems}`,
-          keyword: "minItems"
-        });
-      }
-      if (hasMaxItems && value.length > maxItems) {
-        errors.push({
-          path,
-          message: `Array length ${value.length} is greater than maxItems ${maxItems}`,
-          keyword: "maxItems"
-        });
-      }
-      if (itemsValidator !== null) {
-        for (let i = 0; i < value.length; i++) {
-          const itemErrors = itemsValidator(value[i], `${path}/${i}`);
-          errors.push(...itemErrors);
-        }
-      }
+    if (hasMinItems && value.length < minItems) {
+      errors.push({
+        path,
+        message: `Array length ${value.length} is less than minItems ${minItems}`,
+        keyword: "minItems"
+      });
+    }
+    if (hasMaxItems && value.length > maxItems) {
+      errors.push({
+        path,
+        message: `Array length ${value.length} is greater than maxItems ${maxItems}`,
+        keyword: "maxItems"
+      });
+    }
+    if (itemsValidator === null) {
+      return;
+    }
+    for (const [index, item] of value.entries()) {
+      errors.push(...itemsValidator(item, `${path}/${index}`));
     }
-    return errors;
   };
 }
 function validateJsonSchema(value, schema, path = "") {
@@ -741,7 +1007,7 @@ function inferJsonSchema(sample) {
     case "string":
       return { type: "string" };
     case "number":
-      return Number.isInteger(sample) ? { type: "number" } : { type: "number" };
+      return { type: "number" };
     case "boolean":
       return { type: "boolean" };
     case "object":
@@ -752,21 +1018,173 @@ function inferJsonSchema(sample) {
 }
 
 // src/Mnemonic/use.ts
-function useMnemonicKey(key, options) {
+var SSR_SNAPSHOT_TOKEN = /* @__PURE__ */ Symbol("mnemonic:ssr-snapshot");
+var diagnosticContractRegistry = /* @__PURE__ */ new WeakMap();
+var diagnosticWarningRegistry = /* @__PURE__ */ new WeakMap();
+var diagnosticObjectIds = /* @__PURE__ */ new WeakMap();
+var nextDiagnosticObjectId = 1;
+function serializeEnvelope(version, payload) {
+  return JSON.stringify({
+    version,
+    payload
+  });
+}
+function withReadMetadata(value, rewriteRaw, pendingSchema) {
+  const result = { value };
+  if (rewriteRaw !== void 0) result.rewriteRaw = rewriteRaw;
+  if (pendingSchema !== void 0) result.pendingSchema = pendingSchema;
+  return result;
+}
+function isDevelopmentRuntime() {
+  return getRuntimeNodeEnv() === "development";
+}
+function getDiagnosticWarnings(api) {
+  let warnings = diagnosticWarningRegistry.get(api);
+  if (!warnings) {
+    warnings = /* @__PURE__ */ new Set();
+    diagnosticWarningRegistry.set(api, warnings);
+  }
+  return warnings;
+}
+function warnOnce(api, id, message) {
+  const warnings = getDiagnosticWarnings(api);
+  if (warnings.has(id)) return;
+  warnings.add(id);
+  console.warn(message);
+}
+function stableDiagnosticValue(value) {
+  if (typeof value === "function") {
+    const source = Function.prototype.toString.call(value).split(/\s+/).join(" ").trim();
+    const name = value.name || "anonymous";
+    return `[factory:${name}/${value.length}:${source}]`;
+  }
+  if (typeof value === "bigint") return `${value.toString()}n`;
+  if (typeof value === "symbol") return value.toString();
+  if (value === void 0) return "undefined";
+  try {
+    return JSON.stringify(value);
+  } catch {
+    const tag = Object.prototype.toString.call(value);
+    if (value !== null && (typeof value === "object" || typeof value === "function")) {
+      return `${tag}#${getDiagnosticObjectId(value)}`;
+    }
+    return tag;
+  }
+}
+function isObjectLike(value) {
+  return value !== null && (typeof value === "object" || typeof value === "function");
+}
+function objectHasOwn2(value, property) {
+  const hasOwn = Object.hasOwn;
+  if (typeof hasOwn === "function") {
+    return hasOwn(value, property);
+  }
+  return Object.getOwnPropertyDescriptor(value, property) !== void 0;
+}
+function getDiagnosticObjectId(value) {
+  const existing = diagnosticObjectIds.get(value);
+  if (existing !== void 0) return existing;
+  const id = nextDiagnosticObjectId++;
+  diagnosticObjectIds.set(value, id);
+  return id;
+}
+function buildContractFingerprint({
+  api,
+  key,
+  defaultValue,
+  codecOpt,
+  schema,
+  reconcile,
+  listenCrossTab,
+  ssrOptions
+}) {
+  const codecSignature = codecOpt == null || !isObjectLike(codecOpt) ? "default-json-codec" : `codec:${stableDiagnosticValue(codecOpt.encode)}:${stableDiagnosticValue(codecOpt.decode)}`;
+  const reconcileSignature = reconcile == null || !isObjectLike(reconcile) ? "no-reconcile" : `reconcile:${stableDiagnosticValue(reconcile)}`;
+  return JSON.stringify({
+    key,
+    defaultValue: stableDiagnosticValue(defaultValue),
+    codec: codecSignature,
+    schemaVersion: schema?.version ?? null,
+    listenCrossTab: Boolean(listenCrossTab),
+    reconcile: reconcileSignature,
+    ssrHydration: ssrOptions?.hydration ?? null,
+    hasServerValue: ssrOptions?.serverValue !== void 0,
+    providerHydration: api.ssrHydration ?? null
+  });
+}
+function resolveMnemonicKeyArgs(keyOrDescriptor, options) {
+  if (typeof keyOrDescriptor !== "string") {
+    return keyOrDescriptor;
+  }
+  if (!options) {
+    throw new Error("useMnemonicKey requires options when called with a string key");
+  }
+  return {
+    key: keyOrDescriptor,
+    options
+  };
+}
+function useMnemonicKey(keyOrDescriptor, options) {
+  const descriptor = resolveMnemonicKeyArgs(keyOrDescriptor, options);
+  const key = descriptor.key;
+  const resolvedOptions = descriptor.options;
   const api = useMnemonic();
-  const { defaultValue, onMount, onChange, listenCrossTab, codec: codecOpt, schema, reconcile } = options;
+  const {
+    defaultValue,
+    onMount,
+    onChange,
+    listenCrossTab,
+    codec: codecOpt,
+    schema,
+    reconcile,
+    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();
+  const contractFingerprint = useMemo(
+    () => developmentRuntime ? buildContractFingerprint({
+      api,
+      key,
+      defaultValue,
+      codecOpt,
+      schema,
+      reconcile,
+      listenCrossTab,
+      ssrOptions
+    }) : null,
+    [
+      developmentRuntime,
+      api,
+      key,
+      defaultValue,
+      codecOpt,
+      schema?.version,
+      reconcile,
+      listenCrossTab,
+      ssrOptions?.hydration,
+      ssrOptions?.serverValue
+    ]
+  );
   const getFallback = useCallback(
     (error) => typeof defaultValue === "function" ? defaultValue(error) : defaultValue,
     [defaultValue]
   );
+  const getServerValue = useCallback(() => {
+    const serverValue = ssrOptions?.serverValue;
+    if (serverValue === void 0) {
+      return getFallback();
+    }
+    return typeof serverValue === "function" ? serverValue() : serverValue;
+  }, [getFallback, ssrOptions?.serverValue]);
   const parseEnvelope = useCallback(
     (rawText) => {
       try {
         const parsed = JSON.parse(rawText);
-        if (typeof parsed !== "object" || parsed == null || !Number.isInteger(parsed.version) || parsed.version < 0 || !Object.prototype.hasOwnProperty.call(parsed, "payload")) {
+        if (typeof parsed !== "object" || parsed == null || !Number.isInteger(parsed.version) || parsed.version < 0 || !objectHasOwn2(parsed, "payload")) {
           return {
             ok: false,
             error: new SchemaError("INVALID_ENVELOPE", `Invalid envelope for key "${key}"`)
@@ -784,12 +1202,6 @@ function useMnemonicKey(key, options) {
   );
   const decodeStringPayload = useCallback(
     (payload, activeCodec) => {
-      if (typeof payload !== "string") {
-        throw new SchemaError(
-          "INVALID_ENVELOPE",
-          `Envelope payload must be a string for codec-managed key "${key}"`
-        );
-      }
       try {
         return activeCodec.decode(payload);
       } catch (err) {
@@ -853,21 +1265,28 @@ function useMnemonicKey(key, options) {
     },
     [schemaRegistry, registryCache, key]
   );
+  const buildFallbackResult = useCallback(
+    (error) => ({
+      value: getFallback(error)
+    }),
+    [getFallback]
+  );
+  const buildSchemaManagedResult = useCallback(
+    (version, value2) => serializeEnvelope(version, value2),
+    []
+  );
+  const resolveTargetWriteSchema = useCallback(() => {
+    const explicitVersion = schema?.version;
+    const latestSchema = getLatestSchemaForKey();
+    if (explicitVersion === void 0) return latestSchema;
+    const explicitSchema = getSchemaForVersion(explicitVersion);
+    if (explicitSchema) return explicitSchema;
+    return schemaMode === "strict" ? void 0 : latestSchema;
+  }, [getLatestSchemaForKey, getSchemaForVersion, schema?.version, schemaMode]);
   const encodeForWrite = 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;
-        }
-      }
+      const targetSchema = resolveTargetWriteSchema();
       if (!targetSchema) {
         if (explicitVersion !== void 0 && schemaMode === "strict") {
           throw new SchemaError(
@@ -875,11 +1294,7 @@ function useMnemonicKey(key, options) {
             `Write requires schema for key "${key}" in strict mode`
           );
         }
-        const envelope2 = {
-          version: 0,
-          payload: codec.encode(nextValue)
-        };
-        return JSON.stringify(envelope2);
+        return serializeEnvelope(0, codec.encode(nextValue));
       }
       let valueToStore = nextValue;
       const writeMigration = schemaRegistry?.getWriteMigration?.(key, targetSchema.version);
@@ -891,11 +1306,7 @@ function useMnemonicKey(key, options) {
         }
       }
       validateAgainstSchema(valueToStore, targetSchema.schema);
-      const envelope = {
-        version: targetSchema.version,
-        payload: valueToStore
-      };
-      return JSON.stringify(envelope);
+      return buildSchemaManagedResult(targetSchema.version, valueToStore);
     },
     [
       schema?.version,
@@ -904,8 +1315,8 @@ function useMnemonicKey(key, options) {
       codec,
       schemaRegistry,
       validateAgainstSchema,
-      getLatestSchemaForKey,
-      getSchemaForVersion
+      resolveTargetWriteSchema,
+      buildSchemaManagedResult
     ]
   );
   const applyReconcile = useCallback(
@@ -919,135 +1330,112 @@ function useMnemonicKey(key, options) {
       derivePendingSchema
     }) => {
       if (!reconcile) {
-        const result = { value: value2 };
-        if (rewriteRaw !== void 0) result.rewriteRaw = rewriteRaw;
-        if (pendingSchema !== void 0) result.pendingSchema = pendingSchema;
-        return result;
+        return withReadMetadata(value2, rewriteRaw, pendingSchema);
       }
       const context = {
         key,
         persistedVersion,
         ...latestVersion === void 0 ? {} : { latestVersion }
       };
-      let baselineSerialized;
-      if (serializeForPersist) {
+      const baselineSerialized = (() => {
         try {
-          baselineSerialized = serializeForPersist(value2);
+          return serializeForPersist(value2);
         } catch {
-          baselineSerialized = rewriteRaw;
+          return 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;
+        return withReadMetadata(reconciled, nextRewriteRaw, nextPendingSchema);
       } catch (err) {
         const typedErr = err instanceof SchemaError ? err : new SchemaError("RECONCILE_FAILED", `Reconciliation failed for key "${key}"`, err);
-        return { value: getFallback(typedErr) };
+        return buildFallbackResult(typedErr);
       }
     },
-    [getFallback, key, reconcile]
+    [buildFallbackResult, key, reconcile]
   );
-  const decodeForRead = useCallback(
-    (rawText) => {
-      if (rawText == null) return { value: getFallback() };
-      const parsed = parseEnvelope(rawText);
-      if (!parsed.ok) return { value: getFallback(parsed.error) };
-      const envelope = parsed.envelope;
-      const schemaForVersion = getSchemaForVersion(envelope.version);
-      const latestSchema = getLatestSchemaForKey();
-      if (schemaMode === "strict" && !schemaForVersion) {
-        return {
-          value: getFallback(
-            new SchemaError("SCHEMA_NOT_FOUND", `No schema for key "${key}" v${envelope.version}`)
+  const decodeAutoschemaEnvelope = useCallback(
+    (envelope, latestSchema) => {
+      if (latestSchema) {
+        return buildFallbackResult(
+          new SchemaError("SCHEMA_NOT_FOUND", `No schema for key "${key}" v${envelope.version}`)
+        );
+      }
+      if (!schemaRegistry || typeof schemaRegistry.registerSchema !== "function") {
+        return buildFallbackResult(
+          new SchemaError(
+            "MODE_CONFIGURATION_INVALID",
+            `Autoschema mode requires schema registry registration for key "${key}"`
           )
-        };
+        );
       }
-      if (schemaMode === "autoschema" && !schemaForVersion) {
-        if (latestSchema) {
-          return {
-            value: getFallback(
-              new SchemaError("SCHEMA_NOT_FOUND", `No schema for key "${key}" v${envelope.version}`)
-            )
-          };
-        }
-        if (!schemaRegistry || typeof schemaRegistry.registerSchema !== "function") {
-          return {
-            value: getFallback(
-              new SchemaError(
-                "MODE_CONFIGURATION_INVALID",
-                `Autoschema mode requires schema registry registration for key "${key}"`
-              )
-            )
-          };
-        }
-        try {
-          const decoded2 = typeof envelope.payload === "string" ? decodeStringPayload(envelope.payload, codec) : envelope.payload;
-          const inferSchemaForValue = (value2) => ({
-            key,
-            version: 1,
-            schema: inferJsonSchema(value2)
-          });
-          const inferred = inferSchemaForValue(decoded2);
-          return applyReconcile({
-            value: decoded2,
-            pendingSchema: inferred,
-            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) };
-        }
+      try {
+        const decoded2 = typeof envelope.payload === "string" ? decodeStringPayload(envelope.payload, codec) : envelope.payload;
+        const inferSchemaForValue = (value2) => ({
+          key,
+          version: 1,
+          schema: inferJsonSchema(value2)
+        });
+        const inferred = inferSchemaForValue(decoded2);
+        return applyReconcile({
+          value: decoded2,
+          pendingSchema: inferred,
+          rewriteRaw: buildSchemaManagedResult(inferred.version, decoded2),
+          persistedVersion: envelope.version,
+          serializeForPersist: (value2) => buildSchemaManagedResult(inferred.version, 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 buildFallbackResult(typedErr);
       }
-      if (!schemaForVersion) {
-        if (typeof envelope.payload !== "string") {
-          return applyReconcile({
-            value: envelope.payload,
-            persistedVersion: envelope.version,
-            ...latestSchema ? { latestVersion: latestSchema.version } : {},
-            serializeForPersist: encodeForWrite
-          });
-        }
-        try {
-          const decoded2 = decodeStringPayload(envelope.payload, codec);
-          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) };
-        }
+    },
+    [
+      applyReconcile,
+      buildFallbackResult,
+      buildSchemaManagedResult,
+      codec,
+      decodeStringPayload,
+      key,
+      schemaRegistry
+    ]
+  );
+  const decodeCodecManagedEnvelope = useCallback(
+    (envelope, latestSchema) => {
+      if (typeof envelope.payload !== "string") {
+        return applyReconcile({
+          value: envelope.payload,
+          persistedVersion: envelope.version,
+          ...latestSchema ? { latestVersion: latestSchema.version } : {},
+          serializeForPersist: encodeForWrite
+        });
+      }
+      try {
+        const decoded2 = decodeStringPayload(envelope.payload, codec);
+        return applyReconcile({
+          value: decoded2,
+          persistedVersion: envelope.version,
+          ...latestSchema ? { latestVersion: latestSchema.version } : {},
+          serializeForPersist: encodeForWrite
+        });
+      } catch (err) {
+        return buildFallbackResult(err);
       }
+    },
+    [applyReconcile, buildFallbackResult, codec, decodeStringPayload, encodeForWrite]
+  );
+  const decodeSchemaManagedEnvelope = useCallback(
+    (envelope, schemaForVersion, latestSchema) => {
       let current;
       try {
         current = envelope.payload;
         validateAgainstSchema(current, schemaForVersion.schema);
       } catch (err) {
         const typedErr = err instanceof SchemaError || err instanceof CodecError ? err : new SchemaError("TYPE_MISMATCH", `Schema decode failed for key "${key}"`, err);
-        return { value: getFallback(typedErr) };
+        return buildFallbackResult(typedErr);
       }
       if (!latestSchema || envelope.version >= latestSchema.version) {
         return applyReconcile({
@@ -1059,14 +1447,12 @@ function useMnemonicKey(key, options) {
       }
       const path = getMigrationPathForKey(envelope.version, latestSchema.version);
       if (!path) {
-        return {
-          value: getFallback(
-            new SchemaError(
-              "MIGRATION_PATH_NOT_FOUND",
-              `No migration path for key "${key}" from v${envelope.version} to v${latestSchema.version}`
-            )
+        return buildFallbackResult(
+          new SchemaError(
+            "MIGRATION_PATH_NOT_FOUND",
+            `No migration path for key "${key}" from v${envelope.version} to v${latestSchema.version}`
           )
-        };
+        );
       }
       try {
         let migrated = current;
@@ -1076,43 +1462,140 @@ function useMnemonicKey(key, options) {
         validateAgainstSchema(migrated, latestSchema.schema);
         return applyReconcile({
           value: migrated,
-          rewriteRaw: JSON.stringify({
-            version: latestSchema.version,
-            payload: migrated
-          }),
+          rewriteRaw: buildSchemaManagedResult(latestSchema.version, 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) };
+        return buildFallbackResult(typedErr);
       }
     },
     [
       applyReconcile,
-      codec,
-      decodeStringPayload,
+      buildFallbackResult,
+      buildSchemaManagedResult,
       encodeForWrite,
-      getFallback,
+      getMigrationPathForKey,
       key,
+      validateAgainstSchema
+    ]
+  );
+  const decodeForRead = useCallback(
+    (rawText) => {
+      if (rawText == null) return buildFallbackResult();
+      const parsed = parseEnvelope(rawText);
+      if (!parsed.ok) return buildFallbackResult(parsed.error);
+      const envelope = parsed.envelope;
+      const schemaForVersion = getSchemaForVersion(envelope.version);
+      const latestSchema = getLatestSchemaForKey();
+      if (schemaMode === "strict" && !schemaForVersion) {
+        return buildFallbackResult(
+          new SchemaError("SCHEMA_NOT_FOUND", `No schema for key "${key}" v${envelope.version}`)
+        );
+      }
+      if (schemaMode === "autoschema" && !schemaForVersion) {
+        return decodeAutoschemaEnvelope(envelope, latestSchema);
+      }
+      if (!schemaForVersion) {
+        return decodeCodecManagedEnvelope(envelope, latestSchema);
+      }
+      return decodeSchemaManagedEnvelope(envelope, schemaForVersion, latestSchema);
+    },
+    [
+      buildFallbackResult,
+      decodeAutoschemaEnvelope,
+      decodeCodecManagedEnvelope,
+      decodeSchemaManagedEnvelope,
       parseEnvelope,
       schemaMode,
-      schemaRegistry,
       getSchemaForVersion,
-      getLatestSchemaForKey,
-      getMigrationPathForKey,
-      validateAgainstSchema
+      getLatestSchemaForKey
     ]
   );
+  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(
-    (listener) => api.subscribeRaw(key, listener),
-    () => api.getRawSnapshot(key),
-    () => null
-    // SSR snapshot - no storage in server environment
+    subscribe,
+    () => deferStorageRead ? getServerRawSnapshot() : api.getRawSnapshot(key),
+    getServerRawSnapshot
   );
-  const decoded = useMemo(() => decodeForRead(raw), [decodeForRead, raw]);
+  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,
+        `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);
@@ -1142,7 +1625,8 @@ function useMnemonicKey(key, options) {
   }, [value, onChange]);
   useEffect(() => {
     if (!listenCrossTab) return;
-    if (typeof window === "undefined") return;
+    const globalWindow = globalThis.window;
+    if (globalWindow === void 0) return;
     const storageKey = api.prefix + key;
     const handler = (e) => {
       if (e.key === null) {
@@ -1156,8 +1640,8 @@ function useMnemonicKey(key, options) {
       }
       api.setRaw(key, e.newValue);
     };
-    window.addEventListener("storage", handler);
-    return () => window.removeEventListener("storage", handler);
+    globalWindow.addEventListener("storage", handler);
+    return () => globalWindow.removeEventListener("storage", handler);
   }, [listenCrossTab, api, key]);
   const set = useMemo(() => {
     return (next) => {
@@ -1219,6 +1703,20 @@ function useMnemonicKey(key, options) {
 function uniqueKeys(keys) {
   return [...new Set(keys)];
 }
+function isDevelopmentRuntime2() {
+  return getRuntimeNodeEnv() === "development";
+}
+var recoveryDiagnosticWarnings = /* @__PURE__ */ new WeakMap();
+function warnRecoveryOnce(api, id, message) {
+  let warnings = recoveryDiagnosticWarnings.get(api);
+  if (!warnings) {
+    warnings = /* @__PURE__ */ new Set();
+    recoveryDiagnosticWarnings.set(api, warnings);
+  }
+  if (warnings.has(id)) return;
+  warnings.add(id);
+  console.warn(message);
+}
 function useMnemonicRecovery(options = {}) {
   const api = useMnemonic();
   const { onRecover } = options;
@@ -1252,15 +1750,29 @@ function useMnemonicRecovery(options = {}) {
   );
   const clearAll = useCallback(() => {
     if (!api.canEnumerateKeys) {
+      if (isDevelopmentRuntime2()) {
+        warnRecoveryOnce(
+          api,
+          "recovery-clear-all-non-enumerable",
+          `[Mnemonic] clearAll() requires an enumerable storage backend in namespace "${namespace}". Use clearKeys([...]) with an explicit durable-key list, or supply a storage backend that implements length and key(index).`
+        );
+      }
       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]);
+  }, [api, clearResolvedKeys, namespace]);
   const clearMatching = useCallback(
     (predicate) => {
       if (!api.canEnumerateKeys) {
+        if (isDevelopmentRuntime2()) {
+          warnRecoveryOnce(
+            api,
+            "recovery-clear-matching-non-enumerable",
+            `[Mnemonic] clearMatching() requires an enumerable storage backend in namespace "${namespace}". Use clearKeys([...]) with an explicit durable-key list, or supply a storage backend that implements length and key(index).`
+          );
+        }
         throw new Error(
           "clearMatching requires an enumerable storage backend. Use clearKeys([...]) with an explicit key list instead."
         );
@@ -1270,7 +1782,7 @@ function useMnemonicRecovery(options = {}) {
         api.keys().filter((key) => predicate(key))
       );
     },
-    [api, clearResolvedKeys]
+    [api, clearResolvedKeys, namespace]
   );
   return useMemo(
     () => ({
@@ -1285,6 +1797,23 @@ function useMnemonicRecovery(options = {}) {
   );
 }
 
+// src/Mnemonic/key.ts
+function defineMnemonicKey(keyOrSchema, options) {
+  if (typeof keyOrSchema !== "string") {
+    return Object.freeze({
+      key: keyOrSchema.key,
+      options: {
+        ...options,
+        schema: { version: keyOrSchema.version }
+      }
+    });
+  }
+  return Object.freeze({
+    key: keyOrSchema,
+    options
+  });
+}
+
 // src/Mnemonic/schema-registry.ts
 function schemaVersionKey(key, version) {
   return `${key}:${version}`;
@@ -1374,6 +1903,184 @@ function createSchemaRegistry(options = {}) {
   };
 }
 
+// src/Mnemonic/schema-helpers.ts
+function defineKeySchema(key, version, schema) {
+  return Object.freeze({
+    key,
+    version,
+    schema
+  });
+}
+function defineMigration(fromSchema, toSchema, migrate) {
+  if (fromSchema.key !== toSchema.key) {
+    throw new SchemaError(
+      "MIGRATION_GRAPH_INVALID",
+      `Migration schemas must target the same key: "${fromSchema.key}" !== "${toSchema.key}"`
+    );
+  }
+  return Object.freeze({
+    key: fromSchema.key,
+    fromVersion: fromSchema.version,
+    toVersion: toSchema.version,
+    migrate
+  });
+}
+function defineWriteMigration(schema, migrate) {
+  return Object.freeze({
+    key: schema.key,
+    fromVersion: schema.version,
+    toVersion: schema.version,
+    migrate
+  });
+}
+
+// src/Mnemonic/typed-schema.ts
+var optionalSchemaMarker = /* @__PURE__ */ Symbol("mnemonicOptionalSchema");
+function cloneSchema(schema) {
+  const clone = { ...schema };
+  if (schema[optionalSchemaMarker]) {
+    Object.defineProperty(clone, optionalSchemaMarker, {
+      value: true,
+      enumerable: false,
+      configurable: false
+    });
+  }
+  return clone;
+}
+function isOptionalSchema(schema) {
+  return Boolean(schema[optionalSchemaMarker]);
+}
+function markOptional(schema) {
+  const clone = cloneSchema(schema);
+  Object.defineProperty(clone, optionalSchemaMarker, {
+    value: true,
+    enumerable: false,
+    configurable: false
+  });
+  return clone;
+}
+function withoutOptionalMarker(schema) {
+  const clone = { ...schema };
+  delete clone[optionalSchemaMarker];
+  return clone;
+}
+function withType(type, extra = {}) {
+  return {
+    type,
+    ...extra
+  };
+}
+function toTypeArray(type) {
+  if (type === void 0) return null;
+  return Array.isArray(type) ? [...type] : [type];
+}
+function appendNullType(type) {
+  const types = toTypeArray(type);
+  if (types === null) {
+    return void 0;
+  }
+  return types.includes("null") ? types : [...types, "null"];
+}
+function nullableSchema(schema) {
+  if (schema.enum) {
+    const nullableType = appendNullType(schema.type);
+    return {
+      ...schema,
+      ...nullableType ? { type: nullableType } : {},
+      enum: schema.enum.includes(null) ? schema.enum : [...schema.enum, null]
+    };
+  }
+  if ("const" in schema) {
+    const { const: constValue, ...rest } = schema;
+    const nullableType = appendNullType(rest.type);
+    if (constValue === null || constValue === void 0) {
+      return {
+        ...schema,
+        ...nullableType ? { type: nullableType } : {}
+      };
+    }
+    return {
+      ...rest,
+      ...nullableType ? { type: nullableType } : {},
+      enum: [constValue, null]
+    };
+  }
+  const types = toTypeArray(schema.type);
+  if (types === null) {
+    throw new SchemaError(
+      "MODE_CONFIGURATION_INVALID",
+      "mnemonicSchema.nullable(...) requires a schema with type, enum, or const"
+    );
+  }
+  return {
+    ...schema,
+    type: types.includes("null") ? types : [...types, "null"]
+  };
+}
+var mnemonicSchema = {
+  string(options = {}) {
+    return withType("string", options);
+  },
+  number(options = {}) {
+    return withType("number", options);
+  },
+  integer(options = {}) {
+    return withType("integer", options);
+  },
+  boolean() {
+    return withType("boolean");
+  },
+  nullValue() {
+    return withType("null");
+  },
+  literal(value) {
+    return {
+      const: value
+    };
+  },
+  enum(values) {
+    return {
+      enum: values
+    };
+  },
+  optional(schema) {
+    return markOptional(schema);
+  },
+  nullable(schema) {
+    return nullableSchema(schema);
+  },
+  array(itemSchema, options = {}) {
+    return withType("array", {
+      items: withoutOptionalMarker(itemSchema),
+      ...options
+    });
+  },
+  object(shape, options = {}) {
+    const properties = {};
+    const required = [];
+    for (const [name, schema] of Object.entries(shape)) {
+      properties[name] = withoutOptionalMarker(schema);
+      if (!isOptionalSchema(schema)) {
+        required.push(name);
+      }
+    }
+    const result = {
+      type: "object",
+      properties,
+      ...options
+    };
+    if (required.length > 0) {
+      result.required = required;
+    }
+    return result;
+  },
+  record(valueSchema) {
+    return withType("object", {
+      additionalProperties: withoutOptionalMarker(valueSchema)
+    });
+  }
+};
+
 // src/Mnemonic/structural-migrations.ts
 function resolveHelpers(helpers) {
   if (helpers) return helpers;
@@ -1465,6 +2172,6 @@ function dedupeChildrenBy(root, getKey, helpers) {
   return visit(root);
 }
 
-export { CodecError, JSONCodec, MnemonicProvider, SchemaError, compileSchema, createCodec, createSchemaRegistry, dedupeChildrenBy, findNodeById, insertChildIfMissing, renameNode, useMnemonicKey, useMnemonicRecovery, validateJsonSchema };
+export { CodecError, JSONCodec, MnemonicProvider, SchemaError, compileSchema, createCodec, createSchemaRegistry, dedupeChildrenBy, defineKeySchema, defineMigration, defineMnemonicKey, defineWriteMigration, findNodeById, insertChildIfMissing, mnemonicSchema, renameNode, useMnemonicKey, useMnemonicRecovery, validateJsonSchema };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map