@hyperframes/studio 0.8.141 → 0.8.143

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.141",
+  "version": "0.8.143",
   "description": "",
   "repository": {
     "type": "git",
@@ -60,12 +60,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.141",
-    "@hyperframes/player": "0.8.141",
-    "@hyperframes/parsers": "0.8.141",
-    "@hyperframes/sdk": "0.8.141",
-    "@hyperframes/shader-transitions": "0.8.141",
-    "@hyperframes/studio-server": "0.8.141"
+    "@hyperframes/core": "0.8.143",
+    "@hyperframes/player": "0.8.143",
+    "@hyperframes/sdk": "0.8.143",
+    "@hyperframes/studio-server": "0.8.143",
+    "@hyperframes/parsers": "0.8.143",
+    "@hyperframes/shader-transitions": "0.8.143"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -82,7 +82,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.141"
+    "@hyperframes/producer": "0.8.143"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/MediaPreview.tsx

@@ -1,6 +1,7 @@
 import { buildProjectApiPath } from "../utils/projectRouting";
 import { useState } from "react";
 import { IMAGE_EXT, VIDEO_EXT, AUDIO_EXT } from "../utils/mediaTypes";
+import { encodeUrlPath } from "@hyperframes/parsers";
 
 function MediaErrorPanel({ name, filePath }: { name: string; filePath: string }) {
   return (
@@ -29,7 +30,7 @@ function MediaErrorPanel({ name, filePath }: { name: string; filePath: string })
 }
 
 export function MediaPreview({ projectId, filePath }: { projectId: string; filePath: string }) {
-  const serveUrl = buildProjectApiPath(projectId, `/preview/${filePath}`);
+  const serveUrl = buildProjectApiPath(projectId, `/preview/${encodeUrlPath(filePath)}`);
   const name = filePath.split("/").pop() ?? filePath;
   // Keyed by path so switching to another file clears a previous failure.
   const [failedPath, setFailedPath] = useState<string | null>(null);

package/src/components/TimelineToolbar.test.tsx

@@ -271,7 +271,7 @@ describe("TimelineToolbar Fit", () => {
       timelineFitPps: 10,
       timelinePps: 10,
     });
-    return registerTimelineZoomViewport({ scroll, contentOrigin: 32 });
+    return registerTimelineZoomViewport({ scroll, contentOrigin: 32, publishScroll: () => {} });
   }
 
   it("moves the slider and its readout with a zoom while it is previewed", () => {

package/src/components/editor/mediaAudioEdits.test.ts

@@ -239,6 +239,18 @@ describe("buildKeepSoundCutoutEdit", () => {
     expect(doc.getElementById("clip")?.getAttribute("src")).toBe("assets/cut.webm");
   });
 
+  it("preserves an apostrophe in the authored source of the linked audio", () => {
+    const authored = source.replace('src="assets/talk.mp4"', `src="assets/it's.mp4"`);
+    const edit = buildKeepSoundCutoutEdit({
+      video: liveVideo(),
+      videoId: "clip",
+      target: { id: "clip" },
+      cutoutSrc: "assets/cut.webm",
+    });
+    const doc = parse(applyEdit(authored, edit));
+    expect(doc.getElementById("clip-audio")?.getAttribute("src")).toBe("assets/it's.mp4");
+  });
+
   it("takes the first <source> child when the video has no src attribute", () => {
     const withSource = source.replace(
       /<video id="clip"([^>]*?) src="assets\/talk.mp4"([^>]*)><\/video>/,

package/src/components/editor/mediaAudioEdits.ts

@@ -14,7 +14,7 @@ import {
   findTagByTarget,
   applyPatchByTarget,
   readAttributeByTarget,
-  unescapeHtmlAttribute,
+  readTagAttribute,
   type PatchOperation,
   type PatchTarget,
 } from "../../utils/sourcePatcher";
@@ -147,10 +147,10 @@ export function formatAttrs(attrs: Array<[string, string]>): string {
 export function readAuthoredSrc(source: string, target: PatchTarget): string {
   const tag = findTagByTarget(source, target);
   if (!tag) return "";
-  const own = /\bsrc=(["'])([^"']*)\1/.exec(tag.tag);
-  if (own?.[2]) return unescapeHtmlAttribute(own[2]);
-  const firstSource = /^\s*<source\b[^>]*?\bsrc=(["'])([^"']*)\1/i.exec(source.slice(tag.end + 1));
-  return firstSource?.[2] ? unescapeHtmlAttribute(firstSource[2]) : "";
+  const own = readTagAttribute(tag.tag, "src");
+  if (own) return own;
+  const firstSource = /^\s*<source\b[^>]*>/i.exec(source.slice(tag.end + 1));
+  return (firstSource && readTagAttribute(firstSource[0], "src")) || "";
 }
 
 export function insertBeforeTarget(source: string, target: PatchTarget, markup: string): string {

package/src/components/editor/propertyPanelFill.tsx

@@ -20,6 +20,7 @@ import {
 } from "./propertyPanelPrimitives";
 import { ColorField } from "./propertyPanelColor";
 import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
+import { encodeUrlPath } from "@hyperframes/parsers";
 
 /* ------------------------------------------------------------------ */
 /*  Asset path helpers                                                 */
@@ -181,7 +182,7 @@ export function ImageFillField({
             {selectedAsset && (
               <div className="overflow-hidden rounded-xl border border-neutral-800 bg-neutral-900/80">
                 <img
-                  src={buildProjectApiPath(projectId, `/preview/${selectedAsset}`)}
+                  src={buildProjectApiPath(projectId, `/preview/${encodeUrlPath(selectedAsset)}`)}
                   alt={selectedAsset.split("/").pop() ?? selectedAsset}
                   className="h-28 w-full object-contain bg-neutral-950/80"
                 />

package/src/components/editor/propertyPanelFlatMediaSection.tsx

@@ -10,7 +10,6 @@ import {
   formatTimingValue,
   parseNumericValue,
   readClipInPoint,
-  stripQueryAndHash,
 } from "./propertyPanelHelpers";
 import { FlatSelectRow, FlatSlider } from "./propertyPanelFlatPrimitives";
 import { FlatToggle } from "./propertyPanelFlatToggle";
@@ -37,6 +36,7 @@ import {
 import { parseGainInput, parseRateInput, parseSecondsInput } from "./audioInspectorInput";
 import type { CommitDomAttributeBatch } from "../../hooks/domEditCommitTypes";
 import { commitCutout, commitHasAudioToggle, commitMutedToggle } from "./mediaAudioEdits";
+import { authoredSrcPath } from "../../player/components/thumbnailUtils";
 
 // fallow-ignore-next-line complexity
 export function FlatMediaSection({
@@ -126,12 +126,11 @@ export function FlatMediaSection({
   const [createPlate, setCreatePlate] = useState(false);
   const [quality, setQuality] = useState<"fast" | "balanced" | "best">("balanced");
 
-  const absoluteSrc =
-    projectDir && srcAttr && !srcAttr.startsWith("http") ? `${projectDir}/${srcAttr}` : srcAttr;
   const projectSrc =
     srcAttr && !/^(?:https?:|data:|blob:)/i.test(srcAttr)
-      ? stripQueryAndHash(srcAttr.startsWith("./") ? srcAttr.slice(2) : srcAttr)
+      ? authoredSrcPath(srcAttr.startsWith("./") ? srcAttr.slice(2) : srcAttr)
       : "";
+  const absoluteSrc = projectDir && projectSrc ? `${projectDir}/${projectSrc}` : srcAttr;
   const canRemoveBackground = Boolean(onRemoveBackground && isVisualMedia && projectSrc);
 
   useEffect(() => {

package/src/components/editor/propertyPanelMediaSection.tsx

@@ -11,7 +11,6 @@ import {
   parseNumericValue,
   readClipInPoint,
   RESPONSIVE_GRID,
-  stripQueryAndHash,
 } from "./propertyPanelHelpers";
 import { Section, SegmentedControl, SelectField, SliderControl } from "./propertyPanelPrimitives";
 import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
@@ -26,6 +25,7 @@ import {
 import type { CommitDomAttributeBatch } from "../../hooks/domEditCommitTypes";
 import { useLinkedSpeedCommit, withLinkedPlaybackRate } from "./linkedSpeedEdits";
 import { commitCutout, commitHasAudioToggle, commitMutedToggle } from "./mediaAudioEdits";
+import { authoredSrcPath } from "../../player/components/thumbnailUtils";
 
 // fallow-ignore-next-line complexity
 export function MediaSection({
@@ -98,12 +98,11 @@ export function MediaSection({
   const [createPlate, setCreatePlate] = useState(false);
   const [quality, setQuality] = useState<"fast" | "balanced" | "best">("balanced");
 
-  const absoluteSrc =
-    projectDir && srcAttr && !srcAttr.startsWith("http") ? `${projectDir}/${srcAttr}` : srcAttr;
   const projectSrc =
     srcAttr && !/^(?:https?:|data:|blob:)/i.test(srcAttr)
-      ? stripQueryAndHash(srcAttr.startsWith("./") ? srcAttr.slice(2) : srcAttr)
+      ? authoredSrcPath(srcAttr.startsWith("./") ? srcAttr.slice(2) : srcAttr)
       : "";
+  const absoluteSrc = projectDir && projectSrc ? `${projectDir}/${projectSrc}` : srcAttr;
   const canRemoveBackground = Boolean(onRemoveBackground && isVisualMedia && projectSrc);
   const panelTitle = isImage ? "Image" : isVideo ? "Video" : "Audio";
 

package/src/components/editor/useColorGradingController.ts

@@ -30,6 +30,7 @@ import {
   type ColorGradingPreviewOptions,
 } from "./useColorGradingPreviews";
 import { studioApiFetch } from "../../utils/studioApiFetch";
+import { authoredSrcPath } from "../../player/components/thumbnailUtils";
 
 export type { ColorGradingPresetPreviews, ColorGradingPreviewOptions };
 
@@ -97,7 +98,7 @@ function resolveProjectAssetPath(
   const sourceDir = sourceFile.includes("/")
     ? sourceFile.slice(0, sourceFile.lastIndexOf("/"))
     : "";
-  const parts = `${sourceDir}/${trimmed}`.split("/");
+  const parts = `${sourceDir}/${authoredSrcPath(trimmed)}`.split("/");
   const normalized: string[] = [];
   for (const part of parts) {
     if (!part || part === ".") continue;

package/src/hooks/useDomEditCommits.ts

@@ -23,6 +23,7 @@ import {
 } from "./useDomEditCommitsHelpers";
 import type { CutoverResult } from "../utils/sdkCutover";
 import { serializeStudioFileMutations } from "../utils/studioFileMutationCoordinator";
+import { encodeUrlPath } from "@hyperframes/parsers";
 
 export interface UseDomEditCommitsParams {
   activeCompPath: string | null;
@@ -112,7 +113,7 @@ export function useDomEditCommits({
       return {
         family: fontFamilyFromAssetPath(asset),
         path: asset,
-        url: buildProjectApiPath(projectId, `/preview/${asset}`),
+        url: buildProjectApiPath(projectId, `/preview/${encodeUrlPath(asset)}`),
       };
     },
     [fileTree, projectId, importedFontAssetsRef],

package/src/hooks/useFileManager.ts

@@ -9,6 +9,7 @@ import { useFileTree } from "./useFileTree";
 import { useEditorSave } from "./useEditorSave";
 import { useProjectFileWriter } from "./useProjectFileWriter";
 import { studioApiFetch } from "../utils/studioApiFetch";
+import { encodeUrlPath } from "@hyperframes/parsers";
 
 // ── Types ──
 
@@ -386,7 +387,7 @@ export function useFileManager({
         .map((asset) => ({
           family: fontFamilyFromAssetPath(asset),
           path: asset,
-          url: `/api/projects/${encodeURIComponent(pid)}/preview/${asset}`,
+          url: `/api/projects/${encodeURIComponent(pid)}/preview/${encodeUrlPath(asset)}`,
         }));
       importedFontAssetsRef.current = [
         ...imported,

package/src/hooks/useFileTree.ts

@@ -4,6 +4,7 @@ import { FONT_EXT } from "../utils/mediaTypes";
 import { fontFamilyFromAssetPath, type ImportedFontAsset } from "../components/editor/fontAssets";
 import { captureProjectProvenance } from "../components/feedback/projectProvenance";
 import { studioApiFetch } from "../utils/studioApiFetch";
+import { encodeUrlPath } from "@hyperframes/parsers";
 
 interface UseFileTreeOptions {
   projectId: string | null;
@@ -119,7 +120,7 @@ export function useFileTree({ projectId, projectIdRef }: UseFileTreeOptions) {
         .map((asset) => ({
           family: fontFamilyFromAssetPath(asset),
           path: asset,
-          url: projectId ? buildProjectApiPath(projectId, `/preview/${asset}`) : "",
+          url: projectId ? buildProjectApiPath(projectId, `/preview/${encodeUrlPath(asset)}`) : "",
         })),
     [assets, projectId],
   );

package/src/hooks/useRenderClipContent.ts

@@ -17,7 +17,11 @@ import { AudibleVideoClipContent } from "../player/components/AudibleVideoClipCo
 import { ClipPeakMarks } from "../player/components/ClipPeakMarks";
 import { clipPeaksUrl, clipSourceWindow } from "../player/components/clipPeakMap";
 import { clipHasSound } from "../player/components/clipMenuNormalize";
-import { encodePreviewPath, resolveMediaPreviewUrl } from "../player/components/thumbnailUtils";
+import {
+  authoredSrcPath,
+  encodePreviewPath,
+  resolveMediaPreviewUrl,
+} from "../player/components/thumbnailUtils";
 import { usePlayerStore } from "../player/store/playerStore";
 import { thumbnailRevisionOf } from "../player/store/thumbnailSlice";
 import { effectiveThumbnailMode } from "../player/lib/thumbnailPolicy";
@@ -67,7 +71,11 @@ function renderAudioClip(
   elements: readonly TimelineElement[],
   labelInset?: number,
 ): ReactNode {
-  const audioUrl = resolveMediaPreviewUrl(el.src ?? "", pid, window.location.origin);
+  const audioUrl = resolveMediaPreviewUrl(
+    authoredSrcPath(el.src ?? ""),
+    pid,
+    window.location.origin,
+  );
   const srcRelative = resolvePreviewRelative(audioUrl, pid, window.location.origin);
   // Encode each path segment (spaces, parens, U+202F, unicode) so the URL matches
   // what the assets panel loads — a raw segment 404s. resolvePreviewRelative
@@ -213,7 +221,11 @@ export function useRenderClipContent({
       const htmlPreviewEligible = el.duration > 0 && effectiveTimelineDuration > 0;
 
       if ((el.tag === "video" || el.tag === "img") && el.src) {
-        const mediaSrc = resolveMediaPreviewUrl(el.src, pid, window.location.origin);
+        const mediaSrc = resolveMediaPreviewUrl(
+          authoredSrcPath(el.src),
+          pid,
+          window.location.origin,
+        );
         // Still images can't be decoded by VideoThumbnail's <video> extractor
         // (the error event fires and the shimmer never resolves) — render the
         // image itself as the strip.

package/src/player/components/clipMenuNormalize.ts

@@ -1,6 +1,6 @@
 import { buildProjectApiPath } from "../../utils/projectRouting";
 import { resolvePreviewRelative } from "../../utils/previewRelativePath";
-import { resolveMediaPreviewUrl } from "./thumbnailUtils";
+import { authoredSrcPath, resolveMediaPreviewUrl } from "./thumbnailUtils";
 import type { TimelineElement } from "../store/timelineElement";
 import { parseAutomation, VOLUME_TARGET } from "@hyperframes/core/audio-automation";
 import type { TimelineEditOutcome } from "../../hooks/timelineEditPermission";
@@ -79,7 +79,7 @@ export async function requestNormalizePlan(
 ): Promise<NormalizePlan> {
   const origin = window.location.origin;
   const relative = resolvePreviewRelative(
-    resolveMediaPreviewUrl(el.src ?? "", projectId, origin),
+    resolveMediaPreviewUrl(authoredSrcPath(el.src ?? ""), projectId, origin),
     projectId,
     origin,
   );

package/src/player/components/clipPeakMap.ts

@@ -3,7 +3,7 @@ import { studioApiFetch } from "../../utils/studioApiFetch";
 import { resolvePreviewRelative } from "../../utils/previewRelativePath";
 import type { TimelineElement } from "../store/timelineElement";
 import { clipSourcePeak, isPeakMap, type ClipSourceWindow, type PeakMap } from "./clipPeakRuns";
-import { encodePreviewPath, resolveMediaPreviewUrl } from "./thumbnailUtils";
+import { authoredSrcPath, encodePreviewPath, resolveMediaPreviewUrl } from "./thumbnailUtils";
 
 const peakMapRequests = new Map<string, Promise<PeakMap | null>>();
 
@@ -23,7 +23,7 @@ export function loadPeakMap(url: string): Promise<PeakMap | null> {
 export function clipPeaksUrl(src: string | undefined, projectId: string): string | undefined {
   const origin = window.location.origin;
   const relative = resolvePreviewRelative(
-    resolveMediaPreviewUrl(src ?? "", projectId, origin),
+    resolveMediaPreviewUrl(authoredSrcPath(src ?? ""), projectId, origin),
     projectId,
     origin,
   );

package/src/player/components/thumbnailUtils.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, it } from "vitest";
+import { buildTimelineAssetInsertHtml } from "../../utils/timelineAssetDrop";
 import {
+  authoredSrcPath,
   computeThumbnailStrip,
   encodePreviewPath,
   resolveMediaPreviewUrl,
@@ -187,3 +189,34 @@ describe("encodePreviewPath", () => {
     expect(encodePreviewPath("assets/music.mp3")).toBe("assets/music.mp3");
   });
 });
+
+describe("authoredSrcPath", () => {
+  const droppedSrc = (assetPath: string) =>
+    /src="([^"]*)"/.exec(
+      buildTimelineAssetInsertHtml({
+        id: "clip",
+        hfId: "hf-clip",
+        assetPath,
+        kind: "video",
+        start: 0,
+        duration: 2,
+        track: 1,
+        zIndex: 1,
+      }),
+    )![1]!;
+
+  it.each([
+    ["assets/My clip.mp4", "/api/projects/p/preview/assets/My%20clip.mp4"],
+    ["assets/café.mp4", "/api/projects/p/preview/assets/caf%C3%A9.mp4"],
+    ["assets/50% off #1?.mp4", "/api/projects/p/preview/assets/50%25%20off%20%231%3F.mp4"],
+  ])("previews a dropped %j at its own file", (assetPath, url) => {
+    expect(resolveMediaPreviewUrl(authoredSrcPath(droppedSrc(assetPath)), "p")).toBe(url);
+  });
+
+  it("drops the query and fragment, and leaves URLs with a scheme alone", () => {
+    expect(authoredSrcPath("assets/a%20b.mp4?v=2#t=1")).toBe("assets/a b.mp4");
+    expect(authoredSrcPath("assets/100%.png")).toBe("assets/100%.png");
+    expect(authoredSrcPath("https://cdn.example/a%20b.mp4")).toBe("https://cdn.example/a%20b.mp4");
+    expect(authoredSrcPath("//cdn.example/a%20b.mp4")).toBe("//cdn.example/a%20b.mp4");
+  });
+});

package/src/player/components/thumbnailUtils.ts

@@ -1,3 +1,4 @@
+import { decodedUrlPath } from "@hyperframes/parsers";
 import { buildProjectApiPath } from "../../utils/projectRouting";
 import { MAX_VISIBLE_THUMBNAIL_FRAMES } from "../lib/timelineViewportBudgets";
 
@@ -94,6 +95,10 @@ export function computeThumbnailStrip(
   return { frameW, frameCount };
 }
 
+export function authoredSrcPath(src: string): string {
+  return /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(src) ? src : decodedUrlPath(src);
+}
+
 /**
  * Percent-encode each segment of a composition-relative media path so filenames
  * containing spaces, parentheses, a U+202F narrow no-break space (the macOS

package/src/player/components/timelineLayout.test.ts

@@ -27,13 +27,13 @@ import { resolveInsertRow } from "./timelineCollision";
 import { getTimelineRenderTimeRange } from "./timelineViewportGeometry";
 
 describe("horizontal timeline window", () => {
-  it("adds the shared half-viewport overscan on each side and clamps to duration", () => {
+  it("adds the shared quarter-viewport overscan on each side and clamps to duration", () => {
     expect(getTimelineRenderTimeRange({ scrollLeft: 300, clientWidth: 500 }, 100, 200, 20)).toEqual(
-      { start: 0, end: 8.5 },
+      { start: 0, end: 7.25 },
     );
     expect(
       getTimelineRenderTimeRange({ scrollLeft: 1_900, clientWidth: 500 }, 100, 200, 20),
-    ).toEqual({ start: 14.5, end: 20 });
+    ).toEqual({ start: 15.75, end: 20 });
   });
 
   it("generates globally aligned ticks directly inside the bounded window", () => {

package/src/player/components/timelineZoomInput.test.ts

@@ -49,6 +49,7 @@ afterEach(() => {
 });
 
 let unregisterViewport = () => {};
+const publishScroll = vi.fn();
 
 /** A 1080px timeline viewport with 32px of track headers, holding one scaled row. */
 function viewport(scrollLeft = 0, scrollWidth = 20_000) {
@@ -60,7 +61,7 @@ function viewport(scrollLeft = 0, scrollWidth = 20_000) {
   });
   const row = scroll.appendChild(document.createElement("div"));
   row.setAttribute("data-timeline-zoom-scale", "");
-  unregisterViewport = registerTimelineZoomViewport({ scroll, contentOrigin: 32 });
+  unregisterViewport = registerTimelineZoomViewport({ scroll, contentOrigin: 32, publishScroll });
   return { scroll, row };
 }
 
@@ -120,7 +121,7 @@ describe("requestTimelineZoom", () => {
   it("lays a zoom-out about the left edge out at once, before it shows unmounted time", () => {
     usePlayerStore.setState({ duration: 1000 });
     viewport();
-    // Mounted to (1080 - 32 + 540) / 10 = 158.8 s; at 5 px/s the view reaches 209.6 s.
+    // Mounted to (1080 - 32 + 270) / 10 = 131.8 s; at 5 px/s the view reaches 209.6 s.
     requestTimelineZoom(50, { time: 0, x: 32 });
     vi.advanceTimersToNextFrame();
     expect(usePlayerStore.getState().timelinePps).toBe(5);
@@ -134,14 +135,14 @@ describe("requestTimelineZoom", () => {
       timelinePps: 100,
     });
     viewport(5000);
-    // Mounted 44.28..65.88 s; at 60 px/s about 55.24 s the view shows 46.5..63.97 s.
-    requestTimelineZoom(600, { time: 55.24, x: 556 });
+    // Mounted 46.98..63.18 s; at 70 px/s about 55.24 s the view shows 47.75..62.73 s.
+    requestTimelineZoom(700, { time: 55.24, x: 556 });
     vi.advanceTimersToNextFrame();
     expect(usePlayerStore.getState().timelinePps).toBe(100);
   });
 
   it("lays out a zoom-out before it shows past the window ruler ticks are drawn in", () => {
-    // 50 s of clips in content 1996 s wide: ticks are drawn to 157 s, a view and a half in.
+    // 50 s of clips in content 1996 s wide: ticks are drawn to 131.8 s, a view and a quarter in.
     usePlayerStore.setState({ duration: 50 });
     viewport();
     requestTimelineZoom(60, { time: 0, x: 32 });
@@ -230,7 +231,7 @@ describe("requestTimelineZoom", () => {
     const { scroll } = viewport();
     requestTimelineZoom(150);
     unregisterViewport();
-    unregisterViewport = registerTimelineZoomViewport({ scroll, contentOrigin: 32 });
+    unregisterViewport = registerTimelineZoomViewport({ scroll, contentOrigin: 32, publishScroll });
     await Promise.resolve();
     vi.advanceTimersByTime(200);
     expect(usePlayerStore.getState().timelinePps).toBe(15);
@@ -240,6 +241,7 @@ describe("requestTimelineZoom", () => {
     const unregisterOlder = registerTimelineZoomViewport({
       scroll: document.createElement("div"),
       contentOrigin: 32,
+      publishScroll,
     });
     viewport();
     unregisterOlder();
@@ -258,6 +260,25 @@ describe("requestTimelineZoom", () => {
 });
 
 describe("zoomTimelineToRange", () => {
+  it("tells the timeline where a pan at the laid-out scale scrolled to", () => {
+    usePlayerStore.setState({
+      duration: 1000,
+      zoomMode: "manual",
+      manualZoomPercent: 1000,
+      timelineFitPps: 10,
+      timelinePps: 100,
+    });
+    const { scroll } = viewport(0);
+    const published: number[] = [];
+    publishScroll.mockImplementation((el: HTMLDivElement) => published.push(el.scrollLeft));
+    void zoomTimelineToRange(60, 70);
+    for (let i = 0; i < 40; i++) vi.advanceTimersToNextFrame();
+    publishScroll.mockReset();
+    expect(usePlayerStore.getState().timelinePps).toBe(100);
+    expect(scroll.scrollLeft).toBeGreaterThan(5000);
+    expect(published.at(-1)).toBe(scroll.scrollLeft);
+  });
+
   it("fills the width with the range and puts its start at the left margin", () => {
     viewport();
     void zoomTimelineToRange(40, 90, { smooth: false });

package/src/player/components/timelineZoomInput.ts

@@ -21,6 +21,7 @@ export interface TimelineZoomAnchor {
 export interface TimelineZoomViewport {
   scroll: HTMLDivElement;
   contentOrigin: number;
+  publishScroll: (scroll: HTMLDivElement) => void;
 }
 
 /** How an eased zoom ended: it reached its range, or a person's zoom or the caller stopped it. */
@@ -209,7 +210,10 @@ function commitPreview() {
     );
   }
   preview = null;
-  if (Math.abs(view.scroll.scrollLeft - left) >= 0.5) view.scroll.scrollLeft = left;
+  if (Math.abs(view.scroll.scrollLeft - left) >= 0.5) {
+    view.scroll.scrollLeft = left;
+    flushSync(() => view.publishScroll(view.scroll));
+  }
   clearScaled(view.scroll);
   emitPreview();
 }

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

@@ -1,20 +1,23 @@
 // @vitest-environment happy-dom
 
-import { act, useRef } from "react";
+import { act, useLayoutEffect, useRef } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { liveTime, usePlayerStore, type ZoomMode } from "../store/playerStore";
 import { useTimelinePlayhead } from "./useTimelinePlayhead";
+import { useTimelineScrollViewport } from "./useTimelineScrollViewport";
+import { useTimelineClipRenderWindow } from "./useTimelineClipRenderWindow";
+import { requestTimelineZoom, settleTimelineZoom } from "./timelineZoomInput";
 
 Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
 
 const ORIGIN = 32;
 
-function scrollBox(scrollLeft: number) {
+function scrollBox(scrollLeft: number, clientWidth = 800) {
   const el = document.createElement("div");
   let left = scrollLeft;
   Object.defineProperties(el, {
-    clientWidth: { value: 800 },
+    clientWidth: { value: clientWidth },
     scrollWidth: { value: 20_000 },
     scrollLeft: { get: () => left, set: (v: number) => (left = v) },
   });
@@ -27,9 +30,16 @@ interface HarnessProps {
   scroll: HTMLDivElement;
   dragging?: boolean;
   zoomMode?: ZoomMode;
+  syncScrollViewport?: (scroll: HTMLDivElement) => void;
 }
 
-function Harness({ pps: fixedPps, scroll, dragging = false, zoomMode = "manual" }: HarnessProps) {
+function Harness({
+  pps: fixedPps,
+  scroll,
+  dragging = false,
+  zoomMode = "manual",
+  syncScrollViewport = () => {},
+}: HarnessProps) {
   const storePps = usePlayerStore((s) => s.timelinePps);
   const pps = fixedPps ?? storePps;
   const scrollRef = useRef(scroll);
@@ -37,6 +47,7 @@ function Harness({ pps: fixedPps, scroll, dragging = false, zoomMode = "manual"
   useTimelinePlayhead({
     playheadRef: { current: document.createElement("div") },
     scrollRef,
+    syncScrollViewport,
     ppsRef: { current: pps },
     durationRef,
     isDragging: { current: dragging },
@@ -238,6 +249,81 @@ describe("useTimelinePlayhead follow while paused", () => {
   });
 });
 
+describe("useTimelinePlayhead committed viewport", () => {
+  function mountViewport(scrollLeft: number) {
+    vi.stubGlobal(
+      "ResizeObserver",
+      class {
+        observe() {}
+        disconnect() {}
+      },
+    );
+    usePlayerStore.setState({
+      zoomMode: "manual",
+      manualZoomPercent: 1000,
+      timelineFitPps: 10,
+      timelinePps: 100,
+    });
+    const scroll = scrollBox(scrollLeft, 1080);
+    const container = document.createElement("div");
+    function Probe() {
+      const pps = usePlayerStore((s) => s.timelinePps);
+      const { viewport, setScrollRef, syncScrollViewport } = useTimelineScrollViewport(
+        useRef(scroll),
+        [],
+      );
+      useLayoutEffect(() => setScrollRef(scroll), [setScrollRef]);
+      const { renderTimeRange } = useTimelineClipRenderWindow({
+        tracks: [],
+        viewport,
+        pixelsPerSecond: pps,
+        contentOrigin: ORIGIN,
+        duration: 100,
+      });
+      return (
+        <>
+          <Harness scroll={scroll} syncScrollViewport={syncScrollViewport} />
+          {renderTimeRange.start <= 59 && renderTimeRange.end >= 59 && <span data-clip="59" />}
+          <output>{viewport.scrollLeft}</output>
+        </>
+      );
+    }
+    const root = createRoot(container);
+    roots.push(root);
+    act(() => root.render(<Probe />));
+    return { scroll, container };
+  }
+
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("keeps the visible 59-second clip mounted when a pointer zoom commits", () => {
+    const { scroll, container } = mountViewport(5000);
+    expect(container.querySelector('[data-clip="59"]')).not.toBeNull();
+    act(() => {
+      requestTimelineZoom(1090, { time: 55.24, x: 556 });
+      settleTimelineZoom();
+    });
+    expect(scroll.scrollLeft).toBeCloseTo(5497.16);
+    expect(container.querySelector('[data-clip="59"]')).not.toBeNull();
+    expect(Number(container.querySelector("output")?.textContent)).toBeCloseTo(5497.16);
+  });
+
+  it("renders a pan at the laid-out scale before the browser paints", () => {
+    const { scroll, container } = mountViewport(0);
+    const actEnvironment = globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean };
+    const wasActEnvironment = actEnvironment.IS_REACT_ACT_ENVIRONMENT;
+    actEnvironment.IS_REACT_ACT_ENVIRONMENT = false;
+    try {
+      requestTimelineZoom(1000, { time: 60, x: ORIGIN });
+      settleTimelineZoom();
+      expect(scroll.scrollLeft).toBe(6000);
+      expect(container.querySelector("output")?.textContent).toBe("6000");
+    } finally {
+      actEnvironment.IS_REACT_ACT_ENVIRONMENT = wasActEnvironment;
+    }
+  });
+});
+
 describe("useTimelinePlayhead wheel zoom", () => {
   beforeEach(() => {
     vi.useFakeTimers({