@multiplatform.one/store 6.7.0 → 7.1.0

package/dist/cjs/storage/index.native.js

@@ -24,46 +24,90 @@ var __toCommonJS = mod => __copyProps(__defProp({}, "__esModule", {
 }), mod);
 var index_native_exports = {};
 __export(index_native_exports, {
+  logNativeStorageResolution: () => logNativeStorageResolution,
+  resolveNativeStorage: () => resolveNativeStorage,
   storage: () => storage
 });
 module.exports = __toCommonJS(index_native_exports);
-function createStorage() {
+function _instanceof(left, right) {
+  "@swc/helpers - instanceof";
+
+  if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
+    return !!right[Symbol.hasInstance](left);
+  } else {
+    return left instanceof right;
+  }
+}
+var defaultLoaders = {
+  // Literal require(...) calls on purpose: metro resolves them natively and
+  // vxrn/rolldown rewrites literal requires into bundled module inits (a
+  // passed-around `require` reference would survive as a bare identifier and
+  // crash). Lazy so a genuinely missing native module throws HERE — inside
+  // the try/catch — instead of at bundle evaluation.
+  loadMMKV: function loadMMKV() {
+    return require("react-native-mmkv");
+  },
+  loadAsyncStorage: function loadAsyncStorage() {
+    return require("@react-native-async-storage/async-storage");
+  }
+};
+function resolveNativeStorage() {
+  var loaders = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : defaultLoaders;
+  var errors = {};
   try {
-    var {
-      MMKV
-    } = require("react-native-mmkv");
-    var mmkv = new MMKV();
+    var mmkvModule = loaders.loadMMKV();
+    if (typeof (mmkvModule === null || mmkvModule === void 0 ? void 0 : mmkvModule.createMMKV) !== "function") {
+      throw new Error("no createMMKV() export (react-native-mmkv v4 API expected)");
+    }
+    var mmkv = mmkvModule.createMMKV();
     return {
-      getItem: function getItem(name) {
-        var _mmkv_getString;
-        return (_mmkv_getString = mmkv.getString(name)) !== null && _mmkv_getString !== void 0 ? _mmkv_getString : null;
-      },
-      setItem: function setItem(name, value) {
-        return mmkv.set(name, value);
-      },
-      removeItem: function removeItem(name) {
-        return mmkv.delete(name);
+      backend: "mmkv",
+      errors,
+      storage: {
+        getItem: function getItem(name) {
+          var _mmkv_getString;
+          return (_mmkv_getString = mmkv.getString(name)) !== null && _mmkv_getString !== void 0 ? _mmkv_getString : null;
+        },
+        setItem: function setItem(name, value) {
+          mmkv.set(name, value);
+        },
+        removeItem: function removeItem(name) {
+          mmkv.remove(name);
+        }
       }
     };
-  } catch (unused) {
-    try {
-      var AsyncStorage = require("@react-native-async-storage/async-storage").default;
-      if (AsyncStorage && typeof AsyncStorage.getItem === "function") {
-        return {
-          getItem: function getItem(name) {
-            return AsyncStorage.getItem(name);
-          },
-          setItem: function setItem(name, value) {
-            return AsyncStorage.setItem(name, value);
-          },
-          removeItem: function removeItem(name) {
-            return AsyncStorage.removeItem(name);
-          }
-        };
-      }
-    } catch (unused2) {}
-    var map = /* @__PURE__ */new Map();
+  } catch (err) {
+    errors.mmkv = err;
+  }
+  try {
+    var asyncStorageModule = loaders.loadAsyncStorage();
+    var asyncStorage = asyncStorageModule === null || asyncStorageModule === void 0 ? void 0 : asyncStorageModule.default;
+    if (!asyncStorage || typeof asyncStorage.getItem !== "function") {
+      throw new Error("no usable default export on @react-native-async-storage/async-storage");
+    }
     return {
+      backend: "async-storage",
+      errors,
+      storage: {
+        getItem: function getItem(name) {
+          return asyncStorage.getItem(name);
+        },
+        setItem: function setItem(name, value) {
+          return asyncStorage.setItem(name, value);
+        },
+        removeItem: function removeItem(name) {
+          return asyncStorage.removeItem(name);
+        }
+      }
+    };
+  } catch (err) {
+    errors.asyncStorage = err;
+  }
+  var map = /* @__PURE__ */new Map();
+  return {
+    backend: "memory",
+    errors,
+    storage: {
       getItem: function getItem(name) {
         var _map_get;
         return (_map_get = map.get(name)) !== null && _map_get !== void 0 ? _map_get : null;
@@ -74,8 +118,27 @@ function createStorage() {
       removeItem: function removeItem(name) {
         map.delete(name);
       }
-    };
+    }
+  };
+}
+function describeError(err) {
+  return _instanceof(err, Error) ? err.message : String(err);
+}
+function logNativeStorageResolution(resolution2) {
+  var logger = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : console;
+  if (resolution2.backend === "mmkv") {
+    logger.info("[@multiplatform.one/store] native storage backend: mmkv");
+    return;
   }
+  var causes = [`react-native-mmkv unavailable: ${describeError(resolution2.errors.mmkv)}`];
+  if (resolution2.backend === "memory") {
+    causes.push(`async-storage unavailable: ${describeError(resolution2.errors.asyncStorage)}`);
+  }
+  logger.warn(`[@multiplatform.one/store] native storage fell back to ${resolution2.backend}` + (resolution2.backend === "memory" ? " \u2014 persisted state will NOT survive app restarts" : "") + ` (${causes.join("; ")})`);
+}
+var resolution = resolveNativeStorage();
+if (process.env.NODE_ENV !== "production" && process.env.NODE_ENV !== "test") {
+  logNativeStorageResolution(resolution);
 }
-var storage = createStorage();
+var storage = resolution.storage;
 //# sourceMappingURL=index.native.js.map

package/dist/cjs/storage/index.native.js.map

@@ -1 +1 @@
-{"version":3,"names":["index_native_exports","__export","storage","module","exports","__toCommonJS","createStorage","MMKV","require","mmkv","getItem","name","_mmkv_getString","getString","setItem","value","set","removeItem","delete","unused","AsyncStorage","default","unused2","map","Map","_map_get","get"],"sources":["../../../src/storage/index.native.ts"],"sourcesContent":[null],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAAA,IAAAA,oBAAA;AAAAC,QAAA,CAAAD,oBAAA;EAAAE,OAAA,EAAAA,CAAA,KAAAA;AAAA;AAAAC,MAAA,CAAAC,OAAA,GAAAC,YAAA,CAAAL,oBAAA;AAAA,SAASM,cAAA,EAAgB;EACrB,IAAI;IACA,IAAI;MAAEC;IAAK,IAAIC,OAAA,CAAQ,mBAAmB;IAC1C,IAAIC,IAAA,GAAO,IAAIF,IAAA,CAAK;IACpB,OAAO;MACHG,OAAA,EAAS,SAASA,QAAQC,IAAA,EAAM;QAC5B,IAAIC,eAAA;QACJ,QAAQA,eAAA,GAAkBH,IAAA,CAAKI,SAAA,CAAUF,IAAI,OAAO,QAAQC,eAAA,KAAoB,SAASA,eAAA,GAAkB;MAC/G;MACAE,OAAA,EAAS,SAASA,QAAQH,IAAA,EAAMI,KAAA,EAAO;QACnC,OAAON,IAAA,CAAKO,GAAA,CAAIL,IAAA,EAAMI,KAAK;MAC/B;MACAE,UAAA,EAAY,SAASA,WAAWN,IAAA,EAAM;QAClC,OAAOF,IAAA,CAAKS,MAAA,CAAOP,IAAI;MAC3B;IACJ;EACJ,SAASQ,MAAA,EAAQ;IACb,IAAI;MAEA,IAAIC,YAAA,GAAeZ,OAAA,CAAQ,2CAA2C,EAAEa,OAAA;MAExE,IAAID,YAAA,IAAgB,OAAOA,YAAA,CAAaV,OAAA,KAAY,YAAY;QAC5D,OAAO;UACHA,OAAA,EAAS,SAASA,QAAQC,IAAA,EAAM;YAC5B,OAAOS,YAAA,CAAaV,OAAA,CAAQC,IAAI;UACpC;UACAG,OAAA,EAAS,SAASA,QAAQH,IAAA,EAAMI,KAAA,EAAO;YACnC,OAAOK,YAAA,CAAaN,OAAA,CAAQH,IAAA,EAAMI,KAAK;UAC3C;UACAE,UAAA,EAAY,SAASA,WAAWN,IAAA,EAAM;YAClC,OAAOS,YAAA,CAAaH,UAAA,CAAWN,IAAI;UACvC;QACJ;MACJ;IACJ,SAASW,OAAA,EAAQ,CAAC;IAElB,IAAIC,GAAA,GAAM,mBAAIC,GAAA,CAAI;IAClB,OAAO;MACHd,OAAA,EAAS,SAASA,QAAQC,IAAA,EAAM;QAC5B,IAAIc,QAAA;QACJ,QAAQA,QAAA,GAAWF,GAAA,CAAIG,GAAA,CAAIf,IAAI,OAAO,QAAQc,QAAA,KAAa,SAASA,QAAA,GAAW;MACnF;MACAX,OAAA,EAAS,SAASA,QAAQH,IAAA,EAAMI,KAAA,EAAO;QACnCQ,GAAA,CAAIP,GAAA,CAAIL,IAAA,EAAMI,KAAK;MACvB;MACAE,UAAA,EAAY,SAASA,WAAWN,IAAA,EAAM;QAClCY,GAAA,CAAIL,MAAA,CAAOP,IAAI;MACnB;IACJ;EACJ;AACJ;AACO,IAAIT,OAAA,GAAUI,aAAA,CAAc","ignoreList":[]}
+{"version":3,"names":["index_native_exports","__export","logNativeStorageResolution","resolveNativeStorage","storage","module","exports","__toCommonJS","_instanceof","left","right","Symbol","hasInstance","defaultLoaders","loadMMKV","require","loadAsyncStorage","loaders","arguments","length","errors","mmkvModule","createMMKV","Error","mmkv","backend","getItem","name","_mmkv_getString","getString","setItem","value","set","removeItem","remove","err","asyncStorageModule","asyncStorage","default","map","Map","_map_get","get","delete","describeError","message","String","resolution2","logger","console","info","causes","push","warn","join","resolution","process","env","NODE_ENV"],"sources":["../../../src/storage/index.native.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/esm/storage/index.native.js

@@ -1,40 +1,82 @@
-function createStorage() {
+function _instanceof(left, right) {
+  "@swc/helpers - instanceof";
+
+  if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
+    return !!right[Symbol.hasInstance](left);
+  } else {
+    return left instanceof right;
+  }
+}
+var defaultLoaders = {
+  // Literal require(...) calls on purpose: metro resolves them natively and
+  // vxrn/rolldown rewrites literal requires into bundled module inits (a
+  // passed-around `require` reference would survive as a bare identifier and
+  // crash). Lazy so a genuinely missing native module throws HERE — inside
+  // the try/catch — instead of at bundle evaluation.
+  loadMMKV: function loadMMKV() {
+    return require("react-native-mmkv");
+  },
+  loadAsyncStorage: function loadAsyncStorage() {
+    return require("@react-native-async-storage/async-storage");
+  }
+};
+function resolveNativeStorage() {
+  var loaders = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : defaultLoaders;
+  var errors = {};
   try {
-    var {
-      MMKV
-    } = require("react-native-mmkv");
-    var mmkv = new MMKV();
+    var mmkvModule = loaders.loadMMKV();
+    if (typeof (mmkvModule === null || mmkvModule === void 0 ? void 0 : mmkvModule.createMMKV) !== "function") {
+      throw new Error("no createMMKV() export (react-native-mmkv v4 API expected)");
+    }
+    var mmkv = mmkvModule.createMMKV();
     return {
-      getItem: function getItem(name) {
-        var _mmkv_getString;
-        return (_mmkv_getString = mmkv.getString(name)) !== null && _mmkv_getString !== void 0 ? _mmkv_getString : null;
-      },
-      setItem: function setItem(name, value) {
-        return mmkv.set(name, value);
-      },
-      removeItem: function removeItem(name) {
-        return mmkv.delete(name);
+      backend: "mmkv",
+      errors,
+      storage: {
+        getItem: function getItem(name) {
+          var _mmkv_getString;
+          return (_mmkv_getString = mmkv.getString(name)) !== null && _mmkv_getString !== void 0 ? _mmkv_getString : null;
+        },
+        setItem: function setItem(name, value) {
+          mmkv.set(name, value);
+        },
+        removeItem: function removeItem(name) {
+          mmkv.remove(name);
+        }
       }
     };
-  } catch (unused) {
-    try {
-      var AsyncStorage = require("@react-native-async-storage/async-storage").default;
-      if (AsyncStorage && typeof AsyncStorage.getItem === "function") {
-        return {
-          getItem: function getItem(name) {
-            return AsyncStorage.getItem(name);
-          },
-          setItem: function setItem(name, value) {
-            return AsyncStorage.setItem(name, value);
-          },
-          removeItem: function removeItem(name) {
-            return AsyncStorage.removeItem(name);
-          }
-        };
-      }
-    } catch (unused2) {}
-    var map = /* @__PURE__ */new Map();
+  } catch (err) {
+    errors.mmkv = err;
+  }
+  try {
+    var asyncStorageModule = loaders.loadAsyncStorage();
+    var asyncStorage = asyncStorageModule === null || asyncStorageModule === void 0 ? void 0 : asyncStorageModule.default;
+    if (!asyncStorage || typeof asyncStorage.getItem !== "function") {
+      throw new Error("no usable default export on @react-native-async-storage/async-storage");
+    }
     return {
+      backend: "async-storage",
+      errors,
+      storage: {
+        getItem: function getItem(name) {
+          return asyncStorage.getItem(name);
+        },
+        setItem: function setItem(name, value) {
+          return asyncStorage.setItem(name, value);
+        },
+        removeItem: function removeItem(name) {
+          return asyncStorage.removeItem(name);
+        }
+      }
+    };
+  } catch (err) {
+    errors.asyncStorage = err;
+  }
+  var map = /* @__PURE__ */new Map();
+  return {
+    backend: "memory",
+    errors,
+    storage: {
       getItem: function getItem(name) {
         var _map_get;
         return (_map_get = map.get(name)) !== null && _map_get !== void 0 ? _map_get : null;
@@ -45,9 +87,28 @@ function createStorage() {
       removeItem: function removeItem(name) {
         map.delete(name);
       }
-    };
+    }
+  };
+}
+function describeError(err) {
+  return _instanceof(err, Error) ? err.message : String(err);
+}
+function logNativeStorageResolution(resolution2) {
+  var logger = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : console;
+  if (resolution2.backend === "mmkv") {
+    logger.info("[@multiplatform.one/store] native storage backend: mmkv");
+    return;
   }
+  var causes = [`react-native-mmkv unavailable: ${describeError(resolution2.errors.mmkv)}`];
+  if (resolution2.backend === "memory") {
+    causes.push(`async-storage unavailable: ${describeError(resolution2.errors.asyncStorage)}`);
+  }
+  logger.warn(`[@multiplatform.one/store] native storage fell back to ${resolution2.backend}` + (resolution2.backend === "memory" ? " \u2014 persisted state will NOT survive app restarts" : "") + ` (${causes.join("; ")})`);
+}
+var resolution = resolveNativeStorage();
+if (process.env.NODE_ENV !== "production" && process.env.NODE_ENV !== "test") {
+  logNativeStorageResolution(resolution);
 }
-var storage = createStorage();
-export { storage };
+var storage = resolution.storage;
+export { logNativeStorageResolution, resolveNativeStorage, storage };
 //# sourceMappingURL=index.native.js.map

package/dist/esm/storage/index.native.js.map

@@ -1 +1 @@
-{"version":3,"names":["createStorage","MMKV","require","mmkv","getItem","name","_mmkv_getString","getString","setItem","value","set","removeItem","delete","unused","AsyncStorage","default","unused2","map","Map","_map_get","get","storage"],"sources":["../../../src/storage/index.native.ts"],"sourcesContent":[null],"mappings":"AAAA,SAASA,cAAA,EAAgB;EACrB,IAAI;IACA,IAAI;MAAEC;IAAK,IAAIC,OAAA,CAAQ,mBAAmB;IAC1C,IAAIC,IAAA,GAAO,IAAIF,IAAA,CAAK;IACpB,OAAO;MACHG,OAAA,EAAS,SAASA,QAAQC,IAAA,EAAM;QAC5B,IAAIC,eAAA;QACJ,QAAQA,eAAA,GAAkBH,IAAA,CAAKI,SAAA,CAAUF,IAAI,OAAO,QAAQC,eAAA,KAAoB,SAASA,eAAA,GAAkB;MAC/G;MACAE,OAAA,EAAS,SAASA,QAAQH,IAAA,EAAMI,KAAA,EAAO;QACnC,OAAON,IAAA,CAAKO,GAAA,CAAIL,IAAA,EAAMI,KAAK;MAC/B;MACAE,UAAA,EAAY,SAASA,WAAWN,IAAA,EAAM;QAClC,OAAOF,IAAA,CAAKS,MAAA,CAAOP,IAAI;MAC3B;IACJ;EACJ,SAASQ,MAAA,EAAQ;IACb,IAAI;MAEA,IAAIC,YAAA,GAAeZ,OAAA,CAAQ,2CAA2C,EAAEa,OAAA;MAExE,IAAID,YAAA,IAAgB,OAAOA,YAAA,CAAaV,OAAA,KAAY,YAAY;QAC5D,OAAO;UACHA,OAAA,EAAS,SAASA,QAAQC,IAAA,EAAM;YAC5B,OAAOS,YAAA,CAAaV,OAAA,CAAQC,IAAI;UACpC;UACAG,OAAA,EAAS,SAASA,QAAQH,IAAA,EAAMI,KAAA,EAAO;YACnC,OAAOK,YAAA,CAAaN,OAAA,CAAQH,IAAA,EAAMI,KAAK;UAC3C;UACAE,UAAA,EAAY,SAASA,WAAWN,IAAA,EAAM;YAClC,OAAOS,YAAA,CAAaH,UAAA,CAAWN,IAAI;UACvC;QACJ;MACJ;IACJ,SAASW,OAAA,EAAQ,CAAC;IAElB,IAAIC,GAAA,GAAM,mBAAIC,GAAA,CAAI;IAClB,OAAO;MACHd,OAAA,EAAS,SAASA,QAAQC,IAAA,EAAM;QAC5B,IAAIc,QAAA;QACJ,QAAQA,QAAA,GAAWF,GAAA,CAAIG,GAAA,CAAIf,IAAI,OAAO,QAAQc,QAAA,KAAa,SAASA,QAAA,GAAW;MACnF;MACAX,OAAA,EAAS,SAASA,QAAQH,IAAA,EAAMI,KAAA,EAAO;QACnCQ,GAAA,CAAIP,GAAA,CAAIL,IAAA,EAAMI,KAAK;MACvB;MACAE,UAAA,EAAY,SAASA,WAAWN,IAAA,EAAM;QAClCY,GAAA,CAAIL,MAAA,CAAOP,IAAI;MACnB;IACJ;EACJ;AACJ;AACO,IAAIgB,OAAA,GAAUrB,aAAA,CAAc","ignoreList":[]}
+{"version":3,"names":["_instanceof","left","right","Symbol","hasInstance","defaultLoaders","loadMMKV","require","loadAsyncStorage","resolveNativeStorage","loaders","arguments","length","errors","mmkvModule","createMMKV","Error","mmkv","backend","storage","getItem","name","_mmkv_getString","getString","setItem","value","set","removeItem","remove","err","asyncStorageModule","asyncStorage","default","map","Map","_map_get","get","delete","describeError","message","String","logNativeStorageResolution","resolution2","logger","console","info","causes","push","warn","join","resolution","process","env","NODE_ENV"],"sources":["../../../src/storage/index.native.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/store",
-  "version": "6.7.0",
+  "version": "7.1.0",
   "description": "multiplatform.one TanStack Store with cross-platform persistent storage",
   "keywords": [
     "react",
@@ -57,7 +57,7 @@
     "react-native-mmkv": "^4.3.1"
   },
   "devDependencies": {
-    "@tamagui/build": "2.0.0-rc.41",
+    "@tamagui/build": "2.7.6",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@vitejs/plugin-react": "^6.0.1",
@@ -67,18 +67,18 @@
     "typescript": "~5.9.3",
     "vite": "^8.0.10",
     "vitest": "^4.1.5",
-    "@multiplatform.one/test-utils": "6.7.0",
-    "@multiplatform.one/config": "6.7.0"
+    "@multiplatform.one/config": "7.1.0",
+    "@multiplatform.one/test-utils": "7.1.0"
   },
   "peerDependencies": {
     "react": "^19.1.0"
   },
-  "optionalDependencies": {
-    "@tauri-apps/plugin-store": "^2.4.2"
-  },
   "engines": {
     "node": ">=18.0.0"
   },
+  "optionalDependencies": {
+    "@tauri-apps/plugin-store": "^2.4.2"
+  },
   "scripts": {
     "build": "rm -rf dist types 2>/dev/null && tamagui-build --ts-project ./tsconfig.build.json --exclude '\\.spec\\.|\\.test\\.|\\.stories\\.'",
     "pretest": "node -e \"const p=require('path').resolve(__dirname,'../../node_modules/@testing-library/react/node_modules');['react','react-dom','scheduler'].forEach(d=>{try{require('fs').rmSync(p+'/'+d,{recursive:true,force:true})}catch{}})\"",

package/src/storage/index.native.ts

@@ -1,30 +1,117 @@
+/**
+ * Native storage twin — backend priority: MMKV (react-native-mmkv v4,
+ * synchronous JSI/Nitro) → AsyncStorage (environments without Nitro, e.g.
+ * Expo Go) → in-memory Map (nothing survives a restart).
+ *
+ * react-native-mmkv v4 exports `MMKV` as a TYPE only — the runtime API is
+ * the `createMMKV()` factory. The previous implementation destructured the
+ * non-existent `MMKV` class (v3 API) and threw `undefined is not a
+ * constructor` on every launch, silently landing all native persistence on
+ * the in-memory fallback (favorites lost on restart — 2026-08-13 iOS smoke
+ * test, p-results/native-smoke/REPORT.md #2). Resolution is therefore
+ * factored into a pure, loader-injectable function (spec-covered) and the
+ * chosen backend is logged once in dev — a degraded backend can never be
+ * silent again.
+ */
+
 import type { Storage } from "../persist";
 
-function createStorage(): Storage {
+export type NativeStorageBackend = "mmkv" | "async-storage" | "memory";
+
+/** Runtime subset of react-native-mmkv v4's MMKV HybridObject. */
+interface MMKVLike {
+  getString(key: string): string | undefined;
+  set(key: string, value: string): void;
+  remove(key: string): boolean;
+}
+
+interface AsyncStorageLike {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem(key: string): Promise<void>;
+}
+
+/** Module loaders, injectable so specs can drive every resolution branch. */
+export interface NativeStorageLoaders {
+  /** Load react-native-mmkv (throws when unavailable). */
+  loadMMKV(): unknown;
+  /** Load @react-native-async-storage/async-storage (throws when unavailable). */
+  loadAsyncStorage(): unknown;
+}
+
+export interface NativeStorageResolution {
+  storage: Storage;
+  backend: NativeStorageBackend;
+  /** Why higher-priority backends were skipped (surfaced by the dev log). */
+  errors: { mmkv?: unknown; asyncStorage?: unknown };
+}
+
+const defaultLoaders: NativeStorageLoaders = {
+  // Literal require(...) calls on purpose: metro resolves them natively and
+  // vxrn/rolldown rewrites literal requires into bundled module inits (a
+  // passed-around `require` reference would survive as a bare identifier and
+  // crash). Lazy so a genuinely missing native module throws HERE — inside
+  // the try/catch — instead of at bundle evaluation.
+  loadMMKV: () => require("react-native-mmkv"),
+  loadAsyncStorage: () => require("@react-native-async-storage/async-storage"),
+};
+
+export function resolveNativeStorage(
+  loaders: NativeStorageLoaders = defaultLoaders,
+): NativeStorageResolution {
+  const errors: NativeStorageResolution["errors"] = {};
+
   try {
-    const { MMKV } = require("react-native-mmkv");
-    const mmkv = new MMKV();
+    const mmkvModule = loaders.loadMMKV() as {
+      createMMKV?: (configuration?: unknown) => MMKVLike;
+    };
+    if (typeof mmkvModule?.createMMKV !== "function") {
+      // v3 shipped an `MMKV` class; v4 only ships the factory. Anything
+      // without createMMKV() is not a usable react-native-mmkv module.
+      throw new Error("no createMMKV() export (react-native-mmkv v4 API expected)");
+    }
+    const mmkv = mmkvModule.createMMKV();
     return {
-      getItem: (name: string) => mmkv.getString(name) ?? null,
-      setItem: (name: string, value: string) => mmkv.set(name, value),
-      removeItem: (name: string) => mmkv.delete(name),
+      backend: "mmkv",
+      errors,
+      storage: {
+        getItem: (name: string) => mmkv.getString(name) ?? null,
+        setItem: (name: string, value: string) => {
+          mmkv.set(name, value);
+        },
+        removeItem: (name: string) => {
+          mmkv.remove(name);
+        },
+      },
     };
-  } catch {
-    try {
-      // Fallback to AsyncStorage for Expo Go or environments without TurboModules
-      const AsyncStorage = require("@react-native-async-storage/async-storage").default;
-      // Verify the native module is available before returning
-      if (AsyncStorage && typeof AsyncStorage.getItem === "function") {
-        return {
-          getItem: (name: string) => AsyncStorage.getItem(name),
-          setItem: (name: string, value: string) => AsyncStorage.setItem(name, value),
-          removeItem: (name: string) => AsyncStorage.removeItem(name),
-        };
-      }
-    } catch {}
-    // Final fallback: in-memory storage
-    const map = new Map<string, string>();
+  } catch (err) {
+    errors.mmkv = err;
+  }
+
+  try {
+    const asyncStorageModule = loaders.loadAsyncStorage() as { default?: AsyncStorageLike };
+    const asyncStorage = asyncStorageModule?.default;
+    if (!asyncStorage || typeof asyncStorage.getItem !== "function") {
+      throw new Error("no usable default export on @react-native-async-storage/async-storage");
+    }
     return {
+      backend: "async-storage",
+      errors,
+      storage: {
+        getItem: (name: string) => asyncStorage.getItem(name),
+        setItem: (name: string, value: string) => asyncStorage.setItem(name, value),
+        removeItem: (name: string) => asyncStorage.removeItem(name),
+      },
+    };
+  } catch (err) {
+    errors.asyncStorage = err;
+  }
+
+  const map = new Map<string, string>();
+  return {
+    backend: "memory",
+    errors,
+    storage: {
       getItem: (name: string) => map.get(name) ?? null,
       setItem: (name: string, value: string) => {
         map.set(name, value);
@@ -32,8 +119,42 @@ function createStorage(): Storage {
       removeItem: (name: string) => {
         map.delete(name);
       },
-    };
+    },
+  };
+}
+
+function describeError(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * One dev-mode line naming the winning backend — a console.warn when
+ * persistence degraded, so a broken storage twin is loud instead of silent.
+ */
+export function logNativeStorageResolution(
+  resolution: NativeStorageResolution,
+  logger: Pick<Console, "info" | "warn"> = console,
+): void {
+  if (resolution.backend === "mmkv") {
+    logger.info("[@multiplatform.one/store] native storage backend: mmkv");
+    return;
   }
+  const causes = [`react-native-mmkv unavailable: ${describeError(resolution.errors.mmkv)}`];
+  if (resolution.backend === "memory") {
+    causes.push(`async-storage unavailable: ${describeError(resolution.errors.asyncStorage)}`);
+  }
+  logger.warn(
+    `[@multiplatform.one/store] native storage fell back to ${resolution.backend}` +
+      (resolution.backend === "memory" ? " — persisted state will NOT survive app restarts" : "") +
+      ` (${causes.join("; ")})`,
+  );
+}
+
+const resolution = resolveNativeStorage();
+// NODE_ENV !== "test" keeps vitest imports of this module quiet; specs cover
+// the log contract by calling logNativeStorageResolution directly.
+if (process.env.NODE_ENV !== "production" && process.env.NODE_ENV !== "test") {
+  logNativeStorageResolution(resolution);
 }
 
-export const storage: Storage = createStorage();
+export const storage: Storage = resolution.storage;

package/src/storage/nativeStorage.spec.ts

@@ -0,0 +1,206 @@
+/**
+ * Native storage resolution specs — lock down the backend-priority contract
+ * (mmkv → async-storage → memory), the react-native-mmkv v4 API usage
+ * (`createMMKV()` factory; `MMKV` is a type-only export in v4, and
+ * destructuring it was the silent-in-memory persistence bug on iOS), and
+ * the loud dev-mode fallback log.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import type { Storage } from "../persist";
+import { logNativeStorageResolution, resolveNativeStorage } from "./index.native";
+
+function createMMKVv4Module() {
+  const data = new Map<string, string>();
+  const instance = {
+    getString: (key: string) => data.get(key),
+    set: (key: string, value: string) => {
+      data.set(key, value);
+    },
+    remove: (key: string) => data.delete(key),
+  };
+  const createMMKV = vi.fn(() => instance);
+  return { module: { createMMKV }, createMMKV, data };
+}
+
+function createAsyncStorageModule() {
+  const data = new Map<string, string>();
+  return {
+    module: {
+      default: {
+        getItem: async (key: string) => data.get(key) ?? null,
+        setItem: async (key: string, value: string) => {
+          data.set(key, value);
+        },
+        removeItem: async (key: string) => {
+          data.delete(key);
+        },
+      },
+    },
+    data,
+  };
+}
+
+const throwing = (name: string) => () => {
+  throw new Error(`${name} unavailable`);
+};
+
+async function roundTrip(storage: Storage): Promise<{
+  afterSet: string | null;
+  afterRemove: string | null;
+  missing: string | null;
+}> {
+  await storage.setItem("k", "v");
+  const afterSet = await storage.getItem("k");
+  await storage.removeItem("k");
+  const afterRemove = await storage.getItem("k");
+  const missing = await storage.getItem("never-written");
+  return { afterSet, afterRemove, missing };
+}
+
+describe("resolveNativeStorage", () => {
+  it("picks MMKV via the v4 createMMKV() factory and round-trips values", async () => {
+    const mmkv = createMMKVv4Module();
+    const resolution = resolveNativeStorage({
+      loadMMKV: () => mmkv.module,
+      loadAsyncStorage: throwing("async-storage"),
+    });
+
+    expect(resolution.backend).toBe("mmkv");
+    expect(mmkv.createMMKV).toHaveBeenCalledTimes(1);
+    expect(resolution.errors.mmkv).toBeUndefined();
+    await expect(roundTrip(resolution.storage)).resolves.toEqual({
+      afterSet: "v",
+      afterRemove: null,
+      missing: null,
+    });
+    expect(mmkv.data.size).toBe(0);
+  });
+
+  it("regression: a v3-shaped module (MMKV class, no createMMKV) is not treated as usable", () => {
+    // react-native-mmkv v4 exports `MMKV` as a type only; the old
+    // `new MMKV()` code threw at runtime and silently fell to memory.
+    class FakeV3MMKV {}
+    const asyncStorage = createAsyncStorageModule();
+    const resolution = resolveNativeStorage({
+      loadMMKV: () => ({ MMKV: FakeV3MMKV }),
+      loadAsyncStorage: () => asyncStorage.module,
+    });
+
+    expect(resolution.backend).toBe("async-storage");
+    expect(String(resolution.errors.mmkv)).toContain("createMMKV");
+  });
+
+  it("falls back to AsyncStorage when the MMKV module fails to load", async () => {
+    const asyncStorage = createAsyncStorageModule();
+    const resolution = resolveNativeStorage({
+      loadMMKV: throwing("react-native-mmkv"),
+      loadAsyncStorage: () => asyncStorage.module,
+    });
+
+    expect(resolution.backend).toBe("async-storage");
+    expect(String(resolution.errors.mmkv)).toContain("react-native-mmkv unavailable");
+    await expect(roundTrip(resolution.storage)).resolves.toEqual({
+      afterSet: "v",
+      afterRemove: null,
+      missing: null,
+    });
+  });
+
+  it("falls back to memory when AsyncStorage has no usable default export", async () => {
+    const resolution = resolveNativeStorage({
+      loadMMKV: throwing("react-native-mmkv"),
+      loadAsyncStorage: () => ({ default: undefined }),
+    });
+
+    expect(resolution.backend).toBe("memory");
+    expect(resolution.errors.asyncStorage).toBeDefined();
+    // Memory storage still honors the Storage contract.
+    await expect(roundTrip(resolution.storage)).resolves.toEqual({
+      afterSet: "v",
+      afterRemove: null,
+      missing: null,
+    });
+  });
+
+  it("records both loader errors when everything fails", () => {
+    const resolution = resolveNativeStorage({
+      loadMMKV: throwing("react-native-mmkv"),
+      loadAsyncStorage: throwing("async-storage"),
+    });
+
+    expect(resolution.backend).toBe("memory");
+    expect(String(resolution.errors.mmkv)).toContain("react-native-mmkv unavailable");
+    expect(String(resolution.errors.asyncStorage)).toContain("async-storage unavailable");
+  });
+});
+
+describe("logNativeStorageResolution", () => {
+  it("logs a single info line when MMKV won", () => {
+    const info = vi.fn();
+    const warn = vi.fn();
+    const mmkv = createMMKVv4Module();
+    const resolution = resolveNativeStorage({
+      loadMMKV: () => mmkv.module,
+      loadAsyncStorage: throwing("async-storage"),
+    });
+
+    logNativeStorageResolution(resolution, { info, warn });
+
+    expect(info).toHaveBeenCalledTimes(1);
+    expect(info.mock.calls[0]?.[0]).toContain("backend: mmkv");
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it("warns loudly (once) when persistence degraded to async-storage", () => {
+    const info = vi.fn();
+    const warn = vi.fn();
+    const asyncStorage = createAsyncStorageModule();
+    const resolution = resolveNativeStorage({
+      loadMMKV: throwing("react-native-mmkv"),
+      loadAsyncStorage: () => asyncStorage.module,
+    });
+
+    logNativeStorageResolution(resolution, { info, warn });
+
+    expect(warn).toHaveBeenCalledTimes(1);
+    const message = String(warn.mock.calls[0]?.[0]);
+    expect(message).toContain("fell back to async-storage");
+    expect(message).toContain("react-native-mmkv unavailable");
+    expect(info).not.toHaveBeenCalled();
+  });
+
+  it("warns that state will not survive restarts when memory won", () => {
+    const info = vi.fn();
+    const warn = vi.fn();
+    const resolution = resolveNativeStorage({
+      loadMMKV: throwing("react-native-mmkv"),
+      loadAsyncStorage: throwing("async-storage"),
+    });
+
+    logNativeStorageResolution(resolution, { info, warn });
+
+    expect(warn).toHaveBeenCalledTimes(1);
+    const message = String(warn.mock.calls[0]?.[0]);
+    expect(message).toContain("fell back to memory");
+    expect(message).toContain("NOT survive app restarts");
+    expect(message).toContain("react-native-mmkv unavailable");
+    expect(message).toContain("async-storage unavailable");
+  });
+});
+
+describe("module-level storage export", () => {
+  it("resolves without crashing outside React Native", async () => {
+    // Outside metro/vxrn the default loader chain must settle on SOME backend
+    // instead of throwing at import time (in this vitest environment it lands
+    // on AsyncStorage's web build over the test setup's no-op localStorage
+    // stub, so a round-trip cannot be asserted here — the injected-loader
+    // specs above cover the round-trip contract per backend).
+    const { storage } = await import("./index.native");
+    expect(typeof storage.getItem).toBe("function");
+    expect(typeof storage.setItem).toBe("function");
+    expect(typeof storage.removeItem).toBe("function");
+    await expect(Promise.resolve(storage.setItem("spec-key", "spec-value"))).resolves.not.toThrow();
+    await expect(Promise.resolve(storage.removeItem("spec-key"))).resolves.not.toThrow();
+  });
+});

package/types/storage/index.native.d.ts

@@ -1,3 +1,41 @@
+/**
+ * Native storage twin — backend priority: MMKV (react-native-mmkv v4,
+ * synchronous JSI/Nitro) → AsyncStorage (environments without Nitro, e.g.
+ * Expo Go) → in-memory Map (nothing survives a restart).
+ *
+ * react-native-mmkv v4 exports `MMKV` as a TYPE only — the runtime API is
+ * the `createMMKV()` factory. The previous implementation destructured the
+ * non-existent `MMKV` class (v3 API) and threw `undefined is not a
+ * constructor` on every launch, silently landing all native persistence on
+ * the in-memory fallback (favorites lost on restart — 2026-08-13 iOS smoke
+ * test, p-results/native-smoke/REPORT.md #2). Resolution is therefore
+ * factored into a pure, loader-injectable function (spec-covered) and the
+ * chosen backend is logged once in dev — a degraded backend can never be
+ * silent again.
+ */
 import type { Storage } from "../persist";
+export type NativeStorageBackend = "mmkv" | "async-storage" | "memory";
+/** Module loaders, injectable so specs can drive every resolution branch. */
+export interface NativeStorageLoaders {
+    /** Load react-native-mmkv (throws when unavailable). */
+    loadMMKV(): unknown;
+    /** Load @react-native-async-storage/async-storage (throws when unavailable). */
+    loadAsyncStorage(): unknown;
+}
+export interface NativeStorageResolution {
+    storage: Storage;
+    backend: NativeStorageBackend;
+    /** Why higher-priority backends were skipped (surfaced by the dev log). */
+    errors: {
+        mmkv?: unknown;
+        asyncStorage?: unknown;
+    };
+}
+export declare function resolveNativeStorage(loaders?: NativeStorageLoaders): NativeStorageResolution;
+/**
+ * One dev-mode line naming the winning backend — a console.warn when
+ * persistence degraded, so a broken storage twin is loud instead of silent.
+ */
+export declare function logNativeStorageResolution(resolution: NativeStorageResolution, logger?: Pick<Console, "info" | "warn">): void;
 export declare const storage: Storage;
 //# sourceMappingURL=index.native.d.ts.map

package/types/storage/index.native.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.native.d.ts","sourceRoot":"","sources":["../../src/storage/index.native.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAsC1C,eAAO,MAAM,OAAO,EAAE,OAAyB,CAAC"}
+{"version":3,"file":"index.native.d.ts","sourceRoot":"","sources":["../../src/storage/index.native.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,eAAe,GAAG,QAAQ,CAAC;AAevE,6EAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,QAAQ,IAAI,OAAO,CAAC;IACpB,gFAAgF;IAChF,gBAAgB,IAAI,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,oBAAoB,CAAC;IAC9B,2EAA2E;IAC3E,MAAM,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CACpD;AAYD,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,oBAAqC,GAC7C,uBAAuB,CA+DzB;AAMD;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,uBAAuB,EACnC,MAAM,GAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAW,GAC/C,IAAI,CAcN;AASD,eAAO,MAAM,OAAO,EAAE,OAA4B,CAAC"}