react-mnemonic 1.0.0-beta.0 → 1.2.0-beta1

package/dist/core.cjs

@@ -0,0 +1,1322 @@
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('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 = react.createContext(null);
+function useMnemonic() {
+  const context = react.useContext(MnemonicContext);
+  if (!context) {
+    throw new Error("useMnemonic must be used within a MnemonicProvider");
+  }
+  return context;
+}
+function defaultBrowserStorage() {
+  const globalWindow = globalThis.window;
+  if (globalWindow === void 0) return void 0;
+  try {
+    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,
+  ssr
+}) {
+  if (schemaMode === "strict" && !schemaRegistry) {
+    throw new Error("MnemonicProvider strict mode requires schemaRegistry");
+  }
+  if (schemaMode === "autoschema" && typeof schemaRegistry?.registerSchema !== "function") {
+    throw new Error("MnemonicProvider autoschema mode requires schemaRegistry.registerSchema");
+  }
+  const store = react.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;
+    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) => {
+      const set = listeners.get(key);
+      if (!set) return;
+      for (const fn of set) fn();
+    };
+    const logAccessError = (err) => {
+      if (!accessErrorLogged && err instanceof DOMException && err.name !== "QuotaExceededError") {
+        console.error(
+          `[Mnemonic] Storage access error (${err.name}): ${err.message}. Data is cached in memory but may not persist.`
+        );
+        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 || 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 && !asyncContractViolationDetected) {
+        try {
+          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(
+              `[Mnemonic] Storage quota exceeded writing key "${key}". Data is cached in memory but will not persist.`
+            );
+            quotaErrorLogged = true;
+          }
+          logAccessError(err);
+        }
+      }
+      emit(key);
+      bumpDevToolsVersion(devToolsRoot, namespace, `set:${key}`);
+    };
+    const removeRaw = (key) => {
+      cache.set(key, null);
+      if (st && !asyncContractViolationDetected) {
+        try {
+          const result = st.removeItem(fullKey(key));
+          if (isPromiseLike(result)) {
+            handleAsyncStorageContractViolation("removeItem", result);
+          } else {
+            accessErrorLogged = false;
+          }
+        } catch (err) {
+          logAccessError(err);
+        }
+      }
+      emit(key);
+      bumpDevToolsVersion(devToolsRoot, namespace, `remove:${key}`);
+    };
+    const subscribeRaw = (key, listener) => {
+      let set = listeners.get(key);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        listeners.set(key, set);
+      }
+      set.add(listener);
+      readThrough(key);
+      return () => {
+        const s = listeners.get(key);
+        if (!s) return;
+        s.delete(listener);
+        if (s.size === 0) listeners.delete(key);
+      };
+    };
+    const getRawSnapshot = (key) => readThrough(key);
+    const keys = () => {
+      if (asyncContractViolationDetected) {
+        return Array.from(cache.entries()).filter(([, value]) => value != null).map(([key]) => key);
+      }
+      if (!canEnumerateKeys) return [];
+      return enumerateNamespaceKeys(st, prefix, storageAccessCallbacks);
+    };
+    const dump = () => {
+      const out = {};
+      for (const k of keys()) {
+        const raw = readThrough(k);
+        if (raw != null) out[k] = raw;
+      }
+      return out;
+    };
+    const reloadFromStorage = createReloadFromStorage({
+      storage: st,
+      hasAsyncContractViolation: () => asyncContractViolationDetected,
+      prefix,
+      listeners,
+      cache,
+      emit,
+      callbacks: storageAccessCallbacks,
+      devToolsRoot,
+      namespace
+    });
+    const store2 = {
+      prefix,
+      canEnumerateKeys,
+      subscribeRaw,
+      getRawSnapshot,
+      setRaw: writeRaw,
+      removeRaw,
+      keys,
+      dump,
+      reloadFromStorage,
+      schemaMode,
+      ssrHydration,
+      crossTabSyncMode,
+      ...schemaRegistry ? { schemaRegistry } : {}
+    };
+    if (devToolsRoot) {
+      registerDevToolsProvider({
+        devToolsRoot,
+        namespace,
+        store: store2,
+        dump,
+        keys,
+        readThrough,
+        writeRaw,
+        removeRaw
+      });
+    }
+    return store2;
+  }, [namespace, storage, enableDevTools, schemaMode, schemaRegistry, ssr?.hydration]);
+  react.useEffect(() => {
+    if (!storage?.onExternalChange) return;
+    return storage.onExternalChange((changedKeys) => store.reloadFromStorage(changedKeys));
+  }, [storage, store]);
+  return /* @__PURE__ */ jsxRuntime.jsx(MnemonicContext.Provider, { value: store, children });
+}
+function throwCoreProviderSchemaImportError(propName) {
+  throw new Error(
+    `[Mnemonic] MnemonicProvider from react-mnemonic/core does not support ${propName}. Import MnemonicProvider from "react-mnemonic/schema" or "react-mnemonic" for schema validation, autoschema, and migration support.`
+  );
+}
+function assertNoSchemaProps(props) {
+  if (props.schemaMode !== void 0) {
+    throwCoreProviderSchemaImportError("schemaMode");
+  }
+  if (props.schemaRegistry !== void 0) {
+    throwCoreProviderSchemaImportError("schemaRegistry");
+  }
+}
+function MnemonicProvider2(props) {
+  assertNoSchemaProps(props);
+  return /* @__PURE__ */ jsxRuntime.jsx(MnemonicProvider, { ...props });
+}
+
+// src/Mnemonic/codecs.ts
+var CodecError = class extends Error {
+  /**
+   * Creates a new CodecError.
+   *
+   * @param message - Human-readable error description
+   * @param cause - Optional underlying error that caused this failure
+   */
+  constructor(message, cause) {
+    super(message);
+    this.name = "CodecError";
+    this.cause = cause;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var JSONCodec = {
+  encode: (value) => JSON.stringify(value),
+  decode: (encoded) => JSON.parse(encoded)
+};
+function createCodec(encode, decode) {
+  return { encode, decode };
+}
+
+// src/Mnemonic/schema.ts
+var SchemaError = class extends Error {
+  /**
+   * Creates a new SchemaError.
+   *
+   * @param code - Machine-readable failure category
+   * @param message - Human-readable error description
+   * @param cause - Optional underlying error
+   */
+  constructor(code, message, cause) {
+    super(message);
+    this.name = "SchemaError";
+    this.code = code;
+    this.cause = cause;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/Mnemonic/use-shared.ts
+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, extra) {
+  const result = { value };
+  if (extra !== void 0) {
+    Object.assign(result, extra);
+  }
+  if (rewriteRaw !== void 0) result.rewriteRaw = rewriteRaw;
+  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 objectHasOwn(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,
+  schemaVersion,
+  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: schemaVersion ?? 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 useMnemonicKeyShared(keyOrDescriptor, options, schemaVersion) {
+  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,
+    ssr: ssrOptions
+  } = resolvedOptions;
+  const codec = codecOpt ?? JSONCodec;
+  const hydrationMode = ssrOptions?.hydration ?? api.ssrHydration;
+  const [hasMounted, setHasMounted] = react.useState(hydrationMode !== "client-only");
+  const developmentRuntime = isDevelopmentRuntime();
+  const contractFingerprint = react.useMemo(
+    () => developmentRuntime ? buildContractFingerprint({
+      api,
+      key,
+      defaultValue,
+      codecOpt,
+      ...{} ,
+      reconcile,
+      listenCrossTab,
+      ssrOptions
+    }) : null,
+    [
+      developmentRuntime,
+      api,
+      key,
+      defaultValue,
+      codecOpt,
+      schemaVersion,
+      reconcile,
+      listenCrossTab,
+      ssrOptions?.hydration,
+      ssrOptions?.serverValue
+    ]
+  );
+  const getFallback = react.useCallback(
+    (error) => typeof defaultValue === "function" ? defaultValue(error) : defaultValue,
+    [defaultValue]
+  );
+  const getServerValue = react.useCallback(() => {
+    const serverValue = ssrOptions?.serverValue;
+    if (serverValue === void 0) {
+      return getFallback();
+    }
+    return typeof serverValue === "function" ? serverValue() : serverValue;
+  }, [getFallback, ssrOptions?.serverValue]);
+  const parseEnvelope = react.useCallback(
+    (rawText) => {
+      try {
+        const parsed = JSON.parse(rawText);
+        if (typeof parsed !== "object" || parsed == null || !Number.isInteger(parsed.version) || parsed.version < 0 || !objectHasOwn(parsed, "payload")) {
+          return {
+            ok: false,
+            error: new SchemaError("INVALID_ENVELOPE", `Invalid envelope for key "${key}"`)
+          };
+        }
+        return { ok: true, envelope: parsed };
+      } catch (err) {
+        return {
+          ok: false,
+          error: new SchemaError("INVALID_ENVELOPE", `Invalid envelope for key "${key}"`, err)
+        };
+      }
+    },
+    [key]
+  );
+  const decodeStringPayload = react.useCallback(
+    (payload, activeCodec) => {
+      try {
+        return activeCodec.decode(payload);
+      } catch (err) {
+        throw err instanceof CodecError ? err : new CodecError(`Codec decode failed for key "${key}"`, err);
+      }
+    },
+    [key]
+  );
+  const buildFallbackResult = react.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 react.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 = react.useCallback(
+    () => ssrOptions?.serverValue === void 0 ? null : SSR_SNAPSHOT_TOKEN,
+    [ssrOptions?.serverValue]
+  );
+  const deferStorageRead = hydrationMode === "client-only" && !hasMounted;
+  const subscribe = react.useCallback(
+    (listener) => {
+      if (deferStorageRead) {
+        return () => void 0;
+      }
+      return api.subscribeRaw(key, listener);
+    },
+    [api, deferStorageRead, key]
+  );
+  const raw = react.useSyncExternalStore(
+    subscribe,
+    () => deferStorageRead ? getServerRawSnapshot() : api.getRawSnapshot(key),
+    getServerRawSnapshot
+  );
+  const decoded = react.useMemo(() => {
+    if (raw === SSR_SNAPSHOT_TOKEN) {
+      return withReadMetadata(getServerValue());
+    }
+    return decodeForRead(raw);
+  }, [decodeForRead, getServerValue, raw]);
+  const value = decoded.value;
+  react.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
+  ]);
+  react.useEffect(() => {
+    if (hasMounted) return;
+    setHasMounted(true);
+  }, [hasMounted, setHasMounted]);
+  react.useEffect(() => {
+    if (decoded.rewriteRaw && decoded.rewriteRaw !== raw) {
+      api.setRaw(key, decoded.rewriteRaw);
+    }
+  }, [api, decoded.rewriteRaw, key, raw]);
+  react.useEffect(() => {
+    onDecodedEffect?.(decoded);
+  }, [decoded, onDecodedEffect]);
+  const prevRef = react.useRef(value);
+  const mounted = react.useRef(false);
+  react.useEffect(() => {
+    if (mounted.current) return;
+    mounted.current = true;
+    onMount?.(value);
+    prevRef.current = value;
+  }, []);
+  react.useEffect(() => {
+    const prev = prevRef.current;
+    if (Object.is(prev, value)) return;
+    prevRef.current = value;
+    onChange?.(value, prev);
+  }, [value, onChange]);
+  react.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 = react.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 = react.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 = react.useMemo(() => {
+    return () => api.removeRaw(key);
+  }, [api, key]);
+  return react.useMemo(
+    () => ({
+      value,
+      set,
+      reset,
+      remove
+    }),
+    [value, set, reset, remove]
+  );
+}
+
+// src/Mnemonic/use-core.ts
+function throwCoreSchemaImportError(key) {
+  throw new Error(
+    `[Mnemonic] useMnemonicKey("${key}") requested schema features from react-mnemonic/core. Import useMnemonicKey from "react-mnemonic/schema" or "react-mnemonic" for schema validation, autoschema, and migration support.`
+  );
+}
+function useCoreRuntime(keyOrDescriptor, options) {
+  const shared = useMnemonicKeyShared(keyOrDescriptor, options);
+  const { api, key, codec, schema, reconcile, parseEnvelope, decodeStringPayload, buildFallbackResult } = shared;
+  if (schema?.version !== void 0 || api.schemaMode !== "default") {
+    throwCoreSchemaImportError(key);
+  }
+  const applyReconcile = useApplyReconcile({
+    key,
+    reconcile,
+    buildFallbackResult
+  });
+  const encodeForWrite = react.useCallback(
+    (nextValue) => {
+      return serializeEnvelope(0, codec.encode(nextValue));
+    },
+    [codec]
+  );
+  const decodeForRead = react.useCallback(
+    (rawText) => {
+      if (rawText == null) return buildFallbackResult();
+      const parsed = parseEnvelope(rawText);
+      if (!parsed.ok) return buildFallbackResult(parsed.error);
+      const envelope = parsed.envelope;
+      if (typeof envelope.payload !== "string") {
+        return applyReconcile({
+          value: envelope.payload,
+          persistedVersion: envelope.version,
+          serializeForPersist: encodeForWrite
+        });
+      }
+      try {
+        const decoded = decodeStringPayload(envelope.payload, codec);
+        return applyReconcile({
+          value: decoded,
+          persistedVersion: envelope.version,
+          serializeForPersist: encodeForWrite
+        });
+      } catch (err) {
+        return buildFallbackResult(err);
+      }
+    },
+    [applyReconcile, buildFallbackResult, codec, decodeStringPayload, encodeForWrite, parseEnvelope]
+  );
+  const additionalDevWarnings = react.useCallback(
+    ({ warnOnce: warnOnce2 }) => {
+      if (!api.schemaRegistry) return;
+      warnOnce2(
+        `core-schema-registry:${key}`,
+        `[Mnemonic] useMnemonicKey("${key}") is running from react-mnemonic/core, so registered schemas are ignored for this key. Import useMnemonicKey from "react-mnemonic/schema" or "react-mnemonic" to enable schema validation and migrations.`
+      );
+    },
+    [api.schemaRegistry, key]
+  );
+  return useMnemonicKeyState(shared, {
+    decodeForRead,
+    encodeForWrite,
+    additionalDevWarnings
+  });
+}
+function useMnemonicKey(keyOrDescriptor, options) {
+  return useCoreRuntime(keyOrDescriptor, 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;
+  const namespace = react.useMemo(() => api.prefix.endsWith(".") ? api.prefix.slice(0, -1) : api.prefix, [api.prefix]);
+  const emitRecovery = react.useCallback(
+    (action, clearedKeys) => {
+      const event = {
+        action,
+        namespace,
+        clearedKeys
+      };
+      onRecover?.(event);
+    },
+    [namespace, onRecover]
+  );
+  const listKeys = react.useCallback(() => api.keys(), [api]);
+  const clearResolvedKeys = react.useCallback(
+    (action, keys) => {
+      const clearedKeys = uniqueKeys(keys);
+      for (const key of clearedKeys) {
+        api.removeRaw(key);
+      }
+      emitRecovery(action, clearedKeys);
+      return clearedKeys;
+    },
+    [api, emitRecovery]
+  );
+  const clearKeys = react.useCallback(
+    (keys) => clearResolvedKeys("clear-keys", keys),
+    [clearResolvedKeys]
+  );
+  const clearAll = react.useCallback(() => {
+    if (!api.canEnumerateKeys) {
+      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, namespace]);
+  const clearMatching = react.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."
+        );
+      }
+      return clearResolvedKeys(
+        "clear-matching",
+        api.keys().filter((key) => predicate(key))
+      );
+    },
+    [api, clearResolvedKeys, namespace]
+  );
+  return react.useMemo(
+    () => ({
+      namespace,
+      canEnumerateKeys: api.canEnumerateKeys,
+      listKeys,
+      clearAll,
+      clearKeys,
+      clearMatching
+    }),
+    [namespace, api.canEnumerateKeys, listKeys, clearAll, clearKeys, clearMatching]
+  );
+}
+
+// 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
+  });
+}
+
+exports.CodecError = CodecError;
+exports.JSONCodec = JSONCodec;
+exports.MnemonicProvider = MnemonicProvider2;
+exports.SchemaError = SchemaError;
+exports.createCodec = createCodec;
+exports.defineMnemonicKey = defineMnemonicKey;
+exports.useMnemonicKey = useMnemonicKey;
+exports.useMnemonicRecovery = useMnemonicRecovery;
+//# sourceMappingURL=core.cjs.map
+//# sourceMappingURL=core.cjs.map