@energy8platform/platform-core 0.17.0 → 0.18.0

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/simulation/NativeSimulationRunner.ts

@@ -10,6 +10,19 @@ import type { GameDefinition, SimulationResult } from '../lua/types';
 
 // ─── Types ──────────────────────────────────────────────
 
+export type NativeRNGKind = 'provably-fair' | 'fast';
+
+/**
+ * Replay mode parameters. Forces single-worker deterministic execution over a
+ * specific (server_seed, client_seed, nonce-start) triple — used to reproduce a
+ * production round captured in `provably_fair_rounds`.
+ */
+export interface NativeReplayParams {
+  serverSeed: string;
+  clientSeed: string;
+  nonceStart: number;
+}
+
 export interface NativeSimulationConfig {
   /** Path to native simulation binary */
   binaryPath: string;
@@ -25,6 +38,20 @@ export interface NativeSimulationConfig {
   action?: string;
   /** Action params (buy_bonus, ante_bet, etc.) */
   params?: Record<string, unknown>;
+  /**
+   * Hex-encoded master seed for reproducible runs. The binary derives per-worker
+   * server_seeds via sha256(seed || ":" || worker_idx). When omitted, the binary
+   * generates one and returns it on the result so the run can be reproduced via
+   * `seed: result.masterSeed`. Ignored when `rng === 'fast'`.
+   */
+  seed?: string;
+  /**
+   * RNG backend: `'provably-fair'` (default, matches production) or `'fast'`
+   * (math/rand PCG — local iteration only, do NOT publish those RTP numbers).
+   */
+  rng?: NativeRNGKind;
+  /** Replay mode: requires `rng: 'provably-fair'` (or default). */
+  replay?: NativeReplayParams;
   /** Progress callback */
   onProgress?: (completed: number, total: number) => void;
 }
@@ -55,6 +82,18 @@ export interface NativeSimulationResult extends SimulationResult {
   perStage?: Record<string, StageStats>;
   /** Win distribution histogram */
   winDistribution?: DistributionBucket[];
+  /** RNG backend that produced these numbers. */
+  rngKind?: NativeRNGKind;
+  /**
+   * Hex master seed that drove worker-seed derivation. Always set for
+   * `provably-fair` runs (supplied or auto-generated). Pass back via `seed`
+   * to reproduce the run bit-for-bit.
+   */
+  masterSeed?: string;
+  /** Per-worker server_seed sequence (lets support reproduce any individual spin). */
+  workerSeeds?: string[];
+  /** Echo of replay params when the run was in replay mode. */
+  replay?: NativeReplayParams;
 }
 
 // ─── Go JSON output shape (snake_case) ──────────────────
@@ -88,6 +127,14 @@ interface GoSimulationOutput {
     count: number;
     pct: number;
   }>;
+  rng_kind?: NativeRNGKind;
+  master_seed?: string;
+  worker_seeds?: string[];
+  replay?: {
+    server_seed: string;
+    client_seed: string;
+    nonce_start: number;
+  };
 }
 
 // ─── Runner ─────────────────────────────────────────────
@@ -100,7 +147,12 @@ export class NativeSimulationRunner {
   }
 
   async run(): Promise<NativeSimulationResult> {
-    const { binaryPath, script, gameDefinition, iterations, bet, action, params } = this.config;
+    const { binaryPath, script, gameDefinition, iterations, bet, action, params, seed, rng, replay } = this.config;
+
+    if (replay && rng && rng !== 'provably-fair') {
+      throw new Error(`Replay mode requires rng="provably-fair" (got rng="${rng}")`);
+    }
+
     const id = randomBytes(8).toString('hex');
     const tmpDir = tmpdir();
     const luaPath = join(tmpDir, `sim-${id}.lua`);
@@ -126,6 +178,19 @@ export class NativeSimulationRunner {
       if (params && Object.keys(params).length > 0) {
         args.push('-params', JSON.stringify(params));
       }
+      if (rng) {
+        args.push('-rng', rng);
+      }
+      if (seed) {
+        args.push('-seed', seed);
+      }
+      if (replay) {
+        args.push(
+          '-replay-server-seed', replay.serverSeed,
+          '-replay-client-seed', replay.clientSeed,
+          '-replay-nonce-start', String(replay.nonceStart),
+        );
+      }
 
       // Execute binary
       const output = await this.exec(binaryPath, args);
@@ -211,6 +276,16 @@ function mapGoResult(json: GoSimulationOutput): NativeSimulationResult {
     workersUsed: json.workers_used,
     perStage,
     winDistribution: json.win_distribution,
+    rngKind: json.rng_kind,
+    masterSeed: json.master_seed,
+    workerSeeds: json.worker_seeds,
+    replay: json.replay
+      ? {
+          serverSeed: json.replay.server_seed,
+          clientSeed: json.replay.client_seed,
+          nonceStart: json.replay.nonce_start,
+        }
+      : undefined,
     _raw: {
       totalWagered: json.total_bet,
       totalWon: json.total_win,
@@ -311,6 +386,17 @@ export function formatNativeResult(result: NativeSimulationResult): string {
   if (result.workersUsed) {
     lines.push(`Workers: ${result.workersUsed}`);
   }
+  if (result.rngKind) {
+    lines.push(`RNG: ${result.rngKind}`);
+  }
+  if (result.masterSeed) {
+    lines.push(`Master seed: ${result.masterSeed}  (pass --seed=${result.masterSeed} to reproduce)`);
+  }
+  if (result.replay) {
+    lines.push(
+      `Replay: server_seed=${result.replay.serverSeed} client_seed=${result.replay.clientSeed} nonce_start=${result.replay.nonceStart}`,
+    );
+  }
 
   lines.push(
     '',

package/src/simulation/index.ts

@@ -14,6 +14,8 @@ export {
 export type {
   NativeSimulationConfig,
   NativeSimulationResult,
+  NativeRNGKind,
+  NativeReplayParams,
   StageStats,
   DistributionBucket,
 } from './NativeSimulationRunner';

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;