@anthusai/papyrus 1.0.0-next.51 → 1.0.0-next.52

package/components/article-video.tsx

@@ -7,6 +7,8 @@ import { resolveThemedVideoSrc } from "../lib/themed-image";
 import { useResolvedPapyrusTheme } from "./use-resolved-papyrus-theme";
 import { getSiteBrand } from "../lib/site-brand";
 import { normalizeDevPreviewDsl, type VideoScriptRef } from "../lib/video-script";
+import { useNearViewport } from "./use-near-viewport";
+import { planVideoLoading, videoElementKey } from "../lib/video-loading";
 import { resolveVideoMode, resolveVideoModeFromEnv, type VideoMode } from "../lib/video-mode";
 
 type ArticleVideoFigureProps = {
@@ -18,6 +20,7 @@ type ArticleVideoFigureProps = {
 };
 
 const PREVIEW_STORAGE_PREFIX = "papyrus-video-preview:";
+const VIDEO_LOAD_ROOT_MARGIN = "200px 0px";
 
 export function ArticleVideoFigure({
   video,
@@ -34,6 +37,8 @@ export function ArticleVideoFigure({
   const [previewReady, setPreviewReady] = useState(false);
   const iframeRef = useRef<HTMLIFrameElement>(null);
   const videoRef = useRef<HTMLVideoElement>(null);
+  const figureRef = useRef<HTMLElement>(null);
+  const isNearViewport = useNearViewport(figureRef, VIDEO_LOAD_ROOT_MARGIN);
   const isFramed = getSiteBrand().videoPlayer === "framed";
 
   useEffect(() => {
@@ -44,6 +49,12 @@ export function ArticleVideoFigure({
   // Match SSR to the default dark MP4 in `video.src` until after hydration.
   const resolvedTheme = hasHydrated ? theme : "dark";
   const src = resolveThemedVideoSrc(video.src, video.themeVariants, resolvedTheme);
+  const loadingPlan = planVideoLoading({
+    hasHydrated,
+    isNearViewport,
+    hasPoster: Boolean(video.posterSrc),
+  });
+  const videoKey = videoElementKey(loadingPlan.attachSource, src);
   const usePreview = videoMode === "preview" && Boolean(videoScript?.dsl);
   const previewDsl = videoScript?.dsl
     ? normalizeDevPreviewDsl(videoScript.dsl, getSiteBrand().video?.sceneComponents)
@@ -191,6 +202,7 @@ export function ArticleVideoFigure({
   if (isFramed) {
     return (
       <figure
+        ref={figureRef}
         className={`${figureClassName} article-video--framed`}
         data-media-type="video"
         data-video-theme={resolvedTheme}
@@ -200,11 +212,11 @@ export function ArticleVideoFigure({
           <video
             ref={videoRef}
             playsInline
-            preload="metadata"
+            preload={loadingPlan.preload}
             poster={video.posterSrc}
             aria-label={video.alt}
             className="article-video__player"
-            key={hasHydrated ? src : "ssr"}
+            key={videoKey}
             onPlay={() => setIsPlaying(true)}
             onPause={() => setIsPlaying(false)}
             onEnded={() => setIsPlaying(false)}
@@ -214,7 +226,7 @@ export function ArticleVideoFigure({
               if (Number.isFinite(nextDuration) && nextDuration > 0) setDuration(nextDuration);
             }}
           >
-            <source src={src} type="video/mp4" />
+            {loadingPlan.attachSource ? <source src={src} type="video/mp4" /> : null}
           </video>
         </div>
         {framedControls}
@@ -226,17 +238,17 @@ export function ArticleVideoFigure({
   }
 
   return (
-    <figure className={figureClassName} data-media-type="video" data-video-theme={resolvedTheme} data-video-mode={videoMode}>
+    <figure ref={figureRef} className={figureClassName} data-media-type="video" data-video-theme={resolvedTheme} data-video-mode={videoMode}>
       <video
         controls
         playsInline
-        preload="metadata"
+        preload={loadingPlan.preload}
         poster={video.posterSrc}
         aria-label={video.alt}
         className="article-video__player"
-        key={hasHydrated ? src : "ssr"}
+        key={videoKey}
       >
-        <source src={src} type="video/mp4" />
+        {loadingPlan.attachSource ? <source src={src} type="video/mp4" /> : null}
       </video>
       {video.caption ? <figcaption>{video.caption}</figcaption> : null}
       {video.credit ? <p className="article-video__credit">{video.credit}</p> : null}

package/components/use-near-viewport.ts

@@ -0,0 +1,30 @@
+"use client";
+
+import { useEffect, useState, type RefObject } from "react";
+
+export function useNearViewport(targetRef: RefObject<Element | null>, rootMargin: string): boolean {
+  const [isNearViewport, setIsNearViewport] = useState(false);
+
+  useEffect(() => {
+    if (isNearViewport) return;
+    const target = targetRef.current;
+    if (!target) return;
+    if (typeof IntersectionObserver === "undefined") {
+      setIsNearViewport(true);
+      return;
+    }
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (entries.some((entry) => entry.isIntersecting)) {
+          setIsNearViewport(true);
+          observer.disconnect();
+        }
+      },
+      { rootMargin },
+    );
+    observer.observe(target);
+    return () => observer.disconnect();
+  }, [isNearViewport, rootMargin, targetRef]);
+
+  return isNearViewport;
+}

package/lib/video-loading.ts

@@ -0,0 +1,22 @@
+export type VideoPreload = "none" | "metadata";
+
+export type VideoLoadingPlan = {
+  attachSource: boolean;
+  preload: VideoPreload;
+};
+
+export type VideoLoadingInput = {
+  hasHydrated: boolean;
+  isNearViewport: boolean;
+  hasPoster: boolean;
+};
+
+export function planVideoLoading({ hasHydrated, isNearViewport, hasPoster }: VideoLoadingInput): VideoLoadingPlan {
+  const attachSource = hasHydrated && isNearViewport;
+  const preload: VideoPreload = attachSource && !hasPoster ? "metadata" : "none";
+  return { attachSource, preload };
+}
+
+export function videoElementKey(attachSource: boolean, resolvedSource: string): string {
+  return attachSource ? resolvedSource : "unattached";
+}

package/package.json

@@ -127,6 +127,7 @@
     "./components/ui/tooltip": "./components/ui/tooltip.tsx",
     "./components/use-blog-header-obstacles": "./components/use-blog-header-obstacles.ts",
     "./components/use-brand-fonts-ready": "./components/use-brand-fonts-ready.ts",
+    "./components/use-near-viewport": "./components/use-near-viewport.ts",
     "./components/use-resolved-papyrus-theme": "./components/use-resolved-papyrus-theme.ts",
     "./components/use-rhythm-overlay": "./components/use-rhythm-overlay.ts",
     "./lib/amplify-outputs-guard": "./lib/amplify-outputs-guard.ts",
@@ -224,6 +225,7 @@
     "./lib/staging-preview-object": "./lib/staging-preview-object.ts",
     "./lib/themed-image": "./lib/themed-image.ts",
     "./lib/utils": "./lib/utils.ts",
+    "./lib/video-loading": "./lib/video-loading.ts",
     "./lib/video-mode": "./lib/video-mode.ts",
     "./lib/video-script": "./lib/video-script.ts",
     "./renderers/markus/index": "./renderers/markus/index.ts",
@@ -306,7 +308,7 @@
       "optional": true
     }
   },
-  "version": "1.0.0-next.51",
+  "version": "1.0.0-next.52",
   "dependencies": {
     "@aws-amplify/adapter-nextjs": "^1.7.3",
     "@aws-sdk/client-cognito-identity-provider": "3.1045.0",

package/routes.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.0-next.51",
+  "version": "1.0.0-next.52",
   "routes": [
     {
       "file": "app/%5F_preview/[[...path]]/route.ts",