react-mnemonic 0.1.1-alpha.0

package/dist/index.js

@@ -0,0 +1,987 @@
+import { createContext, useMemo, useEffect, useCallback, useSyncExternalStore, useRef, useContext } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+// src/Mnemonic/provider.tsx
+var MnemonicContext = createContext(null);
+function useMnemonic() {
+  const context = useContext(MnemonicContext);
+  if (!context) {
+    throw new Error("useMnemonic must be used within a MnemonicProvider");
+  }
+  return context;
+}
+function defaultBrowserStorage() {
+  if (typeof window === "undefined") return void 0;
+  try {
+    return window.localStorage;
+  } catch {
+    return void 0;
+  }
+}
+function MnemonicProvider({
+  children,
+  namespace,
+  storage,
+  enableDevTools = false,
+  schemaMode = "default",
+  schemaRegistry
+}) {
+  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 = useMemo(() => {
+    const prefix = `${namespace}.`;
+    const st = storage ?? defaultBrowserStorage();
+    const cache = /* @__PURE__ */ new Map();
+    const listeners = /* @__PURE__ */ new Map();
+    let quotaErrorLogged = false;
+    let accessErrorLogged = false;
+    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 readThrough = (key) => {
+      if (cache.has(key)) return cache.get(key) ?? null;
+      if (!st) {
+        cache.set(key, null);
+        return null;
+      }
+      try {
+        const raw = st.getItem(fullKey(key));
+        cache.set(key, raw);
+        accessErrorLogged = false;
+        return raw;
+      } catch (err) {
+        logAccessError(err);
+        cache.set(key, null);
+        return null;
+      }
+    };
+    const writeRaw = (key, raw) => {
+      cache.set(key, raw);
+      if (st) {
+        try {
+          st.setItem(fullKey(key), raw);
+          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);
+    };
+    const removeRaw = (key) => {
+      cache.set(key, null);
+      if (st) {
+        try {
+          st.removeItem(fullKey(key));
+          accessErrorLogged = false;
+        } catch (err) {
+          logAccessError(err);
+        }
+      }
+      emit(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 (!st || typeof st.length !== "number" || typeof st.key !== "function") return [];
+      const out = [];
+      try {
+        for (let i = 0; i < st.length; i++) {
+          const k = st.key(i);
+          if (!k) continue;
+          if (k.startsWith(prefix)) out.push(k.slice(prefix.length));
+        }
+        accessErrorLogged = false;
+      } catch (err) {
+        logAccessError(err);
+      }
+      return out;
+    };
+    const dump = () => {
+      const out = {};
+      for (const k of keys()) {
+        const raw = readThrough(k);
+        if (raw != null) out[k] = raw;
+      }
+      return out;
+    };
+    const reloadFromStorage = (changedKeys) => {
+      if (!st) return;
+      if (changedKeys !== void 0 && changedKeys.length === 0) return;
+      if (changedKeys !== void 0) {
+        for (const fk of changedKeys) {
+          if (!fk.startsWith(prefix)) continue;
+          const key = fk.slice(prefix.length);
+          const listenerSet = listeners.get(key);
+          if (listenerSet && listenerSet.size > 0) {
+            let fresh;
+            try {
+              fresh = st.getItem(fk);
+              accessErrorLogged = false;
+            } catch (err) {
+              logAccessError(err);
+              fresh = null;
+            }
+            const cached = cache.get(key) ?? null;
+            if (fresh !== cached) {
+              cache.set(key, fresh);
+              emit(key);
+            }
+          } else if (cache.has(key)) {
+            cache.delete(key);
+          }
+        }
+        return;
+      }
+      for (const [key, listenerSet] of listeners) {
+        if (listenerSet.size === 0) continue;
+        let fresh;
+        try {
+          fresh = st.getItem(fullKey(key));
+          accessErrorLogged = false;
+        } catch (err) {
+          logAccessError(err);
+          fresh = null;
+        }
+        const cached = cache.get(key) ?? null;
+        if (fresh !== cached) {
+          cache.set(key, fresh);
+          emit(key);
+        }
+      }
+      for (const key of cache.keys()) {
+        if (!listeners.has(key) || listeners.get(key).size === 0) {
+          cache.delete(key);
+        }
+      }
+    };
+    const store2 = {
+      prefix,
+      subscribeRaw,
+      getRawSnapshot,
+      setRaw: writeRaw,
+      removeRaw,
+      keys,
+      dump,
+      reloadFromStorage,
+      schemaMode,
+      ...schemaRegistry ? { schemaRegistry } : {}
+    };
+    if (enableDevTools && typeof window !== "undefined") {
+      window.__REACT_MNEMONIC_DEVTOOLS__ = window.__REACT_MNEMONIC_DEVTOOLS__ || {};
+      window.__REACT_MNEMONIC_DEVTOOLS__[namespace] = {
+        /** Access the underlying store instance */
+        getStore: () => store2,
+        /** Dump all key-value pairs and display as a console table */
+        dump: () => {
+          const data = dump();
+          console.table(
+            Object.entries(data).map(([key, value]) => ({
+              key,
+              value,
+              decoded: (() => {
+                try {
+                  return JSON.parse(value);
+                } catch {
+                  return value;
+                }
+              })()
+            }))
+          );
+          return data;
+        },
+        /** Get a decoded value by key */
+        get: (key) => {
+          const raw = readThrough(key);
+          if (raw == null) return void 0;
+          try {
+            return JSON.parse(raw);
+          } catch {
+            return raw;
+          }
+        },
+        /** Set a value by key (automatically JSON-encoded) */
+        set: (key, value) => {
+          writeRaw(key, JSON.stringify(value));
+        },
+        /** Remove a key from storage */
+        remove: (key) => removeRaw(key),
+        /** Clear all keys in this namespace */
+        clear: () => {
+          for (const k of keys()) {
+            removeRaw(k);
+          }
+        },
+        /** List all keys in this namespace */
+        keys
+      };
+      console.info(
+        `[Mnemonic DevTools] Namespace "${namespace}" available at window.__REACT_MNEMONIC_DEVTOOLS__.${namespace}`
+      );
+    }
+    return store2;
+  }, [namespace, storage, enableDevTools, schemaMode, schemaRegistry]);
+  useEffect(() => {
+    if (!storage?.onExternalChange) return;
+    return storage.onExternalChange((changedKeys) => store.reloadFromStorage(changedKeys));
+  }, [storage, store]);
+  return /* @__PURE__ */ jsx(MnemonicContext.Provider, { value: store, children });
+}
+
+// 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/json-schema.ts
+function matchesType(value, type) {
+  switch (type) {
+    case "string":
+      return typeof value === "string";
+    case "number":
+      return typeof value === "number" && Number.isFinite(value);
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    case "boolean":
+      return typeof value === "boolean";
+    case "null":
+      return value === null;
+    case "object":
+      return typeof value === "object" && value !== null && !Array.isArray(value);
+    case "array":
+      return Array.isArray(value);
+    default:
+      return false;
+  }
+}
+function jsonDeepEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== typeof b) return false;
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b)) return false;
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!jsonDeepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  if (typeof a === "object") {
+    if (Array.isArray(b)) return false;
+    const aObj = a;
+    const bObj = b;
+    const aKeys = Object.keys(aObj);
+    const bKeys = Object.keys(bObj);
+    if (aKeys.length !== bKeys.length) return false;
+    for (const key of aKeys) {
+      if (!Object.prototype.hasOwnProperty.call(bObj, key)) return false;
+      if (!jsonDeepEqual(aObj[key], bObj[key])) return false;
+    }
+    return true;
+  }
+  return false;
+}
+var compiledCache = /* @__PURE__ */ new WeakMap();
+function compileSchema(schema) {
+  const cached = compiledCache.get(schema);
+  if (cached) return cached;
+  const compiled = buildValidator(schema);
+  compiledCache.set(schema, compiled);
+  return compiled;
+}
+function isJsonPrimitive(value) {
+  return value === null || typeof value !== "object";
+}
+function buildValidator(schema) {
+  const resolvedTypes = schema.type !== void 0 ? Array.isArray(schema.type) ? schema.type : [schema.type] : null;
+  const typeLabel = resolvedTypes !== null ? JSON.stringify(schema.type) : "";
+  const enumMembers = schema.enum;
+  let enumPrimitiveSet = null;
+  let enumComplexMembers = null;
+  if (enumMembers !== void 0) {
+    const primitives = [];
+    const complex = [];
+    for (const member of enumMembers) {
+      if (isJsonPrimitive(member)) {
+        primitives.push(member);
+      } else {
+        complex.push(member);
+      }
+    }
+    if (primitives.length > 0) enumPrimitiveSet = new Set(primitives);
+    if (complex.length > 0) enumComplexMembers = complex;
+  }
+  const hasConst = "const" in schema;
+  const constValue = schema.const;
+  const hasMinimum = schema.minimum !== void 0;
+  const minimum = schema.minimum;
+  const hasMaximum = schema.maximum !== void 0;
+  const maximum = schema.maximum;
+  const hasExMin = schema.exclusiveMinimum !== void 0;
+  const exMin = schema.exclusiveMinimum;
+  const hasExMax = schema.exclusiveMaximum !== void 0;
+  const exMax = schema.exclusiveMaximum;
+  const hasNumberConstraints = hasMinimum || hasMaximum || hasExMin || hasExMax;
+  const hasMinLength = schema.minLength !== void 0;
+  const minLen = schema.minLength;
+  const hasMaxLength = schema.maxLength !== void 0;
+  const maxLen = schema.maxLength;
+  const hasStringConstraints = hasMinLength || hasMaxLength;
+  const requiredKeys = schema.required;
+  const hasRequired = requiredKeys !== void 0 && requiredKeys.length > 0;
+  const hasProperties = schema.properties !== void 0;
+  const propertyValidators = hasProperties ? Object.entries(schema.properties).map(
+    ([name, propSchema]) => [name, compileSchema(propSchema)]
+  ) : null;
+  const checkAdditional = schema.additionalProperties !== void 0 && schema.additionalProperties !== true;
+  const additionalIsFalse = schema.additionalProperties === false;
+  const additionalValidator = checkAdditional && !additionalIsFalse ? compileSchema(schema.additionalProperties) : null;
+  const definedPropKeys = checkAdditional ? new Set(schema.properties ? Object.keys(schema.properties) : []) : null;
+  const hasObjectConstraints = hasRequired || hasProperties || checkAdditional;
+  const hasMinItems = schema.minItems !== void 0;
+  const minItems = schema.minItems;
+  const hasMaxItems = schema.maxItems !== void 0;
+  const maxItems = schema.maxItems;
+  const itemsValidator = schema.items !== void 0 ? compileSchema(schema.items) : null;
+  const hasArrayConstraints = hasMinItems || hasMaxItems || itemsValidator !== null;
+  if (resolvedTypes === null && enumMembers === void 0 && !hasConst && !hasNumberConstraints && !hasStringConstraints && !hasObjectConstraints && !hasArrayConstraints) {
+    return (_value, _path) => [];
+  }
+  return (value, path = "") => {
+    const errors = [];
+    if (resolvedTypes !== null) {
+      const matched = resolvedTypes.some((t) => matchesType(value, t));
+      if (!matched) {
+        errors.push({
+          path,
+          message: `Expected type ${typeLabel}, got ${jsonTypeLabel(value)}`,
+          keyword: "type"
+        });
+        return errors;
+      }
+    }
+    if (enumMembers !== void 0) {
+      let matched = false;
+      if (enumPrimitiveSet !== null && isJsonPrimitive(value)) {
+        matched = enumPrimitiveSet.has(value);
+      }
+      if (!matched && enumComplexMembers !== null) {
+        matched = enumComplexMembers.some((entry) => jsonDeepEqual(value, entry));
+      }
+      if (!matched) {
+        errors.push({
+          path,
+          message: `Value does not match any enum member`,
+          keyword: "enum"
+        });
+      }
+    }
+    if (hasConst) {
+      if (!jsonDeepEqual(value, constValue)) {
+        errors.push({
+          path,
+          message: `Value does not match const`,
+          keyword: "const"
+        });
+      }
+    }
+    if (hasNumberConstraints && typeof value === "number") {
+      if (hasMinimum && value < minimum) {
+        errors.push({
+          path,
+          message: `Value ${value} is less than minimum ${minimum}`,
+          keyword: "minimum"
+        });
+      }
+      if (hasMaximum && value > maximum) {
+        errors.push({
+          path,
+          message: `Value ${value} is greater than maximum ${maximum}`,
+          keyword: "maximum"
+        });
+      }
+      if (hasExMin && value <= exMin) {
+        errors.push({
+          path,
+          message: `Value ${value} is not greater than exclusiveMinimum ${exMin}`,
+          keyword: "exclusiveMinimum"
+        });
+      }
+      if (hasExMax && value >= exMax) {
+        errors.push({
+          path,
+          message: `Value ${value} is not less than exclusiveMaximum ${exMax}`,
+          keyword: "exclusiveMaximum"
+        });
+      }
+    }
+    if (hasStringConstraints && typeof value === "string") {
+      if (hasMinLength && value.length < minLen) {
+        errors.push({
+          path,
+          message: `String length ${value.length} is less than minLength ${minLen}`,
+          keyword: "minLength"
+        });
+      }
+      if (hasMaxLength && value.length > maxLen) {
+        errors.push({
+          path,
+          message: `String length ${value.length} is greater than maxLength ${maxLen}`,
+          keyword: "maxLength"
+        });
+      }
+    }
+    if (hasObjectConstraints && typeof value === "object" && value !== null && !Array.isArray(value)) {
+      const obj = value;
+      if (hasRequired) {
+        for (const reqKey of requiredKeys) {
+          if (!Object.prototype.hasOwnProperty.call(obj, reqKey)) {
+            errors.push({
+              path,
+              message: `Missing required property "${reqKey}"`,
+              keyword: "required"
+            });
+          }
+        }
+      }
+      if (propertyValidators !== null) {
+        for (const [propName, propValidator] of propertyValidators) {
+          if (Object.prototype.hasOwnProperty.call(obj, propName)) {
+            const propErrors = propValidator(obj[propName], `${path}/${propName}`);
+            errors.push(...propErrors);
+          }
+        }
+      }
+      if (checkAdditional) {
+        for (const objKey of Object.keys(obj)) {
+          if (!definedPropKeys.has(objKey)) {
+            if (additionalIsFalse) {
+              errors.push({
+                path,
+                message: `Additional property "${objKey}" is not allowed`,
+                keyword: "additionalProperties"
+              });
+            } else {
+              const propErrors = additionalValidator(obj[objKey], `${path}/${objKey}`);
+              errors.push(...propErrors);
+            }
+          }
+        }
+      }
+    }
+    if (hasArrayConstraints && Array.isArray(value)) {
+      if (hasMinItems && value.length < minItems) {
+        errors.push({
+          path,
+          message: `Array length ${value.length} is less than minItems ${minItems}`,
+          keyword: "minItems"
+        });
+      }
+      if (hasMaxItems && value.length > maxItems) {
+        errors.push({
+          path,
+          message: `Array length ${value.length} is greater than maxItems ${maxItems}`,
+          keyword: "maxItems"
+        });
+      }
+      if (itemsValidator !== null) {
+        for (let i = 0; i < value.length; i++) {
+          const itemErrors = itemsValidator(value[i], `${path}/${i}`);
+          errors.push(...itemErrors);
+        }
+      }
+    }
+    return errors;
+  };
+}
+function validateJsonSchema(value, schema, path = "") {
+  const compiled = compileSchema(schema);
+  return compiled(value, path);
+}
+function jsonTypeLabel(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+function inferJsonSchema(sample) {
+  if (sample === null) return { type: "null" };
+  if (Array.isArray(sample)) return { type: "array" };
+  switch (typeof sample) {
+    case "string":
+      return { type: "string" };
+    case "number":
+      return Number.isInteger(sample) ? { type: "number" } : { type: "number" };
+    case "boolean":
+      return { type: "boolean" };
+    case "object":
+      return { type: "object" };
+    default:
+      return {};
+  }
+}
+
+// src/Mnemonic/use.ts
+function useMnemonicKey(key, options) {
+  const api = useMnemonic();
+  const { defaultValue, onMount, onChange, listenCrossTab, codec: codecOpt, schema } = options;
+  const codec = codecOpt ?? JSONCodec;
+  const schemaMode = api.schemaMode;
+  const schemaRegistry = api.schemaRegistry;
+  const getFallback = useCallback(
+    (error) => typeof defaultValue === "function" ? defaultValue(error) : defaultValue,
+    [defaultValue]
+  );
+  const parseEnvelope = useCallback(
+    (rawText) => {
+      try {
+        const parsed = JSON.parse(rawText);
+        if (typeof parsed !== "object" || parsed == null || !Number.isInteger(parsed.version) || parsed.version < 0 || !Object.prototype.hasOwnProperty.call(parsed, "payload")) {
+          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 = useCallback(
+    (payload, activeCodec) => {
+      if (typeof payload !== "string") {
+        throw new SchemaError(
+          "INVALID_ENVELOPE",
+          `Envelope payload must be a string for codec-managed key "${key}"`
+        );
+      }
+      try {
+        return activeCodec.decode(payload);
+      } catch (err) {
+        throw err instanceof CodecError ? err : new CodecError(`Codec decode failed for key "${key}"`, err);
+      }
+    },
+    [key]
+  );
+  const validateAgainstSchema = useCallback(
+    (value2, jsonSchema) => {
+      const errors = validateJsonSchema(value2, jsonSchema);
+      if (errors.length > 0) {
+        const message = errors.map((e) => `${e.path || "/"}: ${e.message}`).join("; ");
+        throw new SchemaError("TYPE_MISMATCH", `Schema validation failed for key "${key}": ${message}`);
+      }
+    },
+    [key]
+  );
+  const registryCache = useMemo(() => {
+    if (!schemaRegistry || schemaMode === "autoschema") return null;
+    return {
+      latestSchema: void 0,
+      latestSchemaSet: false,
+      schemaByVersion: /* @__PURE__ */ new Map(),
+      migrationPaths: /* @__PURE__ */ new Map()
+    };
+  }, [schemaRegistry, schemaMode, key]);
+  const getSchemaForVersion = useCallback(
+    (version) => {
+      if (!schemaRegistry) return void 0;
+      if (!registryCache) return schemaRegistry.getSchema(key, version);
+      if (registryCache.schemaByVersion.has(version)) {
+        return registryCache.schemaByVersion.get(version);
+      }
+      const s = schemaRegistry.getSchema(key, version);
+      registryCache.schemaByVersion.set(version, s);
+      return s;
+    },
+    [schemaRegistry, registryCache, key]
+  );
+  const getLatestSchemaForKey = useCallback(() => {
+    if (!schemaRegistry) return void 0;
+    if (!registryCache) return schemaRegistry.getLatestSchema(key);
+    if (registryCache.latestSchemaSet) return registryCache.latestSchema;
+    const s = schemaRegistry.getLatestSchema(key);
+    registryCache.latestSchema = s;
+    registryCache.latestSchemaSet = true;
+    return s;
+  }, [schemaRegistry, registryCache, key]);
+  const getMigrationPathForKey = useCallback(
+    (fromVersion, toVersion) => {
+      if (!schemaRegistry) return null;
+      if (!registryCache) return schemaRegistry.getMigrationPath(key, fromVersion, toVersion) ?? null;
+      const cacheKey = `${fromVersion}->${toVersion}`;
+      if (registryCache.migrationPaths.has(cacheKey)) {
+        return registryCache.migrationPaths.get(cacheKey) ?? null;
+      }
+      const path = schemaRegistry.getMigrationPath(key, fromVersion, toVersion) ?? null;
+      registryCache.migrationPaths.set(cacheKey, path);
+      return path;
+    },
+    [schemaRegistry, registryCache, key]
+  );
+  const decodeForRead = useCallback(
+    (rawText) => {
+      if (rawText == null) return { value: getFallback() };
+      const parsed = parseEnvelope(rawText);
+      if (!parsed.ok) return { value: getFallback(parsed.error) };
+      const envelope = parsed.envelope;
+      const schemaForVersion = getSchemaForVersion(envelope.version);
+      const latestSchema = getLatestSchemaForKey();
+      if (schemaMode === "strict" && !schemaForVersion) {
+        return {
+          value: getFallback(
+            new SchemaError("SCHEMA_NOT_FOUND", `No schema for key "${key}" v${envelope.version}`)
+          )
+        };
+      }
+      if (schemaMode === "autoschema" && !schemaForVersion) {
+        if (latestSchema) {
+          return {
+            value: getFallback(
+              new SchemaError("SCHEMA_NOT_FOUND", `No schema for key "${key}" v${envelope.version}`)
+            )
+          };
+        }
+        if (!schemaRegistry || typeof schemaRegistry.registerSchema !== "function") {
+          return {
+            value: getFallback(
+              new SchemaError(
+                "MODE_CONFIGURATION_INVALID",
+                `Autoschema mode requires schema registry registration for key "${key}"`
+              )
+            )
+          };
+        }
+        try {
+          const decoded2 = typeof envelope.payload === "string" ? decodeStringPayload(envelope.payload, codec) : envelope.payload;
+          const inferredJsonSchema = inferJsonSchema(decoded2);
+          const inferred = {
+            key,
+            version: 1,
+            schema: inferredJsonSchema
+          };
+          const rewriteEnvelope = {
+            version: inferred.version,
+            payload: decoded2
+          };
+          return {
+            value: decoded2,
+            pendingSchema: inferred,
+            rewriteRaw: JSON.stringify(rewriteEnvelope)
+          };
+        } catch (err) {
+          const typedErr = err instanceof SchemaError || err instanceof CodecError ? err : new SchemaError("TYPE_MISMATCH", `Autoschema inference failed for key "${key}"`, err);
+          return { value: getFallback(typedErr) };
+        }
+      }
+      if (!schemaForVersion) {
+        if (typeof envelope.payload !== "string") {
+          return { value: envelope.payload };
+        }
+        try {
+          const decoded2 = decodeStringPayload(envelope.payload, codec);
+          return { value: decoded2 };
+        } catch (err) {
+          const typedErr = err instanceof SchemaError || err instanceof CodecError ? err : new CodecError(`Codec decode failed for key "${key}"`, err);
+          return { value: getFallback(typedErr) };
+        }
+      }
+      let current;
+      try {
+        current = envelope.payload;
+        validateAgainstSchema(current, schemaForVersion.schema);
+      } catch (err) {
+        const typedErr = err instanceof SchemaError || err instanceof CodecError ? err : new SchemaError("TYPE_MISMATCH", `Schema decode failed for key "${key}"`, err);
+        return { value: getFallback(typedErr) };
+      }
+      if (!latestSchema || envelope.version >= latestSchema.version) {
+        return { value: current };
+      }
+      const path = getMigrationPathForKey(envelope.version, latestSchema.version);
+      if (!path) {
+        return {
+          value: getFallback(
+            new SchemaError(
+              "MIGRATION_PATH_NOT_FOUND",
+              `No migration path for key "${key}" from v${envelope.version} to v${latestSchema.version}`
+            )
+          )
+        };
+      }
+      try {
+        let migrated = current;
+        for (const step of path) {
+          migrated = step.migrate(migrated);
+        }
+        validateAgainstSchema(migrated, latestSchema.schema);
+        const rewriteEnvelope = {
+          version: latestSchema.version,
+          payload: migrated
+        };
+        return {
+          value: migrated,
+          rewriteRaw: JSON.stringify(rewriteEnvelope)
+        };
+      } catch (err) {
+        const typedErr = err instanceof SchemaError || err instanceof CodecError ? err : new SchemaError("MIGRATION_FAILED", `Migration failed for key "${key}"`, err);
+        return { value: getFallback(typedErr) };
+      }
+    },
+    [
+      codec,
+      decodeStringPayload,
+      getFallback,
+      key,
+      parseEnvelope,
+      schemaMode,
+      schemaRegistry,
+      getSchemaForVersion,
+      getLatestSchemaForKey,
+      getMigrationPathForKey,
+      validateAgainstSchema
+    ]
+  );
+  const encodeForWrite = useCallback(
+    (nextValue) => {
+      const explicitVersion = schema?.version;
+      const latestSchema = getLatestSchemaForKey();
+      const explicitSchema = explicitVersion !== void 0 ? getSchemaForVersion(explicitVersion) : void 0;
+      let targetSchema = explicitSchema;
+      if (!targetSchema) {
+        if (explicitVersion !== void 0) {
+          if (schemaMode !== "strict") {
+            targetSchema = latestSchema;
+          }
+        } else {
+          targetSchema = latestSchema;
+        }
+      }
+      if (!targetSchema) {
+        if (explicitVersion !== void 0 && schemaMode === "strict") {
+          throw new SchemaError(
+            "WRITE_SCHEMA_REQUIRED",
+            `Write requires schema for key "${key}" in strict mode`
+          );
+        }
+        const envelope2 = {
+          version: 0,
+          payload: codec.encode(nextValue)
+        };
+        return JSON.stringify(envelope2);
+      }
+      let valueToStore = nextValue;
+      const writeMigration = schemaRegistry?.getWriteMigration?.(key, targetSchema.version);
+      if (writeMigration) {
+        try {
+          valueToStore = writeMigration.migrate(valueToStore);
+        } catch (err) {
+          throw err instanceof SchemaError ? err : new SchemaError("MIGRATION_FAILED", `Write-time migration failed for key "${key}"`, err);
+        }
+      }
+      validateAgainstSchema(valueToStore, targetSchema.schema);
+      const envelope = {
+        version: targetSchema.version,
+        payload: valueToStore
+      };
+      return JSON.stringify(envelope);
+    },
+    [
+      schema?.version,
+      key,
+      schemaMode,
+      codec,
+      schemaRegistry,
+      validateAgainstSchema,
+      getLatestSchemaForKey,
+      getSchemaForVersion
+    ]
+  );
+  const raw = useSyncExternalStore(
+    (listener) => api.subscribeRaw(key, listener),
+    () => api.getRawSnapshot(key),
+    () => null
+    // SSR snapshot - no storage in server environment
+  );
+  const decoded = useMemo(() => decodeForRead(raw), [decodeForRead, raw]);
+  const value = decoded.value;
+  useEffect(() => {
+    if (decoded.rewriteRaw && decoded.rewriteRaw !== raw) {
+      api.setRaw(key, decoded.rewriteRaw);
+    }
+  }, [api, decoded.rewriteRaw, key, raw]);
+  useEffect(() => {
+    if (!decoded.pendingSchema || !schemaRegistry?.registerSchema) return;
+    if (schemaRegistry.getSchema(decoded.pendingSchema.key, decoded.pendingSchema.version)) return;
+    try {
+      schemaRegistry.registerSchema(decoded.pendingSchema);
+    } catch {
+    }
+  }, [decoded.pendingSchema, schemaRegistry]);
+  const prevRef = useRef(value);
+  const mounted = useRef(false);
+  useEffect(() => {
+    if (mounted.current) return;
+    mounted.current = true;
+    onMount?.(value);
+    prevRef.current = value;
+  }, []);
+  useEffect(() => {
+    const prev = prevRef.current;
+    if (Object.is(prev, value)) return;
+    prevRef.current = value;
+    onChange?.(value, prev);
+  }, [value, onChange]);
+  useEffect(() => {
+    if (!listenCrossTab) return;
+    if (typeof window === "undefined") 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);
+    };
+    window.addEventListener("storage", handler);
+    return () => window.removeEventListener("storage", handler);
+  }, [listenCrossTab, api, key]);
+  const set = useMemo(() => {
+    return (next) => {
+      const nextVal = typeof next === "function" ? next(decodeForRead(api.getRawSnapshot(key)).value) : next;
+      try {
+        const encoded = encodeForWrite(nextVal);
+        api.setRaw(key, encoded);
+      } catch (err) {
+        if (err instanceof SchemaError) {
+          console.error(`[Mnemonic] Schema error for key "${key}" (${err.code}):`, err.message);
+          return;
+        }
+        if (err instanceof CodecError) {
+          console.error(`[Mnemonic] Codec encode error for key "${key}":`, err.message);
+          return;
+        }
+        console.error(`[Mnemonic] Failed to persist key "${key}":`, err);
+      }
+    };
+  }, [api, key, decodeForRead, encodeForWrite]);
+  const reset = useMemo(() => {
+    return () => {
+      const v = getFallback();
+      try {
+        const encoded = encodeForWrite(v);
+        api.setRaw(key, encoded);
+      } catch (err) {
+        if (err instanceof SchemaError) {
+          console.error(`[Mnemonic] Schema error for key "${key}" (${err.code}):`, err.message);
+          return;
+        }
+        if (err instanceof CodecError) {
+          console.error(`[Mnemonic] Codec encode error for key "${key}":`, err.message);
+        }
+        return;
+      }
+    };
+  }, [api, key, getFallback, encodeForWrite]);
+  const remove = useMemo(() => {
+    return () => api.removeRaw(key);
+  }, [api, key]);
+  return useMemo(
+    () => (
+      /** @see {@link UseMnemonicKeyOptions} for configuration details */
+      {
+        /** Current decoded value, or the default when the key is absent or invalid. */
+        value,
+        /** Persist a new value (direct or updater function). */
+        set,
+        /** Reset to `defaultValue` and persist it. */
+        reset,
+        /** Delete the key from storage entirely. */
+        remove
+      }
+    ),
+    [value, set, reset, remove]
+  );
+}
+
+export { CodecError, JSONCodec, MnemonicProvider, SchemaError, compileSchema, createCodec, useMnemonicKey, validateJsonSchema };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map