falak-app-duo 1.3.0 → 1.3.1

package/README.md

@@ -13,7 +13,7 @@ integrations on the frontend side: **Ably** (realtime) and **Brevo**
 | Ably (realtime) | **New** — via Laravel Echo, authorized through the same API-key + user-token headers as the rest of the app |
 | Brevo (email/SMS) | Kept — calls go through Laravel, key never ships to the browser |
 | Laravel API auth | `X-API-Key` (app) + `Authorization: Bearer <token>` (user) |
-| AES-256 | Kept — encrypts the cached user token in localStorage |
+| AES-256 | Kept — encrypts the cached user token in IndexedDB |
 | Arabic/RTL | Kept — baked in via vue-i18n + postcss-rtlcss (opt-out: `--no-rtl` or the RTL prompt) |
 
 ## Install & run
@@ -43,7 +43,7 @@ Every request from `src/services/api.js` carries two headers:
 - `X-API-Key` — identifies this client app, set once per environment in `.env`.
 - `Authorization: Bearer <user token>` — identifies the logged-in user, issued
   by your Laravel `/auth/login` endpoint and stored AES-256 encrypted in
-  `localStorage` (see `src/utils/crypto.js` and `src/stores/auth.js`).
+  IndexedDB (see `src/utils/crypto.js`, `src/storage.js` and `src/stores/auth.js`).
 
 ## Ably (realtime)
 

package/bin/falak-app-duo

@@ -215,6 +215,7 @@ function buildI18nModule(locales, defaultLocale) {
   const ordered = ["ar", "en", "es", "de", "fr", "ru", "it"].filter((c) => locales.includes(c));
   const lines = [];
   lines.push('import { createI18n } from "vue-i18n";');
+  lines.push('import storage from "@/storage";');
   for (const code of ordered) {
     lines.push(`import ${code} from "./locales/${code}.json";`);
   }
@@ -226,27 +227,30 @@ function buildI18nModule(locales, defaultLocale) {
   lines.push("];");
   lines.push("");
   lines.push('const STORAGE_KEY = "falak_locale";');
-  lines.push("const stored = localStorage.getItem(STORAGE_KEY);");
-  lines.push(
-    `const savedLocale = SUPPORTED_LOCALES.some((l) => l.code === stored) ? stored : "${defaultLocale}";`
-  );
   lines.push("");
   lines.push("const i18n = createI18n({");
   lines.push("  legacy: false,");
-  lines.push("  locale: savedLocale,");
+  lines.push(`  locale: "${defaultLocale}",`);
   lines.push('  fallbackLocale: "en",');
   lines.push(`  messages: { ${ordered.join(", ")} },`);
   lines.push("});");
   lines.push("");
   lines.push("export function setLocale(locale) {");
   lines.push("  i18n.global.locale.value = locale;");
-  lines.push("  localStorage.setItem(STORAGE_KEY, locale);");
+  lines.push("  storage.set(STORAGE_KEY, locale);");
   lines.push("  document.documentElement.lang = locale;");
   lines.push('  document.documentElement.dir = locale === "ar" ? "rtl" : "ltr";');
   lines.push("}");
   lines.push("");
-  lines.push("// Apply on load");
-  lines.push("setLocale(savedLocale);");
+  lines.push("// Apply the persisted locale (falling back to the default) once storage is");
+  lines.push("// ready. main.js awaits this before mounting so the first paint is correct.");
+  lines.push("export async function initLocale() {");
+  lines.push("  const stored = await storage.get(STORAGE_KEY);");
+  lines.push(
+    `  const saved = SUPPORTED_LOCALES.some((l) => l.code === stored) ? stored : "${defaultLocale}";`
+  );
+  lines.push("  setLocale(saved);");
+  lines.push("}");
   lines.push("");
   lines.push("export default i18n;");
   lines.push("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "falak-app-duo",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Vue 3 boilerplate scaffolder — Ably (realtime), Brevo, AES-256, Arabic/RTL, and a Laravel API client (API key + user token auth). No Firebase, no Groq/Paymob on the frontend (Groq is backend-only; Paymob dropped).",
   "type": "module",
   "bin": {

package/templates/default/index.html

@@ -4,23 +4,24 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Falak App</title>
+    <style>
+      /* The theme is resolved from IndexedDB (async) before the app mounts;
+         keep the page hidden until then so the first paint is never the wrong
+         theme. main.js removes this class once the theme is applied. */
+      html.theme-loading {
+        visibility: hidden;
+      }
+    </style>
     <script>
-      // FOUC guard: paint with the right theme before the app mounts.
-      // Mirrors src/theme.js.getTheme() — keep in sync.
+      // Runs before first paint: hide the page until main.js has hydrated the
+      // IndexedDB store and applied the theme (see src/main.js).
       (function () {
-        var s;
-        try {
-          s = localStorage.getItem("falak_theme");
-        } catch (e) {}
-        if (s === "light") {
-          document.documentElement.classList.add("light");
-        } else if (s !== "dark") {
-          try {
-            if (window.matchMedia("(prefers-color-scheme: light)").matches) {
-              document.documentElement.classList.add("light");
-            }
-          } catch (e) {}
-        }
+        var el = document.documentElement;
+        el.classList.add("theme-loading");
+        // Safety net: never leave the page hidden if the app fails to boot.
+        setTimeout(function () {
+          el.classList.remove("theme-loading");
+        }, 3000);
       })();
     </script>
   </head>

package/templates/default/package.json

@@ -13,6 +13,7 @@
     "ably": "^2.5.0",
     "axios": "^1.7.7",
     "crypto-js": "^4.2.0",
+    "idb": "^8.0.0",
     "laravel-echo": "^1.16.1",
     "otplib": "^12.0.1",
     "pinia": "^2.2.2",

package/templates/default/src/assets/main.css

@@ -5,8 +5,8 @@
 /* ============================================================
    Theme tokens
    Dark is the default (no class on <html>); light is applied by
-   toggling `.light` on <html> (see src/theme.js + the FOUC guard
-   in index.html). Components use ONLY these semantic tokens — never
+   toggling `.light` on <html> (see src/theme.js + the `theme-loading`
+   guard in index.html). Components use ONLY these semantic tokens — never
    hardcoded dark-palette utilities — so a single var flip re-themes
    the whole app. Keep `html { }` (dark) and `html.light { }` in sync.
    ============================================================ */

package/templates/default/src/i18n/index.js

@@ -1,4 +1,5 @@
 import { createI18n } from "vue-i18n";
+import storage from "@/storage";
 import ar from "./locales/ar.json";
 import de from "./locales/de.json";
 import en from "./locales/en.json";
@@ -18,24 +19,27 @@ export const SUPPORTED_LOCALES = [
 ];
 
 const STORAGE_KEY = "falak_locale";
-const stored = localStorage.getItem(STORAGE_KEY);
-const savedLocale = SUPPORTED_LOCALES.some((l) => l.code === stored) ? stored : "ar";
 
 const i18n = createI18n({
   legacy: false,
-  locale: savedLocale,
+  locale: "ar",
   fallbackLocale: "en",
   messages: { ar, de, en, es, fr, it, ru },
 });
 
 export function setLocale(locale) {
   i18n.global.locale.value = locale;
-  localStorage.setItem(STORAGE_KEY, locale);
+  storage.set(STORAGE_KEY, locale);
   document.documentElement.lang = locale;
   document.documentElement.dir = locale === "ar" ? "rtl" : "ltr";
 }
 
-// Apply on load
-setLocale(savedLocale);
+// Apply the persisted locale (falling back to the default) once storage is
+// ready. main.js awaits this before mounting so the first paint is correct.
+export async function initLocale() {
+  const stored = await storage.get(STORAGE_KEY);
+  const saved = SUPPORTED_LOCALES.some((l) => l.code === stored) ? stored : "ar";
+  setLocale(saved);
+}
 
-export default i18n;
+export default i18n;

package/templates/default/src/main.js

@@ -5,24 +5,36 @@ import Aura from "@primeuix/themes/aura";
 import "primeicons/primeicons.css";
 import App from "./App.vue";
 import router from "./router";
-import i18n from "./i18n";
+import i18n, { initLocale } from "./i18n";
 import { initTheme } from "./theme";
+import { ready } from "./storage";
 import "./assets/main.css";
 
-initTheme();
+// Hydrate the IndexedDB store before mounting: the theme, locale and auth
+// token are read synchronously from its in-memory mirror, so this guarantees
+// the first paint has the right theme/language. The `theme-loading` class
+// (set in index.html) keeps the page hidden until now to avoid any flash.
+async function bootstrap() {
+  await ready();
+  initTheme();
+  await initLocale();
+  document.documentElement.classList.remove("theme-loading");
 
-const app = createApp(App);
+  const app = createApp(App);
 
-app.use(PrimeVue, {
-  theme: {
-    preset: Aura,
-    options: {
-      cssLayer: false,
+  app.use(PrimeVue, {
+    theme: {
+      preset: Aura,
+      options: {
+        cssLayer: false,
+      },
     },
-  },
-});
-app.use(createPinia());
-app.use(router);
-app.use(i18n);
+  });
+  app.use(createPinia());
+  app.use(router);
+  app.use(i18n);
 
-app.mount("#app");
+  app.mount("#app");
+}
+
+bootstrap();

package/templates/default/src/services/api.js

@@ -1,5 +1,6 @@
 import axios from "axios";
 import { decrypt } from "@/utils/crypto";
+import storage from "@/storage";
 
 /**
  * Central client for talking to the Laravel backend.
@@ -21,9 +22,10 @@ const api = axios.create({
 });
 
 api.interceptors.request.use((config) => {
-  // Read the token straight from storage (not the Pinia store) to avoid a
-  // circular import between this file and stores/auth.js.
-  const raw = localStorage.getItem("falak_user_token");
+  // Read the token from the in-memory mirror of the IndexedDB store (hydrated
+  // at boot) rather than the Pinia store, to avoid a circular import between
+  // this file and stores/auth.js.
+  const raw = storage.getSync("falak_user_token");
   if (raw) {
     const token = decrypt(raw);
     if (token) config.headers.Authorization = `Bearer ${token}`;

package/templates/default/src/services/demoApi.js

@@ -3,7 +3,7 @@
 // When VITE_DATA_MODE=demo the whole app runs on the bundled demo data with no
 // Laravel backend or network required. This module mirrors the same routes the
 // real API exposes — auth/me, auth/login, profile/settings writes, entity
-// lists — and serves them from a localStorage-backed database seeded from
+// lists — and serves them from an IndexedDB-backed database seeded from
 // src/data/demoAccounts.js and src/data/demo/*.js. Flip VITE_DATA_MODE=live and
 // the app talks to the real backend again (see services/api.js).
 //
@@ -11,6 +11,7 @@
 // file discovers them via import.meta.glob — only files that exist at build
 // time are bundled, and nothing breaks when ones are missing.
 import { decrypt } from "@/utils/crypto";
+import storage from "@/storage";
 
 const DB_KEY = "falak_demo_db";
 const TOKEN_KEY = "falak_user_token";
@@ -105,16 +106,16 @@ function fingerprint() {
 
 let db = null;
 
-function loadDB() {
+// Loaded lazily on the first request (always after storage.ready() has run at
+// boot, so the mirror already holds any persisted DB). Falls back to a fresh
+// seed when the stored fingerprint no longer matches the bundled data.
+function ensureDB() {
+  if (db) return db;
   const fp = fingerprint();
-  try {
-    const raw = JSON.parse(localStorage.getItem(DB_KEY) || "null");
-    if (raw && raw.fingerprint === fp) {
-      db = raw;
-      return db;
-    }
-  } catch {
-    // Fall through to a fresh seed.
+  const raw = storage.getSync(DB_KEY, null);
+  if (raw && raw.fingerprint === fp) {
+    db = raw;
+    return db;
   }
   const collections = buildCollections();
   db = { fingerprint: fp, accounts: buildSeedAccounts(collections), collections };
@@ -123,15 +124,10 @@ function loadDB() {
 }
 
 function persist() {
-  try {
-    localStorage.setItem(DB_KEY, JSON.stringify(db));
-  } catch {
-    // Quota/storage unavailable — keep running in-memory only.
-  }
+  // Mirror updates synchronously; IndexedDB write happens in the background.
+  storage.set(DB_KEY, db);
 }
 
-loadDB();
-
 function fail(message, status = 400) {
   const error = new Error(message);
   error.response = { status, data: { message } };
@@ -139,7 +135,7 @@ function fail(message, status = 400) {
 }
 
 function tokenFromStorage() {
-  const raw = localStorage.getItem(TOKEN_KEY);
+  const raw = storage.getSync(TOKEN_KEY);
   if (!raw) return null;
   const token = decrypt(raw);
   const match = /^demo\.(\d+)$/.exec(token || "");
@@ -148,7 +144,7 @@ function tokenFromStorage() {
 
 function requireAccount() {
   const id = tokenFromStorage();
-  const account = id && db.accounts.find((a) => String(a.id) === String(id));
+  const account = id && ensureDB().accounts.find((a) => String(a.id) === String(id));
   if (!account) fail("Unauthenticated", 401);
   return account;
 }
@@ -225,6 +221,7 @@ function overview() {
 
 const demoApi = {
   async get(url) {
+    ensureDB();
     const path = (url || "").split("?")[0];
     if (path === "/auth/me") return { data: publicUser(requireAccount()) };
     if (path === "/overview") return { data: overview() };
@@ -234,6 +231,7 @@ const demoApi = {
   },
 
   async post(url, body = {}) {
+    ensureDB();
     const path = (url || "").split("?")[0];
     switch (path) {
       case "/auth/login": {
@@ -331,6 +329,7 @@ const demoApi = {
   },
 
   async put(url, body = {}) {
+    ensureDB();
     const path = (url || "").split("?")[0];
     if (path === "/auth/me") {
       const account = requireAccount();
@@ -371,6 +370,7 @@ const demoApi = {
   },
 
   async delete(url) {
+    ensureDB();
     const entity = matchEntity((url || "").split("?")[0]);
     if (entity?.id !== null) {
       const rows = getEntityRows(entity.name);

package/templates/default/src/storage.js

@@ -0,0 +1,86 @@
+// Single IndexedDB-backed key/value store for every piece of client-side
+// persistence (auth token, locale, theme, remembered login, demo database).
+// The app never uses localStorage/sessionStorage.
+//
+// IndexedDB is asynchronous, but a few call sites need a value synchronously
+// (the axios Authorization header, the theme applied in App.vue). To support
+// that we keep an in-memory mirror of every key and hydrate it once at boot
+// via `ready()` — main.js awaits it before mounting. `getSync` then reads the
+// mirror. Writes update the mirror immediately and persist to IndexedDB in the
+// background, so the UI never blocks on disk.
+import { openDB } from "idb";
+
+const DB_NAME = "falak_app";
+const STORE_NAME = "kv";
+const DB_VERSION = 1;
+
+let dbPromise = null;
+function getDB() {
+  if (!dbPromise) {
+    dbPromise = openDB(DB_NAME, DB_VERSION, {
+      upgrade(db) {
+        if (!db.objectStoreNames.contains(STORE_NAME)) db.createObjectStore(STORE_NAME);
+      },
+    });
+  }
+  return dbPromise;
+}
+
+const mirror = new Map();
+let readyPromise = null;
+
+async function hydrate() {
+  try {
+    const db = await getDB();
+    const keys = await db.getAllKeys(STORE_NAME);
+    const values = await db.getAll(STORE_NAME);
+    keys.forEach((key, index) => {
+      // Don't clobber a value written while hydration was in flight.
+      if (!mirror.has(key)) mirror.set(key, values[index]);
+    });
+  } catch {
+    // IndexedDB unavailable (private mode / SSR / tests) — stay in-memory.
+  }
+}
+
+// Resolves once the mirror has been populated from IndexedDB.
+export function ready() {
+  if (!readyPromise) readyPromise = hydrate();
+  return readyPromise;
+}
+
+// Synchronous read from the in-memory mirror (populated after ready()).
+export function getSync(key, fallback = null) {
+  return mirror.has(key) ? mirror.get(key) : fallback;
+}
+
+// Asynchronous read — always reflects the persisted value.
+export async function get(key, fallback = null) {
+  await ready();
+  return mirror.has(key) ? mirror.get(key) : fallback;
+}
+
+export async function set(key, value) {
+  mirror.set(key, value);
+  await ready();
+  try {
+    const db = await getDB();
+    await db.put(STORE_NAME, value, key);
+  } catch {
+    // Persist failed — the in-memory mirror still holds the value.
+  }
+}
+
+export async function remove(key) {
+  mirror.delete(key);
+  await ready();
+  try {
+    const db = await getDB();
+    await db.delete(STORE_NAME, key);
+  } catch {
+    // Nothing persisted to remove.
+  }
+}
+
+const storage = { ready, get, getSync, set, remove };
+export default storage;

package/templates/default/src/stores/auth.js

@@ -1,11 +1,12 @@
 import { defineStore } from "pinia";
 import { encrypt, decrypt } from "@/utils/crypto";
 import { client } from "@/services/dataClient";
+import storage from "@/storage";
 
 const STORAGE_KEY = "falak_user_token";
 
 function loadToken() {
-  const raw = localStorage.getItem(STORAGE_KEY);
+  const raw = storage.getSync(STORAGE_KEY);
   if (!raw) return null;
   try {
     return decrypt(raw) || null;
@@ -27,12 +28,12 @@ export const useAuthStore = defineStore("auth", {
   actions: {
     setToken(token) {
       this.userToken = token;
-      localStorage.setItem(STORAGE_KEY, encrypt(token));
+      storage.set(STORAGE_KEY, encrypt(token));
     },
     clearToken() {
       this.userToken = null;
       this.user = null;
-      localStorage.removeItem(STORAGE_KEY);
+      storage.remove(STORAGE_KEY);
     },
     // Two-header auth: X-API-Key identifies the *app*, Authorization Bearer
     // identifies the *user*. Both are required by the Laravel API middleware.

package/templates/default/src/theme.js

@@ -1,11 +1,15 @@
 // Light/dark theme. Dark is the default (no class); light adds `.light` on
-// <html> (tokens in assets/main.css flip). Choice persists in localStorage;
-// before any stored choice we follow the OS preference. The tiny duplicated
-// logic in index.html <head> runs first to avoid a flash of the wrong theme.
+// <html> (tokens in assets/main.css flip). The choice persists in IndexedDB
+// (src/storage.js); before any stored choice we follow the OS preference.
+// main.js awaits storage.ready() before initTheme(), so getSync() sees the
+// persisted value; index.html keeps the page hidden until then to avoid a flash
+// of the wrong theme.
+import storage from "@/storage";
+
 const KEY = "falak_theme";
 
 export function getTheme() {
-  const stored = localStorage.getItem(KEY);
+  const stored = storage.getSync(KEY);
   if (stored === "light" || stored === "dark") return stored;
   if (window.matchMedia?.("(prefers-color-scheme: light)").matches) return "light";
   return "dark";
@@ -20,7 +24,7 @@ export function initTheme() {
 }
 
 export function setTheme(theme) {
-  localStorage.setItem(KEY, theme);
+  storage.set(KEY, theme);
   applyTheme(theme);
 }
 
@@ -28,4 +32,4 @@ export function toggleTheme() {
   const next = getTheme() === "light" ? "dark" : "light";
   setTheme(next);
   return next;
-}
+}

package/templates/default/src/utils/crypto.js

@@ -1,8 +1,9 @@
 import CryptoJS from "crypto-js";
 
 // AES-256-CBC, key/IV pulled from .env (generated fresh per-project by the CLI).
-// Use this for encrypting sensitive values you must keep in localStorage/sessionStorage
-// (e.g. a cached user token) — never for anything you'd rather the backend handle.
+// Use this for encrypting sensitive values you must keep client-side
+// (e.g. the cached user token in the IndexedDB store, src/storage.js) — never
+// for anything you'd rather the backend handle.
 const KEY = CryptoJS.enc.Hex.parse(import.meta.env.VITE_AES_KEY || "");
 const IV = CryptoJS.enc.Hex.parse(import.meta.env.VITE_AES_IV || "");
 

package/templates/default/src/views/Login.vue

@@ -7,6 +7,7 @@ import AuthLayout from "@/components/AuthLayout.vue";
 import SocialIcon from "@/components/SocialIcon.vue";
 import { useRipple } from "@/composables/useRipple";
 import { isDemoMode, client } from "@/services/dataClient";
+import storage from "@/storage";
 
 const { t } = useI18n();
 const router = useRouter();
@@ -38,7 +39,7 @@ onMounted(async () => {
   }
 });
 
-const savedIdentifier = localStorage.getItem(REMEMBER_KEY) || "";
+const savedIdentifier = storage.getSync(REMEMBER_KEY, "") || "";
 if (savedIdentifier) {
   identifier.value = savedIdentifier;
   remember.value = true;
@@ -46,8 +47,8 @@ if (savedIdentifier) {
 }
 
 watch(remember, (on) => {
-  if (on) localStorage.setItem(REMEMBER_KEY, identifier.value);
-  else localStorage.removeItem(REMEMBER_KEY);
+  if (on) storage.set(REMEMBER_KEY, identifier.value);
+  else storage.remove(REMEMBER_KEY);
 });
 
 async function submit() {
@@ -55,8 +56,8 @@ async function submit() {
   loading.value = true;
   try {
     await auth.login(identifier.value, password.value);
-    if (remember.value) localStorage.setItem(REMEMBER_KEY, identifier.value);
-    else localStorage.removeItem(REMEMBER_KEY);
+    if (remember.value) storage.set(REMEMBER_KEY, identifier.value);
+    else storage.remove(REMEMBER_KEY);
     router.push({ name: "home" });
   } catch (e) {
     error.value = t("auth.loginError");