react-mnemonic 1.3.0 → 1.5.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { createContext, useMemo, useEffect, useCallback, createElement, useContext, useState, useSyncExternalStore, useRef } from 'react';
+import { createContext, useRef, useEffect, useMemo, useCallback, useContext, createElement, useState, useSyncExternalStore } from 'react';
 import { jsx } from 'react/jsx-runtime';
 
 // src/Mnemonic/provider.tsx
@@ -412,789 +412,368 @@ var SchemaError = class extends Error {
   }
 };
 
-// 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;
+// src/Mnemonic/persistence-shared.ts
+function objectHasOwn2(value, property) {
+  const hasOwn = Object.hasOwn;
+  if (typeof hasOwn === "function") {
+    return hasOwn(value, property);
   }
-  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;
+  return Object.getOwnPropertyDescriptor(value, property) !== void 0;
 }
-
-// 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);
+function parseEnvelope(key, rawText) {
+  try {
+    const parsed = JSON.parse(rawText);
+    if (typeof parsed !== "object" || parsed == null || !Number.isInteger(parsed.version) || parsed.version < 0 || !objectHasOwn2(parsed, "payload")) {
+      throw new SchemaError("INVALID_ENVELOPE", `Invalid envelope for key "${key}"`);
+    }
+    return parsed;
+  } catch (error) {
+    if (error instanceof SchemaError) {
+      throw error;
+    }
+    throw new SchemaError("INVALID_ENVELOPE", `Invalid envelope for key "${key}"`, error);
   }
-  if (rewriteRaw !== void 0) result.rewriteRaw = rewriteRaw;
-  return result;
 }
-function isDevelopmentRuntime() {
-  return getRuntimeNodeEnv() === "development";
+function decodeStringPayload(key, payload, codec) {
+  try {
+    return codec.decode(payload);
+  } catch (error) {
+    throw error instanceof CodecError ? error : new CodecError(`Codec decode failed for key "${key}"`, error);
+  }
 }
-function getDiagnosticWarnings(api) {
-  let warnings = diagnosticWarningRegistry.get(api);
-  if (!warnings) {
-    warnings = /* @__PURE__ */ new Set();
-    diagnosticWarningRegistry.set(api, warnings);
+function validateAgainstSchema(key, value, jsonSchema) {
+  const errors = validateJsonSchema(value, jsonSchema);
+  if (errors.length === 0) {
+    return;
   }
-  return warnings;
+  const message = errors.map((entry) => `${entry.path || "/"}: ${entry.message}`).join("; ");
+  throw new SchemaError("TYPE_MISMATCH", `Schema validation failed for key "${key}": ${message}`);
 }
-function warnOnce(api, id, message) {
-  const warnings = getDiagnosticWarnings(api);
-  if (warnings.has(id)) return;
-  warnings.add(id);
-  console.warn(message);
+function getLatestSchema(schemaRegistry, key) {
+  return schemaRegistry?.getLatestSchema(key);
 }
-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}]`;
+function getSchemaForVersion(schemaRegistry, key, version) {
+  return schemaRegistry?.getSchema(key, version);
+}
+function getMigrationPath(schemaRegistry, key, fromVersion, toVersion) {
+  return schemaRegistry?.getMigrationPath(key, fromVersion, toVersion) ?? null;
+}
+function resolveTargetWriteSchema({
+  key,
+  explicitVersion,
+  schemaMode,
+  schemaRegistry
+}) {
+  const latestSchema = getLatestSchema(schemaRegistry, key);
+  if (explicitVersion === void 0) {
+    return latestSchema;
   }
-  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)}`;
+  const explicitSchema = getSchemaForVersion(schemaRegistry, key, explicitVersion);
+  if (explicitSchema) {
+    return explicitSchema;
+  }
+  return schemaMode === "strict" ? void 0 : latestSchema;
+}
+function encodePersistedValueForWrite({
+  key,
+  nextValue,
+  codec,
+  explicitVersion,
+  schemaMode,
+  schemaRegistry
+}) {
+  const targetSchema = resolveTargetWriteSchema({
+    key,
+    explicitVersion,
+    schemaMode,
+    schemaRegistry
+  });
+  if (!targetSchema) {
+    if (explicitVersion !== void 0 && schemaMode === "strict") {
+      throw new SchemaError("WRITE_SCHEMA_REQUIRED", `Write requires schema for key "${key}" in strict mode`);
+    }
+    return serializeEnvelope(0, codec.encode(nextValue));
+  }
+  let valueToStore = nextValue;
+  const writeMigration = schemaRegistry?.getWriteMigration?.(key, targetSchema.version);
+  if (writeMigration) {
+    try {
+      valueToStore = writeMigration.migrate(valueToStore);
+    } catch (error) {
+      throw error instanceof SchemaError ? error : new SchemaError("MIGRATION_FAILED", `Write-time migration failed for key "${key}"`, error);
     }
-    return tag;
   }
+  validateAgainstSchema(key, valueToStore, targetSchema.schema);
+  return serializeEnvelope(targetSchema.version, valueToStore);
 }
-function isObjectLike(value) {
-  return value !== null && (typeof value === "object" || typeof value === "function");
+
+// src/Mnemonic/optional-bridge-adapter.ts
+function resolveOptionalDefaultValue(defaultValue) {
+  return typeof defaultValue === "function" ? defaultValue() : defaultValue;
 }
-function objectHasOwn2(value, property) {
-  const hasOwn = Object.hasOwn;
-  if (typeof hasOwn === "function") {
-    return hasOwn(value, property);
-  }
-  return Object.getOwnPropertyDescriptor(value, property) !== void 0;
+function getSchemaCapabilities(schemaRegistry) {
+  return schemaRegistry !== 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 buildFallbackResult(options) {
+  return {
+    value: resolveOptionalDefaultValue(options.defaultValue)
+  };
 }
-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({
+function encodeValueForWrite(key, nextValue, options, schemaMode, schemaRegistry) {
+  return encodePersistedValueForWrite({
     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
+    nextValue,
+    codec: options.codec ?? JSONCodec,
+    explicitVersion: options.schema?.version,
+    schemaMode,
+    schemaRegistry
   });
 }
-function resolveMnemonicKeyArgs(keyOrDescriptor, options) {
-  if (typeof keyOrDescriptor !== "string") {
-    return keyOrDescriptor;
+function decodeCodecManagedEnvelope(key, envelope, options) {
+  if (typeof envelope.payload !== "string") {
+    return {
+      value: envelope.payload
+    };
   }
-  if (!options) {
-    throw new Error("useMnemonicKey requires options when called with a string key");
+  return {
+    value: decodeStringPayload(key, envelope.payload, options.codec ?? JSONCodec)
+  };
+}
+function decodeAutoschemaEnvelope(key, envelope, options, schemaRegistry) {
+  if (!schemaRegistry?.registerSchema) {
+    throw new SchemaError(
+      "MODE_CONFIGURATION_INVALID",
+      `Autoschema mode requires schema registry registration for key "${key}"`
+    );
   }
+  const decoded = typeof envelope.payload === "string" ? decodeStringPayload(key, envelope.payload, options.codec ?? JSONCodec) : envelope.payload;
+  const pendingSchema = {
+    key,
+    version: 1,
+    schema: inferJsonSchema(decoded)
+  };
   return {
-    key: keyOrDescriptor,
-    options
+    value: decoded,
+    rewriteRaw: serializeEnvelope(pendingSchema.version, decoded),
+    pendingSchema
   };
 }
-function useMnemonicKeySharedFromApi(api, keyOrDescriptor, options, schemaVersion) {
-  const descriptor = resolveMnemonicKeyArgs(keyOrDescriptor, options);
-  const key = descriptor.key;
-  const resolvedOptions = descriptor.options;
-  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] = useState(hydrationMode !== "client-only");
-  const developmentRuntime = isDevelopmentRuntime();
-  const contractFingerprint = useMemo(
-    () => developmentRuntime ? buildContractFingerprint({
-      api,
-      key,
-      defaultValue,
-      codecOpt,
-      ...schemaVersion === void 0 ? {} : { schemaVersion },
-      reconcile,
-      listenCrossTab,
-      ssrOptions
-    }) : null,
-    [
-      developmentRuntime,
-      api,
-      key,
-      defaultValue,
-      codecOpt,
-      schemaVersion,
-      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 parseEnvelope2 = useCallback(
-    (rawText) => {
-      try {
-        const parsed = JSON.parse(rawText);
-        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}"`)
-          };
-        }
-        return { ok: true, envelope: parsed };
-      } catch (err) {
-        return {
-          ok: false,
-          error: new SchemaError("INVALID_ENVELOPE", `Invalid envelope for key "${key}"`, err)
-        };
-      }
-    },
-    [key]
-  );
-  const decodeStringPayload2 = 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 buildFallbackResult2 = useCallback(
-    (error, extra) => {
-      return withReadMetadata(getFallback(error), void 0, extra);
-    },
-    [getFallback]
-  );
+function decodeSchemaManagedEnvelope(key, envelope, schemaForVersion, latestSchema, schemaRegistry) {
+  let current = envelope.payload;
+  validateAgainstSchema(key, current, schemaForVersion.schema);
+  if (!latestSchema || envelope.version >= latestSchema.version) {
+    return {
+      value: current
+    };
+  }
+  const path = getMigrationPath(schemaRegistry, key, envelope.version, latestSchema.version);
+  if (!path) {
+    throw new SchemaError(
+      "MIGRATION_PATH_NOT_FOUND",
+      `No migration path for key "${key}" from v${envelope.version} to v${latestSchema.version}`
+    );
+  }
+  for (const step of path) {
+    current = step.migrate(current);
+  }
+  validateAgainstSchema(key, current, latestSchema.schema);
   return {
-    api,
-    key,
-    codec,
-    codecOpt,
-    schema,
-    reconcile,
-    onMount,
-    onChange,
-    listenCrossTab,
-    getFallback,
-    getServerValue,
-    parseEnvelope: parseEnvelope2,
-    decodeStringPayload: decodeStringPayload2,
-    buildFallbackResult: buildFallbackResult2,
-    developmentRuntime,
-    contractFingerprint,
-    hasMounted,
-    setHasMounted,
-    hydrationMode,
-    ssrOptions
+    value: current,
+    rewriteRaw: serializeEnvelope(latestSchema.version, current)
   };
 }
-function useApplyReconcile({
-  key,
-  reconcile,
-  buildFallbackResult: buildFallbackResult2
+function decodePersistedValue(key, raw, options, api, schemaRegistry) {
+  if (raw == null) {
+    return buildFallbackResult(options);
+  }
+  const envelope = parseEnvelope(key, raw);
+  const latestSchema = getLatestSchema(schemaRegistry, key);
+  const schemaForVersion = getSchemaForVersion(schemaRegistry, key, envelope.version);
+  if (api.schemaMode === "strict" && !schemaForVersion) {
+    throw new SchemaError("SCHEMA_NOT_FOUND", `No schema for key "${key}" v${envelope.version}`);
+  }
+  if (api.schemaMode === "autoschema" && !schemaForVersion) {
+    return decodeAutoschemaEnvelope(key, envelope, options, schemaRegistry);
+  }
+  if (!schemaForVersion) {
+    return decodeCodecManagedEnvelope(key, envelope, options);
+  }
+  return decodeSchemaManagedEnvelope(key, envelope, schemaForVersion, latestSchema, schemaRegistry);
+}
+function createMnemonicOptionalBridge({
+  api,
+  schemaRegistry
 }) {
-  return useCallback(
-    ({
-      value,
-      rewriteRaw,
-      extra,
-      persistedVersion,
-      latestVersion,
-      serializeForPersist,
-      deriveExtra
-    }) => {
-      if (!reconcile) {
-        return withReadMetadata(value, rewriteRaw, extra);
-      }
-      const context = {
-        key,
-        persistedVersion
-      };
-      if (latestVersion !== void 0) {
-        context.latestVersion = latestVersion;
+  return {
+    namespace: api.prefix.endsWith(".") ? api.prefix.slice(0, -1) : api.prefix,
+    capabilities: {
+      persistence: true,
+      schema: getSchemaCapabilities(schemaRegistry)
+    },
+    subscribeRaw: (key, listener) => api.subscribeRaw(key, listener),
+    getRawSnapshot: (key) => api.getRawSnapshot(key),
+    decodeSnapshot: (key, raw, options) => {
+      try {
+        return decodePersistedValue(key, raw, options, api, schemaRegistry);
+      } catch {
+        return buildFallbackResult(options);
       }
-      const baselineSerialized = (() => {
-        try {
-          return serializeForPersist(value);
-        } catch {
-          return rewriteRaw;
-        }
-      })();
+    },
+    setValue: (key, nextValue, options) => {
       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 buildFallbackResult2(typedErr, extra);
+        api.setRaw(key, encodeValueForWrite(key, nextValue, options, api.schemaMode, schemaRegistry));
+      } catch (error) {
+        if (error instanceof SchemaError) {
+          console.error(`[Mnemonic] Schema error for key "${key}" (${error.code}):`, error.message);
+          return;
+        }
+        if (error instanceof CodecError) {
+          console.error(`[Mnemonic] Codec error for key "${key}":`, error.message);
+          return;
+        }
+        throw error;
       }
     },
-    [buildFallbackResult2, 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, active = true, additionalDevWarnings, onDecodedEffect } = config;
-  const getServerRawSnapshot = useCallback(
-    () => ssrOptions?.serverValue === void 0 ? null : SSR_SNAPSHOT_TOKEN,
-    [ssrOptions?.serverValue]
-  );
-  const deferStorageRead = hydrationMode === "client-only" && !hasMounted;
-  const subscribe = useCallback(
-    (listener) => {
-      if (!active) {
-        return () => void 0;
+    removeValue: (key) => {
+      api.removeRaw(key);
+    },
+    commitSnapshot: (key, raw, snapshot) => {
+      if (snapshot.pendingSchema && schemaRegistry?.registerSchema) {
+        if (!schemaRegistry.getSchema(snapshot.pendingSchema.key, snapshot.pendingSchema.version)) {
+          try {
+            schemaRegistry.registerSchema(snapshot.pendingSchema);
+          } catch {
+          }
+        }
       }
-      if (deferStorageRead) {
-        return () => void 0;
+      if (snapshot.rewriteRaw !== void 0 && snapshot.rewriteRaw !== raw) {
+        api.setRaw(key, snapshot.rewriteRaw);
       }
-      return api.subscribeRaw(key, listener);
-    },
-    [active, api, deferStorageRead, key]
-  );
-  const raw = useSyncExternalStore(
-    subscribe,
-    () => active && !deferStorageRead ? api.getRawSnapshot(key) : getServerRawSnapshot(),
-    getServerRawSnapshot
-  );
-  const decoded = useMemo(() => {
-    if (raw === SSR_SNAPSHOT_TOKEN) {
-      return withReadMetadata(getServerValue());
     }
-    return decodeForRead(raw);
-  }, [decodeForRead, getServerValue, raw]);
-  const value = decoded.value;
-  useEffect(() => {
-    if (!active) return;
-    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.`
-      );
+  };
+}
+var OPTIONAL_BRIDGE_CONTEXT_KEY = /* @__PURE__ */ Symbol.for("react-mnemonic.optional-bridge-context");
+function getMnemonicOptionalBridgeContext() {
+  const globalStore = globalThis;
+  const existing = globalStore[OPTIONAL_BRIDGE_CONTEXT_KEY];
+  if (existing) {
+    return existing;
+  }
+  const context = createContext(null);
+  globalStore[OPTIONAL_BRIDGE_CONTEXT_KEY] = context;
+  return context;
+}
+var MnemonicOptionalBridgeContext = getMnemonicOptionalBridgeContext();
+
+// src/Mnemonic/optional-bridge-provider.tsx
+function MnemonicOptionalBridgeProvider({
+  bridge,
+  children
+}) {
+  return createElement(MnemonicOptionalBridgeContext.Provider, { value: bridge }, children);
+}
+
+// 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 getDefaultBrowserStorage() {
+  const globalWindow = globalThis.window;
+  if (globalWindow === void 0) return void 0;
+  try {
+    return globalWindow.localStorage;
+  } catch {
+    return void 0;
+  }
+}
+function getNativeBrowserStorages() {
+  const globalWindow = globalThis.window;
+  if (!globalWindow) return [];
+  const storages = [];
+  const addStorage = (getter) => {
+    try {
+      storages.push(getter());
+    } catch {
     }
-    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.`
-    );
-  }, [
-    active,
-    additionalDevWarnings,
-    api,
-    key,
-    developmentRuntime,
-    contractFingerprint,
-    listenCrossTab,
-    codecOpt,
-    schema,
-    api.crossTabSyncMode
-  ]);
-  useEffect(() => {
-    if (hasMounted) return;
-    setHasMounted(true);
-  }, [hasMounted, setHasMounted]);
-  useEffect(() => {
-    if (!active) return;
-    if (decoded.rewriteRaw && decoded.rewriteRaw !== raw) {
-      api.setRaw(key, decoded.rewriteRaw);
-    }
-  }, [active, api, decoded.rewriteRaw, key, raw]);
-  useEffect(() => {
-    if (!active) return;
-    onDecodedEffect?.(decoded);
-  }, [active, decoded, onDecodedEffect]);
-  const prevRef = useRef(value);
-  const mounted = useRef(false);
-  useEffect(() => {
-    if (!active) return;
-    if (mounted.current) return;
-    mounted.current = true;
-    onMount?.(value);
-    prevRef.current = value;
-  }, [active]);
-  useEffect(() => {
-    if (!active) return;
-    const prev = prevRef.current;
-    if (Object.is(prev, value)) return;
-    prevRef.current = value;
-    onChange?.(value, prev);
-  }, [active, value, onChange]);
-  useEffect(() => {
-    if (!active) return;
-    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);
-  }, [active, listenCrossTab, api, key]);
-  const set = useMemo(() => {
-    if (!active) {
-      return () => void 0;
-    }
-    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);
-      }
-    };
-  }, [active, api, key, decodeForRead, encodeForWrite]);
-  const reset = useMemo(() => {
-    if (!active) {
-      return () => void 0;
-    }
-    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;
-      }
-    };
-  }, [active, api, key, getFallback, encodeForWrite]);
-  const remove = useMemo(() => {
-    if (!active) {
-      return () => void 0;
-    }
-    return () => api.removeRaw(key);
-  }, [active, api, key]);
-  return useMemo(
-    () => ({
-      value,
-      set,
-      reset,
-      remove
-    }),
-    [value, set, reset, remove]
-  );
-}
-
-// src/Mnemonic/optional-bridge-adapter.ts
-function resolveOptionalDefaultValue(defaultValue) {
-  return typeof defaultValue === "function" ? defaultValue() : defaultValue;
+  };
+  addStorage(() => globalWindow.localStorage);
+  addStorage(() => globalWindow.sessionStorage);
+  return storages;
 }
-function objectHasOwn3(value, property) {
-  const hasOwn = Object.hasOwn;
-  if (typeof hasOwn === "function") {
-    return hasOwn(value, property);
+var MnemonicContext = createContext(null);
+var warnedNestedProviderStores = /* @__PURE__ */ new WeakSet();
+function useMnemonic() {
+  const context = useMnemonicOptional();
+  if (!context) {
+    throw new Error("useMnemonic must be used within a MnemonicProvider");
   }
-  return Object.getOwnPropertyDescriptor(value, property) !== void 0;
+  return context;
 }
-function parseEnvelope(key, rawText) {
-  try {
-    const parsed = JSON.parse(rawText);
-    if (typeof parsed !== "object" || parsed == null || !Number.isInteger(parsed.version) || parsed.version < 0 || !objectHasOwn3(parsed, "payload")) {
-      throw new SchemaError("INVALID_ENVELOPE", `Invalid envelope for key "${key}"`);
-    }
-    return parsed;
-  } catch (error) {
-    if (error instanceof SchemaError) {
-      throw error;
-    }
-    throw new SchemaError("INVALID_ENVELOPE", `Invalid envelope for key "${key}"`, error);
-  }
+function useMnemonicOptional() {
+  return useContext(MnemonicContext);
 }
-function decodeStringPayload(key, payload, options) {
-  const codec = options.codec ?? JSONCodec;
+function detectEnumerableStorage(storage) {
+  if (!storage) return false;
   try {
-    return codec.decode(payload);
-  } catch (error) {
-    throw error instanceof CodecError ? error : new CodecError(`Codec decode failed for key "${key}"`, error);
+    return typeof storage.length === "number" && typeof storage.key === "function";
+  } catch {
+    return false;
   }
 }
-function validateAgainstSchema(key, value, jsonSchema) {
-  const errors = validateJsonSchema(value, jsonSchema);
-  if (errors.length === 0) {
-    return;
+function isProductionRuntime() {
+  const env = getRuntimeNodeEnv();
+  if (env === void 0) {
+    return true;
   }
-  const message = errors.map((entry) => `${entry.path || "/"}: ${entry.message}`).join("; ");
-  throw new SchemaError("TYPE_MISMATCH", `Schema validation failed for key "${key}": ${message}`);
+  return env === "production";
 }
-function getSchemaCapabilities(schemaRegistry) {
-  return schemaRegistry !== void 0;
+function weakRefConstructor() {
+  const ctor = globalThis.WeakRef;
+  return typeof ctor === "function" ? ctor : null;
 }
-function buildFallbackResult(options) {
-  return {
-    value: resolveOptionalDefaultValue(options.defaultValue)
-  };
+function hasFinalizationRegistry() {
+  return typeof globalThis.FinalizationRegistry === "function";
 }
-function getLatestSchema(schemaRegistry, key) {
-  return schemaRegistry?.getLatestSchema(key);
+function isPromiseLike(value) {
+  if (value == null) return false;
+  if (typeof value !== "object" && typeof value !== "function") return false;
+  return typeof value.then === "function";
 }
-function getSchemaForVersion(schemaRegistry, key, version) {
-  return schemaRegistry?.getSchema(key, version);
+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 getMigrationPath(schemaRegistry, key, fromVersion, toVersion) {
-  return schemaRegistry?.getMigrationPath(key, fromVersion, toVersion) ?? null;
+function getDevToolsWindow() {
+  return globalThis.window;
 }
-function encodeValueForWrite(key, nextValue, options, schemaRegistry) {
-  const explicitVersion = options.schema?.version;
-  const latestSchema = getLatestSchema(schemaRegistry, key);
-  const targetSchema = explicitVersion === void 0 ? latestSchema : getSchemaForVersion(schemaRegistry, key, explicitVersion) ?? latestSchema;
-  if (!targetSchema) {
-    const codec = options.codec ?? JSONCodec;
-    return serializeEnvelope(0, codec.encode(nextValue));
-  }
-  let valueToStore = nextValue;
-  const writeMigration = schemaRegistry?.getWriteMigration?.(key, targetSchema.version);
-  if (writeMigration) {
+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 {
-      valueToStore = writeMigration.migrate(valueToStore);
-    } catch (error) {
-      throw error instanceof SchemaError ? error : new SchemaError("MIGRATION_FAILED", `Write-time migration failed for key "${key}"`, error);
-    }
-  }
-  validateAgainstSchema(key, valueToStore, targetSchema.schema);
-  return serializeEnvelope(targetSchema.version, valueToStore);
-}
-function decodeCodecManagedEnvelope(key, envelope, options) {
-  if (typeof envelope.payload !== "string") {
-    return {
-      value: envelope.payload
-    };
-  }
-  return {
-    value: decodeStringPayload(key, envelope.payload, options)
-  };
-}
-function decodeAutoschemaEnvelope(key, envelope, options, schemaRegistry) {
-  if (!schemaRegistry?.registerSchema) {
-    throw new SchemaError(
-      "MODE_CONFIGURATION_INVALID",
-      `Autoschema mode requires schema registry registration for key "${key}"`
-    );
-  }
-  const decoded = typeof envelope.payload === "string" ? decodeStringPayload(key, envelope.payload, options) : envelope.payload;
-  const pendingSchema = {
-    key,
-    version: 1,
-    schema: inferJsonSchema(decoded)
-  };
-  return {
-    value: decoded,
-    rewriteRaw: serializeEnvelope(pendingSchema.version, decoded),
-    pendingSchema
-  };
-}
-function decodeSchemaManagedEnvelope(key, envelope, schemaForVersion, latestSchema, schemaRegistry) {
-  let current = envelope.payload;
-  validateAgainstSchema(key, current, schemaForVersion.schema);
-  if (!latestSchema || envelope.version >= latestSchema.version) {
-    return {
-      value: current
-    };
-  }
-  const path = getMigrationPath(schemaRegistry, key, envelope.version, latestSchema.version);
-  if (!path) {
-    throw new SchemaError(
-      "MIGRATION_PATH_NOT_FOUND",
-      `No migration path for key "${key}" from v${envelope.version} to v${latestSchema.version}`
-    );
-  }
-  for (const step of path) {
-    current = step.migrate(current);
-  }
-  validateAgainstSchema(key, current, latestSchema.schema);
-  return {
-    value: current,
-    rewriteRaw: serializeEnvelope(latestSchema.version, current)
-  };
-}
-function decodePersistedValue(key, raw, options, api, schemaRegistry) {
-  if (raw == null) {
-    return buildFallbackResult(options);
-  }
-  const envelope = parseEnvelope(key, raw);
-  const latestSchema = getLatestSchema(schemaRegistry, key);
-  const schemaForVersion = getSchemaForVersion(schemaRegistry, key, envelope.version);
-  if (api.schemaMode === "strict" && !schemaForVersion) {
-    throw new SchemaError("SCHEMA_NOT_FOUND", `No schema for key "${key}" v${envelope.version}`);
-  }
-  if (api.schemaMode === "autoschema" && !schemaForVersion) {
-    return decodeAutoschemaEnvelope(key, envelope, options, schemaRegistry);
-  }
-  if (!schemaForVersion) {
-    return decodeCodecManagedEnvelope(key, envelope, options);
-  }
-  return decodeSchemaManagedEnvelope(key, envelope, schemaForVersion, latestSchema, schemaRegistry);
-}
-function createMnemonicOptionalBridge({
-  api,
-  schemaRegistry
-}) {
-  return {
-    namespace: api.prefix.endsWith(".") ? api.prefix.slice(0, -1) : api.prefix,
-    capabilities: {
-      persistence: true,
-      schema: getSchemaCapabilities(schemaRegistry)
-    },
-    subscribeRaw: (key, listener) => api.subscribeRaw(key, listener),
-    getRawSnapshot: (key) => api.getRawSnapshot(key),
-    decodeSnapshot: (key, raw, options) => {
-      try {
-        return decodePersistedValue(key, raw, options, api, schemaRegistry);
-      } catch {
-        return buildFallbackResult(options);
-      }
-    },
-    setValue: (key, nextValue, options) => {
-      try {
-        api.setRaw(key, encodeValueForWrite(key, nextValue, options, schemaRegistry));
-      } catch (error) {
-        if (error instanceof SchemaError) {
-          console.error(`[Mnemonic] Schema error for key "${key}" (${error.code}):`, error.message);
-          return;
-        }
-        if (error instanceof CodecError) {
-          console.error(`[Mnemonic] Codec error for key "${key}":`, error.message);
-          return;
-        }
-        throw error;
-      }
-    },
-    removeValue: (key) => {
-      api.removeRaw(key);
-    },
-    commitSnapshot: (key, raw, snapshot) => {
-      if (snapshot.pendingSchema && schemaRegistry?.registerSchema) {
-        if (!schemaRegistry.getSchema(snapshot.pendingSchema.key, snapshot.pendingSchema.version)) {
-          try {
-            schemaRegistry.registerSchema(snapshot.pendingSchema);
-          } catch {
-          }
-        }
-      }
-      if (snapshot.rewriteRaw !== void 0 && snapshot.rewriteRaw !== raw) {
-        api.setRaw(key, snapshot.rewriteRaw);
-      }
-    }
-  };
-}
-var MnemonicOptionalBridgeContext = createContext(null);
-
-// src/Mnemonic/optional-bridge-provider.tsx
-function MnemonicOptionalBridgeProvider({
-  bridge,
-  children
-}) {
-  return createElement(MnemonicOptionalBridgeContext.Provider, { value: bridge }, children);
-}
-var MnemonicContext = createContext(null);
-function useMnemonic() {
-  const context = useMnemonicOptional();
-  if (!context) {
-    throw new Error("useMnemonic must be used within a MnemonicProvider");
-  }
-  return context;
-}
-function useMnemonicOptional() {
-  return useContext(MnemonicContext);
-}
-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 {
+      delete root[key];
+    } catch {
     }
   }
 }
@@ -1530,7 +1109,8 @@ function MnemonicProvider({
   enableDevTools = false,
   schemaMode = "default",
   schemaRegistry,
-  ssr
+  ssr,
+  bootstrap
 }) {
   if (schemaMode === "strict" && !schemaRegistry) {
     throw new Error("MnemonicProvider strict mode requires schemaRegistry");
@@ -1538,14 +1118,32 @@ function MnemonicProvider({
   if (schemaMode === "autoschema" && typeof schemaRegistry?.registerSchema !== "function") {
     throw new Error("MnemonicProvider autoschema mode requires schemaRegistry.registerSchema");
   }
+  const prefix = `${namespace}.`;
+  const parentStore = useMnemonicOptional();
+  const bootstrapRawSeed = useRef(bootstrap?.raw).current;
+  useEffect(() => {
+    if (isProductionRuntime()) return;
+    if (parentStore?.prefix !== prefix) return;
+    if (warnedNestedProviderStores.has(parentStore)) return;
+    warnedNestedProviderStores.add(parentStore);
+    console.warn(
+      `[Mnemonic] Nested MnemonicProvider detected for namespace "${namespace}". The nearest provider wins, so the inner provider creates a separate store and cache even though the namespace matches. Prefer a single provider per namespace, or use distinct namespaces for intentionally separate scopes.`
+    );
+  }, [namespace, parentStore, prefix]);
   const store = useMemo(() => {
-    const prefix = `${namespace}.`;
-    const st = storage ?? defaultBrowserStorage();
+    const st = storage ?? getDefaultBrowserStorage();
     const ssrHydration = ssr?.hydration ?? "immediate";
     const devToolsRoot = ensureDevToolsRoot(enableDevTools);
     const canEnumerateKeys = detectEnumerableStorage(st);
     const crossTabSyncMode = getCrossTabSyncMode(storage, st);
     const cache = /* @__PURE__ */ new Map();
+    if (bootstrapRawSeed) {
+      for (const [key, raw] of Object.entries(bootstrapRawSeed)) {
+        if (raw != null) {
+          cache.set(key, raw);
+        }
+      }
+    }
     const listeners = /* @__PURE__ */ new Map();
     let quotaErrorLogged = false;
     let accessErrorLogged = false;
@@ -1570,151 +1168,605 @@ 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 || asyncContractViolationDetected) {
-        cache.set(key, null);
-        return null;
+    };
+    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, bootstrapRawSeed]);
+  const optionalBridge = useMemo(
+    () => createMnemonicOptionalBridge({
+      api: store,
+      ...schemaRegistry ? { schemaRegistry } : {}
+    }),
+    [schemaRegistry, store]
+  );
+  useEffect(() => {
+    if (!storage?.onExternalChange) return;
+    return storage.onExternalChange((changedKeys) => store.reloadFromStorage(changedKeys));
+  }, [storage, store]);
+  return /* @__PURE__ */ jsx(MnemonicContext.Provider, { value: store, children: /* @__PURE__ */ jsx(MnemonicOptionalBridgeProvider, { bridge: optionalBridge, children }) });
+}
+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 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 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 useMnemonicKeySharedFromApi(api, keyOrDescriptor, options, schemaVersion) {
+  const descriptor = resolveMnemonicKeyArgs(keyOrDescriptor, options);
+  const key = descriptor.key;
+  const resolvedOptions = descriptor.options;
+  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] = useState(hydrationMode !== "client-only");
+  const developmentRuntime = isDevelopmentRuntime();
+  const contractFingerprint = useMemo(
+    () => developmentRuntime ? buildContractFingerprint({
+      api,
+      key,
+      defaultValue,
+      codecOpt,
+      ...schemaVersion === void 0 ? {} : { schemaVersion },
+      reconcile,
+      listenCrossTab,
+      ssrOptions
+    }) : null,
+    [
+      developmentRuntime,
+      api,
+      key,
+      defaultValue,
+      codecOpt,
+      schemaVersion,
+      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 parseEnvelope2 = useCallback(
+    (rawText) => {
+      try {
+        return { ok: true, envelope: parseEnvelope(key, rawText) };
+      } catch (error) {
+        return {
+          ok: false,
+          error: error instanceof SchemaError ? error : new SchemaError("INVALID_ENVELOPE", `Invalid envelope for key "${key}"`, error)
+        };
+      }
+    },
+    [key]
+  );
+  const decodeStringPayload2 = useCallback(
+    (payload, activeCodec) => {
+      return decodeStringPayload(key, payload, activeCodec);
+    },
+    [key]
+  );
+  const buildFallbackResult2 = useCallback(
+    (error, extra) => {
+      return withReadMetadata(getFallback(error), void 0, extra);
+    },
+    [getFallback]
+  );
+  return {
+    api,
+    key,
+    codec,
+    codecOpt,
+    schema,
+    reconcile,
+    onMount,
+    onChange,
+    listenCrossTab,
+    getFallback,
+    getServerValue,
+    parseEnvelope: parseEnvelope2,
+    decodeStringPayload: decodeStringPayload2,
+    buildFallbackResult: buildFallbackResult2,
+    developmentRuntime,
+    contractFingerprint,
+    hasMounted,
+    setHasMounted,
+    hydrationMode,
+    ssrOptions
+  };
+}
+function useApplyReconcile({
+  key,
+  reconcile,
+  buildFallbackResult: buildFallbackResult2
+}) {
+  return useCallback(
+    ({
+      value,
+      rewriteRaw,
+      extra,
+      persistedVersion,
+      latestVersion,
+      serializeForPersist,
+      deriveExtra
+    }) => {
+      if (!reconcile) {
+        return withReadMetadata(value, rewriteRaw, extra);
+      }
+      const context = {
+        key,
+        persistedVersion
+      };
+      if (latestVersion !== void 0) {
+        context.latestVersion = latestVersion;
+      }
+      const baselineSerialized = (() => {
+        try {
+          return serializeForPersist(value);
+        } catch {
+          return rewriteRaw;
+        }
+      })();
+      try {
+        const reconciled = reconcile(value, context);
+        const nextExtra = deriveExtra ? deriveExtra(reconciled, extra) : extra;
+        const nextSerialized = serializeForPersist(reconciled);
+        const nextRewriteRaw = baselineSerialized === void 0 || nextSerialized !== baselineSerialized ? nextSerialized : rewriteRaw;
+        return withReadMetadata(reconciled, nextRewriteRaw, nextExtra);
+      } catch (err) {
+        const typedErr = err instanceof SchemaError ? err : new SchemaError("RECONCILE_FAILED", `Reconciliation failed for key "${key}"`, err);
+        return buildFallbackResult2(typedErr, extra);
+      }
+    },
+    [buildFallbackResult2, 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, active = true, additionalDevWarnings, onDecodedEffect } = config;
+  const getServerRawSnapshot = useCallback(
+    () => ssrOptions?.serverValue === void 0 ? null : SSR_SNAPSHOT_TOKEN,
+    [ssrOptions?.serverValue]
+  );
+  const deferStorageRead = hydrationMode === "client-only" && !hasMounted;
+  const subscribe = useCallback(
+    (listener) => {
+      if (!active) {
+        return () => void 0;
+      }
+      if (deferStorageRead) {
+        return () => void 0;
+      }
+      return api.subscribeRaw(key, listener);
+    },
+    [active, api, deferStorageRead, key]
+  );
+  const raw = useSyncExternalStore(
+    subscribe,
+    () => active && !deferStorageRead ? api.getRawSnapshot(key) : getServerRawSnapshot(),
+    getServerRawSnapshot
+  );
+  const decoded = useMemo(() => {
+    if (raw === SSR_SNAPSHOT_TOKEN) {
+      return withReadMetadata(getServerValue());
+    }
+    return decodeForRead(raw);
+  }, [decodeForRead, getServerValue, raw]);
+  const value = decoded.value;
+  useEffect(() => {
+    if (!active) return;
+    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.`
+    );
+  }, [
+    active,
+    additionalDevWarnings,
+    api,
+    key,
+    developmentRuntime,
+    contractFingerprint,
+    listenCrossTab,
+    codecOpt,
+    schema,
+    api.crossTabSyncMode
+  ]);
+  useEffect(() => {
+    if (hasMounted) return;
+    setHasMounted(true);
+  }, [hasMounted, setHasMounted]);
+  useEffect(() => {
+    if (!active) return;
+    if (decoded.rewriteRaw && decoded.rewriteRaw !== raw) {
+      api.setRaw(key, decoded.rewriteRaw);
+    }
+  }, [active, api, decoded.rewriteRaw, key, raw]);
+  useEffect(() => {
+    if (!active) return;
+    onDecodedEffect?.(decoded);
+  }, [active, decoded, onDecodedEffect]);
+  const prevRef = useRef(value);
+  const mounted = useRef(false);
+  useEffect(() => {
+    if (!active) return;
+    if (mounted.current) return;
+    mounted.current = true;
+    onMount?.(value);
+    prevRef.current = value;
+  }, [active]);
+  useEffect(() => {
+    if (!active) return;
+    const prev = prevRef.current;
+    if (Object.is(prev, value)) return;
+    prevRef.current = value;
+    onChange?.(value, prev);
+  }, [active, value, onChange]);
+  useEffect(() => {
+    if (!active) return;
+    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;
       }
-      const raw = readStorageRaw(st, fullKey(key), storageAccessCallbacks);
-      cache.set(key, raw);
-      return raw;
+      api.setRaw(key, e.newValue);
     };
-    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);
+    globalWindow.addEventListener("storage", handler);
+    return () => globalWindow.removeEventListener("storage", handler);
+  }, [active, listenCrossTab, api, key]);
+  const set = useMemo(() => {
+    if (!active) {
+      return () => void 0;
+    }
+    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;
         }
-      }
-      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);
+        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);
       }
-      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;
+  }, [active, api, key, decodeForRead, encodeForWrite]);
+  const reset = useMemo(() => {
+    if (!active) {
+      return () => void 0;
+    }
+    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;
       }
-      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
-      });
+  }, [active, api, key, getFallback, encodeForWrite]);
+  const remove = useMemo(() => {
+    if (!active) {
+      return () => void 0;
     }
-    return store2;
-  }, [namespace, storage, enableDevTools, schemaMode, schemaRegistry, ssr?.hydration]);
-  const optionalBridge = useMemo(
-    () => createMnemonicOptionalBridge({
-      api: store,
-      ...schemaRegistry ? { schemaRegistry } : {}
+    return () => api.removeRaw(key);
+  }, [active, api, key]);
+  return useMemo(
+    () => ({
+      value,
+      set,
+      reset,
+      remove
     }),
-    [schemaRegistry, store]
+    [value, set, reset, remove]
   );
-  useEffect(() => {
-    if (!storage?.onExternalChange) return;
-    return storage.onExternalChange((changedKeys) => store.reloadFromStorage(changedKeys));
-  }, [storage, store]);
-  return /* @__PURE__ */ jsx(MnemonicContext.Provider, { value: store, children: /* @__PURE__ */ jsx(MnemonicOptionalBridgeProvider, { bridge: optionalBridge, children }) });
 }
+
+// src/Mnemonic/use.ts
 function useSchemaMnemonicKeyFromApi(store, descriptor, active = true) {
   const shared = useMnemonicKeySharedFromApi(store, descriptor, void 0, descriptor.options.schema?.version);
   const { api, key, codec, codecOpt, schema, reconcile, parseEnvelope: parseEnvelope2, decodeStringPayload: decodeStringPayload2, buildFallbackResult: buildFallbackResult2 } = shared;
@@ -1783,7 +1835,7 @@ function useSchemaMnemonicKeyFromApi(store, descriptor, active = true) {
     reconcile,
     buildFallbackResult: buildFallbackResult2
   });
-  const resolveTargetWriteSchema = useCallback(() => {
+  const resolveTargetWriteSchema2 = useCallback(() => {
     const explicitVersion = schema?.version;
     const latestSchema = getLatestSchemaForKey();
     if (explicitVersion === void 0) return latestSchema;
@@ -1794,7 +1846,7 @@ function useSchemaMnemonicKeyFromApi(store, descriptor, active = true) {
   const encodeForWrite = useCallback(
     (nextValue) => {
       const explicitVersion = schema?.version;
-      const targetSchema = resolveTargetWriteSchema();
+      const targetSchema = resolveTargetWriteSchema2();
       if (!targetSchema) {
         if (explicitVersion !== void 0 && schemaMode === "strict") {
           throw new SchemaError(
@@ -1823,7 +1875,7 @@ function useSchemaMnemonicKeyFromApi(store, descriptor, active = true) {
       codec,
       schemaRegistry,
       validateAgainstSchema2,
-      resolveTargetWriteSchema,
+      resolveTargetWriteSchema2,
       buildSchemaManagedResult
     ]
   );