@hyperframes/studio-server 0.7.58 → 0.7.60

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
     });
   });
 }
@@ -133,17 +288,21 @@ function registerStoryboardRoutes(api, adapter) {
 // src/routes/files.ts
 import { bodyLimit } from "hono/body-limit";
 import {
+  closeSync,
   existsSync as existsSync3,
-  readFileSync as readFileSync3,
+  ftruncateSync,
+  openSync,
+  readFileSync as readFileSync4,
   writeFileSync as writeFileSync4,
+  writeSync,
   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 +347,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 +372,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 +481,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 +493,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 +522,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 +537,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)) {
@@ -389,6 +548,38 @@ function pruneBackups(backupDir, backupKey, keepPerFile) {
   }
 }
 
+// src/helpers/fileVersion.ts
+import { createHash as createHash2, randomUUID } from "crypto";
+var RECEIPT_TTL_MS = 1e4;
+var receipts = /* @__PURE__ */ new Map();
+function fileContentVersion(content) {
+  return `"sha256:${createHash2("sha256").update(content, "utf8").digest("hex")}"`;
+}
+function createWriteToken(requestToken) {
+  const token = requestToken?.trim();
+  return token && token.length <= 200 ? token : randomUUID();
+}
+function recordFileWriteReceipt(absPath, receipt) {
+  const now = Date.now();
+  const current = (receipts.get(absPath) ?? []).filter(
+    (entry) => now - entry.recordedAt < RECEIPT_TTL_MS
+  );
+  current.push({ ...receipt, recordedAt: now });
+  receipts.set(absPath, current);
+}
+function consumeFileWriteReceipt(absPath) {
+  const now = Date.now();
+  const current = (receipts.get(absPath) ?? []).filter(
+    (entry) => now - entry.recordedAt < RECEIPT_TTL_MS
+  );
+  const receipt = current.shift() ?? null;
+  if (current.length > 0) receipts.set(absPath, current);
+  else receipts.delete(absPath);
+  if (!receipt) return null;
+  const { path, version, writeToken } = receipt;
+  return { path, version, writeToken };
+}
+
 // src/helpers/finiteMutation.ts
 function findUnsafeMutationValues(value, path = "body", options = {}) {
   if (value === null) {
@@ -931,7 +1122,7 @@ function commitElementPatchBatches(projectDir, batches, writeFile = writeFileSyn
     resolvedPaths.add(absPath);
     let before;
     try {
-      before = readFileSync3(absPath, "utf-8");
+      before = readFileSync4(absPath, "utf-8");
     } catch {
       return { error: "not-found", sourceFile: batch.sourceFile };
     }
@@ -1053,7 +1244,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}`;
   }
@@ -1061,7 +1252,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")
@@ -1080,7 +1271,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) {
@@ -1337,7 +1528,7 @@ function validateGsapMutationRequest(c, body) {
   return null;
 }
 async function prepareGsapMutationScript(c, res, firstMutation) {
-  const beforeHtml = 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")) {
@@ -1397,7 +1588,7 @@ async function applyGsapMutations(c, res, mutations) {
   const changed = block.scriptText !== initialScript;
   const newHtml = changed ? block.replaceScript(block.scriptText) : html;
   let backupPath = null;
-  if (readFileSync3(res.absPath, "utf-8") !== beforeHtml) {
+  if (readFileSync4(res.absPath, "utf-8") !== beforeHtml) {
     return c.json({ error: "file changed during GSAP mutation", conflict: true }, 409);
   }
   if (changed) {
@@ -1415,9 +1606,11 @@ async function applyGsapMutations(c, res, mutations) {
     after: newHtml,
     scriptText: block.scriptText,
     path: res.filePath,
+    version: fileContentVersion(newHtml),
     backupPath
   };
   if (skippedSelectors.size > 0) responsePayload.skippedSelectors = [...skippedSelectors];
+  c.header("ETag", responsePayload.version);
   return c.json(responsePayload);
 }
 function executeGsapMutationAcorn(body, block, respond) {
@@ -2033,7 +2226,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;
@@ -2043,13 +2236,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);
@@ -2077,20 +2270,112 @@ function registerFileRoutes(api, adapter) {
       }
       return c.json({ error: "not found" }, 404);
     }
-    const content = readFileSync3(res.absPath, "utf-8");
-    return c.json({ filename: res.filePath, content });
+    const content = readFileSync4(res.absPath, "utf-8");
+    const version = fileContentVersion(content);
+    c.header("ETag", version);
+    return c.json({ filename: res.filePath, content, version });
   });
   api.put("/projects/:id/files/*", async (c) => {
     const res = await resolveProjectFile(c, adapter);
     if ("error" in res) return res.error;
-    ensureDir(res.absPath);
     const body = await c.req.text();
-    const backup = snapshotBeforeWrite(res.project.dir, res.absPath);
-    if (backup.error) console.warn(`Failed to create backup for ${res.filePath}: ${backup.error}`);
-    writeFileSync4(res.absPath, body, "utf-8");
+    const expectedVersion = c.req.header("If-Match")?.trim() ?? null;
+    const createOnly = c.req.header("If-None-Match")?.trim() === "*";
+    if (expectedVersion === null && !createOnly) {
+      let currentContent = null;
+      try {
+        currentContent = readFileSync4(res.absPath, "utf-8");
+      } catch (error) {
+        if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") {
+          throw error;
+        }
+      }
+      return c.json(
+        {
+          error: "precondition required",
+          path: res.filePath,
+          currentVersion: currentContent === null ? null : fileContentVersion(currentContent),
+          currentContent
+        },
+        428
+      );
+    }
+    let backup = { backupPath: null };
+    if (createOnly) {
+      ensureDir(res.absPath);
+      let fd;
+      try {
+        fd = openSync(res.absPath, "wx");
+      } catch (error) {
+        if (!error || typeof error !== "object" || !("code" in error) || error.code !== "EEXIST") {
+          throw error;
+        }
+        const currentContent = readFileSync4(res.absPath, "utf-8");
+        return c.json(
+          {
+            error: "file conflict",
+            path: res.filePath,
+            currentVersion: fileContentVersion(currentContent),
+            currentContent
+          },
+          409
+        );
+      }
+      try {
+        writeSync(fd, body, 0, "utf-8");
+      } finally {
+        closeSync(fd);
+      }
+    } else {
+      let fd;
+      try {
+        fd = openSync(res.absPath, "r+");
+      } catch (error) {
+        if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") {
+          throw error;
+        }
+        return c.json(
+          {
+            error: "file conflict",
+            path: res.filePath,
+            currentVersion: null,
+            currentContent: null
+          },
+          409
+        );
+      }
+      try {
+        const currentContent = readFileSync4(fd, "utf-8");
+        const currentVersion = fileContentVersion(currentContent);
+        if (expectedVersion !== currentVersion) {
+          return c.json(
+            {
+              error: "file conflict",
+              path: res.filePath,
+              currentVersion,
+              currentContent
+            },
+            409
+          );
+        }
+        backup = snapshotBeforeWrite(res.project.dir, res.absPath);
+        if (backup.error)
+          console.warn(`Failed to create backup for ${res.filePath}: ${backup.error}`);
+        ftruncateSync(fd, 0);
+        writeSync(fd, body, 0, "utf-8");
+      } finally {
+        closeSync(fd);
+      }
+    }
+    const version = fileContentVersion(body);
+    const writeToken = createWriteToken(c.req.header("X-Hyperframes-Write-Token"));
+    recordFileWriteReceipt(res.absPath, { path: res.filePath, version, writeToken });
+    c.header("ETag", version);
     return c.json({
       ok: true,
       path: res.filePath,
+      version,
+      writeToken,
       backupPath: backupPathForResponse(res.project.dir, backup.backupPath)
     });
   });
@@ -2129,7 +2414,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,
@@ -2150,7 +2435,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);
     }
@@ -2162,17 +2447,28 @@ function registerFileRoutes(api, adapter) {
       fallbackTiming
     );
     if (!result.matched) {
-      return c.json({ ok: false, changed: false, content: originalContent, path: ctx.filePath });
+      const version2 = fileContentVersion(originalContent);
+      c.header("ETag", version2);
+      return c.json({
+        ok: false,
+        changed: false,
+        content: originalContent,
+        path: ctx.filePath,
+        version: version2
+      });
     }
     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.html, "utf-8");
+    const version = fileContentVersion(result.html);
+    c.header("ETag", version);
     return c.json({
       ok: true,
       changed: true,
       content: result.html,
       newId: result.newId,
       path: ctx.filePath,
+      version,
       backupPath: backupPathForResponse(ctx.project.dir, backup.backupPath)
     });
   });
@@ -2190,7 +2486,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);
     }
@@ -2280,7 +2576,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);
     }
@@ -2322,7 +2618,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);
     }
@@ -2351,7 +2647,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 });
     }
@@ -2394,7 +2690,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;
@@ -2424,7 +2720,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({
@@ -2483,7 +2779,7 @@ function registerFileRoutes(api, adapter) {
     if (!body || typeof body.expected !== "string" || typeof body.restore !== "string") {
       return c.json({ error: "expected and restore contents required" }, 400);
     }
-    const current = readFileSync3(res.absPath, "utf-8");
+    const current = readFileSync4(res.absPath, "utf-8");
     if (current !== body.expected) {
       return c.json({ ok: true, restored: false, conflict: true });
     }
@@ -2495,11 +2791,11 @@ function registerFileRoutes(api, adapter) {
 // src/routes/preview.ts
 import { existsSync as existsSync5, readFileSync as readFileSync7, statSync as statSync2 } from "fs";
 import { join as join8 } from "path";
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } 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 {
@@ -2608,7 +2904,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 = "";
@@ -2641,7 +2937,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] ?? "";
   }
@@ -2674,145 +2970,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) {
@@ -3006,14 +3163,14 @@ import { ensureHfIds as ensureHfIds3 } from "@hyperframes/parsers/hf-ids";
 // src/helpers/hfIdPersist.ts
 import { ensureHfIds as ensureHfIds2 } from "@hyperframes/parsers/hf-ids";
 import {
-  closeSync,
+  closeSync as closeSync2,
   constants,
   fstatSync,
-  ftruncateSync,
-  openSync,
+  ftruncateSync as ftruncateSync2,
+  openSync as openSync2,
   readFileSync as readFileSync6,
   writeFileSync as writeFileSync5,
-  writeSync
+  writeSync as writeSync2
 } from "fs";
 function persistHfIdsIfNeeded(filePath, html) {
   const normalized = ensureHfIds2(html);
@@ -3034,7 +3191,7 @@ function persistHfIdsIfNeeded(filePath, html) {
 function openNoFollow(filePath, flags) {
   const noFollow = constants.O_NOFOLLOW ?? 0;
   try {
-    return openSync(filePath, flags | noFollow);
+    return openSync2(filePath, flags | noFollow);
   } catch {
     return null;
   }
@@ -3054,15 +3211,15 @@ function stampFileHfIds(filePath) {
     const idsBefore = (html.match(/\bdata-hf-id=/g) ?? []).length;
     const idsAfter = (normalized.match(/\bdata-hf-id=/g) ?? []).length;
     if (writable && idsAfter > idsBefore) {
-      ftruncateSync(fd, 0);
-      writeSync(fd, normalized, 0, "utf-8");
+      ftruncateSync2(fd, 0);
+      writeSync2(fd, normalized, 0, "utf-8");
     }
     return normalized;
   } catch (err) {
     console.warn("[hyperframes] stampFileHfIds: failed to stamp ids:", err);
     return null;
   } finally {
-    closeSync(fd);
+    closeSync2(fd);
   }
 }
 
@@ -3078,9 +3235,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}"`)) {
@@ -3221,7 +3375,7 @@ function parsePreviewVariablesParam(raw) {
 }
 function variablesEtagSalt(raw) {
   if (!raw) return "";
-  return `:vars:${createHash2("sha1").update(raw).digest("hex").slice(0, 12)}`;
+  return `:vars:${createHash3("sha1").update(raw).digest("hex").slice(0, 12)}`;
 }
 function previewVariablesFromRequest(rawVariables) {
   const parse = parsePreviewVariablesParam(rawVariables);
@@ -3269,12 +3423,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) {
@@ -3334,12 +3488,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] ?? ""
     );
@@ -3459,7 +3613,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();
@@ -3513,9 +3667,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";
@@ -3695,7 +3847,7 @@ function registerRenderRoutes(api, adapter) {
 // src/routes/thumbnail.ts
 import { existsSync as existsSync7, readFileSync as readFileSync10, writeFileSync as writeFileSync6, mkdirSync as mkdirSync5, statSync as statSync4 } from "fs";
 import { join as join11 } from "path";
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 
 // src/helpers/manualEditsRenderScript.ts
 var STUDIO_MANUAL_EDITS_PATH = ".hyperframes/studio-manual-edits.json";
@@ -4307,7 +4459,7 @@ function registerThumbnailRoutes(api, adapter) {
     const htmlFile = join11(project.dir, compPath);
     if (existsSync7(htmlFile)) {
       const html = readFileSync10(htmlFile, "utf-8");
-      sourceKey = `_${createHash3("sha1").update(html).digest("hex").slice(0, 16)}`;
+      sourceKey = `_${createHash4("sha1").update(html).digest("hex").slice(0, 16)}`;
       sourceMtime = Math.round(statSync4(htmlFile).mtimeMs);
       if (!vpWidth) {
         const wMatch = html.match(/data-width=["'](\d+)["']/);
@@ -4320,14 +4472,14 @@ function registerThumbnailRoutes(api, adapter) {
     let manualEditsKey = "";
     if (existsSync7(manualEditsFile)) {
       const manualEditsContent = readFileSync10(manualEditsFile, "utf-8");
-      manualEditsKey = `_${createHash3("sha1").update(manualEditsContent).digest("hex").slice(0, 16)}`;
+      manualEditsKey = `_${createHash4("sha1").update(manualEditsContent).digest("hex").slice(0, 16)}`;
       sourceMtime = Math.max(sourceMtime, Math.round(statSync4(manualEditsFile).mtimeMs));
     }
     const motionFile = join11(project.dir, STUDIO_MOTION_PATH);
     let motionKey = "";
     if (existsSync7(motionFile)) {
       const motionContent = readFileSync10(motionFile, "utf-8");
-      motionKey = `_${createHash3("sha1").update(motionContent).digest("hex").slice(0, 16)}`;
+      motionKey = `_${createHash4("sha1").update(motionContent).digest("hex").slice(0, 16)}`;
       sourceMtime = Math.max(sourceMtime, Math.round(statSync4(motionFile).mtimeMs));
     }
     const previewUrl = compPath === "index.html" ? `http://${c.req.header("host")}/api/projects/${project.id}/preview` : `http://${c.req.header("host")}/api/projects/${project.id}/preview/comp/${compPath}`;
@@ -4408,7 +4560,7 @@ function registerWaveformRoutes(api, adapter) {
 }
 
 // src/routes/fonts.ts
-import { closeSync as closeSync2, constants as constants2, fstatSync as fstatSync2, openSync as openSync2, readSync } from "fs";
+import { closeSync as closeSync3, constants as constants2, fstatSync as fstatSync2, openSync as openSync3, readSync } from "fs";
 import {
   collectFontFileEntries,
   fontDirectories,
@@ -4515,7 +4667,7 @@ function registerFontRoutes(api) {
     if (!located) return c.json({ error: "font not found" }, 404);
     let fd;
     try {
-      fd = openSync2(located.path, constants2.O_RDONLY | constants2.O_NOFOLLOW);
+      fd = openSync3(located.path, constants2.O_RDONLY | constants2.O_NOFOLLOW);
     } catch {
       return c.json({ error: "font file not accessible" }, 404);
     }
@@ -4537,7 +4689,7 @@ function registerFontRoutes(api) {
     } catch {
       return c.json({ error: "failed to read font file" }, 500);
     } finally {
-      closeSync2(fd);
+      closeSync3(fd);
     }
   });
 }
@@ -5071,12 +5223,14 @@ export {
   STUDIO_MANUAL_EDITS_PATH,
   STUDIO_MOTION_PATH,
   buildSubCompositionHtml,
+  consumeFileWriteReceipt,
   createBackgroundRemovalJob,
   createProjectSignature,
   createStudioApi,
   createStudioManualEditsRenderBodyScript,
   createStudioMotionRenderBodyScript,
   createStudioPositionSeekReapplyScript,
+  fileContentVersion,
   getElementScreenshotClip,
   getMimeType,
   isSafePath,