@energy8platform/game-engine 0.1.0

package/src/loading/CSSPreloader.ts

@@ -0,0 +1,155 @@
+import type { LoadingScreenConfig } from '../types';
+
+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>`;
+
+/**
+ * Creates a lightweight CSS-only preloader that appears instantly,
+ * BEFORE PixiJS/WebGL is initialized.
+ *
+ * Displays the Energy8 logo SVG with an animated loader bar.
+ */
+export function createCSSPreloader(
+  container: HTMLElement,
+  config?: LoadingScreenConfig,
+): void {
+  if (document.getElementById(PRELOADER_ID)) return;
+
+  const bgColor =
+    typeof config?.backgroundColor === 'string'
+      ? config.backgroundColor
+      : typeof config?.backgroundColor === 'number'
+        ? `#${config.backgroundColor.toString(16).padStart(6, '0')}`
+        : '#0a0a1a';
+
+  const bgGradient = config?.backgroundGradient ?? `linear-gradient(135deg, ${bgColor} 0%, #1a1a3e 100%)`;
+
+  const customHTML = config?.cssPreloaderHTML ?? '';
+
+  const el = document.createElement('div');
+  el.id = PRELOADER_ID;
+  el.innerHTML = customHTML || `
+    <div class="ge-preloader-content">
+      ${LOGO_SVG}
+    </div>
+  `;
+
+  const style = document.createElement('style');
+  style.textContent = `
+    #${PRELOADER_ID} {
+      position: absolute;
+      top: 0; left: 0;
+      width: 100%; height: 100%;
+      background: ${bgGradient};
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      z-index: 10000;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      transition: opacity 0.4s ease-out;
+    }
+
+    #${PRELOADER_ID}.ge-preloader-hidden {
+      opacity: 0;
+      pointer-events: none;
+    }
+
+    .ge-preloader-content {
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      width: 80%;
+      max-width: 700px;
+    }
+
+    .ge-logo-svg {
+      width: 100%;
+      height: auto;
+      filter: drop-shadow(0 0 30px rgba(121, 57, 194, 0.4));
+    }
+
+    /* Animate the loader clip-rect to shimmer while waiting */
+    .ge-clip-rect {
+      animation: ge-loader-fill 2s ease-in-out infinite;
+    }
+
+    @keyframes ge-loader-fill {
+      0%   { width: 0; }
+      50%  { width: 174; }
+      100% { width: 0; }
+    }
+
+    /* Animate the SVG text opacity */
+    .ge-preloader-svg-text {
+      animation: ge-pulse 1.5s ease-in-out infinite;
+    }
+
+    @keyframes ge-pulse {
+      0%, 100% { opacity: 0.4; }
+      50% { opacity: 1; }
+    }
+  `;
+
+  container.style.position = container.style.position || 'relative';
+  container.appendChild(style);
+  container.appendChild(el);
+}
+
+/**
+ * Remove the CSS preloader with a smooth fade-out transition.
+ */
+export function removeCSSPreloader(container: HTMLElement): void {
+  const el = document.getElementById(PRELOADER_ID);
+  if (!el) return;
+
+  el.classList.add('ge-preloader-hidden');
+
+  // Remove after transition
+  el.addEventListener('transitionend', () => {
+    el.remove();
+    // Also remove the style element
+    const styles = container.querySelectorAll('style');
+    for (const style of styles) {
+      if (style.textContent?.includes(PRELOADER_ID)) {
+        style.remove();
+      }
+    }
+  });
+}

package/src/loading/LoadingScene.ts

@@ -0,0 +1,356 @@
+import { Container, Graphics, Text, Sprite, Assets } from 'pixi.js';
+import { Scene } from '../core/Scene';
+import { Tween } from '../animation/Tween';
+import { Easing } from '../animation/Easing';
+import type { LoadingScreenConfig } from '../types';
+
+/**
+ * Inline SVG logo with a loader bar (clip-animated for progress).
+ * The clipPath rect width is set to 0 initially, expanded as loading progresses.
+ */
+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>`;
+}
+
+/** 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;
+  targetData?: unknown;
+}
+
+/**
+ * Built-in loading screen using the Energy8 SVG logo with animated loader bar.
+ *
+ * Renders as an HTML overlay on top of the canvas for crisp SVG quality.
+ * The loader bar fill width is driven by asset loading progress.
+ */
+export class LoadingScene extends Scene {
+  private _engine!: any;
+  private _targetScene!: string;
+  private _targetData?: unknown;
+  private _config!: LoadingScreenConfig;
+
+  // HTML overlay
+  private _overlay: HTMLDivElement | null = null;
+  private _loaderRect: SVGRectElement | null = null;
+  private _percentEl: Element | null = null;
+  private _tapToStartEl: Element | null = null;
+
+  // State
+  private _displayedProgress = 0;
+  private _targetProgress = 0;
+  private _loadingComplete = false;
+  private _startTime = 0;
+
+  override async onEnter(data?: unknown): Promise<void> {
+    const { engine, targetScene, targetData } = data as LoadingSceneData;
+    this._engine = engine;
+    this._targetScene = targetScene;
+    this._targetData = targetData;
+    this._config = engine.config.loading ?? {};
+    this._startTime = Date.now();
+
+    // Create the HTML overlay with the SVG logo
+    this.createOverlay();
+
+    // Initialize asset manager
+    await this._engine.assets.init();
+
+    // Initialize audio manager
+    await this._engine.audio.init();
+
+    // Phase 1: Load preload bundle
+    const bundles = this._engine.assets.getBundleNames();
+    const hasPreload = bundles.includes('preload');
+
+    if (hasPreload) {
+      const preloadAssets = this._engine.config.manifest?.bundles?.find(
+        (b: any) => b.name === 'preload',
+      )?.assets;
+
+      if (preloadAssets && preloadAssets.length > 0) {
+        await this._engine.assets.loadBundle('preload', (p: number) => {
+          this._targetProgress = p * 0.15;
+        });
+      } else {
+        this._targetProgress = 0.15;
+      }
+    }
+
+    // Phase 2: Load remaining bundles
+    const remainingBundles = bundles.filter(
+      (b: string) => b !== 'preload' && !this._engine.assets.isBundleLoaded(b),
+    );
+
+    if (remainingBundles.length > 0) {
+      const hasAssets = remainingBundles.some((name: string) => {
+        const bundle = this._engine.config.manifest?.bundles?.find(
+          (b: any) => b.name === name,
+        );
+        return bundle?.assets && bundle.assets.length > 0;
+      });
+
+      if (hasAssets) {
+        await this._engine.assets.loadBundles(remainingBundles, (p: number) => {
+          this._targetProgress = 0.15 + p * 0.85;
+        });
+      }
+    }
+
+    this._targetProgress = 1;
+    this._loadingComplete = true;
+
+    // Enforce minimum display time: spread the remaining progress fill
+    // over the remaining time so the bar fills smoothly, not abruptly
+    const minTime = this._config.minDisplayTime ?? 1500;
+    const elapsed = Date.now() - this._startTime;
+    const remaining = Math.max(0, minTime - elapsed);
+
+    if (remaining > 0) {
+      // Distribute fill animation over the remaining time
+      await this.animateProgressTo(1, remaining);
+    }
+
+    // Final snap to 100%
+    this._displayedProgress = 1;
+    this.updateLoaderBar(1);
+
+    // Show "Tap to Start" or transition directly
+    if (this._config.tapToStart !== false) {
+      await this.showTapToStart();
+    } else {
+      await this.transitionToGame();
+    }
+  }
+
+  override onUpdate(dt: number): void {
+    // Smooth progress bar fill via HTML (during active loading)
+    if (!this._loadingComplete && this._displayedProgress < this._targetProgress) {
+      this._displayedProgress = Math.min(
+        this._displayedProgress + dt * 1.5,
+        this._targetProgress,
+      );
+      this.updateLoaderBar(this._displayedProgress);
+    }
+  }
+
+  override onResize(_width: number, _height: number): void {
+    // Overlay is CSS-based, auto-resizes
+  }
+
+  override onDestroy(): void {
+    this.removeOverlay();
+  }
+
+  // ─── HTML Overlay ──────────────────────────────────────
+
+  private createOverlay(): void {
+    const bgColor =
+      typeof this._config.backgroundColor === 'string'
+        ? this._config.backgroundColor
+        : typeof this._config.backgroundColor === 'number'
+          ? `#${this._config.backgroundColor.toString(16).padStart(6, '0')}`
+          : '#0a0a1a';
+
+    const bgGradient =
+      this._config.backgroundGradient ??
+      `linear-gradient(135deg, ${bgColor} 0%, #1a1a3e 100%)`;
+
+    this._overlay = document.createElement('div');
+    this._overlay.id = '__ge-loading-overlay__';
+    this._overlay.innerHTML = `
+      <div class="ge-loading-content">
+        ${buildLogoSVG()}
+      </div>
+    `;
+
+    const style = document.createElement('style');
+    style.id = '__ge-loading-style__';
+    style.textContent = `
+      #__ge-loading-overlay__ {
+        position: absolute;
+        top: 0; left: 0;
+        width: 100%; height: 100%;
+        background: ${bgGradient};
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        z-index: 9999;
+        transition: opacity 0.5s ease-out;
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      }
+      #__ge-loading-overlay__.ge-fade-out {
+        opacity: 0;
+        pointer-events: none;
+      }
+      .ge-loading-content {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        width: 75%;
+        max-width: 650px;
+      }
+      .ge-loading-content svg {
+        filter: drop-shadow(0 0 40px rgba(121, 57, 194, 0.5));
+        cursor: default;
+      }
+
+      .ge-svg-pulse {
+        animation: ge-tap-pulse 1.2s ease-in-out infinite;
+      }
+      @keyframes ge-tap-pulse {
+        0%, 100% { opacity: 0.5; }
+        50% { opacity: 1; }
+      }
+    `;
+
+    // Get the container that holds the canvas
+    const container = this._engine.app?.canvas?.parentElement;
+    if (container) {
+      container.style.position = container.style.position || 'relative';
+      container.appendChild(style);
+      container.appendChild(this._overlay);
+    }
+
+    // Cache the SVG loader rect for progress updates
+    this._loaderRect = this._overlay.querySelector('#ge-loader-rect');
+    this._percentEl = this._overlay.querySelector('#ge-loader-pct');
+  }
+
+  private removeOverlay(): void {
+    this._overlay?.remove();
+    document.getElementById('__ge-loading-style__')?.remove();
+    this._overlay = null;
+    this._loaderRect = null;
+    this._percentEl = null;
+    this._tapToStartEl = null;
+  }
+
+  // ─── Progress ──────────────────────────────────────────
+
+  private updateLoaderBar(progress: number): void {
+    if (this._loaderRect) {
+      this._loaderRect.setAttribute('width', String(LOADER_BAR_MAX_WIDTH * progress));
+    }
+    if (this._percentEl) {
+      const pct = Math.round(progress * 100);
+      (this._percentEl as SVGTextElement).textContent = `${pct}%`;
+    }
+  }
+
+  /**
+   * Smoothly animate the displayed progress from its current value to `target`
+   * over `durationMs` using an easeOutCubic curve.
+   */
+  private async animateProgressTo(target: number, durationMs: number): Promise<void> {
+    const startVal = this._displayedProgress;
+    const delta = target - startVal;
+    if (delta <= 0 || durationMs <= 0) return;
+
+    const startTime = Date.now();
+
+    return new Promise<void>((resolve) => {
+      const tick = () => {
+        const elapsed = Date.now() - startTime;
+        const t = Math.min(elapsed / durationMs, 1);
+        // easeOutCubic for a natural deceleration feel
+        const eased = 1 - Math.pow(1 - t, 3);
+        this._displayedProgress = startVal + delta * eased;
+        this.updateLoaderBar(this._displayedProgress);
+
+        if (t < 1) {
+          requestAnimationFrame(tick);
+        } else {
+          resolve();
+        }
+      };
+      requestAnimationFrame(tick);
+    });
+  }
+
+  // ─── Tap to Start ─────────────────────────────────────
+
+  private async showTapToStart(): Promise<void> {
+    const tapText = this._config.tapToStartText ?? 'TAP TO START';
+
+    // Reuse the same SVG text element — replace percentage with tap text
+    if (this._percentEl) {
+      const el = this._percentEl as SVGTextElement;
+      el.textContent = tapText;
+      el.setAttribute('fill', '#ffffff');
+      el.classList.add('ge-svg-pulse');
+      this._tapToStartEl = el;
+    }
+
+    // Make overlay clickable
+    if (this._overlay) {
+      this._overlay.style.cursor = 'pointer';
+    }
+
+    // Wait for tap
+    return new Promise<void>((resolve) => {
+      const handler = async () => {
+        this._overlay?.removeEventListener('click', handler);
+        await this.transitionToGame();
+        resolve();
+      };
+
+      // Listen on the full overlay for easier mobile tap
+      this._overlay?.addEventListener('click', handler);
+    });
+  }
+
+  // ─── Transition ────────────────────────────────────────
+
+  private async transitionToGame(): Promise<void> {
+    // Fade out the HTML overlay
+    if (this._overlay) {
+      this._overlay.classList.add('ge-fade-out');
+      await new Promise<void>((resolve) => {
+        this._overlay!.addEventListener('transitionend', () => resolve(), { once: true });
+        // Safety timeout
+        setTimeout(resolve, 600);
+      });
+    }
+
+    // Remove overlay
+    this.removeOverlay();
+
+    // Navigate to the target scene
+    await this._engine.scenes.goto(this._targetScene, this._targetData);
+  }
+}

package/src/loading/index.ts

@@ -0,0 +1,2 @@
+export { LoadingScene } from './LoadingScene';
+export { createCSSPreloader, removeCSSPreloader } from './CSSPreloader';