feat: self-guided onboarding Learning Path (Beginner to Advanced)

.env.production

@@ -0,0 +1,2 @@
+VITE_API_DOMAIN=api.openfront.io
+VITE_WS_HOST=openfront.io

.gitignore

@@ -7,6 +7,7 @@ TODO.txt
 resources/images/.DS_Store
 resources/.DS_Store
 .env*
+!.env.production
 .DS_Store
 .clinic/
 NOTES.md

index.html

@@ -253,6 +253,12 @@
           inline
           class="hidden w-full h-full page-content relative z-50"
         ></help-modal>
+        <onboarding-modal
+          id="page-onboarding"
+          inline
+          class="hidden w-full h-full page-content relative z-50"
+        ></onboarding-modal>
+        <tour-overlay id="tour-overlay"></tour-overlay>
         <language-modal
           id="page-language"
           inline

src/client/Api.ts

@@ -170,6 +170,13 @@ export async function createCheckoutSession(
 }
 
 export function getApiBase() {
+  const viteApiDomain = (
+    import.meta as unknown as { env?: Record<string, string> }
+  ).env?.VITE_API_DOMAIN;
+  if (viteApiDomain) {
+    return `https://${viteApiDomain}`;
+  }
+
   const domainname = getAudience();
 
   if (domainname === "localhost") {

src/client/ClientGameRunner.ts

@@ -432,6 +432,8 @@ export class ClientGameRunner {
         this.eventBus.emit(new SendHashEvent(hu.tick, hu.hash));
       });
       this.gameView.update(gu);
+      (window as unknown as Record<string, unknown>).__tourGameView =
+        this.gameView;
       this.renderer.tick();
 
       // Emit tick metrics event for performance overlay
@@ -611,6 +613,7 @@ export class ClientGameRunner {
       !this.gameView.config().isRandomSpawn()
     ) {
       this.eventBus.emit(new SendSpawnIntentEvent(tile));
+      window.dispatchEvent(new CustomEvent("tour:spawn-clicked"));
       return;
     }
     if (this.gameView.inSpawnPhase()) {
@@ -850,6 +853,7 @@ export class ClientGameRunner {
         this.eventBus.emit(
           new SendAllianceRequestIntentEvent(myPlayer, recipient),
         );
+        window.dispatchEvent(new CustomEvent("tour:alliance-sent"));
       }
     });
   }

src/client/LobbySocket.ts

@@ -54,7 +54,10 @@ export class PublicLobbySocket {
       }
 
       const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
-      const wsUrl = `${protocol}//${window.location.host}${this.workerPath}/lobbies`;
+      const wsHost =
+        (import.meta as unknown as { env?: Record<string, string> }).env
+          ?.VITE_WS_HOST ?? window.location.host;
+      const wsUrl = `${protocol}//${wsHost}${this.workerPath}/lobbies`;
 
       this.ws = new WebSocket(wsUrl);
       this.wsAttemptCounted = false;

src/client/Main.ts

@@ -34,6 +34,9 @@
 import { GameStartingModal } from "./GameStartingModal";
 import "./GoogleAdElement";
 import { HelpModal } from "./HelpModal";
+import { hasSeenOnboarding, OnboardingModal } from "./OnboardingModal";
+import "./TourOverlay";
+import { getTourOverlay } from "./TourOverlay";
 import "./HomepagePromos";
 import { HostLobbyModal as HostPrivateLobbyModal } from "./HostLobbyModal";
 import { JoinLobbyModal } from "./JoinLobbyModal";
@@ -1019,6 +1022,20 @@
   new Client().initialize();
   initNavigation();
 
+  // Auto-open onboarding for first-time visitors
+  if (!hasSeenOnboarding()) {
+    setTimeout(() => {
+      window.showPage?.("page-onboarding");
+    }, 600);
+  }
+
+  // Wire up the onboarding nav button (desktop + mobile)
+  document.querySelectorAll("[data-action='open-onboarding']").forEach((btn) => {
+    btn.addEventListener("click", () => {
+      window.showPage?.("page-onboarding");
+    });
+  });
+
   // Hide elements immediately
   hideCrazyGamesElements();