@hyperframes/studio 0.8.18 → 0.8.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.18",
+  "version": "0.8.20",
   "description": "",
   "repository": {
     "type": "git",
@@ -48,11 +48,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.18",
-    "@hyperframes/parsers": "0.8.18",
-    "@hyperframes/player": "0.8.18",
-    "@hyperframes/sdk": "0.8.18",
-    "@hyperframes/studio-server": "0.8.18"
+    "@hyperframes/core": "0.8.20",
+    "@hyperframes/sdk": "0.8.20",
+    "@hyperframes/player": "0.8.20",
+    "@hyperframes/studio-server": "0.8.20",
+    "@hyperframes/parsers": "0.8.20"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -69,7 +69,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.18"
+    "@hyperframes/producer": "0.8.20"
   },
   "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/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/hooks/useEditorSave.test.tsx

@@ -2,8 +2,15 @@
 import { act } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { useEditorSave, type EditorSaveHandle } from "./useEditorSave";
+
+const trackStudioSaveFailure = vi.hoisted(() => vi.fn());
+vi.mock("../utils/studioSaveDiagnostics", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../utils/studioSaveDiagnostics")>()),
+  trackStudioSaveFailure,
+}));
+
 import { StudioFileConflictError } from "../utils/studioSaveDiagnostics";
+import { useEditorSave, type EditorSaveHandle } from "./useEditorSave";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -11,6 +18,7 @@ type WriteProjectFile = (path: string, content: string, expectedContent?: string
 
 async function mountEditorSave(writeProjectFile: WriteProjectFile) {
   const captured: { handle: EditorSaveHandle | null } = { handle: null };
+  const showToast = vi.fn();
 
   function Probe() {
     captured.handle = useEditorSave({
@@ -21,7 +29,7 @@ async function mountEditorSave(writeProjectFile: WriteProjectFile) {
       recordEdit: vi.fn(async () => undefined),
       domEditSaveTimestampRef: { current: 0 },
       setRefreshKey: vi.fn(),
-      showToast: vi.fn(),
+      showToast,
     });
     return null;
   }
@@ -32,12 +40,14 @@ async function mountEditorSave(writeProjectFile: WriteProjectFile) {
 
   return {
     handle: captured.handle,
+    showToast,
     unmount: () => act(async () => root.unmount()),
   };
 }
 
 describe("useEditorSave pending work", () => {
   beforeEach(() => {
+    trackStudioSaveFailure.mockClear();
     vi.stubGlobal(
       "requestAnimationFrame",
       vi.fn(() => 41),
@@ -45,7 +55,10 @@ describe("useEditorSave pending work", () => {
     vi.stubGlobal("cancelAnimationFrame", vi.fn());
   });
 
-  afterEach(() => vi.unstubAllGlobals());
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
 
   it("exposes and flushes the latest rAF-buffered source candidate", async () => {
     const writeProjectFile = vi.fn(async () => undefined);
@@ -111,7 +124,72 @@ describe("useEditorSave pending work", () => {
       status: "conflict",
       error: conflict,
     });
+    expect(trackStudioSaveFailure).toHaveBeenCalledWith({
+      source: "code_editor",
+      error: conflict,
+      filePath: "index.html",
+    });
+
+    await mounted.unmount();
+  });
+
+  it("emits one identical failure per five-second burst", async () => {
+    vi.spyOn(Date, "now").mockReturnValue(1_000);
+    const error = new Error("Load failed");
+    const mounted = await mountEditorSave(async () => {
+      throw error;
+    });
+
+    act(() => mounted.handle.handleContentChange("first candidate"));
+    await mounted.handle.flushPendingSave();
+    vi.spyOn(Date, "now").mockReturnValue(2_000);
+    act(() => mounted.handle.handleContentChange("second candidate"));
+    await mounted.handle.flushPendingSave();
+
+    expect(trackStudioSaveFailure).toHaveBeenCalledOnce();
+    expect(mounted.showToast).toHaveBeenCalledOnce();
+    await mounted.unmount();
+  });
+
+  it("emits a changed failure immediately and repeats after the burst window", async () => {
+    const now = vi.spyOn(Date, "now").mockReturnValue(1_000);
+    const writeProjectFile = vi
+      .fn<WriteProjectFile>()
+      .mockRejectedValueOnce(new Error("Load failed"))
+      .mockRejectedValueOnce(new Error("Failed to fetch"))
+      .mockRejectedValueOnce(new Error("Failed to fetch"));
+    const mounted = await mountEditorSave(writeProjectFile);
+
+    act(() => mounted.handle.handleContentChange("first candidate"));
+    await mounted.handle.flushPendingSave();
+    now.mockReturnValue(2_000);
+    act(() => mounted.handle.handleContentChange("second candidate"));
+    await mounted.handle.flushPendingSave();
+    now.mockReturnValue(8_000);
+    act(() => mounted.handle.handleContentChange("third candidate"));
+    await mounted.handle.flushPendingSave();
+
+    expect(trackStudioSaveFailure).toHaveBeenCalledTimes(3);
+    await mounted.unmount();
+  });
+
+  it("emits the same failure again after a successful save", async () => {
+    vi.spyOn(Date, "now").mockReturnValue(1_000);
+    const writeProjectFile = vi
+      .fn<WriteProjectFile>()
+      .mockRejectedValueOnce(new Error("Load failed"))
+      .mockResolvedValueOnce(undefined)
+      .mockRejectedValueOnce(new Error("Load failed"));
+    const mounted = await mountEditorSave(writeProjectFile);
+
+    act(() => mounted.handle.handleContentChange("first candidate"));
+    await mounted.handle.flushPendingSave();
+    act(() => mounted.handle.handleContentChange("successful candidate"));
+    await mounted.handle.flushPendingSave();
+    act(() => mounted.handle.handleContentChange("third candidate"));
+    await mounted.handle.flushPendingSave();
 
+    expect(trackStudioSaveFailure).toHaveBeenCalledTimes(2);
     await mounted.unmount();
   });
 

package/src/hooks/useEditorSave.ts

@@ -1,12 +1,15 @@
 import { useCallback, useRef } from "react";
 import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
 import type { EditHistoryKind } from "../utils/editHistory";
-import { trackStudioEvent } from "../utils/studioTelemetry";
 import {
   StudioFileConflictError,
+  buildStudioSaveFailureProperties,
+  trackStudioSaveFailure,
   type StudioSaveDrainResult,
 } from "../utils/studioSaveDiagnostics";
 
+const FAILURE_BURST_MS = 5_000;
+
 interface RecordEditInput {
   label: string;
   kind: EditHistoryKind;
@@ -58,19 +61,40 @@ export function useEditorSave({
   const refreshRafRef = useRef<number | null>(null);
   // One error toast per burst of failures — every keystroke retries the save,
   // and error toasts persist until dismissed, so don't stack duplicates.
-  const lastFailureToastAtRef = useRef(0);
+  const lastFailureToastAtRef = useRef<number | null>(null);
+  const lastFailureReportRef = useRef<{ fingerprint: string; emittedAt: number } | null>(null);
   const pendingCandidateRef = useRef<EditorSaveCandidate | null>(null);
   const inFlightRef = useRef<Promise<EditorSaveDrainResult> | null>(null);
   const inFlightCandidateRef = useRef<EditorSaveCandidate | null>(null);
 
   const reportFailure = useCallback(
     (path: string, error: unknown) => {
-      trackStudioEvent("save_failure", {
+      const now = Date.now();
+      const properties = buildStudioSaveFailureProperties({
         source: "code_editor",
-        error_message: error instanceof Error ? error.message : "unknown",
+        error,
+        filePath: path,
       });
-      const now = Date.now();
-      if (now - lastFailureToastAtRef.current > 5000) {
+      const errorName = error instanceof Error ? error.name : typeof error;
+      const fingerprint = JSON.stringify([
+        path,
+        errorName,
+        properties.error_message,
+        properties.status_code,
+      ]);
+      const previous = lastFailureReportRef.current;
+      if (
+        previous === null ||
+        previous.fingerprint !== fingerprint ||
+        now - previous.emittedAt >= FAILURE_BURST_MS
+      ) {
+        trackStudioSaveFailure({ source: "code_editor", error, filePath: path });
+        lastFailureReportRef.current = { fingerprint, emittedAt: now };
+      }
+      if (
+        lastFailureToastAtRef.current === null ||
+        now - lastFailureToastAtRef.current >= FAILURE_BURST_MS
+      ) {
         lastFailureToastAtRef.current = now;
         showToast(
           `Couldn't save ${path} — your latest edits are NOT persisted. Check the preview server; editing again retries the save.`,
@@ -95,6 +119,7 @@ export function useEditorSave({
       })
         .then<EditorSaveDrainResult>(() => {
           if (pendingCandidateRef.current === candidate) pendingCandidateRef.current = null;
+          lastFailureReportRef.current = null;
           if (refreshRafRef.current != null) cancelAnimationFrame(refreshRafRef.current);
           refreshRafRef.current = requestAnimationFrame(() => setRefreshKey((k) => k + 1));
           return { status: "clean" };

package/src/hooks/useGsapInteractionFailureTelemetry.test.tsx

@@ -1,32 +1,49 @@
 // @vitest-environment happy-dom
 
 import React, { act } from "react";
-import { describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { mountReactHarness } from "./domSelectionTestHarness";
 import { GsapEditBlockedError } from "./gsapEditOutcome";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
-const trackStudioSaveFailure = vi.hoisted(() => vi.fn());
-vi.mock("../utils/studioSaveDiagnostics", () => ({ trackStudioSaveFailure }));
+const { trackStudioEditBlocked, trackStudioSaveFailure } = vi.hoisted(() => ({
+  trackStudioEditBlocked: vi.fn(),
+  trackStudioSaveFailure: vi.fn(),
+}));
+vi.mock("../utils/studioSaveDiagnostics", () => ({
+  trackStudioEditBlocked,
+  trackStudioSaveFailure,
+}));
 
 import { useGsapInteractionFailureTelemetry } from "./useGsapInteractionFailureTelemetry";
 
+const selection = {
+  id: "clip",
+  selector: "#clip",
+  element: document.createElement("div"),
+} as unknown as DomEditSelection;
+
+function mountFailureTelemetry(showToast: ReturnType<typeof vi.fn>) {
+  let report!: ReturnType<typeof useGsapInteractionFailureTelemetry>;
+  function Harness() {
+    report = useGsapInteractionFailureTelemetry("index.html", showToast);
+    return null;
+  }
+  const root = mountReactHarness(<Harness />);
+  return { report, root };
+}
+
 describe("useGsapInteractionFailureTelemetry", () => {
-  it("surfaces the blocked reason instead of a generic save failure", () => {
+  beforeEach(() => {
+    trackStudioEditBlocked.mockClear();
+    trackStudioSaveFailure.mockClear();
+  });
+
+  it("tracks an expected edit block separately from save failures", () => {
     const showToast = vi.fn();
-    const selection = {
-      id: "clip",
-      selector: "#clip",
-      element: document.createElement("div"),
-    } as unknown as DomEditSelection;
-    let report!: ReturnType<typeof useGsapInteractionFailureTelemetry>;
-    function Harness() {
-      report = useGsapInteractionFailureTelemetry("index.html", showToast);
-      return null;
-    }
-    const root = mountReactHarness(<Harness />);
+    const { report, root } = mountFailureTelemetry(showToast);
 
     act(() => report(new GsapEditBlockedError("unroll-required"), selection, "drag", "Move"));
 
@@ -34,9 +51,24 @@ describe("useGsapInteractionFailureTelemetry", () => {
       "This motion comes from a helper or loop. Choose Unroll to edit it explicitly.",
       "error",
     );
-    expect(trackStudioSaveFailure).toHaveBeenCalledWith(
+    expect(trackStudioEditBlocked).toHaveBeenCalledWith(
       expect.objectContaining({ source: "gsap_commit", mutationType: "drag", targetId: "clip" }),
     );
+    expect(trackStudioSaveFailure).not.toHaveBeenCalled();
+    act(() => root.unmount());
+  });
+
+  it("keeps unexpected GSAP persistence errors in save_failure", () => {
+    const showToast = vi.fn();
+    const { report, root } = mountFailureTelemetry(showToast);
+    const error = new Error("network dropped");
+
+    act(() => report(error, selection, "drag", "Move"));
+
+    expect(trackStudioSaveFailure).toHaveBeenCalledWith(
+      expect.objectContaining({ source: "gsap_commit", error, mutationType: "drag" }),
+    );
+    expect(trackStudioEditBlocked).not.toHaveBeenCalled();
     act(() => root.unmount());
   });
 });

package/src/hooks/useGsapInteractionFailureTelemetry.ts

@@ -1,6 +1,6 @@
 import { useCallback } from "react";
 import type { DomEditSelection } from "../components/editor/domEditing";
-import { trackStudioSaveFailure } from "../utils/studioSaveDiagnostics";
+import { trackStudioEditBlocked, trackStudioSaveFailure } from "../utils/studioSaveDiagnostics";
 import { isGsapEditBlockedError } from "./gsapEditOutcome";
 
 export function useGsapInteractionFailureTelemetry(
@@ -9,7 +9,10 @@ export function useGsapInteractionFailureTelemetry(
 ) {
   return useCallback(
     (error: unknown, selection: DomEditSelection | null, mutationType: string, label: string) => {
-      trackStudioSaveFailure({
+      const report = isGsapEditBlockedError(error)
+        ? trackStudioEditBlocked
+        : trackStudioSaveFailure;
+      report({
         source: "gsap_commit",
         error,
         filePath: selection?.sourceFile ?? activeCompPath ?? "index.html",

package/src/utils/studioFileVersion.test.ts

@@ -1,12 +1,16 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   consumeStudioWriteToken,
+  createStudioWriteToken,
   markStudioWriteToken,
   resetStudioWriteTokens,
   studioExpectedFileVersion,
   studioFileContentVersion,
+  studioWriteHeaders,
 } from "./studioFileVersion";
 
+afterEach(() => vi.unstubAllGlobals());
+
 describe("studioFileContentVersion", () => {
   it("matches the strong SHA-256 ETag format used by studio-server", async () => {
     await expect(studioFileContentVersion("abc")).resolves.toBe(
@@ -42,6 +46,38 @@ describe("studioFileContentVersion", () => {
 });
 
 describe("studio write-token echo identity", () => {
+  it("prefers the platform randomUUID implementation", () => {
+    const randomUUID = vi.fn(() => "11111111-2222-4333-8444-555555555555");
+    vi.stubGlobal("crypto", { randomUUID });
+    resetStudioWriteTokens();
+
+    expect(studioWriteHeaders()).toEqual({
+      "X-Hyperframes-Write-Token": "11111111-2222-4333-8444-555555555555",
+    });
+    expect(randomUUID).toHaveBeenCalledOnce();
+    expect(consumeStudioWriteToken("11111111-2222-4333-8444-555555555555")).toBe(true);
+  });
+
+  it("creates an RFC 4122 UUID-v4 token from getRandomValues when randomUUID is unavailable", () => {
+    const source = Uint8Array.from({ length: 16 }, (_, index) => index);
+    vi.stubGlobal("crypto", {
+      getRandomValues: vi.fn((target: Uint8Array) => {
+        target.set(source);
+        return target;
+      }),
+    });
+
+    expect(createStudioWriteToken()).toBe("00010203-0405-4607-8809-0a0b0c0d0e0f");
+  });
+
+  it("fails explicitly when Web Crypto cannot provide secure random bytes", () => {
+    vi.stubGlobal("crypto", {});
+
+    expect(() => createStudioWriteToken()).toThrow(
+      "Web Crypto getRandomValues is required for Studio write identity",
+    );
+  });
+
   it("suppresses exactly one matching API write receipt without hiding path-only external writes", () => {
     resetStudioWriteTokens();
     markStudioWriteToken("studio-write-1");

package/src/utils/studioFileVersion.ts

@@ -48,8 +48,18 @@ export async function studioExpectedFileVersion(
   return versions.get(path);
 }
 
-function createStudioWriteToken(): string {
-  return globalThis.crypto.randomUUID();
+export function createStudioWriteToken(): string {
+  const webCrypto = globalThis.crypto;
+  if (typeof webCrypto?.randomUUID === "function") return webCrypto.randomUUID();
+  if (typeof webCrypto?.getRandomValues !== "function") {
+    throw new Error("Web Crypto getRandomValues is required for Studio write identity");
+  }
+
+  const bytes = webCrypto.getRandomValues(new Uint8Array(16));
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
 }
 
 /**