@hyperframes/studio 0.8.33 → 0.8.35

package/src/components/nle/useCompositionStack.ts

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "../../utils/projectRouting";
 // Composition drill-down stack management for NLEContext/EditorShell
 import { useState, useCallback, useRef, useEffect } from "react";
 import { usePlayerStore } from "../../player";
@@ -29,7 +30,7 @@ export function useCompositionStack({
     {
       id: "master",
       label: "Master",
-      previewUrl: `/api/projects/${projectId}/preview`,
+      previewUrl: buildProjectApiPath(projectId, `/preview`),
     },
   ]);
 
@@ -89,7 +90,10 @@ export function useCompositionStack({
             .split("/")
             .pop()
             ?.replace(/\.html$/, "") || resolvedPath;
-        const previewUrl = `/api/projects/${projectId}/preview/comp/${encodePreviewPath(resolvedPath)}`;
+        const previewUrl = buildProjectApiPath(
+          projectId,
+          `/preview/comp/${encodePreviewPath(resolvedPath)}`,
+        );
         return [...prev, { id: resolvedPath, label, previewUrl }];
       });
     },
@@ -103,7 +107,7 @@ export function useCompositionStack({
     const master: CompositionLevel = {
       id: "master",
       label: "Master",
-      previewUrl: `/api/projects/${projectId}/preview`,
+      previewUrl: buildProjectApiPath(projectId, `/preview`),
     };
     if (activeCompositionPath === "index.html") {
       usePlayerStore.getState().setElements([]);
@@ -116,7 +120,10 @@ export function useCompositionStack({
       // panel highlighted the row, so the canvas and timeline stayed on
       // index.html and edits landed in the root file.
       const label = activeCompositionPath.replace(/^compositions\//, "").replace(/\.html$/, "");
-      const previewUrl = `/api/projects/${projectId}/preview/comp/${encodePreviewPath(activeCompositionPath)}`;
+      const previewUrl = buildProjectApiPath(
+        projectId,
+        `/preview/comp/${encodePreviewPath(activeCompositionPath)}`,
+      );
       usePlayerStore.getState().setElements([]);
       updateCompositionStack((prev) => {
         if (prev[prev.length - 1]?.id === activeCompositionPath) return prev;

package/src/components/renders/RenderQueue.test.tsx

@@ -2,7 +2,7 @@
 
 import { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from "vitest";
 import { RenderQueue } from "./RenderQueue";
 import type { FfmpegStatus } from "./useFfmpegStatus";
 
@@ -26,7 +26,7 @@ afterEach(() => {
   document.body.innerHTML = "";
 });
 
-function mountRenderQueue(onStartRender: ReturnType<typeof vi.fn>) {
+function mountRenderQueue(onStartRender: Mock) {
   const host = document.createElement("div");
   document.body.append(host);
   root = createRoot(host);

package/src/components/renders/RenderQueueItem.tsx

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "../../utils/projectRouting";
 import { memo, useCallback, useState } from "react";
 import { VideoFrameThumbnail } from "../ui/VideoFrameThumbnail";
 import { Button } from "../ui/Button";
@@ -36,7 +37,7 @@ export const RenderQueueItem = memo(function RenderQueueItem({
   const [confirmingDelete, setConfirmingDelete] = useState(false);
 
   // Direct file URL — serves from disk, survives server restarts
-  const fileSrc = `/api/projects/${projectId}/renders/file/${job.filename}`;
+  const fileSrc = buildProjectApiPath(projectId, `/renders/file/${job.filename}`);
 
   const handleOpen = useCallback(() => {
     window.open(fileSrc, "_blank");

package/src/components/renders/useRenderQueue.ts

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "../../utils/projectRouting";
 import { useState, useEffect, useCallback, useRef, useMemo } from "react";
 import type { CanvasResolution } from "@hyperframes/parsers";
 import { trackStudioRenderStart } from "../../telemetry/events";
@@ -125,7 +126,7 @@ export function useRenderQueue(
   const loadRenders = useCallback(async () => {
     if (!projectId) return;
     try {
-      const res = await fetch(`/api/projects/${projectId}/renders`);
+      const res = await fetch(buildProjectApiPath(projectId, `/renders`));
       if (!res.ok) {
         setLoadError(`Couldn't load render history (server error ${res.status}).`);
         return;
@@ -261,7 +262,7 @@ export function useRenderQueue(
       }
       let res: Response;
       try {
-        res = await fetch(`/api/projects/${projectId}/render`, {
+        res = await fetch(buildProjectApiPath(projectId, `/render`), {
           method: "POST",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify(body),

package/src/components/sidebar/AssetsTab.tsx

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "../../utils/projectRouting";
 // fallow-ignore-file code-duplication
 import { memo, useState, useCallback, useRef, useMemo, useEffect } from "react";
 import { SearchInput } from "../ui/SearchInput";
@@ -216,7 +217,7 @@ export const AssetsTab = memo(function AssetsTab({
   useEffect(() => {
     if (manifest404Ref.current.has(projectId)) return;
     let cancelled = false;
-    fetch(`/api/projects/${projectId}/preview/.media/manifest.jsonl`)
+    fetch(buildProjectApiPath(projectId, `/preview/.media/manifest.jsonl`))
       .then((r) => {
         if (!r.ok) {
           manifest404Ref.current.add(projectId);

package/src/components/sidebar/CompositionsTab.tsx

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "../../utils/projectRouting";
 import { memo, useCallback, useEffect, useRef, useState } from "react";
 import { buildCompositionThumbnailUrl } from "../../player/components/CompositionThumbnail";
 import { setPreviewMediaMuted } from "../../player/lib/timelineIframeHelpers";
@@ -173,7 +174,7 @@ function CompCard({
     setLivePreviewLoaded(false);
   };
   const name = comp.replace(/^compositions\//, "").replace(/\.html$/, "");
-  const previewUrl = `/api/projects/${projectId}/preview/comp/${comp}`;
+  const previewUrl = buildProjectApiPath(projectId, `/preview/comp/${comp}`);
   const thumbnailUrl = buildCompositionThumbnailUrl({
     previewUrl,
     seekTime: THUMBNAIL_SEEK_TIME_SECONDS,

package/src/components/storyboard/FramePoster.tsx

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "../../utils/projectRouting";
 import { useEffect, useState } from "react";
 import { buildCompositionThumbnailUrl } from "../../player/components/CompositionThumbnail";
 
@@ -51,7 +52,7 @@ export function FramePoster({
     );
   }
   let url = buildCompositionThumbnailUrl({
-    previewUrl: `/api/projects/${projectId}/preview/comp/${src}`,
+    previewUrl: buildProjectApiPath(projectId, `/preview/comp/${src}`),
     seekTime: seconds,
     duration: 0,
     origin: window.location.origin,

package/src/hooks/useAskAgentModal.ts

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "../utils/projectRouting";
 import { useState, useCallback, useRef, useEffect } from "react";
 import { copyTextToClipboard } from "../utils/clipboard";
 import { readTagSnippetByTarget } from "../utils/sourcePatcher";
@@ -53,7 +54,7 @@ export function useAskAgentModal({
       const targetPath = selection.sourceFile || activeCompPath || "index.html";
       try {
         const response = await fetch(
-          `/api/projects/${pid}/files/${encodeURIComponent(targetPath)}`,
+          buildProjectApiPath(pid, `/files/${encodeURIComponent(targetPath)}`),
         );
         if (!response.ok) return;
 

package/src/hooks/useCaptionDetection.sender.test.tsx

@@ -0,0 +1,54 @@
+// @vitest-environment jsdom
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, it, vi } from "vitest";
+import { useCaptionDetection } from "./useCaptionDetection";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+it("does not let a foreign window trigger caption activation", () => {
+  const host = document.createElement("div");
+  const preview = document.createElement("iframe");
+  const foreign = document.createElement("iframe");
+  document.body.append(host, preview, foreign);
+  const root = createRoot(host);
+  const fetchMock = vi.fn(() => new Promise<Response>(() => {}));
+  vi.stubGlobal("fetch", fetchMock);
+  const params = {
+    projectId: "demo",
+    activeCompPath: "captions.html",
+    compIdToSrc: new Map<string, string>(),
+    captionEditMode: false,
+    captionHasSelection: false,
+    previewIframeRef: { current: preview },
+    captionSync: { save: vi.fn(), loadOverrides: vi.fn(async () => {}) },
+    setRightCollapsed: vi.fn(),
+  };
+  function Harness() {
+    useCaptionDetection(params);
+    return null;
+  }
+  const send = (source: MessageEventSource | null) =>
+    act(() => {
+      window.dispatchEvent(
+        new MessageEvent("message", { source, data: { source: "hf-preview", type: "state" } }),
+      );
+    });
+  try {
+    act(() => root.render(<Harness />));
+    const group = preview.contentDocument!.createElement("div");
+    group.className = "caption-group";
+    preview.contentDocument!.body.append(group);
+    send(foreign.contentWindow);
+    send(null);
+    expect(fetchMock).not.toHaveBeenCalled();
+    send(preview.contentWindow);
+    expect(fetchMock).toHaveBeenCalledOnce();
+  } finally {
+    act(() => root.unmount());
+    host.remove();
+    preview.remove();
+    foreign.remove();
+    vi.unstubAllGlobals();
+  }
+});

package/src/hooks/useCaptionDetection.ts

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "../utils/projectRouting";
 import { useEffect, useRef } from "react";
 import { useCaptionStore } from "../captions/store";
 import { acceptStudioRuntimeMessage } from "../player/lib/runtimeProtocol";
@@ -107,7 +108,7 @@ export function useCaptionDetection({
 
       activating = true;
       const srcPath = captionSrcPath;
-      fetch(`/api/projects/${projectId}/files/${encodeURIComponent(srcPath)}`)
+      fetch(buildProjectApiPath(projectId, `/files/${encodeURIComponent(srcPath)}`))
         .then((r) => r.json())
         .then((data: { content?: string }) => {
           if (!data.content || !doc || !win || useCaptionStore.getState().isEditMode) return;
@@ -130,6 +131,7 @@ export function useCaptionDetection({
     };
 
     const handleMessage = (e: MessageEvent) => {
+      if (!e.source || e.source !== previewIframeRef.current?.contentWindow) return;
       const data = e.data;
       if (data?.source === "hf-preview" && (data?.type === "state" || data?.type === "timeline")) {
         if (!acceptStudioRuntimeMessage(data)) return;

package/src/hooks/useCompositionContentLoader.ts

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "../utils/projectRouting";
 import { useCallback } from "react";
 
 /**
@@ -20,9 +21,10 @@ export function useCompositionContentLoader({
 }) {
   return useCallback(
     (comp: string) => {
+      if (!projectId) return;
       setActiveCompPath(comp.endsWith(".html") ? comp : null);
       setEditingFile({ path: comp, content: null });
-      fetch(`/api/projects/${projectId}/files/${comp}`)
+      fetch(buildProjectApiPath(projectId, `/files/${encodeURIComponent(comp)}`))
         .then(async (r) => {
           if (!r.ok) throw new Error(`Failed to load ${comp} (${r.status})`);
           return r.json();

package/src/hooks/useCompositionDimensions.test.tsx

@@ -0,0 +1,47 @@
+// @vitest-environment jsdom
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, it } from "vitest";
+import { useCompositionDimensions } from "./useCompositionDimensions";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+it("accepts only the current preview frame and rejects foreign or missing senders", () => {
+  const host = document.createElement("div");
+  const preview = document.createElement("iframe");
+  const foreign = document.createElement("iframe");
+  document.body.append(host, preview, foreign);
+  const ref = { current: preview };
+  const root = createRoot(host);
+  function Harness() {
+    return JSON.stringify(useCompositionDimensions(ref));
+  }
+  const send = (source: MessageEventSource | null, width: number) =>
+    act(() => {
+      window.dispatchEvent(
+        new MessageEvent("message", {
+          source,
+          origin: window.location.origin,
+          data: { source: "hf-preview", type: "stage-size", width, height: 100 },
+        }),
+      );
+    });
+  try {
+    act(() => root.render(<Harness />));
+    send(foreign.contentWindow, 300);
+    send(null, 400);
+    expect(host.textContent).toBe("null");
+    send(preview.contentWindow, 200);
+    expect(host.textContent).toBe('{"width":200,"height":100}');
+    ref.current = foreign;
+    send(preview.contentWindow, 500);
+    expect(host.textContent).toBe('{"width":200,"height":100}');
+    send(foreign.contentWindow, 600);
+    expect(host.textContent).toBe('{"width":600,"height":100}');
+  } finally {
+    act(() => root.unmount());
+    host.remove();
+    preview.remove();
+    foreign.remove();
+  }
+});

package/src/hooks/useCompositionDimensions.ts

@@ -1,4 +1,4 @@
-import { useState } from "react";
+import { useState, type RefObject } from "react";
 import { useMountEffect } from "./useMountEffect";
 import type { CompositionDimensions } from "../components/renders/RenderQueue";
 import { acceptStudioRuntimeMessage } from "../player/lib/runtimeProtocol";
@@ -29,13 +29,14 @@ function readPositiveDimensions(width: unknown, height: unknown): CompositionDim
   return { width: parsedWidth, height: parsedHeight };
 }
 
-export function useCompositionDimensions() {
+export function useCompositionDimensions(iframeRef: RefObject<HTMLIFrameElement | null>) {
   const [compositionDimensions, setCompositionDimensions] = useState<CompositionDimensions | null>(
     null,
   );
 
   useMountEffect(() => {
     const handleMessage = (e: MessageEvent) => {
+      if (!e.source || e.source !== iframeRef.current?.contentWindow) return;
       const dimensions = readCompositionSizeMessage(e.data);
       if (!dimensions) return;
       setCompositionDimensions((prev) =>

package/src/hooks/useDomEditCommits.ts

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "../utils/projectRouting";
 import { useCallback, useRef } from "react";
 import { findUnsafeDomPatchValues } from "@hyperframes/core/studio-api/finite-mutation";
 import { FONT_EXT } from "../utils/mediaTypes";
@@ -127,11 +128,11 @@ export function useDomEditCommits({
           FONT_EXT.test(path) &&
           fontFamilyFromAssetPath(path).toLowerCase() === family.toLowerCase(),
       );
-      if (!asset) return null;
+      if (!asset || !projectId) return null;
       return {
         family: fontFamilyFromAssetPath(asset),
         path: asset,
-        url: `/api/projects/${projectId}/preview/${asset}`,
+        url: buildProjectApiPath(projectId, `/preview/${asset}`),
       };
     },
     [fileTree, projectId, importedFontAssetsRef],
@@ -161,7 +162,7 @@ export function useDomEditCommits({
       };
 
       const readResponse = await fetch(
-        `/api/projects/${pid}/files/${encodeURIComponent(targetPath)}`,
+        buildProjectApiPath(pid, `/files/${encodeURIComponent(targetPath)}`),
       );
       if (!readResponse.ok) {
         throw await createStudioSaveHttpError(readResponse, `Failed to read ${targetPath}`);
@@ -219,7 +220,7 @@ export function useDomEditCommits({
       domEditSaveTimestampRef.current = Date.now();
 
       const patchResponse = await fetch(
-        `/api/projects/${pid}/file-mutations/patch-element/${encodeURIComponent(targetPath)}`,
+        buildProjectApiPath(pid, `/file-mutations/patch-element/${encodeURIComponent(targetPath)}`),
         {
           method: "POST",
           headers: { "Content-Type": "application/json", ...studioWriteHeaders() },

package/src/hooks/useElementLifecycleOps.ts

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "../utils/projectRouting";
 import { useCallback } from "react";
 import { usePlayerStore } from "../player";
 import {
@@ -152,7 +153,10 @@ export function useElementLifecycleOps({
         // selection runs to hundreds of members — the file ended up correct, but
         // only after long enough that Delete looked like it had done nothing.
         const removeResponse = await fetch(
-          `/api/projects/${pid}/file-mutations/remove-elements/${encodeURIComponent(targetPath)}`,
+          buildProjectApiPath(
+            pid,
+            `/file-mutations/remove-elements/${encodeURIComponent(targetPath)}`,
+          ),
           {
             method: "POST",
             headers: { "Content-Type": "application/json", ...studioWriteHeaders() },

package/src/hooks/useFileTree.ts

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "../utils/projectRouting";
 import { useState, useCallback, useEffect, useMemo } from "react";
 import { FONT_EXT } from "../utils/mediaTypes";
 import { fontFamilyFromAssetPath, type ImportedFontAsset } from "../components/editor/fontAssets";
@@ -22,7 +23,7 @@ export function useFileTree({ projectId, projectIdRef }: UseFileTreeOptions) {
     }
     let cancelled = false;
     setFileTreeLoaded(false);
-    fetch(`/api/projects/${projectId}`)
+    fetch(buildProjectApiPath(projectId))
       .then((r) => r.json())
       .then((data: { files?: string[]; dir?: string; compositions?: string[] }) => {
         if (cancelled) return;
@@ -47,7 +48,7 @@ export function useFileTree({ projectId, projectIdRef }: UseFileTreeOptions) {
   const refreshFileTree = useCallback(async () => {
     const pid = projectIdRef.current;
     if (!pid) return;
-    const res = await fetch(`/api/projects/${pid}`);
+    const res = await fetch(buildProjectApiPath(pid));
     const data = await res.json();
     if (data.files) setFileTree(data.files);
   }, [projectIdRef]);
@@ -62,12 +63,12 @@ export function useFileTree({ projectId, projectIdRef }: UseFileTreeOptions) {
 
   const fontAssets = useMemo<ImportedFontAsset[]>(
     () =>
-      assets
+      (projectId ? assets : [])
         .filter((asset) => FONT_EXT.test(asset))
         .map((asset) => ({
           family: fontFamilyFromAssetPath(asset),
           path: asset,
-          url: `/api/projects/${projectId}/preview/${asset}`,
+          url: projectId ? buildProjectApiPath(projectId, `/preview/${asset}`) : "",
         })),
     [assets, projectId],
   );

package/src/hooks/useGroupCommits.ts

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "../utils/projectRouting";
 import { useCallback } from "react";
 import {
   readProjectFileContent,
@@ -73,7 +74,7 @@ async function commitStructuralMutation(
 
   deps.domEditSaveTimestampRef.current = Date.now();
   const mutateResponse = await fetch(
-    `/api/projects/${pid}/file-mutations/${route}/${encodeURIComponent(targetPath)}`,
+    buildProjectApiPath(pid, `/file-mutations/${route}/${encodeURIComponent(targetPath)}`),
     {
       method: "POST",
       headers: { "Content-Type": "application/json", ...studioWriteHeaders() },

package/src/hooks/useGsapInteractionFailureTelemetry.test.tsx

@@ -1,7 +1,7 @@
 // @vitest-environment happy-dom
 
 import React, { act } from "react";
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi, type Mock } from "vitest";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { mountReactHarness } from "./domSelectionTestHarness";
 import { GsapEditBlockedError } from "./gsapEditOutcome";
@@ -25,7 +25,7 @@ const selection = {
   element: document.createElement("div"),
 } as unknown as DomEditSelection;
 
-function mountFailureTelemetry(showToast: ReturnType<typeof vi.fn>) {
+function mountFailureTelemetry(showToast: Mock) {
   let report!: ReturnType<typeof useGsapInteractionFailureTelemetry>;
   function Harness() {
     report = useGsapInteractionFailureTelemetry("index.html", showToast);

package/src/hooks/useLintModal.ts

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "../utils/projectRouting";
 import { useState, useCallback, useEffect, useRef, useMemo } from "react";
 import type { LintFinding } from "../components/LintModal";
 import { usePlayerStore } from "../player";
@@ -35,7 +36,7 @@ export function useLintModal(projectId: string | null, refreshKey?: number) {
       if (!projectId) return;
       if (!opts?.background) setLinting(true);
       try {
-        const res = await fetch(`/api/projects/${projectId}/lint`);
+        const res = await fetch(buildProjectApiPath(projectId, `/lint`));
         const data = await res.json();
         const parsed = ((data.findings ?? []) as RawFinding[]).map(parseFinding);
         if (opts?.background) {

package/src/hooks/useRenderClipContent.ts

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "../utils/projectRouting";
 import { useCallback, type ReactNode } from "react";
 import { createElement } from "react";
 import { CompositionThumbnail, VideoThumbnail } from "../player";
@@ -16,7 +17,7 @@ export function normalizeCompositionSrc(
 ): string {
   try {
     const parsed = new URL(compSrc, origin);
-    const previewPrefix = `/api/projects/${projectId}/preview/`;
+    const previewPrefix = buildProjectApiPath(projectId, `/preview/`);
     if (parsed.pathname.startsWith(previewPrefix)) {
       return parsed.pathname.slice(previewPrefix.length);
     }
@@ -35,7 +36,7 @@ function resolvePreviewRelative(
   if (!src) return null;
   try {
     const parsed = new URL(src, origin);
-    const base = new URL(`/api/projects/${pid}/preview/`, origin).pathname;
+    const base = new URL(buildProjectApiPath(pid, `/preview/`), origin).pathname;
     return parsed.pathname.startsWith(base)
       ? decodeURIComponent(parsed.pathname.slice(base.length))
       : null;
@@ -77,7 +78,7 @@ function renderAudioClip(
   // returns the DECODED path, so it must be re-encoded here.
   const encodedRelative = srcRelative ? encodePreviewPath(srcRelative) : null;
   const waveformUrl = encodedRelative
-    ? `/api/projects/${pid}/waveform/${encodedRelative}`
+    ? buildProjectApiPath(pid, `/waveform/${encodedRelative}`)
     : undefined;
   const { start, end } = trimFractions(el);
   return createElement(AudioWaveform, {
@@ -146,7 +147,7 @@ export function useRenderClipContent({
       // instead of capturing the master at a time when the comp is fading in.
       if (compSrc) {
         return createElement(CompositionThumbnail, {
-          previewUrl: `/api/projects/${pid}/preview/comp/${encodePreviewPath(compSrc)}`,
+          previewUrl: buildProjectApiPath(pid, `/preview/comp/${encodePreviewPath(compSrc)}`),
           label: "",
           labelColor: style.label,
 
@@ -225,7 +226,7 @@ export function useRenderClipContent({
 
       if (htmlPreviewEligible) {
         return createElement(CompositionThumbnail, {
-          previewUrl: `/api/projects/${pid}/preview`,
+          previewUrl: buildProjectApiPath(pid, `/preview`),
           label: "",
           labelColor: style.label,
 

package/src/hooks/useTimelineDeleteOps.ts

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "../utils/projectRouting";
 // Timeline clip deletion: the marquee/multi path and the single-clip wrapper
 // the context menu uses. Extracted verbatim from useTimelineEditing.ts to keep
 // it under the studio 600-line cap, following useTimelineAssetDropOps.
@@ -76,7 +77,10 @@ export function useTimelineDeleteOps({
           }
 
           const removeResponse = await fetch(
-            `/api/projects/${pid}/file-mutations/remove-element/${encodeURIComponent(targetPath)}`,
+            buildProjectApiPath(
+              pid,
+              `/file-mutations/remove-element/${encodeURIComponent(targetPath)}`,
+            ),
             {
               method: "POST",
               headers: { "Content-Type": "application/json", ...studioWriteHeaders() },

package/src/player/components/Player.tsx

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "../../utils/projectRouting";
 import { forwardRef, useEffect, useRef, useState } from "react";
 import { isLottieAnimationLoaded } from "@hyperframes/core/runtime/lottie-readiness";
 import { useMountEffect } from "../../hooks/useMountEffect";
@@ -158,6 +159,10 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
       const container = containerRef.current;
       if (!container) return;
 
+      const previewSource =
+        directUrl || (projectId ? buildProjectApiPath(projectId, "/preview") : null);
+      if (!previewSource) return;
+
       let canceled = false;
       let cleanup: (() => void) | undefined;
 
@@ -167,10 +172,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
 
         // Create the web component imperatively to avoid JSX custom-element typing.
         const player = document.createElement("hyperframes-player") as HyperframesPlayerElement;
-        const srcUrl = new URL(
-          directUrl || `/api/projects/${projectId}/preview`,
-          window.location.origin,
-        );
+        const srcUrl = new URL(previewSource, window.location.origin);
         applyPreviewVariablesToUrl(srcUrl);
         const src = srcUrl.pathname + srcUrl.search;
         const retryPreview = () => {

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

@@ -1,6 +1,6 @@
 // @vitest-environment happy-dom
 import { act } from "react";
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it, vi, type Mock } from "vitest";
 import { createRoot } from "react-dom/client";
 import { TimelineAutomationLane } from "./TimelineAutomationLane";
 import { PAD_X } from "./automationLaneGeometry";
@@ -602,8 +602,8 @@ const mount = (automation: HfAutomation, over: Record<string, unknown> = {}) =>
   // assertion below reads the calls the lane made.
   const props = {
     ...base,
-    onPreview: base.onPreview as ReturnType<typeof vi.fn>,
-    onCommit: base.onCommit as ReturnType<typeof vi.fn>,
+    onPreview: base.onPreview as Mock,
+    onCommit: base.onCommit as Mock,
   };
   const { container } = render(<TimelineAutomationLane {...props} />);
   const svg = container.querySelector("svg")!;
@@ -685,7 +685,7 @@ describe("TimelineAutomationLane segment drag", () => {
     ],
   };
 
-  const previewedPoints = (props: { onPreview: ReturnType<typeof vi.fn> }) =>
+  const previewedPoints = (props: { onPreview: Mock }) =>
     props.onPreview.mock.calls.at(-1)?.[0].lanes[0].points as {
       t: number;
       v: number;
@@ -787,8 +787,8 @@ const mountRerenderable = (automation: HfAutomation, over: Record<string, unknow
   const base = laneProps({ automation, ...over });
   const props = {
     ...base,
-    onPreview: base.onPreview as ReturnType<typeof vi.fn>,
-    onCommit: base.onCommit as ReturnType<typeof vi.fn>,
+    onPreview: base.onPreview as Mock,
+    onCommit: base.onCommit as Mock,
   };
   const { container, rerender } = renderRerenderable(<TimelineAutomationLane {...props} />);
   const svg = container.querySelector("svg")!;
@@ -944,7 +944,7 @@ describe("TimelineAutomationLane modifiers", () => {
       },
     ],
   };
-  const draggedTimes = (props: { onPreview: ReturnType<typeof vi.fn> }) => {
+  const draggedTimes = (props: { onPreview: Mock }) => {
     const points = props.onPreview.mock.calls.at(-1)?.[0].lanes[0].points as
       | { t: number }[]
       | undefined;
@@ -1204,7 +1204,7 @@ describe("TimelineAutomationLane group drag", () => {
       },
     ],
   };
-  const pointsOf = (props: { onPreview: ReturnType<typeof vi.fn> }) =>
+  const pointsOf = (props: { onPreview: Mock }) =>
     props.onPreview.mock.calls.at(-1)?.[0].lanes[0].points as { t: number; v: number }[];
 
   it("moves every selected point by the same distance", () => {
@@ -1346,7 +1346,7 @@ describe("TimelineAutomationLane shift axis lock", () => {
       },
     ],
   };
-  const lastPoints = (props: { onPreview: ReturnType<typeof vi.fn> }) =>
+  const lastPoints = (props: { onPreview: Mock }) =>
     props.onPreview.mock.calls.at(-1)?.[0].lanes[0].points as { t: number; v: number }[];
 
   it("holds the value when the pointer travels mostly sideways", () => {

package/src/player/components/thumbnailUtils.ts

@@ -1,3 +1,4 @@
+import { buildProjectApiPath } from "../../utils/projectRouting";
 /** Rendered height of a timeline-clip thumbnail strip, in CSS px. */
 export const THUMBNAIL_CLIP_HEIGHT = 66;
 
@@ -113,7 +114,7 @@ export function resolveMediaPreviewUrl(
       return src;
     }
     if (!studioOrigin || parsed.origin !== studioOrigin) return src;
-    const previewPath = new URL(`/api/projects/${projectId}/preview/`, studioOrigin).pathname;
+    const previewPath = new URL(buildProjectApiPath(projectId, `/preview/`), studioOrigin).pathname;
     if (parsed.pathname.startsWith(previewPath)) return src;
     if (parsed.pathname.startsWith("/api/")) return src;
     try {
@@ -128,5 +129,8 @@ export function resolveMediaPreviewUrl(
     suffix = `${parsed.search}${parsed.hash}`;
   }
 
-  return `/api/projects/${projectId}/preview/${encodePreviewPath(relativePath.replace(/^\/+/, ""))}${suffix}`;
+  return buildProjectApiPath(
+    projectId,
+    `/preview/${encodePreviewPath(relativePath.replace(/^\/+/, ""))}${suffix}`,
+  );
 }