feat(studio): make agent edits live and explicit (#3581)

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

@@ -1,6 +1,23 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  closeSync,
+  fstatSync,
+  ftruncateSync,
+  futimesSync,
+  mkdtempSync,
+  openSync,
+  rmSync,
+  writeSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
 import { resolve } from "node:path";
-import { affectsProjectSignature } from "./projectSignature.js";
+import { affectsProjectSignature, createProjectSignature } from "./projectSignature.js";
+
+const temporaryProjects: string[] = [];
+
+afterEach(() => {
+  for (const project of temporaryProjects.splice(0)) rmSync(project, { recursive: true });
+});
 
 const PROJECT = resolve("/projects/demo");
 const affects = (relativePath: string) =>
@@ -42,3 +59,25 @@ describe("affectsProjectSignature", () => {
     expect(affectsProjectSignature(PROJECT, PROJECT)).toBe(false);
   });
 });
+
+describe("createProjectSignature", () => {
+  it("changes after same-size content is written with the original mtime restored", () => {
+    const project = mkdtempSync(resolve(tmpdir(), "hf-signature-"));
+    temporaryProjects.push(project);
+    const file = resolve(project, "index.html");
+    const descriptor = openSync(file, "w+");
+    try {
+      writeSync(descriptor, "first");
+      const originalMtime = fstatSync(descriptor).mtime;
+      const before = createProjectSignature(project);
+
+      ftruncateSync(descriptor, 0);
+      writeSync(descriptor, "other", 0, "utf8");
+      futimesSync(descriptor, originalMtime, originalMtime);
+
+      expect(createProjectSignature(project)).not.toBe(before);
+    } finally {
+      closeSync(descriptor);
+    }
+  });
+});

packages/studio-server/src/helpers/projectSignature.ts

@@ -70,6 +70,7 @@ export function affectsProjectSignature(projectDir: string, changedPath: string)
 interface ProjectSignatureFile {
   file: string;
   mtimeMs: number;
+  ctimeMs: number;
   size: number;
   textContentEligible: boolean;
 }
@@ -124,6 +125,7 @@ function collectProjectSignatureFiles(
       files.push({
         file,
         mtimeMs: stat.mtimeMs,
+        ctimeMs: stat.ctimeMs,
         size: stat.size,
         textContentEligible: isTextContentEligible(file, stat.size),
       });
@@ -149,6 +151,7 @@ function collectProjectSignatureManifestFiles(
     files.push({
       file,
       mtimeMs: stat.mtimeMs,
+      ctimeMs: stat.ctimeMs,
       size: stat.size,
       textContentEligible: isTextContentEligible(file, stat.size),
     });
@@ -165,6 +168,8 @@ function createProjectFingerprint(projectDir: string, files: ProjectSignatureFil
     hash.update("\0");
     hash.update(String(entry.mtimeMs));
     hash.update("\0");
+    hash.update(String(entry.ctimeMs));
+    hash.update("\0");
     hash.update(entry.textContentEligible ? "text" : "binary");
     hash.update("\0");
   }

packages/studio-server/src/routes/files.test.ts

@@ -437,11 +437,15 @@ describe("registerFileRoutes", () => {
     const payload = (await response.json()) as {
       changed?: boolean;
       path?: string;
+      version?: string;
       backupPath?: string;
     };
 
     expect(payload.changed).toBe(true);
     expect(payload.path).toBe("index.html");
+    expect(payload.version).toBe(
+      fileContentVersion(readFileSync(join(projectDir, "index.html"), "utf-8")),
+    );
     expect(payload.backupPath).toMatch(/^\.hyperframes\/backup\//);
     expect(readFileSync(join(projectDir, payload.backupPath!), "utf-8")).toBe(
       '<div id="title">Before</div>',
@@ -449,6 +453,43 @@ describe("registerFileRoutes", () => {
     expect(readFileSync(join(projectDir, "index.html"), "utf-8")).toContain("After");
   });
 
+  it("returns the current durable version for a matched no-op element patch", async () => {
+    const projectDir = createProjectDir();
+    const original = '<div id="title">Before</div>';
+    writeFileSync(join(projectDir, "index.html"), original);
+    const app = new Hono();
+    registerFileRoutes(app, createAdapter(projectDir));
+
+    const response = await app.request(
+      "http://localhost/projects/demo/file-mutations/patch-element/index.html",
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          target: { id: "title" },
+          operations: [{ type: "text-content", property: "textContent", value: "Before" }],
+        }),
+      },
+    );
+    const payload = (await response.json()) as {
+      changed?: boolean;
+      matched?: boolean;
+      path?: string;
+      version?: string;
+      backupPath?: string;
+    };
+
+    expect(response.status).toBe(200);
+    expect(payload).toMatchObject({
+      changed: false,
+      matched: true,
+      path: "index.html",
+      version: fileContentVersion(original),
+    });
+    expect(payload.backupPath).toBeUndefined();
+    expect(existsSync(join(projectDir, ".hyperframes", "backup"))).toBe(false);
+  });
+
   // Without the receipt the client cannot recognise its own edit in the watcher
   // broadcast, so it treats it as someone else's write and does a full preview
   // reload — a visible blank on the stage right after the user typed.
@@ -1292,6 +1333,30 @@ const tl = gsap.timeline({ paused: true });
     expect(res.status).toBe(400);
   });
 
+  it("rejects raw JavaScript expressions at the GSAP mutation boundary", async () => {
+    const projectDir = createProjectDir();
+    writeHtml(projectDir, "comp.html", FROMTO_COMP);
+    const app = new Hono();
+    registerFileRoutes(app, createAdapter(projectDir));
+    const animation = await getFirstAnimation(app, "comp.html");
+
+    const response = await app.request("http://localhost/projects/demo/gsap-mutations/comp.html", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        type: "update-meta",
+        animationId: animation.id,
+        updates: { ease: "__raw:(()=>alert(1))()" },
+      }),
+    });
+
+    expect(response.status).toBe(400);
+    expect(await response.json()).toEqual({
+      error: "raw JavaScript expressions are not accepted",
+    });
+    expect(readFileSync(join(projectDir, "comp.html"), "utf8")).toBe(FROMTO_COMP);
+  });
+
   it("update-from-property updates a fromTo start value in place", async () => {
     const projectDir = createProjectDir();
     writeHtml(projectDir, "comp.html", FROMTO_COMP);

packages/studio-server/src/routes/files.ts

@@ -1186,6 +1186,9 @@ function validateGsapMutationRequest(
   if (!body || typeof body !== "object" || !("type" in body) || !body.type) {
     return c.json({ error: "mutation type required" }, 400);
   }
+  if (containsRawGsapExpression(body)) {
+    return c.json({ error: "raw JavaScript expressions are not accepted" }, 400);
+  }
   const unsafeFields = findUnsafeMutationValues(body);
   if (unsafeFields.length > 0) return rejectUnsafeMutationValues(c, unsafeFields);
   if (
@@ -1197,6 +1200,13 @@ function validateGsapMutationRequest(
   return null;
 }
 
+function containsRawGsapExpression(value: unknown): boolean {
+  if (typeof value === "string") return value.startsWith("__raw:");
+  if (Array.isArray(value)) return value.some(containsRawGsapExpression);
+  if (!value || typeof value !== "object") return false;
+  return Object.values(value).some(containsRawGsapExpression);
+}
+
 async function prepareGsapMutationScript(
   c: RouteContext,
   res: ResolvedGsapFile,
@@ -2769,27 +2779,32 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
       parsed.body.operations,
     );
     if (patched === originalContent) {
+      const version = fileContentVersion(originalContent);
+      c.header("ETag", version);
       return c.json({
         ok: true,
         changed: false,
         matched,
         content: originalContent,
         path: ctx.filePath,
+        version,
       });
     }
-    const { backupPath } = writeMutationResult(
+    const { backupPath, version } = writeMutationResult(
       c,
       ctx.project.dir,
       ctx.filePath,
       ctx.absPath,
       patched,
     );
+    c.header("ETag", version);
     return c.json({
       ok: true,
       changed: true,
       matched,
       content: patched,
       path: ctx.filePath,
+      version,
       backupPath,
     });
   });

packages/studio-server/src/routes/thumbnail.test.ts

@@ -14,6 +14,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { pruneThumbnailCache, registerThumbnailRoutes } from "./thumbnail";
 import type { StudioApiAdapter } from "../types";
+import { createProjectSignature } from "../helpers/projectSignature.js";
 
 const tempProjectDirs: string[] = [];
 
@@ -320,6 +321,98 @@ describe("registerThumbnailRoutes", () => {
     expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
   });
 
+  it("regenerates a parent thumbnail when nested composition HTML changes", async () => {
+    const adapter = createAdapter();
+    const project = await adapter.resolveProject("demo");
+    if (!project) throw new Error("missing project");
+    const app = new Hono();
+    registerThumbnailRoutes(app, adapter);
+
+    writeFileSync(
+      join(project.dir, "index.html"),
+      `<div data-width="640" data-height="360" data-composition-src="compositions/nested.html"></div>`,
+    );
+    const compositionsDir = join(project.dir, "compositions");
+    mkdirSync(compositionsDir, { recursive: true });
+    const nestedPath = join(compositionsDir, "nested.html");
+    writeFileSync(nestedPath, `<div>before</div>`);
+    const url = "http://localhost/projects/demo/thumbnail/index.html?t=2&v=test";
+
+    await app.request(url);
+    writeFileSync(nestedPath, `<div>after with a different size</div>`);
+    await app.request(url);
+
+    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
+  });
+
+  it("regenerates a thumbnail when imported CSS changes", async () => {
+    const adapter = createAdapter();
+    const project = await adapter.resolveProject("demo");
+    if (!project) throw new Error("missing project");
+    const app = new Hono();
+    registerThumbnailRoutes(app, adapter);
+
+    writeFileSync(
+      join(project.dir, "index.html"),
+      `<link rel="stylesheet" href="./styles.css"><div data-width="640" data-height="360"></div>`,
+    );
+    const stylesPath = join(project.dir, "styles.css");
+    writeFileSync(stylesPath, `.card { color: red; }`);
+    const url = "http://localhost/projects/demo/thumbnail/index.html?t=2&v=test";
+
+    await app.request(url);
+    writeFileSync(stylesPath, `.card { color: rebeccapurple; }`);
+    await app.request(url);
+
+    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
+  });
+
+  it("uses the adapter-cached project signature for disk reuse and in-flight dedupe", async () => {
+    const adapter = createAdapter();
+    const project = await adapter.resolveProject("demo");
+    if (!project) throw new Error("missing project");
+    const getProjectSignature = vi.fn(() => createProjectSignature(project.dir));
+    adapter.getProjectSignature = getProjectSignature;
+    let resolve!: (buffer: Buffer) => void;
+    const generated = new Promise<Buffer>((done) => (resolve = done));
+    adapter.generateThumbnail = vi.fn(async () => generated);
+    const app = new Hono();
+    registerThumbnailRoutes(app, adapter);
+    const url = "http://localhost/projects/demo/thumbnail/index.html?t=3";
+
+    const first = app.request(url);
+    const duplicate = app.request(url);
+    await vi.waitFor(() => expect(adapter.generateThumbnail).toHaveBeenCalledTimes(1));
+    resolve(Buffer.from("shared"));
+    expect(await (await first).text()).toBe("shared");
+    expect(await (await duplicate).text()).toBe("shared");
+    expect(await (await app.request(url)).text()).toBe("shared");
+
+    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(1);
+    expect(getProjectSignature).toHaveBeenCalledTimes(4);
+    expect(getProjectSignature).toHaveBeenNthCalledWith(1, project.dir);
+  });
+
+  it("does not cache generated pixels under a signature that changed in flight", async () => {
+    const adapter = createAdapter();
+    const project = await adapter.resolveProject("demo");
+    if (!project) throw new Error("missing project");
+    const signatures = ["old", "new", "old", "old"];
+    adapter.getProjectSignature = vi.fn(() => signatures.shift() ?? "old");
+    adapter.generateThumbnail = vi
+      .fn()
+      .mockResolvedValueOnce(Buffer.from("rendered-after-change"))
+      .mockResolvedValueOnce(Buffer.from("rendered-old"));
+    const app = new Hono();
+    registerThumbnailRoutes(app, adapter);
+    const url = "http://localhost/projects/demo/thumbnail/index.html?t=3";
+
+    expect(await (await app.request(url)).text()).toBe("rendered-after-change");
+    expect(existsSync(join(project.dir, ".thumbnails"))).toBe(false);
+    expect(await (await app.request(url)).text()).toBe("rendered-old");
+    expect(adapter.generateThumbnail).toHaveBeenCalledTimes(2);
+  });
+
   it("keeps changed studio motion separated in the disk cache", async () => {
     const adapter = createAdapter();
     const project = await adapter.resolveProject("demo");

packages/studio-server/src/routes/thumbnail.ts

@@ -14,6 +14,7 @@ import { join } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import type { StudioApiAdapter } from "../types.js";
 import { STUDIO_MANUAL_EDITS_PATH } from "../helpers/manualEditsRenderScript.js";
+import { createProjectSignature, resolveProjectAndSignature } from "../helpers/projectSignature.js";
 import { STUDIO_MOTION_PATH } from "../helpers/studioMotionRenderScript.js";
 import { thumbnailGenerationCoordinator } from "./thumbnailGenerationCoordinator.js";
 
@@ -78,8 +79,9 @@ export function registerThumbnailRoutes(api: Hono, adapter: StudioApiAdapter): v
     if (!adapter.generateThumbnail) {
       return c.json({ error: "Thumbnails not available" }, 501);
     }
-    const project = await adapter.resolveProject(c.req.param("id"));
-    if (!project) return c.json({ error: "not found" }, 404);
+    const resolved = await resolveProjectAndSignature(adapter, c.req.param("id"));
+    if (!resolved) return c.json({ error: "not found" }, 404);
+    const { project, signature: projectSignature } = resolved;
 
     let compPath = decodeURIComponent(
       c.req.path.replace(`/projects/${project.id}/thumbnail/`, "").split("?")[0] ?? "",
@@ -162,6 +164,7 @@ export function registerThumbnailRoutes(api: Hono, adapter: StudioApiAdapter): v
     const urlVersionKey = urlVersion
       ? `_${urlVersion.replace(/[^a-zA-Z0-9_-]+/g, "_").slice(0, 32)}`
       : "";
+    const projectSignatureKey = `_${createHash("sha1").update(projectSignature).digest("hex").slice(0, 16)}`;
     const outputScale =
       outputMode === "source"
         ? 1
@@ -174,7 +177,7 @@ export function registerThumbnailRoutes(api: Hono, adapter: StudioApiAdapter): v
           : Math.min(1, THUMBNAIL_MAX_OUTPUT_WIDTH / compW, THUMBNAIL_MAX_OUTPUT_HEIGHT / compH);
     const outputWidth = Math.max(1, Math.round(compW * outputScale));
     const outputHeight = Math.max(1, Math.round(compH * outputScale));
-    const cacheKey = `${THUMBNAIL_CACHE_VERSION}${urlVersionKey}${manualEditsKey}${motionKey}${sourceKey}_${format}_${outputMode}_${compPath.replace(/\//g, "_")}_${compW}x${compH}_${outputWidth}x${outputHeight}_${sourceMtime}_${seekTime.toFixed(2)}${selectorKey}.${format === "png" ? "png" : "jpg"}`;
+    const cacheKey = `${THUMBNAIL_CACHE_VERSION}${urlVersionKey}${projectSignatureKey}${manualEditsKey}${motionKey}${sourceKey}_${format}_${outputMode}_${compPath.replace(/\//g, "_")}_${compW}x${compH}_${outputWidth}x${outputHeight}_${sourceMtime}_${seekTime.toFixed(2)}${selectorKey}.${format === "png" ? "png" : "jpg"}`;
     const cachePath = join(cacheDir, cacheKey);
     if (!prunedCacheDirs.has(cacheDir)) {
       prunedCacheDirs.add(cacheDir);
@@ -209,6 +212,19 @@ export function registerThumbnailRoutes(api: Hono, adapter: StudioApiAdapter): v
             signal,
           });
           if (!generated) return null;
+          const afterGeneration = await resolveProjectAndSignature(adapter, project.id);
+          const freshSignature = createProjectSignature(project.dir);
+          if (
+            !afterGeneration ||
+            afterGeneration.project.dir !== project.dir ||
+            afterGeneration.signature !== projectSignature ||
+            freshSignature !== projectSignature
+          ) {
+            // The browser may have rendered content written after this request
+            // captured its cache identity. Return the pixels to this caller,
+            // but never file them under a signature they do not prove.
+            return generated;
+          }
           if (!existsSync(cacheDir)) mkdirSync(cacheDir, { recursive: true });
           writeThumbnailAtomically(cachePath, generated);
           return generated;