@cavulsqa/create 2.9.2 → 2.9.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavulsqa/create",
-  "version": "2.9.2",
+  "version": "2.9.3",
   "description": "Create a Vue + Framework7 + Capacitor + SQLite app from the cavulsqa templates.",
   "keywords": [
     "capacitor",
@@ -52,7 +52,7 @@
       }
     ]
   },
-  "templatesFingerprint": "sha256-w5ItqHFEFJCJwe7V3W0FEhJf7foJkanjYLY85j/Wbd8=",
+  "templatesFingerprint": "sha256-6R7B6B3lY7wTuktecqa5vTipEb1bILSBEAhOvLXmiTM=",
   "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
@@ -230,6 +232,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
@@ -403,12 +406,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']>
@@ -575,6 +580,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

@@ -20,9 +20,9 @@
     "@capacitor/preferences": "^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.2.1",
+    "@cavulsqa/reactive-db": "^1.2.1",
+    "@cavulsqa/reactive-vue": "^1.2.1",
     "@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/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/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")),
   },
 ];
 

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/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/"]);
+});