fix(studio): Studio shows a video's own file, not its preview copy, and copies only on request

packages/cli/src/commands/play.test.ts

@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { mkdtempSync, rmSync, utimesSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -31,10 +32,8 @@ const mocks = vi.hoisted(() => {
   }
   return {
     resolveProxy: vi.fn<(projectDir: string, absoluteSourcePath: string) => Promise<string>>(
-      // Benign default so `injectMediaCodecMap`'s fire-and-forget pre-warm
-      // (called for every hostile map entry) always gets a promise to
-      // `.catch()`, even in tests that don't care about the proxy path.
-      async () => "/unused-prewarm-proxy-path",
+      // Benign default for tests that don't care about the proxy path.
+      async () => "/unused-proxy-path",
     ),
     scanProjectMediaCodecMap: vi.fn<
       (
@@ -64,7 +63,6 @@ const mediaMocks = vi.hoisted(() => ({
   ),
   isProxyVariant: (value: string) => value === "h264" || value === "vp8",
   isProxyVariantRequest: (value: string) => value === "auto" || value === "h264" || value === "vp8",
-  recordProxyRequest: () => {},
   proxyVariantFor: (facts: { hasAlpha?: boolean }) => (facts.hasAlpha ? "vp8" : "h264"),
   resolveProxyVariantRequest: (request: "auto" | "h264" | "vp8", facts: { hasAlpha?: boolean }) => {
     const expected = facts.hasAlpha ? "vp8" : "h264";
@@ -111,7 +109,7 @@ function tmpProject(): ProjectDir {
 
 afterEach(() => {
   mocks.resolveProxy.mockReset();
-  mocks.resolveProxy.mockResolvedValue("/unused-prewarm-proxy-path");
+  mocks.resolveProxy.mockResolvedValue("/unused-proxy-path");
   mocks.scanProjectMediaCodecMap.mockReset();
   mediaMocks.probeAssetCodec.mockClear();
   mediaMocks.decideMediaProxyEligibility.mockClear();

packages/cli/src/commands/play.ts

@@ -49,7 +49,6 @@ import {
   decideMediaProxyEligibility,
   isProxyVariantRequest,
   probeAssetCodec,
-  recordProxyRequest,
   resolveProxyVariantRequest,
   PROXY_VARIANT_CONFIG,
 } from "@hyperframes/studio-server/media-codec-map";
@@ -265,7 +264,6 @@ export async function registerCompositionRoute(
         if (!proxyVariant) {
           return ctx.text("Media proxy variant does not match asset", 422);
         }
-        recordProxyRequest();
         const proxyPath = await resolveProxy(project.dir, filePath, proxyVariant);
         return buildRangeResponse(
           proxyPath,

packages/cli/src/utils/staticProjectServer.test.ts

@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -35,10 +36,8 @@ const mocks = vi.hoisted(() => {
   }
   return {
     resolveProxy: vi.fn<(projectDir: string, absoluteSourcePath: string) => Promise<string>>(
-      // Benign default so `injectMediaCodecMap`'s fire-and-forget pre-warm
-      // (called for every hostile map entry) always gets a promise to
-      // `.catch()`, even in tests that don't care about the proxy path.
-      async () => "/unused-prewarm-proxy-path",
+      // Benign default for tests that don't care about the proxy path.
+      async () => "/unused-proxy-path",
     ),
     scanProjectMediaCodecMap: vi.fn<
       (
@@ -76,7 +75,6 @@ vi.mock("@hyperframes/studio-server/media-codec-map", () => ({
   decideMediaProxyEligibility: mocks.decideMediaProxyEligibility,
   isProxyVariant: (value: string) => value === "h264" || value === "vp8",
   isProxyVariantRequest: (value: string) => value === "auto" || value === "h264" || value === "vp8",
-  recordProxyRequest: () => {},
   proxyVariantFor: (facts: { hasAlpha?: boolean }) => (facts.hasAlpha ? "vp8" : "h264"),
   resolveProxyVariantRequest: (request: "auto" | "h264" | "vp8", facts: { hasAlpha?: boolean }) => {
     const expected = facts.hasAlpha ? "vp8" : "h264";
@@ -114,7 +112,7 @@ afterEach(async () => {
   if (dir) rmSync(dir, { recursive: true, force: true });
   dir = undefined;
   mocks.resolveProxy.mockReset();
-  mocks.resolveProxy.mockResolvedValue("/unused-prewarm-proxy-path");
+  mocks.resolveProxy.mockResolvedValue("/unused-proxy-path");
   mocks.scanProjectMediaCodecMap.mockReset();
   mocks.scanProjectMediaCodecMap.mockResolvedValue({});
   mocks.probeAssetCodec.mockClear();

packages/cli/src/utils/staticProjectServer.ts

@@ -15,7 +15,6 @@ import {
   decideMediaProxyEligibility,
   isProxyVariantRequest,
   probeAssetCodec,
-  recordProxyRequest,
   resolveProxyVariantRequest,
   PROXY_VARIANT_CONFIG,
   type ProxyVariantRequest,
@@ -234,7 +233,6 @@ async function serveProxyRequest(
       res.end("media proxy variant does not match asset");
       return;
     }
-    recordProxyRequest();
     const proxyPath = await resolveProxy(projectDir, filePath, variant);
     // The await above can span a whole transcode; the client may be gone.
     if (res.writableEnded || res.destroyed) return;

packages/core/src/runtime/init.mediaClipIndex.test.ts

@@ -34,6 +34,7 @@ vi.mock("./media", async (importOriginal) => {
 });
 
 const { initSandboxRuntimeModular } = await import("./init");
+const { swapToProxy } = await import("./mediaProxy");
 
 /**
  * `count` back-to-back one-second clips, so the transport crosses exactly one
@@ -224,6 +225,33 @@ describe("per-seek media clip index", () => {
     expect(indexed[0]).toMatchObject({ currentTime: 3 });
   });
 
+  it("keeps the index through a preview copy's own src swap, and puts the copy on the playhead", async () => {
+    mountClips(16);
+    const clip = document.querySelector<HTMLVideoElement>("#clip3")!;
+    clip.setAttribute("src", "/clip3.mp4");
+    // A real load starts the new file at 0.
+    clip.load = vi.fn(() => {
+      clip.currentTime = 0;
+    });
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => new Response("x", { status: 206 })),
+    );
+    initSandboxRuntimeModular();
+    window.__player!.seek(3.5);
+    const placed = vi.spyOn(clip, "currentTime", "set");
+    mediaSpy.visits = [];
+
+    swapToProxy(clip, null, "reactive");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(clip.getAttribute("src")).toContain("hf-proxy=auto");
+    expect(mediaSpy.visits.length).toBeGreaterThan(0);
+    expect(Math.max(...mediaSpy.visits)).toBeLessThan(16);
+    expect(placed).toHaveBeenLastCalledWith(0.5);
+    vi.unstubAllGlobals();
+  });
+
   it("re-derives the index when a clip is moved on the timeline", () => {
     mountClips(16);
     initSandboxRuntimeModular();

packages/core/src/runtime/init.seekCopies.test.ts

@@ -1,6 +1,7 @@
 import { afterEach, expect, it, vi } from "vitest";
 import { initSandboxRuntimeModular } from "./init";
 import { noteSeekCopyPlayback, startSeekCopies, type SeekCopyHost } from "./mediaProxy";
+import { swappedElements } from "./proxySrc";
 import { createMockTimeline, resetRuntimeFixtureDom } from "./runtimeSeekFixture.test-helpers";
 
 vi.mock("./mediaProxy", async (importOriginal) => ({
@@ -32,6 +33,20 @@ it("starts seek copies after the first frame, on the transport's clips, and repo
   expect(host.playhead()).toBe(7);
 });
 
+it("tells Studio an element's authored src, not the preview copy it plays", () => {
+  resetRuntimeFixtureDom();
+  document.body.innerHTML =
+    '<div data-composition-id="main" data-root="true" data-duration="5"><video id="clip" data-start="0" src="/copy.mp4?hf-proxy=h264"></video></div>';
+  const video = document.querySelector("video")!;
+  video.load = vi.fn();
+  swappedElements.set(video, "/clip.mp4");
+  window.__timelines = { main: createMockTimeline(5) };
+
+  initSandboxRuntimeModular();
+
+  expect(window.__hf?.unproxiedSrc?.(video)).toBe("/clip.mp4");
+});
+
 afterEach(() => {
   window.__hfRuntimeTeardown?.();
   vi.restoreAllMocks();

packages/core/src/runtime/init.ts

@@ -69,6 +69,7 @@ import {
   handleMetadataForProxy,
   maybeProxyProactively,
   noteSeekCopyPlayback,
+  setOwnMediaWrite,
   startSeekCopies,
   setProxyDisplayScale,
 } from "./mediaProxy";
@@ -1389,6 +1390,13 @@ export function initSandboxRuntimeModular(): void {
       invalidateCompositionTimingCaches();
   };
 
+  // A copy swap moves no clip; the forced sync lands the new file on the playhead even while paused.
+  setOwnMediaWrite((el, write) => {
+    withoutOwnTimingRecords(el, write);
+    state.mediaForceSyncNextTick = true;
+    syncMediaForCurrentState();
+  });
+
   const watchCompositionTimingInputs = () => {
     if (compositionTimingObserver || typeof MutationObserver === "undefined") return;
     compositionTimingObserver = new MutationObserver(invalidateCompositionTimingCaches);
@@ -3250,6 +3258,7 @@ export function initSandboxRuntimeModular(): void {
     wakeTransport();
   };
   window.__hf.leasePausedMedia = leasePausedMedia;
+  window.__hf.unproxiedSrc = unproxiedSrc;
   window.__hf.releasePausedMedia = releasePausedMedia;
   window.__hf.setLoopStart = (seconds) => {
     loopStartSeconds = seconds != null && Number.isFinite(seconds) && seconds >= 0 ? seconds : null;

packages/core/src/runtime/mediaProxy.test.ts

@@ -24,6 +24,7 @@ vi.mock("./bridge", () => ({
 }));
 
 import { postRuntimeMessage } from "./bridge";
+import { collectRuntimeTimelinePayload } from "./timeline";
 import { resetSeekDispatchState, waitForSeekCompletion } from "./adapters/seek-dispatch";
 
 const postRuntimeMessageMock = vi.mocked(postRuntimeMessage);
@@ -817,6 +818,27 @@ describe("when a served copy replaces what the element plays", () => {
   });
 });
 
+describe("the authored source outside the preview", () => {
+  it("keeps the original src in the clip list after a copy swaps in", async () => {
+    const root = document.createElement("div");
+    root.setAttribute("data-composition-id", "main");
+    root.setAttribute("data-duration", "10");
+    document.body.appendChild(root);
+    const el = createVideo("/video.mp4");
+    el.id = "clip";
+    el.setAttribute("data-start", "0");
+    el.setAttribute("data-duration", "5");
+    root.appendChild(el);
+
+    swapToProxy(el, HEVC_ENTRY, "proactive");
+    await settle();
+    expect(proxyVariant(el)).toBe("h264");
+
+    const { clips } = collectRuntimeTimelinePayload({ canonicalFps: 30 });
+    expect(clips[0]?.assetUrl).toBe(new URL("/video.mp4", document.baseURI).href);
+  });
+});
+
 describe("deriveCodecMapKey", () => {
   it("returns the decoded, query-stripped pathname for a same-origin src", () => {
     const el = createVideo("/assets/my%20clip.mp4?foo=bar");

packages/core/src/runtime/mediaProxy.ts

@@ -165,6 +165,13 @@ function keepSized(el: HTMLMediaElement, scale: number): void {
   });
 }
 
+let ownMediaWrite = (_el: Element, write: () => void): void => write();
+
+/** The runtime's writer for a src it swaps itself, so the swap is not read as an authored edit. */
+export function setOwnMediaWrite(writer: (el: Element, write: () => void) => void): void {
+  ownMediaWrite = writer;
+}
+
 function loadProxy(
   el: HTMLMediaElement,
   href: string,
@@ -176,8 +183,10 @@ function loadProxy(
   else boxedElements.delete(el);
   // Sync state measured on the previous file would read the new file's buffering as drift.
   evictMediaSyncState(el);
-  el.src = href;
-  el.load();
+  ownMediaWrite(el, () => {
+    el.src = href;
+    el.load();
+  });
 }
 
 /**

packages/core/src/runtime/picker.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect, vi, afterEach, beforeAll } from "vitest";
 import { createPickerModule } from "./picker";
+import { swappedElements } from "./proxySrc";
 
 // jsdom does not implement CSS.escape — polyfill a compact spec-adjacent
 // version. Parallel (simpler) polyfills already live in compositionLoader.test.ts
@@ -194,6 +195,16 @@ describe("createPickerModule", () => {
       }
     });
 
+    it("reports a picked video's authored src, not the preview copy it plays", () => {
+      const picker = createPickerModule({ postMessage: createMockPostMessage() });
+      picker.installPickerApi();
+      document.body.innerHTML = `<video id="clip" src="/clip.mp4?hf-proxy=h264"></video>`;
+      const video = document.getElementById("clip")!;
+      swappedElements.set(video, "/clip.mp4");
+
+      expect(candidatesUnder(() => [video, ...ancestorsOf(video)], "src")[0]).toBe("/clip.mp4");
+    });
+
     it("picks inside a mounted section whose root sets pointer-events:none", () => {
       const picker = createPickerModule({ postMessage: createMockPostMessage() });
       picker.installPickerApi();

packages/core/src/runtime/picker.ts

@@ -2,6 +2,7 @@ import type { RuntimeJson, RuntimeOutboundMessage, RuntimePickerElementInfo } fr
 import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "../colorGrading";
 import { swallow } from "./diagnostics";
 import { isElementNode } from "./domRealm";
+import { unproxiedSrc } from "./proxySrc";
 import { createDrawnProbe } from "./pickerDrawn";
 
 type PickerModuleDeps = {
@@ -308,7 +309,7 @@ export function createPickerModule(deps: PickerModuleDeps): PickerModule {
       label: buildElementLabel(el),
       boundingBox: { x: rect.left, y: rect.top, width: rect.width, height: rect.height },
       textContent: el.textContent ? el.textContent.trim().slice(0, 200) : null,
-      src: el.getAttribute("src") || el.getAttribute("data-composition-src") || null,
+      src: unproxiedSrc(el) || el.getAttribute("data-composition-src") || null,
       dataAttributes,
     };
   }

packages/core/src/runtime/timeline.ts

@@ -12,6 +12,7 @@ import {
   resolveAuthoredTimingWindow,
 } from "./authoredTiming";
 import { swallow } from "./diagnostics";
+import { unproxiedSrc } from "./proxySrc";
 import { readTimelineDurationSeconds } from "./timelineDuration";
 import { readElementPlaybackRate, readElementPlaybackStart } from "./media";
 import {
@@ -170,13 +171,13 @@ function toAbsoluteAssetUrl(rawValue: string | null | undefined): string | null
 }
 
 function resolveNodeAssetUrl(node: Element): string | null {
-  const src = node.getAttribute("src") ?? node.getAttribute("data-src");
+  const src = unproxiedSrc(node) ?? node.getAttribute("data-src");
   if (src) return toAbsoluteAssetUrl(src);
   const compositionSrc = node.getAttribute("data-composition-src");
   if (compositionSrc) return toAbsoluteAssetUrl(compositionSrc);
   const mediaDescendant = node.querySelector("img[src], video[src], audio[src], source[src]");
   if (!mediaDescendant) return null;
-  return toAbsoluteAssetUrl(mediaDescendant.getAttribute("src"));
+  return toAbsoluteAssetUrl(unproxiedSrc(mediaDescendant));
 }
 
 function getFirstClassToken(node: Element): string | null {

packages/core/src/runtime/window.d.ts

@@ -73,6 +73,8 @@ declare global {
        *  runtime's paused-side enforcement leaves it alone. Always release. */
       leasePausedMedia?: (el: HTMLMediaElement) => void;
       releasePausedMedia?: (el: HTMLMediaElement) => void;
+      /** An element's authored src, never the preview copy the runtime plays in its place. */
+      unproxiedSrc?: (el: Element) => string | null;
       /** Where Studio's loop wraps to while it plays, or null: the clips due there stay loaded. */
       setLoopStart?: (seconds: number | null) => void;
       /** Read-only level taps for the Studio meters: nothing exists until

packages/studio-server/src/helpers/mediaCodecMap.test.ts

@@ -11,7 +11,6 @@ import {
   proxyVariantFor,
   resolveProxyVariantRequest,
   scanProjectMediaCodecMap,
-  shouldPrewarmProxy,
   type AssetCodecFacts,
 } from "./mediaCodecMap.js";
 
@@ -288,40 +287,9 @@ describe("BROWSER_HOSTILE_CODECS representative mimes", () => {
   });
 });
 
-describe("shouldPrewarmProxy", () => {
-  function facts(codecName: string): AssetCodecFacts {
-    return { codecName, browserHostile: true, representativeMime: null, hasAlpha: false };
-  }
-
-  it.each(["hevc", "prores", "theora"])(
-    "pre-warms %s, which has no cross-platform browser decode",
-    (codecName) => {
-      expect(shouldPrewarmProxy(facts(codecName))).toBe(true);
-    },
-  );
-
-  it.each(["vp9", "av1"])(
-    "does not pre-warm %s, which every mainstream engine decodes itself",
-    (codecName) => {
-      expect(shouldPrewarmProxy(facts(codecName))).toBe(false);
-    },
-  );
-
-  it("does not pre-warm a browser-safe codec", () => {
-    expect(
-      shouldPrewarmProxy({
-        codecName: "h264",
-        browserHostile: false,
-        representativeMime: null,
-        hasAlpha: false,
-      }),
-    ).toBe(false);
-  });
-
-  // `shouldPrewarmProxy` alone cannot catch a missing `Object.hasOwn` guard —
-  // `.prewarm === true` is already strict against `Object.prototype.constructor`.
-  // The input that misbehaves goes through `codecFactsFor`, which would report
-  // an ordinary asset as browser-hostile.
+describe("BROWSER_HOSTILE_CODECS lookup", () => {
+  // Without the `Object.hasOwn` guard, `codecFactsFor` would report an
+  // ordinary asset as browser-hostile.
   it("does not treat a codec named after an Object.prototype key as hostile", async () => {
     const project = tmpProject();
     const videoPath = join(project, "clip.mp4");
@@ -335,7 +303,6 @@ describe("shouldPrewarmProxy", () => {
       representativeMime: null,
       hasAlpha: false,
     });
-    expect(shouldPrewarmProxy(facts!)).toBe(false);
   });
 });