fix(studio): reject unsafe keyframe values

Author: miguel-heygen

packages/core/package.json

@@ -54,6 +54,10 @@
       "import": "./src/studio-api/helpers/draftMarkers.ts",
       "types": "./src/studio-api/helpers/draftMarkers.ts"
     },
+    "./studio-api/finite-mutation": {
+      "import": "./src/studio-api/helpers/finiteMutation.ts",
+      "types": "./src/studio-api/helpers/finiteMutation.ts"
+    },
     "./text": {
       "import": "./src/text/index.ts",
       "types": "./src/text/index.ts"
@@ -133,6 +137,10 @@
         "import": "./dist/studio-api/helpers/draftMarkers.js",
         "types": "./dist/studio-api/helpers/draftMarkers.d.ts"
       },
+      "./studio-api/finite-mutation": {
+        "import": "./dist/studio-api/helpers/finiteMutation.js",
+        "types": "./dist/studio-api/helpers/finiteMutation.d.ts"
+      },
       "./text": {
         "import": "./dist/text/index.js",
         "types": "./dist/text/index.d.ts"

packages/core/src/studio-api/helpers/finiteMutation.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import { findNonFiniteNumericFields, findUnsafeMutationValues } from "./finiteMutation";
+
+describe("finiteMutation", () => {
+  it("reports non-finite numbers before mutation serialization", () => {
+    expect(
+      findNonFiniteNumericFields({
+        type: "set-arc-path",
+        segments: [{ curviness: Number.NaN, cp1: { x: Infinity, y: 0 } }],
+      }).map((field) => field.path),
+    ).toEqual(["body.segments[0].curviness", "body.segments[0].cp1.x"]);
+  });
+
+  it("treats null as unsafe because JSON serializes NaN and Infinity to null", () => {
+    expect(
+      findUnsafeMutationValues({
+        type: "update-property",
+        property: "x",
+        value: null,
+      }),
+    ).toEqual([{ path: "body.value", reason: "null" }]);
+  });
+});

packages/core/src/studio-api/helpers/finiteMutation.ts

@@ -0,0 +1,36 @@
+export interface NonFiniteNumericField {
+  path: string;
+  value: number;
+}
+
+export interface UnsafeMutationValue {
+  path: string;
+  reason: "non-finite-number" | "null";
+}
+
+export function findNonFiniteNumericFields(value: unknown, path = "body"): NonFiniteNumericField[] {
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? [] : [{ path, value }];
+  }
+  if (!value || typeof value !== "object") return [];
+  if (Array.isArray(value)) {
+    return value.flatMap((item, index) => findNonFiniteNumericFields(item, `${path}[${index}]`));
+  }
+  return Object.entries(value).flatMap(([key, item]) =>
+    findNonFiniteNumericFields(item, `${path}.${key}`),
+  );
+}
+
+export function findUnsafeMutationValues(value: unknown, path = "body"): UnsafeMutationValue[] {
+  if (value === null) return [{ path, reason: "null" }];
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? [] : [{ path, reason: "non-finite-number" }];
+  }
+  if (!value || typeof value !== "object") return [];
+  if (Array.isArray(value)) {
+    return value.flatMap((item, index) => findUnsafeMutationValues(item, `${path}[${index}]`));
+  }
+  return Object.entries(value).flatMap(([key, item]) =>
+    findUnsafeMutationValues(item, `${path}.${key}`),
+  );
+}

packages/core/src/studio-api/routes/files.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, it } from "vitest";
 import { Hono } from "hono";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { registerFileRoutes } from "./files";
@@ -171,6 +171,32 @@ tl.fromTo("#box", { opacity: 0, x: -50 }, { opacity: 1, x: 0, duration: 1.5, eas
     expect(result.parsed.animations[0].fromProperties?.x).toBe(-50);
   });
 
+  it("rejects serialized non-finite mutation values before writing source", async () => {
+    const projectDir = createProjectDir();
+    writeHtml(projectDir, "comp.html", FROMTO_COMP);
+    const app = new Hono();
+    registerFileRoutes(app, createAdapter(projectDir));
+
+    const anim = await getFirstAnimation(app, "comp.html");
+    const before = readFileSync(join(projectDir, "comp.html"), "utf-8");
+    const res = await app.request("http://localhost/projects/demo/gsap-mutations/comp.html", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        type: "update-property",
+        animationId: anim.id,
+        property: "x",
+        value: Number.NaN,
+      }),
+    });
+    const payload = (await res.json()) as { error?: string; fields?: string[] };
+
+    expect(res.status).toBe(400);
+    expect(payload.error).toContain("unsafe numeric");
+    expect(payload.fields).toContain("body.value");
+    expect(readFileSync(join(projectDir, "comp.html"), "utf-8")).toBe(before);
+  });
+
   it("update-from-property returns 400 for a non-fromTo animation", async () => {
     const projectDir = createProjectDir();
     const TO_COMP = `<!DOCTYPE html><html><body><script data-hyperframes-gsap>

packages/core/src/studio-api/routes/files.ts

@@ -17,6 +17,7 @@ import { isAudioFile } from "../helpers/mime.js";
 import { generateWaveformCache } from "../helpers/waveform.js";
 import { validateUploadedMediaBuffer } from "../helpers/mediaValidation.js";
 import { isSafePath } from "../helpers/safePath.js";
+import { findUnsafeMutationValues } from "../helpers/finiteMutation.js";
 import type { GsapAnimation } from "../../parsers/gsapSerialize.js";
 import {
   removeElementFromHtml,
@@ -1077,6 +1078,16 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
     if (!body || !body.type) {
       return c.json({ error: "mutation type required" }, 400);
     }
+    const unsafeFields = findUnsafeMutationValues(body);
+    if (unsafeFields.length > 0) {
+      return c.json(
+        {
+          error: "mutation contains unsafe numeric values",
+          fields: unsafeFields.map((field) => field.path),
+        },
+        400,
+      );
+    }
 
     let html = readFileSync(res.absPath, "utf-8");
     let block = extractGsapScriptBlock(html);

packages/producer/tests/webm-transparency/output/output.webm

@@ -0,0 +1,77 @@
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+
+export const PROPERTY_DEFAULTS: Record<string, number> = {
+  opacity: 1,
+  x: 0,
+  y: 0,
+  scale: 1,
+  scaleX: 1,
+  scaleY: 1,
+  rotation: 0,
+  width: 100,
+  height: 100,
+};
+
+export function ensureElementAddressable(selection: DomEditSelection): {
+  selector: string;
+  autoId?: string;
+} {
+  if (selection.id) return { selector: `#${selection.id}` };
+  if (selection.selector) return { selector: selection.selector };
+
+  const el = selection.element;
+  const doc = el.ownerDocument;
+  const tag = el.tagName.toLowerCase();
+  let id = tag;
+  let n = 1;
+  while (doc.getElementById(id)) {
+    n += 1;
+    id = `${tag}-${n}`;
+  }
+  el.setAttribute("id", id);
+  return { selector: `#${id}`, autoId: id };
+}
+
+export class GsapMutationHttpError extends Error {
+  constructor(
+    readonly statusCode: number,
+    readonly responseBody: unknown,
+  ) {
+    super(formatGsapMutationHttpErrorMessage(statusCode, responseBody));
+    this.name = "GsapMutationHttpError";
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+export async function readJsonResponseBody(res: Response): Promise<unknown> {
+  const contentType = res.headers.get("content-type") ?? "";
+  if (!contentType.includes("application/json")) {
+    return await res.text().catch(() => null);
+  }
+  return await res.json().catch(() => null);
+}
+
+function formatGsapMutationHttpErrorMessage(statusCode: number, body: unknown): string {
+  if (isRecord(body) && typeof body.error === "string") {
+    return body.error;
+  }
+  return `GSAP mutation failed with status ${statusCode}`;
+}
+
+export function formatGsapMutationRejectionToast(error: GsapMutationHttpError): string {
+  const body = error.responseBody;
+  if (isRecord(body)) {
+    const fields = Array.isArray(body.fields)
+      ? body.fields.filter((field): field is string => typeof field === "string")
+      : [];
+    const suffix = fields.length > 0 ? ` (${fields.join(", ")})` : "";
+    return `Couldn't save animation: ${formatGsapMutationHttpErrorMessage(
+      error.statusCode,
+      body,
+    )}${suffix}`;
+  }
+  return `Couldn't save animation: ${error.message}`;
+}

packages/studio/src/hooks/gsapScriptCommitHelpers.ts

@@ -285,6 +285,7 @@ export function useDomEditSession({
     reloadPreview,
     onCacheInvalidate: bumpGsapCache,
     onFileContentChanged: updateEditingFileContent,
+    showToast,
   });
 
   // ── Commit handlers (delegated to useDomEditCommits) ──

packages/studio/src/hooks/useDomEditSession.ts

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef } from "react";
 import type { GsapAnimation, ParsedGsap } from "@hyperframes/core/gsap-parser";
+import { findNonFiniteNumericFields } from "@hyperframes/core/studio-api/finite-mutation";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import type { EditHistoryKind } from "../utils/editHistory";
 import { applySoftReload } from "../utils/gsapSoftReload";
@@ -11,43 +12,13 @@ import {
   readKeyframeSnapshot,
   writeKeyframeCache,
 } from "./gsapKeyframeCacheHelpers";
-
-const PROPERTY_DEFAULTS: Record<string, number> = {
-  opacity: 1,
-  x: 0,
-  y: 0,
-  scale: 1,
-  scaleX: 1,
-  scaleY: 1,
-  rotation: 0,
-  width: 100,
-  height: 100,
-};
-
-/**
- * Ensures the element has an id so it can be targeted by a GSAP selector.
- * If the element already has an id or a CSS selector, returns those.
- * Otherwise mints a unique id and sets it on the live element.
- */
-function ensureElementAddressable(selection: DomEditSelection): {
-  selector: string;
-  autoId?: string;
-} {
-  if (selection.id) return { selector: `#${selection.id}` };
-  if (selection.selector) return { selector: selection.selector };
-
-  const el = selection.element;
-  const doc = el.ownerDocument;
-  const tag = el.tagName.toLowerCase();
-  let id = tag;
-  let n = 1;
-  while (doc.getElementById(id)) {
-    n += 1;
-    id = `${tag}-${n}`;
-  }
-  el.setAttribute("id", id);
-  return { selector: `#${id}`, autoId: id };
-}
+import {
+  GsapMutationHttpError,
+  ensureElementAddressable,
+  formatGsapMutationRejectionToast,
+  PROPERTY_DEFAULTS,
+  readJsonResponseBody,
+} from "./gsapScriptCommitHelpers";
 
 interface MutationResult {
   ok: boolean;
@@ -62,21 +33,19 @@ async function mutateGsapScript(
   projectId: string,
   sourceFile: string,
   mutation: Record<string, unknown>,
-): Promise<MutationResult | null> {
-  try {
-    const res = await fetch(
-      `/api/projects/${encodeURIComponent(projectId)}/gsap-mutations/${encodeURIComponent(sourceFile)}`,
-      {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(mutation),
-      },
-    );
-    if (!res.ok) return null;
-    return (await res.json()) as MutationResult;
-  } catch {
-    return null;
+): Promise<MutationResult> {
+  const res = await fetch(
+    `/api/projects/${encodeURIComponent(projectId)}/gsap-mutations/${encodeURIComponent(sourceFile)}`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(mutation),
+    },
+  );
+  if (!res.ok) {
+    throw new GsapMutationHttpError(res.status, await readJsonResponseBody(res));
   }
+  return (await res.json()) as MutationResult;
 }
 interface GsapScriptCommitsParams {
   projectIdRef: React.MutableRefObject<string | null>;
@@ -94,6 +63,7 @@ interface GsapScriptCommitsParams {
   reloadPreview: () => void;
   onCacheInvalidate: () => void;
   onFileContentChanged?: (path: string, content: string) => void;
+  showToast?: (message: string, tone?: "error" | "info") => void;
 }
 const DEBOUNCE_MS = 150;
 
@@ -107,6 +77,7 @@ export function useGsapScriptCommits({
   reloadPreview,
   onCacheInvalidate,
   onFileContentChanged,
+  showToast,
 }: GsapScriptCommitsParams) {
   const pendingPropertyEditRef = useRef<{
     selection: DomEditSelection;
@@ -131,11 +102,27 @@ export function useGsapScriptCommits({
     ) => {
       const pid = projectIdRef.current;
       if (!pid) return;
+      const nonFiniteFields = findNonFiniteNumericFields(mutation);
+      if (nonFiniteFields.length > 0) {
+        showToast?.(
+          "Couldn't read element layout — try again at a different playhead time",
+          "error",
+        );
+        if (options.skipReload) return;
+        throw new Error(
+          `Mutation contains non-finite numeric values: ${nonFiniteFields.map((field) => field.path).join(", ")}`,
+        );
+      }
       const targetPath = selection.sourceFile || activeCompPath || "index.html";
-      const result = await mutateGsapScript(pid, targetPath, mutation);
-      if (!result) {
+      let result: MutationResult;
+      try {
+        result = await mutateGsapScript(pid, targetPath, mutation);
+      } catch (error) {
+        if (error instanceof GsapMutationHttpError) {
+          showToast?.(formatGsapMutationRejectionToast(error), "error");
+        }
         if (options.skipReload) return;
-        throw new Error(`Mutation failed: ${mutation.type}`);
+        throw error;
       }
 
       if (result.changed === false) {
@@ -195,6 +182,7 @@ export function useGsapScriptCommits({
       reloadPreview,
       onCacheInvalidate,
       onFileContentChanged,
+      showToast,
     ],
   );
   const flushPendingPropertyEdit = useCallback(() => {
@@ -488,7 +476,7 @@ export function useGsapScriptCommits({
       return commitMutation(
         selection,
         { type: "convert-to-keyframes", animationId, resolvedFromValues },
-        { label: "Convert to keyframes" },
+        { label: "Convert to keyframes", softReload: true },
       );
     },
     [commitMutation],