@cavulsqa/create 2.9.2 → 2.10.0

package/README.md

@@ -29,7 +29,7 @@ pnpm create @cavulsqa --name caputa --app-id com.example.caputa --yes
 | flag         | default          |                                                         |
 | ------------ | ---------------- | ------------------------------------------------------- |
 | `--name`     | asked            | package and directory name                              |
-| `--template` | the only one     | which bundled template                                  |
+| `--template` | `f7-app`         | `f7-app` or `m3e-app`; asked from a numbered menu       |
 | `--dir`      | `./<name>`       | where to write it                                       |
 | `--app-name` | `Name`           | launcher name, window title, Settings screen            |
 | `--app-id`   | `com.ayb.<name>` | Android application id                                  |
@@ -40,6 +40,13 @@ pnpm create @cavulsqa --name caputa --app-id com.example.caputa --yes
 
 ## What you get
 
+Two templates, one data layer:
+
+| Template  | Look and feel                                                                                                                                                                                                                                       |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `f7-app`  | Framework7's own components, native on iOS and on Material (`theme: auto`)                                                                                                                                                                          |
+| `m3e-app` | Material 3 Expressive: `@cavulsqa/m3e-vue` components on 2025 dynamic colour, Google Sans Flex, spring motion, a colour studio and a component gallery. Framework7 stays underneath as the navigation engine only, so it is Android-first by design |
+
 The `f7-app` template: a tabbed shell, a `domains` / `modules` / `shared` layout, and a working
 sales demo over a six-table schema — dashboard aggregates, search, an order sheet, swipe actions,
 a detail screen — with tests against real SQLite.
@@ -49,6 +56,10 @@ under Kysely, `@cavulsqa/reactive-db` for the change bus, and `@cavulsqa/reactiv
 `useReactiveQuery`. A write announces the tables it touched and every query watching them refetches;
 nothing in a screen asks for a refresh.
 
+`m3e-app` has the same layout and data layer, with every screen built from `M3*` components and an
+`m3-expressive` skill that carries the design system: which component, which colour role, which
+spring, and a link to the spec page for each.
+
 `CLAUDE.md`, `.claude/rules/` and `.claude/skills/` come with it, so an agent opening the generated
 repository knows the architecture, the conventions, and the traps that have already cost someone a
 day.

package/bin/create.mjs

@@ -7,11 +7,17 @@
  * silent default, because a generated app named "my-app" in the wrong directory is worse than a
  * failed command.
  */
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { scaffold } from "../lib/scaffold.mjs";
+import {
+  defaultTemplate,
+  listTemplates,
+  resolveTemplateChoice,
+  templateMenu,
+} from "../lib/templates.mjs";
 
 const PACKAGE = dirname(dirname(fileURLToPath(import.meta.url)));
 const BUNDLED = join(PACKAGE, "templates");
@@ -38,7 +44,7 @@ function usage() {
 
 Options:
   --name NAME          package and directory name
-  --template NAME      which template (default: the only one, or you are asked)
+  --template NAME      which template (default: the manifest's default, or you are asked)
   --dir PATH           where to write it (default: ./<name>)
   --app-name NAME      launcher name and window title (default: Name)
   --app-id ID          android application id (default: com.ayb.<name>)
@@ -49,24 +55,7 @@ Options:
   --help               this
 
 Templates bundled in this package:
-${listTemplates()
-  .map((entry) => `  ${entry.name}  ${entry.description}`)
-  .join("\n")}`);
-}
-
-function listTemplates() {
-  const manifest = JSON.parse(readFileSync(join(PACKAGE, "package.json"), "utf8"));
-  const declared = manifest.createConfig?.templates ?? [];
-  if (!existsSync(BUNDLED)) return declared;
-
-  // 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, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => ({
-      name: entry.name,
-      description: declared.find((listed) => listed.name === entry.name)?.description ?? "",
-    }));
+${templateMenu(listTemplates(PACKAGE))}`);
 }
 
 /**
@@ -109,15 +98,19 @@ async function main() {
       throw new Error(`"${String(name)}" is not a usable package name`);
     }
 
-    const templates = listTemplates();
+    const templates = listTemplates(PACKAGE);
     if (!templates.length) throw new Error("this build of @cavulsqa/create bundles no templates");
 
     let template = flags.get("template");
     if (typeof template !== "string") {
-      template =
-        templates.length === 1
-          ? templates[0].name
-          : await ask(`Template [${templates.map((t) => t.name).join(", ")}]`, templates[0].name);
+      const fallback = defaultTemplate(templates);
+      if (templates.length === 1 || !rl) {
+        template = fallback.name;
+      } else {
+        console.log(`\nTemplates:\n${templateMenu(templates)}\n`);
+        const answer = await ask("Template", String(templates.indexOf(fallback) + 1));
+        template = resolveTemplateChoice(answer, templates) ?? answer;
+      }
     }
     if (!templates.some((entry) => entry.name === template)) {
       throw new Error(

package/lib/templates.mjs

@@ -0,0 +1,56 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * The templates this build offers, in the manifest's order, with the manifest's descriptions.
+ *
+ * The manifest is what `vp create` reads; the directory is what actually shipped. A template is
+ * offered only when both agree, and a shipped directory the manifest forgot still appears - last,
+ * without a description - rather than silently vanishing.
+ */
+export function listTemplates(packageDir) {
+  const manifest = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8"));
+  const declared = manifest.createConfig?.templates ?? [];
+  const bundled = join(packageDir, "templates");
+  if (!existsSync(bundled)) return declared.map(toEntry);
+
+  const shipped = new Set(
+    readdirSync(bundled, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name),
+  );
+  const listed = declared.filter((entry) => shipped.has(entry.name)).map(toEntry);
+  const unlisted = [...shipped]
+    .filter((name) => !declared.some((entry) => entry.name === name))
+    .sort((a, b) => a.localeCompare(b))
+    .map((name) => toEntry({ name }));
+  return [...listed, ...unlisted];
+}
+
+function toEntry(entry) {
+  return {
+    name: entry.name,
+    description: entry.description ?? "",
+    isDefault: entry.default === true,
+  };
+}
+
+/** The one marked `default` in the manifest, else the first - never whatever readdir returns first. */
+export function defaultTemplate(templates) {
+  return templates.find((entry) => entry.isDefault) ?? templates[0];
+}
+
+/** A typed answer as a template: its number in the list, or its name. Null when it is neither. */
+export function resolveTemplateChoice(answer, templates) {
+  const value = String(answer).trim();
+  if (/^\d+$/.test(value)) return templates[Number(value) - 1]?.name ?? null;
+  return templates.some((entry) => entry.name === value) ? value : null;
+}
+
+/** The numbered menu the interactive prompt prints. */
+export function templateMenu(templates) {
+  const width = Math.max(...templates.map((entry) => entry.name.length));
+  return templates
+    .map((entry, index) => `  ${index + 1}) ${entry.name.padEnd(width)}  ${entry.description}`)
+    .join("\n");
+}

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@cavulsqa/create",
-  "version": "2.9.2",
-  "description": "Create a Vue + Framework7 + Capacitor + SQLite app from the cavulsqa templates.",
+  "version": "2.10.0",
+  "description": "Create a Vue + Capacitor + SQLite app from the cavulsqa templates: Framework7 (iOS and Material) or Material 3 Expressive.",
   "keywords": [
     "capacitor",
     "create",
     "framework7",
+    "material-3",
+    "material-expressive",
     "scaffold",
     "sqlite",
     "template",
@@ -47,12 +49,18 @@
     "templates": [
       {
         "name": "f7-app",
-        "description": "Vue 3 + Framework7 + Capacitor + SQLite, tabbed shell, offline-first data layer",
-        "template": "./templates/f7-app"
+        "description": "Vue 3 + Framework7 + Capacitor + SQLite, tabbed shell, iOS and Material themes, offline-first data layer",
+        "template": "./templates/f7-app",
+        "default": true
+      },
+      {
+        "name": "m3e-app",
+        "description": "Material 3 Expressive: m3e-vue components, 2025 dynamic colour with a colour studio, adaptive bar/rail shell, offline-first data layer",
+        "template": "./templates/m3e-app"
       }
     ]
   },
-  "templatesFingerprint": "sha256-w5ItqHFEFJCJwe7V3W0FEhJf7foJkanjYLY85j/Wbd8=",
+  "templatesFingerprint": "sha256-3YSsClBPuShazZVtnS9LabHQ330E0wPZiedhN6vIadU=",
   "scripts": {
     "build": "node scripts/bundleTemplates.mjs",
     "check": "vp check",

package/templates/f7-app/CLAUDE.md

@@ -71,6 +71,9 @@ The short version of the rules, each earned by a real bug:
   kysely reports `no result`. See `.claude/rules/database.md`.
 - **Money is integer cents.** A float total is a rounding bug waiting to happen.
 - **`f7route` and `f7router` are props**, not imports: `defineProps<{ f7route: Router.Route }>()`.
+- **A route loads its component through `lazyRoute`**, never a bare `import().then(resolve)`.
+  Framework7 locks the router before calling the hook and only unlocks it from `resolve` or
+  `reject`; a hook that settles neither — one failed chunk — freezes that view for the session.
 - **In locale files, `@` and `|` are message syntax.** `@` starts a linked message and `|` a plural
   branch. A literal `@` must be `{'@'}` or the whole locale file fails to compile.
 - **No comments that narrate.** A comment explains a non-obvious _why_ — a platform quirk, an

package/templates/f7-app/auto-imports.d.ts

@@ -58,12 +58,14 @@ declare global {
   const initCapacitor: typeof import('./src/plugins/capacitor/index').initCapacitor
   const inject: typeof import('vue').inject
   const injectLocal: typeof import('@vueuse/core').injectLocal
+  const installNavigationGuard: typeof import('./src/shared/composables/useNavigationGuard').installNavigationGuard
   const isDefined: typeof import('@vueuse/core').isDefined
   const isProxy: typeof import('vue').isProxy
   const isReactive: typeof import('vue').isReactive
   const isReadonly: typeof import('vue').isReadonly
   const isRef: typeof import('vue').isRef
   const isShallow: typeof import('vue').isShallow
+  const lazyRoute: typeof import('./src/shared/utils/lazyRoute').lazyRoute
   const makeDestructurable: typeof import('@vueuse/core').makeDestructurable
   const markRaw: typeof import('vue').markRaw
   const nextTick: typeof import('vue').nextTick
@@ -96,6 +98,8 @@ declare global {
   const reactiveOmit: typeof import('@vueuse/core').reactiveOmit
   const reactivePick: typeof import('@vueuse/core').reactivePick
   const readonly: typeof import('vue').readonly
+  const recorderDiagnostics: typeof import('./src/plugins/recorder.plugin').recorderDiagnostics
+  const recorderPlugin: typeof import('./src/plugins/recorder.plugin').recorderPlugin
   const ref: typeof import('vue').ref
   const refAutoReset: typeof import('@vueuse/core').refAutoReset
   const refDebounced: typeof import('@vueuse/core').refDebounced
@@ -104,6 +108,7 @@ declare global {
   const refThrottled: typeof import('@vueuse/core').refThrottled
   const refWithControl: typeof import('@vueuse/core').refWithControl
   const renderBootstrapError: typeof import('./src/plugins/bootstrapError').renderBootstrapError
+  const reportProblem: typeof import('./src/plugins/recorder.plugin').reportProblem
   const request: typeof import('framework7/lite').request
   const resolveComponent: typeof import('vue').resolveComponent
   const seedPlugin: typeof import('./src/plugins/seed.plugin').seedPlugin
@@ -230,6 +235,7 @@ declare global {
   const useMouseInElement: typeof import('@vueuse/core').useMouseInElement
   const useMousePressed: typeof import('@vueuse/core').useMousePressed
   const useMutationObserver: typeof import('@vueuse/core').useMutationObserver
+  const useNavigationGuard: typeof import('./src/shared/composables/useNavigationGuard').useNavigationGuard
   const useNavigatorLanguage: typeof import('@vueuse/core').useNavigatorLanguage
   const useNetwork: typeof import('@vueuse/core').useNetwork
   const useNow: typeof import('@vueuse/core').useNow
@@ -338,6 +344,9 @@ declare global {
   export type { TabbarVisibility } from './src/shared/composables/useTabbarVisibility'
   import('./src/shared/composables/useTabbarVisibility')
   // @ts-ignore
+  export type { RecorderBackend, RecorderDiagnostics } from './src/plugins/recorder.plugin'
+  import('./src/plugins/recorder.plugin')
+  // @ts-ignore
   export type { CaseComparison } from './src/modules/demo/composables/useBenchmark'
   import('./src/modules/demo/composables/useBenchmark')
   // @ts-ignore
@@ -403,12 +412,14 @@ declare module 'vue' {
     readonly initCapacitor: UnwrapRef<typeof import('./src/plugins/capacitor/index')['initCapacitor']>
     readonly inject: UnwrapRef<typeof import('vue')['inject']>
     readonly injectLocal: UnwrapRef<typeof import('@vueuse/core')['injectLocal']>
+    readonly installNavigationGuard: UnwrapRef<typeof import('./src/shared/composables/useNavigationGuard')['installNavigationGuard']>
     readonly isDefined: UnwrapRef<typeof import('@vueuse/core')['isDefined']>
     readonly isProxy: UnwrapRef<typeof import('vue')['isProxy']>
     readonly isReactive: UnwrapRef<typeof import('vue')['isReactive']>
     readonly isReadonly: UnwrapRef<typeof import('vue')['isReadonly']>
     readonly isRef: UnwrapRef<typeof import('vue')['isRef']>
     readonly isShallow: UnwrapRef<typeof import('vue')['isShallow']>
+    readonly lazyRoute: UnwrapRef<typeof import('./src/shared/utils/lazyRoute')['lazyRoute']>
     readonly makeDestructurable: UnwrapRef<typeof import('@vueuse/core')['makeDestructurable']>
     readonly markRaw: UnwrapRef<typeof import('vue')['markRaw']>
     readonly nextTick: UnwrapRef<typeof import('vue')['nextTick']>
@@ -441,6 +452,8 @@ declare module 'vue' {
     readonly reactiveOmit: UnwrapRef<typeof import('@vueuse/core')['reactiveOmit']>
     readonly reactivePick: UnwrapRef<typeof import('@vueuse/core')['reactivePick']>
     readonly readonly: UnwrapRef<typeof import('vue')['readonly']>
+    readonly recorderDiagnostics: UnwrapRef<typeof import('./src/plugins/recorder.plugin')['recorderDiagnostics']>
+    readonly recorderPlugin: UnwrapRef<typeof import('./src/plugins/recorder.plugin')['recorderPlugin']>
     readonly ref: UnwrapRef<typeof import('vue')['ref']>
     readonly refAutoReset: UnwrapRef<typeof import('@vueuse/core')['refAutoReset']>
     readonly refDebounced: UnwrapRef<typeof import('@vueuse/core')['refDebounced']>
@@ -449,6 +462,7 @@ declare module 'vue' {
     readonly refThrottled: UnwrapRef<typeof import('@vueuse/core')['refThrottled']>
     readonly refWithControl: UnwrapRef<typeof import('@vueuse/core')['refWithControl']>
     readonly renderBootstrapError: UnwrapRef<typeof import('./src/plugins/bootstrapError')['renderBootstrapError']>
+    readonly reportProblem: UnwrapRef<typeof import('./src/plugins/recorder.plugin')['reportProblem']>
     readonly request: UnwrapRef<typeof import('framework7/lite')['request']>
     readonly resolveComponent: UnwrapRef<typeof import('vue')['resolveComponent']>
     readonly seedPlugin: UnwrapRef<typeof import('./src/plugins/seed.plugin')['seedPlugin']>
@@ -575,6 +589,7 @@ declare module 'vue' {
     readonly useMouseInElement: UnwrapRef<typeof import('@vueuse/core')['useMouseInElement']>
     readonly useMousePressed: UnwrapRef<typeof import('@vueuse/core')['useMousePressed']>
     readonly useMutationObserver: UnwrapRef<typeof import('@vueuse/core')['useMutationObserver']>
+    readonly useNavigationGuard: UnwrapRef<typeof import('./src/shared/composables/useNavigationGuard')['useNavigationGuard']>
     readonly useNavigatorLanguage: UnwrapRef<typeof import('@vueuse/core')['useNavigatorLanguage']>
     readonly useNetwork: UnwrapRef<typeof import('@vueuse/core')['useNetwork']>
     readonly useNow: UnwrapRef<typeof import('@vueuse/core')['useNow']>

package/templates/f7-app/package.json

@@ -16,13 +16,16 @@
     "@capacitor/android": "^8.5.0",
     "@capacitor/app": "^8.0.0",
     "@capacitor/core": "^8.0.0",
+    "@capacitor/filesystem": "^8.0.0",
     "@capacitor/keyboard": "^8.0.0",
     "@capacitor/preferences": "^8.0.0",
+    "@capacitor/share": "^8.0.0",
     "@capacitor/splash-screen": "^8.0.0",
     "@capacitor/status-bar": "^8.0.0",
-    "@cavulsqa/mobile-db": "^1.2.0",
-    "@cavulsqa/reactive-db": "^1.2.0",
-    "@cavulsqa/reactive-vue": "^1.2.0",
+    "@cavulsqa/mobile-db": "^1.4.0",
+    "@cavulsqa/reactive-db": "^1.4.0",
+    "@cavulsqa/reactive-vue": "^1.4.0",
+    "@cavulsqa/recorder": "^1.4.0",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@tailwindcss/vite": "^4.3.3",
     "@vueuse/core": "^14.4.0",

package/templates/f7-app/src/App.vue

@@ -57,6 +57,7 @@ const parameters = framework7Parameters(appTheme.value.theme, appTheme.value.dar
 onMounted(() => {
   // The native handlers need the Framework7 instance, which exists only once the shell is mounted.
   f7ready(async (instance) => {
+    useNavigationGuard();
     await initCapacitor(instance);
     hideSplashScreen();
   });

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

@@ -35,6 +35,7 @@ declare const __APP_VERSION__: string;
 interface ImportMetaEnv {
   readonly VITE_STORAGE_ENGINE?: string;
   readonly VITE_PRAGMA_PROFILE?: "safe" | "fast";
+  readonly VITE_FIELD_RECORDER?: "on" | "off";
 }
 
 interface ImportMeta {

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

@@ -9,6 +9,7 @@ import "./assets/css/app.css";
 import App from "./App.vue";
 import { i18n } from "./plugins/i18n.plugin";
 import { renderBootstrapError } from "./plugins/bootstrapError";
+import { recorderPlugin } from "./plugins/recorder.plugin";
 import { seedPlugin } from "./plugins/seed.plugin";
 import { sqlitePlugin } from "./plugins/sqlite.plugin";
 
@@ -31,6 +32,8 @@ async function bootstrap(): Promise<void> {
     return;
   }
 
+  void recorderPlugin();
+
   // Components arrive through Framework7VueResolver, so nothing is registered by hand.
   const app = createApp(App);
   app.use(i18n);

package/templates/f7-app/src/modules/demo/router/routes/demo.routes.ts

@@ -1,33 +1,21 @@
 import type { Router } from "framework7/types";
+import { lazyRoute } from "@/shared/utils/lazyRoute";
 
 const demoRoutes: Router.RouteParameters[] = [
   {
     name: "demo",
     path: "/demo/",
-    // `async` is Framework7's route hook, not an async function - resolve from the promise.
-    async({ resolve }) {
-      void import("@/modules/demo/views/DemoView.vue").then((view) => {
-        resolve({ component: view.default });
-      });
-    },
+    async: lazyRoute(() => import("@/modules/demo/views/DemoView.vue")),
   },
   {
     name: "demo-search",
     path: "/demo/search/",
-    async({ resolve }) {
-      void import("@/modules/demo/views/OrderSearchView.vue").then((view) => {
-        resolve({ component: view.default });
-      });
-    },
+    async: lazyRoute(() => import("@/modules/demo/views/OrderSearchView.vue")),
   },
   {
     name: "demo-order",
     path: "/demo/order/:id/",
-    async({ resolve }) {
-      void import("@/modules/demo/views/OrderDetailView.vue").then((view) => {
-        resolve({ component: view.default });
-      });
-    },
+    async: lazyRoute(() => import("@/modules/demo/views/OrderDetailView.vue")),
   },
 ];
 

package/templates/f7-app/src/modules/home/router/routes/home.routes.ts

@@ -1,4 +1,5 @@
 import type { Router } from "framework7/types";
+import { lazyRoute } from "@/shared/utils/lazyRoute";
 
 /**
  * The detail route is a child of the tab's own view, which is what keeps the tab bar in place and
@@ -8,21 +9,12 @@ const homeRoutes: Router.RouteParameters[] = [
   {
     name: "home",
     path: "/home/",
-    // `async` is Framework7's route hook, not an async function - resolve from the promise.
-    async({ resolve }) {
-      void import("@/modules/home/views/HomeView.vue").then((view) => {
-        resolve({ component: view.default });
-      });
-    },
+    async: lazyRoute(() => import("@/modules/home/views/HomeView.vue")),
   },
   {
     name: "home-feature",
     path: "/home/feature/:id/",
-    async({ resolve }) {
-      void import("@/modules/home/views/FeatureDetailView.vue").then((view) => {
-        resolve({ component: view.default });
-      });
-    },
+    async: lazyRoute(() => import("@/modules/home/views/FeatureDetailView.vue")),
   },
 ];
 

package/templates/f7-app/src/modules/settings/router/routes/settings.routes.ts

@@ -1,15 +1,11 @@
 import type { Router } from "framework7/types";
+import { lazyRoute } from "@/shared/utils/lazyRoute";
 
 const settingsRoutes: Router.RouteParameters[] = [
   {
     name: "settings",
     path: "/settings/",
-    // `async` is Framework7's route hook, not an async function - resolve from the promise.
-    async({ resolve }) {
-      void import("@/modules/settings/views/SettingsView.vue").then((view) => {
-        resolve({ component: view.default });
-      });
-    },
+    async: lazyRoute(() => import("@/modules/settings/views/SettingsView.vue")),
   },
 ];
 

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

@@ -3,6 +3,7 @@ import {
   webviewLikelyTooOld,
   webviewVersion,
 } from "@/shared/database/storage";
+import { hideSplashScreen } from "@/plugins/capacitor/useSplashScreen";
 
 /**
  * The screen shown when the app cannot start, which in practice means the database did not open.
@@ -15,6 +16,7 @@ import {
  * nothing they could act on.
  */
 export function renderBootstrapError(error: unknown): void {
+  hideSplashScreen();
   const root = document.getElementById("app");
   if (!root) return;
 

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

@@ -0,0 +1,155 @@
+import {
+  createConsoleTrack,
+  createDatabasesTrack,
+  createNetworkTrack,
+  createPerfTrack,
+  createRecorder,
+  createRrwebTrack,
+  type Recorder,
+  type TrackContext,
+  type TrackRecorder,
+} from "@cavulsqa/recorder";
+import { changeBus } from "@/shared/database/database";
+import { createCapacitorSink } from "@/shared/recorder/capacitorSink";
+
+const RRWEB_VERIFY_WINDOW_MS = 2000;
+
+export type RecorderBackend = "memory" | "opfs" | null;
+
+export interface RecorderDiagnostics {
+  enabled: boolean;
+  recording: boolean;
+  backend: RecorderBackend;
+  rrwebAvailable: boolean;
+  lastError: string | null;
+}
+
+export const recorderDiagnostics = ref<RecorderDiagnostics>({
+  enabled: false,
+  recording: false,
+  backend: null,
+  rrwebAvailable: true,
+  lastError: null,
+});
+
+let recorder: Recorder | null = null;
+
+function resolveFieldRecorderMode(): "on" | "off" {
+  const raw = import.meta.env.VITE_FIELD_RECORDER;
+  if (raw === "on" || raw === "off") return raw;
+  return import.meta.env.DEV ? "on" : "off";
+}
+
+function isCapuError(data: unknown): boolean {
+  return typeof data === "object" && data !== null && "__capuError" in data;
+}
+
+/**
+ * Wraps `createRrwebTrack` with a runtime check: rrweb's published package resolves to an empty
+ * module outside a bundler, and a `record()` call against that module fails silently inside the
+ * track's own try/catch, so the recorder would otherwise report a healthy `rrweb` track that never
+ * emitted a frame. This watches the first events pushed and flips `rrwebAvailable` to `false` if
+ * nothing but a `__capuError` payload arrives within {@link RRWEB_VERIFY_WINDOW_MS}.
+ */
+function createVerifiedRrwebTrack(): TrackRecorder {
+  const inner = createRrwebTrack();
+  let sawRealFrame = false;
+
+  return {
+    name: "rrweb",
+    async start(ctx: TrackContext<unknown>) {
+      const wrapped: TrackContext<unknown> = {
+        ...ctx,
+        push(data, wallMs) {
+          if (!sawRealFrame && !isCapuError(data)) sawRealFrame = true;
+          ctx.push(data, wallMs);
+        },
+      };
+      await inner.start(wrapped);
+      setTimeout(() => {
+        recorderDiagnostics.value = { ...recorderDiagnostics.value, rrwebAvailable: sawRealFrame };
+        if (!sawRealFrame) {
+          console.error(
+            "[recorder] rrweb produced no frames; recording is running without screen replay.",
+          );
+        }
+      }, RRWEB_VERIFY_WINDOW_MS);
+    },
+    async stop() {
+      await inner.stop();
+    },
+  };
+}
+
+function buildTracks(): TrackRecorder[] {
+  return [
+    createVerifiedRrwebTrack(),
+    createConsoleTrack(),
+    createNetworkTrack(),
+    createPerfTrack(),
+    createDatabasesTrack({ changeBus }),
+  ];
+}
+
+function syncDiagnostics(): void {
+  if (!recorder) return;
+  const status = recorder.status;
+  recorderDiagnostics.value = {
+    ...recorderDiagnostics.value,
+    recording: status.recording,
+    backend: status.backend,
+    lastError: status.lastError,
+  };
+}
+
+/**
+ * Builds and starts the field recorder, gated by `VITE_FIELD_RECORDER` (`"on"` or `"off"`,
+ * defaulting to `on` in dev and `off` in a production build). Recovers a leftover session from a
+ * previous run before starting a new one. Never throws: every failure lands in
+ * {@link recorderDiagnostics}.`lastError` instead, so a broken recorder can never block `main.ts`
+ * from mounting the app.
+ */
+export async function recorderPlugin(): Promise<void> {
+  const mode = resolveFieldRecorderMode();
+  recorderDiagnostics.value = { ...recorderDiagnostics.value, enabled: mode === "on" };
+  if (mode === "off") return;
+
+  try {
+    recorder = createRecorder({
+      tracks: buildTracks(),
+      sink: createCapacitorSink(),
+      label: "field recording",
+      appId: __APP_NAME__,
+      appVersion: __APP_VERSION__,
+    });
+
+    await recorder.recover();
+    await recorder.start();
+    syncDiagnostics();
+  } catch (error) {
+    recorderDiagnostics.value = {
+      ...recorderDiagnostics.value,
+      lastError: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Finalizes the current buffer into a `.capu` and hands it to the sink without stopping the
+ * recorder, for the Settings "Report a problem" action. Returns `true` when the capture reached
+ * the sink with no error.
+ */
+export async function reportProblem(): Promise<boolean> {
+  if (!recorder) return false;
+  try {
+    await recorder.capture("user report");
+  } catch (error) {
+    recorderDiagnostics.value = {
+      ...recorderDiagnostics.value,
+      lastError: error instanceof Error ? error.message : String(error),
+    };
+    return false;
+  }
+  syncDiagnostics();
+  return recorderDiagnostics.value.lastError === null;
+}

package/templates/f7-app/src/router/global/global.routes.ts

@@ -1,15 +1,11 @@
 import type { Router } from "framework7/types";
+import { lazyRoute } from "@/shared/utils/lazyRoute";
 
 const globalRoutes: Router.RouteParameters[] = [
   {
     name: "not-found",
     path: "(.*)",
-    // `async` is Framework7's route hook, not an async function - resolve from the promise.
-    async({ resolve }) {
-      void import("@/shared/components/error/404.vue").then((view) => {
-        resolve({ component: view.default });
-      });
-    },
+    async: lazyRoute(() => import("@/shared/components/error/404.vue")),
   },
 ];