@cavulsqa/create 0.1.2 → 2.2.1

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

@@ -69,7 +69,9 @@
     "deleteConfirm": "Delete this order and its lines?",
     "tapHint": "Tap an order to open it.",
     "allOrders": "Recent orders",
-    "matches": "{count} matches"
+    "matches": "{count} matches",
+    "engineSwitch": "One engine everywhere - no bridge to pipeline",
+    "measuredOn": "Measured on {engine}"
   },
   "metrics": {
     "totalQueries": "Queries run",
@@ -112,7 +114,12 @@
     "dialogText": "Dialogs, sheets and toasts all come from Framework7 - no extra dependency.",
     "sheetText": "A sheet modal. The Android back button closes this before it navigates.",
     "aboutText": "Built on {'@'}cavulsqa/mobile-db, reactive-db and reactive-vue. Replace this text with your own.",
-    "footer": "Change these screens in src/modules/settings/."
+    "footer": "Change these screens in src/modules/settings/.",
+    "storage": "Storage",
+    "engine": "Database engine",
+    "engineHint": "Every query reaches SQLite compiled to WebAssembly, against a real file in the Origin Private File System, in a worker - no native bridge. The same engine in a browser as on a phone.",
+    "webview": "WebView",
+    "notDurable": "Storage is not persisted"
   },
   "errors": {
     "notFoundTitle": "Not found",
@@ -175,5 +182,33 @@
     "scrollMe": "Scroll to see the navbar react",
     "row": "Row",
     "next": "Open the next one"
+  },
+  "bench": {
+    "title": "Benchmark",
+    "intro": "Every operation a screen in this app performs, run against the benchmark's own two tables so it never touches your data. Switch engines in Settings and run it again - the second run is compared against the first.",
+    "run": "Run benchmark",
+    "running": "Running",
+    "against": "vs {engine}",
+    "cases": "Cases",
+    "rows": "Rows seeded",
+    "wall": "Wall clock",
+    "worst": "worst",
+    "faster": "{times}x faster here",
+    "slower": "{times}x slower here",
+    "copy": "Copy JSON",
+    "clear": "Clear results",
+    "copied": "Copied",
+    "copyFailed": "Could not reach the clipboard.",
+    "group": {
+      "read": "Reads",
+      "join": "Joins",
+      "write": "Writes",
+      "transaction": "Transactions",
+      "schema": "Schema",
+      "concurrency": "Concurrency",
+      "sync": "Sync strategies"
+    },
+    "pragmas": "PRAGMA {profile}",
+    "seeded": "Dataset built in {ms} ms - later runs reuse it"
   }
 }

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

@@ -69,7 +69,9 @@
     "deleteConfirm": "Supprimer cette commande et ses lignes ?",
     "tapHint": "Touchez une commande pour l'ouvrir.",
     "allOrders": "Commandes récentes",
-    "matches": "{count} résultats"
+    "matches": "{count} résultats",
+    "engineSwitch": "Un seul moteur partout - aucun pont à paralléliser",
+    "measuredOn": "Mesuré sur {engine}"
   },
   "metrics": {
     "totalQueries": "Requêtes exécutées",
@@ -112,7 +114,12 @@
     "dialogText": "Dialogues, feuilles et toasts viennent de Framework7 - sans dépendance supplémentaire.",
     "sheetText": "Une feuille modale. Le bouton retour Android la ferme avant de naviguer.",
     "aboutText": "Construit sur {'@'}cavulsqa/mobile-db, reactive-db et reactive-vue. Remplacez ce texte par le vôtre.",
-    "footer": "Modifiez ces écrans dans src/modules/settings/."
+    "footer": "Modifiez ces écrans dans src/modules/settings/.",
+    "storage": "Stockage",
+    "engine": "Moteur de base de données",
+    "engineHint": "Chaque requête atteint SQLite compilé en WebAssembly, sur un vrai fichier dans l'Origin Private File System, dans un worker - sans pont natif. Le même moteur dans un navigateur que sur un téléphone.",
+    "webview": "WebView",
+    "notDurable": "Le stockage n'est pas persistant"
   },
   "errors": {
     "notFoundTitle": "Introuvable",
@@ -175,5 +182,33 @@
     "scrollMe": "Défilez pour voir la navbar réagir",
     "row": "Ligne",
     "next": "Ouvrir la suivante"
+  },
+  "bench": {
+    "title": "Benchmark",
+    "intro": "Chaque opération qu'un écran de cette application effectue, exécutée sur les deux tables propres au benchmark : vos données ne sont jamais touchées. Changez de moteur dans Réglages et relancez - la seconde exécution est comparée à la première.",
+    "run": "Lancer le benchmark",
+    "running": "En cours",
+    "against": "vs {engine}",
+    "cases": "Cas",
+    "rows": "Lignes créées",
+    "wall": "Durée totale",
+    "worst": "pire",
+    "faster": "{times}x plus rapide ici",
+    "slower": "{times}x plus lent ici",
+    "copy": "Copier le JSON",
+    "clear": "Effacer les résultats",
+    "copied": "Copié",
+    "copyFailed": "Presse-papiers inaccessible.",
+    "group": {
+      "read": "Lectures",
+      "join": "Jointures",
+      "write": "Écritures",
+      "transaction": "Transactions",
+      "schema": "Schéma",
+      "concurrency": "Concurrence",
+      "sync": "Stratégies de synchro"
+    },
+    "pragmas": "PRAGMA {profile}",
+    "seeded": "Jeu de données construit en {ms} ms - réutilisé ensuite"
   }
 }

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

@@ -8,36 +8,26 @@ import "./assets/css/app.css";
 
 import App from "./App.vue";
 import { i18n } from "./plugins/i18n.plugin";
+import { renderBootstrapError } from "./plugins/bootstrapError";
 import { seedPlugin } from "./plugins/seed.plugin";
 import { sqlitePlugin } from "./plugins/sqlite.plugin";
 
 Framework7.use(Framework7Vue);
 
-function reportFatal(error: unknown): void {
-  const message = error instanceof Error ? error.message : String(error);
-  console.error("[bootstrap] the app could not start:", error);
-
-  const root = document.getElementById("app");
-  if (!root) return;
-  const box = document.createElement("div");
-  box.setAttribute("style", "font:14px/1.5 system-ui;padding:24px;color:#b00020");
-  box.textContent = `The app could not start: ${message}`;
-  root.replaceChildren(box);
-}
-
 /**
  * The database opens before mount so the first screen never renders against a missing schema.
  *
- * If it fails, the failure is shown. Awaiting this at the top level of the module and letting it
- * reject renders an empty `#app` with an unhandled rejection nobody reads - which is exactly what
- * this template did the first time it was opened in a browser.
+ * If it fails, `renderBootstrapError` takes the screen: a sentence, what to do about it, a retry
+ * button and the WebView version behind a details toggle. Awaiting this at the top level of the
+ * module and letting it reject renders an empty `#app` with an unhandled rejection nobody reads -
+ * which is exactly what this template did the first time it was opened in a browser.
  */
 async function bootstrap(): Promise<void> {
   try {
     await sqlitePlugin();
     await seedPlugin();
   } catch (error) {
-    reportFatal(error);
+    renderBootstrapError(error);
     return;
   }
 

package/templates/f7-app/src/modules/demo/components/DemoBenchmark.vue

@@ -0,0 +1,112 @@
+<template>
+  <F7BlockTitle>{{ t("bench.title") }}</F7BlockTitle>
+  <F7Block strong inset class="rounded-2xl!">
+    <p class="mt-0 text-sm opacity-70">{{ t("bench.intro") }}</p>
+
+    <div class="mb-3 flex flex-wrap items-center gap-2">
+      <F7Chip :text="engineName" color="teal" outline />
+      <F7Chip v-if="baseline" :text="t('bench.against', { engine: baseline.engine })" outline />
+      <F7Chip :text="t('bench.pragmas', { profile })" color="orange" outline />
+    </div>
+
+    <F7Button fill :disabled="running" @click="run">
+      {{ running ? t("bench.running") : t("bench.run") }}
+    </F7Button>
+
+    <p v-if="running && progress" class="mb-0 mt-2 text-center text-xs opacity-60">
+      {{ progress }}
+    </p>
+
+    <p v-if="failure" class="text-color-red mb-0 mt-2 text-xs">{{ failure }}</p>
+
+    <div v-if="result" class="mt-3 grid grid-cols-3 gap-2 text-center">
+      <div>
+        <div class="text-xs opacity-60">{{ t("bench.cases") }}</div>
+        <div class="font-mono text-base">{{ result.cases.length }}</div>
+      </div>
+      <div>
+        <div class="text-xs opacity-60">{{ t("bench.rows") }}</div>
+        <div class="font-mono text-base">{{ result.rowsSeeded }}</div>
+      </div>
+      <div>
+        <div class="text-xs opacity-60">{{ t("bench.wall") }}</div>
+        <div class="font-mono text-base">{{ Math.round(result.totalMs) }} ms</div>
+      </div>
+    </div>
+  </F7Block>
+
+  <template v-for="group in groups" :key="group">
+    <template v-if="byGroup(group).length">
+      <F7BlockTitle>{{ t(`bench.group.${group}`) }}</F7BlockTitle>
+      <F7List media-list strong inset dividers class="rounded-2xl!">
+        <F7ListItem v-for="entry in byGroup(group)" :key="entry.name" :title="entry.name">
+          <template #after>
+            <span class="font-mono text-sm tabular-nums">
+              {{ entry.current.msPerOperation }} ms
+            </span>
+          </template>
+          <template #subtitle>
+            <span class="text-[13px] tabular-nums opacity-60">
+              {{ entry.current.operations }} ops &middot; p50 {{ entry.current.medianMs }} ms
+              &middot; {{ t("bench.worst") }} {{ entry.current.worstMs }} ms
+            </span>
+          </template>
+          <template #text>
+            <span v-if="entry.speedup" class="text-[13px]" :class="verdictClass(entry.speedup)">
+              {{ speedupText(entry.speedup) }}
+              <span class="opacity-55">({{ entry.other?.msPerOperation }} ms)</span>
+            </span>
+            <span v-else-if="entry.note" class="text-[13px] opacity-55">{{ entry.note }}</span>
+          </template>
+        </F7ListItem>
+      </F7List>
+    </template>
+  </template>
+
+  <F7Block v-if="result" class="flex gap-2">
+    <F7Button outline small class="flex-1" @click="copy">{{ t("bench.copy") }}</F7Button>
+    <F7Button outline small color="red" class="flex-1" @click="clear">
+      {{ t("bench.clear") }}
+    </F7Button>
+  </F7Block>
+</template>
+
+<script setup lang="ts">
+import { pragmaProfile } from "@/app/pragmas.config";
+import { useBenchmark, type CaseComparison } from "@/modules/demo/composables/useBenchmark";
+
+const { t } = useI18n();
+const { engineName, running, progress, failure, result, baseline, comparison, run, clear, asJson } =
+  useBenchmark();
+
+// Part of the measurement, not a detail: two runs under different PRAGMAs are not comparable.
+const profile = pragmaProfile;
+
+const groups = ["read", "join", "write", "transaction", "schema", "concurrency", "sync"] as const;
+
+function byGroup(group: CaseComparison["group"]): CaseComparison[] {
+  return comparison.value.filter((entry) => entry.group === group);
+}
+
+/** Both directions read plainly; "0.4x faster" would not. */
+function speedupText(speedup: number): string {
+  return speedup >= 1
+    ? t("bench.faster", { times: speedup.toFixed(2) })
+    : t("bench.slower", { times: (1 / speedup).toFixed(2) });
+}
+
+function verdictClass(speedup: number): string {
+  if (speedup >= 1.2) return "text-color-green";
+  if (speedup <= 0.83) return "text-color-red";
+  return "opacity-55";
+}
+
+async function copy() {
+  try {
+    await navigator.clipboard.writeText(asJson());
+    f7.toast.create({ text: t("bench.copied"), position: "center", closeTimeout: 1500 }).open();
+  } catch {
+    f7.dialog.alert(t("bench.copyFailed"), t("bench.title"));
+  }
+}
+</script>

package/templates/f7-app/src/modules/demo/components/DemoPipelineBenchmark.vue

@@ -9,6 +9,11 @@
       }}
     </p>
 
+    <div class="mb-3 flex items-center gap-2">
+      <F7Chip :text="engineName" color="teal" outline />
+      <span class="text-[13px] opacity-55">{{ t("demo.engineSwitch") }}</span>
+    </div>
+
     <F7Button fill :disabled="measuring" @click="$emit('measure')">
       {{ measuring ? t("demo.measuring") : t("demo.measure") }}
     </F7Button>
@@ -29,6 +34,10 @@
         </div>
       </div>
 
+      <p class="mb-0 mt-2 text-center text-xs opacity-55">
+        {{ t("demo.measuredOn", { engine: result.engine }) }}
+      </p>
+
       <p class="mb-0 mt-3 text-xs opacity-70">
         {{ isNative ? t("demo.ratioNative") : t("demo.ratioWeb", { platform }) }}
       </p>
@@ -45,6 +54,7 @@ defineProps<{
   readsPerRun: number;
   isNative: boolean;
   platform: string;
+  engineName: string;
 }>();
 defineEmits<{ measure: [] }>();
 

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

@@ -0,0 +1,139 @@
+import {
+  runBenchmark,
+  type CaseResult,
+  type SuiteResult,
+} from "@/domains/benchmark/benchmark.suite";
+import { activePragmas, activeStorage, activeStorageLabel, rdb } from "@/shared/database/database";
+import type { StorageId } from "@/shared/database/candidates";
+
+const STORAGE_KEY = "app.benchmark.results";
+
+export interface CaseComparison {
+  name: string;
+  group: CaseResult["group"];
+  note?: string;
+  current: CaseResult;
+  other?: CaseResult;
+  /** How many times faster the current engine is at this case. Below 1 means slower. */
+  speedup?: number;
+}
+
+/**
+ * Results are kept per engine in localStorage, because the comparison is the point and an engine
+ * switch needs a restart - so the two halves can never be in memory at the same time.
+ */
+function readStored(): Partial<Record<StorageId, SuiteResult>> {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    return raw ? (JSON.parse(raw) as Partial<Record<StorageId, SuiteResult>>) : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeStored(all: Partial<Record<StorageId, SuiteResult>>): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(all));
+  } catch {
+    // Out of quota or storage disabled: the run still displayed, it just will not be remembered.
+  }
+}
+
+export function useBenchmark() {
+  const engine = activeStorage().id;
+  const stored = ref(readStored());
+  const running = ref(false);
+  const progress = ref("");
+  const failure = ref<string | null>(null);
+
+  const result = computed<SuiteResult | null>(() => stored.value[engine] ?? null);
+
+  /** The most recent run on any other engine, which is what the current one is measured against. */
+  const baseline = computed<SuiteResult | null>(() => {
+    const others = Object.entries(stored.value)
+      .filter(([key]) => key !== engine)
+      .map(([, value]) => value)
+      .filter((value): value is SuiteResult => Boolean(value));
+    return others.sort((a, b) => b.at - a.at)[0] ?? null;
+  });
+
+  const comparison = computed<CaseComparison[]>(() => {
+    const current = result.value;
+    if (!current) return [];
+
+    return current.cases.map((entry) => {
+      const other = baseline.value?.cases.find((candidate) => candidate.name === entry.name);
+      const speedup =
+        other && entry.msPerOperation > 0
+          ? Number((other.msPerOperation / entry.msPerOperation).toFixed(2))
+          : undefined;
+      return {
+        name: entry.name,
+        group: entry.group,
+        note: entry.note,
+        current: entry,
+        other,
+        speedup,
+      };
+    });
+  });
+
+  async function run(): Promise<void> {
+    if (running.value) return;
+    running.value = true;
+    failure.value = null;
+    progress.value = "";
+
+    try {
+      /**
+       * Reads take the raw Kysely instance and writes go through `rdb`, exactly as the app does -
+       * measuring a write that skipped the change bus would measure something the app never runs.
+       * The suite's own tables are not watched by any query, so nothing refetches while it runs.
+       */
+      const finished = await runBenchmark(rdb, (name) => {
+        progress.value = name;
+      });
+
+      const next = {
+        ...stored.value,
+        [engine]: {
+          ...finished,
+          engine: activeStorageLabel(),
+          pragmas: activePragmas(),
+          at: Date.now(),
+        },
+      };
+      stored.value = next;
+      writeStored(next);
+    } catch (error) {
+      failure.value = error instanceof Error ? error.message : String(error);
+    } finally {
+      running.value = false;
+      progress.value = "";
+    }
+  }
+
+  function clear(): void {
+    stored.value = {};
+    writeStored({});
+  }
+
+  /** For pasting a run into an issue or a commit message rather than retyping numbers. */
+  function asJson(): string {
+    return JSON.stringify(stored.value, null, 2);
+  }
+
+  return {
+    engine,
+    engineName: activeStorageLabel(),
+    running,
+    progress,
+    failure,
+    result,
+    baseline,
+    comparison,
+    run,
+    clear,
+    asJson,
+  };
+}

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

@@ -14,7 +14,7 @@ import {
   type DraftLine,
   type OrderRow,
 } from "@/domains/sales/sales.repository";
-import { changeBus, getDatabase, rdb } from "@/shared/database/database";
+import { activeStorageLabel, changeBus, getDatabase, rdb } from "@/shared/database/database";
 import { uniqueQueryKey, useReactiveQuery } from "@/shared/database/queries";
 
 export interface BusEntry {
@@ -29,6 +29,8 @@ export interface PipelineResult {
   parallelMs: number;
   sequentialMs: number;
   ratio: number;
+  /** Recorded with the numbers, because a measurement without its engine is not comparable. */
+  engine: string;
 }
 
 const EVENT_LOG_LIMIT = 20;
@@ -140,6 +142,7 @@ export function useReactiveDemo() {
         parallelMs: Number(parallelMs.toFixed(1)),
         sequentialMs: Number(sequentialMs.toFixed(1)),
         ratio: Number((sequentialMs / Math.max(parallelMs, 0.01)).toFixed(2)),
+        engine: activeStorageLabel(),
       };
     } finally {
       measuring.value = false;
@@ -156,6 +159,7 @@ export function useReactiveDemo() {
     measuring,
     readsPerRun: READS_PER_RUN,
     isNative: Capacitor.isNativePlatform(),
+    engineName: activeStorageLabel(),
     platform: Capacitor.getPlatform(),
     seed,
     advance,

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

@@ -9,8 +9,10 @@
 
     <!-- Real Framework7 tabs, so the panes swipe rather than switching on a v-if. -->
     <F7Toolbar tabbar top>
-      <F7Link tab-link="#demo-tab-data" tab-link-active>{{ t("demo.data") }}</F7Link>
-      <F7Link tab-link="#demo-tab-diagnostics">{{ t("demo.diagnostics") }}</F7Link>
+      <F7ToolbarPane>
+        <F7Link tab-link="#demo-tab-data" tab-link-active>{{ t("demo.data") }}</F7Link>
+        <F7Link tab-link="#demo-tab-diagnostics">{{ t("demo.diagnostics") }}</F7Link>
+      </F7ToolbarPane>
     </F7Toolbar>
 
     <F7Tabs swipeable>
@@ -46,8 +48,11 @@
           :reads-per-run="readsPerRun"
           :is-native="isNative"
           :platform="platform"
+          :engine-name="engineName"
           @measure="measurePipelining"
         />
+
+        <DemoBenchmark />
       </F7Tab>
     </F7Tabs>
 
@@ -80,6 +85,7 @@ import type { OrderRow } from "@/domains/sales/sales.repository";
 import DemoBusLog from "@/modules/demo/components/DemoBusLog.vue";
 import DemoCreateOrderSheet from "@/modules/demo/components/DemoCreateOrderSheet.vue";
 import DemoOrderList from "@/modules/demo/components/DemoOrderList.vue";
+import DemoBenchmark from "@/modules/demo/components/DemoBenchmark.vue";
 import DemoPipelineBenchmark from "@/modules/demo/components/DemoPipelineBenchmark.vue";
 import DemoStatCards from "@/modules/demo/components/DemoStatCards.vue";
 import { useReactiveDemo } from "@/modules/demo/composables/useReactiveDemo";
@@ -101,6 +107,7 @@ const {
   readsPerRun,
   isNative,
   platform,
+  engineName,
   seed,
   advance,
   remove,

package/templates/f7-app/src/modules/settings/views/SettingsView.vue

@@ -38,6 +38,23 @@
       </F7ListItem>
     </F7List>
 
+    <F7BlockTitle>{{ t("settings.storage") }}</F7BlockTitle>
+    <F7List strong inset dividers class="rounded-2xl!">
+      <F7ListItem :title="t('settings.engine')" :after="storage">
+        <template #media><F7Icon f7="archivebox_fill" color="teal" /></template>
+      </F7ListItem>
+      <F7ListItem v-if="!durable" :title="t('settings.notDurable')">
+        <template #media><F7Icon f7="exclamationmark_triangle_fill" color="red" /></template>
+        <template #footer>{{ tradeoff }}</template>
+      </F7ListItem>
+      <F7ListItem v-for="skip in skipped" :key="skip.id" :title="skip.id" :footer="skip.detail">
+        <template #media><F7Icon f7="arrow_turn_down_right" color="gray" /></template>
+      </F7ListItem>
+    </F7List>
+    <F7Block class="mt-0!">
+      <p class="m-0 text-[13px] opacity-60">{{ t("settings.engineHint") }}</p>
+    </F7Block>
+
     <F7BlockTitle>{{ t("settings.tryIt") }}</F7BlockTitle>
     <F7List strong inset dividers class="rounded-2xl!">
       <F7ListItem :title="t('settings.testToast')" link="#" @click="testToast">
@@ -62,6 +79,9 @@
       <F7ListItem :title="t('settings.platform')" :after="platform">
         <template #media><F7Icon f7="device_phone_portrait" color="purple" /></template>
       </F7ListItem>
+      <F7ListItem :title="t('settings.webview')" :after="webview">
+        <template #media><F7Icon f7="globe" color="teal" /></template>
+      </F7ListItem>
       <F7ListItem :title="t('settings.aboutUs')" link="#" @click="showAbout">
         <template #media><F7Icon f7="info_circle_fill" color="blue" /></template>
       </F7ListItem>
@@ -76,6 +96,8 @@
 <script setup lang="ts">
 import { Capacitor } from "@capacitor/core";
 import { useAppTheme, type AppMode, type AppTheme } from "@/shared/composables/theme/useAppTheme";
+import { activeStorage, activeStorageLabel, storageAttempts } from "@/shared/database/database";
+import { webviewVersion } from "@/shared/database/storage";
 
 const { t, locale, availableLocales } = useI18n();
 const theme = useAppTheme();
@@ -85,6 +107,15 @@ const appName = __APP_NAME__;
 const appVersion = __APP_VERSION__;
 const platform = Capacitor.getPlatform();
 
+const storage = activeStorageLabel();
+const durable = activeStorage().durable;
+const tradeoff = activeStorage().tradeoff;
+// Which candidates the chain passed over, so a fallback is never something you discover later.
+const skipped = storageAttempts().filter((attempt) => attempt.outcome !== "opened");
+// The number that decides whether local storage works at all, and the OS version does not imply it.
+const chromium = webviewVersion();
+const webview = chromium === null ? "unknown" : `Chromium ${String(chromium)}`;
+
 function onThemeChange(event: Event) {
   appTheme.value.setTheme((event.target as HTMLSelectElement).value as AppTheme);
 }

package/templates/f7-app/src/plugins/bootstrapError.ts

@@ -0,0 +1,60 @@
+import {
+  MINIMUM_CHROMIUM_FOR_OPFS,
+  webviewLikelyTooOld,
+  webviewVersion,
+} from "@/shared/database/storage";
+
+/**
+ * The screen shown when the app cannot start, which in practice means the database did not open.
+ *
+ * Deliberately framework-free. Mounting the app to report the failure would run screens that assume
+ * a working database, so a second failure would replace the first and the person would learn
+ * nothing. Plain DOM cannot fail for the same reason twice.
+ *
+ * It replaces a red sentence in a bare div, which is what shipped before and told a field user
+ * nothing they could act on.
+ */
+export function renderBootstrapError(error: unknown): void {
+  const root = document.getElementById("app");
+  if (!root) return;
+
+  const message = error instanceof Error ? error.message : String(error);
+  const detail = error instanceof Error ? (error.stack ?? error.message) : String(error);
+  const version = webviewVersion();
+
+  const advice = webviewLikelyTooOld()
+    ? `This WebView is Chromium ${String(version)}. The app needs ${String(MINIMUM_CHROMIUM_FOR_OPFS)} or newer for local storage. Update Android System WebView in the Play Store - it updates separately from Android itself.`
+    : "Closing the app completely and opening it again usually clears this. Your data has not been deleted.";
+
+  root.replaceChildren();
+  root.insertAdjacentHTML(
+    "afterbegin",
+    `<div style="font:15px/1.55 system-ui,-apple-system,sans-serif;padding:28px 22px;max-width:38rem;margin:0 auto;color:#1c1c1e">
+      <div style="font-size:34px;line-height:1">&#9888;&#65039;</div>
+      <h1 style="font-size:19px;margin:14px 0 6px">The app could not start</h1>
+      <p style="margin:0 0 14px;color:#3a3a3c">${escapeHtml(message)}</p>
+      <p style="margin:0 0 20px;color:#3a3a3c">${escapeHtml(advice)}</p>
+      <button id="bootstrap-retry" style="appearance:none;border:0;border-radius:10px;background:#e2622a;color:#fff;font:600 15px system-ui;padding:12px 20px;width:100%">
+        Try again
+      </button>
+      <details style="margin-top:20px;color:#6c6c70">
+        <summary style="cursor:pointer;font-size:13px">Technical details</summary>
+        <p style="font-size:12px;margin:8px 0 0">WebView: Chromium ${version === null ? "unknown" : String(version)}</p>
+        <pre style="font-size:11px;white-space:pre-wrap;word-break:break-word;margin:8px 0 0">${escapeHtml(detail)}</pre>
+      </details>
+    </div>`,
+  );
+
+  document.getElementById("bootstrap-retry")?.addEventListener("click", () => {
+    window.location.reload();
+  });
+}
+
+/** The message can carry an engine's own text, and that text is not trusted markup. */
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}

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

@@ -0,0 +1,3 @@
+export * from "./types";
+export { opfsSahPool } from "./opfsSahPool";
+export { waAccessHandlePool, waIdbBatchAtomic, waOriginPrivateFileSystem } from "./waSqlite";

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

@@ -0,0 +1,25 @@
+import { OpfsSQLiteDialect } from "@cavulsqa/mobile-db/opfs";
+import OpfsWorker from "../opfs.worker?worker";
+import { probeOpfsCapable } from "../storage";
+import type { StorageCandidate } from "./types";
+
+/**
+ * Official `@sqlite.org/sqlite-wasm`, `opfs-sahpool` VFS, in a worker.
+ *
+ * The fastest thing measured on a real phone: reads 2.5-5.5x and batched writes ~9x against the
+ * Capacitor bridge, with much tighter worst cases. The SAH pool is chosen over the plain `opfs` VFS
+ * because it needs neither SharedArrayBuffer nor cross-origin isolation, and a Capacitor WebView
+ * cannot easily be given COOP/COEP headers.
+ */
+export const opfsSahPool: StorageCandidate = {
+  id: "sqlite-wasm-opfs-sahpool",
+  label: "SQLite WASM · OPFS sync access handle pool",
+  tradeoff:
+    "One connection per directory, taken exclusively - a stale handle blocks the open. The worker " +
+    "is serial, so a read waits behind an in-flight write.",
+  durable: true,
+  evidence: "measured",
+  probe: probeOpfsCapable,
+  createDialect: () =>
+    Promise.resolve(new OpfsSQLiteDialect({ worker: new OpfsWorker(), name: "app.sqlite3" })),
+};