@cavulsqa/create 2.9.2 → 2.10.0

package/templates/f7-app/src/shared/composables/useNavigationGuard.ts

@@ -0,0 +1,48 @@
+import { f7 } from "framework7-vue";
+
+interface GuardableRouter {
+  allowPageChange: boolean;
+  navigate: (...args: never[]) => unknown;
+  back: (...args: never[]) => unknown;
+  __navigationGuarded?: boolean;
+}
+
+/**
+ * Framework7 only enforces `allowPageChange` for synchronous routes. Routes here are async, and
+ * `asyncResolve` calls the internal `load()` with `ignorePageChange: true`, so a navigate issued
+ * while a transition is still animating runs a forward on top of an in-flight backward. That
+ * destroys the previous page element and leaves the router holding two copies of the same page;
+ * from there `loadBack` takes its same-url early return and back() can never move again, which
+ * reads to the user as a frozen screen.
+ *
+ * Dropping the losing call is a single boolean read - no queueing, no deferral - so the navigation
+ * that does win runs at exactly the same speed as before.
+ */
+export function installNavigationGuard(router: GuardableRouter): void {
+  if (router.__navigationGuarded) return;
+  router.__navigationGuarded = true;
+
+  let depth = 0;
+
+  const guard = (method: (...args: never[]) => unknown) => {
+    return (...args: never[]) => {
+      if (depth === 0 && !router.allowPageChange) return router;
+      depth += 1;
+      try {
+        return method(...args);
+      } finally {
+        depth -= 1;
+      }
+    };
+  };
+
+  router.navigate = guard(router.navigate.bind(router));
+  router.back = guard(router.back.bind(router));
+}
+
+export function useNavigationGuard(): void {
+  const views = f7.views as unknown as Array<{ router?: GuardableRouter }>;
+  for (const view of views ?? []) {
+    if (view?.router) installNavigationGuard(view.router);
+  }
+}

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/src/shared/utils/lazyRoute.ts

@@ -0,0 +1,25 @@
+import type { Router } from "framework7/types";
+
+type RouteComponentModule = { default: unknown };
+
+/**
+ * Framework7 sets `allowPageChange = false` before calling a route's async hook and only restores
+ * it from `resolve` or `reject`. A hook that settles neither - a chunk that fails to download, or a
+ * module that throws while evaluating - leaves that view's router locked for the rest of the
+ * session, so every later navigation and back press is silently ignored. Routing the import
+ * through here guarantees the router is always released.
+ */
+export function lazyRoute(
+  load: () => Promise<RouteComponentModule>,
+): Router.RouteParameters["async"] {
+  return function routeAsync({ resolve, reject }) {
+    load()
+      .then((module) => {
+        resolve({ component: module.default });
+      })
+      .catch((error: unknown) => {
+        console.error("[router] Unable to load route component", error);
+        reject();
+      });
+  };
+}

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

@@ -0,0 +1,30 @@
+import { expect, test, vi } from "vite-plus/test";
+import { lazyRoute } from "../src/shared/utils/lazyRoute.js";
+
+function callRoute(handler: ReturnType<typeof lazyRoute>) {
+  const resolve = vi.fn();
+  const reject = vi.fn();
+  (handler as (ctx: unknown) => void)({ resolve, reject });
+  return { resolve, reject };
+}
+
+test("resolves the route with the module's default export", async () => {
+  const component = { name: "HomeView" };
+  const { resolve, reject } = callRoute(lazyRoute(() => Promise.resolve({ default: component })));
+
+  await vi.waitFor(() => expect(resolve).toHaveBeenCalledOnce());
+  expect(resolve).toHaveBeenCalledWith({ component });
+  expect(reject).not.toHaveBeenCalled();
+});
+
+test("rejects the route when the chunk fails to load, releasing the router", async () => {
+  // Without this the router keeps allowPageChange === false forever and the view freezes.
+  const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+  const { resolve, reject } = callRoute(
+    lazyRoute(() => Promise.reject(new Error("chunk load failed"))),
+  );
+
+  await vi.waitFor(() => expect(reject).toHaveBeenCalledOnce());
+  expect(resolve).not.toHaveBeenCalled();
+  consoleError.mockRestore();
+});

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

@@ -0,0 +1,82 @@
+import { expect, test } from "vite-plus/test";
+import { installNavigationGuard } from "../src/shared/composables/useNavigationGuard.js";
+
+function makeRouter() {
+  const calls: string[] = [];
+  const router = {
+    allowPageChange: true,
+    navigate(url: string) {
+      calls.push(`navigate:${url}`);
+    },
+    back() {
+      calls.push("back");
+    },
+  };
+  return { router, calls };
+}
+
+test("drops a navigate issued while a transition is still in flight", () => {
+  const { router, calls } = makeRouter();
+  installNavigationGuard(router as never);
+
+  router.allowPageChange = false;
+  router.navigate("/home/feature/1/");
+
+  expect(calls).toEqual([]);
+});
+
+test("drops a back issued while a transition is still in flight", () => {
+  const { router, calls } = makeRouter();
+  installNavigationGuard(router as never);
+
+  router.allowPageChange = false;
+  router.back();
+
+  expect(calls).toEqual([]);
+});
+
+test("lets navigation through while the router is idle", () => {
+  const { router, calls } = makeRouter();
+  installNavigationGuard(router as never);
+
+  router.navigate("/home/feature/1/");
+  router.back();
+
+  expect(calls).toEqual(["navigate:/home/feature/1/", "back"]);
+});
+
+test("still allows Framework7's own recursive calls after it locks the router", () => {
+  // back() re-enters itself with { force: true }, and navigate() re-enters for named routes, both
+  // after allowPageChange is already false. Dropping those would break normal navigation.
+  const calls: string[] = [];
+  const router = {
+    allowPageChange: true,
+    navigate(url: string) {
+      calls.push(`navigate:${url}`);
+      router.allowPageChange = false;
+      if (url === "outer") router.navigate("inner");
+    },
+    back() {
+      calls.push("back");
+      router.allowPageChange = false;
+      router.navigate("from-back");
+    },
+  };
+  installNavigationGuard(router as never);
+
+  router.navigate("outer");
+  router.allowPageChange = true;
+  router.back();
+
+  expect(calls).toEqual(["navigate:outer", "navigate:inner", "back", "navigate:from-back"]);
+});
+
+test("installing twice does not wrap the router twice", () => {
+  const { router, calls } = makeRouter();
+  installNavigationGuard(router as never);
+  installNavigationGuard(router as never);
+
+  router.navigate("/demo/");
+
+  expect(calls).toEqual(["navigate:/demo/"]);
+});

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.

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

@@ -0,0 +1,106 @@
+# Schema and migrations
+
+`src/shared/database/schema.ts` is what Kysely type-checks every query against.
+`src/shared/database/migrations.ts` is what actually creates the tables. The two are edited
+together, always: a field in one and not the other is a runtime error the compiler cannot see.
+
+## Migrations
+
+- Keys are ordered lexically and recorded once applied, so they are **numbered and never renamed**.
+  Renaming one makes it run again on a database that already has it.
+- Never edit a migration that has shipped. Add the next one.
+- A synced table is created with `createTableWithDefaults` when it carries the sync contract, or a
+  plain `createTable` when it does not. This template has no server, so plain tables are the norm.
+- Declare foreign keys, and index the columns screens filter and join by. Without them every
+  dashboard aggregate is a full scan, which you will not notice until the table is large and the
+  device is slow.
+- SQLite ignores foreign keys unless asked; `PRAGMA foreign_keys = ON` runs at the end of the
+  migration. It is per-connection, so a cascade is not something to rely on — `deleteOrder` removes
+  the lines explicitly.
+
+## Types
+
+- Money is **integer cents**, named `*_cents`. A float total is a rounding bug waiting for a
+  large-enough order.
+- Timestamps are ISO strings via `nowISO()`.
+- A price copied onto an order line is copied deliberately, so a later catalogue change does not
+  rewrite history.
+
+## Getting an inserted id
+
+Use `insertId`, never `.returning(...)`:
+
+```ts
+const inserted = await trx.insertInto("sales_order").values({ ... }).executeTakeFirstOrThrow();
+const orderId = Number(inserted.insertId ?? 0);
+if (!orderId) throw new Error("the order was written but the database reported no id for it");
+```
+
+`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
+
+A schema change needs a test in `tests/` that runs the migration and the affected queries against
+sql.js. `tests/sales.repository.test.ts` is the pattern: build a Kysely on `createSqlJsDialect()`,
+migrate, then assert on real rows — including the arithmetic. A total that type-checks can still be
+computed wrong.
+
+## Writing a lot of rows
+
+Measured on a phone, at 100k rows, per row written:
+
+| how                                              | per row        |
+| ------------------------------------------------ | -------------- |
+| one insert per statement, each its own commit    | 8-13 ms        |
+| one insert per statement, inside one transaction | ~0.45 ms       |
+| multi-row insert, ~150 rows per statement        | 0.066-0.115 ms |
+
+Roughly a hundredfold between the worst and best way to write the same row. SQLite caps parameters
+per statement, so 150 rows of five columns is about the practical ceiling for one insert - chunk by
+parameter budget, not by a round number.
+
+## Why a big write freezes the screen, and what to do
+
+The database runs in one worker, and that worker is serial. A read cannot overtake a write already
+in flight; it waits for everything queued ahead of it. So the cost to the UI is not how fast the
+write is, it is **how much work the write committed to before the read arrived**.
+
+Time a screen's read waits when it lands during a 1000-row write:
+
+| write strategy                                 | read waits    |
+| ---------------------------------------------- | ------------- |
+| 1000 single inserts in one transaction         | ~350-690 ms   |
+| 150 rows per statement, one transaction        | ~36-53 ms     |
+| ten transactions of 100, awaited one at a time | **~21-32 ms** |
+
+A naive loop stalls the screen for most of a second. Chunked transactions bring it under the
+threshold anyone notices, and the reason is mechanical: awaiting each chunk means only one chunk is
+ever queued, so an arriving read waits for 100 rows instead of 1000.
+
+**So: write in chunks of about a hundred rows, use multi-row inserts inside each chunk, and await
+each chunk before starting the next.** Do not wrap a thousand rows in one transaction to be fast -
+it is faster in total and far worse for anyone looking at the screen while it runs.
+
+The Diagnostics benchmark measures all three strategies, so this is checkable on any device rather
+than taken on faith.

package/templates/m3e-app/.claude/rules/m3e-ui.md

@@ -0,0 +1,48 @@
+# UI: Material 3 Expressive on a Framework7 engine
+
+The full workflow is the `m3-expressive` skill. These are the guardrails it rests on, each one a way
+the screen breaks silently.
+
+## Framework7 is the engine, not the look
+
+Only five Framework7 components resolve: `F7App`, `F7Views`, `F7View`, `F7Page`, `F7PageContent`
+(the allowlist in `src/shared/utils/resolvers/resolvers.ts`). Routing, per-tab history and page
+events come from them; everything visible is an `M3*` component. A visual `f7-*` component brings
+Framework7's styling and modal stack back and fights the M3 overlay stack for Android back.
+
+`f7`, `f7ready` are auto-imported; `f7route` / `f7router` arrive as props of a route component:
+`defineProps<{ f7route: Router.Route; f7router: Router.Router }>()`. Inside shared components, reach
+the router with `useViewRouter(el)`.
+
+## CSS is layered
+
+`assets/css/app.css` declares `@layer framework7, theme, base, components, utilities`. Framework7's
+CSS is the lowest layer and the M3 components sit below Tailwind's utilities, so a utility on a
+component always wins and `!important` is never needed. New global CSS goes in a layer; component
+CSS goes in the component's `<style scoped>`.
+
+Layers only settle conflicts: a Framework7 rule nothing else contradicts still applies. Its core
+sizes every bare `button` to `width: 100%` - the M3 components undo it for their own buttons, so a
+hand-made `<button>` must set its width or use an `M3*` button.
+
+In `<style scoped>`, wrap the whole selector: `:global(.parent .child)`. Vue compiles
+`:global(.parent) .child` to `.parent` alone, silently styling the wrong element.
+
+## Tokens only
+
+Tailwind's default palette, radii, shadows and easings are cleared in
+`assets/css/theme/tailwind.css` and refilled from `--md-sys-*`. A class like `bg-red-500` does not
+exist. Colours: roles. Corners: the shape scale. Type: `type-*`. Hex values live in
+`src/app/theme.config.ts` only.
+
+## Icons are SVG components, checked at build time
+
+`<i-ms-<name>-rounded />` from Material Symbols (outlined: `-outline-rounded`, filled: `-rounded`).
+`autoInstall` is off, so a wrong name fails the build instead of rendering nothing. In TS:
+`import Icon from "~icons/material-symbols/<name>"` and `markRaw` it before putting it in reactive
+state.
+
+## Proof obligations
+
+`vp check`, `pnpm type-check` and `vp test` pass. Say what you saw run - light and dark, compact width,
+reduced motion - and say plainly when you have not seen it on a device.

package/templates/m3e-app/.claude/rules/modules.md

@@ -0,0 +1,43 @@
+# Modules, domains and shared
+
+```
+modules/<feature>/router/routes/<feature>.routes.ts   default export, Router.RouteParameters[]
+modules/<feature>/views/<Name>View.vue                thin, presentational
+modules/<feature>/components/*.vue                    props in, emits out
+modules/<feature>/composables/use*.ts                 the feature's state and actions
+domains/<domain>/<domain>.repository.ts               SQL only
+shared/…                                              what two modules genuinely both need
+```
+
+## The seam
+
+A **view** wires a composable to components. If it holds business logic, that logic belongs in the
+composable; if it holds SQL, that belongs in a repository.
+
+A **composable** owns state, queries and actions for one feature. It may import repositories and
+the reactive query helpers. It returns refs and functions, never markup.
+
+A **repository** is plain functions over Kysely. No `ref`, no lifecycle, no Framework7, no imports
+from `modules/`. It takes the database as a parameter — that is what makes it testable, and reaching
+for the singleton instead is what made the first version of this template untestable.
+
+A **component** takes props and emits events. It does not query the database.
+
+## Direction of dependencies
+
+`modules → domains → shared → packages`. Never backwards. A repository importing from a module, or
+`shared` importing from `modules`, means something is in the wrong place.
+
+## Adding a feature
+
+1. `modules/<feature>/` with the four folders.
+2. Its routes in `router/routes/<feature>.routes.ts`, registered in `src/router/index.ts` before the
+   global catch-all.
+3. A tab in `src/app/tabs.ts` only if it is a top-level section. Otherwise it is a pushed page, and
+   pushed pages are an `AppPage` with `back`, which hides the navigation bar.
+4. Strings in **both** `locales/en.json` and `locales/fr.json`. A missing key renders the key.
+
+## shared/ is not a junk drawer
+
+Something goes in `shared/` when two modules import it today. Not when one module might later. The
+test is: can you name the second caller? If not, it lives in the module that uses it.

package/templates/m3e-app/.claude/rules/native.md

@@ -0,0 +1,60 @@
+# Capacitor and native behaviour
+
+Every native call is guarded with `Capacitor.isNativePlatform()` or
+`Capacitor.getPlatform() === "web"`. `vp dev` in a browser must keep working — it is how the app is
+inspected — so a handler that assumes a device breaks the fastest feedback loop you have.
+
+Native wiring that needs the Framework7 instance runs inside `f7ready`, not at module load.
+`src/plugins/capacitor/index.ts` is the single entry point.
+
+## What is already handled, and why it is not simple
+
+- **Back button** (`useAndroidBackButton`) first asks the M3 overlay stack to close its topmost
+  overlay (sheet, dialog, menu, FAB menu) - a persistent one swallows back instead. Then the current
+  tab's history, then from another tab's root the start destination, then it minimises rather than
+  exits. Overlays register themselves through `useOverlay`; a hand-built modal is invisible to back.
+- **Keyboard** (`useKeyboard`) scrolls the focused input into view on _every_ phase of the
+  transition, not once — the layout is still settling at `keyboardWillShow` and only
+  `keyboardDidShow` sees the final height. It also hides the navigation bar, which otherwise steals a
+  row from the field being typed into.
+- **Status bar** overlays the web view (edge to edge); the top app bar pads itself with the inset,
+  and the icon colour follows the theme's dark mode.
+- **Splash** stays up until `hideSplashScreen()`, called on a frame boundary so there is no flash of
+  an unpainted shell.
+
+Do not simplify these into a single listener. Each branch is there because of a specific device
+behaviour, and the comments say which.
+
+## The bootstrap must never fail silently
+
+`main.ts` opens the database before mounting, inside a `try`, and renders the failure on the page if
+it throws. An earlier version awaited it at module top level: a rejection produced an empty `#app`
+and a completely silent console, which is the worst possible failure for whoever generates from this
+template. The timeout exists so a hang cannot masquerade as a blank screen either.
+
+Anything else added to the bootstrap follows the same shape: guarded, and loud when it fails.
+
+## Fixed elements and the shell
+
+The compact navigation bar floats over the bottom of the views; the shell publishes its height as
+`--app-nav-offset` and `--app-bottom-inset` (offset plus the gesture area). So:
+
+- Anything floating above content offsets by `--app-bottom-inset` - `AppPage`'s `#fab` slot, the
+  snackbar host and the floating toolbar already do. Never measure the bar.
+- Page content is already padded by the same variable; do not add your own bottom spacer for it.
+- The FAB menu opens upward, away from the bar.
+
+## Permissions live in a generated folder
+
+`android/` is generated by `cap add android` and gitignored, so a permission the app needs is not
+carried by the template. Add it to `android/app/src/main/AndroidManifest.xml` after generating:
+
+- **Location** (the chat's _Location_ attachment): `ACCESS_COARSE_LOCATION` and
+  `ACCESS_FINE_LOCATION`. The web view's own `navigator.geolocation` does the lookup; Capacitor
+  asks the person at runtime only for a permission the manifest declares, so without these the
+  lookup fails as `denied` and the chat offers the depot instead.
+
+## Proof obligations
+
+Say which platform you tested on. "Type-checks" is not a claim about a device, and neither is a
+browser. If you have not run it on Android, say so.