@se-studio/core-ui 0.0.0-next16-20260822103555

package/dist/analytics/video/createVideoEngagementSession.js

@@ -0,0 +1,225 @@
+import { classifySeek } from './classifySeek';
+import { VIDEO_ENGAGEMENT_EVENTS, VIDEO_ENGAGEMENT_THRESHOLDS, } from './videoEngagementTypes';
+function clampPercent(value) {
+    if (!Number.isFinite(value) || value < 0)
+        return 0;
+    if (value > 100)
+        return 100;
+    return value;
+}
+function percentOf(current, duration) {
+    if (!duration || duration <= 0 || !Number.isFinite(current))
+        return 0;
+    return clampPercent((current / duration) * 100);
+}
+function defaultPageUrl() {
+    if (typeof window === 'undefined')
+        return '';
+    return window.location.href;
+}
+/**
+ * Pure engagement session: provider adapters translate player events into these methods.
+ * Fires at most one start/complete/exit/impression; quartiles once each; unmute once.
+ */
+export function createVideoEngagementSession(options) {
+    const { identity, track } = options;
+    const getPageUrl = options.getPageUrl ?? defaultPageUrl;
+    const state = {
+        impressed: false,
+        started: false,
+        completed: false,
+        exited: false,
+        muted: false,
+        mutedAtStart: null,
+        usedFullscreen: false,
+        fullscreen: false,
+        maxPercent: 0,
+        watchSeconds: 0,
+        durationSeconds: 0,
+        seekCount: 0,
+        largeForwardSeekCount: 0,
+        quartilesFired: new Set(),
+        unmutedFired: false,
+        playing: false,
+        playStartedAtMs: null,
+    };
+    function baseProps() {
+        return {
+            ...identity,
+            url: getPageUrl(),
+            autoplay: false,
+            max_percent: Math.round(state.maxPercent * 10) / 10,
+            watch_seconds: Math.round(state.watchSeconds * 10) / 10,
+            duration_seconds: state.durationSeconds > 0 ? Math.round(state.durationSeconds * 10) / 10 : undefined,
+            muted: state.muted,
+            muted_at_start: state.mutedAtStart ?? undefined,
+            used_fullscreen: state.usedFullscreen,
+            seek_count: state.seekCount,
+            completed: state.completed,
+        };
+    }
+    function emit(event, extra) {
+        track(event, { ...baseProps(), ...extra });
+    }
+    function accumulateWatchTime() {
+        if (state.playStartedAtMs == null)
+            return;
+        const now = Date.now();
+        const delta = (now - state.playStartedAtMs) / 1000;
+        if (delta > 0 && Number.isFinite(delta)) {
+            state.watchSeconds += delta;
+        }
+        state.playStartedAtMs = state.playing ? now : null;
+    }
+    function updateMaxPercent(currentTime, duration) {
+        if (duration > 0) {
+            state.durationSeconds = duration;
+        }
+        const pct = percentOf(currentTime, duration || state.durationSeconds);
+        if (pct > state.maxPercent) {
+            state.maxPercent = pct;
+        }
+    }
+    function maybeFireQuartiles() {
+        if (!state.started || state.completed)
+            return;
+        for (const q of VIDEO_ENGAGEMENT_THRESHOLDS.quartiles) {
+            if (state.maxPercent >= q && !state.quartilesFired.has(q)) {
+                state.quartilesFired.add(q);
+                emit(VIDEO_ENGAGEMENT_EVENTS.progress, { percent: q });
+            }
+        }
+    }
+    function maybeComplete(reason) {
+        if (state.completed || !state.started)
+            return;
+        const hitThreshold = state.maxPercent >= VIDEO_ENGAGEMENT_THRESHOLDS.completePercent;
+        if (reason === 'ended' || hitThreshold) {
+            state.completed = true;
+            if (reason === 'ended' && state.maxPercent < 100) {
+                state.maxPercent = Math.max(state.maxPercent, 100);
+            }
+            accumulateWatchTime();
+            emit(VIDEO_ENGAGEMENT_EVENTS.complete, {
+                percent: 100,
+                completed: true,
+                skipped: false,
+            });
+        }
+    }
+    function isSkipped() {
+        if (state.completed)
+            return false;
+        const lowEngagement = state.maxPercent < VIDEO_ENGAGEMENT_THRESHOLDS.skipMaxPercent &&
+            state.watchSeconds < VIDEO_ENGAGEMENT_THRESHOLDS.skipMaxWatchSeconds;
+        const seekSkip = state.largeForwardSeekCount >= 1 &&
+            state.maxPercent < VIDEO_ENGAGEMENT_THRESHOLDS.skipAfterSeekMaxPercent;
+        return lowEngagement || seekSkip;
+    }
+    return {
+        markImpression() {
+            if (state.impressed)
+                return;
+            state.impressed = true;
+            emit(VIDEO_ENGAGEMENT_EVENTS.impression);
+        },
+        onPlay(muted) {
+            state.muted = muted;
+            if (state.mutedAtStart === null) {
+                state.mutedAtStart = muted;
+            }
+            if (!state.started) {
+                state.started = true;
+                emit(VIDEO_ENGAGEMENT_EVENTS.start, { muted });
+            }
+            state.playing = true;
+            state.playStartedAtMs = Date.now();
+        },
+        onPause() {
+            if (!state.playing)
+                return;
+            accumulateWatchTime();
+            state.playing = false;
+            state.playStartedAtMs = null;
+        },
+        onTime(currentTimeSeconds, durationSeconds) {
+            // Keep watch_seconds current during continuous play (not only on pause/exit).
+            if (state.playing) {
+                accumulateWatchTime();
+            }
+            updateMaxPercent(currentTimeSeconds, durationSeconds);
+            maybeFireQuartiles();
+            maybeComplete('threshold');
+        },
+        onSeek(fromSeconds, toSeconds, durationSeconds) {
+            if (durationSeconds > 0) {
+                state.durationSeconds = durationSeconds;
+            }
+            const duration = durationSeconds || state.durationSeconds;
+            const classification = classifySeek(fromSeconds, toSeconds, duration);
+            updateMaxPercent(toSeconds, duration);
+            if (!classification.material) {
+                return;
+            }
+            state.seekCount += 1;
+            if (classification.largeForward) {
+                state.largeForwardSeekCount += 1;
+            }
+            if (!state.started)
+                return;
+            emit(VIDEO_ENGAGEMENT_EVENTS.seek, {
+                from_percent: classification.fromPercent,
+                to_percent: classification.toPercent,
+                direction: classification.direction,
+            });
+            maybeFireQuartiles();
+            maybeComplete('threshold');
+        },
+        onMuteChange(muted) {
+            const wasMuted = state.muted;
+            state.muted = muted;
+            if (wasMuted && !muted && !state.unmutedFired && state.started) {
+                state.unmutedFired = true;
+                emit(VIDEO_ENGAGEMENT_EVENTS.unmute, { muted: false });
+            }
+        },
+        onFullscreen(fullscreen) {
+            state.fullscreen = fullscreen;
+            if (fullscreen) {
+                state.usedFullscreen = true;
+            }
+            if (!state.started && !state.impressed)
+                return;
+            emit(VIDEO_ENGAGEMENT_EVENTS.fullscreen, { fullscreen });
+        },
+        onEnded(durationSeconds) {
+            accumulateWatchTime();
+            state.playing = false;
+            state.playStartedAtMs = null;
+            if (durationSeconds > 0) {
+                state.durationSeconds = durationSeconds;
+                state.maxPercent = Math.max(state.maxPercent, 100);
+            }
+            maybeComplete('ended');
+        },
+        dispose() {
+            accumulateWatchTime();
+            state.playing = false;
+            state.playStartedAtMs = null;
+            if (state.exited)
+                return;
+            state.exited = true;
+            // Exit only if the user started playback (impressions without play stay silent).
+            if (!state.started)
+                return;
+            emit(VIDEO_ENGAGEMENT_EVENTS.exit, {
+                completed: state.completed,
+                skipped: isSkipped(),
+            });
+        },
+        getState() {
+            return state;
+        },
+    };
+}
+//# sourceMappingURL=createVideoEngagementSession.js.map

package/dist/analytics/video/createVideoEngagementSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createVideoEngagementSession.js","sourceRoot":"","sources":["../../../src/analytics/video/createVideoEngagementSession.ts"],"names":[],"mappings":"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"}

package/dist/analytics/video/index.d.ts

@@ -0,0 +1,6 @@
+export { classifySeek, type SeekClassification } from './classifySeek';
+export { type CreateVideoEngagementSessionOptions, createVideoEngagementSession, type VideoEngagementSession, } from './createVideoEngagementSession';
+export { useHtml5VideoEngagement } from './useHtml5VideoEngagement';
+export { type UseVideoEngagementOptions, useVideoEngagement } from './useVideoEngagement';
+export { VIDEO_ENGAGEMENT_EVENT_NAMES, VIDEO_ENGAGEMENT_EVENTS, VIDEO_ENGAGEMENT_THRESHOLDS, type VideoEngagementEventName, type VideoEngagementIdentity, type VideoEngagementTrackFn, type VideoProvider, } from './videoEngagementTypes';
+//# sourceMappingURL=index.d.ts.map

package/dist/analytics/video/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/analytics/video/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,EACL,KAAK,mCAAmC,EACxC,4BAA4B,EAC5B,KAAK,sBAAsB,GAC5B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,KAAK,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1F,OAAO,EACL,4BAA4B,EAC5B,uBAAuB,EACvB,2BAA2B,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,aAAa,GACnB,MAAM,wBAAwB,CAAC"}

package/dist/analytics/video/index.js

@@ -0,0 +1,6 @@
+export { classifySeek } from './classifySeek';
+export { createVideoEngagementSession, } from './createVideoEngagementSession';
+export { useHtml5VideoEngagement } from './useHtml5VideoEngagement';
+export { useVideoEngagement } from './useVideoEngagement';
+export { VIDEO_ENGAGEMENT_EVENT_NAMES, VIDEO_ENGAGEMENT_EVENTS, VIDEO_ENGAGEMENT_THRESHOLDS, } from './videoEngagementTypes';
+//# sourceMappingURL=index.js.map

package/dist/analytics/video/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/analytics/video/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAA2B,MAAM,gBAAgB,CAAC;AACvE,OAAO,EAEL,4BAA4B,GAE7B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAkC,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1F,OAAO,EACL,4BAA4B,EAC5B,uBAAuB,EACvB,2BAA2B,GAK5B,MAAM,wBAAwB,CAAC"}

package/dist/analytics/video/loadYouTubeIframeApi.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Singleton loader for the YouTube IFrame Player API.
+ * @see https://developers.google.com/youtube/iframe_api_reference
+ */
+export interface YouTubePlayer {
+    destroy: () => void;
+    getCurrentTime: () => number;
+    getDuration: () => number;
+    isMuted: () => boolean;
+    getPlayerState: () => number;
+    getIframe: () => HTMLIFrameElement;
+}
+export interface YouTubePlayerEvent {
+    target: YouTubePlayer;
+    data: number;
+}
+export interface YouTubePlayerConstructor {
+    new (element: HTMLElement | string, options: {
+        events?: {
+            onReady?: (event: YouTubePlayerEvent) => void;
+            onStateChange?: (event: YouTubePlayerEvent) => void;
+            onError?: (event: YouTubePlayerEvent) => void;
+        };
+    }): YouTubePlayer;
+    PlayerState: {
+        UNSTARTED: number;
+        ENDED: number;
+        PLAYING: number;
+        PAUSED: number;
+        BUFFERING: number;
+        CUED: number;
+    };
+}
+declare global {
+    interface Window {
+        YT?: {
+            Player: YouTubePlayerConstructor;
+            PlayerState: YouTubePlayerConstructor['PlayerState'];
+        };
+        onYouTubeIframeAPIReady?: () => void;
+    }
+}
+export declare function loadYouTubeIframeApi(): Promise<YouTubePlayerConstructor>;
+/** YT.PlayerState.PLAYING */
+export declare const YT_PLAYING = 1;
+/** YT.PlayerState.PAUSED */
+export declare const YT_PAUSED = 2;
+/** YT.PlayerState.ENDED */
+export declare const YT_ENDED = 0;
+//# sourceMappingURL=loadYouTubeIframeApi.d.ts.map

package/dist/analytics/video/loadYouTubeIframeApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadYouTubeIframeApi.d.ts","sourceRoot":"","sources":["../../../src/analytics/video/loadYouTubeIframeApi.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,cAAc,EAAE,MAAM,MAAM,CAAC;IAC7B,WAAW,EAAE,MAAM,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,OAAO,CAAC;IACvB,cAAc,EAAE,MAAM,MAAM,CAAC;IAC7B,SAAS,EAAE,MAAM,iBAAiB,CAAC;CACpC;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,aAAa,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,wBAAwB;IACvC,KACE,OAAO,EAAE,WAAW,GAAG,MAAM,EAC7B,OAAO,EAAE;QACP,MAAM,CAAC,EAAE;YACP,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;YAC9C,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;YACpD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;SAC/C,CAAC;KACH,GACA,aAAa,CAAC;IACjB,WAAW,EAAE;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,EAAE,CAAC,EAAE;YACH,MAAM,EAAE,wBAAwB,CAAC;YACjC,WAAW,EAAE,wBAAwB,CAAC,aAAa,CAAC,CAAC;SACtD,CAAC;QACF,uBAAuB,CAAC,EAAE,MAAM,IAAI,CAAC;KACtC;CACF;AAID,wBAAgB,oBAAoB,IAAI,OAAO,CAAC,wBAAwB,CAAC,CA4CxE;AAED,6BAA6B;AAC7B,eAAO,MAAM,UAAU,IAAI,CAAC;AAC5B,4BAA4B;AAC5B,eAAO,MAAM,SAAS,IAAI,CAAC;AAC3B,2BAA2B;AAC3B,eAAO,MAAM,QAAQ,IAAI,CAAC"}

package/dist/analytics/video/loadYouTubeIframeApi.js

@@ -0,0 +1,52 @@
+/**
+ * Singleton loader for the YouTube IFrame Player API.
+ * @see https://developers.google.com/youtube/iframe_api_reference
+ */
+let loadPromise = null;
+export function loadYouTubeIframeApi() {
+    if (typeof window === 'undefined') {
+        return Promise.reject(new Error('YouTube IFrame API requires a browser'));
+    }
+    if (window.YT?.Player) {
+        return Promise.resolve(window.YT.Player);
+    }
+    if (loadPromise) {
+        return loadPromise;
+    }
+    loadPromise = new Promise((resolve, reject) => {
+        const previous = window.onYouTubeIframeAPIReady;
+        window.onYouTubeIframeAPIReady = () => {
+            previous?.();
+            if (window.YT?.Player) {
+                resolve(window.YT.Player);
+            }
+            else {
+                reject(new Error('YouTube IFrame API loaded without YT.Player'));
+            }
+        };
+        const existing = document.querySelector('script[src="https://www.youtube.com/iframe_api"]');
+        if (existing) {
+            // Script already requested; onYouTubeIframeAPIReady will fire (or already did)
+            if (window.YT?.Player) {
+                resolve(window.YT.Player);
+            }
+            return;
+        }
+        const script = document.createElement('script');
+        script.src = 'https://www.youtube.com/iframe_api';
+        script.async = true;
+        script.onerror = () => {
+            loadPromise = null;
+            reject(new Error('Failed to load YouTube IFrame API'));
+        };
+        document.head.appendChild(script);
+    });
+    return loadPromise;
+}
+/** YT.PlayerState.PLAYING */
+export const YT_PLAYING = 1;
+/** YT.PlayerState.PAUSED */
+export const YT_PAUSED = 2;
+/** YT.PlayerState.ENDED */
+export const YT_ENDED = 0;
+//# sourceMappingURL=loadYouTubeIframeApi.js.map

package/dist/analytics/video/loadYouTubeIframeApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadYouTubeIframeApi.js","sourceRoot":"","sources":["../../../src/analytics/video/loadYouTubeIframeApi.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA+CH,IAAI,WAAW,GAA6C,IAAI,CAAC;AAEjE,MAAM,UAAU,oBAAoB;IAClC,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC,CAAC;IAC5E,CAAC;IAED,IAAI,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC;QACtB,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;IAC3C,CAAC;IAED,IAAI,WAAW,EAAE,CAAC;QAChB,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,WAAW,GAAG,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC5C,MAAM,QAAQ,GAAG,MAAM,CAAC,uBAAuB,CAAC;QAChD,MAAM,CAAC,uBAAuB,GAAG,GAAG,EAAE;YACpC,QAAQ,EAAE,EAAE,CAAC;YACb,IAAI,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC;gBACtB,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;YAC5B,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC,CAAC;YACnE,CAAC;QACH,CAAC,CAAC;QAEF,MAAM,QAAQ,GAAG,QAAQ,CAAC,aAAa,CAAC,kDAAkD,CAAC,CAAC;QAC5F,IAAI,QAAQ,EAAE,CAAC;YACb,+EAA+E;YAC/E,IAAI,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC;gBACtB,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;YAC5B,CAAC;YACD,OAAO;QACT,CAAC;QAED,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QAChD,MAAM,CAAC,GAAG,GAAG,oCAAoC,CAAC;QAClD,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,MAAM,CAAC,OAAO,GAAG,GAAG,EAAE;YACpB,WAAW,GAAG,IAAI,CAAC;YACnB,MAAM,CAAC,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC,CAAC;QACzD,CAAC,CAAC;QACF,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,6BAA6B;AAC7B,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC;AAC5B,4BAA4B;AAC5B,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC;AAC3B,2BAA2B;AAC3B,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC"}

package/dist/analytics/video/useHtml5VideoEngagement.d.ts

@@ -0,0 +1,8 @@
+import type { RefObject } from 'react';
+import type { VideoEngagementSession } from './createVideoEngagementSession';
+/**
+ * Wires native HTMLMediaElement events into a video engagement session.
+ * No-ops when sessionRef.current is null (autoplay / no analytics).
+ */
+export declare function useHtml5VideoEngagement(videoRef: RefObject<HTMLVideoElement | null>, sessionRef: RefObject<VideoEngagementSession | null>, enabled: boolean): void;
+//# sourceMappingURL=useHtml5VideoEngagement.d.ts.map

package/dist/analytics/video/useHtml5VideoEngagement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHtml5VideoEngagement.d.ts","sourceRoot":"","sources":["../../../src/analytics/video/useHtml5VideoEngagement.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAE7E;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,EAC5C,UAAU,EAAE,SAAS,CAAC,sBAAsB,GAAG,IAAI,CAAC,EACpD,OAAO,EAAE,OAAO,GACf,IAAI,CA8DN"}

package/dist/analytics/video/useHtml5VideoEngagement.js

@@ -0,0 +1,67 @@
+'use client';
+import { useEffect, useRef } from 'react';
+/**
+ * Wires native HTMLMediaElement events into a video engagement session.
+ * No-ops when sessionRef.current is null (autoplay / no analytics).
+ */
+export function useHtml5VideoEngagement(videoRef, sessionRef, enabled) {
+    const lastTimeRef = useRef(0);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const video = videoRef.current;
+        if (!video)
+            return;
+        const session = () => sessionRef.current;
+        const onPlay = () => {
+            session()?.onPlay(video.muted || video.volume === 0);
+            lastTimeRef.current = video.currentTime;
+        };
+        const onPause = () => {
+            session()?.onPause();
+        };
+        const onTimeUpdate = () => {
+            session()?.onTime(video.currentTime, video.duration || 0);
+            lastTimeRef.current = video.currentTime;
+        };
+        const onSeeking = () => {
+            // capture pre-seek time is already in lastTimeRef from timeupdate
+        };
+        const onSeeked = () => {
+            const from = lastTimeRef.current;
+            const to = video.currentTime;
+            session()?.onSeek(from, to, video.duration || 0);
+            lastTimeRef.current = to;
+        };
+        const onVolumeChange = () => {
+            session()?.onMuteChange(video.muted || video.volume === 0);
+        };
+        const onEnded = () => {
+            session()?.onEnded(video.duration || 0);
+        };
+        const onFullscreenChange = () => {
+            const fsEl = document.fullscreenElement;
+            const isFs = fsEl === video || !!fsEl?.contains(video);
+            session()?.onFullscreen(isFs);
+        };
+        video.addEventListener('play', onPlay);
+        video.addEventListener('pause', onPause);
+        video.addEventListener('timeupdate', onTimeUpdate);
+        video.addEventListener('seeking', onSeeking);
+        video.addEventListener('seeked', onSeeked);
+        video.addEventListener('volumechange', onVolumeChange);
+        video.addEventListener('ended', onEnded);
+        document.addEventListener('fullscreenchange', onFullscreenChange);
+        return () => {
+            video.removeEventListener('play', onPlay);
+            video.removeEventListener('pause', onPause);
+            video.removeEventListener('timeupdate', onTimeUpdate);
+            video.removeEventListener('seeking', onSeeking);
+            video.removeEventListener('seeked', onSeeked);
+            video.removeEventListener('volumechange', onVolumeChange);
+            video.removeEventListener('ended', onEnded);
+            document.removeEventListener('fullscreenchange', onFullscreenChange);
+        };
+    }, [videoRef, sessionRef, enabled]);
+}
+//# sourceMappingURL=useHtml5VideoEngagement.js.map

package/dist/analytics/video/useHtml5VideoEngagement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHtml5VideoEngagement.js","sourceRoot":"","sources":["../../../src/analytics/video/useHtml5VideoEngagement.ts"],"names":[],"mappings":"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"}

package/dist/analytics/video/useVideoEngagement.d.ts

@@ -0,0 +1,19 @@
+import type { IAnalyticsContext } from '@se-studio/core-data-types';
+import { type MutableRefObject, type RefObject } from 'react';
+import { type VideoEngagementSession } from './createVideoEngagementSession';
+import { type VideoEngagementIdentity } from './videoEngagementTypes';
+export interface UseVideoEngagementOptions {
+    identity: VideoEngagementIdentity;
+    analyticsContext: IAnalyticsContext | null | undefined;
+    /** When false, no session is created (autoplay / background). */
+    enabled?: boolean;
+}
+/**
+ * Creates a video engagement session bound to `trackEvent` when analytics context is present.
+ * Observes `rootRef` for impression; disposes on unmount / pagehide.
+ */
+export declare function useVideoEngagement({ identity, analyticsContext, enabled, }: UseVideoEngagementOptions): {
+    sessionRef: MutableRefObject<VideoEngagementSession | null>;
+    rootRef: RefObject<HTMLElement | null>;
+};
+//# sourceMappingURL=useVideoEngagement.d.ts.map

package/dist/analytics/video/useVideoEngagement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useVideoEngagement.d.ts","sourceRoot":"","sources":["../../../src/analytics/video/useVideoEngagement.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,SAAS,EAAqB,MAAM,OAAO,CAAC;AAEjF,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAA+B,KAAK,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAEnG,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,uBAAuB,CAAC;IAClC,gBAAgB,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,CAAC;IACvD,iEAAiE;IACjE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,QAAQ,EACR,gBAAgB,EAChB,OAAc,GACf,EAAE,yBAAyB,GAAG;IAC7B,UAAU,EAAE,gBAAgB,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAAC;IAC5D,OAAO,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CACxC,CA+EA"}

package/dist/analytics/video/useVideoEngagement.js

@@ -0,0 +1,80 @@
+'use client';
+import { useEffect, useRef } from 'react';
+import { useAnalytics } from '../useAnalytics';
+import { createVideoEngagementSession, } from './createVideoEngagementSession';
+import { VIDEO_ENGAGEMENT_THRESHOLDS } from './videoEngagementTypes';
+/**
+ * Creates a video engagement session bound to `trackEvent` when analytics context is present.
+ * Observes `rootRef` for impression; disposes on unmount / pagehide.
+ */
+export function useVideoEngagement({ identity, analyticsContext, enabled = true, }) {
+    const { trackEvent } = useAnalytics();
+    const sessionRef = useRef(null);
+    const rootRef = useRef(null);
+    const trackEventRef = useRef(trackEvent);
+    trackEventRef.current = trackEvent;
+    const canTrack = Boolean(enabled && analyticsContext);
+    const identityRef = useRef(identity);
+    identityRef.current = identity;
+    // Primitive deps only — avoid recreating the session when parent passes a new
+    // analyticsContext object with the same slug/title/type.
+    const slug = analyticsContext?.slug ?? '';
+    const pageTitle = analyticsContext?.title ?? '';
+    const pageType = analyticsContext?.type ?? '';
+    const videoProvider = identity.video_provider;
+    const videoId = identity.video_id;
+    const videoLocation = identity.location ?? '';
+    useEffect(() => {
+        if (!canTrack) {
+            sessionRef.current = null;
+            return;
+        }
+        const currentIdentity = identityRef.current;
+        const session = createVideoEngagementSession({
+            identity: {
+                ...currentIdentity,
+                video_provider: videoProvider,
+                video_id: videoId,
+                location: videoLocation || currentIdentity.location,
+                slug: slug || currentIdentity.slug,
+                title: pageTitle || currentIdentity.title,
+                type: pageType || currentIdentity.type,
+            },
+            track: (event, properties) => {
+                trackEventRef.current(event, properties);
+            },
+        });
+        sessionRef.current = session;
+        const onPageHide = () => {
+            session.dispose();
+        };
+        window.addEventListener('pagehide', onPageHide);
+        return () => {
+            window.removeEventListener('pagehide', onPageHide);
+            session.dispose();
+            if (sessionRef.current === session) {
+                sessionRef.current = null;
+            }
+        };
+    }, [canTrack, videoProvider, videoId, videoLocation, slug, pageTitle, pageType]);
+    useEffect(() => {
+        if (!canTrack)
+            return;
+        const el = rootRef.current;
+        if (!el)
+            return;
+        const observer = new IntersectionObserver((entries) => {
+            const entry = entries[0];
+            if (entry?.isIntersecting) {
+                sessionRef.current?.markImpression();
+            }
+        }, { threshold: VIDEO_ENGAGEMENT_THRESHOLDS.impressionRatio });
+        observer.observe(el);
+        return () => observer.disconnect();
+        // videoProvider/videoId/location/slug: re-bind when tracked video identity changes
+        // (session is recreated in the effect above; observer must re-run for a new impression).
+        // biome-ignore lint/correctness/useExhaustiveDependencies: intentional identity key
+    }, [canTrack, videoProvider, videoId, videoLocation, slug]);
+    return { sessionRef, rootRef };
+}
+//# sourceMappingURL=useVideoEngagement.js.map

package/dist/analytics/video/useVideoEngagement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useVideoEngagement.js","sourceRoot":"","sources":["../../../src/analytics/video/useVideoEngagement.ts"],"names":[],"mappings":"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"}

package/dist/analytics/video/videoEngagementTypes.d.ts

@@ -0,0 +1,52 @@
+/**
+ * First-party video engagement events fired via `trackEvent`.
+ * Sites map these names to GTM tags or HubSpot behavioural events.
+ */
+export declare const VIDEO_ENGAGEMENT_EVENTS: {
+    readonly impression: "video_impression";
+    readonly start: "video_start";
+    readonly progress: "video_progress";
+    readonly complete: "video_complete";
+    readonly seek: "video_seek";
+    readonly unmute: "video_unmute";
+    readonly fullscreen: "video_fullscreen";
+    readonly exit: "video_exit";
+};
+export type VideoEngagementEventName = (typeof VIDEO_ENGAGEMENT_EVENTS)[keyof typeof VIDEO_ENGAGEMENT_EVENTS];
+/** All engagement event name strings (for HubSpot eventNameMap keys, etc.). */
+export declare const VIDEO_ENGAGEMENT_EVENT_NAMES: readonly VideoEngagementEventName[];
+export type VideoProvider = 'vimeo' | 'youtube' | 'local';
+/**
+ * Thresholds for progress, completion, skip, and seek classification.
+ * Tuned for marketing-site explainer videos (not long-form).
+ */
+export declare const VIDEO_ENGAGEMENT_THRESHOLDS: {
+    /** Treat as completed when high-water mark reaches this % (or player ended). */
+    readonly completePercent: 95;
+    /** Exit with low % + short watch time counts as skipped. */
+    readonly skipMaxPercent: 10;
+    readonly skipMaxWatchSeconds: 3;
+    /** Large forward seek: at least this % of duration OR this many seconds. */
+    readonly seekMinPercent: 15;
+    readonly seekMinSeconds: 10;
+    /** After a large forward seek, incomplete exit with max_percent below this is skipped. */
+    readonly skipAfterSeekMaxPercent: 50;
+    readonly quartiles: readonly [25, 50, 75];
+    /** IntersectionObserver threshold for video_impression. */
+    readonly impressionRatio: 0.5;
+};
+export interface VideoEngagementIdentity {
+    video_provider: VideoProvider;
+    video_id: string;
+    video_title: string;
+    video_url?: string;
+    location?: string;
+    /** Page slug from IAnalyticsContext */
+    slug?: string;
+    /** Page title from IAnalyticsContext */
+    title?: string;
+    /** Page type from IAnalyticsContext */
+    type?: string;
+}
+export type VideoEngagementTrackFn = (event: string, properties: Record<string, unknown>) => void;
+//# sourceMappingURL=videoEngagementTypes.d.ts.map

package/dist/analytics/video/videoEngagementTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"videoEngagementTypes.d.ts","sourceRoot":"","sources":["../../../src/analytics/video/videoEngagementTypes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;CAS1B,CAAC;AAEX,MAAM,MAAM,wBAAwB,GAClC,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,OAAO,uBAAuB,CAAC,CAAC;AAEzE,+EAA+E;AAC/E,eAAO,MAAM,4BAA4B,EAAE,SAAS,wBAAwB,EAS3E,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,2BAA2B;IACtC,gFAAgF;;IAEhF,4DAA4D;;;IAG5D,4EAA4E;;;IAG5E,0FAA0F;;;IAG1F,2DAA2D;;CAEnD,CAAC;AAEX,MAAM,WAAW,uBAAuB;IACtC,cAAc,EAAE,aAAa,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,sBAAsB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC"}