@truelab/truelogic 4.3.3 → 4.4.0-2

package/dist/types/src/app/lib/hooks/useGameLoadAnalytics.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Game load telemetry (GTT-2800). Marks the load timeline on the tracker and reports it to analytics:
+ * a `gameLoad.phase:completed` event the moment each phase is over (CDN, init, preload, loading, game
+ * code), then one terminal event per load — `gameLoad:completed` when the game calls `setGameReady()`,
+ * `gameLoad:failed` on the failed screen, `gameLoad:abandoned` when the page is hidden before the
+ * main screen — and `gameLoad:finished` once the main screen is reached.
+ *
+ * Every payload carries `metrics` and the `environment` the tracker reads once on mount, so each
+ * event is self-contained. `init` marks are set in `truelogic.init()` itself: the hook mounts inside it.
+ */
+export declare const useGameLoadAnalytics: () => void;

package/dist/types/src/app/lib/hooks/useGameLoadAnalytics.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/src/shared/lib/classes/analyticsService.d.ts

@@ -1,5 +1,8 @@
-type TAnalyticsParameterValue = boolean | number | string;
-export type TAnalyticsCustomParams = Record<string, TAnalyticsParameterValue | undefined>;
+type TAnalyticsParameterValue = boolean | number | string | TAnalyticsCustomParams;
+/** Event parameters; nested objects are allowed — GTM reads them with dot paths (`metrics.init_ms`) */
+export type TAnalyticsCustomParams = {
+    [name: string]: TAnalyticsParameterValue | undefined;
+};
 export declare enum EAnalyticsEvents {
     modeReal = "mode_real",
     modeDemo = "mode_demo",
@@ -38,14 +41,24 @@ export declare enum EAnalyticsEvents {
     spinHold = "spin_hold",
     bonusPurchase = "bonus_purchase",
     bonusBetActivate = "bonus_bet_activate",
-    timeToBuyBonus = "time_to_buy_bonus"
+    timeToBuyBonus = "time_to_buy_bonus",
+    gameLoadCdn = "game_load_cdn",
+    gameLoadInit = "game_load_init",
+    gameLoadPreload = "game_load_preload",
+    gameLoadLoading = "game_load_loading",
+    gameLoadGameCode = "game_load_game_code",
+    gameLoadTime = "game_load_time",
+    gameLoadFailed = "game_load_failed",
+    gameLoadAbandoned = "game_load_abandoned",
+    gameLoadEnv = "game_load_env"
 }
 export declare enum EAnalyticsCategories {
     settings = "settings_changes",
     ui = "ui_interaction",
     gameplay = "gameplay_events",
     mode = "game_mode",
-    config = "session_config"
+    config = "session_config",
+    performance = "performance"
 }
 export type TEventOptions = {
     value?: number;

package/dist/types/src/shared/lib/classes/emitter.d.ts

@@ -5,6 +5,8 @@ export declare abstract class Emitter<TEvents extends Record<keyof TEvents, TVoi
     protected listenersOneTime: Map<keyof TEvents, TVoidFunc[]>;
     on<K extends keyof TEvents>(event: K, listener: TEvents[K]): this;
     once<K extends keyof TEvents>(event: K, listener: TEvents[K]): this;
+    /** Removes a listener added with `on` or `once`; unknown listeners are ignored */
+    off<K extends keyof TEvents>(event: K, listener: TEvents[K]): this;
     emit<K extends keyof TEvents>(event: K, ...args: Parameters<TEvents[K]>): void;
     abstract log(event: unknown, ...args: unknown[]): void;
 }

package/dist/types/src/shared/lib/classes/emitter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/src/shared/lib/classes/gameLoadTracker.d.ts

@@ -0,0 +1,67 @@
+import { TAnalyticsCustomParams } from './analyticsService';
+/**
+ * Points on the game load timeline, from the bundle evaluation to the main screen.
+ * `*:called` marks are the host game calling a public method, the rest are TrueLogic reaching a state.
+ */
+export type TGameLoadMark = 'init:called' | 'init:resolved' | 'session:started' | 'session:ended' | 'configure:called' | 'configure:succeed' | 'preload.images:ended' | 'preload.nonCritical:ended' | 'startLoading:called' | 'endLoading:called' | 'loading:ended' | 'ready:called' | 'welcome:shown' | 'main:shown';
+/** The furthest point a load reached — the `stage` of `game_load_failed` and `game_load_abandoned` */
+export type TGameLoadStage = 'script' | 'init' | 'configure' | 'loading' | 'loading_tail' | 'ready_wait' | 'welcome' | 'main';
+/** Load phases reported as separate events the moment they complete — one dashboard row each */
+export type TGameLoadPhase = 'cdn' | 'init' | 'preload' | 'loading' | 'game_code';
+export type TGameLoadError = {
+    name?: string;
+    message?: string;
+    code?: number;
+};
+export type TGameLoadMarkListener = (mark: TGameLoadMark) => void;
+/** Marks left by the inline preloader loader (`src/app/templates/preloader-loader.ts`) around the CDN fetch */
+export declare const GAME_LOAD_LOADER_MARK_START = "truelogic:loader:start";
+export declare const GAME_LOAD_LOADER_MARK_END = "truelogic:loader:end";
+/**
+ * Collects the game load timeline (GTT-2800). All times are `performance.now()` values, so they
+ * count from the page open (`performance.timeOrigin`), the same origin as the loader marks.
+ *
+ * Every payload groups the measured values under `metrics` and carries the same `environment`
+ * (what the browser reports about the network, the device and the embedding), read once per load.
+ * Phases (`completePhase`) go out as soon as they are over. Every load also ends in exactly one
+ * terminal payload: `complete()` when the game calls `setGameReady()`, `fail()` on the failed screen
+ * or `abandon()` when the page is hidden earlier. The welcome screen comes after `complete()`, so a
+ * load can still be abandoned there; `finish()` closes it on the main screen.
+ */
+export declare class GameLoadTracker {
+    private marks;
+    private listeners;
+    private sentPhases;
+    private environment;
+    private scriptStartMs;
+    private progressTicks;
+    private tabHidden;
+    private isCompleted;
+    private isClosed;
+    constructor();
+    /** Records the first occurrence of a mark and notifies the subscribers; later calls are ignored */
+    mark(name: TGameLoadMark): void;
+    has(name: TGameLoadMark): boolean;
+    /** Called on every new mark; returns the unsubscribe function */
+    subscribe(listener: TGameLoadMarkListener): () => void;
+    /** One `setLoadingProgress()` call of the game */
+    tickProgress(): void;
+    /** Reads the browser environment once per load; call it early so no event waits for the probes */
+    collectEnvironment(): TAnalyticsCustomParams;
+    getStage(): TGameLoadStage;
+    /** Every measured value known so far; a duration is left out while one of its marks is missing */
+    getMetrics(): TAnalyticsCustomParams;
+    /** A phase is over: its `game_load_<phase>` payload, once per load and never after the load is closed */
+    completePhase(phase: TGameLoadPhase): TAnalyticsCustomParams | null;
+    /** The game called `setGameReady()`: the `game_load_time` payload, once per load */
+    complete(): TAnalyticsCustomParams | null;
+    /** The failed screen before the game was ready: the `game_load_failed` payload, once per load */
+    fail(error?: TGameLoadError | null): TAnalyticsCustomParams | null;
+    /** The page is hidden before the main screen: the `game_load_abandoned` payload, once per load */
+    abandon(): TAnalyticsCustomParams | null;
+    /** The main screen is shown: closes the load and returns the welcome screen dwell, once per load */
+    finish(): TAnalyticsCustomParams | null;
+    /** Test helper: a fresh load on the same instance (subscribers stay) */
+    reset(): void;
+    private diff;
+}

package/dist/types/src/shared/lib/classes/gameLoadTracker.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/src/shared/lib/functions/getLoadEnvironment.d.ts

@@ -0,0 +1,12 @@
+export type TLoadEnvironment = Record<string, boolean | number | string | undefined>;
+/**
+ * What the browser reports about the conditions of this game load (GTT-2800): network, HTML and bundle
+ * delivery, device capabilities, embedding. Read once per load by `GameLoadTracker` and attached as
+ * the `environment` object to every `game_load_*` event.
+ *
+ * Every field is optional: a browser without the API, or an API that cannot tell, leaves the field
+ * out — nothing is reported as `0`, `null` or a guess. See the field docs on the helpers above for
+ * units, ranges and browser support; the dashboard-side description lives in
+ * `docs/docs/development/analytics.md` → "environment fields".
+ */
+export declare const getLoadEnvironment: () => TLoadEnvironment;

package/dist/types/src/shared/lib/functions/getLoadEnvironment.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/src/shared/lib/functions/index.d.ts

@@ -7,6 +7,7 @@ export { formatCount } from './formatCount';
 export { formatDate } from './formatDate';
 export { formatTime } from './formatTime';
 export { getBase64Image } from './getBase64Image';
+export { getLoadEnvironment } from './getLoadEnvironment';
 export { getSafeLocale } from './getSafeLocale';
 export { getUrlParam } from './getUrlParam';
 export { isE2E } from './isE2E';

package/dist/types/src/shared/lib/hooks/useClickOutside.d.ts

@@ -12,6 +12,9 @@ import { ForwardedRef, RefObject } from 'react';
  * is clickable (has a click handler of its own, or `cursor: pointer`); a document-level listener
  * alone does not make it so. A `click` caller keeps its outside area clickable — the modal scrims
  * carry `cursor-pointer` for exactly this.
+ *
+ * A `click` ends a press, and only a press begun after the enabling counts: a spin held while a
+ * modal opens (the round error arrives, there are no funds) must not close it with the release.
  */
 export type TClickOutsideEvent = 'pointerdown' | 'click';
 export declare const useClickOutside: (refs: (RefObject<HTMLElement> | ForwardedRef<HTMLElement>)[], onClick: (event: MouseEvent | TouchEvent) => void, isEnabled?: boolean, eventName?: TClickOutsideEvent) => void;

package/dist/types/src/shared/lib/hooks/useHold.d.ts

@@ -20,7 +20,8 @@ type THoldOptions = {
  * One held state for a control pressed with a pointer (attach `onPointerDown` to it) or with
  * hotkeys. The press fires `onPress`, a hold of `holdDelay` fires `onHold`, the release — pointerup
  * or pointercancel anywhere in the document, keyup, window blur — fires `onRelease`. The latest
- * press owns the hold: a second finger or key takes over instead of piling up. `isHeld` paints the
+ * press owns the hold: a second finger or key takes over instead of piling up. A key pressed before
+ * the hook got enabled (mounted) is not a press of this control. `isHeld` paints the
  * control; it comes from the events themselves, not from `:active`, which Blink sets for a touch
  * too late for a quick tap to show.
  */

package/dist/types/src/shared/lib/singletones/analyticsEmitter.d.ts

@@ -1,5 +1,6 @@
 import { TSessionMode } from '../../../shared/api/config';
 import { TAnalyticsCustomParams } from '../../../shared/lib/classes/analyticsService';
+import { TGameLoadPhase } from '../../../shared/lib/classes/gameLoadTracker';
 import { Emitter } from '../classes';
 import { TOrientation } from '../types/viewPort';
 type TEventOptions = {
@@ -99,6 +100,11 @@ export type TAnalyticsEvents = {
     ['walletConvertSuccess:continuePlayingClicked']: (params: TAnalyticsCustomParams) => void;
     ['bonus:purchase']: (options: TEventOptions) => void;
     ['bonus:betActivate']: (options: TEventOptions) => void;
+    ['gameLoad.phase:completed']: (phase: TGameLoadPhase, params: TAnalyticsCustomParams) => void;
+    ['gameLoad:completed']: (params: TAnalyticsCustomParams) => void;
+    ['gameLoad:failed']: (params: TAnalyticsCustomParams) => void;
+    ['gameLoad:abandoned']: (params: TAnalyticsCustomParams) => void;
+    ['gameLoad:finished']: (params: TAnalyticsCustomParams) => void;
 };
 export declare class AnalyticsEmitter extends Emitter<TAnalyticsEvents> {
     log(event: string, ...args: unknown[]): void;

package/dist/types/src/shared/lib/singletones/gameLoadTracker.d.ts

@@ -0,0 +1,2 @@
+import { GameLoadTracker } from '../classes/gameLoadTracker';
+export declare const gameLoadTracker: GameLoadTracker;

package/dist/types/src/shared/lib/singletones/index.d.ts

@@ -4,6 +4,7 @@ export { api } from './api';
 export { cashService } from './cashService';
 export type { TStakeResponse } from './gameEmitter';
 export { gameEmitter } from './gameEmitter';
+export { gameLoadTracker } from './gameLoadTracker';
 export { logger } from './logger';
 export { moduleEmitter } from './moduleEmitter';
 export { utilsService } from './utilsService';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@truelab/truelogic",
-    "version": "4.3.3",
+    "version": "4.4.0-2",
     "description": "",
     "main": "./dist/truelogic.min.js",
     "types": "./dist/types/src/index.d.ts",