@hyperframes/studio 0.8.139 → 0.8.140

package/src/hooks/useExternalFileChangeCoordinator.ts

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useRef, useState, type MutableRefObject } from "react";
 import {
-  mergeFileChangeAffectedCompositions,
+  mergeFileChangePayloads,
   readFileChangeAffectedCompositions,
   readFileChangeAffectsPreview,
   readFileChangeField,
@@ -125,14 +125,18 @@ function decodeFileChange(delivery: unknown): unknown {
   }
 }
 
-/**
- * The production transport. vitest defines `import.meta.hot`, so the selection
- * below never reaches this rung under test; the rung itself is exported so a test
- * can drive a real `MessageEvent` through the listener it registers.
- */
-export function sseFileChangeChannel(onDelivery: (delivery: unknown) => void): () => void {
+export function sseFileChangeChannel(
+  onDelivery: (delivery: unknown) => void,
+  onReconnect: () => void,
+): () => void {
   const eventSource = new EventSource("/api/events");
   eventSource.addEventListener("file-change", onDelivery);
+  // Reopening the stream does not replay changes missed during a disconnect.
+  let opened = false;
+  eventSource.addEventListener("open", () => {
+    if (opened) onReconnect();
+    opened = true;
+  });
   return () => eventSource.close();
 }
 
@@ -168,18 +172,19 @@ export function useExternalFileChangeCoordinator({
   const generationRef = useRef(0);
   const mountedRef = useRef(true);
   const lastEventIdentityRef = useRef<string | null>(null);
-  const blockedRef = useRef(blocked);
+  const blockedRef = useRef<ExternalFileChangeBlockedState | null>(null);
   const snapshotWriteTailRef = useRef<Promise<void>>(Promise.resolve());
   const drainingRef = useRef(false);
   const pendingPayloadRef = useRef<{ payload: unknown } | null>(null);
-  blockedRef.current = blocked;
-  // A newer blocked change replaces the held one, so it inherits the thumbnails the held one owed.
+  // A newer blocked change replaces the held one, so it inherits what the held one owed.
   const setBlocked = useCallback((next: ExternalFileChangeBlockedState | null) => {
-    setBlockedState((held) =>
+    const held = blockedRef.current;
+    const current =
       next && held
-        ? { ...next, payload: mergeFileChangeAffectedCompositions(held.payload, next.payload) }
-        : next,
-    );
+        ? { ...next, payload: mergeFileChangePayloads(held.payload, next.payload) }
+        : next;
+    blockedRef.current = current;
+    setBlockedState(current);
   }, []);
 
   useEffect(() => {
@@ -190,6 +195,10 @@ export function useExternalFileChangeCoordinator({
     };
   }, []);
 
+  useEffect(() => {
+    pendingPayloadRef.current = null;
+  }, [projectId]);
+
   useEffect(() => {
     generationRef.current += 1;
     setBlocked(null);
@@ -240,8 +249,12 @@ export function useExternalFileChangeCoordinator({
     };
   }, [loadConflictSnapshot, projectId, recoveryFilePath, setBlocked]);
 
-  const reloadAcceptedGeneration = useCallback(
-    (path: string, affectsPreview = true) => {
+  // What a settled change owes: thumbnails (unless its own write's echo brings them), then reloads.
+  const deliverOwed = useCallback(
+    (owed: unknown, accept = true) => {
+      const path = readStudioFileChangePath(owed) ?? ".";
+      const affectsPreview = readFileChangeAffectsPreview(owed);
+      if (accept) onAcceptedPersistedFileChange(path, readFileChangeAffectedCompositions(owed));
       logReload(affectsPreview ? "reload" : "file-tree only", {
         path,
         by: "external-change coordinator",
@@ -255,7 +268,7 @@ export function useExternalFileChangeCoordinator({
       // a watcher event the SSE never delivered).
       void refreshFileTree?.();
     },
-    [reloadPreview, reloadSdkSession, refreshFileTree],
+    [onAcceptedPersistedFileChange, reloadPreview, reloadSdkSession, refreshFileTree],
   );
 
   const persistSnapshotInOrder = useCallback(async (write: () => Promise<void>) => {
@@ -274,21 +287,28 @@ export function useExternalFileChangeCoordinator({
       if (!path) return;
 
       const generation = ++generationRef.current;
+      const savingPath = getPendingCandidate?.()?.path;
       const result = await drainPendingChanges();
       if (!mountedRef.current || generation !== generationRef.current) return;
 
       if (result.status === "clean") {
         const previousBlocked = blockedRef.current;
-        if (previousBlocked?.status === "failed" && deleteConflictSnapshot) {
+        // Only saving the failed draft's file retires its copy; restored drafts are never queued.
+        if (
+          previousBlocked?.status === "failed" &&
+          !previousBlocked.recovered &&
+          previousBlocked.path === savingPath &&
+          deleteConflictSnapshot
+        ) {
           try {
-            await deleteConflictSnapshot(projectId!, path);
+            await deleteConflictSnapshot(projectId!, previousBlocked.path);
           } catch (error) {
             if (mountedRef.current && generation === generationRef.current) {
               setBlocked({
                 ...previousBlocked,
                 generation,
                 error,
-                payload: mergeFileChangeAffectedCompositions(payload, previousBlocked.payload),
+                payload: mergeFileChangePayloads(payload, previousBlocked.payload),
               });
             }
             return;
@@ -296,27 +316,30 @@ export function useExternalFileChangeCoordinator({
         }
         if (!mountedRef.current || generation !== generationRef.current) return;
         setBlocked(null);
-        const owed = previousBlocked
-          ? mergeFileChangeAffectedCompositions(previousBlocked.payload, payload)
-          : payload;
-        onAcceptedPersistedFileChange(path, readFileChangeAffectedCompositions(owed));
-        reloadAcceptedGeneration(path, readFileChangeAffectsPreview(payload));
+        const restored = previousBlocked?.status === "failed" && previousBlocked.recovered;
+        deliverOwed(
+          previousBlocked && !restored
+            ? mergeFileChangePayloads(previousBlocked.payload, payload)
+            : payload,
+        );
         return;
       }
-      const content = readFileChangeContent(payload);
       if (result.status === "failed") {
+        // The draft names the file to recover; the payload stays the scope to reload.
         const candidate = getPendingCandidate?.();
-        const studioContent = candidate?.path === path ? candidate.content : null;
+        const failedPath = candidate?.path ?? (path === "." ? (recoveryFilePath ?? path) : path);
+        const studioContent = candidate?.content ?? null;
+        const external = failedPath === path ? payload : null;
         let error = result.error;
         if (studioContent != null && persistFailureSnapshot) {
           try {
             await persistSnapshotInOrder(() =>
               persistFailureSnapshot(
                 projectId!,
-                path,
+                failedPath,
                 studioContent,
-                readFileChangeVersion(payload),
-                content,
+                readFileChangeVersion(external),
+                readFileChangeContent(external),
                 result.error,
               ),
             );
@@ -333,7 +356,7 @@ export function useExternalFileChangeCoordinator({
         setBlocked({
           status: "failed",
           generation,
-          path,
+          path: failedPath,
           error,
           payload,
           studioContent,
@@ -348,7 +371,7 @@ export function useExternalFileChangeCoordinator({
         setBlocked({
           status: "failed",
           generation,
-          path,
+          path: result.error.filePath,
           error,
           payload,
           studioContent: result.error.attemptedContent,
@@ -365,14 +388,17 @@ export function useExternalFileChangeCoordinator({
       projectId,
       deleteConflictSnapshot,
       getPendingCandidate,
+      recoveryFilePath,
       persistConflictSnapshot,
       persistFailureSnapshot,
       persistSnapshotInOrder,
-      reloadAcceptedGeneration,
-      onAcceptedPersistedFileChange,
+      deliverOwed,
     ],
   );
 
+  const drainOnePendingRef = useRef(drainOnePending);
+  drainOnePendingRef.current = drainOnePending;
+
   const startDrainLoop = useCallback(async () => {
     if (drainingRef.current) return;
     drainingRef.current = true;
@@ -381,12 +407,12 @@ export function useExternalFileChangeCoordinator({
         const pending = pendingPayloadRef.current;
         if (!pending) break;
         pendingPayloadRef.current = null;
-        await drainOnePending(pending.payload);
+        await drainOnePendingRef.current(pending.payload);
       }
     } finally {
       drainingRef.current = false;
     }
-  }, [drainOnePending]);
+  }, []);
 
   const processChange = useCallback(
     // fallow-ignore-next-line complexity
@@ -439,8 +465,7 @@ export function useExternalFileChangeCoordinator({
         !readFileChangeAffectsPreview(payload);
       if (!waitingChangeOutranksThis) {
         pendingPayloadRef.current = {
-          payload:
-            waiting == null ? payload : mergeFileChangeAffectedCompositions(waiting, payload),
+          payload: waiting == null ? payload : mergeFileChangePayloads(waiting, payload),
         };
       }
       void startDrainLoop();
@@ -462,7 +487,8 @@ export function useExternalFileChangeCoordinator({
       import.meta.hot.on("hf:file-change", handler);
       return () => import.meta.hot?.off?.("hf:file-change", handler);
     }
-    return sseFileChangeChannel(handler);
+    const catchUp = () => processChangeRef.current({ path: "." });
+    return sseFileChangeChannel(handler, catchUp);
   }, []);
 
   const retry = useCallback(async () => {
@@ -489,18 +515,16 @@ export function useExternalFileChangeCoordinator({
       onUseExternalFile?.(path, external);
       await deleteConflictSnapshot?.(projectId, path);
       setBlocked(null);
-      onAcceptedPersistedFileChange(path, readFileChangeAffectedCompositions(current.payload));
-      reloadAcceptedGeneration(path, readFileChangeAffectsPreview(current.payload));
+      deliverOwed(current.payload);
     },
     [
       deleteConflictSnapshot,
       setBlocked,
       discardPendingChanges,
       onUseExternalFile,
-      onAcceptedPersistedFileChange,
       projectId,
       readProjectFile,
-      reloadAcceptedGeneration,
+      deliverOwed,
       resetSaveQueues,
     ],
   );
@@ -550,7 +574,10 @@ export function useExternalFileChangeCoordinator({
     resetSaveQueues?.();
     await deleteConflictSnapshot?.(projectId, conflict.filePath);
     setBlocked(null);
-    reloadAcceptedGeneration(conflict.filePath);
+    deliverOwed(
+      mergeFileChangePayloads(current.payload, { path: conflict.filePath, affectsPreview: true }),
+      readStudioFileChangePath(current.payload) !== conflict.filePath,
+    );
   }, [
     deleteConflictSnapshot,
     setBlocked,
@@ -558,7 +585,7 @@ export function useExternalFileChangeCoordinator({
     overwriteConflict,
     projectId,
     readProjectFile,
-    reloadAcceptedGeneration,
+    deliverOwed,
     resetSaveQueues,
   ]);
 

package/src/hooks/useMusicBeatAnalysis.ts

@@ -2,6 +2,7 @@ import { useEffect, useMemo, useRef } from "react";
 import { usePlayerStore } from "../player/store/playerStore";
 import { resolveBeatSourceTrack } from "../utils/timelineInspector";
 import { analyzeMusicFromUrl } from "@hyperframes/core/beats";
+import { whenTimelineIdle } from "../player/components/timelineMotion";
 import { useFileManagerContextOptional } from "../contexts/FileManagerContext";
 import { mergeUserBeats } from "../utils/beatEditing";
 import { getTimelineElementIndexes } from "../player/lib/timelineElementIndexes";
@@ -79,7 +80,7 @@ async function loadBeatAnalysis(
 ): Promise<{ analysis: MusicAnalysis; times: number[]; strengths: number[] } | null> {
   let promise = analysisCache.get(musicSrc);
   if (!promise) {
-    promise = analyzeMusicFromUrl(musicSrc);
+    promise = analyzeMusicFromUrl(musicSrc, { pause: whenTimelineIdle });
     cacheAnalysis(musicSrc, promise);
   }
   try {

package/src/hooks/useSdkSession.lifecycle.test.tsx

@@ -13,6 +13,7 @@ vi.mock("@hyperframes/sdk", () => ({
 import type { Composition } from "@hyperframes/sdk";
 import { useSdkSession, type SdkSessionHandle } from "./useSdkSession";
 import { usePlayerStore } from "../player/store/playerStore";
+import { notifyExternalFileReload } from "./externalFileReloadBus";
 
 vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
 
@@ -173,6 +174,25 @@ describe("useSdkSession ownership", () => {
     await act(async () => root.unmount());
     expect(published.dispose).toHaveBeenCalledOnce();
   });
+
+  it("reopens on a project-wide external change whatever composition it holds", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => response("INDEX")),
+    );
+    openComposition.mockImplementation(async () => fakeSession());
+    const root = createRoot(document.createElement("div"));
+    await act(async () => root.render(<Probe projectId="project-a" />));
+    await flushAsyncEffects();
+    expect(openComposition).toHaveBeenCalledOnce();
+    await act(async () => notifyExternalFileReload("film.html"));
+    await flushAsyncEffects();
+    expect(openComposition).toHaveBeenCalledOnce();
+    await act(async () => notifyExternalFileReload("."));
+    await flushAsyncEffects();
+    expect(openComposition).toHaveBeenCalledTimes(2);
+    act(() => root.unmount());
+  });
 });
 
 describe("useSdkSession unreachable project", () => {

package/src/hooks/useSdkSession.ts

@@ -409,7 +409,10 @@ export function useSdkSession(
   useEffect(
     () =>
       addExternalFileReloadListener((changedPath) => {
-        if (changedPath === activeCompPathRef.current) setReloadToken((token) => token + 1);
+        // "." is a project-wide change (a reconnect or a replaced folder): every session reloads.
+        if (changedPath === "." || changedPath === activeCompPathRef.current) {
+          setReloadToken((token) => token + 1);
+        }
       }),
     [],
   );

package/src/hooks/useThumbnailStripSize.test.tsx

@@ -7,6 +7,15 @@ import { NearScreenIntersectionObserver } from "./intersectionObserverTestUtils"
 import { MockResizeObserver, reportResize } from "./resizeObserverTestUtils";
 import { useThumbnailStripSize } from "./useThumbnailStripSize";
 
+const zoom = vi.hoisted(() => ({ previewing: false, listeners: new Set<() => void>() }));
+vi.mock("../player/components/timelineZoomInput", () => ({
+  isTimelineZoomPreviewing: () => zoom.previewing,
+  subscribeTimelineZoomPreview: (listener: () => void) => {
+    zoom.listeners.add(listener);
+    return () => zoom.listeners.delete(listener);
+  },
+}));
+
 Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
 
 it("does not re-render the strip when the observer reports the size it already holds", () => {
@@ -48,6 +57,62 @@ it("does not re-render the strip when the observer reports the size it already h
   }
 });
 
+it("measures a strip once a zoom preview ends, not while the preview scales it", () => {
+  const originalResizeObserver = globalThis.ResizeObserver;
+  globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+  const host = document.createElement("div");
+  document.body.append(host);
+  let width = 300;
+  Object.defineProperty(host, "clientWidth", { configurable: true, get: () => width });
+  Object.defineProperty(host, "clientHeight", { configurable: true, value: 40 });
+  const root = createRoot(host);
+  function Harness() {
+    const [size, ref] = useThumbnailStripSize();
+    return <div ref={ref}>{`${size.width}x${size.height}`}</div>;
+  }
+  try {
+    act(() => root.render(<Harness />));
+    zoom.previewing = true;
+    width = 600;
+    act(() => reportResize(600, 40));
+    expect(host.textContent).toBe("300x40");
+    zoom.previewing = false;
+    act(() => zoom.listeners.forEach((listener) => listener()));
+    expect(host.textContent).toBe("600x40");
+  } finally {
+    zoom.previewing = false;
+    act(() => root.unmount());
+    host.remove();
+    globalThis.ResizeObserver = originalResizeObserver;
+  }
+});
+
+it("measures again each time a preview is laid out, though nothing was read during it", () => {
+  const originalResizeObserver = globalThis.ResizeObserver;
+  globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+  const host = document.createElement("div");
+  document.body.append(host);
+  let width = 300;
+  Object.defineProperty(host, "clientWidth", { configurable: true, get: () => width });
+  Object.defineProperty(host, "clientHeight", { configurable: true, value: 40 });
+  const root = createRoot(host);
+  function Harness() {
+    const [size, ref] = useThumbnailStripSize();
+    return <div ref={ref}>{`${size.width}x${size.height}`}</div>;
+  }
+  try {
+    act(() => root.render(<Harness />));
+    // A zoom-out lays its target out mid-ease; the resize is reported only later.
+    width = 600;
+    act(() => zoom.listeners.forEach((listener) => listener()));
+    expect(host.textContent).toBe("600x40");
+  } finally {
+    act(() => root.unmount());
+    host.remove();
+    globalThis.ResizeObserver = originalResizeObserver;
+  }
+});
+
 describe("on a scroll", () => {
   const originalResizeObserver = globalThis.ResizeObserver;
   const originalIntersectionObserver = globalThis.IntersectionObserver;

package/src/hooks/useThumbnailStripSize.ts

@@ -1,5 +1,9 @@
 import { useCallback, useState } from "react";
 import { flushSync } from "react-dom";
+import {
+  isTimelineZoomPreviewing,
+  subscribeTimelineZoomPreview,
+} from "../player/components/timelineZoomInput";
 
 export interface StripSize {
   width: number;
@@ -24,7 +28,6 @@ const GAP_WARNING: IntersectionObserverInit & { scrollMargin: string } = {
   scrollMargin: `0px ${IN_VIEW_CHUNK_PX / 2}px`,
 };
 
-// A short strip keeps every tile, as before, so only long clips do work on a scroll.
 const SHORT_STRIP_MAX_PX = 8 * IN_VIEW_CHUNK_PX;
 const isShort = (width: number) => width <= SHORT_STRIP_MAX_PX;
 
@@ -62,6 +65,7 @@ let shared: {
   resize: ResizeObserver;
   presence: IntersectionObserver | null;
   gaps: IntersectionObserver | null;
+  stopZoomWatch: () => void;
 } | null = null;
 
 const offsetOf = (scroller: Element | null) =>
@@ -97,8 +101,23 @@ const read = (target: Element, strip: Strip) => {
 const commit = (updates: (readonly [Apply, Partial<StripSize>])[]) =>
   flushSync(() => updates.forEach(([apply, patch]) => apply(patch)));
 
+// A zoom preview scales the strips: reads wait, and each preview's layout re-measures them all.
+const remeasureAfterPreview = () => {
+  if (isTimelineZoomPreviewing()) return;
+  commit(
+    [...strips].map(
+      ([target, strip]) =>
+        [
+          strip.apply,
+          { width: target.clientWidth, height: target.clientHeight, ...read(target, strip) },
+        ] as const,
+    ),
+  );
+};
+
 const refresh = () => {
   frame = 0;
+  if (isTimelineZoomPreviewing()) return;
   const offsetsNow = new Map<Element | null, { x: number; y: number }>();
   const updates: (readonly [Apply, Partial<StripSize>])[] = [];
   for (const [target, strip] of strips) {
@@ -122,6 +141,7 @@ const scheduleRefresh = () => {
 };
 
 const measure = (entries: { target: Element; size?: { width: number; height: number } }[]) =>
+  isTimelineZoomPreviewing() ||
   commit(
     entries.flatMap(({ target, size }) => {
       const strip = strips.get(target);
@@ -153,6 +173,7 @@ function acquire() {
       gaps: observeIntersections(
         (entries) => entries.some((entry) => entry.isIntersecting) && scheduleRefresh(),
       ),
+      stopZoomWatch: subscribeTimelineZoomPreview(remeasureAfterPreview),
     };
     window.addEventListener("scroll", scheduleRefresh, { capture: true, passive: true });
   }
@@ -164,6 +185,7 @@ function release() {
   shared?.resize.disconnect();
   shared?.presence?.disconnect();
   shared?.gaps?.disconnect();
+  shared?.stopZoomWatch();
   shared = null;
   window.removeEventListener("scroll", scheduleRefresh, { capture: true });
   cancelAnimationFrame(frame);

package/src/index.ts

@@ -63,6 +63,7 @@ export {
 export { TimelineProvider, useTimelineContext } from "./player/components/TimelineProvider";
 export type { TimelineTheme } from "./player/components/timelineTheme";
 export { TRACK_H } from "./player/components/timelineLayout";
+export { currentTimelineRange, zoomTimelineToRange } from "./player/components/timelineZoomInput";
 export type { TimelineTrackPadding } from "./player/components/timelineLayout";
 export { displayTrackOrder } from "./player/components/useTimelineTrackDerivations";
 export { fadeHandleBoxes } from "./player/components/timelineClipFadeGeometry";

package/src/player/components/AudioWaveform.test.tsx

@@ -11,15 +11,98 @@ vi.mock("../../hooks/useThumbnailLease", () => ({
   useThumbnailLease: leaseSpy,
 }));
 
+// One observer serves every waveform; it reports each one near as it is watched, unless a test
+// reports by hand.
+const nearScreen = {
+  auto: true,
+  watched: [] as Element[],
+  report: (_target: Element, _near: boolean) => {},
+};
+globalThis.IntersectionObserver = class {
+  constructor(callback: IntersectionObserverCallback) {
+    nearScreen.report = (target, near) =>
+      callback(
+        [{ target, isIntersecting: near } as IntersectionObserverEntry],
+        this as unknown as IntersectionObserver,
+      );
+  }
+  observe(target: Element) {
+    nearScreen.watched.push(target);
+    if (nearScreen.auto) nearScreen.report(target, true);
+  }
+  unobserve() {}
+  disconnect() {}
+} as unknown as typeof IntersectionObserver;
+
+const EMPTY_STRIP = { width: 0, height: 0, inViewStart: 0, inViewEnd: 0 };
+const watchGap = vi.hoisted(() => vi.fn());
+const strip = vi.hoisted(() => ({
+  size: { width: 0, height: 0, inViewStart: 0, inViewEnd: 0 },
+  listeners: new Set<() => void>(),
+}));
+// The strip hook's own tests cover scrolls and moves; here it reports what the test sets.
+vi.mock("../../hooks/useThumbnailStripSize", async () => {
+  const { useSyncExternalStore } = await import("react");
+  const subscribe = (listener: () => void) => {
+    strip.listeners.add(listener);
+    return () => strip.listeners.delete(listener);
+  };
+  return {
+    useThumbnailStripSize: () => [
+      useSyncExternalStore(subscribe, () => strip.size),
+      () => {},
+      watchGap,
+    ],
+  };
+});
+
+const setStrip = (size: typeof EMPTY_STRIP) =>
+  act(() => {
+    strip.size = size;
+    strip.listeners.forEach((listener) => listener());
+  });
+
 import { AudioWaveform, drawWaveformCanvas } from "./AudioWaveform";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
+const mounted: Array<ReturnType<typeof createRoot>> = [];
+
 afterEach(() => {
-  leaseSpy.mockClear();
+  act(() => mounted.splice(0).forEach((root) => root.unmount()));
+  vi.restoreAllMocks();
+  vi.useRealTimers();
+  leaseSpy.mockReset();
+  leaseSpy.mockImplementation(() => ({ status: "loading" as const }));
+  strip.size = EMPTY_STRIP;
+  nearScreen.auto = true;
+  watchGap.mockClear();
   document.body.innerHTML = "";
 });
 
+/** Renders a ready waveform for a two-peak sound into `parent`. */
+function renderReadyWaveform(parent: HTMLElement = document.body) {
+  // One snapshot, as the lease returns, so a re-render alone does not redraw.
+  const ready = { status: "ready", value: { kind: "waveform", peaks: [0.5, 1] } } as never;
+  leaseSpy.mockImplementation(() => ready);
+  const host = document.createElement("div");
+  parent.append(host);
+  const root = createRoot(host);
+  mounted.push(root);
+  act(() => {
+    root.render(
+      <AudioWaveform
+        audioUrl="/media/voice.wav"
+        label=""
+        labelColor="#fff"
+        projectId="project-a"
+        sessionEpoch={1}
+        priority="visible"
+      />,
+    );
+  });
+}
+
 /** A 6 x 20 canvas whose 2D context records every fill as [style, x, y, width, height]. */
 function recordingCanvas() {
   const fills: Array<[string, number, number, number, number]> = [];
@@ -51,6 +134,75 @@ describe("AudioWaveform", () => {
     ]);
   });
 
+  it("draws only the span of the clip it is given", () => {
+    const { canvas, fills } = recordingCanvas();
+    // The clip's second half holds the loud peak only.
+    drawWaveformCanvas(canvas, [0.25, 1], false, 0, 1, null, { from: 0.5, to: 1 });
+    const bars = fills.filter(([, , y, , height]) => !(y === 18 && height === 2));
+    expect(bars.map(([, , y, , height]) => [y, height])).toEqual([
+      [0, 20],
+      [0, 20],
+    ]);
+  });
+
+  it("draws only the stretch of a long clip near the screen, and follows it as the clip moves", () => {
+    vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockReturnValue(null);
+    setStrip({ width: 10_000, height: 40, inViewStart: 2048, inViewEnd: 4096 });
+    renderReadyWaveform();
+    const canvas = document.querySelector("canvas")!;
+    const placed = () => [parseFloat(canvas.style.left), parseFloat(canvas.style.width)];
+    expect(placed()[0]).toBeCloseTo(20.48);
+    expect(placed()[1]).toBeCloseTo(20.48);
+    // A move or scroll carries the clip: the hook reports a new stretch and the bars follow.
+    setStrip({ width: 10_000, height: 40, inViewStart: 4096, inViewEnd: 6144 });
+    expect(placed()[0]).toBeCloseTo(40.96);
+    expect(placed()[1]).toBeCloseTo(20.48);
+  });
+
+  it("watches no ends of a clip drawn whole", () => {
+    setStrip({ width: 1000, height: 40, inViewStart: 0, inViewEnd: 1000 });
+    renderReadyWaveform();
+    expect(watchGap.mock.calls.filter(([gap]) => gap)).toEqual([]);
+  });
+
+  it("leaves a waveform off screen undrawn through a zoom, and draws it once it comes near", () => {
+    nearScreen.auto = false;
+    const getContext = vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockReturnValue(null);
+    setStrip({ width: 1000, height: 40, inViewStart: 0, inViewEnd: 1000 });
+    renderReadyWaveform();
+    const root = nearScreen.watched.at(-1)!;
+    expect(getContext).not.toHaveBeenCalled();
+    act(() => nearScreen.report(root, true));
+    const drawn = getContext.mock.calls.length;
+    expect(drawn).toBeGreaterThan(0);
+    act(() => nearScreen.report(root, false));
+    setStrip({ width: 2000, height: 40, inViewStart: 0, inViewEnd: 2000 });
+    expect(getContext.mock.calls.length).toBe(drawn);
+    act(() => nearScreen.report(root, true));
+    expect(getContext.mock.calls.length).toBe(drawn + 1);
+  });
+
+  it("redraws a short clip, drawn whole, when a zoom changes its width", () => {
+    const getContext = vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockReturnValue(null);
+    setStrip({ width: 1000, height: 40, inViewStart: 0, inViewEnd: 1000 });
+    renderReadyWaveform();
+    const drawn = getContext.mock.calls.length;
+    setStrip({ width: 2000, height: 40, inViewStart: 0, inViewEnd: 2000 });
+    expect(getContext.mock.calls.length).toBe(drawn + 1);
+  });
+
+  it("watches both undrawn ends of a long clip, so a move without a scroll re-measures it", () => {
+    setStrip({ width: 10_000, height: 40, inViewStart: 2048, inViewEnd: 4096 });
+    renderReadyWaveform();
+    const gaps = [
+      ...new Set(watchGap.mock.calls.map(([gap]) => gap).filter(Boolean)),
+    ] as HTMLElement[];
+    expect(gaps.map((gap) => [gap.style.width, gap.style.left])).toEqual([
+      ["20.48%", ""],
+      ["", "40.96%"],
+    ]);
+  });
+
   it("shrinks each bar to the fade's gain and keeps the cut-away part as a ghost", () => {
     const { canvas, fills } = recordingCanvas();
     // A 1 s fade-in on a 2 s clip: the first bar's centre (0.5 s) plays at half gain.