@hyperframes/studio-server 0.7.59 → 0.7.60

package/dist/index.d.ts

@@ -223,6 +223,16 @@ declare function walkDir(dir: string, prefix?: string): string[];
 declare const MIME_TYPES: Record<string, string>;
 declare function getMimeType(path: string): string;
 
+interface FileWriteReceipt {
+    path: string;
+    version: string;
+    writeToken: string;
+}
+/** Strong content version used as both the JSON version and HTTP ETag. */
+declare function fileContentVersion(content: string): string;
+/** Attach one API write's identity to the corresponding filesystem-watch echo. */
+declare function consumeFileWriteReceipt(absPath: string): FileWriteReceipt | null;
+
 /**
  * Build a standalone HTML page for a sub-composition.
  *
@@ -274,4 +284,4 @@ type BackgroundRemovalRender = (options: {
 }>;
 declare function createBackgroundRemovalJob(opts: BackgroundRemovalJobOptions, render: BackgroundRemovalRender): MediaProcessingJobState;
 
-export { type BackgroundRemovalRender, type LintResult, MIME_TYPES, type MediaProcessingJobState, type RenderJobState, type ResolvedProject, type StudioApiAdapter, type StudioSelectionResponse, type StudioSelectionSnapshot, type StudioSelectionTextField, buildSubCompositionHtml, createBackgroundRemovalJob, createProjectSignature, createStudioApi, getMimeType, walkDir };
+export { type BackgroundRemovalRender, type FileWriteReceipt, type LintResult, MIME_TYPES, type MediaProcessingJobState, type RenderJobState, type ResolvedProject, type StudioApiAdapter, type StudioSelectionResponse, type StudioSelectionSnapshot, type StudioSelectionTextField, buildSubCompositionHtml, consumeFileWriteReceipt, createBackgroundRemovalJob, createProjectSignature, createStudioApi, fileContentVersion, getMimeType, walkDir };

package/dist/index.js

@@ -288,9 +288,13 @@ function registerStoryboardRoutes(api, adapter) {
 // src/routes/files.ts
 import { bodyLimit } from "hono/body-limit";
 import {
+  closeSync,
   existsSync as existsSync3,
+  ftruncateSync,
+  openSync,
   readFileSync as readFileSync4,
   writeFileSync as writeFileSync4,
+  writeSync,
   mkdirSync as mkdirSync3,
   unlinkSync as unlinkSync2,
   rmSync as rmSync2,
@@ -544,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) {
@@ -1570,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) {
@@ -2233,19 +2271,111 @@ function registerFileRoutes(api, adapter) {
       return c.json({ error: "not found" }, 404);
     }
     const content = readFileSync4(res.absPath, "utf-8");
-    return c.json({ filename: res.filePath, content });
+    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)
     });
   });
@@ -2317,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)
     });
   });
@@ -2650,7 +2791,7 @@ 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
@@ -3022,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);
@@ -3050,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;
   }
@@ -3070,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);
   }
 }
 
@@ -3234,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);
@@ -3706,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";
@@ -4318,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+)["']/);
@@ -4331,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}`;
@@ -4419,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,
@@ -4526,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);
     }
@@ -4548,7 +4689,7 @@ function registerFontRoutes(api) {
     } catch {
       return c.json({ error: "failed to read font file" }, 500);
     } finally {
-      closeSync2(fd);
+      closeSync3(fd);
     }
   });
 }
@@ -5082,12 +5223,14 @@ export {
   STUDIO_MANUAL_EDITS_PATH,
   STUDIO_MOTION_PATH,
   buildSubCompositionHtml,
+  consumeFileWriteReceipt,
   createBackgroundRemovalJob,
   createProjectSignature,
   createStudioApi,
   createStudioManualEditsRenderBodyScript,
   createStudioMotionRenderBodyScript,
   createStudioPositionSeekReapplyScript,
+  fileContentVersion,
   getElementScreenshotClip,
   getMimeType,
   isSafePath,