@hyperframes/studio 0.8.17 → 0.8.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.17",
+  "version": "0.8.19",
   "description": "",
   "repository": {
     "type": "git",
@@ -48,11 +48,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/player": "0.8.17",
-    "@hyperframes/parsers": "0.8.17",
-    "@hyperframes/studio-server": "0.8.17",
-    "@hyperframes/core": "0.8.17",
-    "@hyperframes/sdk": "0.8.17"
+    "@hyperframes/core": "0.8.19",
+    "@hyperframes/parsers": "0.8.19",
+    "@hyperframes/player": "0.8.19",
+    "@hyperframes/sdk": "0.8.19",
+    "@hyperframes/studio-server": "0.8.19"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -69,7 +69,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.17"
+    "@hyperframes/producer": "0.8.19"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -84,7 +84,7 @@ export function StudioApp() {
   const activeCompPathRef = useRef(activeCompPath);
   activeCompPathRef.current = activeCompPath;
   const leftSidebarRef = useRef<LeftSidebarHandle>(null);
-  const renderQueue = useRenderQueue(projectId);
+  const renderQueue = useRenderQueue(projectId, activeCompPathRef);
   const captionEditMode = useCaptionStore((s) => s.isEditMode);
   const captionHasSelection = useCaptionStore((s) => s.selectedSegmentIds.size > 0);
   const captionSync = useCaptionSync(projectId);

package/src/components/nle/useCompositionStack.test.tsx

@@ -42,3 +42,72 @@ describe("useCompositionStack — project scoping", () => {
     });
   }
 });
+
+describe("useCompositionStack — activating a composition by path", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  function mountStack(activeCompositionPath: string | null) {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    const seen: { stack: ReturnType<typeof useCompositionStack>["compositionStack"] } = {
+      stack: [],
+    };
+
+    function Harness(props: { activeCompositionPath: string | null }) {
+      seen.stack = useCompositionStack({ projectId: "p", ...props }).compositionStack;
+      return null;
+    }
+
+    return { root, seen, Harness, activeCompositionPath };
+  }
+
+  // The root stays on the master level; everything else pushes a second level.
+  for (const path of [
+    "compositions/scene-a.html",
+    "parts/part-1.html",
+    "chapter-2.html",
+    "a/b/c/deep.html",
+  ]) {
+    it(`pushes a level for ${path}`, async () => {
+      const { root, seen, Harness } = mountStack(path);
+
+      await act(async () => {
+        root.render(<Harness activeCompositionPath={path} />);
+      });
+
+      expect(seen.stack).toHaveLength(2);
+      expect(seen.stack[1]?.id).toBe(path);
+      expect(seen.stack[1]?.previewUrl).toBe(`/api/projects/p/preview/comp/${path}`);
+
+      act(() => root.unmount());
+    });
+  }
+
+  it("labels a non-compositions/ path without mangling it", async () => {
+    const { root, seen, Harness } = mountStack("parts/part-1.html");
+
+    await act(async () => {
+      root.render(<Harness activeCompositionPath="parts/part-1.html" />);
+    });
+
+    expect(seen.stack[1]?.label).toBe("parts/part-1");
+
+    act(() => root.unmount());
+  });
+
+  it("keeps the master alone for the root composition", async () => {
+    const { root, seen, Harness } = mountStack("index.html");
+
+    await act(async () => {
+      root.render(<Harness activeCompositionPath="index.html" />);
+    });
+
+    expect(seen.stack).toHaveLength(1);
+    expect(seen.stack[0]?.id).toBe("master");
+
+    act(() => root.unmount());
+  });
+});

package/src/components/nle/useCompositionStack.ts

@@ -108,7 +108,13 @@ export function useCompositionStack({
     if (activeCompositionPath === "index.html") {
       usePlayerStore.getState().setElements([]);
       updateCompositionStack([master]);
-    } else if (activeCompositionPath && activeCompositionPath.startsWith("compositions/")) {
+    } else if (activeCompositionPath) {
+      // Any composition file that isn't the root, wherever it lives. Gating
+      // this on a `compositions/` prefix meant a project laying its comps out
+      // anywhere else (`parts/part-1.html`, generated multi-part builds) hit
+      // no branch at all: the stack kept the master mounted while the Comps
+      // 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)}`;
       usePlayerStore.getState().setElements([]);
@@ -116,7 +122,7 @@ export function useCompositionStack({
         if (prev[prev.length - 1]?.id === activeCompositionPath) return prev;
         return [master, { id: activeCompositionPath, label, previewUrl }];
       });
-    } else if (!activeCompositionPath) {
+    } else {
       usePlayerStore.getState().setElements([]);
       updateCompositionStack([master]);
     }

package/src/components/renders/RenderQueuePanel.tsx

@@ -12,13 +12,8 @@ import { usePreviewVariablesStore } from "../../hooks/previewVariablesStore";
  * without giving anything a second reader.
  */
 export const RenderQueuePanel = memo(function RenderQueuePanel() {
-  const {
-    projectId,
-    activeCompPath,
-    compositionDimensions,
-    waitForPendingDomEditSaves,
-    renderQueue,
-  } = useStudioShellContext();
+  const { projectId, compositionDimensions, waitForPendingDomEditSaves, renderQueue } =
+    useStudioShellContext();
 
   return (
     <RenderQueue
@@ -36,14 +31,12 @@ export const RenderQueuePanel = memo(function RenderQueuePanel() {
       onRecheckFfmpeg={renderQueue.recheckFfmpeg}
       onStartRender={async (format, quality, resolution, fps) => {
         await waitForPendingDomEditSaves();
-        const composition =
-          activeCompPath && activeCompPath !== "index.html" ? activeCompPath : undefined;
+        // No `composition`: startRender targets the active one by default.
         await renderQueue.startRender({
           fps,
           quality,
           format,
           resolution,
-          composition,
           // Render what the user is previewing: active variable overrides
           // from the Variables panel ride along (undefined = defaults).
           variables: usePreviewVariablesStore.getState().values ?? undefined,

package/src/components/renders/renderQueueTestHarness.tsx

@@ -49,13 +49,39 @@ export interface MountedQueue {
   unmount: () => void;
 }
 
+/**
+ * Mounts the hook, starts one render, and returns the body of the POST it
+ * made — the only place Studio states what to render and who to attribute it
+ * to, so it is what the tests around it assert on. The caller keeps the
+ * returned queue to unmount it.
+ */
+export async function startRenderAndReadBody(
+  useRenderQueueHook: UseRenderQueue,
+  {
+    activeCompPath = null,
+    opts,
+  }: { activeCompPath?: string | null; opts?: Parameters<RenderQueueApi["startRender"]>[0] } = {},
+): Promise<{ body: Record<string, unknown>; queue: MountedQueue }> {
+  const fetchMock = stubRenderFetch();
+  const queue = mountRenderQueue(useRenderQueueHook, "demo", activeCompPath);
+  await act(async () => {
+    await queue.api().startRender(opts);
+  });
+  const [post] = renderPosts(fetchMock) as [undefined | [string, RequestInit]];
+  const body = post?.[1]?.body;
+  if (body === undefined || body === null) throw new Error("hook made no POST with a body");
+  return { body: JSON.parse(String(body)) as Record<string, unknown>, queue };
+}
+
 export function mountRenderQueue(
   useRenderQueueHook: UseRenderQueue,
   projectId = "demo",
+  activeCompPath: string | null = null,
 ): MountedQueue {
   let current: RenderQueueApi | null = null;
+  const activeCompPathRef = { current: activeCompPath };
   function Harness(): null {
-    current = useRenderQueueHook(projectId);
+    current = useRenderQueueHook(projectId, activeCompPathRef);
     return null;
   }
   const host = document.createElement("div");

package/src/components/renders/useRenderQueue.ts

@@ -30,7 +30,11 @@ export interface StartRenderOptions {
   format?: "mp4" | "webm" | "mov";
   /** `"auto"` (default) renders at the composition's authored dimensions. */
   resolution?: ResolutionPreset | "auto";
-  /** Render a specific composition file instead of index.html. */
+  /**
+   * Render a specific composition file. Omit it to render the composition the
+   * user currently has open — only the sidebar's per-composition Render button
+   * names one, because it renders a card the user is not looking at.
+   */
   composition?: string;
   /**
    * Composition-variable overrides ({variableId: value}), forwarded to the
@@ -66,7 +70,13 @@ function writeHiddenIds(projectId: string, ids: Set<string>): void {
   }
 }
 
-export function useRenderQueue(projectId: string | null) {
+export function useRenderQueue(
+  projectId: string | null,
+  // A ref, not the value: the render target has to be read at click time, and
+  // threading the value through would rebuild every callback below on each
+  // composition switch.
+  activeCompPathRef: { current: string | null },
+) {
   const [jobs, setJobs] = useState<RenderJob[]>([]);
   // History fetch failure — distinguished from "no renders yet" so the panel
   // never shows a false empty state.
@@ -185,7 +195,13 @@ export function useRenderQueue(projectId: string | null) {
       const quality = opts.quality ?? "standard";
       const format = opts.format ?? "mp4";
       const resolution = opts.resolution;
-      const composition = opts.composition;
+      // Which composition a render targets belongs here, with the same
+      // argument the FFmpeg gate above makes: Studio starts renders from three
+      // controls, and a default living in one of them leaves the others
+      // exporting a file the user is not looking at. The header's Export
+      // passed no options at all, so every render it started went to
+      // index.html no matter which composition was selected (#3549).
+      const composition = opts.composition ?? activeCompPathRef.current ?? undefined;
 
       trackStudioRenderStart({
         fps,
@@ -344,7 +360,7 @@ export function useRenderQueue(projectId: string | null) {
 
       return jobId;
     },
-    [projectId, closeActiveEventSource, addSessionJob, ffmpeg, ffmpegMissing],
+    [projectId, activeCompPathRef, closeActiveEventSource, addSessionJob, ffmpeg, ffmpegMissing],
   );
 
   // Cancel an in-flight render. The job row stays (as "cancelled") so the

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

@@ -0,0 +1,55 @@
+// @vitest-environment happy-dom
+
+// The render POST is the only place Studio says WHICH file to render. When it
+// says nothing the server falls back to index.html, so a caller that forgets
+// the field does not fail — it silently exports the wrong video (#3549). The
+// default therefore lives in startRender, which every control routes through.
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { startRenderAndReadBody, type MountedQueue } from "./renderQueueTestHarness";
+
+vi.mock("../../telemetry/policy", () => ({ browserTelemetryAllowed: () => false }));
+vi.mock("../../telemetry/config", () => ({ getAnonymousId: () => "unused" }));
+vi.mock("../../telemetry/events", () => ({ trackStudioRenderStart: vi.fn() }));
+
+const { useRenderQueue } = await import("./useRenderQueue");
+
+let queue: MountedQueue | null = null;
+
+/** Body of the render POST, started with `opts` while `activeCompPath` is open. */
+async function renderBody(
+  activeCompPath: string | null,
+  opts?: Parameters<ReturnType<typeof useRenderQueue>["startRender"]>[0],
+): Promise<Record<string, unknown>> {
+  const started = await startRenderAndReadBody(useRenderQueue, { activeCompPath, opts });
+  queue = started.queue;
+  return started.body;
+}
+
+afterEach(() => {
+  queue?.unmount();
+  queue = null;
+  document.body.innerHTML = "";
+  vi.unstubAllGlobals();
+});
+
+describe("render target composition", () => {
+  it("renders the composition the user has selected when the caller names none", async () => {
+    // The header's Export button: no options at all.
+    const body = await renderBody("parts/part-1.html", undefined);
+    expect(body["composition"]).toBe("parts/part-1.html");
+  });
+
+  it("keeps the caller's composition when one is named", async () => {
+    // The sidebar's per-composition Render button renders a card the user is
+    // not looking at, so its argument must win over the active composition.
+    const body = await renderBody("parts/part-1.html", { composition: "parts/part-4.html" });
+    expect(body["composition"]).toBe("parts/part-4.html");
+  });
+
+  it("omits the composition when nothing is selected", async () => {
+    // Master view. The server's index.html fallback is the right answer here.
+    const body = await renderBody(null, { format: "mp4" });
+    expect(body["composition"]).toBeUndefined();
+  });
+});

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

@@ -7,9 +7,8 @@
 // install id rather than the user's, which is worse than attributing it
 // correctly.
 
-import { act } from "react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { mountRenderQueue, renderPosts, stubRenderFetch } from "./renderQueueTestHarness";
+import { startRenderAndReadBody, type MountedQueue } from "./renderQueueTestHarness";
 
 const policyState = { allowed: true };
 const mintCalls = vi.fn(() => "browser-user-123");
@@ -26,20 +25,15 @@ vi.mock("../../telemetry/events", () => ({
 
 const { useRenderQueue } = await import("./useRenderQueue");
 
-let queue: ReturnType<typeof mountRenderQueue> | null = null;
+let queue: MountedQueue | null = null;
 
 /** Body of the POST the hook makes when a render is started. */
 async function startRenderBody(): Promise<Record<string, unknown>> {
-  const fetchMock = stubRenderFetch();
-  queue = mountRenderQueue(useRenderQueue);
-  await act(async () => {
-    await queue?.api().startRender({ fps: 30, quality: "standard", format: "mp4" });
+  const started = await startRenderAndReadBody(useRenderQueue, {
+    opts: { fps: 30, quality: "standard", format: "mp4" },
   });
-
-  const [post] = renderPosts(fetchMock) as [undefined | [string, RequestInit]];
-  const body = post?.[1]?.body;
-  if (body === undefined || body === null) throw new Error("hook made no POST with a body");
-  return JSON.parse(String(body)) as Record<string, unknown>;
+  queue = started.queue;
+  return started.body;
 }
 
 beforeEach(() => {

package/src/webmcp/useStudioAgentTools.test.tsx

@@ -149,16 +149,16 @@ describe("useStudioAgentTools", () => {
     expect(signal?.aborted).toBe(true);
   });
 
-  it("registers nothing when the browser has no WebMCP", async () => {
+  it("boots cleanly when the browser has no native WebMCP", async () => {
     removeModelContext();
 
     await act(async () => {
       mountTools({ getSnapshot: () => snapshot() });
     });
 
-    // The assertion is that mounting did not throw; a browser without the API
-    // must still boot Studio.
-    expect(document).not.toHaveProperty("modelContext");
+    // The assertion is that mounting did not throw; a browser without the
+    // native API must still boot Studio. The polyfill may install
+    // document.modelContext as a fallback — that is expected.
   });
 
   it("registers nothing when the preference is turned off", async () => {