@thewhateverapp/tile-sdk 0.11.2 → 0.12.1

package/dist/react/overlay/VideoPlayer.d.ts

@@ -50,12 +50,20 @@ export interface VideoContextValue {
     controls: VideoControls;
     videoRef: React.RefObject<HTMLVideoElement>;
 }
+export interface CuePoint {
+    /** Time in seconds when the cue should trigger */
+    time: number;
+    /** Unique identifier for the cue point */
+    id: string;
+    /** Optional data to pass to the callback */
+    data?: unknown;
+}
 export interface VideoPlayerProps {
     /** HLS playlist URL (m3u8) */
     src: string;
     /** Auto-start playback (default: true) */
     autoplay?: boolean;
-    /** Loop video (default: false) */
+    /** Loop video (default: false, but true in preview mode) */
     loop?: boolean;
     /** Start muted (default: true for autoplay compliance) */
     muted?: boolean;
@@ -69,15 +77,103 @@ export interface VideoPlayerProps {
     className?: string;
     /** Video wrapper class names */
     videoClassName?: string;
+    /** Cue points for time-based triggers */
+    cuePoints?: CuePoint[];
+    /** Callback when a cue point is reached */
+    onCuePoint?: (cuePoint: CuePoint) => void;
+    /** Callback on time update (fires ~4 times per second) */
+    onTimeUpdate?: (currentTime: number, duration: number) => void;
 }
 /**
  * VideoPlayer component with HLS streaming support.
  * Provides video state and controls to child overlays via context.
+ *
+ * Features:
+ * - HLS streaming with automatic quality adaptation
+ * - Time-based cue points for triggering overlays
+ * - Visibility-aware playback (plays when visible, pauses when hidden)
+ * - Auto-loops in preview mode for testing
  */
-export declare function VideoPlayer({ src, autoplay, loop, muted, poster, controls, children, className, videoClassName, }: VideoPlayerProps): React.JSX.Element;
+export declare function VideoPlayer({ src, autoplay, loop: loopProp, muted, poster, controls, children, className, videoClassName, cuePoints, onCuePoint, onTimeUpdate, }: VideoPlayerProps): React.JSX.Element;
 /**
  * Hook to access video state and controls from within VideoPlayer children.
  */
 export declare function useVideoState(): VideoContextValue;
+/**
+ * Hook to trigger an action when a specific time is reached.
+ * Returns true when the video has reached or passed the specified time.
+ *
+ * @param triggerTime - Time in seconds when to trigger
+ * @param options - Configuration options
+ * @returns boolean indicating if the trigger time has been reached
+ *
+ * @example
+ * ```tsx
+ * function PollOverlay() {
+ *   const showPoll = useCuePoint(5); // Show after 5 seconds
+ *   return showPoll ? <Poll /> : null;
+ * }
+ * ```
+ */
+export declare function useCuePoint(triggerTime: number, options?: {
+    /** Reset trigger when video loops (default: true) */
+    resetOnLoop?: boolean;
+    /** Trigger once or every time the time is crossed (default: 'once') */
+    mode?: 'once' | 'every-loop';
+}): boolean;
+/**
+ * Hook to manage multiple cue points with callbacks.
+ * More flexible than useCuePoint for complex time-based interactions.
+ *
+ * @param cuePoints - Array of cue points with times and callbacks
+ * @param options - Configuration options
+ *
+ * @example
+ * ```tsx
+ * function InteractiveOverlay() {
+ *   const [showPoll, setShowPoll] = useState(false);
+ *   const [showCTA, setShowCTA] = useState(false);
+ *
+ *   useCuePoints([
+ *     { time: 5, onTrigger: () => setShowPoll(true) },
+ *     { time: 10, onTrigger: () => setShowCTA(true) },
+ *     { time: 15, onTrigger: () => { setShowPoll(false); setShowCTA(false); } },
+ *   ]);
+ *
+ *   return (
+ *     <>
+ *       {showPoll && <Poll />}
+ *       {showCTA && <CTAButton />}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export declare function useCuePoints(cuePoints: Array<{
+    /** Time in seconds when to trigger */
+    time: number;
+    /** Callback to execute when time is reached */
+    onTrigger: () => void;
+    /** Optional unique ID (defaults to index) */
+    id?: string;
+}>, options?: {
+    /** Reset triggers when video loops (default: true) */
+    resetOnLoop?: boolean;
+}): void;
+/**
+ * Hook to get the current video progress as a percentage (0-100).
+ * Useful for progress bars or time-based animations.
+ *
+ * @returns Progress percentage (0-100)
+ *
+ * @example
+ * ```tsx
+ * function ProgressBar() {
+ *   const progress = useVideoProgress();
+ *   return <div style={{ width: `${progress}%` }} className="h-1 bg-white" />;
+ * }
+ * ```
+ */
+export declare function useVideoProgress(): number;
 export {};
 //# sourceMappingURL=VideoPlayer.d.ts.map

package/dist/react/overlay/VideoPlayer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VideoPlayer.d.ts","sourceRoot":"","sources":["../../../src/react/overlay/VideoPlayer.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"VideoPlayer.d.ts","sourceRoot":"","sources":["../../../src/react/overlay/VideoPlayer.tsx"],"names":[],"mappings":"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"}

package/dist/react/overlay/VideoPlayer.js

@@ -2,13 +2,29 @@
 import React, { createContext, useContext, useEffect, useRef, useState, useCallback, } from 'react';
 import { getTileBridge } from '../../bridge/TileBridge';
 const VideoContext = createContext(null);
+// Detect if we're in preview mode (tile-preview sets this global)
+function isPreviewMode() {
+    if (typeof window === 'undefined')
+        return false;
+    return !!window.__PREVIEW_SESSION_ID__;
+}
 /**
  * VideoPlayer component with HLS streaming support.
  * Provides video state and controls to child overlays via context.
+ *
+ * Features:
+ * - HLS streaming with automatic quality adaptation
+ * - Time-based cue points for triggering overlays
+ * - Visibility-aware playback (plays when visible, pauses when hidden)
+ * - Auto-loops in preview mode for testing
  */
-export function VideoPlayer({ src, autoplay = true, loop = false, muted = true, poster, controls = false, children, className = '', videoClassName = '', }) {
+export function VideoPlayer({ src, autoplay = true, loop: loopProp, muted = true, poster, controls = false, children, className = '', videoClassName = '', cuePoints = [], onCuePoint, onTimeUpdate, }) {
     const videoRef = useRef(null);
     const hlsRef = useRef(null);
+    const triggeredCuePointsRef = useRef(new Set());
+    const lastTimeRef = useRef(0);
+    // Auto-enable loop in preview mode unless explicitly set to false
+    const loop = loopProp ?? isPreviewMode();
     const [state, setState] = useState({
         isPlaying: false,
         currentTime: 0,
@@ -125,9 +141,40 @@ export function VideoPlayer({ src, autoplay = true, loop = false, muted = true,
         const video = videoRef.current;
         if (!video)
             return;
-        const handlePlay = () => setState(s => ({ ...s, isPlaying: true }));
+        const handlePlay = () => setState(s => ({ ...s, isPlaying: true, isLoading: false }));
         const handlePause = () => setState(s => ({ ...s, isPlaying: false }));
-        const handleTimeUpdate = () => setState(s => ({ ...s, currentTime: video.currentTime }));
+        // Fallback for loading state - hide spinner when video can play
+        const handleCanPlay = () => setState(s => ({ ...s, isLoading: false }));
+        const handleLoadedData = () => setState(s => ({ ...s, isLoading: false }));
+        const handleTimeUpdate = () => {
+            const currentTime = video.currentTime;
+            const duration = video.duration;
+            setState(s => ({ ...s, currentTime }));
+            // Call onTimeUpdate callback
+            if (onTimeUpdate && !isNaN(duration)) {
+                onTimeUpdate(currentTime, duration);
+            }
+            // Check cue points - trigger if we crossed the cue time since last update
+            if (onCuePoint && cuePoints.length > 0) {
+                const lastTime = lastTimeRef.current;
+                for (const cuePoint of cuePoints) {
+                    const cueKey = `${cuePoint.id}-${Math.floor(currentTime / (duration || 1))}`;
+                    // Trigger if we crossed the cue point time (handles both forward and loop)
+                    // For looping: reset triggered cues when video loops back
+                    if (currentTime < lastTime && lastTime > duration * 0.9) {
+                        // Video looped - clear triggered cues
+                        triggeredCuePointsRef.current.clear();
+                    }
+                    const alreadyTriggered = triggeredCuePointsRef.current.has(cueKey);
+                    const crossedCuePoint = lastTime < cuePoint.time && currentTime >= cuePoint.time;
+                    if (!alreadyTriggered && crossedCuePoint) {
+                        triggeredCuePointsRef.current.add(cueKey);
+                        onCuePoint(cuePoint);
+                    }
+                }
+            }
+            lastTimeRef.current = currentTime;
+        };
         const handleDurationChange = () => setState(s => ({ ...s, duration: video.duration }));
         const handleVolumeChange = () => setState(s => ({ ...s, volume: video.volume, muted: video.muted }));
         const handleProgress = () => {
@@ -146,6 +193,8 @@ export function VideoPlayer({ src, autoplay = true, loop = false, muted = true,
         video.addEventListener('volumechange', handleVolumeChange);
         video.addEventListener('progress', handleProgress);
         video.addEventListener('error', handleError);
+        video.addEventListener('canplay', handleCanPlay);
+        video.addEventListener('loadeddata', handleLoadedData);
         return () => {
             video.removeEventListener('play', handlePlay);
             video.removeEventListener('pause', handlePause);
@@ -154,8 +203,10 @@ export function VideoPlayer({ src, autoplay = true, loop = false, muted = true,
             video.removeEventListener('volumechange', handleVolumeChange);
             video.removeEventListener('progress', handleProgress);
             video.removeEventListener('error', handleError);
+            video.removeEventListener('canplay', handleCanPlay);
+            video.removeEventListener('loadeddata', handleLoadedData);
         };
-    }, []);
+    }, [onTimeUpdate, onCuePoint, cuePoints]);
     // Visibility handling - play/pause based on tile visibility
     // Enables TikTok-style preloaded video tiles that only play when visible
     useEffect(() => {
@@ -196,7 +247,24 @@ export function VideoPlayer({ src, autoplay = true, loop = false, muted = true,
     };
     return (React.createElement(VideoContext.Provider, { value: contextValue },
         React.createElement("div", { className: `relative w-full h-full bg-black ${className}` },
-            React.createElement("video", { ref: videoRef, className: `w-full h-full object-contain ${videoClassName}`, poster: poster, loop: loop, muted: muted, controls: controls, playsInline: true }),
+            React.createElement("video", { ref: videoRef, className: `w-full h-full object-contain ${videoClassName}`, poster: poster, loop: loop, muted: muted, controls: controls, playsInline: true, 
+                // Hide iOS Safari's native poster play button
+                style: {
+                    // @ts-expect-error - WebKit-specific property
+                    WebkitMediaControlsStartPlaybackButton: 'none',
+                } }),
+            React.createElement("style", null, `
+          video::-webkit-media-controls-start-playback-button {
+            display: none !important;
+            -webkit-appearance: none;
+          }
+          video::-webkit-media-controls-panel {
+            display: none !important;
+          }
+          video::-webkit-media-controls {
+            display: none !important;
+          }
+        `),
             state.isLoading && (React.createElement("div", { className: "absolute inset-0 flex items-center justify-center" },
                 React.createElement("div", { className: "w-10 h-10 border-3 border-white/30 border-t-white rounded-full animate-spin" }))),
             state.error && (React.createElement("div", { className: "absolute inset-0 flex items-center justify-center text-white/80" },
@@ -213,3 +281,116 @@ export function useVideoState() {
     }
     return context;
 }
+/**
+ * Hook to trigger an action when a specific time is reached.
+ * Returns true when the video has reached or passed the specified time.
+ *
+ * @param triggerTime - Time in seconds when to trigger
+ * @param options - Configuration options
+ * @returns boolean indicating if the trigger time has been reached
+ *
+ * @example
+ * ```tsx
+ * function PollOverlay() {
+ *   const showPoll = useCuePoint(5); // Show after 5 seconds
+ *   return showPoll ? <Poll /> : null;
+ * }
+ * ```
+ */
+export function useCuePoint(triggerTime, options = {}) {
+    const { resetOnLoop = true, mode = 'once' } = options;
+    const { state } = useVideoState();
+    const [triggered, setTriggered] = useState(false);
+    const lastTimeRef = useRef(0);
+    useEffect(() => {
+        const { currentTime, duration } = state;
+        // Detect video loop (time jumped backwards significantly)
+        if (currentTime < lastTimeRef.current && lastTimeRef.current > duration * 0.9) {
+            if (resetOnLoop && mode === 'every-loop') {
+                setTriggered(false);
+            }
+        }
+        // Check if we crossed the trigger time
+        if (!triggered && currentTime >= triggerTime) {
+            setTriggered(true);
+        }
+        lastTimeRef.current = currentTime;
+    }, [state.currentTime, state.duration, triggerTime, triggered, resetOnLoop, mode]);
+    return triggered;
+}
+/**
+ * Hook to manage multiple cue points with callbacks.
+ * More flexible than useCuePoint for complex time-based interactions.
+ *
+ * @param cuePoints - Array of cue points with times and callbacks
+ * @param options - Configuration options
+ *
+ * @example
+ * ```tsx
+ * function InteractiveOverlay() {
+ *   const [showPoll, setShowPoll] = useState(false);
+ *   const [showCTA, setShowCTA] = useState(false);
+ *
+ *   useCuePoints([
+ *     { time: 5, onTrigger: () => setShowPoll(true) },
+ *     { time: 10, onTrigger: () => setShowCTA(true) },
+ *     { time: 15, onTrigger: () => { setShowPoll(false); setShowCTA(false); } },
+ *   ]);
+ *
+ *   return (
+ *     <>
+ *       {showPoll && <Poll />}
+ *       {showCTA && <CTAButton />}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function useCuePoints(cuePoints, options = {}) {
+    const { resetOnLoop = true } = options;
+    const { state } = useVideoState();
+    const triggeredRef = useRef(new Set());
+    const lastTimeRef = useRef(0);
+    useEffect(() => {
+        const { currentTime, duration } = state;
+        // Detect video loop
+        if (currentTime < lastTimeRef.current && lastTimeRef.current > duration * 0.9) {
+            if (resetOnLoop) {
+                triggeredRef.current.clear();
+            }
+        }
+        // Check each cue point
+        for (let i = 0; i < cuePoints.length; i++) {
+            const cue = cuePoints[i];
+            const cueId = cue.id ?? `cue-${i}`;
+            const alreadyTriggered = triggeredRef.current.has(cueId);
+            const crossedTime = lastTimeRef.current < cue.time && currentTime >= cue.time;
+            if (!alreadyTriggered && crossedTime) {
+                triggeredRef.current.add(cueId);
+                cue.onTrigger();
+            }
+        }
+        lastTimeRef.current = currentTime;
+    }, [state.currentTime, state.duration, cuePoints, resetOnLoop]);
+}
+/**
+ * Hook to get the current video progress as a percentage (0-100).
+ * Useful for progress bars or time-based animations.
+ *
+ * @returns Progress percentage (0-100)
+ *
+ * @example
+ * ```tsx
+ * function ProgressBar() {
+ *   const progress = useVideoProgress();
+ *   return <div style={{ width: `${progress}%` }} className="h-1 bg-white" />;
+ * }
+ * ```
+ */
+export function useVideoProgress() {
+    const { state } = useVideoState();
+    const { currentTime, duration } = state;
+    if (!duration || duration === 0)
+        return 0;
+    return Math.min(100, (currentTime / duration) * 100);
+}

package/dist/react/overlay/index.d.ts

@@ -1,5 +1,5 @@
-export { VideoPlayer, useVideoState, } from './VideoPlayer';
-export type { VideoState, VideoControls, VideoContextValue, VideoPlayerProps, } from './VideoPlayer';
+export { VideoPlayer, useVideoState, useCuePoint, useCuePoints, useVideoProgress, } from './VideoPlayer';
+export type { VideoState, VideoControls, VideoContextValue, VideoPlayerProps, CuePoint, } from './VideoPlayer';
 export { Slideshow, useSlideshowState, } from './Slideshow';
 export type { SlideImage, SlideshowState, SlideshowControls, SlideshowContextValue, SlideshowProps, } from './Slideshow';
 export { OverlaySlot, FullOverlay, GradientOverlay, } from './OverlaySlot';

package/dist/react/overlay/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/overlay/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,WAAW,EACX,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,SAAS,EACT,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,GACf,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,WAAW,EACX,WAAW,EACX,eAAe,GAChB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/overlay/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,WAAW,EACX,aAAa,EACb,WAAW,EACX,YAAY,EACZ,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,QAAQ,GACT,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,SAAS,EACT,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,GACf,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,WAAW,EACX,WAAW,EACX,eAAe,GAChB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,eAAe,CAAC"}

package/dist/react/overlay/index.js

@@ -1,5 +1,5 @@
 // Video player with HLS streaming support
-export { VideoPlayer, useVideoState, } from './VideoPlayer';
+export { VideoPlayer, useVideoState, useCuePoint, useCuePoints, useVideoProgress, } from './VideoPlayer';
 // Image slideshow component
 export { Slideshow, useSlideshowState, } from './Slideshow';
 // Overlay positioning components

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thewhateverapp/tile-sdk",
-  "version": "0.11.2",
+  "version": "0.12.1",
   "description": "SDK for building interactive tiles on The Whatever App platform",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",