@energy8platform/game-engine 0.34.3 → 0.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@energy8platform/game-engine",
-  "version": "0.34.3",
+  "version": "0.35.0",
   "description": "Universal casino game engine built on PixiJS v8 and @energy8platform/game-sdk",
   "type": "module",
   "main": "./dist/index.cjs.js",
@@ -93,7 +93,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@energy8platform/platform-core": ">=0.30.8",
+    "@energy8platform/platform-core": ">=0.31.0",
     "@energy8platform/shell": ">=0.7.0"
   },
   "peerDependencies": {

package/src/core/GameApplication.ts

@@ -11,7 +11,14 @@ import { AudioManager } from '../audio/AudioManager';
 import { InputManager } from '../input/InputManager';
 import { ViewportManager } from '../viewport/ViewportManager';
 import { LoadingScene } from '../loading/LoadingScene';
-import { createCSSPreloader, removeCSSPreloader } from '@energy8platform/platform-core/loading';
+import {
+  createCSSPreloader,
+  removeCSSPreloader,
+  adoptExternalOverlay,
+  advanceExternalOverlay,
+  releaseExternalOverlay,
+  hasExternalOverlay,
+} from '@energy8platform/platform-core/loading';
 import { FPSOverlay } from '../debug/FPSOverlay';
 
 /**
@@ -155,17 +162,40 @@ export class GameApplication extends EventEmitter<GameEngineEvents> {
     }
 
     try {
+      // 0. Adopt a game-supplied loading overlay (`loading.externalOverlay`) BEFORE anything that
+      //    can throw. Such an overlay is already on screen — Artube's is injected into index.html,
+      //    so it paints before this bundle is even fetched — and until the engine has adopted it,
+      //    the catch below has no way to take it down. A bad `container` selector (step 1) would
+      //    otherwise strand it on screen forever. It needs no container of ours.
+      //    Adoption is also where its minimum display time starts counting, which is why the
+      //    config value is handed over here rather than read at the hand-over: this is the
+      //    earliest moment the engine runs, and the overlay has been on screen since before it.
+      const external = this.config.loading?.externalOverlay;
+      if (external)
+        adoptExternalOverlay(external, this.config.loading?.externalOverlayMinDisplayTime);
+
       // 1. Resolve container element
       this._container = this.resolveContainer();
 
-      // 2. Show CSS preloader immediately (before PixiJS)
-      createCSSPreloader(this._container, this.config.loading);
+      // 2. Show the CSS preloader immediately (before PixiJS) — UNLESS a game-supplied overlay is
+      //    already covering the screen. In that case the preloader is mounted later, by LoadingScene
+      //    at its first frame, which is where the hand-over happens. Mounting it here instead would
+      //    put our brand over theirs for the whole of Pixi init and the SDK handshake, i.e. hand
+      //    over long before the gap the external overlay exists to cover has closed.
+      if (!hasExternalOverlay()) createCSSPreloader(this._container, this.config.loading);
 
       // 3. Initialize PixiJS
       await this.initPixi();
+      // Milestones through the pre-first-frame gap, for a game-supplied overlay only (no-ops
+      // otherwise, so the built-in preloader's behaviour is untouched). They are also what makes
+      // Artube's loader crossfade from its dark partner phase to its branded one: that transition
+      // fires on the first progress above zero, and without it the player would never see the
+      // brand the loader exists to show. Values are honest weights of what remains, not a timer.
+      advanceExternalOverlay(0.35);
 
       // 4. Initialize SDK (if enabled)
       await this.initSDK();
+      advanceExternalOverlay(0.7);
 
       // 4b. Mount the branded game shell after the SDK handshake (optional)
       if (this.config.shell) {
@@ -178,12 +208,19 @@ export class GameApplication extends EventEmitter<GameEngineEvents> {
 
       // 6. Initialize sub-systems
       this.initSubSystems();
+      advanceExternalOverlay(0.85);
 
       this.emit('initialized');
 
       // 7. Load assets. The CSS preloader stays on screen — LoadingScene drives
       //    its progress/tap and removes it before entering the game, so there's
       //    a single continuous overlay from boot to gameplay (no logo flash).
+      //
+      //    With a game-supplied overlay the sequence has one extra step at the
+      //    front: LoadingScene MOUNTS the preloader, waits for its first painted
+      //    frame, and only then dismisses the external overlay. From that frame
+      //    on this path and every other are identical — same brand, same bar,
+      //    same tap-to-start.
       await this.loadAssets(firstScene, sceneData);
 
       this.emit('loaded');
@@ -193,8 +230,13 @@ export class GameApplication extends EventEmitter<GameEngineEvents> {
       this.emit('started');
     } catch (err) {
       console.error('[GameEngine] Failed to start:', err);
-      // Tear down the preloader so a failure doesn't strand the brand frame.
-      if (this._container) removeCSSPreloader(this._container);
+      // Tear down both possible overlays so a failure strands neither brand frame. BOTH calls run:
+      // a throw during the hand-over window can leave the preloader mounted AND the external
+      // overlay still adopted, and each call is a no-op when there is nothing to remove. The
+      // container may never have resolved (step 1 is inside this try), hence the `document.body`
+      // fallback — the external overlay ignores the element entirely.
+      releaseExternalOverlay();
+      void removeCSSPreloader(this._container ?? document.body);
       this.emit('error', err instanceof Error ? err : new Error(String(err)));
       throw err;
     }

package/src/host/buildConfig.ts

@@ -6,12 +6,18 @@ import type { SlotSpinResultBase } from '@energy8platform/platform-core/slot-res
 
 /**
  * Pure: map host options to a GameApplicationConfig with sane defaults.
- * `isStakeNow` is computed by the orchestrator (kept out of here so this
- * stays a pure, renderer-free function).
+ * `isStakeNow` / `isArtubeNow` are computed by the orchestrator (kept out of
+ * here so this stays a pure, renderer-free function).
+ *
+ * Both host bridges run IN-PROCESS with the game, so either one means the SDK
+ * must be in `devMode` — that is what makes it talk over the in-memory channel
+ * the bridge listens on instead of postMessage-ing an outer host that isn't
+ * there. (`dev` is the third, unrelated reason for the same flag: DevBridge.)
  */
 export function buildAppConfig<T extends SlotSpinResultBase = SlotSpinResultBase>(
   opts: CreateSlotGameOptions<T>,
   isStakeNow: boolean,
+  isArtubeNow = false,
 ): GameApplicationConfig {
   return {
     container: opts.container ?? '#game',
@@ -19,11 +25,18 @@ export function buildAppConfig<T extends SlotSpinResultBase = SlotSpinResultBase
     designHeight: opts.design?.height ?? 1080,
     scaleMode: opts.scaleMode ?? ScaleMode.FILL,
     orientation: opts.orientation ?? Orientation.ANY,
-    loading: opts.loading ?? { tapToStart: false, minDisplayTime: 600 },
+    // MERGED, not replaced. `opts.loading ?? {…}` looked equivalent and was not: a game that
+    // passes ANY loading option loses every default it did not restate, so `{ minDisplayTime: 900 }`
+    // silently re-armed tap-to-start (the engine's own default for that flag is `true`, for
+    // backwards compatibility with direct GameApplication users). The Artube target made it
+    // visible — a game supplying only `externalOverlay` waited for a tap there and nowhere else,
+    // i.e. the same source line behaved differently per platform. Spreading `opts.loading` last
+    // keeps every explicit value winning while unset keys stay on the host's defaults.
+    loading: { tapToStart: false, minDisplayTime: 600, ...opts.loading },
     manifest: opts.manifest,
     audio: opts.audio,
     pixi: opts.pixi,
-    sdk: { devMode: isStakeNow || (opts.dev ?? false) },
+    sdk: { devMode: isStakeNow || isArtubeNow || (opts.dev ?? false) },
     debug: opts.dev ?? false,
   };
 }

package/src/host/createSlotGame.ts

@@ -5,13 +5,14 @@ import { buildAppConfig } from './buildConfig';
 import { loadFonts, applyTextureDefaults, bootGuard } from './preboot';
 import { showFatalError, installGlobalErrorHandlers } from './fatalError';
 import type { CreateSlotGameOptions, SlotGameHandle } from './types';
+import { releaseExternalOverlay } from '@energy8platform/platform-core/loading';
 import type { SlotSpinResultBase } from '@energy8platform/platform-core/slot-result';
 import type { ShellMode } from '@energy8platform/shell/pixi';
 import type { SceneApi, SlotSceneController, RenderContext } from './sceneController';
 import type { FreeSpinsView } from './freeSpinsCounter';
 
 /**
- * One-call slot bootstrap: preboot → (optional Stake bridge) → GameApplication
+ * One-call slot bootstrap: preboot → (optional Stake / Artube bridge) → GameApplication
  * → register scene → start. Collapses the per-game main.ts boilerplate.
  *
  * Not unit-tested: GameApplication.init() drives Pixi, which hangs in headless
@@ -29,6 +30,24 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
   let shell: SlotGameHandle['shell'] = null;
 
   const fatal = (message: string) => {
+    // Take down a game-supplied loading overlay (`loading.externalOverlay`) first. Several fatal
+    // paths below — a refused Artube launch, a bridge that cannot connect — happen BEFORE
+    // `GameApplication.start()`, so its own error path never runs and nothing else would ever
+    // dismiss the overlay. Artube's is already on screen from index.html at z-index 9999: leaving
+    // it up means the player stares at a frozen loading screen, and a custom `onFatalError`
+    // renderer would be hidden underneath it entirely.
+    //
+    // `releaseExternalOverlay` handles the case where the engine already adopted it (and keeps the
+    // dismissal idempotent, which matters now that the normal hand-over also dismisses it). Its
+    // `false` means the engine never got that far — those are exactly the pre-boot refusals, where
+    // hiding the game's overlay directly is the only thing that can work.
+    if (!releaseExternalOverlay()) {
+      try {
+        opts.loading?.externalOverlay?.hideLoader();
+      } catch {
+        /* the overlay is the game's; a throw here must not swallow the error we came to report */
+      }
+    }
     if (opts.onFatalError) return opts.onFatalError(message);
     // Once the shell is up, use ITS branded modal (consistent chrome, social vocabulary, fit
     // scaling) rather than the bare DOM fallback. Errors thrown before the shell boots (asset
@@ -100,7 +119,66 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
     }
   }
 
-  const game = new GameApplication(buildAppConfig(opts, isStakeNow));
+  let artubeBridge: SlotGameHandle['artubeBridge'] = null;
+  let isArtubeNow = false;
+  // `!isStakeNow`: both bridges install themselves in-process on the SAME SDK memory channel, so
+  // whichever launch already claimed the game wins. (The two launch shapes are disjoint in practice
+  // — Stake's marker is `sessionID`/`replay`, Artube's is `sessionId` — so this never fires; it just
+  // makes the precedence explicit rather than leaving two bridges racing.)
+  if (opts.artube && !isStakeNow) {
+    // The GAME supplies the loader (see `ArtubeIntegration.load`): a bare
+    // `import('@energy8platform/artube-bridge')` here would be resolved statically by every bundler
+    // and would break — loudly or, under Vite, silently — every game that never installed the
+    // package. Classifier and bridge come from the same module, so this is one load.
+    let artube: import('./types').ArtubeModule;
+    try {
+      artube = await opts.artube.load();
+    } catch (err) {
+      fatal('Could not start the game.');
+      throw err;
+    }
+    // Security gate, the Artube counterpart of the Stake one above. Artube's only launch marker is
+    // `sessionId`, and unlike Stake there is no attacker-suppliable server address to validate
+    // (`apiBase` is the launch URL's own origin). What IS reachable is stripping the session: a URL
+    // that carries `sessionId` with an empty/blank value claims a session it doesn't have, fails the
+    // "is this Artube?" check, and would silently fall through to the offline/dev bridge — the
+    // free-play hole. 'artube' = a real launch (load the bridge); 'offline' = no marker at all, a
+    // genuine dev launch.
+    //
+    // What URL classification cannot catch: a marker removed ENTIRELY is indistinguishable from a
+    // dev launch. In a production BUILD there is nothing to fall through to anyway — the DevBridge
+    // bootstrapper is injected by a Vite plugin with `apply: 'serve'`, so no build carries one,
+    // whatever BUILD_TARGET says. Under a plain `npm run dev` the bootstrapper HAS already started a
+    // DevBridge before this code runs (it wraps the entry module), so there the protection is this
+    // gate refusing to start the game — not the absence of a bridge.
+    const launch = artube.classifyArtubeLaunch(location.href);
+    if (launch === 'blocked') {
+      fatal('Invalid game session. Please relaunch the game from the lobby.');
+      throw new Error(
+        'createSlotGame: refusing to run — Artube launch with a missing or blank sessionId',
+      );
+    }
+    isArtubeNow = launch === 'artube';
+    if (isArtubeNow) {
+      try {
+        artubeBridge = new artube.ArtubeBridge({
+          // In-process over the SDK's MemoryChannel (see buildAppConfig's devMode).
+          devMode: true,
+          gameId: opts.model.spec.id,
+          url: location.href,
+          // Same-origin in production; both fields are dev/demo escape hatches (see ArtubeIntegration).
+          ...(opts.artube.apiBase ? { apiBase: opts.artube.apiBase } : {}),
+          ...(opts.artube.demoBalance != null ? { demoBalance: opts.artube.demoBalance } : {}),
+        });
+        await artubeBridge.ready();
+      } catch (err) {
+        fatal('Could not connect to the game server. Please reload.');
+        throw err;
+      }
+    }
+  }
+
+  const game = new GameApplication(buildAppConfig(opts, isStakeNow, isArtubeNow));
 
   // Register EVERY scene up front so any of them can navigate to any other.
   for (const { key, scene } of opts.scenes) game.scenes.register(key, scene);
@@ -174,6 +252,8 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
 
     const ps = game.platformSession;
     const balance = (game.initData?.balance as number | undefined) ?? 0;
+    // Replay is a STAKE concept (a shared link that re-plays one recorded round). Artube has no
+    // equivalent, so an Artube launch is always 'base' — nothing to mirror here.
     const isReplay = !!stakeBridge?.isReplay;
     const mode: ShellMode = isReplay ? 'replay' : 'base';
     // initData.config carries the Stake bridge's currency/social/disclaimer surface (GameConfigData);
@@ -189,9 +269,16 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
         stake?: { defaultBetLevel?: number; minBet?: number; maxBet?: number };
         /** Set by the Stake bridge when `/wallet/authenticate` returned a still-open round. */
         activeRound?: { bet?: number; roundId?: string; mode?: string };
+        /** Artube's platform block. The default bet arrives as an INDEX into `config.betLevels`
+         *  (the platform's `allowed_bets`), where Stake states an amount. */
+        artube?: { defaultBetIndex?: number };
       };
-      /** Present only on a resume — the bridge synthesises it from the open round. */
+      /** Present only on a resume — the bridge synthesises it from the open round. Both the Stake
+       *  and the Artube bridge fill it the same way, so the resumed-bet path below is shared. */
       session?: { betAmount?: number };
+      /** Session currency CODE. The Artube bridge's only currency surface (the platform picks it
+       *  per session; demo sessions are 'FUN'); Stake sends full meta on `config.currency` instead. */
+      currency?: string;
       lang?: string;
     } | null;
     const config = initData?.config;
@@ -203,33 +290,44 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
     // carrier for the same value (INIT only ever has a session on a resume). Both are ignored when
     // absent or 0 so an ordinary launch still starts on the default.
     const resumedBet = config?.activeRound?.bet || initData?.session?.betAmount || undefined;
+    // Artube states its per-session default bet as an INDEX into the platform's ladder; resolve it
+    // against that SAME ladder so `runtime.defaultBet` is an amount on both platforms.
+    const artubeDefaultBet = isArtubeNow
+      ? config?.betLevels?.[config?.artube?.defaultBetIndex ?? -1]
+      : undefined;
     const { resolveCurrency } = await import('./shellConfig');
     // SINGLE source of truth for the symbol: the Stake bridge already puts a full CurrencyMetaData
     // (symbol + placement) on initData.config.currency. In the non-stake/devBridge path that meta
     // is absent and we only have the spec's currency CODE — resolve it through the SAME table
     // (stake-bridge's lookupCurrency) so e.g. 'EUR' renders as '€', not the literal text "EUR".
     // stake-bridge ships with every scaffold; if it's somehow absent we degrade to the code.
+    // On Artube the session currency is the PLATFORM's (per player, and 'FUN' for demo sessions) and
+    // arrives as a bare code on initData — there is no meta object. It outranks the spec's static
+    // code, which would otherwise show every Artube player the spec's currency symbol.
+    const currencyCode = (isArtubeNow ? initData?.currency : undefined) || opts.model.spec.currency;
     let currencyMeta = config?.currency;
-    if (!currencyMeta?.symbol && opts.model.spec.currency) {
+    if (!currencyMeta?.symbol && currencyCode) {
       try {
         const { lookupCurrency } = await import('@energy8platform/stake-bridge');
-        currencyMeta = lookupCurrency(opts.model.spec.currency);
+        currencyMeta = lookupCurrency(currencyCode);
       } catch {
         /* stake-bridge not installed — resolveCurrency falls back to the code */
       }
     }
     const runtime = {
       balance,
-      currency: resolveCurrency(currencyMeta, opts.model.spec.currency),
+      currency: resolveCurrency(currencyMeta, currencyCode),
       language: initData?.lang,
       mode,
       social: config?.socialMode,
       disclaimerLines: config?.disclaimerLines,
       jurisdiction: config?.jurisdiction,
-      // Currency-specific ladder + per-currency default from /wallet/authenticate (Stake);
-      // absent on dev/devBridge → buildShellConfig falls back to the spec.
+      // Currency-specific ladder + per-currency default from /wallet/authenticate (Stake) or the
+      // backend's `allowed_bets` (Artube); absent on dev/devBridge → buildShellConfig falls back to
+      // the spec.
       betLevels: config?.betLevels,
-      defaultBet: resumedBet ?? config?.stake?.defaultBetLevel ?? config?.defaultBet,
+      defaultBet:
+        resumedBet ?? config?.stake?.defaultBetLevel ?? artubeDefaultBet ?? config?.defaultBet,
       // Hard stake window; the bridge rejects anything outside it before /bet/play.
       minBet: config?.stake?.minBet,
       maxBet: config?.stake?.maxBet,
@@ -238,10 +336,14 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
     // spec's (EUR-shaped) ladder here would put the game on bets the wallet can't honour — every
     // spin rejected on a high-denomination currency (ARS minBet 50), or silently mispriced. Fail
     // where the cause is visible instead of at the first spin.
-    if (isStakeNow && !runtime.betLevels?.length) {
+    // Artube is the same requirement by a different route: the wire carries a bet INDEX, not an
+    // amount, and the bridge maps the amount the game plays to the NEAREST rung of the platform's
+    // ladder — so a spec-shaped ladder wouldn't be rejected, it would silently charge a different
+    // price than the bar shows. Refuse there too.
+    if ((isStakeNow || isArtubeNow) && !runtime.betLevels?.length) {
       fatal('Could not load the bet levels for your currency. Please relaunch the game.');
       throw new Error(
-        'createSlotGame: Stake launch returned no config.betLevels — refusing to fall back to the spec ladder',
+        `createSlotGame: ${isStakeNow ? 'Stake' : 'Artube'} launch returned no config.betLevels — refusing to fall back to the spec ladder`,
       );
     }
     if (opts.dev) {
@@ -811,5 +913,5 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
     }
   }
 
-  return { game, stakeBridge, shell };
+  return { game, stakeBridge, artubeBridge, shell };
 }

package/src/host/index.ts

@@ -4,6 +4,9 @@ export type {
   CreateSlotGameOptions,
   SlotGameHandle,
   StakeIntegration,
+  ArtubeIntegration,
+  ArtubeModule,
+  ArtubeBridgeLike,
   SceneRegistration,
   SceneNavData,
   ShellFactory,

package/src/host/types.ts

@@ -34,6 +34,58 @@ export interface StakeIntegration {
   adapter: BookAdapter | AdapterModule;
 }
 
+/** The live Artube bridge, structurally. Kept minimal so game-engine never has to import
+ *  `@energy8platform/artube-bridge` — see `ArtubeIntegration.load`. */
+export interface ArtubeBridgeLike {
+  /** Resolves once the backend has sent its init. */
+  ready(): Promise<void>;
+  destroy(): void;
+}
+
+/** What `ArtubeIntegration.load()` must resolve to. `@energy8platform/artube-bridge`'s own entry
+ *  satisfies this structurally, so `load: () => import('@energy8platform/artube-bridge')` typechecks
+ *  with no adapter. The launch CLASSIFIER comes from the same module as the bridge: one import, and
+ *  no chicken-and-egg where the host would have to load something to decide whether to load. */
+export interface ArtubeModule {
+  classifyArtubeLaunch: (url: string) => 'artube' | 'blocked' | 'offline';
+  ArtubeBridge: new (options: {
+    devMode?: boolean;
+    gameId?: string;
+    url?: string;
+    apiBase?: string;
+    demoBalance?: number;
+  }) => ArtubeBridgeLike;
+}
+
+/** Artube host integration. There is no per-game artifact to pass: the game's own BACKEND
+ *  (`@energy8platform/artube-server`) owns the round shape, so the bridge is a pure protocol
+ *  translator — `load` is the only required field. `gameId` comes from the model, the launch params
+ *  from the URL. */
+export interface ArtubeIntegration {
+  /** REQUIRED. How the host reaches the bridge:
+   *  `load: () => import('@energy8platform/artube-bridge')`.
+   *
+   *  Why the GAME supplies this instead of the host importing the package itself: a bare
+   *  `import('@energy8platform/artube-bridge')` inside this always-shipped `/host` entry is resolved
+   *  STATICALLY by every bundler, so it would have to resolve in games that never opted into Artube
+   *  and therefore never installed the package — esbuild/webpack fail the build outright, and Vite
+   *  silently substitutes an empty module (it stubs uninstalled optional peers), which is worse:
+   *  the game builds and then dies at runtime. With the loader, the specifier only ever appears in
+   *  the bundle of a game that took the dependency.
+   *
+   *  The loaded chunk is fetched on every launch of such a game (the classifier lives in it), which
+   *  is the point of the split: only Artube-targeted builds pay for it. */
+  load: () => Promise<ArtubeModule>;
+  /** Starting virtual balance for a DEMO session (the platform doesn't keep one — the bridge does,
+   *  client-side). Default: the backend's own configured demo balance. Ignored for real sessions. */
+  demoBalance?: number;
+  /** Origin of the game's backend. Default (and the only supported PRODUCTION value) is the launch
+   *  URL's own origin: Artube serves frontend and backend on one domain, split by path (`/api/**`).
+   *  Override only for local dev against a backend on another port — prefer proxying `/api` from the
+   *  dev server (what the `BUILD_TARGET=artube` target does) so dev matches production. */
+  apiBase?: string;
+}
+
 /** One scene registered with the host: a key + its constructor. The list order matters — the
  *  first scene that is eligible for the current launch mode is the start scene (unless an explicit
  *  `startScene` overrides it). */
@@ -77,6 +129,10 @@ export interface CreateSlotGameOptions<T extends SlotSpinResultBase = SlotSpinRe
   textureDefaults?: boolean;
   dev?: boolean;
   stake?: StakeIntegration;
+  /** Run on Artube when the launch URL says so (`?sessionId=…`):
+   *  `artube: { load: () => import('@energy8platform/artube-bridge') }`. See `ArtubeIntegration`
+   *  for why the game supplies the loader. Build with `BUILD_TARGET=artube`. */
+  artube?: ArtubeIntegration;
   shell?: SlotShellOptions;
   /** Customise the bonus bar readout for games whose bonus isn't plain free spins (adventure,
    *  hold-and-spin, respins). Omit for the free-spins default. See `BonusReadoutConfig`. */
@@ -101,5 +157,7 @@ export type ShellFactory = (config: PixiShellConfig) => Shell;
 export interface SlotGameHandle {
   game: GameApplication;
   stakeBridge: StakeBridge | null;
+  /** The live Artube bridge — non-null only on a real Artube launch (`opts.artube` + `?sessionId=…`). */
+  artubeBridge: ArtubeBridgeLike | null;
   shell: Shell | null;
 }

package/src/loading/LoadingScene.ts

@@ -1,9 +1,13 @@
 import { Scene } from '../core/Scene';
 import type { LoadingScreenConfig } from '../types';
 import {
+  createCSSPreloader,
   setCSSPreloaderProgress,
   waitCSSPreloaderTap,
   removeCSSPreloader,
+  hasExternalOverlay,
+  externalOverlayHold,
+  releaseExternalOverlay,
 } from '@energy8platform/platform-core/loading';
 
 interface LoadingSceneData {
@@ -21,6 +25,14 @@ interface LoadingSceneData {
  * tap-to-start → `waitCSSPreloaderTap`, then fades it out via
  * `removeCSSPreloader` before entering the game. One continuous overlay from
  * boot to gameplay — no second logo, no mid-load flash.
+ *
+ * When the game supplied its own overlay (`loading.externalOverlay`, e.g.
+ * Artube's `LoaderViewController`), this scene is also the HAND-OVER point: that
+ * overlay covered the gap this scene's existence ends — the bundle download,
+ * Pixi init and the SDK handshake, none of which the engine can paint over. The
+ * first thing `onEnter` does is mount the preloader, wait for it to be painted,
+ * and dismiss the game's overlay. Everything after that line is identical on
+ * every platform.
  */
 export class LoadingScene extends Scene {
   private _engine!: any;
@@ -40,6 +52,12 @@ export class LoadingScene extends Scene {
     this._targetScene = targetScene;
     this._targetData = targetData;
     this._config = engine.config.loading ?? {};
+
+    // Take the screen from a game-supplied loading overlay, if there is one. Before any awaited
+    // work: from here on the player is looking at OUR loading screen, and `_startTime` (which
+    // `minDisplayTime` is measured from) must start when that becomes true.
+    await this.takeOverFromExternalOverlay();
+
     this._startTime = Date.now();
 
     // Initialize asset manager
@@ -104,8 +122,10 @@ export class LoadingScene extends Scene {
     this._displayedProgress = 1;
     this.updateLoaderBar(1);
 
-    // Wait for the player's tap — resolves immediately when tapToStart is
-    // false (the preloader honours that flag) — then enter the game.
+    // Wait for the player's tap — resolves immediately when tapToStart is false — then enter the
+    // game. This is the preloader's gate and it reads the preloader's config, so it means the same
+    // thing on every target: a game-supplied overlay has no say in it, and by now no part in the
+    // screen either. It was dismissed at the hand-over above; the player is looking at ours.
     await waitCSSPreloaderTap();
     await this.transitionToGame();
   }
@@ -131,6 +151,60 @@ export class LoadingScene extends Scene {
     void removeCSSPreloader(this.hostElement());
   }
 
+  // ─── Hand-over from a game-supplied overlay ────────────
+
+  /**
+   * Swap a game-supplied loading overlay for the engine's own loading screen.
+   *
+   * The overlay (Artube's) has been on screen since before this bundle was fetched, covering a gap
+   * nothing of ours could. Its job ends here, at the first frame the engine paints; the player then
+   * gets the game's own brand, progress bar and tap-to-start, exactly as on every other target.
+   *
+   * The order of the four steps is the whole design, and each is wrong on its own:
+   *
+   *  0. Wait out whatever the overlay is still owed on screen (`externalOverlayMinDisplayTime`,
+   *     default 1.5s, plus room for a phase crossfade already in flight). The gap this overlay
+   *     covers can be under half a second, which is not long enough for a partner's brand to
+   *     register. Waiting here — BEFORE mounting ours — rather than after is what keeps the two
+   *     screens' timelines from overlapping: our splash and brand floor start when the player can
+   *     actually see them, not behind someone else's overlay. On any boot slower than the floor
+   *     this step costs nothing, and on a non-Artube target it is not reached at all.
+   *  1. Mount the preloader, opaque and full-bleed, while theirs is still up. Both are on screen
+   *     together for a few frames, so there is never a moment with neither, whatever happens next.
+   *  2. Wait for that frame to actually be PAINTED — mounting only queues it. Dismissing theirs
+   *     before the paint is precisely the flash of bare background this ordering exists to avoid.
+   *     Two `requestAnimationFrame`s: the first callback runs before the frame it belongs to is
+   *     composited, the second after. Two frames is also enough for Pixi's own rAF-driven ticker
+   *     to have rendered this scene at least once, so "the loading scene has painted" is literally
+   *     true by the time step 3 runs.
+   *  3. Only then dismiss theirs. Their `hideLoader()` plays a 0.3s fade and removes the element.
+   *     Not waiting for that fade is deliberate — it is an animation on someone else's element,
+   *     and blocking a boot on it would be a hang waiting to happen.
+   *
+   * Which of the two is visually on top is the host page's business, not ours, and it does NOT
+   * change the guarantee. On a typical game page (`#game { position: fixed; inset: 0 }`) the fixed
+   * container establishes a stacking context, so the preloader's z-index is scoped inside it and
+   * Artube's `position: fixed; z-index: 9999` sits above — their fade then crossfades onto our
+   * loading screen, which is what was observed live and looks right. On a page where ours wins
+   * instead, their fade simply plays underneath, unseen. Either way the seam is covered, because
+   * what step 2 buys is that OUR screen is already painted before theirs starts going away.
+   */
+  private async takeOverFromExternalOverlay(): Promise<void> {
+    if (!hasExternalOverlay()) return;
+    await externalOverlayHold();
+    createCSSPreloader(this.hostElement(), this._config);
+    await this.nextPaint();
+    releaseExternalOverlay();
+  }
+
+  /** Resolves after the browser has composited at least one frame (see step 2 above). */
+  private nextPaint(): Promise<void> {
+    if (typeof requestAnimationFrame !== 'function') return Promise.resolve();
+    return new Promise<void>((resolve) => {
+      requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+    });
+  }
+
   // ─── Progress ──────────────────────────────────────────
 
   private updateLoaderBar(progress: number): void {

package/src/loading/index.ts

@@ -7,6 +7,12 @@ export {
   setCSSPreloaderProgress,
   waitCSSPreloaderTap,
   removeCSSPreloader,
+  adoptExternalOverlay,
+  advanceExternalOverlay,
+  externalOverlayHold,
+  releaseExternalOverlay,
+  hasExternalOverlay,
+  DEFAULT_EXTERNAL_MIN_DISPLAY_MS,
   buildLogoSVG,
   LOADER_BAR_MAX_WIDTH,
 } from '@energy8platform/platform-core/loading';

package/src/types.ts

@@ -37,6 +37,7 @@ export enum Orientation {
 // existing game-engine consumers keep their imports.
 import type {
   LoadingScreenConfig,
+  ExternalLoadingOverlay,
   AssetManifest,
   AssetBundle,
   AssetEntry,
@@ -44,6 +45,7 @@ import type {
 
 export type {
   LoadingScreenConfig,
+  ExternalLoadingOverlay,
   AssetManifest,
   AssetBundle,
   AssetEntry,