ebta-workflow-prod 4.1.6 → 4.1.8

package/src/elements/PanovideoPlayer.tsx

@@ -1,7 +1,25 @@
+/** @jsxRuntime classic */
 import * as React from "react";
 import { FormElementProps, FormElementRegistration } from "@vertigis/workflow";
 import Marzipano from "marzipano";
+const M: any = Marzipano;
 
+function logPanovideo(message: string, details?: unknown): void {
+    if (details === undefined) {
+        console.log(`[PanovideoPlayer] ${message}`);
+    } else {
+        console.log(`[PanovideoPlayer] ${message}`, details);
+    }
+}
+
+logPanovideo("module loaded", { marzipanoAvailable: Boolean(M) });
+
+export interface VideoResolution {
+    /** Display label for this source. */
+    label: string;
+    /** URL of the equirectangular video. Must be served with CORS headers. */
+    url: string;
+}
 
 /**
  * The generic type argument provided to `FormElementProps<T>` controls the type
@@ -13,213 +31,822 @@ import Marzipano from "marzipano";
  * runtime, and passed in as `props`. You can update the properties by using
  * `props.setProperty(key, value)`.
  */
-interface PanovideoPlayerProps extends FormElementProps<string> {}
+interface PanovideoPlayerProps extends FormElementProps<string> {
+    /** URL of the equirectangular video. Takes priority over `resolutions`. */
+    value: string;
+    /** Fallback list of sources. The first entry is used when `value` is empty. */
+    resolutions?: VideoResolution[];
+    /** Start playing automatically (muted autoplay is allowed by browsers). */
+    autoplay?: boolean;
+    /**
+     * How far past 1:1 video pixels the user can zoom in.
+     * 1 = native resolution only, 3 = up to 3x magnified.
+     */
+    maxZoom?: number;
+}
 
-class VideoAsset extends (Marzipano as any).util.Emitter {
-    private _element: HTMLVideoElement;
+/* -------------------------------------------------------------------------- */
+/* VideoAsset (equivalent of the demo's VideoAsset.js)                        */
+/*                                                                            */
+/* A Marzipano dynamic asset that exposes the current video frame.            */
+/* -------------------------------------------------------------------------- */
 
-    constructor(videoElement: HTMLVideoElement) {
-        super();
-        this._element = videoElement;
-        // Marzipano polls isDynamic()/emits('change') to know when to redraw.
-        this._element.addEventListener("timeupdate", () => {
-            this.emit("change");
-        });
-    }
+interface VideoAsset {
+    emit(eventName: string): void;
+}
 
-    element(): HTMLVideoElement {
-        return this._element;
+class VideoAsset {
+    private el: HTMLVideoElement;
+    private destroyed = false;
+    private lastTime = -1;
+    private stamp = 0;
+    private raf = 0;
+    private readonly emptyCanvas: HTMLCanvasElement;
+
+    constructor(el: HTMLVideoElement) {
+        logPanovideo("VideoAsset.constructor: start", { src: el.currentSrc || el.src });
+        this.el = el;
+        this.emptyCanvas = document.createElement("canvas");
+        this.emptyCanvas.width = 1;
+        this.emptyCanvas.height = 1;
+        this.loop();
+        logPanovideo("VideoAsset.constructor: complete");
     }
 
     width(): number {
-        return this._element.videoWidth;
+        return this.el.videoWidth || 1;
     }
 
     height(): number {
-        return this._element.videoHeight;
+        return this.el.videoHeight || 1;
+    }
+
+    element(): HTMLVideoElement | HTMLCanvasElement {
+        // Until a frame is available, hand WebGL a 1x1 canvas instead.
+        return this.el.readyState >= 2 ? this.el : this.emptyCanvas;
     }
 
     isDynamic(): boolean {
         return true;
     }
+
+    timestamp(): number {
+        return this.stamp;
+    }
+
+    destroy(): void {
+        logPanovideo("VideoAsset.destroy: start");
+        this.destroyed = true;
+        cancelAnimationFrame(this.raf);
+        logPanovideo("VideoAsset.destroy: complete");
+    }
+
+    private loop = (): void => {
+        if (this.destroyed) {
+            logPanovideo("VideoAsset.loop: stopped; asset destroyed");
+            return;
+        }
+        const t = this.el.currentTime;
+        if (t !== this.lastTime) {
+            this.lastTime = t;
+            this.stamp++;
+            this.emit("change");
+        }
+        this.raf = requestAnimationFrame(this.loop);
+    };
 }
+M.dependencies.eventEmitter(VideoAsset);
+
+/* -------------------------------------------------------------------------- */
+/* Video loading helper                                                       */
+/* -------------------------------------------------------------------------- */
+
+function createVideo(url: string, muted: boolean): HTMLVideoElement {
+    logPanovideo("createVideo: start", { url, muted });
+    const v = document.createElement("video");
+    v.crossOrigin = "anonymous"; // required to use the video as a WebGL texture
+    v.loop = true;
+    v.muted = muted;
+    v.preload = "auto";
+    v.playsInline = true;
+    // Prevent iOS from forcing fullscreen playback.
+    v.setAttribute("playsinline", "");
+    v.setAttribute("webkit-playsinline", "");
+    v.src = url;
+    v.load();
+    logPanovideo("createVideo: complete", { src: v.src, readyState: v.readyState });
+    return v;
+}
+
+function disposeVideo(v: HTMLVideoElement): void {
+    logPanovideo("disposeVideo: start", { src: v.currentSrc || v.src, readyState: v.readyState });
+    v.pause();
+    v.removeAttribute("src");
+    v.load();
+    logPanovideo("disposeVideo: complete");
+}
+
+function formatTime(seconds: number): string {
+    const wholeSeconds = Number.isFinite(seconds) ? Math.max(0, Math.floor(seconds)) : 0;
+    const minutes = Math.floor(wholeSeconds / 60);
+    const remainingSeconds = wholeSeconds % 60;
+    return `${String(minutes).padStart(2, "0")}:${String(remainingSeconds).padStart(2, "0")}`;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Constants and styles                                                       */
+/* -------------------------------------------------------------------------- */
+
+const DEFAULT_RESOLUTIONS: VideoResolution[] = [
+    // The first source is used by the player when `value` is empty.
+    { label: "1280x640", url: "//win11assets.blob.core.windows.net/playbookicon/260917_BR120.mp4" },
+];
+
+/** Widest vertical field of view the user can zoom out to. */
+const MAX_VFOV = (120 * Math.PI) / 180;
+/** Field of view the player starts with. */
+const INITIAL_FOV = (90 * Math.PI) / 180;
+/** Each zoom click / key press multiplies the FOV by these factors. */
+const ZOOM_IN_FACTOR = 0.8;
+const ZOOM_OUT_FACTOR = 1.25;
+/** Wheel sensitivity. FOV is multiplied by exp(deltaY * WHEEL_SENSITIVITY). */
+const WHEEL_SENSITIVITY = 0.001;
+/** Permissive limiter used until the real video size is known. */
+const PLACEHOLDER_MAX_RESOLUTION = 4096 * 4;
+
+const SPEED_OPTIONS = [0.5, 0.75, 1, 1.25, 1.5];
+
+const loadingOverlayStyle: React.CSSProperties = {
+    position: "absolute",
+    inset: 0,
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: 12,
+    background: "transparent",
+    color: "#fff",
+    fontSize: 14,
+    fontWeight: 600,
+    textShadow: "0 1px 4px rgba(0,0,0,0.9)",
+    zIndex: 5,
+    pointerEvents: "none",
+};
+
+const spinnerStyle: React.CSSProperties = {
+    width: 44,
+    height: 44,
+    borderRadius: "50%",
+    border: "4px solid rgba(255,255,255,0.35)",
+    borderTopColor: "#fff",
+    filter: "drop-shadow(0 1px 4px rgba(0,0,0,0.8))",
+    animation: "panovideo-spin 0.9s linear infinite",
+};
+
+
+const barStyle: React.CSSProperties = {
+    position: "absolute",
+    left: 8,
+    right: 8,
+    bottom: 8,
+    display: "flex",
+    gap: 8,
+    alignItems: "center",
+    minWidth: 0,
+    padding: "6px 8px",
+    background: "rgba(0,0,0,0.55)",
+    borderRadius: 4,
+    color: "#fff",
+    fontSize: 13,
+};
+
+const btnStyle: React.CSSProperties = {
+    background: "transparent",
+    border: "1px solid rgba(255,255,255,0.6)",
+    borderRadius: 3,
+    color: "#fff",
+    cursor: "pointer",
+    minWidth: 32,
+    height: 28,
+};
+
+
+const speedStyle: React.CSSProperties = {
+    ...btnStyle,
+    background: "rgba(0,0,0,0.55)",
+    padding: "0 4px",
+};
+
+const zoomControlsStyle: React.CSSProperties = {
+    position: "absolute",
+    top: 8,
+    left: 8,
+    display: "flex",
+    flexDirection: "column",
+    gap: 6,
+    zIndex: 10000,
+    pointerEvents: "auto",
+};
+
+const zoomBtnStyle: React.CSSProperties = {
+    ...btnStyle,
+    width: 34,
+    height: 34,
+    fontSize: 20,
+    fontWeight: 600,
+    background: "rgba(0,0,0,0.55)",
+};
+
+const timelineStyle: React.CSSProperties = {
+    flex: "1 1 auto",
+    minWidth: 40,
+    height: 20,
+    cursor: "pointer",
+};
+
+const timeStyle: React.CSSProperties = {
+    whiteSpace: "nowrap",
+    fontVariantNumeric: "tabular-nums",
+};
+
+/* -------------------------------------------------------------------------- */
+/* Component                                                                  */
+/* -------------------------------------------------------------------------- */
 
 /**
- * A Workflow element built using React.
+ * A Workflow element built using React
  * @displayName PanovideoPlayer
  * @description Marzipano library panoramic video player
  * @param props The props that will be provided by the Workflow runtime.
  */
 function PanovideoPlayer(props: PanovideoPlayerProps): React.ReactElement {
-    const { setValue, value } = props;
-
-    const containerRef = React.useRef<HTMLDivElement | null>(null);
-    const videoElRef = React.useRef<HTMLVideoElement | null>(null);
+    const { value, resolutions = DEFAULT_RESOLUTIONS, autoplay = true, maxZoom = 3, raiseEvent } = props;
+    const sourceUrl = value || resolutions[0]?.url;
+
+    logPanovideo("component render: start", {
+        sourceUrl,
+        resolutionsCount: resolutions.length,
+        autoplay,
+        maxZoom,
+        hasSetValue: typeof props.setValue === "function",
+    });
+
+    const playerRef = React.useRef<HTMLDivElement>(null);
+    const containerRef = React.useRef<HTMLDivElement>(null);
     const viewerRef = React.useRef<any>(null);
-    const [isPlaying, setIsPlaying] = React.useState(false);
-    const [error, setError] = React.useState<string | null>(null);
+    const viewRef = React.useRef<any>(null);
+    const assetRef = React.useRef<VideoAsset | null>(null);
+    const videoRef = React.useRef<HTMLVideoElement | null>(null);
+
+    // Latest prop values for use inside effects that must not re-run on change.
+    const maxZoomRef = React.useRef(maxZoom);
+    maxZoomRef.current = maxZoom;
+    const autoplayRef = React.useRef(autoplay);
+    autoplayRef.current = autoplay;
+    const raiseEventRef = React.useRef(raiseEvent);
+    raiseEventRef.current = raiseEvent;
+
+    const [playing, setPlaying] = React.useState(false);
+    const [muted, setMuted] = React.useState(true);
+    const [isFullscreen, setIsFullscreen] = React.useState(false);
+    const [currentTime, setCurrentTime] = React.useState(0);
+    const [duration, setDuration] = React.useState(0);
+    const [error, setError] = React.useState<string>();
+
+    const [loading, setLoading] = React.useState(true);
+    const [loadPercent, setLoadPercent] = React.useState(0);
+    const [playbackRate, setPlaybackRate] = React.useState(1);
+    const playbackRateRef = React.useRef(1);
+
+    /* ---- zoom limit, derived from the real video resolution ---- */
+    const applyZoomLimit = (reason: string) => {
+        const view = viewRef.current;
+        const video = videoRef.current;
+        if (!view || !video || !video.videoWidth) {
+            logPanovideo("applyZoomLimit: skipped", {
+                reason,
+                hasView: Boolean(view),
+                hasVideo: Boolean(video),
+                videoWidth: video?.videoWidth,
+            });
+            return;
+        }
+        const effectiveWidth = video.videoWidth * Math.max(1, maxZoomRef.current);
+        view.setLimiter(M.RectilinearView.limit.traditional(effectiveWidth, MAX_VFOV));
+        // Re-clamp the current FOV under the new limiter.
+        view.setFov(Math.min(INITIAL_FOV, view.fov()));
+        logPanovideo("applyZoomLimit: complete", {
+            reason,
+            videoWidth: video.videoWidth,
+            videoHeight: video.videoHeight,
+            maxZoom: maxZoomRef.current,
+            effectiveWidth,
+            fovDeg: (view.fov() * 180) / Math.PI,
+        });
+    };
+
+    React.useEffect(() => {
+        logPanovideo("fullscreen effect: start");
+        const onFullscreenChange = () => {
+            const fullscreen = document.fullscreenElement === playerRef.current;
+            logPanovideo("fullscreen event: changed", { fullscreen });
+            setIsFullscreen(fullscreen);
+        };
+        document.addEventListener("fullscreenchange", onFullscreenChange);
+        logPanovideo("fullscreen effect: complete");
+        return () => {
+            logPanovideo("fullscreen effect cleanup: start");
+            document.removeEventListener("fullscreenchange", onFullscreenChange);
+            logPanovideo("fullscreen effect cleanup: complete");
+        };
+    }, []);
 
-    // (Re)builds the Marzipano viewer whenever the video URL (props.value) changes.
     React.useEffect(() => {
-        if (!value || !containerRef.current) {
+        const container = containerRef.current;
+        if (!container) {
             return undefined;
         }
 
-        setError(null);
+        const resizeViewer = (reason: string) => {
+            const viewer = viewerRef.current;
+            if (!viewer) {
+                return;
+            }
+            logPanovideo("resize: updating Marzipano size", {
+                reason,
+                fullscreen: isFullscreen,
+                width: container.clientWidth,
+                height: container.clientHeight,
+            });
+            viewer.updateSize();
+        };
 
-        // Create a hidden video element to drive the panorama. We don't
-        // attach it to the DOM directly - Marzipano reads frames from it
-        // and draws them into its own WebGL canvas.
-        const videoEl = document.createElement("video");
-        videoEl.crossOrigin = "anonymous";
-        videoEl.loop = true;
-        videoEl.muted = true; // required for autoplay in most browsers
-        videoEl.playsInline = true;
-        videoEl.src = value;
-        videoElRef.current = videoEl;
+        // Fires whenever the container's real size changes, including the end of the fullscreen transition.
+        const observer = new ResizeObserver(() => resizeViewer("ResizeObserver"));
+        observer.observe(container);
 
-        let viewer: any;
-        let cancelled = false;
+        // Backup: re-measure over two frames after the fullscreen state flips.
+        let frame2 = 0;
+        const frame1 = requestAnimationFrame(() => {
+            resizeViewer("fullscreen frame 1");
+            frame2 = requestAnimationFrame(() => resizeViewer("fullscreen frame 2"));
+        });
 
-        const onLoadedMetadata = () => {
-            if (cancelled || !containerRef.current) {
+        return () => {
+            observer.disconnect();
+            cancelAnimationFrame(frame1);
+            cancelAnimationFrame(frame2);
+        };
+    }, [isFullscreen]);
+
+    React.useEffect(() => {
+        logPanovideo("wheel effect: start");
+        const player = playerRef.current;
+        if (!player) {
+            return undefined;
+        }
+        const onWheel = (event: WheelEvent) => {
+            const view = viewRef.current;
+            if (!view || event.deltaY === 0) {
                 return;
             }
+            const deltaMultiplier = event.deltaMode === 1 ? 20 : event.deltaMode === 2 ? player.clientHeight : 1;
+            event.preventDefault();
+            const previousFov = view.fov();
+            // Proportional zoom: the same wheel travel feels the same at any FOV.
+            view.setFov(previousFov * Math.exp(event.deltaY * deltaMultiplier * WHEEL_SENSITIVITY));
+            logPanovideo("wheel: zoom", { deltaY: event.deltaY, previousFov, nextFov: view.fov() });
+        };
+        player.addEventListener("wheel", onWheel, { passive: false });
+        logPanovideo("wheel effect: complete");
+        return () => {
+            logPanovideo("wheel effect cleanup");
+            player.removeEventListener("wheel", onWheel);
+        };
+    }, []);
 
-            try {
-                viewer = new (Marzipano as any).Viewer(containerRef.current);
-                viewerRef.current = viewer;
-
-                const asset = new VideoAsset(videoEl);
-                const source = (Marzipano as any).SingleAssetSource.fromAsset(asset);
-
-                const geometry = new (Marzipano as any).EquirectGeometry([
-                    { width: videoEl.videoWidth || 1920 },
-                ]);
-
-                const limiter = (Marzipano as any).RectilinearView.limit.traditional(
-                    1024,
-                    (100 * Math.PI) / 180
-                );
-                const view = new (Marzipano as any).RectilinearView(
-                    { yaw: 0, pitch: 0, fov: Math.PI / 2 },
-                    limiter
-                );
-
-                const scene = viewer.createScene({
-                    source,
-                    geometry,
-                    view,
-                    pinFirstLevel: true,
-                });
-
-                scene.switchTo();
-
-                videoEl
-                    .play()
-                    .then(() => setIsPlaying(true))
-                    .catch(() => {
-                        // Autoplay was blocked - user needs to tap play.
-                        setIsPlaying(false);
-                    });
-            } catch (e) {
-                setError(
-                    e instanceof Error ? e.message : "Failed to initialize panoramic video."
-                );
-            }
+    /* ---- 1. create the Marzipano viewer and view once ---- */
+    React.useEffect(() => {
+        logPanovideo("viewer effect: start");
+        const container = containerRef.current;
+        if (!container) {
+            logPanovideo("viewer effect: skipped; no container");
+            return undefined;
+        }
+
+        logPanovideo("viewer effect: creating Marzipano viewer");
+        const viewer = new M.Viewer(container, { controls: { scrollZoom: false } });
+        logPanovideo("viewer effect: viewer created");
+
+        // Permissive limiter for now; the real one is applied once the video
+        // reports its dimensions (see applyZoomLimit).
+        const limiter = M.RectilinearView.limit.traditional(PLACEHOLDER_MAX_RESOLUTION, MAX_VFOV);
+        const view = new M.RectilinearView({ yaw: Math.PI, fov: INITIAL_FOV }, limiter);
+        logPanovideo("viewer effect: view created", { fovDeg: (view.fov() * 180) / Math.PI });
+
+        viewerRef.current = viewer;
+        viewRef.current = view;
+        logPanovideo("viewer effect: complete");
+
+        return () => {
+            logPanovideo("viewer effect cleanup: start");
+            viewer.destroy();
+            viewerRef.current = null;
+            viewRef.current = null;
+            logPanovideo("viewer effect cleanup: complete");
         };
+    }, []);
 
-        const onVideoError = () => {
-            if (!cancelled) {
-                setError("Unable to load video from the provided URL.");
-            }
+    /* ---- 2. create the video and scene; rebuilt whenever the source URL changes ---- */
+    React.useEffect(() => {
+        logPanovideo("video effect: start", { sourceUrl });
+        const viewer = viewerRef.current;
+        const view = viewRef.current;
+        if (!viewer || !view || !sourceUrl) {
+            logPanovideo("video effect: skipped", {
+                hasViewer: Boolean(viewer),
+                hasView: Boolean(view),
+                sourceUrl,
+            });
+            return undefined;
+        }
+
+        setError(undefined);
+        setCurrentTime(0);
+        setDuration(0);
+        setLoading(true);
+setLoadPercent(0);
+
+        logPanovideo("video effect: creating video", { sourceUrl });
+        const video = createVideo(sourceUrl, videoRef.current?.muted ?? true);
+        videoRef.current = video;
+        setMuted(video.muted);
+        video.defaultPlaybackRate = playbackRateRef.current;
+video.playbackRate = playbackRateRef.current;
+
+        const onPlay = () => {
+            logPanovideo("video event: play", { src: video.currentSrc || video.src });
+            setPlaying(true);
+        };
+        const onPause = () => {
+            logPanovideo("video event: pause", { src: video.currentSrc || video.src });
+            setPlaying(false);
+        };
+        const onError = () => {
+            setLoading(false);
+            logPanovideo("video event: error", { src: video.currentSrc || video.src, error: video.error });
+            setError(`Unable to load ${video.src}`);
         };
 
-        videoEl.addEventListener("loadedmetadata", onLoadedMetadata);
-        videoEl.addEventListener("error", onVideoError);
+        const onWaiting = () => {
+    logPanovideo("video event: waiting (buffering)");
+    setLoading(true);
+};
+const onReady = () => {
+    logPanovideo("video event: ready to play", { readyState: video.readyState });
+    setLoading(false);
+};
+const onProgress = () => {
+    if (!Number.isFinite(video.duration) || video.duration <= 0 || video.buffered.length === 0) {
+        return;
+    }
+    const bufferedEnd = video.buffered.end(video.buffered.length - 1);
+    setLoadPercent(Math.min(100, Math.round((bufferedEnd / video.duration) * 100)));
+};
+        const updateTimeline = () => {
+            setCurrentTime(video.currentTime);
+            setDuration(Number.isFinite(video.duration) ? video.duration : 0);
+        };
+        const onLoadedMetadata = () => {
+            logPanovideo("video event: loadedmetadata", {
+                videoWidth: video.videoWidth,
+                videoHeight: video.videoHeight,
+                duration: video.duration,
+            });
+            updateTimeline();
+            applyZoomLimit("loadedmetadata");
+            try {
+                raiseEventRef.current("loaded" as any, sourceUrl);
+            } catch (raiseError) {
+                logPanovideo("video event: raiseEvent(loaded) failed", raiseError);
+            }
+        };
+        video.addEventListener("play", onPlay);
+        video.addEventListener("pause", onPause);
+        video.addEventListener("error", onError);
+        video.addEventListener("timeupdate", updateTimeline);
+        video.addEventListener("durationchange", updateTimeline);
+        video.addEventListener("loadedmetadata", onLoadedMetadata);
+        video.addEventListener("seeked", updateTimeline);
+        video.addEventListener("waiting", onWaiting);
+video.addEventListener("canplay", onReady);
+video.addEventListener("playing", onReady);
+video.addEventListener("progress", onProgress);
+
+        const asset = new VideoAsset(video);
+        logPanovideo("video effect: asset created");
+        const source = new M.SingleAssetSource(asset);
+        logPanovideo("video effect: source created");
+        const geometry = new M.EquirectGeometry([{ width: 1 }]);
+        logPanovideo("video effect: geometry created");
+
+        logPanovideo("video effect: creating scene");
+        // The view is reused so camera direction and zoom survive a source swap.
+        const scene = viewer.createScene({ source, geometry, view, pinFirstLevel: true });
+        logPanovideo("video effect: switching to scene");
+        scene.switchTo();
+        assetRef.current = asset;
+
+        if (autoplayRef.current) {
+            logPanovideo("video effect: attempting autoplay");
+            void video.play().then(
+                () => logPanovideo("video effect: autoplay started"),
+                (playError: unknown) => logPanovideo("video effect: autoplay rejected", playError),
+            );
+        } else {
+            logPanovideo("video effect: autoplay disabled");
+        }
+        logPanovideo("video effect: complete");
 
         return () => {
-            cancelled = true;
-            videoEl.removeEventListener("loadedmetadata", onLoadedMetadata);
-            videoEl.removeEventListener("error", onVideoError);
-            videoEl.pause();
-            videoEl.removeAttribute("src");
-            videoEl.load();
-
-            if (viewerRef.current) {
+            logPanovideo("video effect cleanup: start");
+            video.removeEventListener("play", onPlay);
+            video.removeEventListener("pause", onPause);
+            video.removeEventListener("error", onError);
+            video.removeEventListener("timeupdate", updateTimeline);
+            video.removeEventListener("durationchange", updateTimeline);
+            video.removeEventListener("loadedmetadata", onLoadedMetadata);
+            video.removeEventListener("seeked", updateTimeline);
+            video.removeEventListener("waiting", onWaiting);
+video.removeEventListener("canplay", onReady);
+video.removeEventListener("playing", onReady);
+video.removeEventListener("progress", onProgress);
+            asset.destroy();
+            // On unmount the viewer effect cleanup has already destroyed the viewer.
+            if (viewerRef.current === viewer) {
                 try {
-                    // Not all Marzipano versions expose destroy(); guard defensively.
-                    viewerRef.current.destroy?.();
-                } catch {
-                    // no-op
+                    viewer.destroyScene(scene);
+                } catch (sceneError) {
+                    logPanovideo("video effect cleanup: destroyScene failed", sceneError);
                 }
-                viewerRef.current = null;
             }
-
-            if (containerRef.current) {
-                containerRef.current.innerHTML = "";
+            disposeVideo(video);
+            if (videoRef.current === video) {
+                videoRef.current = null;
+            }
+            if (assetRef.current === asset) {
+                assetRef.current = null;
             }
+            logPanovideo("video effect cleanup: complete");
         };
-    }, [value]);
+        // Rebuilt only when the source URL changes. Other props are read via refs.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [sourceUrl]);
 
-    const togglePlayback = () => {
-        const videoEl = videoElRef.current;
-        if (!videoEl) {
+    /* ---- re-apply the zoom limit when `maxZoom` changes at runtime ---- */
+    React.useEffect(() => {
+        logPanovideo("maxZoom effect", { maxZoom });
+        applyZoomLimit("maxZoom changed");
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [maxZoom]);
+
+    /* ---- controls ---- */
+    const togglePlay = () => {
+        logPanovideo("togglePlay: start");
+        const v = videoRef.current;
+        if (!v) {
+            logPanovideo("togglePlay: skipped; no video");
             return;
         }
-        if (videoEl.paused) {
-            videoEl.play().then(() => setIsPlaying(true));
+        if (v.paused) {
+            logPanovideo("togglePlay: requesting playback", { src: v.currentSrc || v.src });
+            void v.play().then(
+                () => logPanovideo("togglePlay: playback started"),
+                (playError: unknown) => logPanovideo("togglePlay: playback rejected", playError),
+            );
         } else {
-            videoEl.pause();
-            setIsPlaying(false);
+            logPanovideo("togglePlay: pausing playback", { currentTime: v.currentTime });
+            v.pause();
         }
+        logPanovideo("togglePlay: complete");
     };
 
-    return (
-        <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
-            <input
-                type="text"
-                placeholder="Enter 360° equirectangular video URL"
-                onChange={(event) => setValue(event.currentTarget.value)}
-                value={value ?? ""}
-                style={{ width: "100%" }}
-            />
+    const toggleMute = () => {
+        logPanovideo("toggleMute: start");
+        const v = videoRef.current;
+        if (!v) {
+            logPanovideo("toggleMute: skipped; no video");
+            return;
+        }
+        v.muted = !v.muted;
+        setMuted(v.muted);
+        logPanovideo("toggleMute: complete", { muted: v.muted });
+    };
 
-            {error && (
-                <div style={{ color: "red", fontSize: 12 }}>{error}</div>
-            )}
+    const changeSpeed = (rate: number) => {
+    logPanovideo("changeSpeed", { rate });
+    playbackRateRef.current = rate;
+    setPlaybackRate(rate);
+    const v = videoRef.current;
+    if (v) {
+        v.defaultPlaybackRate = rate;
+        v.playbackRate = rate;
+    }
+};
+
+    const adjustZoom = (direction: "in" | "out") => {
+        const view = viewRef.current;
+        if (!view) {
+            logPanovideo("adjustZoom: skipped; no view", { direction });
+            return;
+        }
+        const previousFov = view.fov();
+        // Proportional step; setFov passes through the limiter, so min/max are enforced.
+        view.setFov(previousFov * (direction === "in" ? ZOOM_IN_FACTOR : ZOOM_OUT_FACTOR));
+        logPanovideo("adjustZoom: complete", {
+            direction,
+            previousFov,
+            nextFov: view.fov(),
+            nextFovDeg: (view.fov() * 180) / Math.PI,
+        });
+    };
+
+    const seekTo = (time: number) => {
+        const video = videoRef.current;
+        if (!video || !Number.isFinite(video.duration)) {
+            return;
+        }
+        const nextTime = Math.max(0, Math.min(time, video.duration));
+        video.currentTime = nextTime;
+        setCurrentTime(nextTime);
+    };
+
+    const toggleFullscreen = async () => {
+        logPanovideo("toggleFullscreen: start", { isFullscreen });
+        const player = playerRef.current;
+        if (!player) {
+            logPanovideo("toggleFullscreen: skipped; no player element");
+            return;
+        }
+        try {
+            if (document.fullscreenElement === player) {
+                await document.exitFullscreen();
+            } else {
+                await player.requestFullscreen();
+            }
+            logPanovideo("toggleFullscreen: request complete");
+        } catch (fullscreenError) {
+            logPanovideo("toggleFullscreen: request failed", fullscreenError);
+            setError("Fullscreen is unavailable in this browser or context.");
+        }
+    };
+
+    const handlePlayerKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+        if (event.repeat) {
+            return;
+        }
+        const target = event.target;
+        const isTextEntry =
+            target instanceof HTMLElement &&
+            (target.isContentEditable || target.closest("input, select, textarea, [contenteditable='true']"));
+        if (isTextEntry) {
+            return;
+        }
+        if (event.key === "+" || event.key === "=") {
+            event.preventDefault();
+            adjustZoom("in");
+            return;
+        }
+        if (event.key === "-" || event.key === "_") {
+            event.preventDefault();
+            adjustZoom("out");
+            return;
+        }
+        if (event.code !== "Space") {
+            return;
+        }
+        if (target instanceof HTMLElement && target.closest("button")) {
+            return;
+        }
+        event.preventDefault();
+        logPanovideo("keyboard: Space pressed; toggling playback");
+        togglePlay();
+    };
 
-            {value && (
-                <div style={{ position: "relative" }}>
-                    <div
-                        ref={containerRef}
-                        style={{
-                            width: "100%",
-                            height: 400,
-                            background: "#000",
-                        }}
-                    />
-                    <button
-                        type="button"
-                        onClick={togglePlayback}
-                        style={{
-                            position: "absolute",
-                            bottom: 8,
-                            left: 8,
-                        }}
-                    >
-                        {isPlaying ? "Pause" : "Play"}
-                    </button>
+    const playerStyle: React.CSSProperties = isFullscreen
+        ? {
+            position: "fixed",
+            inset: 0,
+            width: "100vw",
+            height: "100vh",
+            background: "#000",
+            zIndex: 9999,
+        }
+        : {
+            position: "relative",
+            width: "100%",
+            aspectRatio: "2 / 1",
+            background: "#000",
+        };
+
+    const element = (
+        <div
+            ref={playerRef}
+            style={playerStyle}
+            role="region"
+            aria-label="Panoramic video player"
+            tabIndex={0}
+            onKeyDown={handlePlayerKeyDown}
+        >
+            <div ref={containerRef} style={{ position: "absolute", inset: 0 }} />
+<style>{`@keyframes panovideo-spin { to { transform: rotate(360deg); } }`}</style>
+
+{loading && !error && (
+    <div style={loadingOverlayStyle} role="status" aria-live="polite">
+        <div style={spinnerStyle} />
+        <span>Loading video{loadPercent > 0 ? `… ${loadPercent}%` : "…"}</span>
+    </div>
+)}
+            <div style={zoomControlsStyle}>
+                <button type="button" style={zoomBtnStyle} onClick={() => adjustZoom("in")} title="Zoom in" aria-label="Zoom in">
+                    +
+                </button>
+                <button type="button" style={zoomBtnStyle} onClick={() => adjustZoom("out")} title="Zoom out" aria-label="Zoom out">
+                    −
+                </button>
+            </div>
+
+            <div style={barStyle}>
+                <button type="button" style={btnStyle} onClick={togglePlay} title="Play / pause">
+                    {playing ? "⏸" : "▶"}
+                </button>
+                {/* <button type="button" style={btnStyle} onClick={toggleMute} title="Sound on / off">
+                    {muted ? "🔇" : "🔊"}
+                </button> */}
+                <select
+    style={speedStyle}
+    value={playbackRate}
+    onChange={(event) => changeSpeed(Number(event.currentTarget.value))}
+    title="Playback speed"
+    aria-label="Playback speed"
+>
+    {SPEED_OPTIONS.map((rate) => (
+        <option key={rate} value={rate} style={{ color: "#000" }}>
+            {rate}x
+        </option>
+    ))}
+</select>
+                <span style={timeStyle} aria-live="off">
+                    {formatTime(currentTime)} / {formatTime(duration)}
+                </span>
+                <input
+                    type="range"
+                    min={0}
+                    max={duration}
+                    step={0.1}
+                    value={Math.min(currentTime, duration)}
+                    disabled={duration <= 0}
+                    onChange={(event) => seekTo(Number(event.currentTarget.value))}
+                    style={timelineStyle}
+                    aria-label="Video progress"
+                    aria-valuetext={`${formatTime(currentTime)} of ${formatTime(duration)}`}
+                />
+                <button
+                    type="button"
+                    style={btnStyle}
+                    onClick={toggleFullscreen}
+                    title={isFullscreen ? "Exit fullscreen" : "Enter fullscreen"}
+                    aria-label={isFullscreen ? "Exit fullscreen" : "Enter fullscreen"}
+                >
+                    {isFullscreen ? "⤢" : "⛶"}
+                </button>
+            </div>
+
+            {error && (
+                <div style={{ ...barStyle, top: 8, bottom: "auto", background: "rgba(160,0,0,0.8)" }}>
+                    {error}
                 </div>
             )}
         </div>
     );
+    logPanovideo("component render: JSX tree created", { playing, muted, isFullscreen, error });
+    return element;
 }
 
 const PanovideoPlayerElementRegistration: FormElementRegistration<PanovideoPlayerProps> = {
     component: PanovideoPlayer,
-    getInitialProperties: () => ({ value: "" }),
+    getInitialProperties: () => {
+        logPanovideo("getInitialProperties: start");
+        const properties = {
+            value: "",
+            resolutions: DEFAULT_RESOLUTIONS,
+            autoplay: true,
+            maxZoom: 3,
+        };
+        logPanovideo("getInitialProperties: complete", properties);
+        return properties;
+    },
     id: "PanovideoPlayer",
 };
 
-export default PanovideoPlayerElementRegistration;
+export default PanovideoPlayerElementRegistration;