@energy8platform/platform-core 0.30.10 → 0.31.0

package/src/loading/ExternalOverlay.ts

@@ -0,0 +1,249 @@
+/**
+ * A loading overlay the GAME owns, covering the gap the engine cannot: from the
+ * browser's first paint until the engine's own loading screen is on screen.
+ *
+ * The case this exists for is Artube. Their platform ships a branded loader
+ * whose markup a Vite plugin injects into `index.html`, so it is painted before
+ * the game bundle has even been fetched — earlier than any engine code can
+ * possibly run. That window (bundle download → Pixi init → SDK handshake) is
+ * otherwise a blank page.
+ *
+ * ── Where it stops ──────────────────────────────────────────────────────────
+ * It stops once BOTH are true: the engine's own loading screen has painted its
+ * first frame, and the overlay has had its guaranteed time on screen
+ * ({@link DEFAULT_EXTERNAL_MIN_DISPLAY_MS}, `loading.externalOverlayMinDisplayTime`).
+ * The gap alone is often only a few hundred milliseconds, which is not long
+ * enough for a partner's branding to register — let alone for their two-phase
+ * screen to reach its second phase.
+ *
+ * From there the player gets the engine's brand, the engine's progress bar and
+ * the engine's tap-to-start — exactly as on every other target. The external
+ * overlay covers the gap; it does not replace the loading screen, and it has no
+ * say in the tap gate: by then the player is looking at OUR screen.
+ *
+ * (This inverts an earlier design in which the external overlay REPLACED the
+ * CSS preloader for the whole boot. Handing over at the first frame keeps the
+ * game's own loading identity on every platform and leaves the built-in
+ * preloader's code path untouched — `CSSPreloader.ts` knows nothing about any
+ * of this, so non-Artube targets cannot be affected by a change here.)
+ *
+ * ── Structural, not nominal ─────────────────────────────────────────────────
+ * Nothing in `@energy8platform` names Artube's controller. The game passes an
+ * instance; we describe the shape (`ExternalLoadingOverlay`). Artube's vendored
+ * `LoaderViewController` (`@energy8platform/artube-bridge/loader`) satisfies it
+ * with no adapter.
+ *
+ * ── Module-level state ──────────────────────────────────────────────────────
+ * Singleton, like the CSS preloader next door, and for the same reason: the
+ * three call sites (boot, hand-over, failure path) are in different files and
+ * there is exactly one loading screen per page.
+ */
+import type { ExternalLoadingOverlay } from '../types';
+
+let adopted: ExternalLoadingOverlay | null = null;
+/** Last value pushed, so a repeated milestone cannot walk the bar backwards. */
+let lastProgress = 0;
+/** When the overlay was adopted — the origin the minimum display time is measured from. */
+let adoptedAt = 0;
+/** How long this overlay is owed on screen; see {@link DEFAULT_EXTERNAL_MIN_DISPLAY_MS}. */
+let minDisplayMs = 0;
+/** When the first progress went out, i.e. when their phase crossfade started. 0 = not yet. */
+let crossfadeStartedAt = 0;
+/** The one pending timer: the hand-over waiting out the floor below. */
+let holdTimer: ReturnType<typeof setTimeout> | null = null;
+let holdResolve: (() => void) | null = null;
+
+/**
+ * How long a game-supplied overlay is guaranteed on screen, measured from
+ * adoption (which is the first thing the boot does, so in practice from the
+ * page's first paint).
+ *
+ * Without a floor the overlay lives exactly as long as the gap it covers, and
+ * that gap is short: a warm local boot handed over at ~500ms and dismissed
+ * their screen at ~840ms. A partner's branding that flashes past in under a
+ * second has not been shown. 1500ms is the user's number, and it is also the
+ * smallest one that fits their two-phase screen whole — a 500ms crossfade into
+ * the branded phase plus time to read it — with room for the 300ms dismissal
+ * fade on top.
+ *
+ * Overridable per game: `loading.externalOverlayMinDisplayTime`.
+ */
+export const DEFAULT_EXTERNAL_MIN_DISPLAY_MS = 1500;
+
+/**
+ * Artube's partner→branded crossfade, `transition: opacity 0.5s ease` in the
+ * markup their Vite plugin injects (vendored verbatim in
+ * `@energy8platform/artube-server/vite`). It is triggered by the first
+ * `updateProgress` above zero.
+ *
+ * The floor below is extended to cover it because a crossfade that starts and
+ * then gets cut is worse than one that never starts: the player sees a
+ * half-formed gradient and a bar that never fills — the three-screens-at-once
+ * artefact this integration hit once and rejected (evidence:
+ * `rejected-immediate-progress-01-Lartube_P_C.png`). Extending the floor is
+ * bounded by construction: only the FIRST progress starts it, and every
+ * progress value comes from a boot milestone that precedes the hand-over.
+ */
+const PHASE_CROSSFADE_MS = 500;
+
+/**
+ * Call into the game's overlay without letting it break the boot. A third-party
+ * controller is outside our control (Artube's throws if its markup is missing,
+ * for one), and none of these calls is worth failing a game over — least of all
+ * `hideLoader`, where a throw escaping the teardown path is exactly how an
+ * overlay ends up stranded on screen forever.
+ */
+function guard(method: string, fn: () => void): void {
+  try {
+    fn();
+  } catch (err) {
+    console.warn(`[GameEngine] loading overlay ${method}() threw`, err);
+  }
+}
+
+/** Whether a game-supplied overlay is currently on screen and owned by us. */
+export function hasExternalOverlay(): boolean {
+  return adopted !== null;
+}
+
+/**
+ * Take ownership of the game's overlay: from here on the engine is responsible
+ * for taking it down, including when the boot fails.
+ *
+ * Called BEFORE anything in the boot that can throw — notably before the
+ * container selector is resolved. Until the engine has adopted it, nothing can
+ * dismiss it, and Artube's is already on screen from `index.html`.
+ *
+ * `showLoader()` is Artube's "reveal the progress affordance"; it does not
+ * switch their two-phase screen to the branded phase — only progress does, see
+ * {@link advanceExternalOverlay}.
+ *
+ * @param minDisplayMillis how long the overlay is owed on screen before the
+ * hand-over may dismiss it (`loading.externalOverlayMinDisplayTime`); defaults
+ * to {@link DEFAULT_EXTERNAL_MIN_DISPLAY_MS}. Adoption is where the clock
+ * starts, so it is taken here rather than read at the hand-over.
+ */
+export function adoptExternalOverlay(
+  overlay: ExternalLoadingOverlay,
+  minDisplayMillis?: number,
+): void {
+  if (adopted) return; // idempotent: boot step 0 and step 2 both reach here
+  adopted = overlay;
+  lastProgress = 0;
+  crossfadeStartedAt = 0;
+  minDisplayMs =
+    typeof minDisplayMillis === 'number' && Number.isFinite(minDisplayMillis)
+      ? Math.max(0, minDisplayMillis)
+      : DEFAULT_EXTERNAL_MIN_DISPLAY_MS;
+  adoptedAt = Date.now();
+  guard('showLoader', () => overlay.showLoader());
+}
+
+/**
+ * Report boot progress, as a 0..1 fraction, to a game-supplied overlay.
+ *
+ * NOT the asset-loading progress the built-in preloader shows — that belongs to
+ * the engine's own loading screen, which by then has taken over. This is the
+ * pre-first-frame boot: bundle up, Pixi up, SDK handshake done.
+ *
+ * Sending it is deliberate, not decorative: Artube's loader only crossfades to
+ * its BRANDED phase on the first value above zero, so without progress the
+ * player never sees the half of their screen the integration exists to show.
+ * Values go out as they arrive — the guarantee that the crossfade has room to
+ * finish is the dismissal floor ({@link externalOverlayHold}), not a delay
+ * here. An earlier design held the first value back for 800ms instead; the
+ * floor makes that redundant, and one timer on this overlay is the whole point.
+ *
+ * Values are clamped to 0..1, kept monotonic, and converted to the PERCENTAGE
+ * (0–100) that `ILoaderViewController.updateProgress` documents.
+ */
+export function advanceExternalOverlay(fraction: number): void {
+  const overlay = adopted;
+  if (!overlay) return;
+  const clamped = Number.isFinite(fraction) ? Math.max(0, Math.min(1, fraction)) : 0;
+  if (clamped <= lastProgress) return;
+  lastProgress = clamped;
+  // The first non-zero value is what starts their partner→branded crossfade, so
+  // it is also what the floor has to cover.
+  if (clamped > 0 && crossfadeStartedAt === 0) crossfadeStartedAt = Date.now();
+  guard('updateProgress', () => overlay.updateProgress(clamped * 100));
+}
+
+/**
+ * Milliseconds still owed to the overlay before the hand-over may dismiss it:
+ * the minimum display time, extended when needed so a phase crossfade that has
+ * started can finish. Zero once both are satisfied — and zero when there is no
+ * overlay, so nothing on a normal target ever waits.
+ */
+function remainingHoldMs(): number {
+  if (!adopted) return 0;
+  const now = Date.now();
+  const floor = Math.max(
+    adoptedAt + minDisplayMs,
+    crossfadeStartedAt === 0 ? 0 : crossfadeStartedAt + PHASE_CROSSFADE_MS,
+  );
+  return Math.max(0, floor - now);
+}
+
+/**
+ * Wait until the overlay has had its guaranteed time on screen. The hand-over
+ * awaits this BEFORE it mounts the engine's own loading screen, so the two
+ * timelines do not overlap: their screen is whole and undisturbed for the whole
+ * window, then ours mounts, paints, and only then takes over.
+ *
+ * Resolves immediately when no overlay is adopted (every non-Artube target) or
+ * when the floor has already passed (any boot slower than it, which is the
+ * normal case in production — this costs nothing there).
+ *
+ * NOT part of the failure path on purpose: {@link releaseExternalOverlay} is
+ * synchronous and immediate, so a boot that throws takes the overlay down at
+ * once instead of stranding the player behind a courtesy delay. A release also
+ * settles a wait already in progress.
+ */
+export function externalOverlayHold(): Promise<void> {
+  // Reaching here means the boot is done and the only thing left is the wait, so the bar is
+  // finished too. Without this it freezes at the last boot milestone (0.85 live) and their screen
+  // is taken away with the bar still short — a bar that never fills, which is the same artefact in
+  // a different costume. Only when a bar is actually on screen: if no progress ever went out the
+  // player is still on the first phase, and starting a crossfade at the hand-over is precisely
+  // what must not happen.
+  if (crossfadeStartedAt !== 0) advanceExternalOverlay(1);
+  const remaining = remainingHoldMs();
+  if (remaining <= 0) return Promise.resolve();
+  return new Promise<void>((resolve) => {
+    const finish = () => {
+      if (holdTimer !== null) clearTimeout(holdTimer);
+      holdTimer = null;
+      holdResolve = null;
+      resolve();
+    };
+    holdResolve = finish;
+    holdTimer = setTimeout(finish, remaining);
+  });
+}
+
+/**
+ * Dismiss the overlay and forget it. Idempotent — this is reached both on the
+ * normal hand-over and defensively from the failure paths, and a second
+ * `hideLoader()` must not fire.
+ *
+ * @returns whether this call is the one that dismissed it. Callers that can run
+ * BEFORE adoption (`createSlotGame`'s `fatal`, which refuses some launches
+ * before `GameApplication` exists) use the `false` to fall back to hiding the
+ * game's overlay directly.
+ */
+export function releaseExternalOverlay(): boolean {
+  // Settle a hand-over that is still waiting out the floor, even if there is
+  // nothing to release. This is the failure path: a boot that threw must not
+  // leave a timer holding the process open (Node-side tests) or a promise that
+  // resolves into a teardown that already happened.
+  if (holdResolve) holdResolve();
+
+  const overlay = adopted;
+  if (!overlay) return false;
+  adopted = null;
+  lastProgress = 0;
+  crossfadeStartedAt = 0;
+  guard('hideLoader', () => overlay.hideLoader());
+  return true;
+}

package/src/loading/index.ts

@@ -4,6 +4,19 @@ export {
   waitCSSPreloaderTap,
   removeCSSPreloader,
 } from './CSSPreloader';
+/**
+ * A game-supplied overlay covering the gap before the engine's own loading
+ * screen paints (Artube's branded loader). Deliberately NOT part of
+ * `CSSPreloader.ts`: the built-in preloader must have no branch for it.
+ */
+export {
+  adoptExternalOverlay,
+  advanceExternalOverlay,
+  externalOverlayHold,
+  releaseExternalOverlay,
+  hasExternalOverlay,
+  DEFAULT_EXTERNAL_MIN_DISPLAY_MS,
+} from './ExternalOverlay';
 export { buildLogoSVG, LOADER_BAR_MAX_WIDTH } from './logo';
 export { VARIANTS, DEFAULT_VARIANT_NAME } from './variants';
 export type {
@@ -11,4 +24,10 @@ export type {
   PreloaderVariantHandle,
   PreloaderVariantName,
 } from './variants';
-export type { LoadingScreenConfig, AssetManifest, AssetBundle, AssetEntry } from '../types';
+export type {
+  LoadingScreenConfig,
+  ExternalLoadingOverlay,
+  AssetManifest,
+  AssetBundle,
+  AssetEntry,
+} from '../types';

package/src/loading/variants/voidmoon.ts

@@ -4,41 +4,50 @@ import type { PreloaderVariant, PreloaderVariantHandle } from './types';
 const RECT_ID = 'ge-vm-loader-rect';
 const TEXT_ID = 'ge-vm-loader-text';
 
-/** Max width (SVG units) of the voidmoon loader bar fill. Spans the first 'o' → end of the crescent. */
-const LOADER_BAR_MAX_WIDTH = 751;
+/** Left edge (SVG units) of the loader bar — aligned with the "V" of the wordmark. */
+const LOADER_BAR_X = 249.79;
+
+/** Max width (SVG units) of the voidmoon loader bar fill. Spans the wordmark: "V" → end of the final "N". */
+const LOADER_BAR_MAX_WIDTH = 519;
 
 /**
- * "voidmoon" wordmark — the official logo, embedded verbatim as SVG outlines:
- * thin white letters with the final "o" of "moon" rendered as a purple crescent
- * (#9D63FE). The glyphs live in a flipped group (`translate(0,941) scale(1,-1)`)
- * exactly as exported; the loader bar + status text are added beneath it in the
- * outer (un-flipped) viewBox space.
+ * voidmoon logo — the official lockup, embedded verbatim as SVG outlines:
+ * the crescent-moon-and-spark mark on the left, the "VOIDMOON" wordmark on the
+ * right, all in #f5f5f5 (filled *and* stroked, exactly as exported — the stroke
+ * is what gives the thin glyphs their weight). The export's `.st0` / `.st1`
+ * classes are inlined as presentation attributes on two wrapper groups so the
+ * logo carries no global CSS into the host page.
+ *
+ * The loader bar + status text are added beneath the lockup in the same
+ * viewBox space; the viewBox is taller than the artwork (140.2) to make room.
  */
-const LOGO_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="301 339 1075 335" class="ge-vm-logo-svg" style="overflow:visible" role="img">
+const LOGO_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 769.28 215" class="ge-vm-logo-svg" style="overflow:visible" role="img">
   <title>voidmoon</title>
-  <g transform="translate(0,941) scale(1,-1)">
-    <g fill="#ffffff" fill-rule="evenodd">
-      <path d="M627 562 c-4 -2 -7 -6 -7 -12 0 -13 14 -18 23 -10 3 3 3 5 4 9 0 7 -2 11 -7 13 -5 2 -9 2 -13 0z"/>
-      <path d="M780 531 l0 -31 -6 5 c-14 14 -35 17 -56 10 -24 -8 -40 -28 -42 -53 0 -11 1 -19 6 -30 8 -16 22 -27 40 -32 8 -2 23 -2 31 0 18 4 34 17 42 33 2 5 4 11 5 14 1 3 1 24 1 61 l0 55 -10 0 -11 0 0 -32z m-24 -38 c20 -10 28 -31 20 -50 -3 -6 -13 -16 -19 -19 -21 -10 -45 -2 -56 18 -2 4 -2 7 -3 14 -1 14 4 24 15 33 8 6 15 8 27 8 9 -1 10 -1 16 -4z"/>
-      <path d="M520 518 c-26 -6 -45 -25 -50 -51 -1 -9 -1 -11 0 -19 3 -12 7 -21 15 -30 8 -8 16 -13 28 -17 6 -2 9 -2 19 -2 10 0 13 0 20 2 21 8 36 24 41 46 1 8 1 13 0 22 -5 23 -21 40 -44 47 -6 2 -23 3 -29 2z m29 -25 c9 -4 16 -11 20 -19 2 -5 3 -6 3 -15 0 -10 -1 -11 -3 -16 -8 -15 -23 -24 -40 -23 -9 1 -15 3 -22 8 -22 15 -21 48 2 63 7 4 14 6 24 6 8 -1 10 -1 16 -4z"/>
-      <path d="M869 518 c-21 -4 -35 -18 -40 -38 -1 -6 -1 -14 -1 -43 l1 -35 10 0 11 0 0 37 c0 33 1 38 2 41 3 7 7 11 13 14 5 2 8 3 13 3 11 0 20 -5 25 -16 l3 -5 0 -37 1 -37 10 0 10 0 0 37 c0 35 1 37 3 42 5 10 14 16 26 16 11 0 21 -7 25 -17 2 -5 2 -7 2 -41 0 -19 0 -36 1 -37 0 -1 3 -1 11 -1 l10 1 0 35 c0 23 0 38 -1 42 -2 9 -8 21 -14 27 -20 17 -51 17 -68 -1 l-5 -5 -5 5 c-9 9 -19 13 -31 14 -5 0 -10 0 -12 -1z"/>
-      <path d="M1077 517 c-9 -1 -20 -7 -27 -12 -7 -6 -14 -16 -18 -25 -4 -11 -5 -25 -3 -35 5 -21 21 -37 42 -44 38 -12 78 14 81 53 1 15 -4 31 -14 43 -14 17 -38 25 -61 20z m25 -22 c19 -5 31 -24 28 -42 -4 -26 -34 -41 -59 -29 -20 10 -27 32 -17 52 8 16 29 25 48 19z"/>
-      <path d="M1282 516 c-18 -5 -34 -21 -38 -39 -1 -4 -1 -18 -1 -40 l1 -35 10 -1 10 0 0 32 c0 20 0 35 1 38 2 11 8 18 18 23 7 3 18 3 26 0 6 -3 12 -9 15 -16 2 -4 3 -6 3 -40 l1 -36 10 0 11 0 0 33 c0 38 0 43 -6 54 -7 14 -19 24 -34 28 -7 1 -20 1 -27 -1z"/>
-      <path d="M329 515 c0 -1 2 -5 4 -9 2 -5 13 -28 24 -53 12 -24 21 -45 22 -46 2 -4 10 -7 15 -7 4 0 11 3 13 6 3 2 50 105 50 108 0 1 -3 1 -11 1 l-11 0 -7 -14 c-3 -8 -12 -28 -20 -45 -7 -17 -13 -31 -14 -31 -1 -1 -3 5 -17 35 -19 43 -23 53 -24 54 -1 1 -5 1 -13 1 -6 0 -11 0 -11 0z"/>
-      <path d="M623 514 c0 -1 0 -26 0 -57 l1 -55 10 0 10 0 0 56 0 57 -10 0 c-7 0 -10 0 -11 -1z"/>
-    </g>
-    <g fill="#9D63FE" fill-rule="evenodd">
-      <path d="M1150 515 c-3 0 -6 -1 -6 -1 0 -1 2 -2 5 -2 10 -4 26 -17 31 -27 11 -21 8 -44 -7 -62 -5 -7 -17 -16 -24 -18 -3 -1 -5 -2 -4 -2 0 -2 16 -3 24 -3 35 3 59 40 49 74 -2 8 -7 18 -13 24 -5 6 -15 13 -23 16 -8 3 -24 4 -32 1z"/>
-    </g>
+  <g fill="#f5f5f5" stroke="#f5f5f5" stroke-miterlimit="10">
+    <polygon points="274.76 98.02 249.79 48.07 256.03 48.07 274.76 85.54 293.49 48.07 299.74 48.07 274.76 98.02"/>
+    <path d="M325.51,70.2h6.24c1.12-8.22,7.63-14.65,15.83-15.85v-6.24c-11.99,1.24-20.85,10.36-22.07,22.1ZM353.82,48.1v6.24c9.03,1.32,15.48,9.27,15.48,18.67,0,10.33-8.4,18.73-18.73,18.73-9.33,0-17.41-6.36-18.82-15.3h-6.24c1.49,12.45,11.94,21.55,25.06,21.55,14.14,0,24.97-11.14,24.97-24.97,0-12.92-8.88-23.58-21.72-24.91Z"/>
+    <rect x="400.39" y="48.08" width="6.24" height="49.95"/>
+    <path d="M437.62,54.32l-6.14-6.24h19.14c13.15,0,23.81,10.85,23.81,24.22v.63c0,13.91-10.99,25.1-24.54,25.1-9.62,0-18.41,0-18.41,0l6.14-6.24h12.27c10.17,0,18.41-8.39,18.41-18.73h0c0-10.34-8.24-18.73-18.41-18.73h-12.27Z"/>
+    <polygon points="499.59 98.02 505.83 98.02 505.85 63.24 524.56 79.29 543.29 64.35 543.29 98.02 549.54 98.02 549.54 48.07 524.62 70.2 499.59 48.07 499.59 98.02"/>
+    <polygon points="725.07 68.91 731.32 74.56 731.32 98.02 725.07 98.02 725.07 68.91"/>
+    <polygon points="768.78 48.07 768.78 98.01 762.53 92.38 753.31 84.06 753.31 84.05 725.07 58.51 725.07 48.1 731.32 53.73 762.53 81.87 762.53 48.07 768.78 48.07"/>
+    <path d="M602.55,48.03v6.24c8.22,1.12,14.65,7.63,15.85,15.83h6.24c-1.24-11.99-10.36-20.85-22.1-22.07ZM624.65,76.34h-6.24c-1.32,9.03-9.27,15.48-18.67,15.48-10.33,0-18.73-8.4-18.73-18.73,0-9.33,6.36-17.41,15.3-18.82v-6.24c-12.45,1.49-21.55,11.94-21.55,25.06,0,14.14,11.14,24.97,24.97,24.97,12.92,0,23.58-8.88,24.91-21.72Z"/>
+    <path d="M699.92,75.89h-6.24c-1.12,8.22-7.63,14.65-15.83,15.85v6.24c11.99-1.24,20.85-10.36,22.07-22.1ZM671.6,97.99v-6.24c-9.03-1.32-15.48-9.27-15.48-18.67,0-10.33,8.4-18.73,18.73-18.73,9.33,0,17.41,6.36,18.82,15.3h6.24c-1.49-12.45-11.94-21.55-25.06-21.55-14.14,0-24.97,11.14-24.97,24.97,0,12.92,8.88,23.58,21.72,24.91Z"/>
+  </g>
+  <g fill="#f5f5f5" stroke="#f5f5f5" stroke-miterlimit="10" stroke-width="2">
+    <path d="M199.39,73.47h.01c-1.76,36.6-31.98,65.73-69.01,65.73s-67.52-29.39-69.04-66.2c-.9-.53-1.53-1.47-1.63-2.57l-22.61,2.67c-1.75.2-3.12,1.6-3.3,3.35l-2.47,24.86-3.11-24.95c-.21-1.7-1.56-3.06-3.28-3.25L.12,70.11l25.29-1.97c1.83-.14,3.28-1.57,3.46-3.38l2.47-25.88,2.47,25.88c.18,1.81,1.63,3.24,3.45,3.38l22.45,1.74c.06-1.14.7-2.13,1.64-2.68C62.87,30.38,93.2,1,130.39,1s67.25,29.12,69.01,65.72h0s-.01,0-.01,0c-1.74-30.76-27.24-55.15-58.43-55.15s-58.52,26.2-58.52,58.52,26.2,58.52,58.52,58.52,56.69-24.4,58.43-55.15Z"/>
+    <path d="M202.84,70.1c0,1.86-1.51,3.38-3.37,3.38-.02,0-.05,0-.07,0,.02-.25.02-.49.03-.74-.01.25-.03.49-.04.74-1.83-.04-3.3-1.53-3.3-3.37s1.47-3.34,3.3-3.37c.01.25.03.49.04.74-.01-.25-.01-.49-.03-.74.02,0,.05,0,.07,0,1.86,0,3.37,1.51,3.37,3.38Z"/>
+    <line x1="232.26" y1="70.1" x2="202.84" y2="70.1"/>
+    <line x1="196.09" y1="70.1" x2="166.58" y2="70.1"/>
   </g>
 
-  <rect x="469" y="600" width="751" height="9" rx="4.5" fill="rgba(255,255,255,0.12)"/>
+  <rect x="${LOADER_BAR_X}" y="170" width="${LOADER_BAR_MAX_WIDTH}" height="6.5" rx="3.25" fill="rgba(255,255,255,0.12)"/>
   <clipPath id="vm-loader-clip">
-    <rect id="${RECT_ID}" x="469" y="600" width="0" height="9" rx="4.5" class="ge-vm-clip-rect"/>
+    <rect id="${RECT_ID}" x="${LOADER_BAR_X}" y="170" width="0" height="6.5" rx="3.25" class="ge-vm-clip-rect"/>
   </clipPath>
-  <rect x="469" y="600" width="751" height="9" rx="4.5" fill="#9D63FE" clip-path="url(#vm-loader-clip)"/>
+  <rect x="${LOADER_BAR_X}" y="170" width="${LOADER_BAR_MAX_WIDTH}" height="6.5" rx="3.25" fill="#9D63FE" clip-path="url(#vm-loader-clip)"/>
 
-  <text id="${TEXT_ID}" x="844.5" y="650" text-anchor="middle" class="ge-vm-text">Loading...</text>
+  <text id="${TEXT_ID}" x="${LOADER_BAR_X + LOADER_BAR_MAX_WIDTH / 2}" y="205" text-anchor="middle" class="ge-vm-text">Loading...</text>
 </svg>`;
 
 export const voidmoonVariant: PreloaderVariant = {
@@ -72,7 +81,7 @@ export const voidmoonVariant: PreloaderVariant = {
 
     @keyframes ge-vm-fill {
       0%   { width: 0; }
-      50%  { width: 751; }
+      50%  { width: 519px; }
       100% { width: 0; }
     }
 
@@ -84,9 +93,9 @@ export const voidmoonVariant: PreloaderVariant = {
     .ge-vm-text {
       fill: rgba(255, 255, 255, 0.6);
       font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-      font-size: 20px;
+      font-size: 14px;
       font-weight: 600;
-      letter-spacing: 3px;
+      letter-spacing: 2.2px;
       animation: ge-vm-pulse 1.5s ease-in-out infinite;
     }
 

package/src/types.ts

@@ -44,7 +44,62 @@ export interface AssetManifest {
 // Used by the Energy8 CSS preloader (in this package) and by
 // engine-specific loading scenes (in @energy8platform/game-engine etc.).
 
+/**
+ * A loading overlay the GAME owns, covering the gap BEFORE the engine's own loading screen exists:
+ * from the browser's first paint to the first frame the engine paints. It does not replace the
+ * loading screen — see `LoadingScreenConfig.externalOverlay`.
+ *
+ * Described structurally on purpose. The implementation this exists for is Artube's
+ * `LoaderViewController` (vendored at `@energy8platform/artube-bridge/loader`), whose markup their
+ * Vite plugin injects into `index.html` so the overlay is painted before our bundle is even
+ * fetched. Naming that type here would tie every consumer of platform-core to the Artube packages;
+ * the shape is satisfied with no adapter, and nothing in `@energy8platform/platform-core` knows
+ * Artube exists.
+ *
+ * The engine's use of it, in order:
+ *  - `showLoader()` once, at the very start of boot, before anything that can throw;
+ *  - `updateProgress(0..100)` at boot milestones (Pixi up, SDK handshake done, subsystems up) —
+ *    real progress through the gap, not the asset loading that follows;
+ *  - `hideLoader()` the moment the engine's loading screen has painted its first frame — AND on
+ *    every failure path, so a boot that throws can never leave the overlay on screen forever.
+ */
+export interface ExternalLoadingOverlay {
+  /** Reveal the overlay / its progress affordance. Called once, at the start of boot. */
+  showLoader(): void;
+  /** Loading progress as a PERCENTAGE, 0–100 (what `ILoaderViewController` expects — the engine's
+   *  internal 0..1 fraction is converted at the seam). */
+  updateProgress(value: number): void;
+  /** Dismiss the overlay. Called once; must tolerate being called after a failed boot. */
+  hideLoader(): void;
+}
+
 export interface LoadingScreenConfig {
+  /**
+   * A game-supplied loading overlay covering ONLY the gap before the engine's own loading screen
+   * paints — Artube's branded loader is the case this exists for. It is not a replacement: once the
+   * loading screen has painted its first frame, the overlay is dismissed and the rest of the boot
+   * (brand, progress bar, tap-to-start, minimum display time) is exactly what it is on every other
+   * target. Every other option in this object therefore still applies.
+   *
+   * The two never stack visibly: the built-in preloader is mounted only at the hand-over, and it
+   * covers the external overlay (z-index) from the frame it appears in, so there is no gap, no
+   * flash and no bare background at the seam.
+   */
+  externalOverlay?: ExternalLoadingOverlay;
+  /**
+   * How long {@link externalOverlay} is guaranteed on screen, in ms, measured from the boot's very
+   * first step. Default 1500.
+   *
+   * The gap this overlay covers is short — a warm boot hands over in a few hundred milliseconds —
+   * and a partner's branding that flashes past in under a second has not been shown. The floor also
+   * gives a two-phase overlay (Artube's) room to reach its second phase and settle there instead of
+   * being cut mid-crossfade. It costs a slow boot nothing: the hand-over happens later than this
+   * anyway.
+   *
+   * Distinct from {@link minDisplayTime}, which is the minimum for the engine's OWN loading screen
+   * and is measured from the hand-over. A game that sets both is asking for the sum.
+   */
+  externalOverlayMinDisplayTime?: number;
   /**
    * Which visual identity the CSS preloader renders. Defaults to `'energy8'`;
    * an unknown value falls back to the default. Ignored when `cssPreloaderHTML`