@vanillaskyai/video 0.10.7 → 0.10.9

package/CHANGELOG.md

@@ -4,6 +4,24 @@ VanillaSky follows semantic versioning. This changelog begins with the 0.1 beta.
 
 ## Unreleased
 
+## 0.10.9
+
+- Use essential subject hints and explicit exclusions when selecting starter Pexels footage, and isolate cached selections by those hints. Metadata-free results remain unverified provider-ranked fallbacks.
+
+- Forward bounded optional subject/activity hints to Pexels resolvers from the existing planning stream, without adding fields to emitted scenes or AI-video requests.
+
+- Clarify beginner instructions and condition-dependent advice, and retain essential subjects and activities in Pexels search planning.
+
+## 0.10.8
+
+- Reassert a requested pause if native video playback starts late, preserving footage during delayed narration and keeping viewer pauses in place.
+
+- Distinguish decode errors, frame-readiness timeouts and stalled footage in the local chat diagnostic log without retaining media URLs or user content.
+
+- Correct starter guidance for separate footage modes and remove obsolete planner logs that included raw model output.
+- Prepare the next compatible mobile video while the current scene plays, retaining its decoded element across cuts and limiting mounted footage to the active and next scenes.
+- Observe cached video frames on mount so a missed loading event cannot delay genuine stall recovery.
+
 ## 0.10.7
 
 - Reuse the first presented video frame at scene handoffs so a second readiness observation cannot briefly interrupt continuous narration.

package/dist/check-runtime.js

@@ -1,8 +1,8 @@
 import {
   VideoFrame
-} from "./chunk-24TCMDAA.js";
+} from "./chunk-KUCEOG2L.js";
+import "./chunk-5JBMYQP6.js";
 import "./chunk-224QNWRA.js";
-import "./chunk-OOBT4X46.js";
 import "./chunk-SPVTJH3F.js";
 import "./chunk-R3XAOMKP.js";
 import "./chunk-73NTSFFI.js";

package/dist/{chunk-OBRKB7PL.js → chunk-J7EGPURK.js}

@@ -1,13 +1,60 @@
 import {
   darken,
   resolveTokens,
+  useExternalVideoBackdrop,
   useMediaAudio,
   useMediaFailure,
   useNarrationPreroll
-} from "./chunk-OOBT4X46.js";
+} from "./chunk-5JBMYQP6.js";
+import {
+  resolveMediaType
+} from "./chunk-224QNWRA.js";
 
-// src/visual-system/scene-templates/scene-video-backdrop.tsx
-import { useCallback, useEffect, useRef, useState } from "react";
+// src/visual-system/motion/curves.ts
+function interpolate(value, inputRange, outputRange, options) {
+  const { easing, extrapolateLeft = "extend", extrapolateRight = "extend" } = options ?? {};
+  let i = 0;
+  for (; i < inputRange.length - 2; i++) {
+    if (value < inputRange[i + 1]) break;
+  }
+  const inputMin = inputRange[i];
+  const inputMax = inputRange[i + 1];
+  const outputMin = outputRange[i];
+  const outputMax = outputRange[i + 1];
+  let t = inputMax === inputMin ? 0 : (value - inputMin) / (inputMax - inputMin);
+  if (t < 0 && extrapolateLeft === "clamp") t = 0;
+  if (t > 1 && extrapolateRight === "clamp") t = 1;
+  if (easing && t >= 0 && t <= 1) {
+    t = easing(t);
+  }
+  return outputMin + t * (outputMax - outputMin);
+}
+function spring(progress, config) {
+  if (progress <= 0) return 0;
+  if (progress >= 1) {
+    const { damping: damping2 = 26 } = config ?? {};
+    if (damping2 >= 20) return 1;
+  }
+  const { damping = 26, stiffness = 170, mass = 1 } = config ?? {};
+  const omega = Math.sqrt(stiffness / mass);
+  const zeta = damping / (2 * Math.sqrt(stiffness * mass));
+  const t = progress * 3.5;
+  let value;
+  if (zeta < 1) {
+    const omegaD = omega * Math.sqrt(1 - zeta * zeta);
+    value = 1 - Math.exp(-zeta * omega * t) * (Math.cos(omegaD * t) + zeta * omega / omegaD * Math.sin(omegaD * t));
+  } else if (zeta === 1) {
+    value = 1 - Math.exp(-omega * t) * (1 + omega * t);
+  } else {
+    const s1 = -omega * (zeta + Math.sqrt(zeta * zeta - 1));
+    const s2 = -omega * (zeta - Math.sqrt(zeta * zeta - 1));
+    value = 1 + (s1 * Math.exp(s2 * t) - s2 * Math.exp(s1 * t)) / (s2 - s1);
+  }
+  return value;
+}
+
+// src/visual-system/scene-templates/scene-background.tsx
+import { useEffect as useEffect2, useState as useState2 } from "react";
 
 // src/visual-system/scene-templates/color-utils.ts
 import React from "react";
@@ -83,49 +130,6 @@ var BrandGradientOverlay = ({ style: globalStyle, progress, sceneDuration, seed
   });
 };
 
-// src/visual-system/motion/curves.ts
-function interpolate(value, inputRange, outputRange, options) {
-  const { easing, extrapolateLeft = "extend", extrapolateRight = "extend" } = options ?? {};
-  let i = 0;
-  for (; i < inputRange.length - 2; i++) {
-    if (value < inputRange[i + 1]) break;
-  }
-  const inputMin = inputRange[i];
-  const inputMax = inputRange[i + 1];
-  const outputMin = outputRange[i];
-  const outputMax = outputRange[i + 1];
-  let t = inputMax === inputMin ? 0 : (value - inputMin) / (inputMax - inputMin);
-  if (t < 0 && extrapolateLeft === "clamp") t = 0;
-  if (t > 1 && extrapolateRight === "clamp") t = 1;
-  if (easing && t >= 0 && t <= 1) {
-    t = easing(t);
-  }
-  return outputMin + t * (outputMax - outputMin);
-}
-function spring(progress, config) {
-  if (progress <= 0) return 0;
-  if (progress >= 1) {
-    const { damping: damping2 = 26 } = config ?? {};
-    if (damping2 >= 20) return 1;
-  }
-  const { damping = 26, stiffness = 170, mass = 1 } = config ?? {};
-  const omega = Math.sqrt(stiffness / mass);
-  const zeta = damping / (2 * Math.sqrt(stiffness * mass));
-  const t = progress * 3.5;
-  let value;
-  if (zeta < 1) {
-    const omegaD = omega * Math.sqrt(1 - zeta * zeta);
-    value = 1 - Math.exp(-zeta * omega * t) * (Math.cos(omegaD * t) + zeta * omega / omegaD * Math.sin(omegaD * t));
-  } else if (zeta === 1) {
-    value = 1 - Math.exp(-omega * t) * (1 + omega * t);
-  } else {
-    const s1 = -omega * (zeta + Math.sqrt(zeta * zeta - 1));
-    const s2 = -omega * (zeta - Math.sqrt(zeta * zeta - 1));
-    value = 1 + (s1 * Math.exp(s2 * t) - s2 * Math.exp(s1 * t)) / (s2 - s1);
-  }
-  return value;
-}
-
 // src/visual-system/scene-templates/background-effect.ts
 var DIRECTIONS = ["right", "left", "up", "down"];
 function getKenBurnsTransform(progress, direction) {
@@ -223,6 +227,7 @@ function resolveMediaPosition(value) {
 }
 
 // src/visual-system/scene-templates/scene-video-backdrop.tsx
+import { useCallback, useEffect, useRef, useState } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 var SceneVideoBackdrop = ({
   mediaUrl,
@@ -237,9 +242,6 @@ var SceneVideoBackdrop = ({
   muted,
   volume,
   playbackId = mediaUrl,
-  retainPoster = false,
-  persistent = false,
-  preparedPoster,
   onReady,
   onError
 }) => {
@@ -261,11 +263,11 @@ var SceneVideoBackdrop = ({
   const videoPresentationKey = `${playbackId}\0${mediaUrl}`;
   const presentationRef = useRef({ key: videoPresentationKey, playing: isPlaying });
   presentationRef.current = { key: videoPresentationKey, playing: isPlaying };
-  const unavailable = () => {
+  const unavailable = (reason = "playback-error") => {
     if (presentationRef.current.key === videoPresentationKey && presentationRef.current.playing) {
       setExhaustedKey(videoPresentationKey);
       onError?.();
-      reportMediaFailure?.();
+      reportMediaFailure?.(reason);
     }
   };
   useEffect(() => {
@@ -306,7 +308,7 @@ var SceneVideoBackdrop = ({
     const fail = () => {
       if (!stopped) {
         stopped = true;
-        unavailable();
+        unavailable(awaitingFirstFrame ? "frame-readiness-timeout" : "stalled-media");
       }
     };
     let deadline = setTimeout(fail, awaitingFirstFrame ? 8e3 : 1e3);
@@ -318,6 +320,39 @@ var SceneVideoBackdrop = ({
       if (frame !== void 0) video.cancelVideoFrameCallback?.(frame);
     };
   }, [waitingKey, videoPresentationKey, isPlaying]);
+  const onReadyRef = useRef(onReady);
+  onReadyRef.current = onReady;
+  useEffect(() => {
+    const video = videoRef.current;
+    if (!video) return;
+    let stopped = false;
+    let frame;
+    const markPresented = () => {
+      if (stopped || !video.isConnected || presentationRef.current.key !== videoPresentationKey || video.getAttribute("src") !== mediaUrl || video.currentSrc !== video.src) return false;
+      presentedVideoUrl.current = mediaUrl;
+      video.dispatchEvent(new Event("vanillasky:video-frame-presented", { bubbles: true }));
+      onReadyRef.current?.();
+      setDecodedVideoUrl(mediaUrl);
+      stopped = true;
+      return true;
+    };
+    const observe = () => {
+      if (stopped || frame !== void 0) return;
+      if (video.requestVideoFrameCallback) {
+        frame = video.requestVideoFrameCallback(() => {
+          frame = void 0;
+          if (!markPresented()) observe();
+        });
+      } else if (video.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA) markPresented();
+    };
+    video.addEventListener("loadeddata", observe);
+    observe();
+    return () => {
+      stopped = true;
+      video.removeEventListener("loadeddata", observe);
+      if (frame !== void 0) video.cancelVideoFrameCallback?.(frame);
+    };
+  }, [mediaUrl, videoPresentationKey]);
   const fitDuration = useCallback((video) => {
     video.playbackRate = (resolvedMuted || video.preservesPitch === true) && sceneDuration && Number.isFinite(video.duration) && video.duration > 0 ? Math.max(0.75, Math.min(1, video.duration / (sceneDuration + 0.2))) : 1;
   }, [resolvedMuted, sceneDuration]);
@@ -331,7 +366,7 @@ var SceneVideoBackdrop = ({
       return;
     }
     video.currentTime = 0;
-    void video.play().catch(unavailable);
+    void video.play().catch(() => unavailable());
   };
   useEffect(() => {
     const video = videoRef.current;
@@ -366,16 +401,21 @@ var SceneVideoBackdrop = ({
     }
     if (startedPlaybackId.current === playbackId) {
       if (video.ended) continueMotion(video);
-      else void video.play().catch(unavailable);
+      else void video.play().catch(() => unavailable());
       return;
     }
     const changingSource = startedVideoUrl.current !== void 0 && startedVideoUrl.current !== mediaUrl;
     fitDuration(video);
     if (!changingSource && video.currentTime > 0) video.currentTime = 0;
-    video.play().catch(unavailable);
+    video.play().catch(() => unavailable());
     startedVideoUrl.current = mediaUrl;
     startedPlaybackId.current = playbackId;
   }, [isPlaying, mediaUrl, playbackId, rewindPreroll]);
+  const enforceRequestedPause = (event) => {
+    if (presentationRef.current.playing) return;
+    event.currentTarget.pause();
+    if (rewindPreroll && event.currentTarget.currentTime > 0) event.currentTarget.currentTime = 0;
+  };
   const mediaStyle = {
     position: "absolute",
     inset: 0,
@@ -384,59 +424,9 @@ var SceneVideoBackdrop = ({
     objectFit: "cover",
     objectPosition: resolvedPosition,
     transform: bgTransform.transform,
-    transformOrigin: bgTransform.transformOrigin,
-    zIndex: persistent ? 1 : void 0
+    transformOrigin: bgTransform.transformOrigin
   };
-  const preparedPosition = preparedPoster ? resolveMediaPosition(preparedPoster.mediaPosition) : resolvedPosition;
-  const preparedTransform = getBackgroundTransform(preparedPoster?.backgroundEffect, 0, 0);
-  const posterPlanes = [
-    ...persistent && mediaPoster ? [{
-      presentationKey: videoPresentationKey,
-      mediaPoster,
-      mediaPosition: resolvedPosition,
-      transform: bgTransform.transform,
-      transformOrigin: bgTransform.transformOrigin,
-      opacity: 1,
-      zIndex: 0,
-      role: "current"
-    }] : [],
-    ...preparedPoster && preparedPoster.presentationKey !== videoPresentationKey ? [{
-      presentationKey: preparedPoster.presentationKey,
-      mediaPoster: preparedPoster.mediaPoster,
-      mediaPosition: preparedPosition,
-      transform: preparedTransform.transform,
-      transformOrigin: preparedTransform.transformOrigin,
-      opacity: preparedPoster.opacity ?? 0,
-      zIndex: 2,
-      role: "prepared"
-    }] : []
-  ];
   return /* @__PURE__ */ jsxs(Fragment, { children: [
-    posterPlanes.map((posterPlane) => /* @__PURE__ */ jsx(
-      "img",
-      {
-        src: posterPlane.mediaPoster,
-        alt: "",
-        "aria-hidden": "true",
-        draggable: false,
-        "data-video-poster-plane": posterPlane.role,
-        "data-video-poster-visible": posterPlane.opacity > 0 ? "true" : "false",
-        style: {
-          position: "absolute",
-          inset: 0,
-          width: "100%",
-          height: "100%",
-          objectFit: "cover",
-          objectPosition: posterPlane.mediaPosition,
-          transform: posterPlane.transform,
-          transformOrigin: posterPlane.transformOrigin,
-          zIndex: posterPlane.zIndex,
-          opacity: posterPlane.opacity,
-          pointerEvents: "none"
-        }
-      },
-      posterPlane.presentationKey
-    )),
     exhaustedKey === videoPresentationKey && /* @__PURE__ */ jsx(
       "div",
       {
@@ -451,44 +441,218 @@ var SceneVideoBackdrop = ({
       {
         ref: videoRef,
         src: mediaUrl,
-        poster: retainPoster || decodedVideoUrl !== mediaUrl ? mediaPoster || void 0 : void 0,
+        poster: decodedVideoUrl !== mediaUrl ? mediaPoster || void 0 : void 0,
         muted: resolvedMuted,
         loop: false,
         playsInline: true,
         preload: "auto",
         onLoadedMetadata: (event) => fitDuration(event.currentTarget),
         onEnded: (event) => continueMotion(event.currentTarget),
+        onPlay: enforceRequestedPause,
+        onPlaying: enforceRequestedPause,
         onWaiting: () => {
           if (isPlaying) setWaitingKey(videoPresentationKey);
         },
-        onLoadedData: (event) => {
-          const video = event.currentTarget;
-          const markPresented = () => {
-            if (!video.isConnected || presentationRef.current.key !== videoPresentationKey || video.getAttribute("src") !== mediaUrl || video.currentSrc !== video.src) return;
-            presentedVideoUrl.current = mediaUrl;
-            video.dispatchEvent(new Event("vanillasky:video-frame-presented", { bubbles: true }));
-            onReady?.();
-            if (!retainPoster) setDecodedVideoUrl(mediaUrl);
-          };
-          if (video.requestVideoFrameCallback) {
-            video.requestVideoFrameCallback(markPresented);
-            return;
-          }
-          markPresented();
-        },
         onError,
         "data-media-position": mediaPosition,
-        "data-video-backdrop": persistent ? "persistent" : "scene",
+        "data-video-backdrop": "scene",
         style: { ...mediaStyle, visibility: exhaustedKey === videoPresentationKey ? "hidden" : void 0 }
       }
     )
   ] });
 };
 
+// src/visual-system/scene-templates/scene-background.tsx
+import { Fragment as Fragment2, jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+function resolveMediaTreatment(value) {
+  return value === "none" || value === "subtle" || value === "text-safe" ? value : "cinematic";
+}
+var SCRIM_STOP_COUNT = 7;
+function smoothstep(t) {
+  return t * t * (3 - 2 * t);
+}
+function easedStops(peakAlpha, start, end, direction) {
+  const alphaAt = (t) => {
+    const eased = direction === "fade-out" ? 1 - smoothstep(t) : smoothstep(t);
+    return `rgba(0,0,0,${Number((peakAlpha * eased).toFixed(3))})`;
+  };
+  const stops = [];
+  if (start > 0) stops.push(`${alphaAt(0)} 0%`);
+  for (let i = 0; i < SCRIM_STOP_COUNT; i += 1) {
+    const t = i / (SCRIM_STOP_COUNT - 1);
+    const position = Number((start + (end - start) * t).toFixed(2));
+    stops.push(`${alphaAt(t)} ${position}%`);
+  }
+  if (end < 100) stops.push(`${alphaAt(1)} 100%`);
+  return stops.join(", ");
+}
+function getMediaTreatmentLayers(value, anchor = "full") {
+  const treatment = resolveMediaTreatment(value);
+  if (treatment === "none") return [];
+  const vignette = {
+    id: "vignette",
+    background: treatment === "subtle" ? `radial-gradient(ellipse at center, ${easedStops(0.28, 45, 100, "fade-in")})` : `radial-gradient(ellipse at center, ${easedStops(0.72, 32, 100, "fade-in")})`
+  };
+  if (treatment === "subtle") return [vignette];
+  const textSafe = treatment === "text-safe";
+  const layers = [vignette];
+  if (anchor !== "bottom") {
+    layers.push({
+      id: "center-scrim",
+      background: textSafe ? `radial-gradient(ellipse 92% 58% at 50% 50%, ${easedStops(0.46, 34, 90, "fade-out")})` : `radial-gradient(ellipse 88% 52% at 50% 50%, ${easedStops(0.26, 30, 88, "fade-out")})`
+    });
+  }
+  if (anchor !== "center") {
+    layers.push({
+      id: "bottom-scrim",
+      background: `linear-gradient(to top, ${easedStops(textSafe ? 0.64 : 0.5, 8, 100, "fade-out")})`,
+      style: { top: "55%" }
+    });
+  }
+  return layers;
+}
+function initialMediaPaint(wantsMedia, resolved, mediaUrl, mediaPoster) {
+  if (typeof window === "undefined") return "ready";
+  if (!wantsMedia) return "ready";
+  if (resolved === "video") return mediaPoster ? "ready" : "pending";
+  if (typeof Image === "undefined") return "ready";
+  const cached = new Image();
+  cached.src = mediaUrl;
+  return cached.complete && cached.naturalWidth > 0 ? "ready" : "pending";
+}
+function getMediaBackgroundProps(variables) {
+  return {
+    mediaUrl: String(variables.mediaUrl || ""),
+    mediaType: String(variables.mediaType || "auto"),
+    mediaPoster: String(variables.mediaPoster || ""),
+    mediaPosition: String(variables.mediaPosition || "center"),
+    mediaTreatment: String(variables.mediaTreatment || "cinematic")
+  };
+}
+var SceneBackground = ({
+  style,
+  progress,
+  sceneDuration,
+  width: _width,
+  // accepted for symmetry; not currently used in render
+  height: _height,
+  mediaUrl = "",
+  mediaType = "auto",
+  mediaPoster,
+  mediaPosition = "center",
+  mediaTreatment = "cinematic",
+  textAnchor = "full",
+  backgroundEffect,
+  seed,
+  isPlaying = true,
+  beatIntensity = 0
+}) => {
+  void _width;
+  void _height;
+  const resolved = resolveMediaType(mediaType, mediaUrl);
+  const wantsMedia = resolved !== "gradient" && !!mediaUrl;
+  const externalVideoBackdrop = useExternalVideoBackdrop();
+  const hasExternalVideoBackdrop = externalVideoBackdrop !== false && resolved === "video";
+  const externalVideoFailed = externalVideoBackdrop === "fallback" && resolved === "video";
+  const externalVideoReady = externalVideoBackdrop === "ready" && resolved === "video";
+  const [mediaPaint, setMediaPaint] = useState2(
+    () => initialMediaPaint(wantsMedia, resolved, mediaUrl, mediaPoster)
+  );
+  useEffect2(() => {
+    setMediaPaint(initialMediaPaint(wantsMedia, resolved, mediaUrl, mediaPoster));
+    if (!wantsMedia || resolved !== "photo") return;
+    if (typeof Image === "undefined") return;
+    let cancelled = false;
+    const probe = new Image();
+    probe.onload = () => {
+      if (!cancelled) setMediaPaint("ready");
+    };
+    probe.onerror = () => {
+      if (!cancelled) setMediaPaint("failed");
+    };
+    probe.src = mediaUrl;
+    if (probe.complete) setMediaPaint(probe.naturalWidth > 0 ? "ready" : "failed");
+    return () => {
+      cancelled = true;
+      probe.onload = null;
+      probe.onerror = null;
+    };
+  }, [mediaUrl, mediaPoster, resolved, wantsMedia]);
+  const showMedia = wantsMedia && mediaPaint !== "failed";
+  const showTreatment = wantsMedia && mediaPaint === "ready";
+  const resolvedPosition = resolveMediaPosition(mediaPosition);
+  const resolvedTreatment = resolveMediaTreatment(mediaTreatment);
+  const treatmentLayers = getMediaTreatmentLayers(resolvedTreatment, textAnchor);
+  const gradSeed = typeof seed === "number" ? seed : typeof seed === "string" ? seed.split("").reduce((acc, c) => acc + c.charCodeAt(0), 0) : 0;
+  const bgTransform = getBackgroundTransform(
+    backgroundEffect,
+    progress,
+    beatIntensity
+  );
+  return /* @__PURE__ */ jsxs2(Fragment2, { children: [
+    (!hasExternalVideoBackdrop || externalVideoFailed) && /* @__PURE__ */ jsx2(
+      BrandGradientOverlay,
+      {
+        style,
+        progress,
+        sceneDuration,
+        seed: gradSeed
+      }
+    ),
+    showMedia && !hasExternalVideoBackdrop && (resolved === "video" ? /* @__PURE__ */ jsx2(
+      SceneVideoBackdrop,
+      {
+        mediaUrl,
+        mediaPoster,
+        mediaPosition,
+        backgroundEffect,
+        progress,
+        sceneDuration,
+        beatIntensity,
+        isPlaying,
+        onReady: () => setMediaPaint("ready"),
+        onError: () => setMediaPaint("failed")
+      }
+    ) : /* @__PURE__ */ jsx2(
+      "img",
+      {
+        src: mediaUrl,
+        alt: "",
+        "aria-hidden": "true",
+        draggable: false,
+        "data-media-position": mediaPosition,
+        style: {
+          position: "absolute",
+          inset: 0,
+          transform: bgTransform.transform,
+          transformOrigin: bgTransform.transformOrigin,
+          width: "100%",
+          height: "100%",
+          objectFit: "cover",
+          objectPosition: resolvedPosition
+        }
+      }
+    )),
+    (hasExternalVideoBackdrop ? externalVideoReady : showTreatment) && !externalVideoFailed && treatmentLayers.map((layer) => /* @__PURE__ */ jsx2(
+      "div",
+      {
+        "data-media-treatment": resolvedTreatment,
+        "data-media-overlay": layer.id,
+        style: {
+          position: "absolute",
+          inset: 0,
+          background: layer.background,
+          pointerEvents: "none",
+          ...layer.style
+        }
+      },
+      layer.id
+    ))
+  ] });
+};
+
 export {
-  BrandGradientOverlay,
   spring,
-  getBackgroundTransform,
-  resolveMediaPosition,
-  SceneVideoBackdrop
+  getMediaBackgroundProps,
+  SceneBackground
 };