@energy8platform/game-engine 0.2.0 → 0.3.0

package/src/core/GameApplication.ts

@@ -11,6 +11,7 @@ import { InputManager } from '../input/InputManager';
 import { ViewportManager } from '../viewport/ViewportManager';
 import { LoadingScene } from '../loading/LoadingScene';
 import { createCSSPreloader, removeCSSPreloader } from '../loading/CSSPreloader';
+import { FPSOverlay } from '../debug/FPSOverlay';
 
 /**
  * The main entry point for a game built on @energy8platform/game-engine.
@@ -67,6 +68,9 @@ export class GameApplication extends EventEmitter<GameEngineEvents> {
   /** SDK instance (null in offline mode) */
   public sdk: CasinoGameSDK | null = null;
 
+  /** FPS overlay instance (only when debug: true) */
+  public fpsOverlay: FPSOverlay | null = null;
+
   /** Data received from SDK initialization */
   public initData: InitData | null = null;
 
@@ -154,7 +158,7 @@ export class GameApplication extends EventEmitter<GameEngineEvents> {
       // 6. Initialize sub-systems
       this.initSubSystems();
 
-      this.emit('initialized', undefined as any);
+      this.emit('initialized');
 
       // 7. Remove CSS preloader, show Canvas loading screen
       removeCSSPreloader(this._container);
@@ -162,9 +166,11 @@ export class GameApplication extends EventEmitter<GameEngineEvents> {
       // 8. Load assets with loading screen
       await this.loadAssets(firstScene, sceneData);
 
+      this.emit('loaded');
+
       // 9. Start the game loop
       this._running = true;
-      this.emit('started', undefined as any);
+      this.emit('started');
     } catch (err) {
       console.error('[GameEngine] Failed to start:', err);
       this.emit('error', err instanceof Error ? err : new Error(String(err)));
@@ -186,9 +192,9 @@ export class GameApplication extends EventEmitter<GameEngineEvents> {
     this.viewport?.destroy();
     this.sdk?.destroy();
     this.app?.destroy(true, { children: true, texture: true });
-    this.removeAllListeners();
 
-    this.emit('destroyed', undefined as any);
+    this.emit('destroyed');
+    this.removeAllListeners();
   }
 
   // ─── Private initialization steps ──────────────────────
@@ -280,9 +286,10 @@ export class GameApplication extends EventEmitter<GameEngineEvents> {
     // Wire SceneManager to the PixiJS stage
     this.scenes.setRoot(this.app.stage);
 
-    // Wire viewport resize → scene manager
-    this.viewport.on('resize', ({ width, height }) => {
+    // Wire viewport resize → scene manager + input manager
+    this.viewport.on('resize', ({ width, height, scale }) => {
       this.scenes.resize(width, height);
+      this.input.setViewportTransform(scale, this.app.stage.x, this.app.stage.y);
       this.emit('resize', { width, height });
     });
 
@@ -290,6 +297,11 @@ export class GameApplication extends EventEmitter<GameEngineEvents> {
       this.emit('orientationChange', orientation);
     });
 
+    // Wire scene changes → engine event
+    this.scenes.on('change', ({ from, to }) => {
+      this.emit('sceneChange', { from, to });
+    });
+
     // Connect ticker → scene updates
     this.app.ticker.add((ticker) => {
       // Always update scenes (loading screen needs onUpdate before _running=true)
@@ -298,11 +310,17 @@ export class GameApplication extends EventEmitter<GameEngineEvents> {
 
     // Trigger initial resize
     this.viewport.refresh();
+
+    // Enable FPS overlay in debug mode
+    if (this.config.debug) {
+      this.fpsOverlay = new FPSOverlay(this.app);
+      this.fpsOverlay.show();
+    }
   }
 
   private async loadAssets(firstScene: string, sceneData?: unknown): Promise<void> {
     // Register built-in loading scene
-    this.scenes.register('__loading__', LoadingScene as any);
+    this.scenes.register('__loading__', LoadingScene);
 
     // Enter loading scene
     await this.scenes.goto('__loading__', {

package/src/core/SceneManager.ts

@@ -190,9 +190,11 @@ export class SceneManager extends EventEmitter<SceneManagerEvents> {
     // Transition in
     await this.transitionIn(scene.container, transition);
 
+    // Push to stack BEFORE onEnter so currentKey is correct during initialization
+    this.stack.push({ scene, key });
+
     await scene.onEnter?.(data);
 
-    this.stack.push({ scene, key });
     this._transitioning = false;
   }
 

package/src/debug/DevBridge.ts

@@ -1,8 +1,10 @@
-import type {
-  InitData,
-  GameConfigData,
-  PlayResultData,
-  SessionData,
+import {
+  Bridge,
+  type BridgeMessageType,
+  type InitData,
+  type GameConfigData,
+  type PlayResultData,
+  type SessionData,
 } from '@energy8platform/game-sdk';
 
 export interface DevBridgeConfig {
@@ -44,8 +46,9 @@ const DEFAULT_CONFIG: Required<DevBridgeConfig> = {
 /**
  * Mock host bridge for local development.
  *
- * Intercepts postMessage communication from the SDK and responds
- * with mock data, simulating a real casino host environment.
+ * Uses the SDK's `Bridge` class in `devMode` to communicate with
+ * `CasinoGameSDK` via a shared in-memory `MemoryChannel`, removing
+ * the need for postMessage and iframes.
  *
  * This allows games to be developed and tested without a real backend.
  *
@@ -73,8 +76,7 @@ export class DevBridge {
   private _config: Required<DevBridgeConfig>;
   private _balance: number;
   private _roundCounter = 0;
-  private _listening = false;
-  private _handler: ((e: MessageEvent) => void) | null = null;
+  private _bridge: Bridge | null = null;
 
   constructor(config: DevBridgeConfig = {}) {
     this._config = { ...DEFAULT_CONFIG, ...config };
@@ -88,27 +90,47 @@ export class DevBridge {
 
   /** Start listening for SDK messages */
   start(): void {
-    if (this._listening) return;
+    if (this._bridge) return;
 
-    this._handler = (e: MessageEvent) => {
-      this.handleMessage(e);
-    };
+    console.debug('[DevBridge] Starting with config:', this._config);
+
+    this._bridge = new Bridge({ devMode: true, debug: this._config.debug });
+
+    this._bridge.on('GAME_READY', (_payload: unknown, id?: string) => {
+      this.handleGameReady(id);
+    });
+
+    this._bridge.on('PLAY_REQUEST', (payload: { action: string; bet: number; roundId?: string }, id?: string) => {
+      this.handlePlayRequest(payload, id);
+    });
+
+    this._bridge.on('PLAY_RESULT_ACK', (payload: unknown) => {
+      this.handlePlayAck(payload);
+    });
+
+    this._bridge.on('GET_BALANCE', (_payload: unknown, id?: string) => {
+      this.handleGetBalance(id);
+    });
 
-    window.addEventListener('message', this._handler);
-    this._listening = true;
+    this._bridge.on('GET_STATE', (_payload: unknown, id?: string) => {
+      this.handleGetState(id);
+    });
+
+    this._bridge.on('OPEN_DEPOSIT', () => {
+      this.handleOpenDeposit();
+    });
 
     if (this._config.debug) {
-      console.log('[DevBridge] Started — listening for SDK messages');
+      console.log('[DevBridge] Started — listening via Bridge (devMode)');
     }
   }
 
   /** Stop listening */
   stop(): void {
-    if (this._handler) {
-      window.removeEventListener('message', this._handler);
-      this._handler = null;
+    if (this._bridge) {
+      this._bridge.destroy();
+      this._bridge = null;
     }
-    this._listening = false;
 
     if (this._config.debug) {
       console.log('[DevBridge] Stopped');
@@ -118,8 +140,7 @@ export class DevBridge {
   /** Set mock balance */
   setBalance(balance: number): void {
     this._balance = balance;
-    // Send balance update
-    this.sendMessage('BALANCE_UPDATE', { balance: this._balance });
+    this._bridge?.send('BALANCE_UPDATE', { balance: this._balance });
   }
 
   /** Destroy the dev bridge */
@@ -129,42 +150,6 @@ export class DevBridge {
 
   // ─── Message Handling ──────────────────────────────────
 
-  private handleMessage(e: MessageEvent): void {
-    const data = e.data;
-
-    // Only process bridge messages
-    if (!data || data.__casino_bridge !== true) return;
-
-    if (this._config.debug) {
-      console.log('[DevBridge] ←', data.type, data.payload);
-    }
-
-    switch (data.type) {
-      case 'GAME_READY':
-        this.handleGameReady(data.id);
-        break;
-      case 'PLAY_REQUEST':
-        this.handlePlayRequest(data.payload, data.id);
-        break;
-      case 'PLAY_RESULT_ACK':
-        this.handlePlayAck(data.payload, data.id);
-        break;
-      case 'GET_BALANCE':
-        this.handleGetBalance(data.id);
-        break;
-      case 'GET_STATE':
-        this.handleGetState(data.id);
-        break;
-      case 'OPEN_DEPOSIT':
-        this.handleOpenDeposit();
-        break;
-      default:
-        if (this._config.debug) {
-          console.log('[DevBridge] Unknown message type:', data.type);
-        }
-    }
-  }
-
   private handleGameReady(id?: string): void {
     const initData: InitData = {
       balance: this._balance,
@@ -208,14 +193,14 @@ export class DevBridge {
     this.delayedSend('PLAY_RESULT', result, id);
   }
 
-  private handlePlayAck(_payload: unknown, _id?: string): void {
+  private handlePlayAck(_payload: unknown): void {
     if (this._config.debug) {
       console.log('[DevBridge] Play acknowledged');
     }
   }
 
   private handleGetBalance(id?: string): void {
-    this.delayedSend('BALANCE_RESPONSE', { balance: this._balance }, id);
+    this.delayedSend('BALANCE_UPDATE', { balance: this._balance }, id);
   }
 
   private handleGetState(id?: string): void {
@@ -227,33 +212,17 @@ export class DevBridge {
       console.log('[DevBridge] 💰 Open deposit requested (mock: adding 1000)');
     }
     this._balance += 1000;
-    this.sendMessage('BALANCE_UPDATE', { balance: this._balance });
+    this._bridge?.send('BALANCE_UPDATE', { balance: this._balance });
   }
 
   // ─── Communication ─────────────────────────────────────
 
-  private delayedSend(type: string, payload: unknown, id?: string): void {
+  private delayedSend(type: BridgeMessageType, payload: unknown, id?: string): void {
     const delay = this._config.networkDelay;
     if (delay > 0) {
-      setTimeout(() => this.sendMessage(type, payload, id), delay);
+      setTimeout(() => this._bridge?.send(type, payload, id), delay);
     } else {
-      this.sendMessage(type, payload, id);
+      this._bridge?.send(type, payload, id);
     }
   }
-
-  private sendMessage(type: string, payload: unknown, id?: string): void {
-    const message = {
-      __casino_bridge: true,
-      type,
-      payload,
-      id,
-    };
-
-    if (this._config.debug) {
-      console.log('[DevBridge] →', type, payload);
-    }
-
-    // Post to the same window (SDK listens on window)
-    window.postMessage(message, '*');
-  }
 }

package/src/index.ts

@@ -48,6 +48,8 @@ export { Tween } from './animation/Tween';
 export { Timeline } from './animation/Timeline';
 export { Easing } from './animation/Easing';
 export { SpineHelper } from './animation/SpineHelper';
+export { SpriteAnimation } from './animation/SpriteAnimation';
+export type { SpriteAnimationConfig } from './animation/SpriteAnimation';
 
 // ─── Input ───────────────────────────────────────────────
 export { InputManager } from './input/InputManager';
@@ -61,6 +63,10 @@ export { BalanceDisplay } from './ui/BalanceDisplay';
 export { WinDisplay } from './ui/WinDisplay';
 export { Modal } from './ui/Modal';
 export { Toast } from './ui/Toast';
+export { Layout } from './ui/Layout';
+export type { LayoutConfig, LayoutDirection, LayoutAlignment, LayoutAnchor } from './ui/Layout';
+export { ScrollContainer } from './ui/ScrollContainer';
+export type { ScrollContainerConfig, ScrollDirection } from './ui/ScrollContainer';
 
 // ─── Loading ─────────────────────────────────────────────
 export { LoadingScene } from './loading/LoadingScene';

package/src/input/InputManager.ts

@@ -41,6 +41,11 @@ export class InputManager extends EventEmitter<InputEvents> {
   private _keysDown = new Set<string>();
   private _destroyed = false;
 
+  // Viewport transform (set by ViewportManager via setViewportTransform)
+  private _viewportScale = 1;
+  private _viewportOffsetX = 0;
+  private _viewportOffsetY = 0;
+
   // Gesture tracking
   private _pointerStart: { x: number; y: number; time: number } | null = null;
   private _swipeThreshold = 50; // minimum distance in px
@@ -73,6 +78,27 @@ export class InputManager extends EventEmitter<InputEvents> {
     return this._keysDown.has(key.toLowerCase());
   }
 
+  /**
+   * Update the viewport transform used for DOM→world coordinate mapping.
+   * Called automatically by GameApplication when ViewportManager emits resize.
+   */
+  setViewportTransform(scale: number, offsetX: number, offsetY: number): void {
+    this._viewportScale = scale;
+    this._viewportOffsetX = offsetX;
+    this._viewportOffsetY = offsetY;
+  }
+
+  /**
+   * Convert a DOM canvas position to game-world coordinates,
+   * accounting for viewport scaling and offset.
+   */
+  getWorldPosition(canvasX: number, canvasY: number): { x: number; y: number } {
+    return {
+      x: (canvasX - this._viewportOffsetX) / this._viewportScale,
+      y: (canvasY - this._viewportOffsetY) / this._viewportScale,
+    };
+  }
+
   /** Destroy the input manager */
   destroy(): void {
     this._destroyed = true;

package/src/loading/CSSPreloader.ts

@@ -1,4 +1,5 @@
 import type { LoadingScreenConfig } from '../types';
+import { buildLogoSVG } from './logo';
 
 const PRELOADER_ID = '__ge-css-preloader__';
 
@@ -6,39 +7,12 @@ const PRELOADER_ID = '__ge-css-preloader__';
  * Inline SVG logo with animated loader bar.
  * The `#loader` path acts as the progress fill — animated via clipPath.
  */
-const LOGO_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 250 200" fill="none" class="ge-logo-svg">
-  <path d="m241 81.75h-19.28c-1.77 0-6.73 4.98-7.43 6.99l-4.36 12.22c-0.49 1.37 0.05 2.92 1.06 4.32-2.07 1.19-3.69 3.08-4.36 5.43l-3.25 10.41c-0.86 2.89 2.39 6.63 4.31 6.63h19.28c1.96 0 7.4-5.56 7.96-7.51l2.96-10.22c0.63-2.25 0.1-3.98-1.22-4.99 2.55-1.56 3.86-4.14 4.55-6.31l2.77-9.31c0.74-2.57-1.37-7.66-2.99-7.66zm-13.36 28.31-2.27 7.03h-8.28l2.58-8.28h8.28l-0.31 1.25zm4.06-16.97-2.11 6.7h-7.04l2.25-7.34h7.26l-0.36 0.64z" fill="url(#pl0)"/>
-  <path d="m202.5 81.75-9.31 14.97-2.32-14.97h-11.82l4.32 25.15-0.57 4.91-8.64 26.44 15.31-12.76 5.63-16.48 19.96-27.26h-12.56z" fill="url(#pl1)"/>
-  <path d="m174.2 81.75h-19.78l-5.75 5.16-10.79 33.2c-0.77 2.53 2.48 6.93 4.87 6.93h17.38c2.63 0 7.85-5.34 8.32-6.83l5.37-18.14h-15.17l-2.2 7.64h3.78l-2.25 7.2h-8.01l7.1-25.52h7.58l-1.48 8.4 12.78-5.98c1.28-0.63 1.97-3.99 1.61-6.61-0.36-2.34-1.64-5.45-3.36-5.45z" fill="url(#pl2)"/>
-  <path d="m140.6 81.75h-70.6l-5.36 19.37-4.26-19.37h-46.76l2.95 5.88-10.58 39.28h26.84l2.95-9.52-15.63-0.13 2.55-8.34h8.74l8.47-9.81h-14.61l2.11-7.3h15.47l2.54-8.71 2.58 4.74-11.4 39.07h11.05l6.46-21.49 8.84 36.33 19.18-55.67-1.83-3.36 3.68 4.09-12.07 40.1h28.18l3.39-10.31h-17.01l2.67-8.03h9.98l7.58-9.52h-14.28l1.93-6.6h14.61l3.25-9.73 2.81 5.12-11.3 38.89h11.05l5.23-17.81h1.62l1.48 17.6h10.69l-1.48-16.81c4.75-1.28 7.52-5.9 8.64-9.81l2.95-11.3c0.86-2.73-1.43-6.85-3.3-6.85zm-9.8 17.3h-8.69l2.54-7.84h8.35l-2.2 7.84z" fill="url(#pl3)"/>
-  <path d="m205.9 148.9h-122.6l-2.61-3.12h-32.4l-2.51 3.12h-1.59c-5.34 0-7.94 4.88-7.94 7.65v0.03c0 4.2 3.55 7.6 7.74 7.6h103.6l2.11 3.12h36.09l1.82-3.12h18.3c5.25 0 6.64-5.3 6.64-7.35v-0.25c0-4.23-2.9-7.68-6.64-7.68zm-0.7 12.83h-160.6c-3.69 0-6.11-2.58-6.11-5.47v-0.03c0-2.89 2.1-5.47 5.61-5.47h161.1c3.45 0 4.89 3.12 4.89 5.65v0.17c0 2.57-2.11 5.15-4.89 5.15z" fill="url(#pl4)"/>
-  <!-- Loader fill with clip for progress animation -->
-  <clipPath id="ge-loader-clip">
-    <rect x="37" y="148" width="0" height="20" class="ge-clip-rect"/>
-  </clipPath>
-  <path d="m204.5 152.6h-159.8c-2.78 0-4.45 1.69-4.45 3.99v0.11c0 2.04 1.42 3.43 3.64 3.43h160.6c2.88 0 3.67-2.07 3.67-3.43v-0.25c0-2.04-1.48-3.85-3.67-3.85z" fill="url(#pl5)" clip-path="url(#ge-loader-clip)"/>
-  <text x="125" y="196" text-anchor="middle" fill="rgba(255,255,255,0.6)" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif" font-size="8" font-weight="600" letter-spacing="1.5" class="ge-preloader-svg-text">Loading...</text>
-  <defs>
-    <linearGradient id="pl0" x1="223.7" x2="223.7" y1="81.75" y2="127.8" gradientUnits="userSpaceOnUse">
-      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
-    </linearGradient>
-    <linearGradient id="pl1" x1="194.6" x2="194.6" y1="81.75" y2="138.3" gradientUnits="userSpaceOnUse">
-      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
-    </linearGradient>
-    <linearGradient id="pl2" x1="157.8" x2="157.8" y1="81.75" y2="127" gradientUnits="userSpaceOnUse">
-      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
-    </linearGradient>
-    <linearGradient id="pl3" x1="79.96" x2="79.96" y1="81.75" y2="141.8" gradientUnits="userSpaceOnUse">
-      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
-    </linearGradient>
-    <linearGradient id="pl4" x1="36.18" x2="212.5" y1="156.6" y2="156.6" gradientUnits="userSpaceOnUse">
-      <stop stop-color="#316FB0"/><stop stop-color="#1FCDE6" offset=".5"/><stop stop-color="#29FEE7" offset="1"/>
-    </linearGradient>
-    <linearGradient id="pl5" x1="40.27" x2="208.2" y1="156.4" y2="156.4" gradientUnits="userSpaceOnUse">
-      <stop stop-color="#316FB0"/><stop stop-color="#1FCDE6" offset=".5"/><stop stop-color="#29FEE7" offset="1"/>
-    </linearGradient>
-  </defs>
-</svg>`;
+const LOGO_SVG = buildLogoSVG({
+  idPrefix: 'pl',
+  svgClass: 'ge-logo-svg',
+  clipRectClass: 'ge-clip-rect',
+  textClass: 'ge-preloader-svg-text',
+});
 
 /**
  * Creates a lightweight CSS-only preloader that appears instantly,

package/src/loading/LoadingScene.ts

@@ -3,49 +3,22 @@ import { Scene } from '../core/Scene';
 import { Tween } from '../animation/Tween';
 import { Easing } from '../animation/Easing';
 import type { LoadingScreenConfig } from '../types';
+import { buildLogoSVG, LOADER_BAR_MAX_WIDTH } from './logo';
 
 /**
- * Inline SVG logo with a loader bar (clip-animated for progress).
- * The clipPath rect width is set to 0 initially, expanded as loading progresses.
+ * Build the loading scene variant of the logo SVG.
+ * Uses unique IDs (prefixed with 'ls') to avoid collisions with CSSPreloader.
  */
-function buildLogoSVG(): string {
-  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 250 200" fill="none" style="width:100%;height:auto;">
-  <path d="m241 81.75h-19.28c-1.77 0-6.73 4.98-7.43 6.99l-4.36 12.22c-0.49 1.37 0.05 2.92 1.06 4.32-2.07 1.19-3.69 3.08-4.36 5.43l-3.25 10.41c-0.86 2.89 2.39 6.63 4.31 6.63h19.28c1.96 0 7.4-5.56 7.96-7.51l2.96-10.22c0.63-2.25 0.1-3.98-1.22-4.99 2.55-1.56 3.86-4.14 4.55-6.31l2.77-9.31c0.74-2.57-1.37-7.66-2.99-7.66zm-13.36 28.31-2.27 7.03h-8.28l2.58-8.28h8.28l-0.31 1.25zm4.06-16.97-2.11 6.7h-7.04l2.25-7.34h7.26l-0.36 0.64z" fill="url(#ls0)"/>
-  <path d="m202.5 81.75-9.31 14.97-2.32-14.97h-11.82l4.32 25.15-0.57 4.91-8.64 26.44 15.31-12.76 5.63-16.48 19.96-27.26h-12.56z" fill="url(#ls1)"/>
-  <path d="m174.2 81.75h-19.78l-5.75 5.16-10.79 33.2c-0.77 2.53 2.48 6.93 4.87 6.93h17.38c2.63 0 7.85-5.34 8.32-6.83l5.37-18.14h-15.17l-2.2 7.64h3.78l-2.25 7.2h-8.01l7.1-25.52h7.58l-1.48 8.4 12.78-5.98c1.28-0.63 1.97-3.99 1.61-6.61-0.36-2.34-1.64-5.45-3.36-5.45z" fill="url(#ls2)"/>
-  <path d="m140.6 81.75h-70.6l-5.36 19.37-4.26-19.37h-46.76l2.95 5.88-10.58 39.28h26.84l2.95-9.52-15.63-0.13 2.55-8.34h8.74l8.47-9.81h-14.61l2.11-7.3h15.47l2.54-8.71 2.58 4.74-11.4 39.07h11.05l6.46-21.49 8.84 36.33 19.18-55.67-1.83-3.36 3.68 4.09-12.07 40.1h28.18l3.39-10.31h-17.01l2.67-8.03h9.98l7.58-9.52h-14.28l1.93-6.6h14.61l3.25-9.73 2.81 5.12-11.3 38.89h11.05l5.23-17.81h1.62l1.48 17.6h10.69l-1.48-16.81c4.75-1.28 7.52-5.9 8.64-9.81l2.95-11.3c0.86-2.73-1.43-6.85-3.3-6.85zm-9.8 17.3h-8.69l2.54-7.84h8.35l-2.2 7.84z" fill="url(#ls3)"/>
-  <path d="m205.9 148.9h-122.6l-2.61-3.12h-32.4l-2.51 3.12h-1.59c-5.34 0-7.94 4.88-7.94 7.65v0.03c0 4.2 3.55 7.6 7.74 7.6h103.6l2.11 3.12h36.09l1.82-3.12h18.3c5.25 0 6.64-5.3 6.64-7.35v-0.25c0-4.23-2.9-7.68-6.64-7.68zm-0.7 12.83h-160.6c-3.69 0-6.11-2.58-6.11-5.47v-0.03c0-2.89 2.1-5.47 5.61-5.47h161.1c3.45 0 4.89 3.12 4.89 5.65v0.17c0 2.57-2.11 5.15-4.89 5.15z" fill="url(#ls4)"/>
-  <clipPath id="ge-canvas-loader-clip">
-    <rect id="ge-loader-rect" x="37" y="148" width="0" height="20"/>
-  </clipPath>
-  <path d="m204.5 152.6h-159.8c-2.78 0-4.45 1.69-4.45 3.99v0.11c0 2.04 1.42 3.43 3.64 3.43h160.6c2.88 0 3.67-2.07 3.67-3.43v-0.25c0-2.04-1.48-3.85-3.67-3.85z" fill="url(#ls5)" clip-path="url(#ge-canvas-loader-clip)"/>
-  <text id="ge-loader-pct" x="125" y="196" text-anchor="middle" fill="rgba(255,255,255,0.7)" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif" font-size="8" font-weight="600" letter-spacing="1.5">0%</text>
-  <defs>
-    <linearGradient id="ls0" x1="223.7" x2="223.7" y1="81.75" y2="127.8" gradientUnits="userSpaceOnUse">
-      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
-    </linearGradient>
-    <linearGradient id="ls1" x1="194.6" x2="194.6" y1="81.75" y2="138.3" gradientUnits="userSpaceOnUse">
-      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
-    </linearGradient>
-    <linearGradient id="ls2" x1="157.8" x2="157.8" y1="81.75" y2="127" gradientUnits="userSpaceOnUse">
-      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
-    </linearGradient>
-    <linearGradient id="ls3" x1="79.96" x2="79.96" y1="81.75" y2="141.8" gradientUnits="userSpaceOnUse">
-      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
-    </linearGradient>
-    <linearGradient id="ls4" x1="36.18" x2="212.5" y1="156.6" y2="156.6" gradientUnits="userSpaceOnUse">
-      <stop stop-color="#316FB0"/><stop stop-color="#1FCDE6" offset=".5"/><stop stop-color="#29FEE7" offset="1"/>
-    </linearGradient>
-    <linearGradient id="ls5" x1="40.27" x2="208.2" y1="156.4" y2="156.4" gradientUnits="userSpaceOnUse">
-      <stop stop-color="#316FB0"/><stop stop-color="#1FCDE6" offset=".5"/><stop stop-color="#29FEE7" offset="1"/>
-    </linearGradient>
-  </defs>
-</svg>`;
+function buildLoadingLogoSVG(): string {
+  return buildLogoSVG({
+    idPrefix: 'ls',
+    svgStyle: 'width:100%;height:auto;',
+    clipRectId: 'ge-loader-rect',
+    textId: 'ge-loader-pct',
+    textContent: '0%',
+  });
 }
 
-/** Max width of the loader bar in SVG units */
-const LOADER_BAR_MAX_WIDTH = 174;
-
 interface LoadingSceneData {
   engine: any; // GameApplication — avoid circular import
   targetScene: string;
@@ -194,7 +167,7 @@ export class LoadingScene extends Scene {
     this._overlay.id = '__ge-loading-overlay__';
     this._overlay.innerHTML = `
       <div class="ge-loading-content">
-        ${buildLogoSVG()}
+        ${buildLoadingLogoSVG()}
       </div>
     `;
 
@@ -350,7 +323,10 @@ export class LoadingScene extends Scene {
     // Remove overlay
     this.removeOverlay();
 
-    // Navigate to the target scene
-    await this._engine.scenes.goto(this._targetScene, this._targetData);
+    // Navigate to the target scene, always passing the engine reference
+    await this._engine.scenes.goto(this._targetScene, {
+      engine: this._engine,
+      ...(this._targetData && typeof this._targetData === 'object' ? this._targetData as Record<string, unknown> : { data: this._targetData }),
+    });
   }
 }

package/src/loading/index.ts

@@ -1,2 +1,3 @@
 export { LoadingScene } from './LoadingScene';
 export { createCSSPreloader, removeCSSPreloader } from './CSSPreloader';
+export { buildLogoSVG, LOADER_BAR_MAX_WIDTH } from './logo';

package/src/loading/logo.ts

@@ -0,0 +1,95 @@
+/**
+ * Shared Energy8 SVG logo with an embedded loader bar.
+ *
+ * The loader bar fill is controlled via a `<clipPath>` whose `<rect>` width
+ * is animatable. Different consumers customise gradient IDs and the clip
+ * element's ID/class to avoid collisions when both CSSPreloader and
+ * LoadingScene appear in the same DOM.
+ */
+
+/** SVG path data for the Energy8 wordmark — reused across loaders */
+const WORDMARK_PATHS = `
+  <path d="m241 81.75h-19.28c-1.77 0-6.73 4.98-7.43 6.99l-4.36 12.22c-0.49 1.37 0.05 2.92 1.06 4.32-2.07 1.19-3.69 3.08-4.36 5.43l-3.25 10.41c-0.86 2.89 2.39 6.63 4.31 6.63h19.28c1.96 0 7.4-5.56 7.96-7.51l2.96-10.22c0.63-2.25 0.1-3.98-1.22-4.99 2.55-1.56 3.86-4.14 4.55-6.31l2.77-9.31c0.74-2.57-1.37-7.66-2.99-7.66zm-13.36 28.31-2.27 7.03h-8.28l2.58-8.28h8.28l-0.31 1.25zm4.06-16.97-2.11 6.7h-7.04l2.25-7.34h7.26l-0.36 0.64z" fill="url(#GID0)"/>
+  <path d="m202.5 81.75-9.31 14.97-2.32-14.97h-11.82l4.32 25.15-0.57 4.91-8.64 26.44 15.31-12.76 5.63-16.48 19.96-27.26h-12.56z" fill="url(#GID1)"/>
+  <path d="m174.2 81.75h-19.78l-5.75 5.16-10.79 33.2c-0.77 2.53 2.48 6.93 4.87 6.93h17.38c2.63 0 7.85-5.34 8.32-6.83l5.37-18.14h-15.17l-2.2 7.64h3.78l-2.25 7.2h-8.01l7.1-25.52h7.58l-1.48 8.4 12.78-5.98c1.28-0.63 1.97-3.99 1.61-6.61-0.36-2.34-1.64-5.45-3.36-5.45z" fill="url(#GID2)"/>
+  <path d="m140.6 81.75h-70.6l-5.36 19.37-4.26-19.37h-46.76l2.95 5.88-10.58 39.28h26.84l2.95-9.52-15.63-0.13 2.55-8.34h8.74l8.47-9.81h-14.61l2.11-7.3h15.47l2.54-8.71 2.58 4.74-11.4 39.07h11.05l6.46-21.49 8.84 36.33 19.18-55.67-1.83-3.36 3.68 4.09-12.07 40.1h28.18l3.39-10.31h-17.01l2.67-8.03h9.98l7.58-9.52h-14.28l1.93-6.6h14.61l3.25-9.73 2.81 5.12-11.3 38.89h11.05l5.23-17.81h1.62l1.48 17.6h10.69l-1.48-16.81c4.75-1.28 7.52-5.9 8.64-9.81l2.95-11.3c0.86-2.73-1.43-6.85-3.3-6.85zm-9.8 17.3h-8.69l2.54-7.84h8.35l-2.2 7.84z" fill="url(#GID3)"/>
+  <path d="m205.9 148.9h-122.6l-2.61-3.12h-32.4l-2.51 3.12h-1.59c-5.34 0-7.94 4.88-7.94 7.65v0.03c0 4.2 3.55 7.6 7.74 7.6h103.6l2.11 3.12h36.09l1.82-3.12h18.3c5.25 0 6.64-5.3 6.64-7.35v-0.25c0-4.23-2.9-7.68-6.64-7.68zm-0.7 12.83h-160.6c-3.69 0-6.11-2.58-6.11-5.47v-0.03c0-2.89 2.1-5.47 5.61-5.47h161.1c3.45 0 4.89 3.12 4.89 5.65v0.17c0 2.57-2.11 5.15-4.89 5.15z" fill="url(#GID4)"/>`;
+
+/** Gradient definitions template (gradient IDs are replaced per-consumer) */
+const GRADIENT_DEFS = `
+    <linearGradient id="GID0" x1="223.7" x2="223.7" y1="81.75" y2="127.8" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
+    </linearGradient>
+    <linearGradient id="GID1" x1="194.6" x2="194.6" y1="81.75" y2="138.3" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
+    </linearGradient>
+    <linearGradient id="GID2" x1="157.8" x2="157.8" y1="81.75" y2="127" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
+    </linearGradient>
+    <linearGradient id="GID3" x1="79.96" x2="79.96" y1="81.75" y2="141.8" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#663BA6"/><stop stop-color="#7939C2" offset=".349"/><stop stop-color="#8A2FC0" offset=".6615"/><stop stop-color="#791BA3" offset="1"/>
+    </linearGradient>
+    <linearGradient id="GID4" x1="36.18" x2="212.5" y1="156.6" y2="156.6" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#316FB0"/><stop stop-color="#1FCDE6" offset=".5"/><stop stop-color="#29FEE7" offset="1"/>
+    </linearGradient>
+    <linearGradient id="GID5" x1="40.27" x2="208.2" y1="156.4" y2="156.4" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#316FB0"/><stop stop-color="#1FCDE6" offset=".5"/><stop stop-color="#29FEE7" offset="1"/>
+    </linearGradient>`;
+
+/** Max width of the loader bar in SVG units */
+export const LOADER_BAR_MAX_WIDTH = 174;
+
+interface LogoSVGOptions {
+  /** Prefix for gradient/clip IDs to avoid collisions (e.g. 'pl' or 'ls') */
+  idPrefix: string;
+  /** Optional CSS class on the root <svg> */
+  svgClass?: string;
+  /** Optional inline style on the root <svg> */
+  svgStyle?: string;
+  /** Optional CSS class on the clip <rect> */
+  clipRectClass?: string;
+  /** Optional id on the clip <rect> (for JS access) */
+  clipRectId?: string;
+  /** Optional id on the percentage <text> */
+  textId?: string;
+  /** Default text content */
+  textContent?: string;
+  /** Optional CSS class on the <text> */
+  textClass?: string;
+}
+
+/**
+ * Build the Energy8 SVG logo with a loader bar, using unique IDs.
+ *
+ * @param opts - Configuration to avoid element ID collisions
+ * @returns SVG markup string
+ */
+export function buildLogoSVG(opts: LogoSVGOptions): string {
+  const { idPrefix, svgClass, svgStyle, clipRectClass, clipRectId, textId, textContent, textClass } = opts;
+
+  // Replace gradient ID placeholders with prefixed versions
+  const paths = WORDMARK_PATHS.replace(/GID(\d)/g, `${idPrefix}$1`);
+  const defs = GRADIENT_DEFS.replace(/GID(\d)/g, `${idPrefix}$1`);
+
+  const clipId = `${idPrefix}-loader-clip`;
+  const fillGradientId = `${idPrefix}5`;
+
+  const classAttr = svgClass ? ` class="${svgClass}"` : '';
+  const styleAttr = svgStyle ? ` style="${svgStyle}"` : '';
+  const rectClassAttr = clipRectClass ? ` class="${clipRectClass}"` : '';
+  const rectIdAttr = clipRectId ? ` id="${clipRectId}"` : '';
+  const txtIdAttr = textId ? ` id="${textId}"` : '';
+  const txtClassAttr = textClass ? ` class="${textClass}"` : '';
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 250 200" fill="none"${classAttr}${styleAttr}>
+${paths}
+  <clipPath id="${clipId}">
+    <rect${rectIdAttr} x="37" y="148" width="0" height="20"${rectClassAttr}/>
+  </clipPath>
+  <path d="m204.5 152.6h-159.8c-2.78 0-4.45 1.69-4.45 3.99v0.11c0 2.04 1.42 3.43 3.64 3.43h160.6c2.88 0 3.67-2.07 3.67-3.43v-0.25c0-2.04-1.48-3.85-3.67-3.85z" fill="url(#${fillGradientId})" clip-path="url(#${clipId})"/>
+  <text${txtIdAttr} x="125" y="196" text-anchor="middle" fill="rgba(255,255,255,0.6)" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif" font-size="8" font-weight="600" letter-spacing="1.5"${txtClassAttr}>${textContent ?? 'Loading...'}</text>
+  <defs>
+${defs}
+  </defs>
+</svg>`;
+}

package/src/types.ts

@@ -121,6 +121,8 @@ export interface GameApplicationConfig {
         parentOrigin?: string;
         timeout?: number;
         debug?: boolean;
+        /** Use in-memory channel instead of postMessage (no iframe required) */
+        devMode?: boolean;
       }
     | false;
 
@@ -135,6 +137,8 @@ export interface GameApplicationConfig {
 
 export interface SceneConstructor {
   new (): IScene;
+  // Allow Scene subclasses to be used as constructors
+  [key: string]: any;
 }
 
 export interface IScene {