@liorian/sdk 0.28.0-alpha.56010ca

package/src/infrastructure/utilities/access-label.util.ts

@@ -0,0 +1,158 @@
+import {DomainsEnum} from "../../domain/enums/domains.enum";
+
+/** Libellés français des rôles par défaut (clé API → libellé). */
+const ROLE_LABELS: Record<string, string> = {
+    Root: "Système",
+    SuperAdmin: "Super Administrateur",
+    Admin: "Administrateur",
+    Manager: "Gestionnaire",
+    Editor: "Éditeur",
+    Moderator: "Modérateur",
+    Analyst: "Analyste",
+    Commercial: "Commercial",
+    Operator: "Opérateur",
+    Contributor: "Contributeur",
+    Caissier: "Caissier",
+    User: "Utilisateur",
+    Guest: "Invité",
+    Viewer: "Lecteur",
+};
+
+/** Libellés français des domaines de permission (clé API → libellé). */
+const DOMAIN_LABELS: Record<string, string> = {
+    // Identity
+    [DomainsEnum.User]: "Utilisateur",
+    UserDevice: "Appareil utilisateur",
+    UserDocument: "Document utilisateur",
+    OrganizationDocumentType: "Type de document d'organisation",
+
+    // Organization
+    [DomainsEnum.Organization]: "Organisation",
+    [DomainsEnum.OrganizationMember]: "Membre d'organisation",
+    [DomainsEnum.ApiAccessKey]: "Clé API",
+
+    // Access Control
+    [DomainsEnum.Role]: "Rôle",
+
+    // Blogging
+    Post: "Publication",
+    PostCategory: "Catégorie de publication",
+    PostCollaborator: "Collaborateur de publication",
+
+    // CRM
+    Contact: "Contact",
+    Company: "Société",
+    Lead: "Prospect",
+    Deal: "Affaire",
+    Activity: "Activité",
+    SalesTeam: "Groupe de commerciaux",
+
+    // Projects
+    Project: "Projet",
+    Task: "Tâche",
+    TaskReminder: "Rappel de tâche",
+
+    // Messaging / Media
+    Media: "Médias",
+    Notification: "Notifications",
+    OTP: "Code OTP",
+    UserPreference: "Préférence utilisateur",
+    OrganizationPreference: "Préférence d'organisation",
+    UserActivity: "Activité utilisateur",
+
+    // Billing
+    PaymentMethod: "Méthode de paiement",
+    Order: "Commande",
+    Invoice: "Facture",
+
+    // Stock
+    [DomainsEnum.Stock]: "Stock",
+    [DomainsEnum.Product]: "Produit",
+    ProductCategory: "Catégorie de produit",
+    StockMovement: "Mouvement de stock",
+    Warehouse: "Entrepôt",
+
+    // Restaurant
+    RestaurantDish: "Plat restaurant",
+    RestaurantMenu: "Menu restaurant",
+
+    // Analytics
+    [DomainsEnum.Analytics]: "Analytiques",
+
+    // Accounting
+    [DomainsEnum.Accounting]: "Comptabilité",
+    AccountingSetting: "Paramètres comptables",
+    AccountingAccount: "Compte comptable",
+    AccountingJournal: "Journal comptable",
+    AccountingJournalEntry: "Écriture comptable",
+    AccountingLedger: "Grand livre",
+    AccountingTrialBalance: "Balance de vérification",
+    AccountingBankAccount: "Compte bancaire",
+    AccountingTax: "Taxe",
+    AccountingBudget: "Budget",
+    AccountingClosePeriod: "Clôture de période",
+    AccountingReport: "Rapport comptable",
+
+    // Customer
+    [DomainsEnum.Customer]: "Client",
+    CustomerModule: "Module client",
+
+    // POS
+    Pos: "Point de vente",
+    PosTable: "Table POS",
+    PosOrder: "Commande POS",
+    PosOrderItem: "Article de commande POS",
+    PosBundle: "Pack POS",
+    PosBundleItem: "Article de pack POS",
+
+    // E-commerce
+    Ecommerce: "E-commerce",
+    EcommerceProductAttribute: "Attribut produit e-commerce",
+    EcommerceProductVariant: "Variante produit e-commerce",
+    EcommerceProductImage: "Image produit e-commerce",
+    EcommerceProductReview: "Avis produit e-commerce",
+    EcommerceProductTag: "Étiquette produit e-commerce",
+    EcommerceCart: "Panier e-commerce",
+    EcommerceCoupon: "Coupon e-commerce",
+    EcommerceCarrier: "Transporteur e-commerce",
+    EcommerceShippingZone: "Zone de livraison e-commerce",
+    EcommerceShippingRate: "Tarif de livraison e-commerce",
+    EcommerceShipment: "Expédition e-commerce",
+    EcommerceOrder: "Commande e-commerce",
+    EcommerceWishlist: "Liste de souhaits e-commerce",
+    EcommerceStoreSettings: "Paramètres boutique e-commerce",
+
+    // Messenger
+    MessengerWorkspace: "Espace de messagerie",
+    MessengerChannel: "Canal de messagerie",
+    MessengerMessage: "Message",
+};
+
+/** Transforme une clé en lecture humaine (CamelCase → mots séparés). */
+function humanize(key: string): string {
+    const spaced = key
+        .replace(/^[a-z]/u, char => char.toUpperCase())
+        .replace(/([a-z0-9])([A-Z])/gu, "$1 $2")
+        .replace(/([A-Z])([A-Z][a-z])/gu, "$1 $2")
+        .trim();
+
+    return spaced || key;
+}
+
+/**
+ * Libellé français d'un rôle par défaut (Root, SuperAdmin, Admin…).
+ * Retourne un libellé lisible si la clé n'est pas dans le dictionnaire.
+ */
+export function getRoleLabel(name?: string | null): string {
+    if (!name) return "";
+    return ROLE_LABELS[name] ?? humanize(name);
+}
+
+/**
+ * Libellé français d'un domaine de permission (Organization, User…).
+ * Retourne un libellé lisible si la clé n'est pas dans le dictionnaire.
+ */
+export function getDomainLabel(domain?: string | null): string {
+    if (!domain) return "";
+    return DOMAIN_LABELS[domain] ?? humanize(domain);
+}

package/src/infrastructure/utilities/activities.util.tsx

@@ -0,0 +1,54 @@
+import {ActivityInterface} from "../../domain/entities/activities.interface";
+import {useModuleStore} from "../stores/module.store";
+import {retrieveModule} from "./modules";
+import {Fragment} from "react";
+import {capitalizeFirstLetter} from "./strings.util";
+import {ActivityDescriptorParser} from "../../presentation/components/activity-descriptor-parser";
+
+
+export function explainActivityAction(method: string): string {
+    switch (method.toUpperCase()) {
+        default:
+            return method;
+        case 'GET':
+            return 'Lecture';
+        case 'POST':
+            return 'Création';
+        case 'PUT':
+            return 'Modification';
+        case 'DELETE':
+            return 'Suppression';
+    }
+}
+
+export function explainActivityActionVerb(action?: string) {
+    switch (action?.toLowerCase()) {
+        case 'get':
+            return '*a lu*';
+        case 'post':
+            return '*a créé*';
+        case 'patch':
+        case 'put':
+            return '*a modifié*';
+        case 'delete':
+            return '*a supprimé*';
+        default:
+            return '*a effectué*';
+    }
+}
+
+export function ActivityDescriptor(activity: ActivityInterface) {
+    const module = retrieveModule(activity.module);
+    const defaultTemplate = `${
+        capitalizeFirstLetter(activity.user?.username)
+    } ${
+        explainActivityActionVerb(activity.action)
+    } ${module ? `dans le module ${module.name}` : 'dans un module'}`
+
+    return (
+        <Fragment>
+            <ActivityDescriptorParser template={activity.describe ?? defaultTemplate} context={activity}/>
+        </Fragment>
+    );
+}
+

package/src/infrastructure/utilities/activity-lock.service.ts

@@ -0,0 +1,263 @@
+"use client"
+
+import {AppConfig} from "../../domain/config/app.config";
+import {UserPreferencesApiService} from "../../application/service/user-preferences-api.service";
+import {ActivityTrackerService} from "./activity-tracker.service";
+import {ACTIVITY_LOCK_EVENT, ACTIVITY_UNLOCK_EVENT, FormSnapshotService} from "./form-snapshot.service";
+import {activityLockStore} from "../stores/activity-lock.store";
+
+/** Libellé de préférence utilisateur (persistée) contrôlant le délai d'inactivité. */
+export const ACTIVITY_LOCK_PREFERENCE_LABEL = "ui_activity_tracker_timeout";
+
+/** Clé localStorage du verrou : persiste l'état verrouillé même après un rafraîchissement. */
+const ACTIVITY_LOCK_STORAGE_KEY = "@liorian-activity-lock";
+
+/** Délai d'inactivité par défaut (repli) : 3 minutes. */
+const DEFAULT_TIMEOUT = 3 * 60 * 1000;
+
+export interface ActivityLockState {
+    locked: boolean;
+    userId?: string;
+    lockedAt?: number;
+}
+
+export interface ActivityLockOptions {
+    /** Identifiant de l'utilisateur connecté. */
+    userId?: string;
+    /** Délai d'inactivité (ms) avant verrouillage. */
+    timeout?: number;
+    /** Callback déclenché lorsque l'écran est verrouillé par inactivité. */
+    onLocked?: () => void;
+}
+
+/**
+ * Verrouillage automatique de l'écran après une période d'inactivité.
+ *
+ * - S'appuie sur `ActivityTrackerService` pour détecter l'activité de l'utilisateur
+ *   (partagé avec les notifications push).
+ * - Le délai est résolu depuis la préférence utilisateur persistée
+ *   (`ACTIVITY_LOCK_PREFERENCE_LABEL`), sinon depuis `AppConfig.UI_ACTIVITY_TRACKER_TIMEOUT`.
+ * - L'état verrouillé est persisté dans le `localStorage` : il survit au rafraîchissement
+ *   de la page (l'écran reste verrouillé tant que l'utilisateur ne se déverrouille pas).
+ * - Le verrouillage est déclenché précisément dès que le délai d'inactivité est atteint
+ *   (minuterie ré-armée à chaque activité, en plus de la surveillance périodique).
+ * - À chaque verrouillage, les formulaires en cours de saisie sont sauvegardés via
+ *   `FormSnapshotService` puis restaurés au déverrouillage de l'interface.
+ */
+export class ActivityLockService {
+
+    protected static enabled = false;
+    protected static userId?: string;
+    protected static timeout = 0;
+    protected static onLocked?: () => void;
+    protected static checkInterval: ReturnType<typeof setInterval> | undefined;
+    protected static lockTimer: ReturnType<typeof setTimeout> | undefined;
+    protected static unwatch: (() => void) | undefined;
+    protected static unwatchActivity: (() => void) | undefined;
+    protected static stopTracking: (() => void) | undefined;
+    protected static handleVisibility: (() => void) | undefined;
+    protected static handleFocus: (() => void) | undefined;
+
+    static get isEnabled(): boolean {
+        return this.enabled;
+    }
+
+    static getPreferenceLabel(): string {
+        return ACTIVITY_LOCK_PREFERENCE_LABEL;
+    }
+
+    /** Lit l'état verrouillé persisté (survit au rafraîchissement de la page). */
+    static isLocked(userId?: string): boolean {
+        if (typeof window === "undefined") return false;
+        try {
+            const raw = window.localStorage.getItem(ACTIVITY_LOCK_STORAGE_KEY);
+            if (!raw) return false;
+            const state = JSON.parse(raw) as ActivityLockState;
+            if (!state?.locked) return false;
+            if (userId && state.userId && state.userId !== userId) return false;
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    /** Persiste l'état verrouillé et stoppe le suivi. */
+    static lock(userId?: string): void {
+        if (typeof window === "undefined") return;
+        this.stop();
+        try {
+            const {isLocked, setLocked} = activityLockStore.getState()
+            const state: ActivityLockState = {locked: true, userId, lockedAt: Date.now()};
+            window.localStorage.setItem(ACTIVITY_LOCK_STORAGE_KEY, JSON.stringify(state));
+            setLocked(true);
+        } catch {
+            // Stockage indisponible : on ignore, le verrou sera géré en mémoire.
+        }
+        // Émis avant que l'écran de verrouillage remplace le contenu : permet à
+        // `FormSnapshotService` de capturer l'état des formulaires encore montés.
+        window.dispatchEvent(new CustomEvent(ACTIVITY_LOCK_EVENT));
+    }
+
+    /** Efface l'état verrouillé. */
+    static unlock(): void {
+        if (typeof window === "undefined") return;
+        try {
+            const {isLocked, setLocked} = activityLockStore.getState()
+            window.localStorage.removeItem(ACTIVITY_LOCK_STORAGE_KEY);
+            setLocked(false);
+        } catch {
+            // Stockage indisponible : on ignore.
+        }
+        // Émis avant le remontage des pages : `FormSnapshotService` restaure le brouillon.
+        window.dispatchEvent(new CustomEvent(ACTIVITY_UNLOCK_EVENT));
+    }
+
+    /**
+     * Résout le délai d'inactivité : préférence utilisateur persistée (si définie),
+     * sinon `AppConfig.UI_ACTIVITY_TRACKER_TIMEOUT`, sinon valeur par défaut.
+     */
+    static async getTimeout(userId?: string): Promise<number> {
+        if (userId) {
+            const raw = await UserPreferencesApiService
+                .getValue(userId, ACTIVITY_LOCK_PREFERENCE_LABEL)
+                .catch(() => undefined);
+            const parsed = raw ? Number(raw) : NaN;
+            if (Number.isFinite(parsed) && parsed > 0) return parsed;
+        }
+        const config = Number(AppConfig.UI_ACTIVITY_TRACKER_TIMEOUT);
+        return Number.isFinite(config) && config > 0 ? config : DEFAULT_TIMEOUT;
+    }
+
+    /** Persiste le délai d'inactivité choisi par l'utilisateur (via UserPreference). */
+    static async setTimeoutPreference(userId: string, timeout: number): Promise<void> {
+        await UserPreferencesApiService.setValue(
+            userId,
+            ACTIVITY_LOCK_PREFERENCE_LABEL,
+            String(Math.round(timeout))
+        );
+    }
+
+    /** Met à jour le délai courant sans redémarrer la surveillance (prise d'effet immédiate). */
+    static updateTimeout(timeout: number): void {
+        this.timeout = timeout;
+        this.scheduleLockTimer();
+    }
+
+    /** Démarre la surveillance d'inactivité. */
+    static start(options: ActivityLockOptions = {}): void {
+        if (this.enabled) this.stop();
+
+        this.enabled = true;
+        this.userId = options.userId;
+        this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+        this.onLocked = options.onLocked;
+
+        // S'assure que le tracker d'activité tourne (partagé avec les notifications push) :
+        // une souscription est comptabilisée et libérée dans `stop()`.
+        this.stopTracking = ActivityTrackerService.start();
+
+        this.unwatch = ActivityTrackerService.watch((state) => {
+            if (this.enabled && !state.active) this.check();
+        });
+
+        // Ré-arme la minuterie précise à chaque activité réelle : l'écran se verrouille
+        // dès que le délai d'inactivité est atteint, sans attendre le passage périodique.
+        this.unwatchActivity = ActivityTrackerService.watchActivity(() => this.scheduleLockTimer());
+
+        // Les minuteries sont bridées en arrière-plan : le verrou doit s'afficher dès
+        // le retour de l'utilisateur dans l'onglet/fenêtre si le délai d'inactivité a
+        // été dépassé pendant la période hors onglet (le focus ne rafraîchit plus
+        // `lastActivityAt`, la vérification peut donc se baser sur l'inactivité réelle).
+        if (typeof document !== "undefined") {
+            this.handleVisibility = () => {
+                if (document.visibilityState === "visible") this.check();
+            };
+            document.addEventListener("visibilitychange", this.handleVisibility);
+        }
+        if (typeof window !== "undefined") {
+            this.handleFocus = () => this.check();
+            window.addEventListener("focus", this.handleFocus);
+        }
+
+        // Sauvegarde/restauration automatique des formulaires en cours de saisie.
+        FormSnapshotService.bind();
+
+        // Vérifie immédiatement (déjà inactif) puis périodiquement.
+        this.check();
+        this.checkInterval = setInterval(() => this.check(), 15000);
+    }
+
+    static stop(): void {
+        this.enabled = false;
+        if (this.checkInterval) {
+            clearInterval(this.checkInterval);
+            this.checkInterval = undefined;
+        }
+        if (this.lockTimer) {
+            clearTimeout(this.lockTimer);
+            this.lockTimer = undefined;
+        }
+        if (this.unwatch) {
+            this.unwatch();
+            this.unwatch = undefined;
+        }
+        if (this.unwatchActivity) {
+            this.unwatchActivity();
+            this.unwatchActivity = undefined;
+        }
+        if (this.stopTracking) {
+            this.stopTracking();
+            this.stopTracking = undefined;
+        }
+        if (typeof document !== "undefined") {
+            if (this.handleVisibility) {
+                document.removeEventListener("visibilitychange", this.handleVisibility);
+                this.handleVisibility = undefined;
+            }
+        }
+        if (typeof window !== "undefined") {
+            if (this.handleFocus) {
+                window.removeEventListener("focus", this.handleFocus);
+                this.handleFocus = undefined;
+            }
+        }
+        this.onLocked = undefined;
+    }
+
+    /**
+     * Arme une minuterie qui déclenche le verrouillage exactement `timeout` ms après
+     * la dernière activité. Elle est ré-armée à chaque activité et recalculée à chaque
+     * passage de `check()` (tolère une activité survenue entre deux événements).
+     */
+    protected static scheduleLockTimer(): void {
+        if (!this.enabled) return;
+        if (this.isLocked(this.userId)) return;
+        if (!this.timeout || this.timeout <= 0) return;
+        if (this.lockTimer) {
+            clearTimeout(this.lockTimer);
+            this.lockTimer = undefined;
+        }
+
+        const elapsed = Date.now() - ActivityTrackerService.lastActivityAt;
+        const remaining = Math.max(0, this.timeout - elapsed);
+        this.lockTimer = setTimeout(() => this.check(), remaining);
+    }
+
+    protected static check(): void {
+        if (!this.enabled) return;
+        if (this.isLocked(this.userId)) return;
+        if (!this.timeout || this.timeout <= 0) return;
+
+        const elapsed = Date.now() - ActivityTrackerService.lastActivityAt;
+        if (elapsed >= this.timeout) {
+            // `lock()` stoppe le service et efface `onLocked` : on capture le callback
+            // AVANT de verrouiller, sinon la notification de verrouillage n'est jamais
+            // émise et le déverrouillage ne ré-armerait pas la surveillance.
+            const notifyLocked = this.onLocked;
+            this.lock(this.userId);
+            notifyLocked?.();
+            return;
+        }
+        this.scheduleLockTimer();
+    }
+}

package/src/infrastructure/utilities/activity-tracker.service.ts

@@ -0,0 +1,205 @@
+"use client"
+
+export interface ActivityState {
+    active: boolean;
+    lastActivityAt: number;
+}
+
+export interface ActivityTrackerOptions {
+    inactivityTimeout?: number;
+    onStateChange?: (state: ActivityState) => void;
+}
+
+export class ActivityTrackerService {
+
+    protected static inactivityTimeout = 60000;
+    protected static trackingStarted = false;
+    protected static active = false;
+    protected static lastActivityTimestamp = 0;
+    protected static onStateChange: ((state: ActivityState) => void) | undefined;
+    protected static watchers: Array<(state: ActivityState) => void> = [];
+    protected static activityWatchers: Array<(timestamp: number) => void> = [];
+
+    protected static activityHandler = (): void => undefined;
+    protected static refocusHandler = (): void => undefined;
+    protected static blurHandler = (): void => undefined;
+    protected static stateSyncInterval: ReturnType<typeof setInterval> | undefined;
+
+    /** Nombre de consommateurs actifs (verrouillage, notifications push…). */
+    protected static consumers = 0;
+
+    static get isSupported(): boolean {
+        return typeof window !== "undefined";
+    }
+
+    static get isStarted(): boolean {
+        return this.trackingStarted;
+    }
+
+    static get isActive(): boolean {
+        return this.active;
+    }
+
+    static get isInactive(): boolean {
+        return !this.active;
+    }
+
+    static get lastActivityAt(): number {
+        return this.lastActivityTimestamp;
+    }
+
+    static get state(): ActivityState {
+        return {active: this.active, lastActivityAt: this.lastActivityTimestamp};
+    }
+
+    /**
+     * Abonne un observateur aux changements d'état d'activité.
+     * Permet à plusieurs features (verrouillage automatique, notifications push…)
+     * de réagir au même tracker sans démarrer d'instance supplémentaire.
+     * Renvoie une fonction pour désabonner l'observateur.
+     */
+    static watch(callback: (state: ActivityState) => void): () => void {
+        this.watchers.push(callback);
+        return () => {
+            this.watchers = this.watchers.filter((watcher) => watcher !== callback);
+        };
+    }
+
+    /**
+     * Abonne un observateur à chaque évènement d'activité réelle (mouvement, clic,
+     * frappe…). Contrairement à `watch()`, le callback est invoqué à chaque activité
+     * et reçoit l'horodatage de cette dernière - utile pour (ré)armer précisément un
+     * délai basé sur la dernière activité (ex. verrouillage automatique).
+     * Renvoie une fonction pour désabonner l'observateur.
+     */
+    static watchActivity(callback: (timestamp: number) => void): () => void {
+        this.activityWatchers.push(callback);
+        return () => {
+            this.activityWatchers = this.activityWatchers.filter((watcher) => watcher !== callback);
+        };
+    }
+
+    /**
+     * Abonne un consommateur au suivi d'activité. Le premier appel démarre le
+     * suivi (listeners + intervalle) ; les appels suivants réutilisent l'exécution
+     * en cours et re-lient éventuellement `onStateChange`.
+     *
+     * Renvoie une fonction de libération : le suivi n'est arrêté que lorsque le
+     * dernier consommateur l'a libérée. Contrairement à `stop()` (teardown global),
+     * libérer une souscription ne détruit ni les watchers ni l'horloge des autres
+     * consommateurs (ex. verrouillage automatique partageant le tracker avec le push).
+     */
+    static start(options?: ActivityTrackerOptions): () => void {
+        if (!this.isSupported) return () => undefined;
+
+        this.consumers += 1;
+
+        if (options?.onStateChange) {
+            this.onStateChange = options.onStateChange;
+        }
+
+        // Chaque nouvelle souscription relance l'horloge d'activité : après un
+        // déverrouillage, l'inactivité recommence à zéro (pas de re-verrouillage
+        // immédiat même si le tracker était encore actif).
+        this.lastActivityTimestamp = Date.now();
+
+        if (!this.trackingStarted) {
+            this.trackingStarted = true;
+            this.active = true;
+            this.inactivityTimeout = options?.inactivityTimeout ?? 60000;
+
+            this.activityHandler = () => {
+                this.lastActivityTimestamp = Date.now();
+                if (!this.active) {
+                    this.active = true;
+                    this.emitStateChange();
+                }
+                const timestamp = this.lastActivityTimestamp;
+                for (const watcher of this.activityWatchers) {
+                    watcher(timestamp);
+                }
+            };
+
+            /**
+             * Le simple retour de focus ne remet PAS l'horloge d'inactivité à zéro :
+             * la dernière activité réelle reste inchangée pour que les consommateurs
+             * (ex. verrouillage automatique) constatent que le temps passé hors de
+             * l'onglet/fenêtre compte comme de l'inactivité. L'état redevient actif,
+             * mais le délai est recalculé à partir de la dernière activité réelle.
+             */
+            this.refocusHandler = () => {
+                if (!this.active) {
+                    this.active = true;
+                    this.emitStateChange();
+                }
+                const timestamp = this.lastActivityTimestamp;
+                for (const watcher of this.activityWatchers) {
+                    watcher(timestamp);
+                }
+            };
+
+            this.blurHandler = () => {
+                if (this.active) {
+                    this.active = false;
+                    this.emitStateChange();
+                }
+            };
+
+            window.addEventListener("mousemove", this.activityHandler, {passive: true});
+            window.addEventListener("mousedown", this.activityHandler, {passive: true});
+            window.addEventListener("keydown", this.activityHandler, {passive: true});
+            window.addEventListener("scroll", this.activityHandler, {passive: true});
+            window.addEventListener("touchstart", this.activityHandler, {passive: true});
+            window.addEventListener("focus", this.refocusHandler);
+            window.addEventListener("blur", this.blurHandler);
+
+            this.stateSyncInterval = setInterval(() => {
+                const isInactive = Date.now() - this.lastActivityTimestamp >= this.inactivityTimeout;
+                if (isInactive && this.active) {
+                    this.active = false;
+                    this.emitStateChange();
+                }
+            }, 15000);
+        }
+
+        let released = false;
+        return () => {
+            if (released) return;
+            released = true;
+            this.consumers = Math.max(0, this.consumers - 1);
+            if (this.consumers === 0) {
+                this.stop();
+            }
+        };
+    }
+
+    static stop(): void {
+        if (!this.trackingStarted) return;
+
+        this.trackingStarted = false;
+        if (this.stateSyncInterval) clearInterval(this.stateSyncInterval);
+        this.stateSyncInterval = undefined;
+
+        window.removeEventListener("mousemove", this.activityHandler);
+        window.removeEventListener("mousedown", this.activityHandler);
+        window.removeEventListener("keydown", this.activityHandler);
+        window.removeEventListener("scroll", this.activityHandler);
+        window.removeEventListener("touchstart", this.activityHandler);
+        window.removeEventListener("focus", this.refocusHandler);
+        window.removeEventListener("blur", this.blurHandler);
+
+        this.onStateChange = undefined;
+        this.watchers = [];
+        this.activityWatchers = [];
+        this.consumers = 0;
+    }
+
+    protected static emitStateChange(): void {
+        const state = this.state;
+        this.onStateChange?.(state);
+        for (const watcher of this.watchers) {
+            watcher(state);
+        }
+    }
+
+}