@cavulsqa/create 2.9.2 → 2.10.0

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

@@ -0,0 +1,157 @@
+<template>
+  <AppPage :title="t('settings.title')" name="settings">
+    <SectionHeader :title="t('settings.appearance')" />
+    <M3List variant="segmented" inset>
+      <M3ListItem
+        clickable
+        :headline="t('settings.colors')"
+        :supporting="t(`studio.variants.${settings.variant}`)"
+        @click="f7router.navigate('/settings/studio/')"
+      >
+        <template #leading>
+          <M3Shape shape="cookie9Sided" class="size-10 bg-primary text-on-primary">
+            <i-ms-palette-outline-rounded class="size-5" />
+          </M3Shape>
+        </template>
+        <template #trailing><i-ms-chevron-right-rounded class="rtl:-scale-x-100" /></template>
+      </M3ListItem>
+    </M3List>
+
+    <div class="mx-4 mt-0.5 flex flex-col gap-0.5">
+      <SettingsChoice
+        :model-value="settings.mode"
+        :label="t('settings.darkMode')"
+        :options="modeOptions"
+        @update:model-value="(mode) => theme.update({ mode })"
+      >
+        <template #icon><component :is="modeIcon" /></template>
+      </SettingsChoice>
+      <SettingsChoice
+        :model-value="settings.motion"
+        :label="t('settings.motion')"
+        :supporting="t('settings.motionNote')"
+        :options="motionOptions"
+        @update:model-value="(motion) => theme.update({ motion })"
+      >
+        <template #icon><i-ms-animation-rounded /></template>
+      </SettingsChoice>
+    </div>
+
+    <SectionHeader :title="t('settings.general')" />
+    <M3List variant="segmented" inset>
+      <M3ListItem
+        clickable
+        :headline="t('settings.language')"
+        :supporting="t(`settings.languages.${locale}`)"
+        @click="chooseLanguage"
+      >
+        <template #leading><i-ms-language-rounded /></template>
+      </M3ListItem>
+    </M3List>
+
+    <SectionHeader :title="t('settings.storage')" />
+    <M3List variant="segmented" inset>
+      <M3ListItem :headline="t('settings.engine')" :supporting="storage">
+        <template #leading><i-ms-database-outline-rounded /></template>
+      </M3ListItem>
+      <M3ListItem
+        v-if="!durable"
+        :headline="t('settings.notDurable')"
+        :supporting="tradeoff"
+        multiline
+        tone="destructive"
+      >
+        <template #leading><i-ms-info-outline-rounded /></template>
+      </M3ListItem>
+      <M3ListItem
+        v-for="skip in skipped"
+        :key="skip.id"
+        :headline="skip.id"
+        :supporting="skip.detail"
+        multiline
+      >
+        <template #leading><i-ms-chevron-right-rounded class="rtl:-scale-x-100" /></template>
+      </M3ListItem>
+    </M3List>
+
+    <SectionHeader :title="t('settings.about')" />
+    <M3List variant="segmented" inset>
+      <M3ListItem :headline="t('settings.appName')" :trailing-text="appName">
+        <template #leading><i-ms-info-outline-rounded /></template>
+      </M3ListItem>
+      <M3ListItem :headline="t('settings.version')" :trailing-text="appVersion">
+        <template #leading><i-ms-verified-outline-rounded /></template>
+      </M3ListItem>
+      <M3ListItem :headline="t('settings.platform')" :trailing-text="platform">
+        <template #leading><i-ms-phone-android-outline-rounded /></template>
+      </M3ListItem>
+      <M3ListItem :headline="t('settings.webview')" :trailing-text="webview">
+        <template #leading><i-ms-web-rounded /></template>
+      </M3ListItem>
+    </M3List>
+  </AppPage>
+</template>
+
+<script setup lang="ts">
+import { Capacitor } from "@capacitor/core";
+import { markRaw } from "vue";
+import type { Router } from "framework7/types";
+import AutoIcon from "~icons/material-symbols/brightness-auto-outline-rounded";
+import DarkIcon from "~icons/material-symbols/dark-mode-outline-rounded";
+import LightIcon from "~icons/material-symbols/light-mode-outline-rounded";
+import SettingsChoice from "@/modules/settings/components/SettingsChoice.vue";
+import type { ChoiceOption } from "@/modules/settings/types";
+import { LOCALES, setLocale, type AppLocale } from "@/plugins/i18n.plugin";
+import { activeStorage, activeStorageLabel, storageAttempts } from "@/shared/database/database";
+import { webviewVersion } from "@/shared/database/storage";
+import type { ModeChoice, MotionChoice } from "@/shared/utils/theme/themeSettings";
+
+defineProps<{ f7router: Router.Router }>();
+
+const { t, locale } = useI18n();
+const theme = useThemeSettings();
+const settings = computed(() => theme.settings.value);
+const actionSheet = useActionSheet();
+
+const appName = __APP_NAME__;
+const appVersion = __APP_VERSION__;
+const platform = Capacitor.getPlatform();
+const storage = activeStorageLabel();
+const durable = activeStorage().durable;
+const tradeoff = activeStorage().tradeoff;
+const skipped = storageAttempts().filter((attempt) => attempt.outcome !== "opened");
+const chromium = webviewVersion();
+const webview = chromium === null ? t("settings.unknown") : `Chromium ${String(chromium)}`;
+
+const modeOptions = computed<ChoiceOption<ModeChoice>[]>(() => [
+  { value: "system", label: t("settings.modeSystem"), icon: markRaw(AutoIcon) },
+  { value: "light", label: t("settings.modeLight"), icon: markRaw(LightIcon) },
+  { value: "dark", label: t("settings.modeDark"), icon: markRaw(DarkIcon) },
+]);
+
+const modeIcon = computed(
+  () => modeOptions.value.find((option) => option.value === settings.value.mode)?.icon ?? AutoIcon,
+);
+
+const motionOptions = computed<ChoiceOption<MotionChoice>[]>(() => [
+  { value: "system", label: t("settings.motionSystem") },
+  { value: "reduced", label: t("settings.motionReduced") },
+  { value: "full", label: t("settings.motionFull") },
+]);
+
+async function chooseLanguage() {
+  const choice = await actionSheet.open({
+    title: t("settings.language"),
+    groups: [
+      {
+        items: LOCALES.map((code) => ({
+          id: code,
+          label: t(`settings.languages.${code}`),
+          selected: locale.value === code,
+        })),
+      },
+    ],
+  });
+  if (choice) setLocale(choice as AppLocale);
+}
+</script>

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

@@ -0,0 +1,62 @@
+import {
+  MINIMUM_CHROMIUM_FOR_OPFS,
+  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.
+ *
+ * Deliberately framework-free. Mounting the app to report the failure would run screens that assume
+ * a working database, so a second failure would replace the first and the person would learn
+ * nothing. Plain DOM cannot fail for the same reason twice.
+ *
+ * It replaces a red sentence in a bare div, which is what shipped before and told a field user
+ * nothing they could act on.
+ */
+export function renderBootstrapError(error: unknown): void {
+  hideSplashScreen();
+  const root = document.getElementById("app");
+  if (!root) return;
+
+  const message = error instanceof Error ? error.message : String(error);
+  const detail = error instanceof Error ? (error.stack ?? error.message) : String(error);
+  const version = webviewVersion();
+
+  const advice = webviewLikelyTooOld()
+    ? `This WebView is Chromium ${String(version)}. The app needs ${String(MINIMUM_CHROMIUM_FOR_OPFS)} or newer for local storage. Update Android System WebView in the Play Store - it updates separately from Android itself.`
+    : "Closing the app completely and opening it again usually clears this. Your data has not been deleted.";
+
+  root.replaceChildren();
+  root.insertAdjacentHTML(
+    "afterbegin",
+    `<div style="font:16px/1.5 var(--md-ref-typeface-plain,system-ui),sans-serif;padding:max(32px,env(safe-area-inset-top)) 24px 32px;max-width:38rem;margin:0 auto;min-height:100dvh;box-sizing:border-box;background:var(--md-sys-color-surface,#fff);color:var(--md-sys-color-on-surface,#1c1b1f)">
+      <div style="width:56px;height:56px;border-radius:28px;display:grid;place-items:center;font-size:28px;background:var(--md-sys-color-error-container,#ffdad6);color:var(--md-sys-color-on-error-container,#410002)">!</div>
+      <h1 style="font:400 28px/36px var(--md-ref-typeface-brand,system-ui),sans-serif;margin:20px 0 8px">The app could not start</h1>
+      <p style="margin:0 0 12px;color:var(--md-sys-color-on-surface-variant,#49454f)">${escapeHtml(message)}</p>
+      <p style="margin:0 0 24px;color:var(--md-sys-color-on-surface-variant,#49454f)">${escapeHtml(advice)}</p>
+      <button id="bootstrap-retry" style="appearance:none;border:0;border-radius:28px;height:56px;width:100%;background:var(--md-sys-color-primary,#6750a4);color:var(--md-sys-color-on-primary,#fff);font:500 16px var(--md-ref-typeface-plain,system-ui),sans-serif">
+        Try again
+      </button>
+      <details style="margin-top:24px;color:var(--md-sys-color-on-surface-variant,#49454f)">
+        <summary style="cursor:pointer;font-size:13px">Technical details</summary>
+        <p style="font-size:12px;margin:8px 0 0">WebView: Chromium ${version === null ? "unknown" : String(version)}</p>
+        <pre style="font-size:11px;white-space:pre-wrap;word-break:break-word;margin:8px 0 0">${escapeHtml(detail)}</pre>
+      </details>
+    </div>`,
+  );
+
+  document.getElementById("bootstrap-retry")?.addEventListener("click", () => {
+    window.location.reload();
+  });
+}
+
+/** The message can carry an engine's own text, and that text is not trusted markup. */
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}

package/templates/m3e-app/src/plugins/capacitor/index.ts

@@ -0,0 +1,14 @@
+import type Framework7 from "framework7";
+import { useAndroidBackButton } from "./useAndroidBackButton";
+import { useKeyboard } from "./useKeyboard";
+import { useStatusBar } from "./useStatusBar";
+
+/**
+ * Native wiring that needs the Framework7 instance, so it runs once the shell exists rather than at
+ * module load. Every handler no-ops off-device, which is what keeps `vp dev` in a browser working.
+ */
+export async function initCapacitor(f7: Framework7): Promise<void> {
+  await useAndroidBackButton(f7);
+  useKeyboard();
+  await useStatusBar();
+}

package/templates/m3e-app/src/plugins/capacitor/useAndroidBackButton.ts

@@ -0,0 +1,36 @@
+import { App } from "@capacitor/app";
+import { Capacitor } from "@capacitor/core";
+import type Framework7 from "framework7";
+import { m3e } from "@/plugins/m3e.plugin";
+import { useActiveTab } from "@/shared/composables/navigation/useActiveTab";
+import { START_TAB } from "@/app/tabs";
+
+/**
+ * Android back closes what is on top before it navigates, in this order:
+ * 1. the topmost M3 overlay - a sheet, a dialog, a menu, the FAB menu. A persistent one swallows
+ *    back instead of closing, so a required decision cannot be backed out of by accident;
+ * 2. the current tab's own history;
+ * 3. from the root of any other destination, the start destination, as M3 navigation does;
+ * 4. otherwise the app goes to the background rather than exiting, so it reopens where it was.
+ */
+export async function useAndroidBackButton(f7: Framework7): Promise<void> {
+  if (!Capacitor.isNativePlatform()) return;
+  const tabs = useActiveTab();
+
+  await App.addListener("backButton", () => {
+    if (m3e.config.overlays.closeTop()) return;
+
+    const view = f7.views.current;
+    if (view?.router && view.router.history.length > 1) {
+      view.router.back();
+      return;
+    }
+
+    if (!tabs.isStart()) {
+      tabs.show(START_TAB);
+      return;
+    }
+
+    void App.minimizeApp();
+  });
+}

package/templates/m3e-app/src/plugins/capacitor/useKeyboard.ts

@@ -0,0 +1,48 @@
+import { Capacitor } from "@capacitor/core";
+import { Keyboard } from "@capacitor/keyboard";
+import { useNavigationVisibility } from "@/shared/composables/navigation/useNavigationVisibility";
+
+const EDITABLE = "input, textarea, [contenteditable='true']";
+const KEEPS_KEYBOARD = `${EDITABLE}, [data-keeps-keyboard]`;
+
+function scrollFocusedIntoView(): void {
+  const focused = document.activeElement;
+  if (focused instanceof HTMLElement && focused.matches(EDITABLE)) {
+    focused.scrollIntoView({ block: "center", behavior: "smooth" });
+  }
+}
+
+/**
+ * The focused field scrolls out of view as the keyboard animates in, so it is scrolled back on
+ * every phase: the layout is still settling at `keyboardWillShow` and only `keyboardDidShow` sees
+ * the final height. The navigation bar leaves while the keyboard is up - it would otherwise sit on
+ * the keyboard and steal a row from the field being typed into. A tap outside any field dismisses
+ * the keyboard instead of leaving it over half the screen - except inside `[data-keeps-keyboard]`,
+ * such as a message composer, whose send button must not close it.
+ */
+export function useKeyboard(): void {
+  if (!Capacitor.isNativePlatform()) return;
+  const { setKeyboardOpen } = useNavigationVisibility();
+
+  void Keyboard.addListener("keyboardWillShow", () => {
+    setKeyboardOpen(true);
+    scrollFocusedIntoView();
+  });
+  void Keyboard.addListener("keyboardDidShow", scrollFocusedIntoView);
+  void Keyboard.addListener("keyboardDidHide", () => setKeyboardOpen(false));
+
+  document.addEventListener(
+    "touchstart",
+    (event) => {
+      const target = event.target;
+      if (!(target instanceof Element) || target.closest(KEEPS_KEYBOARD)) return;
+      if (
+        document.activeElement instanceof HTMLElement &&
+        document.activeElement.matches(EDITABLE)
+      ) {
+        document.activeElement.blur();
+      }
+    },
+    { passive: true },
+  );
+}

package/templates/m3e-app/src/plugins/capacitor/useSplashScreen.ts

@@ -0,0 +1,43 @@
+import { Capacitor } from "@capacitor/core";
+import { SplashScreen } from "@capacitor/splash-screen";
+import type Framework7 from "framework7/lite";
+
+const PAGE_TIMEOUT_MS = 4000;
+
+/**
+ * `launchAutoHide` is off in `capacitor.config.ts`, so the splash stays up until this is called.
+ * Hiding it on a frame boundary avoids a flash of an unpainted shell between the two.
+ */
+export function hideSplashScreen(): void {
+  if (!Capacitor.isNativePlatform()) return;
+  requestAnimationFrame(() => void SplashScreen.hide());
+}
+
+const inActiveTab = (element: Element | null | undefined) =>
+  Boolean(element?.closest(".tab-active, .view-main"));
+
+/**
+ * Keeps the splash up until the visible tab's first page has rendered - route components load
+ * lazily, so the shell alone would show an empty screen with a navigation bar for a beat. A page
+ * that never arrives (a failed chunk) still lets the splash go after a few seconds.
+ */
+export function hideSplashWhenPageReady(app: Framework7): void {
+  if (!Capacitor.isNativePlatform()) return;
+  if (document.querySelector(".tab-active .page-current, .view-main .page-current")) {
+    hideSplashScreen();
+    return;
+  }
+  let done = false;
+  const finish = () => {
+    if (done) return;
+    done = true;
+    clearTimeout(timer);
+    app.off("pageInit", onPage);
+    hideSplashScreen();
+  };
+  const onPage = (page: { el?: Element }) => {
+    if (inActiveTab(page.el)) finish();
+  };
+  const timer = window.setTimeout(finish, PAGE_TIMEOUT_MS);
+  app.on("pageInit", onPage);
+}

package/templates/m3e-app/src/plugins/capacitor/useStatusBar.ts

@@ -0,0 +1,16 @@
+import { Capacitor } from "@capacitor/core";
+import { StatusBar } from "@capacitor/status-bar";
+
+/**
+ * Edge to edge: the status bar is transparent over the web view and the top app bar pads itself
+ * with the safe-area inset. Its icon colour follows the theme's dark mode, which the theme sets -
+ * see `useThemeSettings`.
+ */
+export async function useStatusBar(): Promise<void> {
+  if (!Capacitor.isNativePlatform()) return;
+  try {
+    await StatusBar.setOverlaysWebView({ overlay: true });
+  } catch (error) {
+    console.warn("[status-bar] overlay not applied", error);
+  }
+}

package/templates/m3e-app/src/plugins/framework7.plugin.ts

@@ -0,0 +1,36 @@
+import type { Framework7Parameters } from "framework7/types";
+import routes from "@/router";
+
+/**
+ * Framework7 runs as the navigation engine: routing, the per-tab view stacks and the page
+ * lifecycle. The theme is pinned to Material because its Material page metrics are what the M3
+ * components sit in; nothing visual of Framework7's own is used. Pages move with `m3e-axis`, the
+ * shared-axis transition in `assets/css/layout/transitions.css`, and Framework7 plays it backwards
+ * on back.
+ */
+export function framework7Parameters(): Framework7Parameters {
+  return {
+    name: "App",
+    theme: "md",
+    // Framework7 sets or clears `dark` on <html> at init, and F7App turns an unset value into
+    // `false`, which cleared the dark mode `startTheme` applied before mount. Handing it the mode
+    // already applied keeps them in agreement; the theme's own watcher owns the class afterwards.
+    darkMode:
+      typeof document !== "undefined" && document.documentElement.classList.contains("dark"),
+    routes,
+    touch: {
+      tapHold: true,
+      tapHoldDelay: 500,
+      tapHoldPreventClicks: true,
+      touchRipple: false,
+      activeState: false,
+    },
+    statusbar: { enabled: false },
+    view: {
+      animate: true,
+      transition: "m3e-axis",
+      browserHistory: false,
+      mdSwipeBack: false,
+    },
+  };
+}

package/templates/m3e-app/src/plugins/i18n.plugin.ts

@@ -0,0 +1,87 @@
+import { f7 } from "framework7-vue";
+import { createI18n } from "vue-i18n";
+import { textDirection } from "@/shared/utils/textDirection";
+import ar from "@/locales/ar.json";
+import en from "@/locales/en.json";
+import fr from "@/locales/fr.json";
+
+/**
+ * Arabic is `ar-DZ`, not `ar`: Algeria writes Latin digits (bare `ar` formats ٠١٢) and its own month
+ * names (جانفي, فيفري ...), and every date and number in the app is formatted with this tag.
+ */
+export const LOCALES = ["en", "fr", "ar-DZ"] as const;
+export type AppLocale = (typeof LOCALES)[number];
+
+const STORAGE_KEY = "app-locale";
+
+const isLocale = (value: unknown): value is AppLocale =>
+  typeof value === "string" && (LOCALES as readonly string[]).includes(value);
+
+function initialLocale(): AppLocale {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (isLocale(stored)) return stored;
+  } catch {
+    return "en";
+  }
+  return fromDevice(navigator.language) ?? "en";
+}
+
+/** The app locale for a device language: the same language, whatever its region. */
+export function fromDevice(tag: string): AppLocale | null {
+  const language = tag.split("-")[0]?.toLowerCase();
+  return LOCALES.find((locale) => locale.split("-")[0] === language) ?? null;
+}
+
+const SIX_FORMS = ["zero", "one", "two", "few", "many", "other"] as const;
+
+/**
+ * `"{count} line | {count} lines"` picks its form from the language's own plural rules: French
+ * counts 0 as singular, English does not. A three-form message is `zero | one | other`, and a
+ * six-form one is CLDR's full set, `zero | one | two | few | many | other`, which Arabic needs:
+ * 3 to 10 take a plural, 11 to 99 a singular accusative, 100 the singular again.
+ */
+export function pluralRule(locale: AppLocale) {
+  const rules = new Intl.PluralRules(locale);
+  return (count: number, forms: number) => {
+    const category = rules.select(count);
+    if (forms === 6) return SIX_FORMS.indexOf(category as (typeof SIX_FORMS)[number]);
+    const one = category === "one";
+    if (forms === 3) return count === 0 ? 0 : one ? 1 : 2;
+    return one ? 0 : 1;
+  };
+}
+
+/**
+ * The document's language and direction follow the app's locale: `lang` picks fonts, hyphenation
+ * and the screen reader's voice, and `dir` mirrors the layout, which the components read through
+ * logical properties and `[dir="rtl"]`. A right-to-left locale needs no other change.
+ */
+function applyToDocument(locale: AppLocale): void {
+  if (typeof document === "undefined") return;
+  const direction = textDirection(locale);
+  document.documentElement.lang = locale;
+  document.documentElement.dir = direction;
+  if (f7) f7.rtl = direction === "rtl";
+}
+
+export const i18n = createI18n({
+  legacy: false,
+  locale: initialLocale(),
+  fallbackLocale: "en",
+  messages: { en, fr, "ar-DZ": ar },
+  pluralRules: Object.fromEntries(LOCALES.map((locale) => [locale, pluralRule(locale)])),
+});
+
+applyToDocument(i18n.global.locale.value as AppLocale);
+
+/** Switches language and remembers it; the device language is only the first-run default. */
+export function setLocale(locale: AppLocale): void {
+  i18n.global.locale.value = locale;
+  applyToDocument(locale);
+  try {
+    localStorage.setItem(STORAGE_KEY, locale);
+  } catch {
+    return;
+  }
+}

package/templates/m3e-app/src/plugins/m3e.plugin.ts

@@ -0,0 +1,22 @@
+import { createM3e } from "@cavulsqa/m3e-vue";
+import { Capacitor } from "@capacitor/core";
+import { Haptics, ImpactStyle } from "@capacitor/haptics";
+
+const native = Capacitor.isNativePlatform();
+
+function impact(style: ImpactStyle): void {
+  if (!native) return;
+  Haptics.impact({ style }).catch(() => undefined);
+}
+
+/**
+ * The one m3e instance: components inject it, the Android back handler closes its overlays, and
+ * the theme writes the motion preference into it. Haptics are best-effort - a device without a
+ * vibrator rejects, and a missed tick is not worth an error.
+ */
+export const m3e = createM3e({
+  haptics: {
+    tick: () => impact(ImpactStyle.Light),
+    confirm: () => impact(ImpactStyle.Medium),
+  },
+});

package/templates/m3e-app/src/plugins/seed.plugin.ts

@@ -0,0 +1,7 @@
+import { ensureReferenceData } from "@/domains/sales/sales.repository";
+import { rdb } from "@/shared/database";
+
+/** Runs on every start: `ensureReferenceData` is idempotent and does nothing after the first. */
+export async function seedPlugin(): Promise<void> {
+  await ensureReferenceData(rdb);
+}

package/templates/m3e-app/src/plugins/sqlite.plugin.ts

@@ -0,0 +1,32 @@
+import { openDatabase } from "@/shared/database";
+
+const OPEN_TIMEOUT_MS = 10_000;
+
+/**
+ * Opening the database is the one thing that must succeed before the first screen renders, and the
+ * one thing that used to fail silently: awaited at the top level of `main.ts`, a rejection left an
+ * empty `#app` and nothing in the console. The timeout turns a hang into a message.
+ */
+export async function sqlitePlugin(): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  try {
+    await Promise.race([
+      openDatabase(),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () =>
+            reject(
+              new Error(`opening the database did not finish in ${String(OPEN_TIMEOUT_MS)}ms`),
+            ),
+          OPEN_TIMEOUT_MS,
+        );
+      }),
+    ]);
+  } finally {
+    // Losing the race does not stop the timer, which then held the event loop for the full timeout
+    // after a fast open. The walk itself is not cancellable, but `openDatabase` memoises it, so a
+    // retry joins the attempt already running instead of racing it for the same OPFS directory.
+    clearTimeout(timer);
+  }
+}

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

@@ -0,0 +1,12 @@
+import type { Router } from "framework7/types";
+import { lazyRoute } from "@/shared/utils/lazyRoute";
+
+const globalRoutes: Router.RouteParameters[] = [
+  {
+    name: "not-found",
+    path: "(.*)",
+    async: lazyRoute(() => import("@/shared/components/error/404.vue")),
+  },
+];
+
+export default globalRoutes;

package/templates/m3e-app/src/router/index.ts

@@ -0,0 +1,20 @@
+import type { Router } from "framework7/types";
+import homeRoutes from "@/modules/home/router/routes/home.routes";
+import demoRoutes from "@/modules/demo/router/routes/demo.routes";
+import galleryRoutes from "@/modules/gallery/router/routes/gallery.routes";
+import settingsRoutes from "@/modules/settings/router/routes/settings.routes";
+import globalRoutes from "./global/global.routes";
+
+/**
+ * Each module owns its routes; this only orders them. The catch-all is last because Framework7
+ * takes the first match.
+ */
+const routes: Router.RouteParameters[] = [
+  ...homeRoutes,
+  ...demoRoutes,
+  ...galleryRoutes,
+  ...settingsRoutes,
+  ...globalRoutes,
+];
+
+export default routes;

package/templates/m3e-app/src/shared/components/error/404.vue

@@ -0,0 +1,13 @@
+<template>
+  <AppPage :title="t('errors.notFoundTitle')" back>
+    <EmptyState
+      shape="ghostish"
+      :headline="t('errors.notFoundTitle')"
+      :text="t('errors.notFound')"
+    />
+  </AppPage>
+</template>
+
+<script setup lang="ts">
+const { t } = useI18n();
+</script>

package/templates/m3e-app/src/shared/components/layout/EmptyState.vue

@@ -0,0 +1,30 @@
+<template>
+  <section class="flex flex-col items-center gap-4 px-8 py-12 text-center">
+    <M3Shape
+      :shape="props.shape"
+      class="size-24 bg-secondary-container text-on-secondary-container"
+    >
+      <slot name="icon" />
+    </M3Shape>
+    <h3 class="type-title-large m-0 text-on-surface">{{ props.headline }}</h3>
+    <p v-if="props.text" class="type-body-medium m-0 max-w-80 text-on-surface-variant">
+      {{ props.text }}
+    </p>
+    <slot />
+  </section>
+</template>
+
+<script setup lang="ts">
+import type { MaterialShapeName } from "@cavulsqa/m3e";
+
+/**
+ * What a screen shows when it has nothing to show: a shape, one line that explains, and the one
+ * action that fills it. Never a paragraph, never placeholder rows.
+ */
+const props = withDefaults(
+  defineProps<{ headline: string; text?: string; shape?: MaterialShapeName }>(),
+  {
+    shape: "cookie9Sided",
+  },
+);
+</script>

package/templates/m3e-app/src/shared/components/layout/SectionHeader.vue

@@ -0,0 +1,10 @@
+<template>
+  <h2 class="type-title-small-emphasized px-6 pt-6 pb-2 text-primary">
+    <slot>{{ props.title }}</slot>
+  </h2>
+</template>
+
+<script setup lang="ts">
+/** The label above a group of content: M3's list subheader, in the primary role. */
+const props = defineProps<{ title?: string }>();
+</script>