@energy8platform/platform-core 0.17.1 → 0.18.0

package/dist/loading.esm.js

@@ -68,22 +68,23 @@ ${defs}
 }
 
 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 RECT_ID = 'ge-pl-loader-rect';
+const TEXT_ID = 'ge-pl-loader-text';
+const REMOVE_FADE_TIMEOUT_MS = 600;
 const LOGO_SVG = buildLogoSVG({
     idPrefix: 'pl',
     svgClass: 'ge-logo-svg',
     clipRectClass: 'ge-clip-rect',
+    clipRectId: RECT_ID,
     textClass: 'ge-preloader-svg-text',
+    textId: TEXT_ID,
 });
-/**
- * Creates a lightweight CSS-only preloader that appears instantly,
- * BEFORE PixiJS/WebGL is initialized.
- *
- * Displays the Energy8 logo SVG with an animated loader bar.
- */
+let state = null;
+function clampProgress(p) {
+    if (!Number.isFinite(p))
+        return 0;
+    return Math.max(0, Math.min(1, p));
+}
 function createCSSPreloader(container, config) {
     if (document.getElementById(PRELOADER_ID))
         return;
@@ -94,15 +95,15 @@ function createCSSPreloader(container, config) {
             : '#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 || `
+    const overlay = document.createElement('div');
+    overlay.id = PRELOADER_ID;
+    overlay.innerHTML = customHTML || `
     <div class="ge-preloader-content">
       ${LOGO_SVG}
     </div>
   `;
-    const style = document.createElement('style');
-    style.textContent = `
+    const styleEl = document.createElement('style');
+    styleEl.textContent = `
     #${PRELOADER_ID} {
       position: absolute;
       top: 0; left: 0;
@@ -155,31 +156,146 @@ function createCSSPreloader(container, config) {
       0%, 100% { opacity: 0.4; }
       50% { opacity: 1; }
     }
+
+    /* Stop shimmer once JS-driven progress takes over. */
+    .ge-clip-rect.driven {
+      animation: none;
+    }
+
+    /* Tap-to-start CTA pulse. Compound selector outweighs the ambient
+       .ge-preloader-svg-text rule, swapping the animation cleanly. */
+    .ge-preloader-svg-text.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; }
+    }
   `;
     container.style.position = container.style.position || 'relative';
-    container.appendChild(style);
-    container.appendChild(el);
+    container.appendChild(styleEl);
+    container.appendChild(overlay);
+    const rectEl = overlay.querySelector(`#${RECT_ID}`);
+    const textEl = overlay.querySelector(`#${TEXT_ID}`);
+    if (!rectEl || !textEl) {
+        // Custom HTML mode — no logo SVG, lifecycle API becomes mostly inert.
+        // We still record state so removeCSSPreloader works.
+        state = {
+            container,
+            overlay,
+            styleEl,
+            rectEl: null,
+            textEl: null,
+            showPercentage: false,
+            tapToStart: config?.tapToStart !== false,
+            tapToStartText: config?.tapToStartText ?? 'TAP TO START',
+            driven: false,
+            tapState: 'idle',
+            tapPromise: null,
+            tapResolve: null,
+            tapHandler: null,
+            removed: false,
+        };
+        return;
+    }
+    state = {
+        container,
+        overlay,
+        styleEl,
+        rectEl,
+        textEl,
+        showPercentage: config?.showPercentage === true,
+        tapToStart: config?.tapToStart !== false,
+        tapToStartText: config?.tapToStartText ?? 'TAP TO START',
+        driven: false,
+        tapState: 'idle',
+        tapPromise: null,
+        tapResolve: null,
+        tapHandler: null,
+        removed: false,
+    };
 }
-/**
- * Remove the CSS preloader with a smooth fade-out transition.
- */
-function removeCSSPreloader(container) {
-    const el = document.getElementById(PRELOADER_ID);
-    if (!el)
+function setCSSPreloaderProgress(progress) {
+    if (!state || state.removed)
+        return;
+    if (state.tapState === 'waiting' || state.tapState === 'resolved')
+        return;
+    if (!state.rectEl)
         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();
-            }
-        }
+    const p = clampProgress(progress);
+    if (!state.driven) {
+        state.rectEl.classList.add('driven');
+        state.driven = true;
+    }
+    state.rectEl.setAttribute('width', String(p * LOADER_BAR_MAX_WIDTH));
+    if (state.showPercentage && state.textEl) {
+        state.textEl.textContent = `${Math.round(p * 100)}%`;
+    }
+}
+function waitCSSPreloaderTap() {
+    if (!state) {
+        throw new Error('CSS preloader not initialized — call createCSSPreloader first');
+    }
+    if (state.removed)
+        return Promise.resolve();
+    if (!state.tapToStart)
+        return Promise.resolve();
+    if (state.tapPromise)
+        return state.tapPromise;
+    if (state.textEl) {
+        state.textEl.textContent = state.tapToStartText;
+        state.textEl.classList.add('ge-svg-pulse');
+    }
+    state.overlay.style.cursor = 'pointer';
+    state.tapState = 'waiting';
+    state.tapPromise = new Promise((resolve) => {
+        state.tapResolve = resolve;
+        const handler = (_e) => {
+            if (!state)
+                return;
+            state.overlay.removeEventListener('pointerdown', handler);
+            state.tapHandler = null;
+            state.tapState = 'resolved';
+            state.tapResolve = null;
+            resolve();
+        };
+        state.tapHandler = handler;
+        state.overlay.addEventListener('pointerdown', handler);
+    });
+    return state.tapPromise;
+}
+function removeCSSPreloader(_container) {
+    if (!state || state.removed)
+        return Promise.resolve();
+    // Detach the pending pointer listener (if any) and resolve a pending tap.
+    if (state.tapHandler) {
+        state.overlay.removeEventListener('pointerdown', state.tapHandler);
+        state.tapHandler = null;
+    }
+    if (state.tapState === 'waiting' && state.tapResolve) {
+        state.tapState = 'resolved';
+        state.tapResolve();
+        state.tapResolve = null;
+    }
+    state.removed = true;
+    const { overlay, styleEl } = state;
+    overlay.classList.add('ge-preloader-hidden');
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            overlay.remove();
+            styleEl.remove();
+            state = null;
+            resolve();
+        };
+        overlay.addEventListener('transitionend', finish, { once: true });
+        setTimeout(finish, REMOVE_FADE_TIMEOUT_MS);
     });
 }
 
-export { LOADER_BAR_MAX_WIDTH, buildLogoSVG, createCSSPreloader, removeCSSPreloader };
+export { LOADER_BAR_MAX_WIDTH, buildLogoSVG, createCSSPreloader, removeCSSPreloader, setCSSPreloaderProgress, waitCSSPreloaderTap };
 //# sourceMappingURL=loading.esm.js.map

package/dist/loading.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"loading.esm.js","sources":["../src/loading/logo.ts","../src/loading/CSSPreloader.ts"],"sourcesContent":[null,null],"names":[],"mappings":"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"}
+{"version":3,"file":"loading.esm.js","sources":["../src/loading/logo.ts","../src/loading/CSSPreloader.ts"],"sourcesContent":[null,null],"names":[],"mappings":"AAAA;;;;;;;AAOG;AAEH;AACA,MAAM,cAAc,GAAG;;;;;+XAKwW;AAE/X;AACA,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;sBAkBA;AAEtB;AACO,MAAM,oBAAoB,GAAG;AAqBpC;;;;;AAKG;AACG,SAAU,YAAY,CAAC,IAAoB,EAAA;AAC/C,IAAA,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,GAAG,IAAI;;AAGxG,IAAA,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,UAAU,EAAE,CAAA,EAAG,QAAQ,CAAA,EAAA,CAAI,CAAC;AACjE,IAAA,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,UAAU,EAAE,CAAA,EAAG,QAAQ,CAAA,EAAA,CAAI,CAAC;AAE/D,IAAA,MAAM,MAAM,GAAG,CAAA,EAAG,QAAQ,cAAc;AACxC,IAAA,MAAM,cAAc,GAAG,CAAA,EAAG,QAAQ,GAAG;AAErC,IAAA,MAAM,SAAS,GAAG,QAAQ,GAAG,CAAA,QAAA,EAAW,QAAQ,CAAA,CAAA,CAAG,GAAG,EAAE;AACxD,IAAA,MAAM,SAAS,GAAG,QAAQ,GAAG,CAAA,QAAA,EAAW,QAAQ,CAAA,CAAA,CAAG,GAAG,EAAE;AACxD,IAAA,MAAM,aAAa,GAAG,aAAa,GAAG,CAAA,QAAA,EAAW,aAAa,CAAA,CAAA,CAAG,GAAG,EAAE;AACtE,IAAA,MAAM,UAAU,GAAG,UAAU,GAAG,CAAA,KAAA,EAAQ,UAAU,CAAA,CAAA,CAAG,GAAG,EAAE;AAC1D,IAAA,MAAM,SAAS,GAAG,MAAM,GAAG,CAAA,KAAA,EAAQ,MAAM,CAAA,CAAA,CAAG,GAAG,EAAE;AACjD,IAAA,MAAM,YAAY,GAAG,SAAS,GAAG,CAAA,QAAA,EAAW,SAAS,CAAA,CAAA,CAAG,GAAG,EAAE;IAE7D,OAAO,CAAA,yEAAA,EAA4E,SAAS,CAAA,EAAG,SAAS,CAAA;EACxG,KAAK;kBACW,MAAM,CAAA;AACb,SAAA,EAAA,UAAU,wCAAwC,aAAa,CAAA;;AAEkG,0KAAA,EAAA,cAAc,sBAAsB,MAAM,CAAA;AAC7M,OAAA,EAAA,SAAS,CAAA,mMAAA,EAAsM,YAAY,CAAA,CAAA,EAAI,WAAW,IAAI,YAAY,CAAA;;EAEjQ,IAAI;;OAEC;AACP;;AC3FA,MAAM,YAAY,GAAG,sBAAsB;AAC3C,MAAM,OAAO,GAAG,mBAAmB;AACnC,MAAM,OAAO,GAAG,mBAAmB;AACnC,MAAM,sBAAsB,GAAG,GAAG;AAElC,MAAM,QAAQ,GAAG,YAAY,CAAC;AAC5B,IAAA,QAAQ,EAAE,IAAI;AACd,IAAA,QAAQ,EAAE,aAAa;AACvB,IAAA,aAAa,EAAE,cAAc;AAC7B,IAAA,UAAU,EAAE,OAAO;AACnB,IAAA,SAAS,EAAE,uBAAuB;AAClC,IAAA,MAAM,EAAE,OAAO;AAChB,CAAA,CAAC;AAmBF,IAAI,KAAK,GAA0B,IAAI;AAEvC,SAAS,aAAa,CAAC,CAAS,EAAA;AAC9B,IAAA,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;AAAE,QAAA,OAAO,CAAC;AACjC,IAAA,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACpC;AAEM,SAAU,kBAAkB,CAChC,SAAsB,EACtB,MAA4B,EAAA;AAE5B,IAAA,IAAI,QAAQ,CAAC,cAAc,CAAC,YAAY,CAAC;QAAE;AAE3C,IAAA,MAAM,OAAO,GACX,OAAO,MAAM,EAAE,eAAe,KAAK;UAC/B,MAAM,CAAC;AACT,UAAE,OAAO,MAAM,EAAE,eAAe,KAAK;AACnC,cAAE,CAAA,CAAA,EAAI,MAAM,CAAC,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;cACxD,SAAS;IAEjB,MAAM,UAAU,GACd,MAAM,EAAE,kBAAkB,IAAI,CAAA,wBAAA,EAA2B,OAAO,CAAA,kBAAA,CAAoB;AAEtF,IAAA,MAAM,UAAU,GAAG,MAAM,EAAE,gBAAgB,IAAI,EAAE;IAEjD,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC;AAC7C,IAAA,OAAO,CAAC,EAAE,GAAG,YAAY;AACzB,IAAA,OAAO,CAAC,SAAS,GAAG,UAAU,IAAI;;QAE5B,QAAQ;;GAEb;IAED,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC;IAC/C,OAAO,CAAC,WAAW,GAAG;OACjB,YAAY,CAAA;;;;oBAIC,UAAU,CAAA;;;;;;;;;OASvB,YAAY,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDhB;AAED,IAAA,SAAS,CAAC,KAAK,CAAC,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,QAAQ,IAAI,UAAU;AACjE,IAAA,SAAS,CAAC,WAAW,CAAC,OAAO,CAAC;AAC9B,IAAA,SAAS,CAAC,WAAW,CAAC,OAAO,CAAC;IAE9B,MAAM,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA,CAAA,EAAI,OAAO,CAAA,CAAE,CAA0B;IAC5E,MAAM,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA,CAAA,EAAI,OAAO,CAAA,CAAE,CAA0B;AAC5E,IAAA,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE;;;AAGtB,QAAA,KAAK,GAAG;YACN,SAAS;YACT,OAAO;YACP,OAAO;AACP,YAAA,MAAM,EAAE,IAAiC;AACzC,YAAA,MAAM,EAAE,IAAiC;AACzC,YAAA,cAAc,EAAE,KAAK;AACrB,YAAA,UAAU,EAAE,MAAM,EAAE,UAAU,KAAK,KAAK;AACxC,YAAA,cAAc,EAAE,MAAM,EAAE,cAAc,IAAI,cAAc;AACxD,YAAA,MAAM,EAAE,KAAK;AACb,YAAA,QAAQ,EAAE,MAAM;AAChB,YAAA,UAAU,EAAE,IAAI;AAChB,YAAA,UAAU,EAAE,IAAI;AAChB,YAAA,UAAU,EAAE,IAAI;AAChB,YAAA,OAAO,EAAE,KAAK;SACf;QACD;IACF;AAEA,IAAA,KAAK,GAAG;QACN,SAAS;QACT,OAAO;QACP,OAAO;QACP,MAAM;QACN,MAAM;AACN,QAAA,cAAc,EAAE,MAAM,EAAE,cAAc,KAAK,IAAI;AAC/C,QAAA,UAAU,EAAE,MAAM,EAAE,UAAU,KAAK,KAAK;AACxC,QAAA,cAAc,EAAE,MAAM,EAAE,cAAc,IAAI,cAAc;AACxD,QAAA,MAAM,EAAE,KAAK;AACb,QAAA,QAAQ,EAAE,MAAM;AAChB,QAAA,UAAU,EAAE,IAAI;AAChB,QAAA,UAAU,EAAE,IAAI;AAChB,QAAA,UAAU,EAAE,IAAI;AAChB,QAAA,OAAO,EAAE,KAAK;KACf;AACH;AAEM,SAAU,uBAAuB,CAAC,QAAgB,EAAA;AACtD,IAAA,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO;QAAE;IAC7B,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,KAAK,UAAU;QAAE;IACnE,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE;AAEnB,IAAA,MAAM,CAAC,GAAG,aAAa,CAAC,QAAQ,CAAC;AAEjC,IAAA,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE;QACjB,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC;AACpC,QAAA,KAAK,CAAC,MAAM,GAAG,IAAI;IACrB;AAEA,IAAA,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,GAAG,oBAAoB,CAAC,CAAC;IAEpE,IAAI,KAAK,CAAC,cAAc,IAAI,KAAK,CAAC,MAAM,EAAE;AACxC,QAAA,KAAK,CAAC,MAAM,CAAC,WAAW,GAAG,CAAA,EAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG;IACtD;AACF;SAEgB,mBAAmB,GAAA;IACjC,IAAI,CAAC,KAAK,EAAE;AACV,QAAA,MAAM,IAAI,KAAK,CACb,+DAA+D,CAChE;IACH;IACA,IAAI,KAAK,CAAC,OAAO;AAAE,QAAA,OAAO,OAAO,CAAC,OAAO,EAAE;IAC3C,IAAI,CAAC,KAAK,CAAC,UAAU;AAAE,QAAA,OAAO,OAAO,CAAC,OAAO,EAAE;IAC/C,IAAI,KAAK,CAAC,UAAU;QAAE,OAAO,KAAK,CAAC,UAAU;AAE7C,IAAA,IAAI,KAAK,CAAC,MAAM,EAAE;QAChB,KAAK,CAAC,MAAM,CAAC,WAAW,GAAG,KAAK,CAAC,cAAc;QAC/C,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,cAAc,CAAC;IAC5C;IACA,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,SAAS;AAEtC,IAAA,KAAK,CAAC,QAAQ,GAAG,SAAS;IAC1B,KAAK,CAAC,UAAU,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,KAAI;AAC/C,QAAA,KAAM,CAAC,UAAU,GAAG,OAAO;AAC3B,QAAA,MAAM,OAAO,GAAG,CAAC,EAAS,KAAI;AAC5B,YAAA,IAAI,CAAC,KAAK;gBAAE;YACZ,KAAK,CAAC,OAAO,CAAC,mBAAmB,CAAC,aAAa,EAAE,OAAO,CAAC;AACzD,YAAA,KAAK,CAAC,UAAU,GAAG,IAAI;AACvB,YAAA,KAAK,CAAC,QAAQ,GAAG,UAAU;AAC3B,YAAA,KAAK,CAAC,UAAU,GAAG,IAAI;AACvB,YAAA,OAAO,EAAE;AACX,QAAA,CAAC;AACD,QAAA,KAAM,CAAC,UAAU,GAAG,OAAO;QAC3B,KAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,aAAa,EAAE,OAAO,CAAC;AACzD,IAAA,CAAC,CAAC;IAEF,OAAO,KAAK,CAAC,UAAU;AACzB;AAEM,SAAU,kBAAkB,CAAC,UAAuB,EAAA;AACxD,IAAA,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO;AAAE,QAAA,OAAO,OAAO,CAAC,OAAO,EAAE;;AAGrD,IAAA,IAAI,KAAK,CAAC,UAAU,EAAE;QACpB,KAAK,CAAC,OAAO,CAAC,mBAAmB,CAAC,aAAa,EAAE,KAAK,CAAC,UAAU,CAAC;AAClE,QAAA,KAAK,CAAC,UAAU,GAAG,IAAI;IACzB;IACA,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,UAAU,EAAE;AACpD,QAAA,KAAK,CAAC,QAAQ,GAAG,UAAU;QAC3B,KAAK,CAAC,UAAU,EAAE;AAClB,QAAA,KAAK,CAAC,UAAU,GAAG,IAAI;IACzB;AAEA,IAAA,KAAK,CAAC,OAAO,GAAG,IAAI;AACpB,IAAA,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,KAAK;AAClC,IAAA,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,qBAAqB,CAAC;AAE5C,IAAA,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,KAAI;QACnC,IAAI,OAAO,GAAG,KAAK;QACnB,MAAM,MAAM,GAAG,MAAK;AAClB,YAAA,IAAI,OAAO;gBAAE;YACb,OAAO,GAAG,IAAI;YACd,OAAO,CAAC,MAAM,EAAE;YAChB,OAAO,CAAC,MAAM,EAAE;YAChB,KAAK,GAAG,IAAI;AACZ,YAAA,OAAO,EAAE;AACX,QAAA,CAAC;AAED,QAAA,OAAO,CAAC,gBAAgB,CAAC,eAAe,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACjE,QAAA,UAAU,CAAC,MAAM,EAAE,sBAAsB,CAAC;AAC5C,IAAA,CAAC,CAAC;AACJ;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@energy8platform/platform-core",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Energy8 platform core: Lua engine, DevBridge, RTP simulation, and SDK session orchestration. Renderer-agnostic — pair with any game framework (Pixi, Phaser, Three.js, custom).",
   "type": "module",
   "main": "./dist/index.cjs.js",
@@ -77,6 +77,7 @@
     "eslint": "^9.0.0",
     "fengari": "^0.1.5",
     "fengari-web": "^0.1.4",
+    "jsdom": "^25.0.1",
     "rollup": "^4.24.0",
     "rollup-plugin-dts": "^6.1.0",
     "tslib": "^2.8.0",

package/src/index.ts

@@ -43,6 +43,8 @@ export type { DevBridgeConfig } from './dev-bridge';
 // brand consistent across games on the platform.
 export {
   createCSSPreloader,
+  setCSSPreloaderProgress,
+  waitCSSPreloaderTap,
   removeCSSPreloader,
   buildLogoSVG,
   LOADER_BAR_MAX_WIDTH,

package/src/loading/CSSPreloader.ts

@@ -1,25 +1,44 @@
 import type { LoadingScreenConfig } from '../types';
-import { buildLogoSVG } from './logo';
+import { buildLogoSVG, LOADER_BAR_MAX_WIDTH } from './logo';
 
 const PRELOADER_ID = '__ge-css-preloader__';
+const RECT_ID = 'ge-pl-loader-rect';
+const TEXT_ID = 'ge-pl-loader-text';
+const REMOVE_FADE_TIMEOUT_MS = 600;
 
-/**
- * Inline SVG logo with animated loader bar.
- * The `#loader` path acts as the progress fill — animated via clipPath.
- */
 const LOGO_SVG = buildLogoSVG({
   idPrefix: 'pl',
   svgClass: 'ge-logo-svg',
   clipRectClass: 'ge-clip-rect',
+  clipRectId: RECT_ID,
   textClass: 'ge-preloader-svg-text',
+  textId: TEXT_ID,
 });
 
-/**
- * Creates a lightweight CSS-only preloader that appears instantly,
- * BEFORE PixiJS/WebGL is initialized.
- *
- * Displays the Energy8 logo SVG with an animated loader bar.
- */
+interface PreloaderState {
+  container: HTMLElement;
+  overlay: HTMLDivElement;
+  styleEl: HTMLStyleElement;
+  rectEl: SVGRectElement;
+  textEl: SVGTextElement;
+  showPercentage: boolean;
+  tapToStart: boolean;
+  tapToStartText: string;
+  driven: boolean;
+  tapState: 'idle' | 'waiting' | 'resolved';
+  tapPromise: Promise<void> | null;
+  tapResolve: (() => void) | null;
+  tapHandler: ((e: Event) => void) | null;
+  removed: boolean;
+}
+
+let state: PreloaderState | null = null;
+
+function clampProgress(p: number): number {
+  if (!Number.isFinite(p)) return 0;
+  return Math.max(0, Math.min(1, p));
+}
+
 export function createCSSPreloader(
   container: HTMLElement,
   config?: LoadingScreenConfig,
@@ -33,20 +52,21 @@ export function createCSSPreloader(
         ? `#${config.backgroundColor.toString(16).padStart(6, '0')}`
         : '#0a0a1a';
 
-  const bgGradient = config?.backgroundGradient ?? `linear-gradient(135deg, ${bgColor} 0%, #1a1a3e 100%)`;
+  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 || `
+  const overlay = document.createElement('div');
+  overlay.id = PRELOADER_ID;
+  overlay.innerHTML = customHTML || `
     <div class="ge-preloader-content">
       ${LOGO_SVG}
     </div>
   `;
 
-  const style = document.createElement('style');
-  style.textContent = `
+  const styleEl = document.createElement('style');
+  styleEl.textContent = `
     #${PRELOADER_ID} {
       position: absolute;
       top: 0; left: 0;
@@ -99,31 +119,153 @@ export function createCSSPreloader(
       0%, 100% { opacity: 0.4; }
       50% { opacity: 1; }
     }
+
+    /* Stop shimmer once JS-driven progress takes over. */
+    .ge-clip-rect.driven {
+      animation: none;
+    }
+
+    /* Tap-to-start CTA pulse. Compound selector outweighs the ambient
+       .ge-preloader-svg-text rule, swapping the animation cleanly. */
+    .ge-preloader-svg-text.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; }
+    }
   `;
 
   container.style.position = container.style.position || 'relative';
-  container.appendChild(style);
-  container.appendChild(el);
+  container.appendChild(styleEl);
+  container.appendChild(overlay);
+
+  const rectEl = overlay.querySelector(`#${RECT_ID}`) as SVGRectElement | null;
+  const textEl = overlay.querySelector(`#${TEXT_ID}`) as SVGTextElement | null;
+  if (!rectEl || !textEl) {
+    // Custom HTML mode — no logo SVG, lifecycle API becomes mostly inert.
+    // We still record state so removeCSSPreloader works.
+    state = {
+      container,
+      overlay,
+      styleEl,
+      rectEl: null as unknown as SVGRectElement,
+      textEl: null as unknown as SVGTextElement,
+      showPercentage: false,
+      tapToStart: config?.tapToStart !== false,
+      tapToStartText: config?.tapToStartText ?? 'TAP TO START',
+      driven: false,
+      tapState: 'idle',
+      tapPromise: null,
+      tapResolve: null,
+      tapHandler: null,
+      removed: false,
+    };
+    return;
+  }
+
+  state = {
+    container,
+    overlay,
+    styleEl,
+    rectEl,
+    textEl,
+    showPercentage: config?.showPercentage === true,
+    tapToStart: config?.tapToStart !== false,
+    tapToStartText: config?.tapToStartText ?? 'TAP TO START',
+    driven: false,
+    tapState: 'idle',
+    tapPromise: null,
+    tapResolve: null,
+    tapHandler: null,
+    removed: false,
+  };
 }
 
-/**
- * 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();
-      }
-    }
+export function setCSSPreloaderProgress(progress: number): void {
+  if (!state || state.removed) return;
+  if (state.tapState === 'waiting' || state.tapState === 'resolved') return;
+  if (!state.rectEl) return;
+
+  const p = clampProgress(progress);
+
+  if (!state.driven) {
+    state.rectEl.classList.add('driven');
+    state.driven = true;
+  }
+
+  state.rectEl.setAttribute('width', String(p * LOADER_BAR_MAX_WIDTH));
+
+  if (state.showPercentage && state.textEl) {
+    state.textEl.textContent = `${Math.round(p * 100)}%`;
+  }
+}
+
+export function waitCSSPreloaderTap(): Promise<void> {
+  if (!state) {
+    throw new Error(
+      'CSS preloader not initialized — call createCSSPreloader first',
+    );
+  }
+  if (state.removed) return Promise.resolve();
+  if (!state.tapToStart) return Promise.resolve();
+  if (state.tapPromise) return state.tapPromise;
+
+  if (state.textEl) {
+    state.textEl.textContent = state.tapToStartText;
+    state.textEl.classList.add('ge-svg-pulse');
+  }
+  state.overlay.style.cursor = 'pointer';
+
+  state.tapState = 'waiting';
+  state.tapPromise = new Promise<void>((resolve) => {
+    state!.tapResolve = resolve;
+    const handler = (_e: Event) => {
+      if (!state) return;
+      state.overlay.removeEventListener('pointerdown', handler);
+      state.tapHandler = null;
+      state.tapState = 'resolved';
+      state.tapResolve = null;
+      resolve();
+    };
+    state!.tapHandler = handler;
+    state!.overlay.addEventListener('pointerdown', handler);
+  });
+
+  return state.tapPromise;
+}
+
+export function removeCSSPreloader(_container: HTMLElement): Promise<void> {
+  if (!state || state.removed) return Promise.resolve();
+
+  // Detach the pending pointer listener (if any) and resolve a pending tap.
+  if (state.tapHandler) {
+    state.overlay.removeEventListener('pointerdown', state.tapHandler);
+    state.tapHandler = null;
+  }
+  if (state.tapState === 'waiting' && state.tapResolve) {
+    state.tapState = 'resolved';
+    state.tapResolve();
+    state.tapResolve = null;
+  }
+
+  state.removed = true;
+  const { overlay, styleEl } = state;
+  overlay.classList.add('ge-preloader-hidden');
+
+  return new Promise<void>((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      overlay.remove();
+      styleEl.remove();
+      state = null;
+      resolve();
+    };
+
+    overlay.addEventListener('transitionend', finish, { once: true });
+    setTimeout(finish, REMOVE_FADE_TIMEOUT_MS);
   });
 }

package/src/loading/index.ts

@@ -1,3 +1,8 @@
-export { createCSSPreloader, removeCSSPreloader } from './CSSPreloader';
+export {
+  createCSSPreloader,
+  setCSSPreloaderProgress,
+  waitCSSPreloaderTap,
+  removeCSSPreloader,
+} from './CSSPreloader';
 export { buildLogoSVG, LOADER_BAR_MAX_WIDTH } from './logo';
 export type { LoadingScreenConfig, AssetManifest, AssetBundle, AssetEntry } from '../types';

package/src/types.ts

@@ -55,9 +55,15 @@ export interface LoadingScreenConfig {
   showPercentage?: boolean;
   /** Custom progress text formatter */
   progressTextFormatter?: (progress: number) => string;
-  /** Show "Tap to start" after loading (needed for mobile audio unlock) */
+  /**
+   * If true (default), `waitCSSPreloaderTap()` blocks until the user
+   * clicks the preloader. Set to `false` to make `waitCSSPreloaderTap()`
+   * resolve immediately (skip-flag for games that don't want a manual
+   * gate). Useful for mobile audio unlock — the click satisfies the
+   * browser's user-gesture requirement.
+   */
   tapToStart?: boolean;
-  /** "Tap to start" label text */
+  /** Label shown in the SVG text element while waiting for tap. Default: 'TAP TO START'. */
   tapToStartText?: string;
   /** Minimum display time in ms (so the user sees the brand, even if loading is fast) */
   minDisplayTime?: number;