@truelab/truelogic 4.3.0-9 → 4.3.2-0

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/features/play/ui/PanelPlay/PanelPlay.d.ts

@@ -5,6 +5,12 @@ type TPanelPlayProps = {
     ref: RefObject<HTMLButtonElement>;
     /** Rendered as `data-state` so e2e tests can tell play from stop/skip without guessing by `disabled` */
     state?: TPanelPlayState;
+    /**
+     * The spin is held — a pointer on the button or a hotkey down; the panel owns the hold (useHold).
+     * Not `:active`: Blink sets that for a touch too late for a quick tap to show, and On_tap must
+     * stay until the player lets go even once the round it started has disabled the button (GTT-2754)
+     */
+    isPressed?: boolean;
 } & ButtonHTMLAttributes<HTMLButtonElement>;
-export declare const PanelPlay: ({ onClick, className, disabled, state, ref, ...props }: TPanelPlayProps) => import("react/jsx-runtime").JSX.Element;
+export declare const PanelPlay: ({ onPointerDown, className, disabled, state, isPressed, ref, ...props }: TPanelPlayProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/types/src/features/play/ui/PanelPlay/PanelPlay.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/index.d.ts

@@ -4,7 +4,8 @@ export { useElementInViewPort } from './useElementInViewPort';
 export { useElementsBottomCssVar } from './useElementsBottomCssVar';
 export { useEnv } from './useEnv';
 export { useGameTime } from './useGameTime';
-export { useHoldDown } from './useHoldDown';
+export type { THoldSource } from './useHold';
+export { useHold } from './useHold';
 export { useOffline } from './useOffline';
 export { useOrientationChange } from './useOrientationChange';
 export { usePageVisibility } from './usePageVisibility';

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

@@ -0,0 +1,26 @@
+import { PointerEvent as ReactPointerEvent } from 'react';
+export type THoldSource = 'pointer' | 'key';
+type THoldOptions = {
+    /** The control is held while one of these keys is down (`KeyboardEvent.code`) */
+    keys?: readonly string[];
+    /** How long the control must stay held for `onHold` to fire */
+    holdDelay: number;
+    onPress?: (source: THoldSource) => void;
+    onHold?: (source: THoldSource) => void;
+    onRelease?: (source: THoldSource) => void;
+    /** Turning it off releases a hold in progress: a lock (a modal) must not leave the action stuck on */
+    isEnabled?: boolean;
+};
+/**
+ * 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
+ * control; it comes from the events themselves, not from `:active`, which Blink sets for a touch
+ * too late for a quick tap to show.
+ */
+export declare const useHold: ({ keys, holdDelay, onPress, onHold, onRelease, isEnabled }: THoldOptions) => {
+    isHeld: boolean;
+    onPointerDown: (event: ReactPointerEvent<HTMLElement>) => void;
+};
+export {};

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

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

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/dist/types/src/shared/modules/menuInnerPage.d.ts

@@ -8,6 +8,13 @@ type TMenuInnerPageContext = {
     page: TMenuInnerPage | null;
     openPage: (page: TMenuInnerPage) => void;
     closePage: () => void;
+    /**
+     * A box over the header row for the toasts of a page, drawn there through a portal. Anything
+     * positioned inside the tab content, `fixed` included, travels with it: the tab scroll moves
+     * the content with a transform.
+     */
+    headerOverlay: HTMLElement | null;
+    setHeaderOverlay: (element: HTMLElement | null) => void;
 };
 type TProps = {
     children: ReactNode;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@truelab/truelogic",
-    "version": "4.3.0-9",
+    "version": "4.3.2-0",
     "description": "",
     "main": "./dist/truelogic.min.js",
     "types": "./dist/types/src/index.d.ts",
@@ -58,7 +58,11 @@
         "test:e2e:ui": "playwright test --project=sandbox --ui",
         "test:e2e:ui:game": "playwright test --project=game --ui",
         "test:e2e:report": "playwright show-report",
-        "test:e2e:typecheck": "tsc -p tests/e2e/tsconfig.json"
+        "test:e2e:typecheck": "tsc -p tests/e2e/tsconfig.json",
+        "email:install": "npm install --prefix ./email-letters",
+        "email:dev": "npm run dev --prefix ./email-letters",
+        "email:export": "npm run export --prefix ./email-letters",
+        "email:send-test": "npm run send-test --prefix ./email-letters --"
     },
     "browserslist": [
         "defaults and supports es6-module"

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

@@ -1 +0,0 @@
-export declare const useHoldDown: (button: "Space" | "Enter", onKeyDown: () => void, onKeyUp: () => void, keyDownDelay?: number, isEnabled?: boolean) => void;