feat: preload adjacent media in streams

js/src/features/particles/stream-view.tsx

@@ -18,6 +18,7 @@ import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbP
 import { WindowControls } from "@/components/window-controls";
 import { formatDistanceToNow } from "@/lib/time-utils";
 import { useStreamPlayback } from "@/hooks/use-stream-playback";
+import { usePrefetchAdjacentMedia } from "@/hooks/use-prefetch-adjacent-media";
 
 function getParticleDisplayName(particle: Particle): string {
   switch (particle.type) {
@@ -113,6 +114,8 @@ export function StreamView({ path, streamParticle }: StreamViewProps) {
     resume,
   } = useStreamPlayback(streamParticle, path);
 
+  usePrefetchAdjacentMedia(children, currentIndex);
+
   const [composeActive, setComposeActive] = useState(false);
   const [progress, setProgress] = useState(0);
 

js/src/hooks/use-download-url.ts

@@ -6,5 +6,6 @@ export function useDownloadUrl(objectId?: string) {
     queryKey: ["download-url", objectId],
     queryFn: () => apiClient.getParticleDownloadUrl(objectId!),
     enabled: !!objectId,
+    staleTime: 1000 * 60 * 60, // 1 hour — signed URLs valid for 24h
   });
 }

js/src/hooks/use-prefetch-adjacent-media.ts

@@ -0,0 +1,47 @@
+import { useEffect } from "react";
+import { preload } from "react-dom";
+import { useQueryClient } from "@tanstack/react-query";
+import type { Particle } from "@/api/types";
+import { apiClient } from "@/api/client";
+
+// TODO: verify that caching is actually working by slowing down our network to simulate
+/**
+ * Prefetches download URLs and warms the browser cache for adjacent media particles.
+ */
+export function usePrefetchAdjacentMedia(
+  children: Particle[],
+  currentIndex: number,
+) {
+  const queryClient = useQueryClient();
+
+  useEffect(() => {
+    const adjacentIndices = [currentIndex - 1, currentIndex + 1];
+    const mediaParticles = adjacentIndices
+      .filter((i) => i >= 0 && i < children.length)
+      .map((i) => children[i])
+      .filter(
+        (p): p is Extract<Particle, { type: "media" }> => p.type === "media",
+      );
+
+    for (const particle of mediaParticles) {
+      const objectId = particle.properties.object_id;
+      const isAudio = particle.properties.mime_type?.startsWith("audio/");
+
+      queryClient
+        .prefetchQuery({
+          queryKey: ["download-url", objectId],
+          queryFn: () => apiClient.getParticleDownloadUrl(objectId),
+          staleTime: 1000 * 60 * 60,
+        })
+        .then(() => {
+          const url = queryClient.getQueryData<string>([
+            "download-url",
+            objectId,
+          ]);
+          if (url) {
+            preload(url, { as: isAudio ? "audio" : "video" });
+          }
+        });
+    }
+  }, [children, currentIndex, queryClient]);
+}