@cavulsqa/create 2.9.3 → 2.10.1

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.3",
-  "description": "Create a Vue + Framework7 + Capacitor + SQLite app from the cavulsqa templates.",
+  "version": "2.10.1",
+  "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-6R7B6B3lY7wTuktecqa5vTipEb1bILSBEAhOvLXmiTM=",
+  "templatesFingerprint": "sha256-rGqnILJ0mL3Tjp8wsotbcajPFpJWqAEtS9G80QBcA/Q=",
   "scripts": {
     "build": "node scripts/bundleTemplates.mjs",
     "check": "vp check",

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

@@ -98,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
@@ -106,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
@@ -341,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
@@ -446,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']>
@@ -454,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']>

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.1",
-    "@cavulsqa/reactive-db": "^1.2.1",
-    "@cavulsqa/reactive-vue": "^1.2.1",
+    "@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/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/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/shared/recorder/capacitorSink.ts

@@ -0,0 +1,124 @@
+import { Capacitor } from "@capacitor/core";
+import { Directory, Filesystem } from "@capacitor/filesystem";
+import { Share } from "@capacitor/share";
+import type { RecorderSink, SessionManifest } from "@cavulsqa/recorder";
+
+const CAPTURE_DIR = "capu";
+const BASE64_CHUNK = 0x8000;
+
+export interface CaptureFile {
+  name: string;
+  size: number;
+  modifiedAt: number;
+}
+
+interface BrowserCapture {
+  name: string;
+  blob: Blob;
+  size: number;
+  savedAt: number;
+}
+
+const browserCaptures = new Map<string, BrowserCapture>();
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (let offset = 0; offset < bytes.length; offset += BASE64_CHUNK) {
+    const chunk = bytes.subarray(offset, offset + BASE64_CHUNK);
+    binary += String.fromCharCode(...chunk);
+  }
+  return btoa(binary);
+}
+
+function fileNameFor(manifest: SessionManifest): string {
+  return `${manifest.sessionId}-${String(Date.now())}.capu`;
+}
+
+function downloadBlob(name: string, blob: Blob): void {
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = name;
+  document.body.appendChild(link);
+  link.click();
+  link.remove();
+  URL.revokeObjectURL(url);
+}
+
+async function saveNative(archive: Uint8Array, manifest: SessionManifest): Promise<void> {
+  const path = `${CAPTURE_DIR}/${fileNameFor(manifest)}`;
+  await Filesystem.writeFile({
+    path,
+    data: bytesToBase64(archive),
+    directory: Directory.External,
+    recursive: true,
+  });
+  const { uri } = await Filesystem.getUri({ path, directory: Directory.External });
+  await Share.share({ url: uri, title: manifest.label });
+}
+
+function saveBrowser(archive: Uint8Array, manifest: SessionManifest): void {
+  const name = fileNameFor(manifest);
+  const blob = new Blob([archive as Uint8Array<ArrayBuffer>], { type: "application/zip" });
+  browserCaptures.set(name, { name, blob, size: blob.size, savedAt: Date.now() });
+  downloadBlob(name, blob);
+}
+
+/**
+ * On native, writes a finished `.capu` under `capu/<sessionId>-<ts>.capu` in the app's external
+ * storage and opens the Android share sheet. Off-device (`vp dev` in a browser) it triggers a blob
+ * download instead, since `Filesystem`/`Share` have nothing to write to there.
+ */
+export function createCapacitorSink(): RecorderSink {
+  return {
+    async save(archive, manifest) {
+      if (Capacitor.isNativePlatform()) {
+        await saveNative(archive, manifest);
+      } else {
+        saveBrowser(archive, manifest);
+      }
+    },
+  };
+}
+
+/** Lists previously captured `.capu` files for the Settings diagnostics list, newest first. */
+export async function listCaptures(): Promise<CaptureFile[]> {
+  if (Capacitor.isNativePlatform()) {
+    try {
+      const result = await Filesystem.readdir({
+        path: CAPTURE_DIR,
+        directory: Directory.External,
+      });
+      return result.files
+        .filter((file) => file.type === "file")
+        .map((file) => ({ name: file.name, size: file.size, modifiedAt: file.mtime }))
+        .sort((a, b) => b.modifiedAt - a.modifiedAt);
+    } catch {
+      return [];
+    }
+  }
+  return [...browserCaptures.values()]
+    .map((capture) => ({ name: capture.name, size: capture.size, modifiedAt: capture.savedAt }))
+    .sort((a, b) => b.modifiedAt - a.modifiedAt);
+}
+
+/** Re-opens the Android share sheet for a previously captured file; on browser, re-triggers the download. */
+export async function shareCapture(name: string): Promise<void> {
+  if (Capacitor.isNativePlatform()) {
+    const path = `${CAPTURE_DIR}/${name}`;
+    const { uri } = await Filesystem.getUri({ path, directory: Directory.External });
+    await Share.share({ url: uri });
+    return;
+  }
+  const capture = browserCaptures.get(name);
+  if (capture) downloadBlob(name, capture.blob);
+}
+
+/** Permanently deletes a previously captured file. */
+export async function deleteCapture(name: string): Promise<void> {
+  if (Capacitor.isNativePlatform()) {
+    await Filesystem.deleteFile({ path: `${CAPTURE_DIR}/${name}`, directory: Directory.External });
+    return;
+  }
+  browserCaptures.delete(name);
+}

package/templates/f7-app/vite.config.ts

@@ -52,6 +52,7 @@ export default defineConfig({
      */
     AutoImport({
       include: [/\.[tj]sx?$/, /\.vue$/, /\.vue\?vue/],
+      exclude: [/[\\/]node_modules[\\/]/, /[\\/]\.git[\\/]/, /[\\/]dist[\\/]/],
       imports: ["vue", "vue-i18n", "@vueuse/core", getFramework7AutoImports()],
       dirs: [
         "src/shared/composables/**",

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

@@ -0,0 +1,68 @@
+# Reading and writing data
+
+Every read is a reactive query or a deliberate on-demand call. Every write goes through `rdb`. A
+third shape — a hand-rolled cache, or a raw write — produces "stale screen, no error, no symptom",
+which is the one failure an offline app cannot afford: the user has no network to blame.
+
+## Reads
+
+`useReactiveQuery(fn, { tables, queryKey, debounce })` from `@/shared/database/queries`.
+
+- **`tables` is the invalidation contract.** It must list exactly the tables `fn` reads — no more,
+  no less. Under-list and a write to the missing table leaves the screen stale with no error.
+  Over-list and an unrelated write re-runs an expensive query for nothing.
+
+  A join means every joined table. `loadOrderDetail` reads the order, its lines, the customer, the
+  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 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.
+
+- Reads may take the database directly: `searchOrders(getDatabase().db, term)`. Repositories take
+  the database as a parameter rather than reaching for the singleton, which is what makes them
+  testable — `tests/sales.repository.test.ts` runs them against sql.js.
+
+## Writes
+
+Always `rdb`, never `getDatabase().db`:
+
+```ts
+await saveOrder(rdb, { customerId, reference, lines });   // announces sales_order, order_line
+await saveOrder(getDatabase().db, …);                     // writes, and nothing notices
+```
+
+`rdb` wraps Kysely so a mutation publishes the tables it touched on the change bus. A raw write
+lands in SQLite and no query hears about it, so the screen keeps showing the old rows until
+something unrelated triggers a refetch. There is no error and nothing to see in review.
+
+Anything that must be all-or-nothing goes in one transaction. `saveOrder` writes the order and its
+lines together because a half-written order is worse than no order.
+
+## Forbidden
+
+A module-scope `Map` or `ref` holding fetched rows with neither a TTL nor a bus subscription. Once
+populated it never refreshes for the session, and the next write is invisible until restart.
+In-flight dedup (a `Map<key, Promise>` cleared in `finally`) is concurrency control, not a cache,
+and is fine — `useReactiveQuery` already does it.
+
+## Seed and demo helpers
+
+Anything a person can press twice must survive being pressed twice. `seedSampleData` inserts the
+catalogue only where missing and upserts tags, because a plain insert threw
+`UNIQUE constraint failed: tag.label` on the second press.
+
+## Proof obligations
+
+- A new query: state which tables its SQL touches and that `tables` matches.
+- A new write: state that it goes through `rdb`, and whether it needs a transaction.
+- Either: a test in `tests/` exercising it against sql.js. Type-checking a query proves nothing
+  about what it returns.