@cavulsqa/create 2.2.1 → 2.4.0

package/bin/create.mjs

@@ -61,27 +61,25 @@ function listTemplates() {
 
   // The manifest is what `vp create` reads; the directory is what actually shipped. Trust the
   // directory, and let the manifest supply the descriptions.
-  return readdirSync(BUNDLED).map((name) => ({
-    name,
-    description: declared.find((entry) => entry.name === name)?.description ?? "",
-  }));
+  return readdirSync(BUNDLED, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => ({
+      name: entry.name,
+      description: declared.find((listed) => listed.name === entry.name)?.description ?? "",
+    }));
 }
 
 /**
- * The engine ids a template actually offers, read out of its own candidate list rather than kept in
- * a second list here - a generator that knows more engines than the template does is a generator
- * that writes a `.env` the app ignores.
+ * The engine ids a template offers, from the template's own manifest. `bundleTemplates.mjs` refuses
+ * to publish a template whose manifest disagrees with the engines its code implements, so this is
+ * data rather than a second opinion.
  */
 function listEngines(templateDir) {
   try {
-    const source = readFileSync(
-      join(templateDir, "src/shared/database/candidates/types.ts"),
-      "utf8",
-    );
-    const union = /export type StorageId =([\s\S]*?);/.exec(source)?.[1] ?? "";
-    return [...union.matchAll(/"([a-z0-9-]+)"/g)].map((match) => match[1]);
+    const pkg = JSON.parse(readFileSync(join(templateDir, "package.json"), "utf8"));
+    return pkg.cavulsqa?.storageEngines ?? [];
   } catch {
-    // A template without the candidate module simply has no engine choice to offer.
+    // A template that declares none simply has no engine choice to offer.
     return [];
   }
 }
@@ -133,7 +131,12 @@ async function main() {
     const appId =
       flags.get("app-id") ?? (await ask("Android application id", `com.ayb.${bareName}`));
 
-    const engines = listEngines(join(BUNDLED, template));
+    const from = flags.get("from");
+    const templateDir =
+      typeof from === "string" ? resolve(process.cwd(), from) : join(BUNDLED, template);
+
+    // Read from the directory that will actually be copied, so --from offers its own engines.
+    const engines = listEngines(templateDir);
     let engine = flags.get("engine");
     if (typeof engine !== "string" && engines.length > 1) {
       engine = await ask(`Storage engine [${engines.join(", ")}]`, engines[0]);
@@ -150,10 +153,6 @@ async function main() {
     const dir = flags.get("dir") ?? (await ask("Directory", `./${name}`));
     const out = isAbsolute(dir) ? dir : resolve(process.cwd(), dir);
 
-    const from = flags.get("from");
-    const templateDir =
-      typeof from === "string" ? resolve(process.cwd(), from) : join(BUNDLED, template);
-
     scaffold({
       templateDir,
       out,

package/lib/scaffold.mjs

@@ -22,7 +22,7 @@ function personalise(entry, text, { name, appName }) {
 
 function manifest(source, { name, appName, templateName }) {
   const pkg = JSON.parse(source);
-  const { private: _private, ...rest } = pkg;
+  const { private: _private, cavulsqa: _cavulsqa, ...rest } = pkg;
   return `${JSON.stringify(
     {
       ...rest,
@@ -37,9 +37,19 @@ function manifest(source, { name, appName, templateName }) {
   )}\n`;
 }
 
+/**
+ * Installed, generated or platform-specific: none of it belongs in a generated app.
+ *
+ * A bundled template never contains these, but `--from` points at a live working copy that usually
+ * does - and `node_modules` is full of directory symlinks, which `isDirectory()` reports as files and
+ * `readFileSync` then rejects with EISDIR. `--from` could not generate anything at all.
+ */
+const SKIP = new Set(["node_modules", "dist", "android", "ios", ".git", "pnpm-lock.yaml"]);
+
 function copyTree(from, to, transform) {
   mkdirSync(to, { recursive: true });
   for (const entry of readdirSync(from, { withFileTypes: true })) {
+    if (SKIP.has(entry.name)) continue;
     const source = join(from, entry.name);
     const target = join(to, entry.name);
     if (entry.isDirectory()) {
@@ -123,7 +133,7 @@ Generated from \`@cavulsqa/create\` (${templateName}).
 
 \`\`\`bash
 pnpm install
-pnpm dev            # browser, sql.js in memory - data does not survive a reload
+pnpm dev            # browser, SQLite in a worker on OPFS - data survives a reload
 npx cap add android # once
 pnpm build && npx cap sync android && npx cap run android
 \`\`\`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavulsqa/create",
-  "version": "2.2.1",
+  "version": "2.4.0",
   "description": "Create a Vue + Framework7 + Capacitor + SQLite app from the cavulsqa templates.",
   "keywords": [
     "capacitor",
@@ -52,7 +52,7 @@
       }
     ]
   },
-  "templatesFingerprint": "sha256-9dD3cJPCgdO6nEfyea3vG2eZNUNd4gzbYnde1KPIZIM=",
+  "templatesFingerprint": "sha256-tG0kS6m1X1FkrDBDpzezvdSxTxaLazPunAi3a0xab7o=",
   "scripts": {
     "build": "node scripts/bundleTemplates.mjs",
     "check": "vp check",

package/templates/f7-app/.claude/rules/data-fetching.md

@@ -16,13 +16,14 @@ which is the one failure an offline app cannot afford: the user has no network t
   product names and the customer's tags, so it lists all five. Count the tables in the SQL, not the
   ones you were thinking about.
 
-- **`queryKey` is a process-wide identity, not a label.** Two mounted queries sharing a key await
-  one request and share its result — right for the same list rendered twice, wrong for two
-  different queries that happen to be named alike, and the second silently receives the first's
-  rows. Framework7 keeps pages mounted, so two instances of one screen genuinely coexist.
-
-  Default to `uniqueQueryKey("prefix")`. A stable literal is opt-in sharing, and anything
-  parameterised by a route param or a ref must never use one.
+- **`queryKey` is a process-wide identity built from arguments, not a label.** It is an array, and
+  two mounted queries whose keys match await one request and share its result. Framework7 keeps
+  pages mounted, so two instances of one screen genuinely coexist — which is exactly why the key
+  has to carry what distinguishes them: `["demo:order", orderId]`, never `["demo:order"]`.
+
+  Put every value the query reads in the key. A ref belongs there directly — `["demo:search", term]`
+  — and the query re-runs through its own `debounce` when the ref moves, so a filtered screen never
+  calls `refetch()` by hand.
 
 - **`debounce`** collapses a burst. A loop of twenty inserts should refetch once, not twenty times.
 

package/templates/f7-app/.claude/rules/database.md

@@ -36,26 +36,28 @@ const orderId = Number(inserted.insertId ?? 0);
 if (!orderId) throw new Error("the order was written but the database reported no id for it");
 ```
 
-The SQLite plugin runs a statement issued inside an open transaction through `query()`, which
-executes it and drops its RETURNING rows. `.returning("id").executeTakeFirstOrThrow()` therefore
-threw `no result` from an insert that had in fact succeeded — a message that sends you hunting for a
-failed write. `@cavulsqa/mobile-db` now throws a message that says so, and fills `insertId` from
-`last_insert_rowid()` on both sides of a transaction boundary. The sql.js test dialect reports it
-too, so a repository written this way behaves the same in tests as on a device.
-
-## The web path is not the device path
-
-On a device the database is a real file behind the Capacitor plugin. In a browser it is sql.js in
-memory, through the dialect `@cavulsqa/mobile-db` ships for its own tests. Two consequences:
-
-- Browser data does not survive a reload. That is expected, not a bug to fix.
-- The plugin's own web mode is deliberately unused: it needs a `jeep-sqlite` element and a
-  `sql-wasm.wasm` whose build must match the glue jeep-sqlite bundles, a pairing outside this
-  template's control that fails as a `WebAssembly LinkError` on an upstream bump.
-
-Measurements taken in a browser do not transfer. Concurrent reads are several times faster than
-sequential ones **on a device**, because the native bridge pipelines them; in memory there is no
-bridge and the ratio sits at 1.
+`insertId` is the portable answer. Every engine reports it — the worker engines from
+`last_insert_rowid()`, the sql.js test dialect the same way — so a repository written against it
+behaves identically in tests and on a device. `.returning(...)` does work on the worker engines, but
+it is the one thing that differs between them: the Capacitor plugin runs a statement issued inside an
+open transaction through `query()`, which executes it and silently drops its RETURNING rows, so
+`.returning("id").executeTakeFirstOrThrow()` threw `no result` from an insert that had in fact
+succeeded. `@cavulsqa/mobile-db` now throws a message that says so instead.
+
+## The web path is the device path
+
+Both run the same engine: SQLite compiled to WebAssembly, in a worker, with the database file in
+OPFS. There is no Capacitor SQLite plugin in this template and no sql.js outside the tests. So:
+
+- **Browser data survives a reload.** OPFS is durable storage, not memory. Clear it from
+  Diagnostics, or through the browser's site-data controls.
+- A bug reproduced in the browser is very likely the same bug as on the device, which was not true
+  when the two ran different engines.
+- `localStorage["app.storage.force"]` pins the chain to one engine id, for comparing them.
+
+What still does not transfer is **timing**. A phone's storage and CPU are nothing like a laptop's,
+and the worker is serial either way, so a ratio measured in a browser says nothing about the device.
+Run the Diagnostics benchmark on hardware.
 
 ## Proof obligations
 

package/templates/f7-app/.claude/skills/module-architecture/file-templates.md

@@ -89,7 +89,7 @@ No `ref`, no lifecycle, no Framework7, no imports from `modules/`.
 ```ts
 import { listThings, saveThing, type ThingRow } from "@/domains/thing/thing.repository";
 import { getDatabase, rdb } from "@/shared/database/database";
-import { uniqueQueryKey, useReactiveQuery } from "@/shared/database/queries";
+import { useReactiveQuery } from "@/shared/database/queries";
 
 export function useFeature() {
   const term = ref("");
@@ -98,7 +98,8 @@ export function useFeature() {
   const query = useReactiveQuery(() => listThings(getDatabase().db, term.value), {
     // Every table the SQL touches. A join means each joined table.
     tables: ["thing"],
-    queryKey: uniqueQueryKey("feature:things"),
+    // The term is part of the identity, so the query re-runs (debounced) as it moves.
+    queryKey: ["feature:things", term],
     debounce: 250,
   });
 

package/templates/f7-app/.claude/skills/reactive-data/SKILL.md

@@ -13,7 +13,7 @@ tables it touched and every query watching one of them refetches. Nothing calls
 ```ts
 const query = useReactiveQuery(() => searchOrders(getDatabase().db, term.value), {
   tables: ["sales_order", "order_line", "customer"],
-  queryKey: uniqueQueryKey("demo:orders"),
+  queryKey: ["demo:orders", term],
   debounce: 250,
 });
 ```
@@ -24,9 +24,10 @@ const query = useReactiveQuery(() => searchOrders(getDatabase().db, term.value),
 2. **List every table the SQL touches in `tables`.** Count them in the query, not from memory: a
    join means each joined table. Under-list and the screen goes stale with no error; over-list and
    an unrelated write re-runs an expensive query.
-3. `queryKey`: default to `uniqueQueryKey("prefix")`. A stable literal means "share this result with
-   any other query using the same key", which is right for one list rendered twice and wrong for
-   anything parameterised.
+3. `queryKey` is an array of the values the query reads. Two mounted queries whose keys match
+   share one request, so anything that distinguishes them belongs in the key — a route param, a
+   filter ref. Refs are unwrapped and tracked: when one moves the query re-runs through its own
+   `debounce`, so never pair a key with a manual `refetch()`.
 4. `debounce` so a burst of writes causes one refetch.
 
 ## Adding a write

package/templates/f7-app/CLAUDE.md

@@ -64,7 +64,8 @@ The short version of the rules, each earned by a real bug:
   screen goes stale with no error. See `.claude/rules/data-fetching.md`.
 - **Every write goes through `rdb`**, never `getDatabase().db`. `rdb` announces the tables it
   touched; a raw write is invisible to every query watching them.
-- **`queryKey` is an identity, not a label.** Default to `uniqueQueryKey()`.
+- **`queryKey` is an identity built from arguments**, not a label: `["demo:order", orderId]`.
+  Refs in the key are tracked, so a filter belongs in it rather than in a manual `refetch()`.
 - **An inserted id comes from `insertId`, never `.returning(...)`.** Inside a transaction the
   SQLite plugin executes the statement and drops its RETURNING rows, so the insert succeeds and
   kysely reports `no result`. See `.claude/rules/database.md`.

package/templates/f7-app/package.json

@@ -19,9 +19,9 @@
     "@capacitor/preferences": "^8.0.0",
     "@capacitor/splash-screen": "^8.0.0",
     "@capacitor/status-bar": "^8.0.0",
-    "@cavulsqa/mobile-db": "^0.5.0",
-    "@cavulsqa/reactive-db": "^0.2.0",
-    "@cavulsqa/reactive-vue": "^0.2.0",
+    "@cavulsqa/mobile-db": "^0.6.0",
+    "@cavulsqa/reactive-db": "^0.3.0",
+    "@cavulsqa/reactive-vue": "^0.3.0",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@tailwindcss/vite": "^4.3.3",
     "@vueuse/core": "^14.4.0",
@@ -47,5 +47,13 @@
     "vite": "npm:@voidzero-dev/vite-plus-core@0.3.0",
     "vite-plus": "0.3.0",
     "vue-tsc": "^3.2.4"
+  },
+  "cavulsqa": {
+    "storageEngines": [
+      "sqlite-wasm-opfs-sahpool",
+      "wa-sqlite-access-handle-pool",
+      "wa-sqlite-opfs-async",
+      "wa-sqlite-idb-batch-atomic"
+    ]
   }
 }

package/templates/f7-app/src/app/pragmas.config.ts

@@ -1,19 +1,11 @@
 /**
- * PRAGMAs applied to every engine, identically, right after it opens.
+ * PRAGMAs applied to every engine identically, because SQLite's defaults are per-build and two
+ * engines left on their own are not comparable - an unpinned `synchronous` alone produced a 1.47x
+ * "ranking" between engines that were the same speed.
  *
- * They live here rather than inside a candidate for one reason: SQLite's defaults are per-build, and
- * two engines left on their own defaults are not comparable. Measuring them without pinning this
- * produced a 1.47x "ranking" that may have been nothing but a difference in `synchronous`.
- *
- * `fast` is what a benchmark should use - both engines pushed as hard as they go, so the comparison
- * is between engines rather than between journal settings. It is not a safe default for an app that
- * holds a day's orders: `synchronous = OFF` means the OS, not SQLite, decides when bytes reach
- * storage, so a crash or a battery pull can leave the database corrupt rather than merely stale.
- *
- * `safe` keeps SQLite's durability guarantee and pays for it on single writes, which the benchmark
- * measures at 19-57 ms depending on engine. Both settings batch equally well - inside one
- * transaction the cost per row falls under 3 ms either way - so an app that batches its writes gives
- * up very little by staying safe.
+ * `fast` is for measuring only: `synchronous = OFF` hands durability to the OS, so a battery pull can
+ * leave the database corrupt rather than merely stale. `safe` costs 19-57 ms on a single write and
+ * under 3 ms per row inside a transaction, so an app that batches gives up very little.
  */
 export type PragmaProfile = "fast" | "safe";
 
@@ -35,14 +27,6 @@ const PROFILES: Record<PragmaProfile, readonly string[]> = {
   ],
 };
 
-/**
- * From `VITE_PRAGMA_PROFILE`, defaulting to `safe`.
- *
- * Safe by default because the cost is small once writes are batched - inside one transaction the
- * per-row difference is under a millisecond - and the failure it prevents is a corrupt database
- * rather than a slow one. Set `fast` when measuring, where the point is to compare engines rather
- * than journal settings.
- */
 export const pragmaProfile: PragmaProfile =
   import.meta.env.VITE_PRAGMA_PROFILE === "fast" ? "fast" : "safe";
 

package/templates/f7-app/src/app/storage.config.ts

@@ -1,35 +1,24 @@
 import {
+  isStorageId,
   opfsSahPool,
   waAccessHandlePool,
   waIdbBatchAtomic,
   waOriginPrivateFileSystem,
+  STORAGE_IDS,
   type StorageCandidate,
 } from "@/shared/database/candidates";
 
 /**
- * Which SQLite implementation this app uses, and what it falls back to.
+ * The knob. Walked in order, first candidate that opens wins, and the rest are never imported - so a
+ * chain that stops at the first entry never downloads wa-sqlite's wasm.
  *
- * This is the knob. The list is walked in order: each candidate is asked whether the device supports
- * it, then asked to open; the first that succeeds wins, and the rest are never imported - so a chain
- * that stops at the first entry never downloads wa-sqlite's wasm at all.
+ * Reorder freely to trade speed for reach: `waIdbBatchAtomic` first is the compatibility choice,
+ * since IndexedDB is the only durable route on a WebView between Chromium 86 and 108. Only
+ * `sqlite-wasm-opfs-sahpool` has been measured on a phone; the rest carry `evidence: "expected"`.
  *
- * Ordered fastest-first, and that ordering is a claim worth being precise about. Only
- * `sqlite-wasm-opfs-sahpool` has been measured on a phone; the three below it are placed on the
- * vendor's own description of them and each says so through `evidence`. The Diagnostics benchmark
- * exists to replace that guess with numbers.
- *
- * Reorder freely - this is the supported way to trade speed for reach:
- *
- * - Compatibility first: put `waIdbBatchAtomic` at the top. IndexedDB is the only durable route on a
- *   WebView between Chromium 86 and 108, which runs this bundle but has no synchronous access
- *   handles. Slowest, works almost everywhere.
- * - One vendor only: drop `opfsSahPool` and keep the wa-sqlite three, or the reverse. Both engines
- *   implement the same dialect contract, so nothing above this file changes either way.
- *
- * There is deliberately no in-memory entry. A chain that silently ends somewhere data is not kept is
- * worse than one that fails and says why, and the error screen names every attempt.
+ * No in-memory entry on purpose: a chain that ends somewhere data is not kept is worse than one that
+ * fails and names every attempt.
  */
-/** The ranking, before any environment preference reorders it. */
 export const DEFAULT_ORDER: StorageCandidate[] = [
   opfsSahPool,
   waAccessHandlePool,
@@ -42,13 +31,21 @@ export const DEFAULT_ORDER: StorageCandidate[] = [
  * env var reorders the chain rather than replacing it - a device that cannot open the preferred
  * engine still gets a working app.
  *
- * An unknown id is ignored rather than fatal: a typo in a `.env` should not brick the build's
- * output, and the app reports which candidate actually opened in Settings.
+ * A typo is reported and ignored rather than fatal: it should not brick the build's output, but a
+ * setting that was silently dropped looks exactly like one that was applied and did nothing.
  */
 function preferredFirst(candidates: StorageCandidate[]): StorageCandidate[] {
   const preferred = import.meta.env.VITE_STORAGE_ENGINE;
   if (!preferred) return candidates;
 
+  if (!isStorageId(preferred)) {
+    console.warn(
+      `[storage] VITE_STORAGE_ENGINE="${preferred}" is not an engine this app has. ` +
+        `Expected one of: ${STORAGE_IDS.join(", ")}. Falling back to the default order.`,
+    );
+    return candidates;
+  }
+
   const match = candidates.find((candidate) => candidate.id === preferred);
   return match ? [match, ...candidates.filter((candidate) => candidate !== match)] : candidates;
 }

package/templates/f7-app/src/app/tabs.ts

@@ -9,15 +9,7 @@ export interface TabDefinition {
   iconMd: string;
 }
 
-/**
- * The tab bar is data: add an entry, add a route file in the matching module, and the shell, the bar
- * and the navigation all follow. Each tab is a Framework7 view with its own history, so switching
- * away and back returns to the same screen.
- *
- * Icons are given per theme rather than once. Framework7 picks `icon-ios` or `icon-md` from the
- * active theme, which is what makes the bar look native on both platforms instead of iOS glyphs on
- * Android.
- */
+/** Add an entry plus a route file in the matching module; the shell and the bar follow. */
 export const tabs: TabDefinition[] = [
   { id: "home", labelKey: "tabs.home", iconIos: "house_fill", iconMd: "home" },
   { id: "demo", labelKey: "tabs.demo", iconIos: "bolt_fill", iconMd: "bolt" },

package/templates/f7-app/src/domains/sales/sales.repository.ts

@@ -1,5 +1,5 @@
 import { sql, type Kysely } from "kysely";
-import { nowISO } from "@cavulsqa/mobile-db/core";
+import { nowISO } from "@cavulsqa/mobile-db";
 import type { Database } from "@/shared/database/schema";
 
 export interface DashboardStats {

package/templates/f7-app/src/env.d.ts

@@ -26,6 +26,10 @@ declare const __APP_VERSION__: string;
  * The environment this app reads. Declared, so a typo in a variable name is a type error rather than
  * a silent `undefined` that falls back to the default and looks like the setting was ignored.
  *
+ * The engine is `string`, not `StorageId`, because a `.env` is unchecked text: a union here would
+ * claim a guarantee nothing enforces. `storage.config.ts` narrows it with `isStorageId` and reports
+ * a value it does not recognise.
+ *
  * See `.env.example` for what each value means.
  */
 interface ImportMetaEnv {

package/templates/f7-app/src/locales/en.json

@@ -24,10 +24,10 @@
     "parallel": "Together",
     "sequential": "One by one",
     "ratio": "Faster by",
-    "pipeliningNative": "{count} reads issued together, then the same {count} awaited one at a time. Reads stay outside the write lock and the native bridge pipelines them, so together should win by several times.",
-    "pipeliningWeb": "{count} reads issued together, then the same {count} awaited one at a time. In a browser this measures nothing useful — see the note under the result.",
-    "ratioNative": "Above 1x means concurrent reads are genuinely overlapping on the native bridge. Near 1x would mean something is serialising them.",
-    "ratioWeb": "Expected on {platform}: the web path is sql.js in memory with no bridge to pipeline, so issuing reads together buys nothing and adds a little overhead. The several-times gain is a device property — measure it there.",
+    "pipeliningNative": "{count} reads issued together, then the same {count} awaited one at a time. The engine runs in a worker that executes statements one at a time, so issuing them together overlaps the message round trips and nothing else.",
+    "pipeliningWeb": "{count} reads issued together, then the same {count} awaited one at a time. In a desktop browser the round trip is nearly free - see the note under the result.",
+    "ratioNative": "Above 1x means the message round trips are overlapping. The worker is serial, so this can never show queries themselves running in parallel.",
+    "ratioWeb": "Expected on {platform}: the worker is serial and a desktop round trip is nearly free, so there is little to overlap. Measure on a device, where the round trip costs something.",
     "data": "Data",
     "diagnostics": "Diagnostics",
     "searchPlaceholder": "Search orders or customers",

package/templates/f7-app/src/locales/fr.json

@@ -24,10 +24,10 @@
     "parallel": "Ensemble",
     "sequential": "Une par une",
     "ratio": "Plus rapide de",
-    "pipeliningNative": "{count} lectures lancées ensemble, puis les mêmes {count} une par une. Les lectures restent hors du verrou d'écriture et le pont natif les parallélise : « ensemble » devrait gagner largement.",
-    "pipeliningWeb": "{count} lectures lancées ensemble, puis les mêmes {count} une par une. Dans un navigateur, cette mesure n'a pas de sens — voir la note sous le résultat.",
-    "ratioNative": "Au-dessus de 1x, les lectures se chevauchent réellement sur le pont natif. Proche de 1x signifierait que quelque chose les sérialise.",
-    "ratioWeb": "Attendu sur {platform} : le chemin web est sql.js en mémoire, sans pont à paralléliser — les lancer ensemble n'apporte rien. Le gain se mesure sur un appareil.",
+    "pipeliningNative": "{count} lectures lancées ensemble, puis les mêmes {count} attendues une par une. Le moteur tourne dans un worker qui exécute les requêtes une à la fois : les lancer ensemble ne recouvre que les allers-retours de messages.",
+    "pipeliningWeb": "{count} lectures lancées ensemble, puis les mêmes {count} attendues une par une. Dans un navigateur de bureau l'aller-retour est quasi gratuit - voir la note sous le résultat.",
+    "ratioNative": "Au-dessus de 1x, les allers-retours de messages se recouvrent. Le worker est séquentiel : ce test ne montrera jamais des requêtes exécutées en parallèle.",
+    "ratioWeb": "Attendu sur {platform} : le worker est séquentiel et l'aller-retour de bureau est quasi gratuit, il n'y a donc presque rien à recouvrir. Mesurez sur un appareil.",
     "data": "Données",
     "diagnostics": "Diagnostics",
     "searchPlaceholder": "Chercher une commande ou un client",

package/templates/f7-app/src/modules/demo/composables/useReactiveDemo.ts

@@ -15,7 +15,7 @@ import {
   type OrderRow,
 } from "@/domains/sales/sales.repository";
 import { activeStorageLabel, changeBus, getDatabase, rdb } from "@/shared/database/database";
-import { uniqueQueryKey, useReactiveQuery } from "@/shared/database/queries";
+import { useReactiveQuery } from "@/shared/database/queries";
 
 export interface BusEntry {
   /** Monotonic, because a millisecond timestamp is not unique - several events share one. */
@@ -62,13 +62,13 @@ export function useReactiveDemo() {
   const statsQuery = useReactiveQuery(() => loadDashboardStats(getDatabase().db), {
     // Four tables, because the tiles aggregate across all of them.
     tables: ["customer", "product", "sales_order", "order_line"],
-    queryKey: uniqueQueryKey("demo:stats"),
+    queryKey: ["demo:stats"],
     debounce: 250,
   });
 
   const ordersQuery = useReactiveQuery(() => searchOrders(getDatabase().db, ""), {
     tables: ["sales_order", "order_line", "customer"],
-    queryKey: uniqueQueryKey("demo:orders"),
+    queryKey: ["demo:orders"],
     debounce: 250,
   });
 
@@ -118,10 +118,9 @@ export function useReactiveDemo() {
   /**
    * Reads issued together against reads awaited one by one.
    *
-   * On a device the ratio is the point: the native bridge pipelines concurrent calls and the dialect
-   * keeps reads out of the write lock, so a screen loading with `Promise.all` pays once rather than
-   * N times. In a browser it sits near 1x because sql.js in memory has no bridge to pipeline, and
-   * the screen says so rather than reporting a number that reads as a regression.
+   * The worker executes statements one at a time, so this measures how much of a read is the message
+   * round trip rather than the query - it cannot show queries overlapping, and a ratio near 1x is
+   * the expected result rather than a regression.
    */
   async function measurePipelining(): Promise<void> {
     measuring.value = true;

package/templates/f7-app/src/modules/demo/views/OrderDetailView.vue

@@ -82,7 +82,7 @@ import {
 } from "@/domains/sales/sales.repository";
 import { useHiddenTabbar } from "@/shared/composables/useTabbarVisibility";
 import { getDatabase, rdb } from "@/shared/database/database";
-import { uniqueQueryKey, useReactiveQuery } from "@/shared/database/queries";
+import { useReactiveQuery } from "@/shared/database/queries";
 
 const { t } = useI18n();
 
@@ -100,7 +100,7 @@ const statuses = ["draft", "confirmed", "delivered"] as const;
  */
 const query = useReactiveQuery(() => loadOrderDetail(getDatabase().db, orderId), {
   tables: ["sales_order", "order_line", "customer", "product", "customer_tag"],
-  queryKey: uniqueQueryKey(`demo:order-${String(orderId)}`),
+  queryKey: ["demo:order", orderId],
 });
 
 const order = computed<OrderDetail | null>(() => query.data.value ?? null);

package/templates/f7-app/src/modules/demo/views/OrderSearchView.vue

@@ -60,7 +60,7 @@
 import { useHiddenTabbar } from "@/shared/composables/useTabbarVisibility";
 import { searchOrders, type OrderRow } from "@/domains/sales/sales.repository";
 import { getDatabase } from "@/shared/database/database";
-import { uniqueQueryKey, useReactiveQuery } from "@/shared/database/queries";
+import { useReactiveQuery } from "@/shared/database/queries";
 
 const { t } = useI18n();
 
@@ -75,7 +75,7 @@ const term = ref("");
  */
 const query = useReactiveQuery(() => searchOrders(getDatabase().db, term.value), {
   tables: ["sales_order", "order_line", "customer"],
-  queryKey: uniqueQueryKey("demo:search"),
+  queryKey: ["demo:search", term],
   debounce: 200,
 });
 
@@ -83,12 +83,10 @@ const results = computed<OrderRow[]>(() => query.data.value ?? []);
 
 function onInput(event: Event) {
   term.value = (event.target as HTMLInputElement).value;
-  void query.refetch();
 }
 
 function onClear() {
   term.value = "";
-  void query.refetch();
 }
 
 const formatter = new Intl.NumberFormat(undefined, { maximumFractionDigits: 0 });

package/templates/f7-app/src/plugins/seed.plugin.ts

@@ -1,17 +1,7 @@
 import { ensureReferenceData } from "@/domains/sales/sales.repository";
 import { rdb } from "@/shared/database";
 
-/**
- * Reference data the app cannot work without: the product catalogue, the tags, a few customers.
- *
- * A template has to be usable the moment it opens. Without this, the first thing a new install asks
- * you to do is press "seed sample data" before the New order sheet has anything to pick from - the
- * schema is there and every screen is empty, which reads as broken rather than as new.
- *
- * `ensureReferenceData` is idempotent, so this runs on every start and does nothing after the first.
- * Replace it with your own once the app has real data to load; delete it if data arrives from a
- * server. Demo orders stay behind the button - those are a demo, this is a working state.
- */
+/** Runs on every start: `ensureReferenceData` is idempotent and does nothing after the first. */
 export async function seedPlugin(): Promise<void> {
   await ensureReferenceData(rdb);
 }

package/templates/f7-app/src/plugins/sqlite.plugin.ts

@@ -8,14 +8,25 @@ const OPEN_TIMEOUT_MS = 10_000;
  * empty `#app` and nothing in the console. The timeout turns a hang into a message.
  */
 export async function sqlitePlugin(): Promise<void> {
-  await Promise.race([
-    openDatabase(),
-    new Promise<never>((_, reject) => {
-      setTimeout(
-        () =>
-          reject(new Error(`opening the database did not finish in ${String(OPEN_TIMEOUT_MS)}ms`)),
-        OPEN_TIMEOUT_MS,
-      );
-    }),
-  ]);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  try {
+    await Promise.race([
+      openDatabase(),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () =>
+            reject(
+              new Error(`opening the database did not finish in ${String(OPEN_TIMEOUT_MS)}ms`),
+            ),
+          OPEN_TIMEOUT_MS,
+        );
+      }),
+    ]);
+  } finally {
+    // Losing the race does not stop the timer, which then held the event loop for the full timeout
+    // after a fast open. The walk itself is not cancellable, but `openDatabase` memoises it, so a
+    // retry joins the attempt already running instead of racing it for the same OPFS directory.
+    clearTimeout(timer);
+  }
 }

package/templates/f7-app/src/shared/database/candidates/opfsSahPool.ts

@@ -1,4 +1,4 @@
-import { OpfsSQLiteDialect } from "@cavulsqa/mobile-db/opfs";
+import { createOpfsDialect } from "@cavulsqa/mobile-db/opfs";
 import OpfsWorker from "../opfs.worker?worker";
 import { probeOpfsCapable } from "../storage";
 import type { StorageCandidate } from "./types";
@@ -21,5 +21,5 @@ export const opfsSahPool: StorageCandidate = {
   evidence: "measured",
   probe: probeOpfsCapable,
   createDialect: () =>
-    Promise.resolve(new OpfsSQLiteDialect({ worker: new OpfsWorker(), name: "app.sqlite3" })),
+    Promise.resolve(createOpfsDialect({ worker: new OpfsWorker(), name: "app.sqlite3" })),
 };

package/templates/f7-app/src/shared/database/candidates/types.ts

@@ -1,17 +1,31 @@
 import type { Dialect } from "kysely";
 
-export type StorageId =
-  | "sqlite-wasm-opfs-sahpool"
-  | "wa-sqlite-access-handle-pool"
-  | "wa-sqlite-opfs-async"
-  | "wa-sqlite-idb-batch-atomic";
+/**
+ * Every engine this template offers, as values rather than only as a type.
+ *
+ * A types-only union cannot be read at runtime, and everything that needs the list had to invent
+ * its own copy: `@cavulsqa/create` was regexing this very file to populate `--engine`, and
+ * `localStorage`'s override was cast rather than checked.
+ */
+export const STORAGE_IDS = [
+  "sqlite-wasm-opfs-sahpool",
+  "wa-sqlite-access-handle-pool",
+  "wa-sqlite-opfs-async",
+  "wa-sqlite-idb-batch-atomic",
+] as const;
+
+export type StorageId = (typeof STORAGE_IDS)[number];
 
-export interface StorageProbe {
-  supported: boolean;
-  /** Present when unsupported, phrased so the person reading it can act on it. */
-  reason?: string;
+export function isStorageId(value: string): value is StorageId {
+  return (STORAGE_IDS as readonly string[]).includes(value);
 }
 
+/**
+ * A union rather than an optional field, so an unsupported probe cannot forget its reason and a
+ * supported one cannot carry a stale one.
+ */
+export type StorageProbe = { supported: true } | { supported: false; reason: string };
+
 /**
  * One way to persist SQLite, described well enough to choose between them without reading the code.
  *

package/templates/f7-app/src/shared/database/candidates/waSqlite.ts

@@ -1,4 +1,4 @@
-import { WaSQLiteDialect, type WaVfsKind } from "@cavulsqa/mobile-db/wa";
+import { createWaDialect, type WaVfsKind } from "@cavulsqa/mobile-db/wa";
 import WaWorker from "../wa.worker?worker";
 import { probeIndexedDb, probeOpfsCapable } from "../storage";
 import type { StorageCandidate } from "./types";
@@ -24,9 +24,7 @@ function waCandidate(
     // Nothing below the official pool has been on a phone yet.
     evidence: "expected",
     createDialect: () =>
-      Promise.resolve(
-        new WaSQLiteDialect({ worker: new WaWorker(), name: "app-wa.sqlite3", kind }),
-      ),
+      Promise.resolve(createWaDialect({ worker: new WaWorker(), name: "app-wa.sqlite3", kind })),
   };
 }
 

package/templates/f7-app/src/shared/database/database.ts

@@ -1,60 +1,52 @@
 import { Kysely, sql, type Dialect } from "kysely";
 import { Migrator } from "kysely/migration";
-import { runWrite, type MobileDatabase } from "@cavulsqa/mobile-db/core";
+import { runWrite, type MobileDatabase } from "@cavulsqa/mobile-db";
 import { createChangeBus, createReactiveDb } from "@cavulsqa/reactive-db";
 import { pragmaProfile, pragmasFor } from "@/app/pragmas.config";
 import { storageChain } from "@/app/storage.config";
-import type { StorageId } from "./candidates";
-import type { StorageAttempt, StorageCandidate } from "./candidates";
+import { isStorageId, type StorageAttempt, type StorageCandidate } from "./candidates";
 import { migrations } from "./migrations";
 import { describeOpenFailure } from "./storage";
 import type { Database } from "./schema";
 
-/**
- * One bus for the whole app. Writes announce the tables they touched on it and reactive queries
- * listen to it, so both sides have to be the same instance - which is why it is created here and
- * passed outward rather than constructed wherever it is needed.
- */
-export const changeBus = createChangeBus();
+/** Writes and reactive queries must share one instance, so it is created here and passed outward. */
+export const changeBus = createChangeBus<Database>();
 
 const RETRY_DELAY_MS = 400;
 
 let database: MobileDatabase<Database> | null = null;
+let opening: Promise<MobileDatabase<Database>> | null = null;
 let chosen: StorageCandidate | null = null;
 let attempts: StorageAttempt[] = [];
-let applied: string[] = [];
+let applied: readonly string[] = [];
+
+interface OpenedDatabase {
+  handle: MobileDatabase<Database>;
+  pragmas: readonly string[];
+}
 
 /**
- * Wraps a Kysely instance in the shape the app consumes, and runs the migrations.
- *
- * Shared by every candidate: they differ in how bytes reach storage and in nothing above that, which
- * is what makes the chain swappable at all.
+ * Wraps a Kysely instance in the shape the app consumes, and runs the migrations. Shared by every
+ * candidate: they differ in how bytes reach storage and in nothing above it, which is what makes the
+ * chain swappable at all.
  */
-async function fromDialect(dialect: Dialect): Promise<MobileDatabase<Database>> {
+async function fromDialect(candidate: StorageCandidate, dialect: Dialect): Promise<OpenedDatabase> {
   const db = new Kysely<Database>({ dialect });
 
-  /**
-   * Before the migrations, and identically for every engine. SQLite's defaults are per-build, so two
-   * engines left on their own are not comparable - a difference in `synchronous` alone can look like
-   * one engine being half as fast as the other.
-   */
-  applied = [];
+  // Before the migrations, and identically for every engine - see pragmas.config.ts for why.
+  const pragmas: string[] = [];
   for (const pragma of pragmasFor(pragmaProfile)) {
     try {
       await sql.raw(pragma).execute(db);
-      applied.push(pragma);
+      pragmas.push(pragma);
     } catch (error) {
       // A VFS that refuses a journal mode is worth knowing about, not worth failing over.
-      applied.push(`${pragma} -> rejected: ${error instanceof Error ? error.message : "unknown"}`);
+      pragmas.push(`${pragma} -> rejected: ${error instanceof Error ? error.message : "unknown"}`);
     }
   }
 
-  /**
-   * `migrateToLatest` reports failure in its return value rather than throwing, so an unchecked call
-   * boots an app whose tables were never created - which is exactly what happened: a deleted
-   * migration made kysely refuse the whole set, and the failure only surfaced later as
-   * "no such table" from the first query that needed one.
-   */
+  // `migrateToLatest` reports failure in its return value rather than throwing, so an unchecked
+  // call boots an app whose tables were never created - it surfaced as "no such table" much later.
   const migration = await new Migrator({
     db,
     provider: { getMigrations: () => Promise.resolve(migrations) },
@@ -69,16 +61,16 @@ async function fromDialect(dialect: Dialect): Promise<MobileDatabase<Database>>
   }
 
   return {
-    db,
-    write: (ctx, work) =>
-      runWrite(ctx, () => db.transaction().execute((trx) => work(trx)), {
-        runInTransaction: <R>(task: () => Promise<R>) => task(),
-        emitTableChange: (table) => changeBus.emit(table, "bulk"),
-      }),
-    getRawConnection: () => {
-      throw new Error("the OPFS engine has no native connection");
+    pragmas,
+    handle: {
+      db,
+      write: (ctx, work) =>
+        runWrite(ctx, () => db.transaction().execute((trx) => work(trx)), {
+          runInTransaction: <R>(task: () => Promise<R>) => task(),
+          emitTableChange: (table) => changeBus.emit(table, "bulk"),
+        }),
+      close: () => db.destroy(),
     },
-    close: () => db.destroy(),
   };
 }
 
@@ -102,22 +94,13 @@ export function storageAttempts(): readonly StorageAttempt[] {
   return attempts;
 }
 
-/**
- * Walks the chain in `storage.config.ts` and keeps the first candidate that opens.
- *
- * A candidate is skipped when it says the device cannot support it, and dropped when it says so by
- * throwing. Every step is recorded: which were skipped and why, which failed and with what, and
- * which won - because a silent fallback to a slower or non-durable engine is the kind of thing that
- * gets discovered weeks later by someone wondering why the app is slow.
- */
+// Every step is recorded, because a silent fallback to a slower engine gets discovered weeks later
+// by someone wondering why the app is slow.
 const FORCE_KEY = "app.storage.force";
 
 /**
- * Pins the chain to one candidate, for benchmarking.
- *
- * Set `localStorage.app.storage.force` to a candidate id and only that engine is tried - not moved
- * to the front, the *only* one - because a benchmark that quietly fell through to a different engine
- * would report the wrong engine's numbers. An unknown id is ignored rather than bricking the app.
+ * Pins the chain to one candidate for benchmarking: the *only* one tried, not merely promoted, since
+ * a benchmark that fell through to another engine would report the wrong engine's numbers.
  */
 function forcedChain(): StorageCandidate[] {
   let forced: string | null = null;
@@ -126,14 +109,33 @@ function forcedChain(): StorageCandidate[] {
   } catch {
     // Storage disabled; the full chain is the right answer anyway.
   }
-  if (!forced) return storageChain;
+  if (!forced || !isStorageId(forced)) return storageChain;
 
-  const pinned = storageChain.find((candidate) => candidate.id === (forced as StorageId));
+  const pinned = storageChain.find((candidate) => candidate.id === forced);
   return pinned ? [pinned] : storageChain;
 }
 
-export async function openDatabase(): Promise<MobileDatabase<Database>> {
-  if (database) return database;
+/**
+ * Memoised on the promise, not the result. Two callers in the same tick both passed a `if (database)`
+ * guard and both walked the chain - and since the pool VFSes hold their OPFS directory exclusively,
+ * the second collided with the first and fell through to a slower engine the app then reported as
+ * its choice.
+ */
+export function openDatabase(): Promise<MobileDatabase<Database>> {
+  if (database) return Promise.resolve(database);
+  opening ??= walkStorageChain();
+  return opening;
+}
+
+async function walkStorageChain(): Promise<MobileDatabase<Database>> {
+  try {
+    return await tryEveryCandidate();
+  } finally {
+    opening = null;
+  }
+}
+
+async function tryEveryCandidate(): Promise<MobileDatabase<Database>> {
   if (!storageChain.length) throw new Error("storageChain is empty: nothing can open the database");
 
   attempts = [];
@@ -148,7 +150,9 @@ export async function openDatabase(): Promise<MobileDatabase<Database>> {
     }
 
     try {
-      database = await openCandidate(candidate);
+      const opened = await openCandidate(candidate);
+      database = opened.handle;
+      applied = opened.pragmas;
       chosen = candidate;
       attempts.push({ id: candidate.id, outcome: "opened" });
       return database;
@@ -168,18 +172,17 @@ export async function openDatabase(): Promise<MobileDatabase<Database>> {
 }
 
 /**
- * One retry per candidate, because the pool VFSes take an exclusive lock on their directory and the
- * usual reason it is held is a process on its way out - a crash, or a relaunch racing the old
- * WebView's teardown. Its handles are released when that process dies, so the same open succeeds a
- * moment later. Exactly one retry: past that, the chain moving on is the better answer.
+ * One retry, because the usual reason a pool VFS's directory lock is held is a process on its way out
+ * - its handles are released when that process dies, so the same open succeeds a moment later. Past
+ * one, the chain moving on is the better answer.
  */
-async function openCandidate(candidate: StorageCandidate): Promise<MobileDatabase<Database>> {
+async function openCandidate(candidate: StorageCandidate): Promise<OpenedDatabase> {
   try {
-    return await fromDialect(await candidate.createDialect());
+    return await fromDialect(candidate, await candidate.createDialect());
   } catch (first) {
     await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS));
     try {
-      return await fromDialect(await candidate.createDialect());
+      return await fromDialect(candidate, await candidate.createDialect());
     } catch {
       // The first error is the honest one; the retry's is a duplicate of it.
       throw first;
@@ -201,6 +204,7 @@ export const rdb = createReactiveDb<Database>({
 export async function closeDatabase(): Promise<void> {
   await database?.close();
   database = null;
+  opening = null;
   chosen = null;
   attempts = [];
   applied = [];

package/templates/f7-app/src/shared/database/migrations.ts

@@ -1,4 +1,4 @@
-import { createTableWithDefaults, type MigrationSet } from "@cavulsqa/mobile-db/core";
+import { createTableWithDefaults, type MigrationSet } from "@cavulsqa/mobile-db";
 import { sql } from "kysely";
 
 /**

package/templates/f7-app/src/shared/database/queries.ts

@@ -1,6 +1,7 @@
 import { createReactiveQuery, createVueQueryMetrics } from "@cavulsqa/reactive-vue";
 import { usePageVisibility } from "@cavulsqa/reactive-vue/framework7";
 import { changeBus } from "./database";
+import type { Database } from "./schema";
 
 const metrics = createVueQueryMetrics({
   exposeOnWindowAs: import.meta.env.DEV ? "__appMetrics" : undefined,
@@ -10,13 +11,16 @@ const metrics = createVueQueryMetrics({
  * The composables every screen uses. They are built once, here, because the change bus and the
  * metrics recorder are app-wide singletons - a query created with a different bus would never hear
  * about a write.
+ *
+ * Typed on `Database`, so every `tables` entry is checked against the schema. A misspelt table name
+ * is otherwise invisible: the query subscribes to a table nobody writes to and never refetches.
  */
-export const { useReactiveQuery, useStructuralQuery, useStaticQuery } = createReactiveQuery({
-  onTableChange: changeBus.on,
-  metrics: metrics.recorder,
-  // Without this a tab the user cannot see keeps refetching in the background.
-  useVisibility: usePageVisibility,
-});
+export const { useReactiveQuery, useStructuralQuery, useStaticQuery } =
+  createReactiveQuery<Database>({
+    onTableChange: changeBus.on,
+    metrics: metrics.recorder,
+    // Without this a tab the user cannot see keeps refetching in the background.
+    useVisibility: usePageVisibility,
+  });
 
 export const { useQueryMetrics } = metrics;
-export { uniqueQueryKey } from "@cavulsqa/reactive-vue";

package/templates/f7-app/src/shared/database/storage.ts

@@ -3,24 +3,10 @@ import type { StorageProbe } from "./candidates/types";
 export type { StorageProbe };
 
 /**
- * Capability checks and failure diagnosis, shared by the candidates.
- *
- * The chain itself lives in `app/storage.config.ts` and each engine in `candidates/`; this is only
- * the part they have in common - deciding whether a device can host OPFS at all, and turning an
- * engine's failure into a sentence somebody can act on.
- */
-
-/**
- * Only what the main thread can honestly observe.
- *
- * The tempting check - `"createSyncAccessHandle" in FileSystemFileHandle.prototype` - is wrong here
- * and rejected a phone on WebView 150 that had been running OPFS happily: synchronous access handles
- * are Worker-only in Chromium, so the method is absent from the main-thread prototype on *every*
- * device, new or old. `navigator.storage.getDirectory` is visible from both scopes, so that is the
- * whole of what can be pre-checked.
- *
- * Anything finer belongs to the engine. `describeOpenFailure` turns its error into something a
- * person can act on, which is what the pre-check was reaching for in the first place.
+ * `navigator.storage.getDirectory` is the whole of what a main-thread probe can see. Synchronous
+ * access handles are Worker-only in Chromium, so checking `createSyncAccessHandle` on
+ * `FileSystemFileHandle.prototype` is false on *every* device - it rejected a phone that had been
+ * running OPFS for hours. Anything finer belongs to the engine, via `describeOpenFailure`.
  */
 export function probeOpfsCapable(): StorageProbe {
   if (typeof navigator === "undefined" || !navigator.storage?.getDirectory) {
@@ -35,11 +21,6 @@ export function probeOpfsCapable(): StorageProbe {
   return { supported: true };
 }
 
-/**
- * The engine is the authority on whether it can open, so its failure is wrapped rather than
- * predicted. A missing synchronous access handle surfaces from inside wasm initialisation, where the
- * message names an internal symbol and not the thing to do about it.
- */
 export function probeIndexedDb(): StorageProbe {
   if (typeof indexedDB === "undefined") {
     return {
@@ -65,11 +46,8 @@ export function describeOpenFailure(error: unknown): string {
 }
 
 /**
- * The Chromium version behind this WebView, which is the number that decides whether OPFS works.
- *
- * Worth surfacing rather than reasoning about: Android System WebView updates from the Play Store
- * independently of Android itself, so the OS version says nothing useful. A phone on Android 7 with
- * a current WebView is fine; a phone on Android 14 that has never reached the Play Store may not be.
+ * Android System WebView updates from the Play Store independently of Android itself, so the OS
+ * version says nothing useful here - a phone on Android 7 can be current and one on Android 14 old.
  */
 export function webviewVersion(): number | null {
   if (typeof navigator === "undefined") return null;
@@ -77,15 +55,7 @@ export function webviewVersion(): number | null {
   return match ? Number(match[1]) : null;
 }
 
-/**
- * OPFS arrived in Chromium 86, synchronous access handles followed, and the combination is reported
- * stable in WebView from 109. 109 is used rather than the earlier number because this value only
- * ever produces advice: too low and a phone in the gap is told its WebView is fine before failing
- * anyway, while too high only ever suggests an update that does no harm.
- *
- * A floor, never a gate. A vendor WebView build can differ either way, so the app probes and wraps
- * the engine's real failure rather than letting this number decide anything.
- */
+/** Advice, never a gate: a vendor WebView build can differ either way, so the engine decides. */
 export const MINIMUM_CHROMIUM_FOR_OPFS = 109;
 
 export function webviewLikelyTooOld(): boolean {

package/templates/f7-app/tests/openDatabase.test.ts

@@ -0,0 +1,54 @@
+import { afterEach, expect, test, vi } from "vite-plus/test";
+import { storageChain } from "../src/app/storage.config.js";
+import { closeDatabase, openDatabase } from "../src/shared/database/database.js";
+
+afterEach(async () => {
+  await closeDatabase();
+  vi.restoreAllMocks();
+});
+
+/**
+ * Nothing in this environment can open a database, which is the point: what is under test is how
+ * many times the chain gets walked, not whether it succeeds.
+ *
+ * The guard used to be `if (database) return database` - a value, not a promise - so two callers in
+ * the same tick both walked it. The pool VFSes take their OPFS directory exclusively, so the second
+ * walk collided with the first, retried, failed, and fell through to a slower engine that the app
+ * then reported as its choice.
+ */
+test("concurrent callers share one walk of the chain", async () => {
+  const probes = storageChain.map((candidate) => vi.spyOn(candidate, "probe"));
+
+  const [first, second] = await Promise.allSettled([openDatabase(), openDatabase()]);
+
+  expect(first.status).toBe("rejected");
+  expect(second.status).toBe("rejected");
+
+  for (const [index, probe] of probes.entries()) {
+    expect(probe, storageChain[index]?.id).toHaveBeenCalledTimes(1);
+  }
+});
+
+test("a caller arriving after a failed walk gets a fresh attempt", async () => {
+  await expect(openDatabase()).rejects.toThrow(/No storage engine could open the database/);
+
+  const probes = storageChain.map((candidate) => vi.spyOn(candidate, "probe"));
+  await expect(openDatabase()).rejects.toThrow(/No storage engine could open the database/);
+
+  // Memoising the promise must not memoise the failure: a retry has to be able to try again.
+  for (const probe of probes) expect(probe).toHaveBeenCalledTimes(1);
+});
+
+test("the failure names every candidate and why it was passed over", async () => {
+  const failure = await openDatabase().then(
+    () => null,
+    (error: unknown) => (error instanceof Error ? error.message : String(error)),
+  );
+
+  // "the database would not open" on its own helps nobody: every attempt has to say what happened.
+  expect(failure).toBeTruthy();
+  for (const candidate of storageChain) {
+    expect(failure).toContain(candidate.id);
+  }
+  expect(failure).toContain("unsupported");
+});