@ericchen1990/pano-view 2.0.0 → 2.2.0

package/dist/index.mjs

@@ -718,7 +718,7 @@ function useHotspotAccessibilityLayer() {
       "button",
       {
         "aria-label": entry.label,
-        className: "sr-only",
+        className: "pano-sr-only",
         onBlur: () => entry.onFocusChange(false),
         onClick: (event) => entry.activate(event.nativeEvent),
         onFocus: () => entry.onFocusChange(true),
@@ -1437,9 +1437,6 @@ function DefaultContextMenuPanel({
     fontSize: resolved.fontSize,
     minWidth: resolved.minWidth,
     padding: resolved.padding,
-    pointerEvents: "auto",
-    position: "relative",
-    userSelect: "none",
     ...style
   };
   return /* @__PURE__ */ jsxs(
@@ -1447,7 +1444,7 @@ function DefaultContextMenuPanel({
     {
       ref: menuRef,
       "aria-label": "Panorama context menu",
-      className: cn("relative select-none", className),
+      className: cn("pano-context-menu", className),
       onKeyDown: handleKeyDown,
       role: "menu",
       style: panelStyle,
@@ -1457,7 +1454,7 @@ function DefaultContextMenuPanel({
           "div",
           {
             "aria-hidden": true,
-            className: "pointer-events-none absolute inset-0 z-0",
+            className: "pano-context-menu-backdrop",
             style: {
               background: resolved.background,
               borderRadius: resolved.borderRadius,
@@ -1465,7 +1462,7 @@ function DefaultContextMenuPanel({
             }
           }
         ),
-        /* @__PURE__ */ jsx2("div", { className: "relative z-[1]", children: visibleItems.map((item, index) => {
+        /* @__PURE__ */ jsx2("div", { className: "pano-context-menu-items", children: visibleItems.map((item, index) => {
           if (!isActionItem(item)) {
             return /* @__PURE__ */ jsx2(
               "div",
@@ -1503,7 +1500,7 @@ function DefaultContextMenuPanel({
             {
               "aria-disabled": disabled || void 0,
               className: cn(
-                "flex w-full items-center gap-2 rounded text-left",
+                "pano-context-menu-item",
                 itemClassName,
                 item.className
               ),
@@ -1538,7 +1535,7 @@ function DefaultContextMenuPanel({
                   "span",
                   {
                     "aria-hidden": true,
-                    className: "inline-flex shrink-0 items-center justify-center",
+                    className: "pano-context-menu-item-icon",
                     style: {
                       height: iconSize,
                       width: iconSize
@@ -1589,7 +1586,7 @@ function PositionedMenuShell({
   return /* @__PURE__ */ jsx2(
     "div",
     {
-      className: "absolute z-20",
+      className: "pano-context-menu-shell",
       ref: shellRef,
       style: {
         left: offset.left,
@@ -2713,7 +2710,7 @@ function usePanoChromeOverlay() {
   const overlay = /* @__PURE__ */ jsx5(
     "div",
     {
-      className: "pointer-events-none absolute inset-0 z-[15]",
+      className: "pano-chrome-overlay",
       "data-pano-chrome-overlay": "",
       ref: setOverlayNode
     }
@@ -2805,14 +2802,7 @@ function PanoVideoCaptionsOverlay({
     return null;
   }
   const wrapperStyle = {
-    bottom: snapshot.captionAppearance.bottom,
-    display: "flex",
-    justifyContent: "center",
-    left: 0,
-    pointerEvents: "none",
-    position: "absolute",
-    right: 0,
-    zIndex: 1
+    bottom: snapshot.captionAppearance.bottom
   };
   const textStyle = {
     background: snapshot.captionAppearance.background,
@@ -2831,7 +2821,7 @@ function PanoVideoCaptionsOverlay({
   return /* @__PURE__ */ jsx6(
     "div",
     {
-      className: "pointer-events-none absolute inset-x-0 z-1 flex justify-center",
+      className: "pano-video-captions",
       "data-pano-video-captions": "",
       style: wrapperStyle,
       children: /* @__PURE__ */ jsx6("div", { style: textStyle, children: snapshot.captionText })
@@ -3075,7 +3065,7 @@ function ChromeButton({
     "button",
     {
       "aria-label": label,
-      className: "inline-flex min-h-7 min-w-7 items-center justify-center rounded",
+      className: "pano-video-chrome-button",
       disabled,
       id,
       onClick,
@@ -3083,18 +3073,7 @@ function ChromeButton({
         event.stopPropagation();
       },
       style: {
-        alignItems: "center",
-        background: "transparent",
-        border: "none",
-        borderRadius: 4,
-        color: appearance.color,
-        cursor: disabled ? "default" : "pointer",
-        display: "inline-flex",
-        height: 28,
-        justifyContent: "center",
-        minWidth: 28,
-        opacity: disabled ? 0.45 : 1,
-        padding: 4
+        color: appearance.color
       },
       title: label,
       type: "button",
@@ -3139,7 +3118,7 @@ function ChromeMenuSurface({
     "div",
     {
       "aria-labelledby": labelledBy,
-      className: "absolute right-0 flex min-w-28 flex-col p-1",
+      className: "pano-video-chrome-menu",
       id,
       role,
       style: {
@@ -3163,7 +3142,7 @@ function ChromeMenuRadioItem({
     "button",
     {
       "aria-checked": active,
-      className: "rounded px-2.5 py-1.5 text-left whitespace-nowrap",
+      className: "pano-video-chrome-menu-item",
       onClick,
       role: "menuitemradio",
       style: {
@@ -3187,7 +3166,7 @@ function ChromeMenuActionItem({
   return /* @__PURE__ */ jsxs3(
     "button",
     {
-      className: "flex items-center justify-between gap-3 rounded px-2.5 py-1.5 text-left whitespace-nowrap",
+      className: "pano-video-chrome-menu-action",
       onClick,
       role: "menuitem",
       style: {
@@ -3208,17 +3187,10 @@ function ChromeMenuActionItem({
 function ChromeMenuSectionLabel({
   children
 }) {
-  return /* @__PURE__ */ jsx7(
-    "div",
-    {
-      className: "px-2.5 pt-2 pb-1 uppercase opacity-70",
-      style: { fontSize: 10, letterSpacing: "0.08em" },
-      children
-    }
-  );
+  return /* @__PURE__ */ jsx7("div", { className: "pano-video-chrome-menu-label", children });
 }
 function ChromeMenuDivider() {
-  return /* @__PURE__ */ jsx7("div", { className: "my-1 h-px bg-white/10" });
+  return /* @__PURE__ */ jsx7("div", { className: "pano-video-chrome-menu-divider" });
 }
 function CaptionsMenu({
   appearance,
@@ -3239,7 +3211,7 @@ function CaptionsMenu({
       labelledBy,
       role: "menu",
       children: panel === "tracks" ? /* @__PURE__ */ jsxs3(Fragment, { children: [
-        /* @__PURE__ */ jsxs3("div", { className: "flex max-h-48 flex-col overflow-y-auto", children: [
+        /* @__PURE__ */ jsxs3("div", { className: "pano-video-chrome-menu-list", children: [
           /* @__PURE__ */ jsx7(
             ChromeMenuRadioItem,
             {
@@ -3347,7 +3319,7 @@ function VerticalVolumeSlider({
   return /* @__PURE__ */ jsxs3(
     "div",
     {
-      className: "absolute left-1/2 flex min-w-11 -translate-x-1/2 flex-col items-center rounded-[14px]",
+      className: "pano-video-volume-popover",
       style: {
         background: "rgba(12, 12, 12, 0.92)",
         bottom: `calc(100% + ${CHROME_POPOVER_GAP}px)`,
@@ -3362,7 +3334,7 @@ function VerticalVolumeSlider({
           "span",
           {
             "aria-hidden": true,
-            className: "mb-3.5 font-bold leading-none [font-variant-numeric:tabular-nums]",
+            className: "pano-video-volume-percent",
             style: {
               color: appearance.color,
               fontSize: VOLUME_POP_FONT_SIZE
@@ -3401,7 +3373,7 @@ function VerticalVolumeSlider({
                 },
                 ref: trackRef,
                 role: "slider",
-                className: "relative cursor-pointer rounded-[999px]",
+                className: "pano-video-volume-track",
                 style: {
                   background: "rgba(255, 255, 255, 0.14)",
                   borderRadius: 999,
@@ -3498,7 +3470,7 @@ function VolumeControl({
     "div",
     {
       "data-pano-video-volume": "",
-      className: "relative",
+      className: "pano-video-volume",
       onBlur: (event) => {
         if (event.currentTarget.contains(event.relatedTarget)) {
           return;
@@ -3829,7 +3801,7 @@ function PanoVideoControlsHud({
     transition: "opacity 160ms ease",
     zIndex: 2
   };
-  const rateButton = /* @__PURE__ */ jsxs3("div", { className: "relative", "data-pano-video-menu": "rate", children: [
+  const rateButton = /* @__PURE__ */ jsxs3("div", { className: "pano-video-menu", "data-pano-video-menu": "rate", children: [
     !compact && menu === "rate" ? menuNode : null,
     /* @__PURE__ */ jsx7(
       ChromeButton,
@@ -3839,11 +3811,11 @@ function PanoVideoControlsHud({
         onClick: () => {
           toggleMenu("rate");
         },
-        children: /* @__PURE__ */ jsx7("span", { className: "px-0.5 text-[11px]", id: `${barId}-rate-btn`, children: snapshot.playbackRate === 1 ? "1x" : `${snapshot.playbackRate}x` })
+        children: /* @__PURE__ */ jsx7("span", { className: "pano-video-chrome-label", id: `${barId}-rate-btn`, children: snapshot.playbackRate === 1 ? "1x" : `${snapshot.playbackRate}x` })
       }
     )
   ] });
-  const variantButton = canSwitchVariant ? /* @__PURE__ */ jsxs3("div", { className: "relative", "data-pano-video-menu": "variant", children: [
+  const variantButton = canSwitchVariant ? /* @__PURE__ */ jsxs3("div", { className: "pano-video-menu", "data-pano-video-menu": "variant", children: [
     !compact && menu === "variant" ? menuNode : null,
     /* @__PURE__ */ jsx7(
       ChromeButton,
@@ -3853,11 +3825,11 @@ function PanoVideoControlsHud({
         onClick: () => {
           toggleMenu("variant");
         },
-        children: /* @__PURE__ */ jsx7("span", { className: "px-0.5 text-[11px]", id: `${barId}-variant-btn`, children: snapshot.variants.find((variant) => variant.id === snapshot.variantId)?.label ?? "Quality" })
+        children: /* @__PURE__ */ jsx7("span", { className: "pano-video-chrome-label", id: `${barId}-variant-btn`, children: snapshot.variants.find((variant) => variant.id === snapshot.variantId)?.label ?? "Quality" })
       }
     )
   ] }) : null;
-  const captionsButton = showCaptionsMenu ? /* @__PURE__ */ jsxs3("div", { className: "relative", "data-pano-video-menu": "captions", children: [
+  const captionsButton = showCaptionsMenu ? /* @__PURE__ */ jsxs3("div", { className: "pano-video-menu", "data-pano-video-menu": "captions", children: [
     !compact && menu === "captions" ? menuNode : null,
     /* @__PURE__ */ jsx7(
       ChromeButton,
@@ -3874,7 +3846,7 @@ function PanoVideoControlsHud({
   return /* @__PURE__ */ jsxs3(
     "div",
     {
-      className: "absolute right-2.5 bottom-2.5 left-2.5 z-2 flex items-center gap-2 transition-opacity",
+      className: "pano-video-controls",
       "data-pano-video-controls": "",
       style: barStyle,
       children: [
@@ -3889,7 +3861,7 @@ function PanoVideoControlsHud({
             children: snapshot.playing ? /* @__PURE__ */ jsx7(Icon, { path: "M5 3.5h2.2v9H5zM8.8 3.5H11v9H8.8z" }) : /* @__PURE__ */ jsx7(Icon, { path: "M5 3.2v9.6L13 8z" })
           }
         ),
-        hideTime ? null : /* @__PURE__ */ jsx7("span", { className: "min-w-8.5 opacity-[0.85] [font-variant-numeric:tabular-nums]", children: formatMediaTime(snapshot.currentTime) }),
+        hideTime ? null : /* @__PURE__ */ jsx7("span", { className: "pano-video-time", children: formatMediaTime(snapshot.currentTime) }),
         /* @__PURE__ */ jsx7(
           "input",
           {
@@ -3912,7 +3884,7 @@ function PanoVideoControlsHud({
             value: duration > 0 ? snapshot.currentTime : 0
           }
         ),
-        hideTime ? null : /* @__PURE__ */ jsx7("span", { className: "min-w-8.5 opacity-[0.85]", children: formatMediaTime(duration) }),
+        hideTime ? null : /* @__PURE__ */ jsx7("span", { className: "pano-video-time", children: formatMediaTime(duration) }),
         /* @__PURE__ */ jsx7(
           VolumeControl,
           {
@@ -3929,7 +3901,7 @@ function PanoVideoControlsHud({
             volumeAdjustable: snapshot.volumeAdjustable
           }
         ),
-        compact ? /* @__PURE__ */ jsxs3("div", { className: "relative", "data-pano-video-menu": "more", children: [
+        compact ? /* @__PURE__ */ jsxs3("div", { className: "pano-video-menu", "data-pano-video-menu": "more", children: [
           menu !== null ? menuNode : null,
           /* @__PURE__ */ jsx7(
             ChromeButton,
@@ -4166,7 +4138,7 @@ function ChromeButton2({
   return /* @__PURE__ */ jsx9(
     "button",
     {
-      className: "pointer-events-auto border border-white/20 px-3 py-2 font-semibold shadow-lg backdrop-blur-sm",
+      className: "pano-webvr-button",
       onClick,
       style: {
         background: appearance.background,
@@ -4204,19 +4176,19 @@ function SetupPanel({
     "div",
     {
       "aria-label": "Mobile VR setup",
-      className: "pointer-events-auto absolute top-1/2 left-1/2 w-[min(22rem,calc(100%-2rem))] -translate-x-1/2 -translate-y-1/2 border border-white/20 p-5 text-center shadow-2xl backdrop-blur-md",
+      className: "pano-webvr-setup",
       role: "dialog",
       style: panelStyle,
       children: [
-        /* @__PURE__ */ jsx9("h2", { className: "m-0 mb-5 text-2xl font-extrabold", children: appearance.setupTitle ?? "MobileVR Setup" }),
-        /* @__PURE__ */ jsxs5("label", { className: "mb-5 block font-semibold", children: [
+        /* @__PURE__ */ jsx9("h2", { className: "pano-webvr-setup-title", children: appearance.setupTitle ?? "MobileVR Setup" }),
+        /* @__PURE__ */ jsxs5("label", { className: "pano-webvr-setup-field", children: [
           "Screen size (inch)",
-          /* @__PURE__ */ jsxs5("div", { className: "mt-2 flex items-center justify-center gap-3", children: [
+          /* @__PURE__ */ jsxs5("div", { className: "pano-webvr-setup-row", children: [
             /* @__PURE__ */ jsx9(
               "button",
               {
                 "aria-label": "Decrease screen size",
-                className: "text-2xl",
+                className: "pano-webvr-setup-stepper",
                 onClick: () => setScreensize(
                   settings.screensize === "auto" ? 5 : Math.max(3, settings.screensize - 0.1)
                 ),
@@ -4224,12 +4196,12 @@ function SetupPanel({
                 children: "\u2039"
               }
             ),
-            /* @__PURE__ */ jsx9("strong", { className: "min-w-16 text-xl", children: settings.screensize === "auto" ? "Auto" : settings.screensize.toFixed(1) }),
+            /* @__PURE__ */ jsx9("strong", { className: "pano-webvr-setup-value", children: settings.screensize === "auto" ? "Auto" : settings.screensize.toFixed(1) }),
             /* @__PURE__ */ jsx9(
               "button",
               {
                 "aria-label": "Increase screen size",
-                className: "text-2xl",
+                className: "pano-webvr-setup-stepper",
                 onClick: () => setScreensize(
                   settings.screensize === "auto" ? 5 : Math.min(20, settings.screensize + 0.1)
                 ),
@@ -4239,25 +4211,25 @@ function SetupPanel({
             )
           ] })
         ] }),
-        /* @__PURE__ */ jsxs5("fieldset", { className: "m-0 mb-5 border-0 p-0", children: [
-          /* @__PURE__ */ jsx9("legend", { className: "mb-2 font-semibold", children: "VR headset preset" }),
-          /* @__PURE__ */ jsxs5("div", { className: "mt-2 flex items-center justify-center gap-3", children: [
+        /* @__PURE__ */ jsxs5("fieldset", { className: "pano-webvr-setup-fieldset", children: [
+          /* @__PURE__ */ jsx9("legend", { className: "pano-webvr-setup-legend", children: "VR headset preset" }),
+          /* @__PURE__ */ jsxs5("div", { className: "pano-webvr-setup-row", children: [
             /* @__PURE__ */ jsx9(
               "button",
               {
                 "aria-label": "Previous headset preset",
-                className: "text-2xl",
+                className: "pano-webvr-setup-stepper",
                 onClick: () => cycleProfile(-1),
                 type: "button",
                 children: "\u2039"
               }
             ),
-            /* @__PURE__ */ jsx9("strong", { className: "min-w-32 text-xl", children: WEBVR_PROFILES[settings.profileId].label }),
+            /* @__PURE__ */ jsx9("strong", { className: "pano-webvr-setup-value-wide", children: WEBVR_PROFILES[settings.profileId].label }),
             /* @__PURE__ */ jsx9(
               "button",
               {
                 "aria-label": "Next headset preset",
-                className: "text-2xl",
+                className: "pano-webvr-setup-stepper",
                 onClick: () => cycleProfile(1),
                 type: "button",
                 children: "\u203A"
@@ -4289,7 +4261,7 @@ function WebVRChromeBridge({ host }) {
   }
   const appearance = resolveAppearance(chrome);
   return /* @__PURE__ */ jsxs5(Fragment3, { children: [
-    /* @__PURE__ */ jsx9("div", { className: "pointer-events-none absolute inset-x-0 top-4 flex justify-center", children: mode ? /* @__PURE__ */ jsxs5("div", { className: "flex gap-2", children: [
+    /* @__PURE__ */ jsx9("div", { className: "pano-webvr-toolbar", children: mode ? /* @__PURE__ */ jsxs5("div", { className: "pano-webvr-toolbar-actions", children: [
       mode !== "webxr" ? /* @__PURE__ */ jsx9(
         ChromeButton2,
         {
@@ -4317,7 +4289,7 @@ function WebVRChromeBridge({ host }) {
     mode === "fake" ? /* @__PURE__ */ jsx9(
       "p",
       {
-        className: "pointer-events-none absolute inset-x-0 bottom-5 m-0 text-center text-xs font-semibold text-white drop-shadow",
+        className: "pano-webvr-hint",
         style: { color: appearance.color },
         children: "Simulated VR Mode \xB7 Click the view to lock the mouse, then move to look around. Use a headset or phone for real VR."
       }
@@ -4663,7 +4635,7 @@ var PanoViewer = forwardRef2(
       "div",
       {
         ...divProps,
-        className: cn("relative overflow-hidden", divProps.className),
+        className: cn("pano-viewer", divProps.className),
         "data-pano-viewer": "",
         ref: rootRef,
         "aria-label": ariaLabel,
@@ -4762,12 +4734,9 @@ var PanoViewer = forwardRef2(
           /* @__PURE__ */ jsxs6(
             "div",
             {
-              className: "pointer-events-none absolute inset-0 z-15",
+              className: "pano-chrome-overlay",
               "data-pano-chrome-overlay": "",
               ref: setOverlayNode,
-              style: {
-                inset: 0
-              },
               children: [
                 /* @__PURE__ */ jsx11(
                   PanoVideoChromeBridge,
@@ -6369,7 +6338,7 @@ var WebVR = forwardRef4(function WebVR2({
 
 // src/sphere.tsx
 import { useThree as useThree13 } from "@react-three/fiber";
-import { useEffect as useEffect19, useRef as useRef19, useState as useState8 } from "react";
+import { useEffect as useEffect19, useMemo as useMemo12, useRef as useRef19, useState as useState8 } from "react";
 import {
   BackSide as BackSide2,
   LinearFilter,
@@ -6380,6 +6349,27 @@ import {
   TextureLoader
 } from "three";
 
+// src/asset-url.ts
+function isAbsoluteAssetUrl(url) {
+  return url.startsWith("/") || url.startsWith("//") || /^[a-z][a-z0-9+.-]*:/i.test(url);
+}
+function resolveRelativeAssetUrl(baseUrl, relativePath) {
+  const normalizedBaseUrl = baseUrl.replace(/\/+$/, "");
+  const normalizedPath = relativePath.replace(/^\/+/, "");
+  return normalizedBaseUrl ? `${normalizedBaseUrl}/${normalizedPath}` : normalizedPath;
+}
+function resolveAssetUrl(baseUrl, path) {
+  return isAbsoluteAssetUrl(path) ? path : resolveRelativeAssetUrl(baseUrl, path);
+}
+function resolveUrlAgainstFile(fileUrl, path) {
+  if (isAbsoluteAssetUrl(path)) {
+    return path;
+  }
+  const slash = fileUrl.lastIndexOf("/");
+  const directory = slash === -1 ? "" : fileUrl.slice(0, slash);
+  return resolveRelativeAssetUrl(directory, path);
+}
+
 // src/pano-filter/pano-basic-material.tsx
 import { useLayoutEffect as useLayoutEffect2, useMemo as useMemo11, useRef as useRef18 } from "react";
 
@@ -6596,25 +6586,22 @@ function PanoBasicMaterial({
 
 // src/sphere.tsx
 import { jsx as jsx15, jsxs as jsxs9 } from "react/jsx-runtime";
-function Sphere({
-  src,
-  yawOffset = 0,
-  onLoad,
-  onError,
-  visible = true
-}) {
-  const gl = useThree13((state) => state.gl);
+function useEquirectTexture(url, anisotropy, generateMipmaps, onLoad, onError) {
   const [texture, setTexture] = useState8(null);
   const onLoadRef = useRef19(onLoad);
   const onErrorRef = useRef19(onError);
   onLoadRef.current = onLoad;
   onErrorRef.current = onError;
   useEffect19(() => {
+    if (!url) {
+      setTexture(null);
+      return;
+    }
     let active = true;
     const loader = new TextureLoader();
     setTexture(null);
     loader.load(
-      src,
+      url,
       (loadedTexture) => {
         if (!active) {
           loadedTexture.dispose();
@@ -6624,10 +6611,10 @@ function Sphere({
         loadedTexture.wrapS = RepeatWrapping;
         loadedTexture.repeat.x = -1;
         loadedTexture.offset.x = 1;
-        loadedTexture.anisotropy = gl.capabilities.getMaxAnisotropy();
+        loadedTexture.anisotropy = anisotropy;
         loadedTexture.magFilter = LinearFilter;
-        loadedTexture.minFilter = LinearMipmapLinearFilter;
-        loadedTexture.generateMipmaps = true;
+        loadedTexture.minFilter = generateMipmaps ? LinearMipmapLinearFilter : LinearFilter;
+        loadedTexture.generateMipmaps = generateMipmaps;
         loadedTexture.needsUpdate = true;
         setTexture(loadedTexture);
         onLoadRef.current?.(loadedTexture);
@@ -6635,6 +6622,7 @@ function Sphere({
       void 0,
       (error) => {
         if (active) {
+          setTexture(null);
           onErrorRef.current?.(error);
         }
       }
@@ -6642,14 +6630,58 @@ function Sphere({
     return () => {
       active = false;
     };
-  }, [gl, src]);
+  }, [anisotropy, generateMipmaps, url]);
   useEffect19(
     () => () => {
       texture?.dispose();
     },
     [texture]
   );
-  if (!texture) {
+  return texture;
+}
+function Sphere({
+  src,
+  previewUrl,
+  yawOffset = 0,
+  onReady,
+  onLoad,
+  onError,
+  onPreviewError,
+  visible = true
+}) {
+  const gl = useThree13((state) => state.gl);
+  const anisotropy = gl.capabilities.getMaxAnisotropy();
+  const resolvedPreviewUrl = useMemo12(
+    () => resolveUrlAgainstFile(src, previewUrl),
+    [previewUrl, src]
+  );
+  const texture = useEquirectTexture(
+    src,
+    anisotropy,
+    true,
+    onLoad,
+    onError
+  );
+  const previewTexture = useEquirectTexture(
+    texture ? null : resolvedPreviewUrl,
+    anisotropy,
+    false,
+    void 0,
+    onPreviewError
+  );
+  const displayTexture = texture ?? previewTexture;
+  const readyRef = useRef19(false);
+  useEffect19(() => {
+    readyRef.current = false;
+  }, [resolvedPreviewUrl, src]);
+  useEffect19(() => {
+    if (!displayTexture || readyRef.current) {
+      return;
+    }
+    readyRef.current = true;
+    onReady?.();
+  }, [displayTexture, onReady]);
+  if (!displayTexture) {
     return null;
   }
   return /* @__PURE__ */ jsxs9(
@@ -6662,7 +6694,7 @@ function Sphere({
         /* @__PURE__ */ jsx15(
           PanoBasicMaterial,
           {
-            map: texture,
+            map: displayTexture,
             side: BackSide2,
             toneMapped: false
           }
@@ -6679,7 +6711,7 @@ import {
   useContext as useContext19,
   useEffect as useEffect20,
   useLayoutEffect as useLayoutEffect3,
-  useMemo as useMemo12,
+  useMemo as useMemo13,
   useRef as useRef20,
   useState as useState9
 } from "react";
@@ -6878,13 +6910,13 @@ function PanoVideo({
   const gl = useThree14((state) => state.gl);
   const host = useContext19(PanoVideoHostContext);
   const overlay = useContext19(PanoChromeOverlayContext);
-  const variants = useMemo12(
+  const variants = useMemo13(
     () => resolvePanoVideoVariants({ poster, src, variants: variantsProp }),
     [poster, src, variantsProp]
   );
   const tracks = tracksProp ?? EMPTY_TRACKS;
   const captionsEnabled = captions !== false;
-  const captionAppearance = useMemo12(
+  const captionAppearance = useMemo13(
     () => resolvePanoVideoCaptionAppearance(
       typeof captions === "object" ? captions : void 0
     ),
@@ -6949,7 +6981,7 @@ function PanoVideo({
   onEndedRef.current = onEnded;
   onVariantChangeRef.current = onVariantChange;
   onTrackChangeRef.current = onTrackChange;
-  const resource = useMemo12(() => {
+  const resource = useMemo13(() => {
     if (typeof document === "undefined") {
       return null;
     }
@@ -7062,7 +7094,7 @@ function PanoVideo({
       captionAppearance
     ]
   );
-  const controller = useMemo12(
+  const controller = useMemo13(
     () => ({
       subscribe: (onStoreChange) => {
         const store = storeRef.current;
@@ -7429,7 +7461,7 @@ import {
   useCallback as useCallback10,
   useContext as useContext21,
   useEffect as useEffect25,
-  useMemo as useMemo17,
+  useMemo as useMemo18,
   useRef as useRef24,
   useState as useState11
 } from "react";
@@ -7487,7 +7519,7 @@ function isSnapshotTransition(preset) {
 
 // src/scene-transitions/particle-overlay.tsx
 import { useFrame as useFrame9, useThree as useThree15 } from "@react-three/fiber";
-import { useEffect as useEffect21, useMemo as useMemo13, useRef as useRef21 } from "react";
+import { useEffect as useEffect21, useMemo as useMemo14, useRef as useRef21 } from "react";
 import {
   DoubleSide as DoubleSide2,
   InstancedBufferAttribute,
@@ -7631,8 +7663,8 @@ function ParticleOverlay({
   const startRef = useRef21(null);
   const finishedRef = useRef21(false);
   const directionRef = useRef21(new Vector38());
-  const geometry = useMemo13(() => createParticleGeometry(), []);
-  const material = useMemo13(
+  const geometry = useMemo14(() => createParticleGeometry(), []);
+  const material = useMemo14(
     () => new ShaderMaterial2({
       transparent: true,
       depthTest: false,
@@ -7686,7 +7718,7 @@ function ParticleOverlay({
 
 // src/scene-transitions/snapshot-overlay.tsx
 import { useFrame as useFrame10, useThree as useThree16 } from "@react-three/fiber";
-import { useEffect as useEffect22, useMemo as useMemo14, useRef as useRef22 } from "react";
+import { useEffect as useEffect22, useMemo as useMemo15, useRef as useRef22 } from "react";
 import { Vector3 as Vector39 } from "three";
 
 // src/scene-transitions/snapshot-shaders.ts
@@ -7979,7 +8011,7 @@ function SnapshotOverlay({
   const startRef = useRef22(null);
   const finishedRef = useRef22(false);
   const directionRef = useRef22(new Vector39());
-  const material = useMemo14(() => {
+  const material = useMemo15(() => {
     if (!isSnapshotTransition(transition.preset)) {
       return null;
     }
@@ -8072,7 +8104,7 @@ import {
   createContext as createContext11,
   useContext as useContext20,
   useEffect as useEffect23,
-  useMemo as useMemo15
+  useMemo as useMemo16
 } from "react";
 
 // src/tile/texture-manager.ts
@@ -8313,7 +8345,7 @@ function TileTextureManagerProvider({
 }) {
   const gl = useThree17((state) => state.gl);
   const anisotropy = gl.capabilities.getMaxAnisotropy();
-  const manager = useMemo15(
+  const manager = useMemo16(
     () => new TileTextureManager({
       anisotropy,
       maxBytes: Math.max(1, maxTextureMemoryMb) * 1024 * 1024,
@@ -8337,7 +8369,7 @@ import { useFrame as useFrame11, useThree as useThree18 } from "@react-three/fib
 import {
   memo,
   useEffect as useEffect24,
-  useMemo as useMemo16,
+  useMemo as useMemo17,
   useRef as useRef23,
   useState as useState10
 } from "react";
@@ -8520,13 +8552,12 @@ function parseMultires(multires) {
   );
   return { tileSize, levels };
 }
+var DEFAULT_TILE_URL_TEMPLATE = "tiles/%s/l%l/%v/l%l_%s_%h_%v.webp";
 function buildDefaultTileUrlTemplate() {
-  return "tiles/%s/l%l/%v/l%l_%s_%h_%v.webp";
+  return DEFAULT_TILE_URL_TEMPLATE;
 }
 function resolveRelativeTileUrl(baseUrl, relativePath) {
-  const normalizedBaseUrl = baseUrl.replace(/\/+$/, "");
-  const normalizedPath = relativePath.replace(/^\/+/, "");
-  return normalizedBaseUrl ? `${normalizedBaseUrl}/${normalizedPath}` : normalizedPath;
+  return resolveRelativeAssetUrl(baseUrl, relativePath);
 }
 function resolveTemplateUrl(template, address) {
   return template.replace(/%s/g, address.face).replace(/%l/g, String(address.level)).replace(/%(0*)([hxucvywr])/g, (_match, zeroes, placeholder) => {
@@ -8598,7 +8629,7 @@ function PreviewFace({
   texture,
   faceOrder
 }) {
-  const geometry = useMemo16(() => {
+  const geometry = useMemo17(() => {
     const nextGeometry = new PlaneGeometry4(
       PREVIEW_RADIUS * 2,
       PREVIEW_RADIUS * 2
@@ -8884,15 +8915,15 @@ function Tile({
   onLevelChange
 }) {
   const { camera, gl, size } = useThree18();
-  const multiresConfig = useMemo16(() => parseMultires(multires), [multires]);
+  const multiresConfig = useMemo17(() => parseMultires(multires), [multires]);
   const { levels, tileSize } = multiresConfig;
   const multiresToken = `${tileSize}:${levels.join(",")}`;
-  const candidatesByLevel = useMemo16(
+  const candidatesByLevel = useMemo17(
     () => buildTileCandidates(levels, tileSize),
     [levels, tileSize]
   );
   const anisotropy = gl.capabilities.getMaxAnisotropy();
-  const effectivePreviewUrl = previewUrl === void 0 ? `${baseUrl.replace(/\/$/, "")}/previews/cube-vertical.webp` : previewUrl;
+  const effectivePreviewUrl = resolveAssetUrl(baseUrl, previewUrl);
   const previewTexture = usePreviewTexture(
     effectivePreviewUrl,
     anisotropy,
@@ -8905,7 +8936,7 @@ function Tile({
   progressRef.current = onLoadProgress;
   errorRef.current = onTileError;
   levelChangeRef.current = onLevelChange;
-  const ownedManager = useMemo16(
+  const ownedManager = useMemo17(
     () => new TileTextureManager({
       anisotropy,
       maxBytes: Math.max(1, maxTextureMemoryMb) * 1024 * 1024,
@@ -8948,7 +8979,7 @@ function Tile({
     onReady?.();
   }, [onReady, previewTexture]);
   const template = urlTemplate ?? buildDefaultTileUrlTemplate();
-  const resolveUrl = useMemo16(
+  const resolveUrl = useMemo17(
     () => (address) => {
       const relativePath = resolveTileUrl ? resolveTileUrl(address) : resolveTemplateUrl(template, address);
       return resolveRelativeTileUrl(baseUrl, relativePath);
@@ -9090,9 +9121,10 @@ function SceneSource({
         Sphere,
         {
           src: scene.src,
+          previewUrl: scene.previewUrl,
           yawOffset: scene.yawOffset,
           visible,
-          onLoad: onReady,
+          onReady,
           onError
         }
       );
@@ -9181,11 +9213,11 @@ function ScenesController({
 }) {
   const controlsRef = useContext21(PanoramaViewContext);
   const manager = useSharedTileTextureManager();
-  const transition = useMemo17(
+  const transition = useMemo18(
     () => resolveTransition(transitionInput),
     [transitionInput]
   );
-  const sceneMap = useMemo17(
+  const sceneMap = useMemo18(
     () => new Map(scenes.map((scene) => [scene.id, scene])),
     [scenes]
   );
@@ -9435,7 +9467,7 @@ import {
   useContext as useContext23,
   useEffect as useEffect27,
   useLayoutEffect as useLayoutEffect4,
-  useMemo as useMemo19,
+  useMemo as useMemo20,
   useRef as useRef25,
   useState as useState13
 } from "react";
@@ -9453,7 +9485,7 @@ import {
 } from "three";
 
 // src/hotspot/hotspot-tooltip.tsx
-import { useEffect as useEffect26, useMemo as useMemo18, useState as useState12 } from "react";
+import { useEffect as useEffect26, useMemo as useMemo19, useState as useState12 } from "react";
 
 // src/webvr/stereo-html.tsx
 import { Html } from "@react-three/drei";
@@ -9581,11 +9613,11 @@ function HotspotTooltip({
     setImageFailed(false);
   }, [content.image]);
   const showImage = Boolean(content.image) && !imageFailed;
-  const resolvedAppearance = useMemo18(
+  const resolvedAppearance = useMemo19(
     () => resolveHotspotTooltipAppearance(appearance),
     [appearance]
   );
-  const bubbleStyle = useMemo18(
+  const bubbleStyle = useMemo19(
     () => ({
       background: resolvedAppearance.background,
       border: resolvedAppearance.border,
@@ -9607,7 +9639,7 @@ function HotspotTooltip({
   return /* @__PURE__ */ jsx24(PanoHtml, { pointerEvents: "none", style: WRAPPER_STYLE, zIndexRange: [20, 10], children: /* @__PURE__ */ jsxs15(
     "div",
     {
-      className: "pointer-events-none flex gap-2 whitespace-nowrap",
+      className: "pano-hotspot-tooltip",
       role: "tooltip",
       style: bubbleStyle,
       children: [
@@ -9615,12 +9647,12 @@ function HotspotTooltip({
           "img",
           {
             alt: content.imageAlt ?? content.text ?? "",
-            className: "block h-auto max-h-[120px] max-w-[220px] rounded object-contain",
+            className: "pano-hotspot-tooltip-image",
             onError: () => setImageFailed(true),
             src: content.image
           }
         ) : null,
-        content.text ? /* @__PURE__ */ jsx24("p", { className: "m-0 overflow-visible whitespace-nowrap leading-[1.4]", children: content.text }) : null
+        content.text ? /* @__PURE__ */ jsx24("p", { className: "pano-hotspot-tooltip-text", children: content.text }) : null
       ]
     }
   ) });
@@ -9975,7 +10007,7 @@ function HotspotAnchor({
   const [hovered, setHovered] = useState13(false);
   const [dragging, setDragging] = useState13(false);
   const [pinned, setPinned] = useState13(false);
-  const tooltipContent = useMemo19(
+  const tooltipContent = useMemo20(
     () => resolveHotspotTooltipContent(tooltip),
     [tooltip]
   );
@@ -9991,17 +10023,17 @@ function HotspotAnchor({
     scaledWidth,
     scaledHeight
   );
-  const worldPosition = useMemo19(
+  const worldPosition = useMemo20(
     () => panoPositionToVector3(normalizedPosition, resolvedDistance),
     [normalizedPosition.pitch, normalizedPosition.yaw, resolvedDistance]
   );
-  const surfaceQuaternion3 = useMemo19(
+  const surfaceQuaternion3 = useMemo20(
     () => createSurfaceQuaternion(normalizedPosition),
     [normalizedPosition.pitch, normalizedPosition.yaw]
   );
   const worldWidth = angularSizeToWorldSize(scaledWidth, resolvedDistance);
   const worldHeight = angularSizeToWorldSize(scaledHeight, resolvedDistance);
-  const focusGeometry = useMemo19(() => {
+  const focusGeometry = useMemo20(() => {
     const planeGeometry = new PlaneGeometry5(1, 1);
     const geometry = new EdgesGeometry(planeGeometry);
     planeGeometry.dispose();
@@ -10487,7 +10519,7 @@ function ImageHotspot({
 }
 
 // src/hotspot/polygon-hotspot.tsx
-import { useEffect as useEffect29, useMemo as useMemo20, useRef as useRef28 } from "react";
+import { useEffect as useEffect29, useMemo as useMemo21, useRef as useRef28 } from "react";
 import {
   BufferGeometry,
   DoubleSide as DoubleSide5,
@@ -10832,14 +10864,14 @@ function PolygonHotspot({
   onInvalid,
   ...anchorProps
 }) {
-  const issues = useMemo20(() => validatePolygonVertices(vertices), [vertices]);
+  const issues = useMemo21(() => validatePolygonVertices(vertices), [vertices]);
   const valid = issues.length === 0;
-  const center = useMemo20(() => valid ? polygonCenter(vertices) : null, [valid, vertices]);
-  const fillGeometry = useMemo20(
+  const center = useMemo21(() => valid ? polygonCenter(vertices) : null, [valid, vertices]);
+  const fillGeometry = useMemo21(
     () => valid && center ? makeFillGeometry(vertices, center) : null,
     [center, valid, vertices]
   );
-  const strokePoints = useMemo20(
+  const strokePoints = useMemo21(
     () => valid && center ? makeStrokePositions(vertices, center) : null,
     [center, valid, vertices]
   );
@@ -10929,7 +10961,7 @@ function PolygonHotspot({
 }
 
 // src/hotspot/polyline-hotspot.tsx
-import { useEffect as useEffect30, useMemo as useMemo21, useRef as useRef29 } from "react";
+import { useEffect as useEffect30, useMemo as useMemo22, useRef as useRef29 } from "react";
 import {
   MathUtils as MathUtils8,
   Matrix4 as Matrix44,
@@ -11053,10 +11085,10 @@ function PolylineHotspot({
   onInvalid,
   ...anchorProps
 }) {
-  const issues = useMemo21(() => validatePolylineVertices(vertices), [vertices]);
+  const issues = useMemo22(() => validatePolylineVertices(vertices), [vertices]);
   const valid = issues.length === 0;
-  const center = useMemo21(() => valid ? polylineCenter(vertices) : null, [valid, vertices]);
-  const linePoints = useMemo21(
+  const center = useMemo22(() => valid ? polylineCenter(vertices) : null, [valid, vertices]);
+  const linePoints = useMemo22(
     () => valid && center ? makeLinePositions(vertices, center) : null,
     [center, valid, vertices]
   );
@@ -12213,7 +12245,7 @@ function IframeHotspot({
               "iframe",
               {
                 allow,
-                className: "block h-full w-full border-0",
+                className: "pano-iframe-hotspot",
                 loading,
                 onError: (event) => onError?.(event.nativeEvent),
                 onLoad,