Core Refactor Initiative

This repository remains a single Vite + React codebase for desktop web, mobile web/PWA, and Capacitor native wrappers.

What was added in this step

• Capacitor dependency wiring in package.json
• Capacitor config in capacitor.config.ts (uses Vite dist/ output)
• Scripts to add/sync/open Android and iOS projects (all via npx --no-install cap so no global cap binary is required and commands only use the local CLI install)
• Safe platform detection helpers in src/platform/runtime.ts

No desktop layout/navigation/business-logic rewrite is included.

Install dependencies

npm install

Run web (unchanged)

npm run dev
npm run build
npm run preview

Source integrity safeguards (code generation / patch pipeline)

• npm run guard:generated -- <file...> validates .ts/.tsx/.js/.jsx files for:
  • banned narrative phrases ("The user is", "I need to", "continue where", "previous response")
  • markdown-like contamination
  • TypeScript/JSX parse errors (AST-level syntax diagnostics)
• scripts/safe-source-write.mjs performs the same validation before writing content to a source file; if parsing/sanitization fails it aborts the write.
• npm run build now enforces TypeScript preflight (tsc --noEmit) before vite build.
• npm run guard:precommit validates staged source files, and when critical UI files are staged (src/pages/OrdersPage.tsx, src/pages/MerchantsPage.tsx, src/components/*) it also runs:
  • npm run typecheck
  • npm run build:dry-run

Capacitor setup (Android + iOS)

Create native projects once:

npm run cap:add:android
npm run cap:add:ios

Sync web build into native projects:

npm run cap:sync

Open native IDE projects:

npm run cap:android
npm run cap:ios

Host prerequisites for native validation

• Node modules must be installable from your configured package registry (must allow @capacitor/* packages).
• Android validation requires Android Studio + Android SDK.
• iOS validation requires macOS + Xcode (cannot be fully validated on Linux hosts).

Platform helper usage

Use src/platform/runtime.ts utilities for guarded checks:

• isNativeApp()
• isAndroid()
• isIOS()
• isWebBrowser()

Keep native-only behavior behind these checks so browser desktop remains unaffected.

Mandatory mobile app installation

Once a user is signed in on a mobile browser (iOS or Android), a blocking install gate appears — the app must be installed before it can be used on a phone or tablet. The policy lives in src/platform/install-gate.ts and is rendered by src/components/shared/MobileInstallPrompt.tsx:

• Signed out → no gate, so the login flow always works in the browser.
• Capacitor native shell or an installed PWA launched from the home screen → no gate.
• Mobile browser → hard gate: no "continue in browser", and any previously stored skip is cleared. After installing, the browser tab stays blocked and asks the user to relaunch from the home screen.
• In-app browsers (Facebook, Instagram, Android WebView, …) cannot install a PWA, so the gate tells the user to reopen the link in Chrome/Safari and offers a copy-link button.
• Edge on Android only adds a home-screen shortcut when it cannot offer a real install prompt. That shortcut opens in a browser tab and never satisfies the gate, so the gate hands off to Chrome via an intent://…;package=com.android.chrome link, which installs a real WebAPK. Desktop Edge installs a proper app window and is unaffected.

How "already installed" is detected

Inside a normal browser tab display-mode is always browser, even when the app is installed — so standalone detection alone reports "not installed" forever. The gate also calls navigator.getInstalledRelatedApps(), which needs related_applications in the manifest (declared in vite.config.ts, pointing at the production origin). Override the origin per environment with PWA_ORIGIN=https://your-domain at build time, otherwise the call cannot match and detection silently falls back to standalone-only.

Detection runs on mount, on tab focus, and on the "I've installed it — recheck" button. isInstalledPwa() accepts standalone, minimal-ui, fullscreen and window-controls-overlay display modes, iOS navigator.standalone, and the android-app:// referrer set by WebAPK launches — a plain shortcut matches none of these, which is exactly the distinction that keeps shortcuts from passing as installs.

• Desktop browser → soft prompt, unchanged: install is offered but the user may continue in the browser.

Set VITE_FORCE_MOBILE_INSTALL=false at build time to fall back to the soft prompt on mobile (kill switch for fleets on browsers that cannot install a PWA). Append ?pwa_debug=1 to any URL to see the resolved gate state.

Native pipeline validation checklist

Run these commands in order to validate native pipeline readiness:

npm run build
test -f dist/index.html
npx cap sync

If platform folders are missing, generate them once:

Note: Native android/ and ios/ projects are generated locally via Capacitor commands and are not committed to this repository to avoid binary artifacts in PRs.

npx cap add android
npx cap add ios

Auth redirect configuration (Supabase / OAuth provider)

For this app's auth to work reliably across web + Capacitor Android, configure all of these redirect URLs in your Supabase Auth settings (and any provider allow-list if required):

• Web production callback: https://<your-production-domain>/auth/callback
• Local web callback: http://localhost:5173/auth/callback
• Local web password reset callback: http://localhost:5173/reset-password
• Capacitor Android OAuth callback: com.taheito26sys.corerefactorinitiative://login-callback
• Capacitor Android password reset callback: com.taheito26sys.corerefactorinitiative://reset-password-callback

Implementation notes:

• Web runtime uses web URLs (/auth/callback, /reset-password).
• Capacitor native runtime uses deep links with the app scheme (com.taheito26sys.corerefactorinitiative://...).
• Android receives those deep links via AndroidManifest.xml intent filters and routes back into the SPA callback routes.