@hyperframes/studio-server 0.7.57 → 0.7.59

package/dist/index.js

@@ -31,6 +31,153 @@ function walkDir(dir, prefix = "") {
   return files;
 }
 
+// src/helpers/projectSignature.ts
+import { createHash } from "crypto";
+import { lstatSync, readFileSync, readdirSync as readdirSync2 } from "fs";
+import { extname, isAbsolute, relative, resolve } from "path";
+var SIGNATURE_TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".cjs",
+  ".css",
+  ".html",
+  ".js",
+  ".json",
+  ".jsx",
+  ".mjs",
+  ".svg",
+  ".ts",
+  ".tsx"
+]);
+var SIGNATURE_EXCLUDED_DIRS = /* @__PURE__ */ new Set([
+  ".cache",
+  ".git",
+  ".hyperframes",
+  ".next",
+  ".vite",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "outputs",
+  "renders"
+]);
+var MAX_SIGNATURE_TEXT_BYTES = 2e6;
+var STUDIO_SIGNATURE_MANIFEST_PATHS = [
+  ".hyperframes/studio-manual-edits.json",
+  ".hyperframes/studio-motion.json"
+];
+var projectSignatureCache = /* @__PURE__ */ new Map();
+function isPathWithin(parentDir, childPath) {
+  const childRelativePath = relative(parentDir, childPath);
+  return childRelativePath === "" || !childRelativePath.startsWith("..") && !isAbsolute(childRelativePath);
+}
+function isTextContentEligible(file, size) {
+  return SIGNATURE_TEXT_EXTENSIONS.has(extname(file).toLowerCase()) && size <= MAX_SIGNATURE_TEXT_BYTES;
+}
+function collectProjectSignatureFiles(projectDir, dir, files) {
+  let entries;
+  try {
+    entries = readdirSync2(dir).sort();
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (SIGNATURE_EXCLUDED_DIRS.has(entry)) continue;
+    const file = resolve(dir, entry);
+    if (!isPathWithin(projectDir, file)) continue;
+    let stat;
+    try {
+      stat = lstatSync(file);
+    } catch {
+      continue;
+    }
+    if (stat.isSymbolicLink()) continue;
+    if (stat.isDirectory()) {
+      collectProjectSignatureFiles(projectDir, file, files);
+    } else if (stat.isFile()) {
+      files.push({
+        file,
+        mtimeMs: stat.mtimeMs,
+        size: stat.size,
+        textContentEligible: isTextContentEligible(file, stat.size)
+      });
+    }
+  }
+}
+function collectProjectSignatureManifestFiles(projectDir, files) {
+  const seen = new Set(files.map((entry) => entry.file));
+  for (const manifestPath of STUDIO_SIGNATURE_MANIFEST_PATHS) {
+    const file = resolve(projectDir, manifestPath);
+    if (seen.has(file) || !isPathWithin(projectDir, file)) continue;
+    let stat;
+    try {
+      stat = lstatSync(file);
+    } catch {
+      continue;
+    }
+    if (stat.isSymbolicLink() || !stat.isFile()) continue;
+    files.push({
+      file,
+      mtimeMs: stat.mtimeMs,
+      size: stat.size,
+      textContentEligible: isTextContentEligible(file, stat.size)
+    });
+    seen.add(file);
+  }
+}
+function createProjectFingerprint(projectDir, files) {
+  const hash = createHash("sha256");
+  for (const entry of files) {
+    hash.update(relative(projectDir, entry.file));
+    hash.update("\0");
+    hash.update(String(entry.size));
+    hash.update("\0");
+    hash.update(String(entry.mtimeMs));
+    hash.update("\0");
+    hash.update(entry.textContentEligible ? "text" : "binary");
+    hash.update("\0");
+  }
+  return hash.digest("hex").slice(0, 24);
+}
+function resolveProjectSignature(adapter, projectDir) {
+  return adapter.getProjectSignature?.(projectDir) ?? createProjectSignature(projectDir);
+}
+async function resolveProjectAndSignature(adapter, projectId) {
+  const project = await adapter.resolveProject(projectId);
+  if (!project) return null;
+  return { project, signature: resolveProjectSignature(adapter, project.dir) };
+}
+function createProjectSignature(projectDir) {
+  const normalizedProjectDir = resolve(projectDir);
+  const files = [];
+  collectProjectSignatureFiles(normalizedProjectDir, normalizedProjectDir, files);
+  collectProjectSignatureManifestFiles(normalizedProjectDir, files);
+  files.sort((a, b) => a.file.localeCompare(b.file));
+  const fingerprint = createProjectFingerprint(normalizedProjectDir, files);
+  const cached = projectSignatureCache.get(normalizedProjectDir);
+  if (cached?.fingerprint === fingerprint) return cached.signature;
+  const hash = createHash("sha256");
+  for (const entry of files) {
+    const relativePath = relative(normalizedProjectDir, entry.file);
+    hash.update(relativePath);
+    hash.update("\0");
+    hash.update(String(entry.size));
+    hash.update("\0");
+    if (entry.textContentEligible) {
+      try {
+        hash.update(readFileSync(entry.file));
+      } catch {
+        hash.update(String(entry.mtimeMs));
+      }
+    } else {
+      hash.update(String(entry.mtimeMs));
+    }
+    hash.update("\0");
+  }
+  const signature = hash.digest("hex").slice(0, 24);
+  projectSignatureCache.set(normalizedProjectDir, { fingerprint, signature });
+  return signature;
+}
+
 // src/routes/projects.ts
 var COMPOSITION_ID_RE = /data-composition-id\s*=/;
 async function filterCompositionFiles(projectDir, files) {
@@ -61,6 +208,11 @@ function registerProjectRoutes(api, adapter) {
     if (!result) return c.json({ error: "Session not found" }, 404);
     return c.json(result);
   });
+  api.get("/projects/:id/signature", async (c) => {
+    const project = await adapter.resolveProject(c.req.param("id"));
+    if (!project) return c.json({ error: "not found" }, 404);
+    return c.json({ signature: resolveProjectSignature(adapter, project.dir) });
+  });
   api.get("/projects/:id", async (c) => {
     const project = await adapter.resolveProject(c.req.param("id"));
     if (!project) return c.json({ error: "not found" }, 404);
@@ -71,7 +223,7 @@ function registerProjectRoutes(api, adapter) {
 }
 
 // src/routes/storyboard.ts
-import { existsSync, readFileSync } from "fs";
+import { existsSync, readFileSync as readFileSync2 } from "fs";
 import {
   parseStoryboard,
   SCRIPT_FILENAME,
@@ -91,7 +243,7 @@ function readScript(projectDir) {
   const abs = resolveWithinProject(projectDir, SCRIPT_FILENAME);
   if (abs && existsSync(abs)) {
     try {
-      return { exists: true, path: SCRIPT_FILENAME, content: readFileSync(abs, "utf-8") };
+      return { exists: true, path: SCRIPT_FILENAME, content: readFileSync2(abs, "utf-8") };
     } catch {
     }
   }
@@ -99,8 +251,9 @@ function readScript(projectDir) {
 }
 function registerStoryboardRoutes(api, adapter) {
   api.get("/projects/:id/storyboard", async (c) => {
-    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 } = resolved;
     const abs = resolveWithinProject(project.dir, STORYBOARD_FILENAME);
     if (!abs || !existsSync(abs)) {
       return c.json({
@@ -109,12 +262,13 @@ function registerStoryboardRoutes(api, adapter) {
         globals: { extra: {} },
         frames: [],
         warnings: [],
-        script: readScript(project.dir)
+        script: readScript(project.dir),
+        signature
       });
     }
     let source;
     try {
-      source = readFileSync(abs, "utf-8");
+      source = readFileSync2(abs, "utf-8");
     } catch {
       return c.json({ error: "failed to read storyboard" }, 500);
     }
@@ -125,7 +279,8 @@ function registerStoryboardRoutes(api, adapter) {
       globals: manifest.globals,
       frames: resolveFrames(project.dir, manifest.frames),
       warnings: manifest.warnings,
-      script: readScript(project.dir)
+      script: readScript(project.dir),
+      signature
     });
   });
 }
@@ -134,16 +289,16 @@ function registerStoryboardRoutes(api, adapter) {
 import { bodyLimit } from "hono/body-limit";
 import {
   existsSync as existsSync3,
-  readFileSync as readFileSync3,
+  readFileSync as readFileSync4,
   writeFileSync as writeFileSync4,
   mkdirSync as mkdirSync3,
   unlinkSync as unlinkSync2,
   rmSync as rmSync2,
   statSync,
   renameSync,
-  readdirSync as readdirSync3
+  readdirSync as readdirSync4
 } from "fs";
-import { resolve as resolve2, dirname, join as join6 } from "path";
+import { resolve as resolve3, dirname, join as join6 } from "path";
 
 // src/helpers/mime.ts
 var MIME_TYPES = {
@@ -188,7 +343,7 @@ function isAudioFile(name) {
 // src/helpers/waveform.ts
 import { spawn } from "child_process";
 import { existsSync as existsSync2, writeFileSync, mkdirSync } from "fs";
-import { join as join3, resolve } from "path";
+import { join as join3, resolve as resolve2 } from "path";
 var SAMPLE_RATE = 4e3;
 var PEAK_COUNT = 4e3;
 var WAVEFORM_CACHE_VERSION = "v2";
@@ -213,7 +368,7 @@ function computePeaks(floats, count) {
 }
 function ffmpegBinary() {
   const configured = process.env.HYPERFRAMES_FFMPEG_PATH?.trim();
-  if (configured) return resolve(configured);
+  if (configured) return resolve2(configured);
   return "ffmpeg";
 }
 function decodeAudioPeaks(audioPath) {
@@ -322,9 +477,9 @@ function validateUploadedMediaBuffer(fileName, buffer, runner = spawnSync) {
 }
 
 // src/helpers/backupJournal.ts
-import { mkdirSync as mkdirSync2, readdirSync as readdirSync2, readFileSync as readFileSync2, unlinkSync, writeFileSync as writeFileSync3 } from "fs";
+import { mkdirSync as mkdirSync2, readdirSync as readdirSync3, readFileSync as readFileSync3, unlinkSync, writeFileSync as writeFileSync3 } from "fs";
 import { Buffer as Buffer2 } from "buffer";
-import { join as join5, relative } from "path";
+import { join as join5, relative as relative2 } from "path";
 var DEFAULT_KEEP_PER_FILE = 10;
 function backupKeyForPath(path) {
   return Buffer2.from(path, "utf-8").toString("base64url");
@@ -334,15 +489,15 @@ function timestampPrefix() {
 }
 function backupPathForResponse(projectDir, backupPath) {
   if (!backupPath) return null;
-  const rel = relative(projectDir, backupPath);
+  const rel = relative2(projectDir, backupPath);
   if (!rel || rel.startsWith("..")) return null;
   return rel.split("\\").join("/");
 }
 function snapshotBeforeWrite(projectDir, absPath, options = {}) {
   if (!isSafePath(projectDir, absPath)) return { backupPath: null };
   try {
-    const content = readFileSync2(absPath);
-    const relativePath = relative(projectDir, absPath);
+    const content = readFileSync3(absPath);
+    const relativePath = relative2(projectDir, absPath);
     const backupDir = join5(projectDir, ".hyperframes", "backup");
     mkdirSync2(backupDir, { recursive: true });
     const backupKey = backupKeyForPath(relativePath);
@@ -363,7 +518,7 @@ function nextBackupPath(backupDir, backupKey) {
   let counter = 2;
   while (true) {
     try {
-      readFileSync2(candidate);
+      readFileSync3(candidate);
     } catch (error) {
       if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
         return candidate;
@@ -378,7 +533,7 @@ function pruneBackups(backupDir, backupKey, keepPerFile) {
   const keep = Math.max(1, Math.floor(keepPerFile));
   const suffix = `-${backupKey}`;
   const numberedSuffix = new RegExp(`-${backupKey}-\\d+$`);
-  const matches = readdirSync2(backupDir).filter((name) => name.endsWith(suffix) || numberedSuffix.test(name)).map((name) => join5(backupDir, name)).sort((a, b) => {
+  const matches = readdirSync3(backupDir).filter((name) => name.endsWith(suffix) || numberedSuffix.test(name)).map((name) => join5(backupDir, name)).sort((a, b) => {
     return b.localeCompare(a);
   });
   for (const file of matches.slice(keep)) {
@@ -896,6 +1051,21 @@ function resolveProjectFile(c, adapter, opts) {
 function resolveFileMutationContext(c, adapter, operation) {
   return resolveProjectPath(c, adapter, (id) => `/projects/${id}/file-mutations/${operation}/`);
 }
+function isElementPatchRequest(value) {
+  if (typeof value !== "object" || value === null) return false;
+  if (!("target" in value) || typeof value.target !== "object" || value.target === null) {
+    return false;
+  }
+  return "operations" in value && Array.isArray(value.operations) && value.operations.length > 0;
+}
+function isElementPatchBatchRequest(value) {
+  return typeof value === "object" && value !== null && "sourceFile" in value && typeof value.sourceFile === "string" && value.sourceFile.length > 0 && "patches" in value && Array.isArray(value.patches) && value.patches.length > 0 && value.patches.every(isElementPatchRequest);
+}
+function findUnsafeElementPatchBatchValues(batches) {
+  return batches.flatMap(
+    (batch) => batch.patches.flatMap((patch) => findUnsafeDomPatchValues(patch))
+  );
+}
 function foldElementPatches(originalContent, patches) {
   let content = originalContent;
   const matched = [];
@@ -906,6 +1076,90 @@ function foldElementPatches(originalContent, patches) {
   }
   return { content, matched };
 }
+function commitElementPatchBatches(projectDir, batches, writeFile = writeFileSync4) {
+  const resolvedPaths = /* @__PURE__ */ new Set();
+  const prepared = [];
+  for (const batch of batches) {
+    const absPath = resolveWithinProject(projectDir, batch.sourceFile);
+    if (!absPath) return { error: "forbidden", sourceFile: batch.sourceFile };
+    if (resolvedPaths.has(absPath)) return { error: "duplicate", sourceFile: batch.sourceFile };
+    resolvedPaths.add(absPath);
+    let before;
+    try {
+      before = readFileSync4(absPath, "utf-8");
+    } catch {
+      return { error: "not-found", sourceFile: batch.sourceFile };
+    }
+    const folded = foldElementPatches(before, batch.patches);
+    prepared.push({
+      sourceFile: batch.sourceFile,
+      absPath,
+      before,
+      matched: folded.matched,
+      after: folded.content
+    });
+  }
+  const durable = prepared.every((file) => file.matched.every(Boolean));
+  if (!durable) {
+    return {
+      durable: false,
+      files: prepared.map((file) => ({
+        sourceFile: file.sourceFile,
+        changed: false,
+        matched: file.matched,
+        before: file.before,
+        after: file.before
+      }))
+    };
+  }
+  const files = [];
+  const attemptedWrites = [];
+  try {
+    for (const file of prepared) {
+      if (file.after === file.before) {
+        files.push({
+          sourceFile: file.sourceFile,
+          changed: false,
+          matched: file.matched,
+          before: file.before,
+          after: file.before
+        });
+        continue;
+      }
+      const backup = snapshotBeforeWrite(projectDir, file.absPath);
+      if (backup.error) {
+        throw new Error(`Failed to create backup for ${file.sourceFile}: ${backup.error}`);
+      }
+      attemptedWrites.push(file);
+      writeFile(file.absPath, file.after, "utf-8");
+      files.push({
+        sourceFile: file.sourceFile,
+        changed: true,
+        matched: file.matched,
+        before: file.before,
+        after: file.after,
+        backupPath: backupPathForResponse(projectDir, backup.backupPath)
+      });
+    }
+  } catch (error) {
+    const rollbackErrors = [];
+    for (const file of attemptedWrites.reverse()) {
+      try {
+        writeFile(file.absPath, file.before, "utf-8");
+      } catch (rollbackError) {
+        rollbackErrors.push(rollbackError);
+      }
+    }
+    if (rollbackErrors.length > 0) {
+      throw new AggregateError(
+        [error, ...rollbackErrors],
+        "Element patch batch failed and rollback did not complete"
+      );
+    }
+    throw error;
+  }
+  return { durable: true, files };
+}
 function writeIfChanged(c, projectDir, filePath, absPath, original, next) {
   if (next === original) {
     return c.json({ ok: true, changed: false, content: original, path: filePath });
@@ -931,6 +1185,11 @@ function rejectUnsafeMutationValues(c, unsafeFields) {
     400
   );
 }
+function elementPatchBatchCommitErrorResponse(c, error, sourceFile) {
+  if (error === "not-found") return c.json({ error, sourceFile }, 404);
+  if (error === "forbidden") return c.json({ error, sourceFile }, 403);
+  return c.json({ error: "duplicate source file", sourceFile }, 400);
+}
 async function parseMutationBody(c) {
   const body = await c.req.json().catch(() => null);
   if (!body?.target) {
@@ -949,7 +1208,7 @@ function generateCopyPath(projectDir, originalPath) {
   const cleanBase = copyMatch ? base.slice(0, -copyMatch[0].length) : base;
   let num = copyMatch ? copyMatch[1] ? parseInt(copyMatch[1]) + 1 : 2 : 1;
   let candidate = num === 1 ? `${cleanBase} (copy)${ext}` : `${cleanBase} (copy ${num})${ext}`;
-  while (existsSync3(resolve2(projectDir, candidate))) {
+  while (existsSync3(resolve3(projectDir, candidate))) {
     num++;
     candidate = `${cleanBase} (copy ${num})${ext}`;
   }
@@ -957,7 +1216,7 @@ function generateCopyPath(projectDir, originalPath) {
 }
 function walkFiles(dir, filter) {
   const results = [];
-  for (const entry of readdirSync3(dir, { withFileTypes: true })) {
+  for (const entry of readdirSync4(dir, { withFileTypes: true })) {
     const full = join6(dir, entry.name);
     if (entry.isDirectory()) {
       if (entry.name === "node_modules" || entry.name === ".thumbnails" || entry.name === "renders")
@@ -976,7 +1235,7 @@ function updateReferences(projectDir, oldPath, newPath) {
   );
   let updatedCount = 0;
   for (const file of textFiles) {
-    const content = readFileSync3(file, "utf-8");
+    const content = readFileSync4(file, "utf-8");
     if (!content.includes(oldPath)) continue;
     const updated = content.split(oldPath).join(newPath);
     if (updated !== content) {
@@ -1233,7 +1492,8 @@ function validateGsapMutationRequest(c, body) {
   return null;
 }
 async function prepareGsapMutationScript(c, res, firstMutation) {
-  let html = readFileSync3(res.absPath, "utf-8");
+  const beforeHtml = readFileSync4(res.absPath, "utf-8");
+  let html = beforeHtml;
   let block = extractGsapScriptBlock(html);
   if (!block && (firstMutation.type === "add" || firstMutation.type === "add-with-keyframes")) {
     const compId = html.match(/data-composition-id="([^"]+)"/)?.[1] ?? "main";
@@ -1265,14 +1525,14 @@ ${bootstrap}`;
     });
   }
   if (!block) return c.json({ error: "no GSAP script found in file" }, 400);
-  return { html, block };
+  return { html, beforeHtml, block };
 }
 async function applyGsapMutations(c, res, mutations) {
   const firstMutation = mutations[0];
   if (!firstMutation) return c.json({ error: "mutations array required" }, 400);
   const prepared = await prepareGsapMutationScript(c, res, firstMutation);
   if (prepared instanceof Response) return prepared;
-  const { html, block } = prepared;
+  const { html, beforeHtml, block } = prepared;
   const initialScript = block.scriptText;
   const skippedSelectors = /* @__PURE__ */ new Set();
   const respond = (data, status) => status ? c.json(data, status) : c.json(data);
@@ -1292,6 +1552,9 @@ async function applyGsapMutations(c, res, mutations) {
   const changed = block.scriptText !== initialScript;
   const newHtml = changed ? block.replaceScript(block.scriptText) : html;
   let backupPath = null;
+  if (readFileSync4(res.absPath, "utf-8") !== beforeHtml) {
+    return c.json({ error: "file changed during GSAP mutation", conflict: true }, 409);
+  }
   if (changed) {
     const backup = snapshotBeforeWrite(res.project.dir, res.absPath);
     if (backup.error) console.warn(`Failed to create backup for ${res.filePath}: ${backup.error}`);
@@ -1303,7 +1566,7 @@ async function applyGsapMutations(c, res, mutations) {
     changed,
     mutated: changed,
     parsed: parseGsapScriptAcorn(block.scriptText),
-    before: html,
+    before: beforeHtml,
     after: newHtml,
     scriptText: block.scriptText,
     path: res.filePath,
@@ -1925,7 +2188,7 @@ async function processUploadedFiles(formData, targetDir, projectDir) {
       skipped.push(name);
       continue;
     }
-    const destPath = resolve2(targetDir, name);
+    const destPath = resolve3(targetDir, name);
     if (!isSafePath(projectDir, destPath)) continue;
     let finalPath = destPath;
     let finalName = name;
@@ -1935,13 +2198,13 @@ async function processUploadedFiles(formData, targetDir, projectDir) {
       const base = dotIdx > 0 ? name.slice(0, dotIdx) : name;
       let n = 2;
       const MAX_COPY_INDEX = 1e4;
-      while (n < MAX_COPY_INDEX && existsSync3(resolve2(targetDir, `${base} (${n})${ext}`))) n++;
+      while (n < MAX_COPY_INDEX && existsSync3(resolve3(targetDir, `${base} (${n})${ext}`))) n++;
       if (n >= MAX_COPY_INDEX) {
         skipped.push(name);
         continue;
       }
       finalName = `${base} (${n})${ext}`;
-      finalPath = resolve2(targetDir, finalName);
+      finalPath = resolve3(targetDir, finalName);
     }
     const buffer = Buffer.from(await value.arrayBuffer());
     const validation = validateUploadedMediaBuffer(finalName, buffer);
@@ -1969,7 +2232,7 @@ function registerFileRoutes(api, adapter) {
       }
       return c.json({ error: "not found" }, 404);
     }
-    const content = readFileSync3(res.absPath, "utf-8");
+    const content = readFileSync4(res.absPath, "utf-8");
     return c.json({ filename: res.filePath, content });
   });
   api.put("/projects/:id/files/*", async (c) => {
@@ -2021,7 +2284,7 @@ function registerFileRoutes(api, adapter) {
     }
     const parsed = await parseMutationBody(c);
     if ("error" in parsed) return parsed.error;
-    const originalContent = readFileSync3(ctx.absPath, "utf-8");
+    const originalContent = readFileSync4(ctx.absPath, "utf-8");
     return writeIfChanged(
       c,
       ctx.project.dir,
@@ -2042,7 +2305,7 @@ function registerFileRoutes(api, adapter) {
     const fallbackTiming = typeof parsed.body.elementStart === "number" && typeof parsed.body.elementDuration === "number" ? { start: parsed.body.elementStart, duration: parsed.body.elementDuration } : void 0;
     let originalContent;
     try {
-      originalContent = readFileSync3(ctx.absPath, "utf-8");
+      originalContent = readFileSync4(ctx.absPath, "utf-8");
     } catch {
       return c.json({ error: "not found" }, 404);
     }
@@ -2082,7 +2345,7 @@ function registerFileRoutes(api, adapter) {
     }
     let originalContent;
     try {
-      originalContent = readFileSync3(ctx.absPath, "utf-8");
+      originalContent = readFileSync4(ctx.absPath, "utf-8");
     } catch {
       return c.json({ error: "not found" }, 404);
     }
@@ -2112,45 +2375,46 @@ function registerFileRoutes(api, adapter) {
       backupPath: backupPathForResponse(ctx.project.dir, backup.backupPath)
     });
   });
+  api.post("/projects/:id/file-mutations/patch-element-batches", async (c) => {
+    const project = await adapter.resolveProject(c.req.param("id"));
+    if (!project) return c.json({ error: "not found" }, 404);
+    const body = await c.req.json().catch(() => null);
+    if (typeof body !== "object" || body === null || !("batches" in body) || !Array.isArray(body.batches) || body.batches.length === 0 || !body.batches.every(isElementPatchBatchRequest)) {
+      return c.json({ error: "batches with sourceFile and patches required" }, 400);
+    }
+    const unsafeFields = findUnsafeElementPatchBatchValues(body.batches);
+    if (unsafeFields.length > 0) return rejectUnsafeMutationValues(c, unsafeFields);
+    const result = commitElementPatchBatches(project.dir, body.batches);
+    if ("error" in result) {
+      return elementPatchBatchCommitErrorResponse(c, result.error, result.sourceFile);
+    }
+    return c.json(result);
+  });
   api.post("/projects/:id/file-mutations/patch-elements-batch/*", async (c) => {
     const ctx = await resolveFileMutationContext(c, adapter, "patch-elements-batch");
     if ("error" in ctx) return ctx.error;
     const body = await c.req.json().catch(() => null);
-    if (!body || !Array.isArray(body.patches) || body.patches.length === 0 || body.patches.some(
-      (patch) => !patch?.target || !Array.isArray(patch.operations) || patch.operations.length === 0
-    )) {
+    if (!body || !Array.isArray(body.patches) || body.patches.length === 0 || !body.patches.every(isElementPatchRequest)) {
       return c.json({ error: "patches with target and operations required" }, 400);
     }
-    const unsafeFields = body.patches.flatMap((patch) => findUnsafeDomPatchValues(patch));
+    const batch = { sourceFile: ctx.filePath, patches: body.patches };
+    const unsafeFields = findUnsafeElementPatchBatchValues([batch]);
     if (unsafeFields.length > 0) {
       return rejectUnsafeMutationValues(c, unsafeFields);
     }
-    let originalContent;
-    try {
-      originalContent = readFileSync3(ctx.absPath, "utf-8");
-    } catch {
-      return c.json({ error: "not found" }, 404);
-    }
-    const result = foldElementPatches(originalContent, body.patches);
-    if (result.content === originalContent) {
-      return c.json({
-        ok: true,
-        changed: false,
-        matched: result.matched,
-        content: originalContent,
-        path: ctx.filePath
-      });
+    const result = commitElementPatchBatches(ctx.project.dir, [batch]);
+    if ("error" in result) {
+      return elementPatchBatchCommitErrorResponse(c, result.error, result.sourceFile);
     }
-    const backup = snapshotBeforeWrite(ctx.project.dir, ctx.absPath);
-    if (backup.error) console.warn(`Failed to create backup for ${ctx.filePath}: ${backup.error}`);
-    writeFileSync4(ctx.absPath, result.content, "utf-8");
+    const file = result.files[0];
+    if (!file) return c.json({ error: "empty element patch result" }, 500);
     return c.json({
       ok: true,
-      changed: true,
-      matched: result.matched,
-      content: result.content,
-      path: ctx.filePath,
-      backupPath: backupPathForResponse(ctx.project.dir, backup.backupPath)
+      changed: file.changed,
+      matched: file.matched,
+      content: file.after,
+      path: file.sourceFile,
+      backupPath: file.backupPath
     });
   });
   api.post("/projects/:id/file-mutations/wrap-elements/*", async (c) => {
@@ -2171,7 +2435,7 @@ function registerFileRoutes(api, adapter) {
     }
     let originalContent;
     try {
-      originalContent = readFileSync3(ctx.absPath, "utf-8");
+      originalContent = readFileSync4(ctx.absPath, "utf-8");
     } catch {
       return c.json({ error: "not found" }, 404);
     }
@@ -2213,7 +2477,7 @@ function registerFileRoutes(api, adapter) {
     if ("error" in parsed) return parsed.error;
     let originalContent;
     try {
-      originalContent = readFileSync3(ctx.absPath, "utf-8");
+      originalContent = readFileSync4(ctx.absPath, "utf-8");
     } catch {
       return c.json({ error: "not found" }, 404);
     }
@@ -2242,7 +2506,7 @@ function registerFileRoutes(api, adapter) {
     if ("error" in parsed) return parsed.error;
     let content;
     try {
-      content = readFileSync3(ctx.absPath, "utf-8");
+      content = readFileSync4(ctx.absPath, "utf-8");
     } catch {
       return c.json({ exists: false });
     }
@@ -2285,7 +2549,7 @@ function registerFileRoutes(api, adapter) {
       return c.json({ error: "forbidden" }, 403);
     }
     ensureDir(destAbs);
-    writeFileSync4(destAbs, readFileSync3(srcAbs));
+    writeFileSync4(destAbs, readFileSync4(srcAbs));
     return c.json({ ok: true, path: copyPath }, 201);
   });
   const MAX_UPLOAD_BYTES = 500 * 1024 * 1024;
@@ -2315,7 +2579,7 @@ function registerFileRoutes(api, adapter) {
       mustExist: true
     });
     if ("error" in res) return res.error;
-    const html = readFileSync3(res.absPath, "utf-8");
+    const html = readFileSync4(res.absPath, "utf-8");
     const block = extractGsapScriptBlock(html);
     if (!block) {
       return c.json({
@@ -2328,6 +2592,11 @@ function registerFileRoutes(api, adapter) {
     const parsed = parseGsapScriptAcorn(block.scriptText);
     return c.json(parsed);
   });
+  api.get("/projects/:id/gsap-mutation-capabilities", async (c) => {
+    const project = await adapter.resolveProject(c.req.param("id"));
+    if (!project) return c.json({ error: "not found" }, 404);
+    return c.json({ atomicOwnershipPairs: true });
+  });
   api.post("/projects/:id/gsap-mutations/*", async (c) => {
     const res = await resolveProjectPath(c, adapter, (id) => `/projects/${id}/gsap-mutations/`, {
       mustExist: true
@@ -2357,6 +2626,25 @@ function registerFileRoutes(api, adapter) {
     }
     return applyGsapMutations(c, res, body.mutations);
   });
+  api.post("/projects/:id/gsap-mutation-rollback/*", async (c) => {
+    const res = await resolveProjectPath(
+      c,
+      adapter,
+      (id) => `/projects/${id}/gsap-mutation-rollback/`,
+      { mustExist: true }
+    );
+    if ("error" in res) return res.error;
+    const body = await c.req.json().catch(() => null);
+    if (!body || typeof body.expected !== "string" || typeof body.restore !== "string") {
+      return c.json({ error: "expected and restore contents required" }, 400);
+    }
+    const current = readFileSync4(res.absPath, "utf-8");
+    if (current !== body.expected) {
+      return c.json({ ok: true, restored: false, conflict: true });
+    }
+    writeFileSync4(res.absPath, body.restore, "utf-8");
+    return c.json({ ok: true, restored: true, conflict: false });
+  });
 }
 
 // src/routes/preview.ts
@@ -2366,7 +2654,7 @@ import { createHash as createHash2 } from "crypto";
 import { injectScriptsIntoHtml, stripEmbeddedRuntimeScripts as stripEmbeddedRuntimeScripts2 } from "@hyperframes/core/compiler";
 
 // src/helpers/subComposition.ts
-import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync5 } from "fs";
 import { join as join7 } from "path";
 import { parseHTML as parseHTML3 } from "linkedom";
 import {
@@ -2475,7 +2763,7 @@ function tagRootCompositionFile(bodyHtml, compPath) {
 function buildSubCompositionHtml(projectDir, compPath, runtimeUrl, baseHref, rawOverride) {
   const compFile = join7(projectDir, compPath);
   if (!existsSync4(compFile)) return null;
-  const rawComp = rawOverride ?? readFileSync4(compFile, "utf-8");
+  const rawComp = rawOverride ?? readFileSync5(compFile, "utf-8");
   let compHeadContent = "";
   let rewrittenContent;
   let htmlAttrs = "";
@@ -2508,7 +2796,7 @@ function buildSubCompositionHtml(projectDir, compPath, runtimeUrl, baseHref, raw
   const indexPath = join7(projectDir, "index.html");
   let headContent = "";
   if (existsSync4(indexPath)) {
-    const indexHtml = readFileSync4(indexPath, "utf-8");
+    const indexHtml = readFileSync5(indexPath, "utf-8");
     const headMatch = indexHtml.match(/<head[^>]*>([\s\S]*?)<\/head>/i);
     headContent = headMatch?.[1] ?? "";
   }
@@ -2541,145 +2829,6 @@ ${rewrittenContent}
 </html>`;
 }
 
-// src/helpers/projectSignature.ts
-import { createHash } from "crypto";
-import { lstatSync, readFileSync as readFileSync5, readdirSync as readdirSync4 } from "fs";
-import { extname, isAbsolute, relative as relative2, resolve as resolve3 } from "path";
-var SIGNATURE_TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
-  ".cjs",
-  ".css",
-  ".html",
-  ".js",
-  ".json",
-  ".jsx",
-  ".mjs",
-  ".svg",
-  ".ts",
-  ".tsx"
-]);
-var SIGNATURE_EXCLUDED_DIRS = /* @__PURE__ */ new Set([
-  ".cache",
-  ".git",
-  ".hyperframes",
-  ".next",
-  ".vite",
-  "build",
-  "coverage",
-  "dist",
-  "node_modules",
-  "outputs",
-  "renders"
-]);
-var MAX_SIGNATURE_TEXT_BYTES = 2e6;
-var STUDIO_SIGNATURE_MANIFEST_PATHS = [
-  ".hyperframes/studio-manual-edits.json",
-  ".hyperframes/studio-motion.json"
-];
-var projectSignatureCache = /* @__PURE__ */ new Map();
-function isPathWithin(parentDir, childPath) {
-  const childRelativePath = relative2(parentDir, childPath);
-  return childRelativePath === "" || !childRelativePath.startsWith("..") && !isAbsolute(childRelativePath);
-}
-function isTextContentEligible(file, size) {
-  return SIGNATURE_TEXT_EXTENSIONS.has(extname(file).toLowerCase()) && size <= MAX_SIGNATURE_TEXT_BYTES;
-}
-function collectProjectSignatureFiles(projectDir, dir, files) {
-  let entries;
-  try {
-    entries = readdirSync4(dir).sort();
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    if (SIGNATURE_EXCLUDED_DIRS.has(entry)) continue;
-    const file = resolve3(dir, entry);
-    if (!isPathWithin(projectDir, file)) continue;
-    let stat;
-    try {
-      stat = lstatSync(file);
-    } catch {
-      continue;
-    }
-    if (stat.isSymbolicLink()) continue;
-    if (stat.isDirectory()) {
-      collectProjectSignatureFiles(projectDir, file, files);
-    } else if (stat.isFile()) {
-      files.push({
-        file,
-        mtimeMs: stat.mtimeMs,
-        size: stat.size,
-        textContentEligible: isTextContentEligible(file, stat.size)
-      });
-    }
-  }
-}
-function collectProjectSignatureManifestFiles(projectDir, files) {
-  const seen = new Set(files.map((entry) => entry.file));
-  for (const manifestPath of STUDIO_SIGNATURE_MANIFEST_PATHS) {
-    const file = resolve3(projectDir, manifestPath);
-    if (seen.has(file) || !isPathWithin(projectDir, file)) continue;
-    let stat;
-    try {
-      stat = lstatSync(file);
-    } catch {
-      continue;
-    }
-    if (stat.isSymbolicLink() || !stat.isFile()) continue;
-    files.push({
-      file,
-      mtimeMs: stat.mtimeMs,
-      size: stat.size,
-      textContentEligible: isTextContentEligible(file, stat.size)
-    });
-    seen.add(file);
-  }
-}
-function createProjectFingerprint(projectDir, files) {
-  const hash = createHash("sha256");
-  for (const entry of files) {
-    hash.update(relative2(projectDir, entry.file));
-    hash.update("\0");
-    hash.update(String(entry.size));
-    hash.update("\0");
-    hash.update(String(entry.mtimeMs));
-    hash.update("\0");
-    hash.update(entry.textContentEligible ? "text" : "binary");
-    hash.update("\0");
-  }
-  return hash.digest("hex").slice(0, 24);
-}
-function createProjectSignature(projectDir) {
-  const normalizedProjectDir = resolve3(projectDir);
-  const files = [];
-  collectProjectSignatureFiles(normalizedProjectDir, normalizedProjectDir, files);
-  collectProjectSignatureManifestFiles(normalizedProjectDir, files);
-  files.sort((a, b) => a.file.localeCompare(b.file));
-  const fingerprint = createProjectFingerprint(normalizedProjectDir, files);
-  const cached = projectSignatureCache.get(normalizedProjectDir);
-  if (cached?.fingerprint === fingerprint) return cached.signature;
-  const hash = createHash("sha256");
-  for (const entry of files) {
-    const relativePath = relative2(normalizedProjectDir, entry.file);
-    hash.update(relativePath);
-    hash.update("\0");
-    hash.update(String(entry.size));
-    hash.update("\0");
-    if (entry.textContentEligible) {
-      try {
-        hash.update(readFileSync5(entry.file));
-      } catch {
-        hash.update(String(entry.mtimeMs));
-      }
-    } else {
-      hash.update(String(entry.mtimeMs));
-    }
-    hash.update("\0");
-  }
-  const signature = hash.digest("hex").slice(0, 24);
-  projectSignatureCache.set(normalizedProjectDir, { fingerprint, signature });
-  return signature;
-}
-
 // src/helpers/studioMotionRenderScript.ts
 var STUDIO_MOTION_PATH = ".hyperframes/studio-motion.json";
 function hasStudioMotionEntries(manifestContent) {
@@ -2945,9 +3094,6 @@ var GSAP_CDN_VERSION = "3.15.0";
 var GSAP_CDN_SCRIPT = `<script src="https://cdn.jsdelivr.net/npm/gsap@${GSAP_CDN_VERSION}/dist/gsap.min.js"></script>`;
 var GSAP_CUSTOM_EASE_CDN_SCRIPT = `<script src="https://cdn.jsdelivr.net/npm/gsap@${GSAP_CDN_VERSION}/dist/CustomEase.min.js"></script>`;
 var GSAP_MOTION_PATH_CDN_SCRIPT = `<script src="https://cdn.jsdelivr.net/npm/gsap@${GSAP_CDN_VERSION}/dist/MotionPathPlugin.min.js"></script>`;
-function resolveProjectSignature(adapter, projectDir) {
-  return adapter.getProjectSignature?.(projectDir) ?? createProjectSignature(projectDir);
-}
 function injectProjectSignature(html, signature) {
   const tag = `<meta name="${PROJECT_SIGNATURE_META}" content="${signature}">`;
   if (html.includes(`name="${PROJECT_SIGNATURE_META}"`)) {
@@ -3136,12 +3282,12 @@ function registerPreviewRoutes(api, adapter) {
     ETag: etag
   });
   api.get("/projects/:id/preview", async (c) => {
-    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 } = resolved;
     const vars = previewVariablesFromRequest(c.req.query("variables"));
     if (vars.error !== void 0) return c.json({ error: vars.error }, 400);
     const previewVariables = vars.values;
-    const signature = resolveProjectSignature(adapter, project.dir);
     const etag = `"preview:${signature}${variablesEtagSalt(vars.raw)}"`;
     const ifNoneMatch = c.req.header("If-None-Match");
     if (ifNoneMatch === etag) {
@@ -3201,12 +3347,12 @@ ${runtimeTag}`;
     return stampFileHfIds(compFile);
   }
   api.get("/projects/:id/preview/comp/*", async (c) => {
-    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 } = resolved;
     const vars = previewVariablesFromRequest(c.req.query("variables"));
     if (vars.error !== void 0) return c.json({ error: vars.error }, 400);
     const previewVariables = vars.values;
-    const signature = resolveProjectSignature(adapter, project.dir);
     const compPath = decodeURIComponent(
       c.req.path.replace(`/projects/${project.id}/preview/comp/`, "").split("?")[0] ?? ""
     );
@@ -3326,7 +3472,7 @@ import { streamSSE } from "hono/streaming";
 import { existsSync as existsSync6, readFileSync as readFileSync9, mkdirSync as mkdirSync4, unlinkSync as unlinkSync3, readdirSync as readdirSync5, statSync as statSync3 } from "fs";
 import { join as join10 } from "path";
 import { VALID_CANVAS_RESOLUTIONS } from "@hyperframes/parsers";
-import { parseFps } from "@hyperframes/core";
+import { formatRenderOutputTimestamp, parseFps } from "@hyperframes/core";
 var VALID_RESOLUTIONS = new Set(VALID_CANVAS_RESOLUTIONS);
 function registerRenderRoutes(api, adapter) {
   const renderJobs = /* @__PURE__ */ new Map();
@@ -3380,9 +3526,7 @@ function registerRenderRoutes(api, adapter) {
       variables = body.variables;
     }
     const now = /* @__PURE__ */ new Date();
-    const datePart = now.toISOString().slice(0, 10);
-    const timePart = now.toTimeString().slice(0, 8).replace(/:/g, "-");
-    const jobId = `${project.id}_${datePart}_${timePart}`;
+    const jobId = `${project.id}_${formatRenderOutputTimestamp(now)}`;
     const rendersDir = adapter.rendersDir(project);
     if (!existsSync6(rendersDir)) mkdirSync4(rendersDir, { recursive: true });
     const ext = FORMAT_EXT[format] ?? ".mp4";