@hyperframes/studio-server 0.8.75 → 0.8.77

package/dist/index.js

@@ -13,7 +13,7 @@ import {
   splitElementInHtml,
   unwrapElementsFromHtml,
   wrapElementsInHtml
-} from "./chunk-KFPWE4Q7.js";
+} from "./chunk-QYDRVMJ6.js";
 import {
   getElementScreenshotClip
 } from "./chunk-W2SBTCO2.js";
@@ -22,7 +22,7 @@ import {
   isAutoProxyEnabled,
   proxyEtagSalt,
   resolvePreviewMediaCodecProbeCache
-} from "./chunk-PGL4S2ZU.js";
+} from "./chunk-X3T65KC2.js";
 import {
   ProxyCapacityError,
   ProxyTranscodeError,
@@ -52,7 +52,7 @@ import { Hono } from "hono";
 
 // src/routes/projects.ts
 import { readFile } from "fs/promises";
-import { join as join2 } from "path";
+import { join as join3 } from "path";
 
 // src/helpers/safePath.ts
 import { join } from "path";
@@ -86,9 +86,113 @@ function walkDir(dir, prefix = "") {
   return files;
 }
 
-// src/helpers/projectSignature.ts
+// src/helpers/hfIdPersist.ts
+import { ensureHfIds } from "@hyperframes/parsers/hf-ids";
 import { createHash } from "crypto";
-import { lstatSync, readFileSync, readdirSync as readdirSync2 } from "fs";
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  writeFileSync
+} from "fs";
+import { dirname, join as join2 } from "path";
+
+// src/helpers/atomicFile.ts
+import * as fs from "fs";
+import { randomUUID } from "crypto";
+function replaceFileAtomically(filePath, content, mode, operations = fs) {
+  const tempPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    operations.writeFileSync(tempPath, content, { encoding: "utf-8", mode });
+    operations.chmodSync(tempPath, mode);
+    operations.renameSync(tempPath, filePath);
+  } catch (error) {
+    try {
+      operations.unlinkSync(tempPath);
+    } catch {
+    }
+    throw error;
+  }
+}
+
+// src/helpers/hfIdPersist.ts
+var isCompositionSource = (html) => /data-composition-id\s*=/.test(html);
+var STAMP_RECORD = join2(".hyperframes", "hf-ids-stamped.json");
+var contentHash = (text2) => createHash("sha1").update(text2).digest("base64url");
+function stampProjectHfIds(projectDir) {
+  const recordPath = join2(projectDir, STAMP_RECORD);
+  let last = {};
+  try {
+    last = JSON.parse(readFileSync(recordPath, "utf-8"));
+  } catch {
+  }
+  const next = {};
+  for (const file of walkDir(projectDir)) {
+    if (!file.endsWith(".html") || isInHiddenOrVendorDir(file)) continue;
+    const absPath = join2(projectDir, file);
+    let html;
+    try {
+      html = readFileSync(absPath, "utf-8");
+    } catch {
+      continue;
+    }
+    let hash = contentHash(html);
+    if (last[file] !== hash && isCompositionSource(html)) {
+      const stamped = stampFileHfIds(absPath);
+      if (stamped === null) continue;
+      hash = contentHash(stamped);
+    }
+    next[file] = hash;
+  }
+  try {
+    mkdirSync(dirname(recordPath), { recursive: true });
+    writeFileSync(recordPath, JSON.stringify(next));
+  } catch {
+  }
+}
+function openNoFollow(filePath, flags) {
+  const noFollow = constants.O_NOFOLLOW ?? 0;
+  try {
+    return openSync(filePath, flags | noFollow);
+  } catch {
+    return null;
+  }
+}
+function stampFileHfIds(filePath) {
+  let fd = openNoFollow(filePath, constants.O_RDWR);
+  let writable = true;
+  if (fd === null) {
+    fd = openNoFollow(filePath, constants.O_RDONLY);
+    writable = false;
+  }
+  if (fd === null) return null;
+  try {
+    if (!fstatSync(fd).isFile()) return null;
+    const html = readFileSync(fd, "utf-8");
+    const normalized = ensureHfIds(html);
+    const idsBefore = (html.match(/\bdata-hf-id=/g) ?? []).length;
+    const idsAfter = (normalized.match(/\bdata-hf-id=/g) ?? []).length;
+    if (writable && idsAfter > idsBefore) {
+      const mode = fstatSync(fd).mode;
+      closeSync(fd);
+      fd = null;
+      replaceFileAtomically(filePath, normalized, mode);
+    }
+    return normalized;
+  } catch (err) {
+    console.warn("[hyperframes] stampFileHfIds: failed to stamp ids:", err);
+    return null;
+  } finally {
+    if (fd !== null) closeSync(fd);
+  }
+}
+
+// src/helpers/projectSignature.ts
+import { createHash as createHash2 } from "crypto";
+import { lstatSync, readFileSync as readFileSync2, readdirSync as readdirSync2 } from "fs";
 import { extname, isAbsolute, relative, resolve, sep } from "path";
 var SIGNATURE_TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
   ".cjs",
@@ -194,7 +298,7 @@ function collectProjectSignatureManifestFiles(projectDir, files) {
   }
 }
 function createProjectFingerprint(projectDir, files) {
-  const hash = createHash("sha256");
+  const hash = createHash2("sha256");
   for (const entry of files) {
     hash.update(relative(projectDir, entry.file));
     hash.update("\0");
@@ -240,10 +344,10 @@ function createProjectSignature(projectDir, excluding = /* @__PURE__ */ new Set(
   );
   files.sort((a, b) => a.file.localeCompare(b.file));
   const fingerprint = createProjectFingerprint(normalizedProjectDir, files);
-  const cacheKey = excluding.size ? `${normalizedProjectDir}\0${createHash("sha256").update([...excluding].sort().join("\0")).digest("hex")}` : normalizedProjectDir;
+  const cacheKey = excluding.size ? `${normalizedProjectDir}\0${createHash2("sha256").update([...excluding].sort().join("\0")).digest("hex")}` : normalizedProjectDir;
   const cached = projectSignatureCache.get(cacheKey);
   if (cached?.fingerprint === fingerprint) return cached.signature;
-  const hash = createHash("sha256");
+  const hash = createHash2("sha256");
   for (const entry of files) {
     const relativePath = relative(normalizedProjectDir, entry.file);
     hash.update(relativePath);
@@ -252,7 +356,7 @@ function createProjectSignature(projectDir, excluding = /* @__PURE__ */ new Set(
     hash.update("\0");
     if (entry.textContentEligible) {
       try {
-        hash.update(readFileSync(entry.file));
+        hash.update(readFileSync2(entry.file));
       } catch {
         hash.update(String(entry.mtimeMs));
       }
@@ -267,14 +371,13 @@ function createProjectSignature(projectDir, excluding = /* @__PURE__ */ new Set(
 }
 
 // src/routes/projects.ts
-var COMPOSITION_ID_RE = /data-composition-id\s*=/;
 async function filterCompositionFiles(projectDir, files) {
   const htmlFiles = files.filter((f) => f.endsWith(".html") && !isInHiddenOrVendorDir(f));
   const checks = await Promise.all(
     htmlFiles.map(async (f) => {
       try {
-        const content = await readFile(join2(projectDir, f), "utf-8");
-        return COMPOSITION_ID_RE.test(content);
+        const content = await readFile(join3(projectDir, f), "utf-8");
+        return isCompositionSource(content);
       } catch {
         return false;
       }
@@ -313,23 +416,23 @@ function registerProjectRoutes(api, adapter) {
 // src/routes/files.ts
 import { bodyLimit } from "hono/body-limit";
 import {
-  closeSync,
+  closeSync as closeSync2,
   existsSync as existsSync3,
   lstatSync as lstatSync3,
-  openSync,
-  readFileSync as readFileSync5,
+  openSync as openSync2,
+  readFileSync as readFileSync6,
   readlinkSync,
-  writeFileSync as writeFileSync4,
+  writeFileSync as writeFileSync5,
   writeSync,
-  mkdirSync as mkdirSync3,
+  mkdirSync as mkdirSync4,
   unlinkSync as unlinkSync2,
   rmSync as rmSync3,
   statSync as statSync3,
-  fstatSync,
+  fstatSync as fstatSync2,
   renameSync as renameSync2,
   readdirSync as readdirSync4
 } from "fs";
-import { resolve as resolve3, dirname as dirname3, join as join6 } from "path";
+import { resolve as resolve3, dirname as dirname4, join as join7 } from "path";
 
 // src/helpers/mime.ts
 var MIME_TYPES = {
@@ -377,37 +480,19 @@ function isAudioFile(name) {
   return (getMimeType(name) ?? "").startsWith("audio/");
 }
 
-// src/helpers/atomicFile.ts
-import * as fs from "fs";
-import { randomUUID } from "crypto";
-function replaceFileAtomically(filePath, content, mode, operations = fs) {
-  const tempPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
-  try {
-    operations.writeFileSync(tempPath, content, { encoding: "utf-8", mode });
-    operations.chmodSync(tempPath, mode);
-    operations.renameSync(tempPath, filePath);
-  } catch (error) {
-    try {
-      operations.unlinkSync(tempPath);
-    } catch {
-    }
-    throw error;
-  }
-}
-
 // src/helpers/waveform.ts
 import { spawn } from "child_process";
 import {
   existsSync,
-  writeFileSync,
-  mkdirSync,
+  writeFileSync as writeFileSync2,
+  mkdirSync as mkdirSync2,
   lstatSync as lstatSync2,
   mkdtempSync,
   renameSync,
   rmSync,
   statSync
 } from "fs";
-import { dirname, join as join3 } from "path";
+import { dirname as dirname2, join as join4 } from "path";
 import { findFfBinary } from "@hyperframes/parsers/ff-binaries";
 var SAMPLE_RATE = 4e3;
 var PEAK_COUNT = 4e3;
@@ -474,11 +559,11 @@ function decodeAudioPeaks(audioPath) {
   });
 }
 async function generateWaveformCache(projectDir, assetPath) {
-  const audioPath = join3(projectDir, assetPath);
+  const audioPath = join4(projectDir, assetPath);
   if (!existsSync(audioPath)) return;
   const stats = statSync(audioPath);
-  const cacheDir = join3(projectDir, ".waveform-cache");
-  const cachePath = join3(cacheDir, buildWaveformCacheKey(assetPath, stats));
+  const cacheDir = join4(projectDir, ".waveform-cache");
+  const cachePath = join4(cacheDir, buildWaveformCacheKey(assetPath, stats));
   if (isWaveformCacheDirectory(cacheDir) && existsSync(cachePath)) return;
   const peaks = await decodeAudioPeaks(audioPath);
   writeWaveformCache(cachePath, peaks);
@@ -487,19 +572,19 @@ function isWaveformCacheDirectory(cacheDir) {
   return lstatSync2(cacheDir, { throwIfNoEntry: false })?.isDirectory() ?? false;
 }
 function writeWaveformCache(cachePath, peaks) {
-  const cacheDir = dirname(cachePath);
+  const cacheDir = dirname2(cachePath);
   try {
-    mkdirSync(cacheDir, { mode: 448 });
+    mkdirSync2(cacheDir, { mode: 448 });
   } catch (error) {
     if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw error;
   }
   if (!isWaveformCacheDirectory(cacheDir)) {
     throw new Error("Waveform cache must be a directory, not a symlink");
   }
-  const stagingDir = mkdtempSync(join3(cacheDir, ".waveform-"));
+  const stagingDir = mkdtempSync(join4(cacheDir, ".waveform-"));
   try {
-    const stagingPath = join3(stagingDir, "peaks.json");
-    writeFileSync(stagingPath, JSON.stringify(peaks), { flag: "wx" });
+    const stagingPath = join4(stagingDir, "peaks.json");
+    writeFileSync2(stagingPath, JSON.stringify(peaks), { flag: "wx" });
     renameSync(stagingPath, cachePath);
   } finally {
     try {
@@ -511,9 +596,9 @@ function writeWaveformCache(cachePath, peaks) {
 
 // src/helpers/mediaValidation.ts
 import { spawnSync } from "child_process";
-import { mkdtempSync as mkdtempSync2, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
+import { mkdtempSync as mkdtempSync2, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "fs";
 import { tmpdir } from "os";
-import { basename, join as join4 } from "path";
+import { basename, join as join5 } from "path";
 var VIDEO_EXT = /\.(mp4|webm|mov|mkv|avi|m4v|mxf|mts|m2ts|ts)$/i;
 var AUDIO_EXT = /\.(mp3|wav|ogg|m4a|aac)$/i;
 function validateUploadedMedia(filePath, runner = spawnSync) {
@@ -550,10 +635,10 @@ function validateUploadedMedia(filePath, runner = spawnSync) {
   }
 }
 function validateUploadedMediaBuffer(fileName, buffer, runner = spawnSync) {
-  const tempDir = mkdtempSync2(join4(tmpdir(), "hyperframes-upload-"));
-  const tempPath = join4(tempDir, basename(fileName));
+  const tempDir = mkdtempSync2(join5(tmpdir(), "hyperframes-upload-"));
+  const tempPath = join5(tempDir, basename(fileName));
   try {
-    writeFileSync2(tempPath, buffer);
+    writeFileSync3(tempPath, buffer);
     return validateUploadedMedia(tempPath, runner);
   } finally {
     rmSync2(tempDir, { recursive: true, force: true });
@@ -561,9 +646,9 @@ function validateUploadedMediaBuffer(fileName, buffer, runner = spawnSync) {
 }
 
 // src/helpers/backupJournal.ts
-import { mkdirSync as mkdirSync2, readdirSync as readdirSync3, readFileSync as readFileSync2, unlinkSync, writeFileSync as writeFileSync3 } from "fs";
+import { mkdirSync as mkdirSync3, readdirSync as readdirSync3, readFileSync as readFileSync3, unlinkSync, writeFileSync as writeFileSync4 } from "fs";
 import { Buffer as Buffer2 } from "buffer";
-import { join as join5, relative as relative2 } from "path";
+import { join as join6, relative as relative2 } from "path";
 var DEFAULT_KEEP_PER_FILE = 10;
 function backupKeyForPath(path) {
   return Buffer2.from(path, "utf-8").toString("base64url");
@@ -580,13 +665,13 @@ function backupPathForResponse(projectDir, backupPath) {
 function snapshotBeforeWrite(projectDir, absPath, options = {}) {
   if (!isSafePath(projectDir, absPath)) return { backupPath: null };
   try {
-    const content = readFileSync2(absPath);
+    const content = readFileSync3(absPath);
     const relativePath = relative2(projectDir, absPath);
-    const backupDir = join5(projectDir, ".hyperframes", "backup");
-    mkdirSync2(backupDir, { recursive: true });
+    const backupDir = join6(projectDir, ".hyperframes", "backup");
+    mkdirSync3(backupDir, { recursive: true });
     const backupKey = backupKeyForPath(relativePath);
     const backupPath = nextBackupPath(backupDir, backupKey);
-    writeFileSync3(backupPath, content);
+    writeFileSync4(backupPath, content);
     pruneBackups(backupDir, backupKey, options.keepPerFile ?? DEFAULT_KEEP_PER_FILE);
     return { backupPath };
   } catch (error) {
@@ -598,18 +683,18 @@ function snapshotBeforeWrite(projectDir, absPath, options = {}) {
 }
 function nextBackupPath(backupDir, backupKey) {
   const base = `${timestampPrefix()}-${backupKey}`;
-  let candidate = join5(backupDir, base);
+  let candidate = join6(backupDir, base);
   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;
       }
       throw error;
     }
-    candidate = join5(backupDir, `${base}-${counter}`);
+    candidate = join6(backupDir, `${base}-${counter}`);
     counter += 1;
   }
 }
@@ -617,7 +702,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 = readdirSync3(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) => join6(backupDir, name)).sort((a, b) => {
     return b.localeCompare(a);
   });
   for (const file of matches.slice(keep)) {
@@ -629,11 +714,18 @@ function pruneBackups(backupDir, backupKey, keepPerFile) {
 }
 
 // src/helpers/fileVersion.ts
-import { createHash as createHash2, randomUUID as randomUUID2 } from "crypto";
+import { createHash as createHash3, randomUUID as randomUUID2 } from "crypto";
 var RECEIPT_TTL_MS = 1e4;
 var receipts = /* @__PURE__ */ new Map();
 function fileContentVersion(content) {
-  return `"sha256:${createHash2("sha256").update(content).digest("hex")}"`;
+  return hashVersion(createHash3("sha256").update(content).digest("hex"));
+}
+var DELETED_VERSION = '"deleted"';
+function hashVersion(hex) {
+  return `"sha256:${hex}"`;
+}
+function hashOfVersion(version) {
+  return /^"sha256:([0-9a-f]{64})"$/.exec(version)?.[1];
 }
 function settledFileTag(stat2, now = Date.now()) {
   if (now - stat2.ctimeMs < 3e3) return null;
@@ -676,11 +768,11 @@ function identifyFileWrite(absPath, expectedVersion) {
 var consumeFileWriteReceipt = identifyFileWrite;
 
 // src/helpers/applyFileMutations.ts
-import { readFileSync as readFileSync3, statSync as statSync2 } from "fs";
+import { readFileSync as readFileSync4, statSync as statSync2 } from "fs";
 function applyFileMutations(projectDir, mutations, requestToken, writeFile = (path, content) => replaceFileAtomically(path, content, statSync2(path).mode)) {
   const prepared = mutations.map((mutation) => ({
     ...mutation,
-    before: mutation.before ?? readFileSync3(mutation.absPath, "utf-8")
+    before: mutation.before ?? readFileSync4(mutation.absPath, "utf-8")
   }));
   const results = [];
   const attempted = [];
@@ -709,7 +801,7 @@ function applyFileMutations(projectDir, mutations, requestToken, writeFile = (pa
   }
 }
 function applyOneMutation(projectDir, mutation, requestToken, writeFile, attempted) {
-  const current = readFileSync3(mutation.absPath, "utf-8");
+  const current = readFileSync4(mutation.absPath, "utf-8");
   assertExpectedVersion(mutation.expectedVersion, current);
   if (mutation.after === mutation.before) {
     return {
@@ -781,11 +873,12 @@ import {
   syncPositionHoldsBeforeKeyframes
 } from "@hyperframes/parsers/gsap-writer-acorn";
 import { parseHTML as parseHTML2 } from "linkedom";
+import { ensureHfIds as ensureHfIds2 } from "@hyperframes/parsers/hf-ids";
 
 // src/helpers/compositionInsertion.ts
-import { existsSync as existsSync2, readFileSync as readFileSync4, realpathSync } from "fs";
+import { existsSync as existsSync2, readFileSync as readFileSync5, realpathSync } from "fs";
 import { randomUUID as randomUUID3 } from "crypto";
-import { dirname as dirname2, relative as relative3, resolve as resolve2, sep as sep2 } from "path";
+import { dirname as dirname3, relative as relative3, resolve as resolve2, sep as sep2 } from "path";
 import { parseHTML } from "linkedom";
 var CompositionInsertionError = class extends Error {
   constructor(message, status) {
@@ -840,7 +933,7 @@ function canonicalDependency(projectDir, ownerAbs, sourcePath) {
   validateSourcePath(sourcePath);
   return canonicalProjectPath(
     projectDir,
-    resolveWithinProject(projectDir, relative3(projectDir, resolve2(dirname2(ownerAbs), sourcePath)))
+    resolveWithinProject(projectDir, relative3(projectDir, resolve2(dirname3(ownerAbs), sourcePath)))
   );
 }
 function validateDependencyGraph(projectDir, targetAbs, sourceAbs) {
@@ -855,7 +948,7 @@ function validateDependencyGraph(projectDir, targetAbs, sourceAbs) {
     }
     if (visited.has(file)) return;
     visiting.add(file);
-    const source = readFileSync4(file, "utf-8");
+    const source = readFileSync5(file, "utf-8");
     const { document } = compositionRoot(source);
     for (const host of descendants(document, "[data-composition-src]")) {
       const dependency = host.getAttribute("data-composition-src");
@@ -913,13 +1006,13 @@ function uniqueHostId(root, base) {
   return `${base}_${suffix}`;
 }
 function relativeSourcePath(targetAbs, sourceAbs) {
-  return relative3(dirname2(targetAbs), sourceAbs).split(sep2).join("/");
+  return relative3(dirname3(targetAbs), sourceAbs).split(sep2).join("/");
 }
 function insertCompositionIntoSource(input) {
   const targetAbs = canonicalProjectFile(input.projectDir, input.targetPath);
   const sourceAbs = canonicalProjectFile(input.projectDir, input.sourcePath);
   validateDependencyGraph(input.projectDir, targetAbs, sourceAbs);
-  const source = readFileSync4(sourceAbs, "utf-8");
+  const source = readFileSync5(sourceAbs, "utf-8");
   const sourceComposition = compositionRoot(source).root;
   const duration = positiveAttribute(
     sourceComposition,
@@ -1040,11 +1133,12 @@ function requestSubPath(url, route) {
 }
 
 // src/routes/files.ts
+import { insertBeforeCloseTag } from "@hyperframes/core/compiler/html-document";
 async function loadGsapParser() {
   return import("@hyperframes/parsers/gsap-parser-recast");
 }
 function isDanglingSymlinkInProject(projectDir, lexicalPath) {
-  if (!isSafePath(projectDir, dirname3(lexicalPath))) return false;
+  if (!isSafePath(projectDir, dirname4(lexicalPath))) return false;
   let stats;
   try {
     stats = lstatSync3(lexicalPath);
@@ -1052,7 +1146,7 @@ function isDanglingSymlinkInProject(projectDir, lexicalPath) {
     return false;
   }
   if (!stats.isSymbolicLink()) return false;
-  const target = resolve3(dirname3(lexicalPath), readlinkSync(lexicalPath));
+  const target = resolve3(dirname4(lexicalPath), readlinkSync(lexicalPath));
   if (!isSafePath(projectDir, target)) return false;
   try {
     statSync3(lexicalPath);
@@ -1151,7 +1245,7 @@ function commitElementPatchBatches(projectDir, batches, writeFile = (path, conte
     resolvedPaths.add(absPath);
     let before;
     try {
-      before = readFileSync5(absPath, "utf-8");
+      before = readFileSync6(absPath, "utf-8");
     } catch {
       return { error: "not-found", sourceFile: batch.sourceFile };
     }
@@ -1202,7 +1296,7 @@ function commitElementPatchBatchesWithReceipts(c, projectDir, batches) {
   return commitElementPatchBatches(
     projectDir,
     batches,
-    writeFileSync4,
+    writeFileSync5,
     c.req.header("X-Hyperframes-Write-Token")
   );
 }
@@ -1260,8 +1354,8 @@ async function parseMutationBody(c) {
   return { target: body.target, body };
 }
 function ensureDir(filePath) {
-  const dir = dirname3(filePath);
-  if (!existsSync3(dir)) mkdirSync3(dir, { recursive: true });
+  const dir = dirname4(filePath);
+  if (!existsSync3(dir)) mkdirSync4(dir, { recursive: true });
 }
 function generateCopyPath(projectDir, originalPath) {
   const ext = originalPath.includes(".") ? "." + originalPath.split(".").pop() : "";
@@ -1279,7 +1373,7 @@ function generateCopyPath(projectDir, originalPath) {
 function walkFiles(dir, filter) {
   const results = [];
   for (const entry of readdirSync4(dir, { withFileTypes: true })) {
-    const full = join6(dir, entry.name);
+    const full = join7(dir, entry.name);
     if (entry.isDirectory()) {
       if (entry.name === "node_modules" || entry.name === ".thumbnails" || entry.name === "renders" || entry.name === ".transcode-cache")
         continue;
@@ -1298,7 +1392,7 @@ function updateReferences(projectDir, oldPath, newPath) {
   let updatedCount = 0;
   for (const file of textFiles) {
     if (!isSafePath(projectDir, file)) continue;
-    const content = readFileSync5(file, "utf-8");
+    const content = readFileSync6(file, "utf-8");
     if (!content.includes(oldPath)) continue;
     const updated = content.split(oldPath).join(newPath);
     if (updated !== content) {
@@ -1309,7 +1403,7 @@ function updateReferences(projectDir, oldPath, newPath) {
   return updatedCount;
 }
 function extractGsapScriptBlock(html) {
-  const { document } = parseHTML2(html);
+  const { document } = parseHTML2(ensureHfIds2(html));
   const scripts = [
     ...document.querySelectorAll("script:not([src])"),
     ...Array.from(document.querySelectorAll("template")).flatMap(
@@ -1572,7 +1666,7 @@ function containsRawGsapExpression(value) {
   return Object.values(value).some(containsRawGsapExpression);
 }
 async function prepareGsapMutationScript(c, res, firstMutation) {
-  const beforeHtml = readFileSync5(res.absPath, "utf-8");
+  const beforeHtml = readFileSync6(res.absPath, "utf-8");
   let html = beforeHtml;
   let block = extractGsapScriptBlock(html);
   if (!block && (firstMutation.type === "add" || firstMutation.type === "add-with-keyframes")) {
@@ -1586,8 +1680,8 @@ async function prepareGsapMutationScript(c, res, firstMutation) {
       `window.__timelines["${compId}"] = tl;`,
       "</script>"
     ].join("\n");
-    html = html.includes("</body>") ? html.replace("</body>", `${bootstrap}
-</body>`) : `${html}
+    html = insertBeforeCloseTag(html, "body", `${bootstrap}
+`) ?? `${html}
 ${bootstrap}`;
     block = extractGsapScriptBlock(html);
   }
@@ -1639,7 +1733,7 @@ async function applyGsapMutations(c, res, mutations) {
   const changed = block.scriptText !== initialScript;
   const newHtml = changed ? block.replaceScript(block.scriptText) : html;
   let backupPath = null;
-  if (readFileSync5(res.absPath, "utf-8") !== beforeHtml) {
+  if (readFileSync6(res.absPath, "utf-8") !== beforeHtml) {
     return c.json({ error: "file changed during GSAP mutation", conflict: true }, 409);
   }
   if (changed) {
@@ -2420,11 +2514,11 @@ async function processUploadedFiles(formData, targetDir, projectDir) {
     let written = false;
     while (n < MAX_COPY_INDEX && isSafePath(projectDir, finalPath)) {
       try {
-        const fd = openSync(finalPath, "wx");
+        const fd = openSync2(finalPath, "wx");
         try {
-          writeFileSync4(fd, buffer);
+          writeFileSync5(fd, buffer);
         } finally {
-          closeSync(fd);
+          closeSync2(fd);
         }
         written = true;
         break;
@@ -2441,7 +2535,7 @@ async function processUploadedFiles(formData, targetDir, projectDir) {
       if (n >= MAX_COPY_INDEX) skipped.push(name);
       continue;
     }
-    const relativePath = subDir ? join6(subDir, finalName) : finalName;
+    const relativePath = subDir ? join7(subDir, finalName) : finalName;
     uploaded.push(relativePath);
     if (isAudioFile(finalName)) {
       generateWaveformCache(projectDir, relativePath).catch(() => {
@@ -2456,7 +2550,7 @@ function registerFileRoutes(api, adapter) {
     if ("error" in res) return res.error;
     let fd;
     try {
-      fd = openSync(res.absPath, "r");
+      fd = openSync2(res.absPath, "r");
     } catch {
       if (c.req.query("optional") === "1") {
         return c.json({ filename: res.filePath, content: "", missing: true });
@@ -2464,10 +2558,10 @@ function registerFileRoutes(api, adapter) {
       return c.json({ error: "not found" }, 404);
     }
     try {
-      if (!fstatSync(fd).isFile()) {
+      if (!fstatSync2(fd).isFile()) {
         return c.json({ error: "not found", why: "not_a_file" }, 404);
       }
-      const content = readFileSync5(fd);
+      const content = readFileSync6(fd);
       const version = fileContentVersion(content);
       c.header("ETag", version);
       return c.json({
@@ -2477,7 +2571,7 @@ function registerFileRoutes(api, adapter) {
         missing: false
       });
     } finally {
-      closeSync(fd);
+      closeSync2(fd);
     }
   });
   api.put("/projects/:id/files/*", async (c) => {
@@ -2489,7 +2583,7 @@ function registerFileRoutes(api, adapter) {
     if (expectedVersion === null && !createOnly) {
       let currentContent = null;
       try {
-        currentContent = readFileSync5(res.absPath);
+        currentContent = readFileSync6(res.absPath);
       } catch (error) {
         if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") {
           throw error;
@@ -2510,12 +2604,12 @@ function registerFileRoutes(api, adapter) {
       ensureDir(res.absPath);
       let fd;
       try {
-        fd = openSync(res.absPath, "wx");
+        fd = openSync2(res.absPath, "wx");
       } catch (error) {
         if (!error || typeof error !== "object" || !("code" in error) || error.code !== "EEXIST") {
           throw error;
         }
-        const currentContent = readFileSync5(res.absPath);
+        const currentContent = readFileSync6(res.absPath);
         return c.json(
           {
             error: "file conflict",
@@ -2529,12 +2623,12 @@ function registerFileRoutes(api, adapter) {
       try {
         writeSync(fd, body, 0, body.length, 0);
       } finally {
-        closeSync(fd);
+        closeSync2(fd);
       }
     } else {
       let fd;
       try {
-        fd = openSync(res.absPath, "r+");
+        fd = openSync2(res.absPath, "r+");
       } catch (error) {
         if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") {
           throw error;
@@ -2550,7 +2644,7 @@ function registerFileRoutes(api, adapter) {
         );
       }
       try {
-        const currentContent = readFileSync5(fd);
+        const currentContent = readFileSync6(fd);
         const currentVersion = fileContentVersion(currentContent);
         if (expectedVersion !== currentVersion) {
           return c.json(
@@ -2565,12 +2659,12 @@ function registerFileRoutes(api, adapter) {
         }
         backup = snapshotBeforeWrite(res.project.dir, res.absPath);
         if (backup.error) return c.json({ error: `backup failed: ${backup.error}` }, 500);
-        const mode = fstatSync(fd).mode;
-        closeSync(fd);
+        const mode = fstatSync2(fd).mode;
+        closeSync2(fd);
         fd = null;
         replaceFileAtomically(res.absPath, body, mode);
       } finally {
-        if (fd !== null) closeSync(fd);
+        if (fd !== null) closeSync2(fd);
       }
     }
     const version = fileContentVersion(body);
@@ -2591,7 +2685,7 @@ function registerFileRoutes(api, adapter) {
     ensureDir(res.absPath);
     const body = Buffer.from(await c.req.arrayBuffer());
     try {
-      writeFileSync4(res.absPath, body, { flag: "wx" });
+      writeFileSync5(res.absPath, body, { flag: "wx" });
     } catch (error) {
       if (!error || typeof error !== "object" || !("code" in error) || error.code !== "EEXIST") {
         throw error;
@@ -2625,7 +2719,7 @@ function registerFileRoutes(api, adapter) {
     }
     let before;
     try {
-      before = readFileSync5(ctx.absPath, "utf-8");
+      before = readFileSync6(ctx.absPath, "utf-8");
     } catch (error) {
       if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") {
         throw error;
@@ -2682,7 +2776,7 @@ function registerFileRoutes(api, adapter) {
     }
     const parsed = await parseMutationBody(c);
     if ("error" in parsed) return parsed.error;
-    const originalContent = readFileSync5(ctx.absPath, "utf-8");
+    const originalContent = readFileSync6(ctx.absPath, "utf-8");
     return writeIfChanged(
       c,
       ctx.project.dir,
@@ -2703,7 +2797,7 @@ function registerFileRoutes(api, adapter) {
     if (!Array.isArray(targets) || targets.length === 0) {
       return c.json({ error: "targets required" }, 400);
     }
-    const originalContent = readFileSync5(ctx.absPath, "utf-8");
+    const originalContent = readFileSync6(ctx.absPath, "utf-8");
     let next = originalContent;
     for (const target of targets) {
       next = removeElementFromHtml(next, target);
@@ -2736,7 +2830,7 @@ function registerFileRoutes(api, adapter) {
         seen.add(absPath);
         let before;
         try {
-          before = readFileSync5(absPath, "utf-8");
+          before = readFileSync6(absPath, "utf-8");
         } catch {
           return c.json({ error: `not found: ${file.path}` }, 404);
         }
@@ -2763,7 +2857,7 @@ function registerFileRoutes(api, adapter) {
         prepared.push(folded);
       }
       for (const file of prepared) {
-        const current = readFileSync5(file.absPath, "utf-8");
+        const current = readFileSync6(file.absPath, "utf-8");
         if (current !== file.before) {
           return c.json(
             {
@@ -2805,7 +2899,7 @@ function registerFileRoutes(api, adapter) {
         const conflicts = [];
         for (const file of written.reverse()) {
           try {
-            const current = readFileSync5(file.absPath, "utf-8");
+            const current = readFileSync6(file.absPath, "utf-8");
             if (current !== file.after) {
               conflicts.push(file.path);
               continue;
@@ -2853,7 +2947,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 = readFileSync5(ctx.absPath, "utf-8");
+      originalContent = readFileSync6(ctx.absPath, "utf-8");
     } catch {
       return c.json({ error: "not found" }, 404);
     }
@@ -2909,7 +3003,7 @@ function registerFileRoutes(api, adapter) {
     }
     let originalContent;
     try {
-      originalContent = readFileSync5(ctx.absPath, "utf-8");
+      originalContent = readFileSync6(ctx.absPath, "utf-8");
     } catch {
       return c.json({ error: "not found" }, 404);
     }
@@ -3010,7 +3104,7 @@ function registerFileRoutes(api, adapter) {
     }
     let originalContent;
     try {
-      originalContent = readFileSync5(ctx.absPath, "utf-8");
+      originalContent = readFileSync6(ctx.absPath, "utf-8");
     } catch {
       return c.json({ error: "not found" }, 404);
     }
@@ -3065,7 +3159,7 @@ function registerFileRoutes(api, adapter) {
     ).map((entry) => ({ target: entry.target, track: entry.track }));
     let originalContent;
     try {
-      originalContent = readFileSync5(ctx.absPath, "utf-8");
+      originalContent = readFileSync6(ctx.absPath, "utf-8");
     } catch {
       return c.json({ error: "not found" }, 404);
     }
@@ -3094,7 +3188,7 @@ function registerFileRoutes(api, adapter) {
     if ("error" in parsed) return parsed.error;
     let content;
     try {
-      content = readFileSync5(ctx.absPath, "utf-8");
+      content = readFileSync6(ctx.absPath, "utf-8");
     } catch {
       return c.json({ exists: false });
     }
@@ -3137,7 +3231,7 @@ function registerFileRoutes(api, adapter) {
       return c.json({ error: "forbidden" }, 403);
     }
     ensureDir(destAbs);
-    writeFileSync4(destAbs, readFileSync5(srcAbs));
+    writeFileSync5(destAbs, readFileSync6(srcAbs));
     return c.json({ ok: true, path: copyPath }, 201);
   });
   const MAX_UPLOAD_BYTES = 500 * 1024 * 1024;
@@ -3153,7 +3247,7 @@ function registerFileRoutes(api, adapter) {
       const subDir = c.req.query("dir") ?? "";
       const targetDir = subDir ? resolveWithinProject(project.dir, subDir) : project.dir;
       if (!targetDir) return c.json({ error: "forbidden" }, 403);
-      if (subDir && !existsSync3(targetDir)) mkdirSync3(targetDir, { recursive: true });
+      if (subDir && !existsSync3(targetDir)) mkdirSync4(targetDir, { recursive: true });
       const formData = await c.req.formData();
       const result = await processUploadedFiles(formData, targetDir, project.dir);
       return c.json(
@@ -3167,7 +3261,7 @@ function registerFileRoutes(api, adapter) {
       mustExist: true
     });
     if ("error" in res) return res.error;
-    const html = readFileSync5(res.absPath, "utf-8");
+    const html = readFileSync6(res.absPath, "utf-8");
     const block = extractGsapScriptBlock(html);
     if (!block) {
       return c.json({
@@ -3216,7 +3310,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 = readFileSync5(res.absPath, "utf-8");
+    const current = readFileSync6(res.absPath, "utf-8");
     if (current !== body.expected) {
       return c.json({ ok: true, restored: false, conflict: true });
     }
@@ -3226,19 +3320,20 @@ function registerFileRoutes(api, adapter) {
 }
 
 // src/routes/preview.ts
-import { createReadStream, existsSync as existsSync5, readFileSync as readFileSync8, statSync as statSync5 } from "fs";
+import { createReadStream, existsSync as existsSync5, readFileSync as readFileSync8, statSync as statSync4 } from "fs";
 import { Readable } from "stream";
-import { join as join8, resolve as resolve4 } from "path";
-import { createHash as createHash3 } from "crypto";
+import { join as join9, resolve as resolve4 } from "path";
+import { createHash as createHash4 } from "crypto";
 import {
   injectScriptsIntoHtml,
+  insertBeforeCloseTag as insertBeforeCloseTag2,
   stripEmbeddedRuntimeScripts as stripEmbeddedRuntimeScripts2
 } from "@hyperframes/core/compiler";
 import { isWithinProjectRoot } from "@hyperframes/parsers/asset-resolution";
 
 // src/helpers/subComposition.ts
-import { existsSync as existsSync4, readFileSync as readFileSync6 } from "fs";
-import { join as join7 } from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync7 } from "fs";
+import { join as join8 } from "path";
 import { parseHTML as parseHTML3 } from "linkedom";
 import {
   rewriteAssetPaths,
@@ -3250,7 +3345,7 @@ function isFullHtmlDocument(html) {
   return /^\s*(?:<!doctype\s|<html[\s>])/i.test(html);
 }
 function rewriteRelativePaths(root, compPath, projectDir) {
-  const assetExists = (path) => existsSync4(join7(projectDir, path));
+  const assetExists = (path) => existsSync4(join8(projectDir, path));
   rewriteAssetPaths(
     root.querySelectorAll("[src], [href]"),
     compPath,
@@ -3347,9 +3442,9 @@ function tagRootCompositionFile(bodyHtml, compPath) {
   return bodyHtml.slice(0, tagEnd) + ` data-composition-file="${compPath}"` + bodyHtml.slice(tagEnd);
 }
 function buildSubCompositionHtml(projectDir, compPath, runtimeUrl, baseHref, rawOverride) {
-  const compFile = join7(projectDir, compPath);
+  const compFile = join8(projectDir, compPath);
   if (!existsSync4(compFile)) return null;
-  const rawComp = rawOverride ?? readFileSync6(compFile, "utf-8");
+  const rawComp = rawOverride ?? readFileSync7(compFile, "utf-8");
   let compHeadContent = "";
   let rewrittenContent;
   let htmlAttrs = "";
@@ -3379,10 +3474,10 @@ function buildSubCompositionHtml(projectDir, compPath, runtimeUrl, baseHref, raw
   }
   rewrittenContent = stripEmbeddedRuntimeScripts(rewrittenContent);
   rewrittenContent = tagRootCompositionFile(rewrittenContent, compPath);
-  const indexPath = join7(projectDir, "index.html");
+  const indexPath = join8(projectDir, "index.html");
   let headContent = "";
   if (existsSync4(indexPath)) {
-    const indexHtml = readFileSync6(indexPath, "utf-8");
+    const indexHtml = readFileSync7(indexPath, "utf-8");
     const headMatch = indexHtml.match(/<head[^>]*>([\s\S]*?)<\/head>/i);
     headContent = headMatch?.[1] ?? "";
   }
@@ -3419,63 +3514,7 @@ function hasBaseElement(html) {
 }
 
 // src/routes/preview.ts
-import { ensureHfIds as ensureHfIds2 } from "@hyperframes/parsers/hf-ids";
-
-// src/helpers/hfIdPersist.ts
-import { ensureHfIds } from "@hyperframes/parsers/hf-ids";
-import { closeSync as closeSync2, constants, fstatSync as fstatSync2, openSync as openSync2, readFileSync as readFileSync7, statSync as statSync4 } from "fs";
-function persistHfIdsIfNeeded(filePath, html) {
-  const normalized = ensureHfIds(html);
-  const idsBefore = (html.match(/\bdata-hf-id=/g) ?? []).length;
-  const idsAfter = (normalized.match(/\bdata-hf-id=/g) ?? []).length;
-  if (idsAfter > idsBefore) {
-    try {
-      const current = readFileSync7(filePath, "utf-8");
-      if (current === html) {
-        replaceFileAtomically(filePath, normalized, statSync4(filePath).mode);
-      }
-    } catch (err) {
-      console.warn("[hyperframes] persistHfIdsIfNeeded: failed to write ids to disk:", err);
-    }
-  }
-  return normalized;
-}
-function openNoFollow(filePath, flags) {
-  const noFollow = constants.O_NOFOLLOW ?? 0;
-  try {
-    return openSync2(filePath, flags | noFollow);
-  } catch {
-    return null;
-  }
-}
-function stampFileHfIds(filePath) {
-  let fd = openNoFollow(filePath, constants.O_RDWR);
-  let writable = true;
-  if (fd === null) {
-    fd = openNoFollow(filePath, constants.O_RDONLY);
-    writable = false;
-  }
-  if (fd === null) return null;
-  try {
-    if (!fstatSync2(fd).isFile()) return null;
-    const html = readFileSync7(fd, "utf-8");
-    const normalized = ensureHfIds(html);
-    const idsBefore = (html.match(/\bdata-hf-id=/g) ?? []).length;
-    const idsAfter = (normalized.match(/\bdata-hf-id=/g) ?? []).length;
-    if (writable && idsAfter > idsBefore) {
-      const mode = fstatSync2(fd).mode;
-      closeSync2(fd);
-      fd = null;
-      replaceFileAtomically(filePath, normalized, mode);
-    }
-    return normalized;
-  } catch (err) {
-    console.warn("[hyperframes] stampFileHfIds: failed to stamp ids:", err);
-    return null;
-  } finally {
-    if (fd !== null) closeSync2(fd);
-  }
-}
+import { ensureHfIds as ensureHfIds3 } from "@hyperframes/parsers/hf-ids";
 
 // src/helpers/variablesPayload.ts
 var VARIABLES_PAYLOAD_ERROR = "variables must be a JSON object of {variableId: value}";
@@ -3513,13 +3552,12 @@ function injectProjectSignature(html, signature) {
       tag
     );
   }
-  if (html.includes("</head>")) return html.replace("</head>", `${tag}
-</head>`);
-  return `${tag}
+  return insertBeforeCloseTag2(html, "head", `${tag}
+`) ?? `${tag}
 ${html}`;
 }
 function readStudioMotionManifestContent(projectDir) {
-  const manifestPath = join8(projectDir, STUDIO_MOTION_PATH);
+  const manifestPath = join9(projectDir, STUDIO_MOTION_PATH);
   if (!existsSync5(manifestPath)) return "";
   try {
     return readFileSync8(manifestPath, "utf-8");
@@ -3540,9 +3578,8 @@ function parseStudioMotionManifestContent(content) {
   }
 }
 function injectScriptTagIntoHead(html, scriptTag) {
-  if (html.includes("</head>")) return html.replace("</head>", `${scriptTag}
-</head>`);
-  return `${scriptTag}
+  return insertBeforeCloseTag2(html, "head", `${scriptTag}
+`) ?? `${scriptTag}
 ${html}`;
 }
 function htmlHasGsap(html) {
@@ -3633,7 +3670,7 @@ function parsePreviewVariablesParam(raw) {
 }
 function variablesEtagSalt(raw) {
   if (!raw) return "";
-  return `:vars:${createHash3("sha1").update(raw).digest("hex").slice(0, 12)}`;
+  return `:vars:${createHash4("sha1").update(raw).digest("hex").slice(0, 12)}`;
 }
 function previewVariablesFromRequest(rawVariables) {
   const parse = parsePreviewVariablesParam(rawVariables);
@@ -3665,14 +3702,14 @@ async function transformPreviewHtml(html, adapter, project, activeCompositionPat
   }
 }
 function resolveProjectMainHtml(projectDir, projectId) {
-  const indexPath = join8(projectDir, "index.html");
+  const indexPath = join9(projectDir, "index.html");
   if (existsSync5(indexPath)) {
     return {
       html: readFileSync8(indexPath, "utf-8"),
       compositionPath: "index.html"
     };
   }
-  const blockHtmlPath = join8(projectDir, `${projectId}.html`);
+  const blockHtmlPath = join9(projectDir, `${projectId}.html`);
   if (existsSync5(blockHtmlPath)) {
     return {
       html: readFileSync8(blockHtmlPath, "utf-8"),
@@ -3683,7 +3720,8 @@ function resolveProjectMainHtml(projectDir, projectId) {
 }
 var PREVIEW_BUNDLE_OPTIONS = {
   runtime: "placeholder",
-  inlineAssets: false
+  inlineAssets: false,
+  staticGuard: false
 };
 function registerPreviewRoutes(api, adapter) {
   const previewCacheHeaders = (etag) => ({
@@ -3691,35 +3729,28 @@ function registerPreviewRoutes(api, adapter) {
     ETag: etag
   });
   const mediaCodecProbeCache = resolvePreviewMediaCodecProbeCache(adapter);
-  api.get("/projects/:id/preview", async (c) => {
-    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 etag = `"preview:${signature}${variablesEtagSalt(vars.raw)}"`;
-    const ifNoneMatch = c.req.header("If-None-Match");
-    if (ifNoneMatch === etag) {
-      return new Response(null, {
-        status: 304,
-        headers: previewCacheHeaders(etag)
-      });
-    }
+  const builtPreviews = /* @__PURE__ */ new Map();
+  const rememberPreview = (key, html) => {
+    builtPreviews.delete(key);
+    builtPreviews.set(key, html);
+    if (builtPreviews.size > 4) builtPreviews.delete(builtPreviews.keys().next().value);
+  };
+  const previewBuilds = /* @__PURE__ */ new Map();
+  async function buildPreview(project, previewVariables, builtKey) {
     const diskMain = resolveProjectMainHtml(project.dir, project.id);
-    const normalizedDisk = diskMain ? persistHfIdsIfNeeded(join8(project.dir, diskMain.compositionPath), diskMain.html) : null;
+    const normalizedDisk = diskMain ? ensureHfIds3(diskMain.html) : null;
     try {
-      let bundled = await adapter.bundle(project.dir);
+      let bundled = await adapter.bundle(project.dir, { stampHfIds: true });
       let mainCompositionPath = "index.html";
       if (!bundled) {
-        if (!diskMain) return c.text("not found", 404);
+        if (!diskMain) return null;
         bundled = stripEmbeddedRuntimeScripts2(normalizedDisk ?? diskMain.html);
         mainCompositionPath = diskMain.compositionPath;
       }
       if (!bundled.includes("hyperframe.runtime") && !bundled.includes("hyperframes-preview-runtime")) {
         const runtimeTag = `<script src="${adapter.runtimeUrl}"></script>`;
-        bundled = bundled.includes("</body>") ? bundled.replace("</body>", `${runtimeTag}
-</body>`) : bundled + `
+        bundled = insertBeforeCloseTag2(bundled, "body", `${runtimeTag}
+`) ?? `${bundled}
 ${runtimeTag}`;
       }
       const baseHref = `/api/projects/${project.id}/preview/`;
@@ -3727,7 +3758,7 @@ ${runtimeTag}`;
         bundled = bundled.replace(/<head>/i, `<head><base href="${baseHref}">`);
       }
       bundled = injectStudioPreviewAugmentations(
-        ensureHfIds2(await transformPreviewHtml(bundled, adapter, project, mainCompositionPath)),
+        ensureHfIds3(await transformPreviewHtml(bundled, adapter, project, mainCompositionPath)),
         adapter,
         project.dir,
         mainCompositionPath
@@ -3740,14 +3771,13 @@ ${runtimeTag}`;
         mainCompositionPath,
         mediaCodecProbeCache
       );
-      return c.html(bundled, 200, previewCacheHeaders(etag));
+      rememberPreview(builtKey, bundled);
+      adapter.previewDocuments?.write(builtKey, bundled);
+      return bundled;
     } catch {
       const fallback = resolveProjectMainHtml(project.dir, project.id);
       if (fallback) {
-        const fallbackHtml = persistHfIdsIfNeeded(
-          join8(project.dir, fallback.compositionPath),
-          fallback.html
-        );
+        const fallbackHtml = ensureHfIds3(fallback.html);
         let fallbackAugmented = injectStudioPreviewAugmentations(
           await transformPreviewHtml(fallbackHtml, adapter, project, fallback.compositionPath),
           adapter,
@@ -3764,14 +3794,51 @@ ${runtimeTag}`;
           fallback.compositionPath,
           mediaCodecProbeCache
         );
-        return c.html(fallbackAugmented, 200, previewCacheHeaders(etag));
+        return fallbackAugmented;
       }
-      return c.text("not found", 404);
+      return null;
+    }
+  }
+  api.get("/projects/:id/preview", async (c) => {
+    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 etag = `"preview:${signature}${variablesEtagSalt(vars.raw)}"`;
+    const ifNoneMatch = c.req.header("If-None-Match");
+    if (ifNoneMatch === etag) {
+      return new Response(null, {
+        status: 304,
+        headers: previewCacheHeaders(etag)
+      });
     }
+    const builtKey = `${project.id}
+${etag}`;
+    const cached = builtPreviews.get(builtKey) ?? adapter.previewDocuments?.read(builtKey);
+    if (cached) {
+      rememberPreview(builtKey, cached);
+      return c.html(cached, 200, previewCacheHeaders(etag));
+    }
+    let pending = previewBuilds.get(builtKey);
+    if (!pending) {
+      pending = buildPreview(project, previewVariables, builtKey).finally(
+        () => previewBuilds.delete(builtKey)
+      );
+      previewBuilds.set(builtKey, pending);
+    }
+    const html = await pending;
+    if (!html) return c.text("not found", 404);
+    return c.html(html, 200, previewCacheHeaders(etag));
   });
   function pinSubCompHfIds(compFile, compPath) {
     if (!/\.html?$/i.test(compPath)) return void 0;
-    return stampFileHfIds(compFile);
+    try {
+      return ensureHfIds3(readFileSync8(compFile, "utf-8"));
+    } catch {
+      return null;
+    }
   }
   api.get("/projects/:id/preview/comp/*", async (c) => {
     const resolved = await resolveProjectAndSignature(adapter, c.req.param("id"));
@@ -3782,10 +3849,10 @@ ${runtimeTag}`;
     const previewVariables = vars.values;
     const compPath = requestSubPath(c.req.url, "projects/:id/preview/comp");
     const compFile = resolveWithinProject(project.dir, compPath);
-    if (!compFile || !existsSync5(compFile) || !statSync5(compFile).isFile()) {
+    if (!compFile || !existsSync5(compFile) || !statSync4(compFile).isFile()) {
       return c.text("not found", 404);
     }
-    const compPathHash = createHash3("sha1").update(compPath).digest("hex");
+    const compPathHash = createHash4("sha1").update(compPath).digest("hex");
     const etag = `"comp:v2:${compPathHash}:${signature}${variablesEtagSalt(vars.raw)}"`;
     const ifNoneMatch = c.req.header("If-None-Match");
     if (ifNoneMatch === etag) {
@@ -3805,7 +3872,7 @@ ${runtimeTag}`;
       stamped
     );
     if (!html) return c.text("not found", 404);
-    html = ensureHfIds2(await transformPreviewHtml(html, adapter, project, compPath));
+    html = ensureHfIds3(await transformPreviewHtml(html, adapter, project, compPath));
     html = injectStudioPreviewAugmentations(html, adapter, project.dir, compPath);
     if (previewVariables) html = injectPreviewVariables(html, previewVariables);
     html = await injectMediaCodecMap(html, adapter, project.dir, compPath, mediaCodecProbeCache);
@@ -3820,7 +3887,7 @@ ${runtimeTag}`;
     if (!file) {
       return c.text("not found", 404);
     }
-    const stat2 = existsSync5(file) ? statSync5(file) : null;
+    const stat2 = existsSync5(file) ? statSync4(file) : null;
     if (!stat2?.isFile()) {
       return c.text("not found", 404);
     }
@@ -3868,7 +3935,7 @@ ${runtimeTag}`;
       servedContentType = PROXY_VARIANT_CONFIG[proxyVariant].contentType;
     }
     const textBuffer = isText ? Buffer.from(readFileSync8(file, "utf-8"), "utf-8") : null;
-    const totalSize = textBuffer ? textBuffer.length : statSync5(servedPath).size;
+    const totalSize = textBuffer ? textBuffer.length : statSync4(servedPath).size;
     const bodyFor = (start, end) => textBuffer ? new Uint8Array(textBuffer.subarray(start, end + 1)) : (
       // Node's web stream type and the DOM one do not overlap for tsc on
       // every platform's lib set; the double cast is the documented bridge.
@@ -3912,7 +3979,7 @@ ${runtimeTag}`;
 
 // src/routes/lint.ts
 import { readFileSync as readFileSync9 } from "fs";
-import { join as join9 } from "path";
+import { join as join10 } from "path";
 async function collectProjectFindings(adapter, projectDir) {
   const findings = [];
   const coveredFiles = /* @__PURE__ */ new Set();
@@ -3930,7 +3997,7 @@ async function lintUncoveredHtml(adapter, projectDir, htmlFiles, coveredFiles) {
   const findings = [];
   for (const file of htmlFiles) {
     if (coveredFiles.has(file)) continue;
-    const content = readFileSync9(join9(projectDir, file), "utf-8");
+    const content = readFileSync9(join10(projectDir, file), "utf-8");
     const result = await adapter.lint(content, { filePath: file, isSubComposition: true });
     for (const finding of result?.findings ?? []) {
       findings.push({ ...finding, file });
@@ -3963,8 +4030,8 @@ function registerLintRoutes(api, adapter) {
 
 // src/routes/render.ts
 import { streamSSE } from "hono/streaming";
-import { existsSync as existsSync6, readFileSync as readFileSync10, mkdirSync as mkdirSync4, unlinkSync as unlinkSync3, readdirSync as readdirSync5, statSync as statSync6 } from "fs";
-import { join as join10 } from "path";
+import { existsSync as existsSync6, readFileSync as readFileSync10, mkdirSync as mkdirSync5, unlinkSync as unlinkSync3, readdirSync as readdirSync5, statSync as statSync5 } from "fs";
+import { join as join11 } from "path";
 import { VALID_CANVAS_RESOLUTIONS } from "@hyperframes/parsers";
 import { formatRenderOutputTimestamp, parseFps } from "@hyperframes/core";
 var VALID_RESOLUTIONS = new Set(VALID_CANVAS_RESOLUTIONS);
@@ -4030,9 +4097,9 @@ function registerRenderRoutes(api, adapter) {
     const now = /* @__PURE__ */ new Date();
     const jobId = `${project.id}_${formatRenderOutputTimestamp(now)}`;
     const rendersDir = adapter.rendersDir(project);
-    if (!existsSync6(rendersDir)) mkdirSync4(rendersDir, { recursive: true });
+    if (!existsSync6(rendersDir)) mkdirSync5(rendersDir, { recursive: true });
     const ext = FORMAT_EXT[format] ?? ".mp4";
-    const outputPath = join10(rendersDir, `${jobId}${ext}`);
+    const outputPath = join11(rendersDir, `${jobId}${ext}`);
     const jobState = adapter.startRender({
       project,
       outputPath,
@@ -4133,7 +4200,7 @@ function registerRenderRoutes(api, adapter) {
       if (state.id === jobId && state.outputPath) {
         const dir = state.outputPath.replace(/\/[^/]+$/, "");
         for (const ext of [".mp4", ".webm", ".mov", ".meta.json"]) {
-          const fp = join10(dir, `${jobId}${ext}`);
+          const fp = join11(dir, `${jobId}${ext}`);
           if (existsSync6(fp)) unlinkSync3(fp);
         }
         break;
@@ -4168,10 +4235,10 @@ function registerRenderRoutes(api, adapter) {
     const rendersDir = adapter.rendersDir(project);
     if (!existsSync6(rendersDir)) return c.json({ renders: [] });
     const files = readdirSync5(rendersDir).filter((f) => f.endsWith(".mp4") || f.endsWith(".webm") || f.endsWith(".mov")).map((f) => {
-      const fp = join10(rendersDir, f);
-      const stat2 = statSync6(fp);
+      const fp = join11(rendersDir, f);
+      const stat2 = statSync5(fp);
       const rid = f.replace(/\.(mp4|webm|mov)$/, "");
-      const metaPath = join10(rendersDir, `${rid}.meta.json`);
+      const metaPath = join11(rendersDir, `${rid}.meta.json`);
       let status = "complete";
       let durationMs;
       if (existsSync6(metaPath)) {
@@ -4197,7 +4264,7 @@ function registerRenderRoutes(api, adapter) {
           id: file.id,
           status: file.status,
           progress: 100,
-          outputPath: join10(rendersDir, file.filename),
+          outputPath: join11(rendersDir, file.filename),
           createdAt: file.createdAt
         });
       }
@@ -4212,17 +4279,17 @@ import {
   existsSync as existsSync7,
   fstatSync as fstatSync3,
   openSync as openSync3,
-  mkdirSync as mkdirSync5,
+  mkdirSync as mkdirSync6,
   readFileSync as readFileSync12,
   readdirSync as readdirSync6,
   renameSync as renameSync3,
   rmSync as rmSync4,
-  statSync as statSync7,
+  statSync as statSync6,
   unlinkSync as unlinkSync4,
-  writeFileSync as writeFileSync5
+  writeFileSync as writeFileSync6
 } from "fs";
-import { join as join11 } from "path";
-import { createHash as createHash4, randomUUID as randomUUID4 } from "crypto";
+import { join as join12 } from "path";
+import { createHash as createHash5, randomUUID as randomUUID4 } from "crypto";
 
 // src/helpers/compositionInputs.ts
 import { readFileSync as readFileSync11 } from "fs";
@@ -4395,9 +4462,9 @@ function pruneThumbnailCache(cacheDir, protectedPaths, now = Date.now()) {
   if (!existsSync7(cacheDir)) return;
   const files = readdirSync6(cacheDir, { withFileTypes: true }).flatMap((entry) => {
     if (!entry.isFile()) return [];
-    const path = join11(cacheDir, entry.name);
+    const path = join12(cacheDir, entry.name);
     try {
-      const stats = statSync7(path);
+      const stats = statSync6(path);
       return [{ path, bytes: stats.size, mtimeMs: stats.mtimeMs }];
     } catch {
       return [];
@@ -4425,7 +4492,7 @@ function pruneThumbnailCache(cacheDir, protectedPaths, now = Date.now()) {
 function writeThumbnailAtomically(path, buffer) {
   const temporaryPath = `${path}.${process.pid}.${randomUUID4()}.tmp`;
   try {
-    writeFileSync5(temporaryPath, buffer, { flag: "wx" });
+    writeFileSync6(temporaryPath, buffer, { flag: "wx" });
     renameSync3(temporaryPath, path);
   } finally {
     rmSync4(temporaryPath, { force: true });
@@ -4481,7 +4548,7 @@ function registerThumbnailRoutes(api, adapter) {
     let sourceKey = "";
     if (source !== "missing") {
       const { html } = source;
-      sourceKey = `_${createHash4("sha1").update(html).digest("hex").slice(0, 16)}`;
+      sourceKey = `_${createHash5("sha1").update(html).digest("hex").slice(0, 16)}`;
       sourceMtime = Math.round(source.mtimeMs);
       if (!vpWidth) {
         const wMatch = html.match(/data-width=["'](\d+)["']/);
@@ -4490,31 +4557,31 @@ function registerThumbnailRoutes(api, adapter) {
         if (hMatch?.[1]) compH = parseInt(hMatch[1]);
       }
     }
-    const manualEditsFile = join11(project.dir, STUDIO_MANUAL_EDITS_PATH);
+    const manualEditsFile = join12(project.dir, STUDIO_MANUAL_EDITS_PATH);
     let manualEditsKey = "";
     if (existsSync7(manualEditsFile)) {
       const manualEditsContent = readFileSync12(manualEditsFile, "utf-8");
-      manualEditsKey = `_${createHash4("sha1").update(manualEditsContent).digest("hex").slice(0, 16)}`;
-      sourceMtime = Math.max(sourceMtime, Math.round(statSync7(manualEditsFile).mtimeMs));
+      manualEditsKey = `_${createHash5("sha1").update(manualEditsContent).digest("hex").slice(0, 16)}`;
+      sourceMtime = Math.max(sourceMtime, Math.round(statSync6(manualEditsFile).mtimeMs));
     }
-    const motionFile = join11(project.dir, STUDIO_MOTION_PATH);
+    const motionFile = join12(project.dir, STUDIO_MOTION_PATH);
     let motionKey = "";
     if (existsSync7(motionFile)) {
       const motionContent = readFileSync12(motionFile, "utf-8");
-      motionKey = `_${createHash4("sha1").update(motionContent).digest("hex").slice(0, 16)}`;
-      sourceMtime = Math.max(sourceMtime, Math.round(statSync7(motionFile).mtimeMs));
+      motionKey = `_${createHash5("sha1").update(motionContent).digest("hex").slice(0, 16)}`;
+      sourceMtime = Math.max(sourceMtime, Math.round(statSync6(motionFile).mtimeMs));
     }
     const projectUrl = `http://${c.req.header("host")}/api/projects/${encodeURIComponent(project.id)}`;
     const previewUrl = compPath === "index.html" ? `${projectUrl}/preview` : `${projectUrl}/preview/comp/${compPath.split("/").map(encodeURIComponent).join("/")}`;
-    const cacheDir = join11(project.dir, ".thumbnails");
+    const cacheDir = join12(project.dir, ".thumbnails");
     const selectorKey = selector ? `_${selector.replace(/[^a-zA-Z0-9_-]+/g, "_").slice(0, 80)}_${selectorIndex ?? 0}` : "";
     const urlVersionKey = urlVersion ? `_${urlVersion.replace(/[^a-zA-Z0-9_-]+/g, "_").slice(0, 32)}` : "";
-    const inputSignatureKey = `_${createHash4("sha1").update(inputSignature).digest("hex").slice(0, 16)}`;
+    const inputSignatureKey = `_${createHash5("sha1").update(inputSignature).digest("hex").slice(0, 16)}`;
     const outputScale = outputMode === "source" ? 1 : Math.min(1, THUMBNAIL_MAX_OUTPUT_WIDTH / compW, THUMBNAIL_MAX_OUTPUT_HEIGHT / compH);
     const outputWidth = Math.max(1, Math.round(compW * outputScale));
     const outputHeight = Math.max(1, Math.round(compH * outputScale));
     const cacheKey = `${THUMBNAIL_CACHE_VERSION}${urlVersionKey}${inputSignatureKey}${manualEditsKey}${motionKey}${sourceKey}_${format}_${outputMode}_${compPath.replace(/\//g, "_")}_${compW}x${compH}_${outputWidth}x${outputHeight}_${sourceMtime}_${seekTime.toFixed(2)}${selectorKey}.${format === "png" ? "png" : "jpg"}`;
-    const cachePath = join11(cacheDir, cacheKey);
+    const cachePath = join12(cacheDir, cacheKey);
     if (!prunedCacheDirs.has(cacheDir)) {
       prunedCacheDirs.add(cacheDir);
       pruneThumbnailCache(
@@ -4527,6 +4594,7 @@ function registerThumbnailRoutes(api, adapter) {
         headers: { "Content-Type": contentType, "Cache-Control": "no-cache" }
       });
     }
+    if (url.searchParams.get("cached") === "1") return c.body(null, 404);
     try {
       const buffer = await thumbnailGenerationCoordinator.acquire(
         cachePath,
@@ -4552,7 +4620,7 @@ function registerThumbnailRoutes(api, adapter) {
           if (afterGeneration?.project.dir !== project.dir || !inputsUnchanged(afterGeneration.signature) || !inputsUnchanged(createProjectSignature(project.dir))) {
             return generated;
           }
-          if (!existsSync7(cacheDir)) mkdirSync5(cacheDir, { recursive: true });
+          if (!existsSync7(cacheDir)) mkdirSync6(cacheDir, { recursive: true });
           writeThumbnailAtomically(cachePath, generated);
           return generated;
         }
@@ -4578,8 +4646,8 @@ function registerThumbnailRoutes(api, adapter) {
 }
 
 // src/routes/waveform.ts
-import { existsSync as existsSync8, readFileSync as readFileSync13, statSync as statSync8 } from "fs";
-import { join as join12, resolve as resolve5 } from "path";
+import { existsSync as existsSync8, readFileSync as readFileSync13, statSync as statSync7 } from "fs";
+import { join as join13, resolve as resolve5 } from "path";
 import { isWithinProjectRoot as isWithinProjectRoot2 } from "@hyperframes/parsers/asset-resolution";
 function registerWaveformRoutes(api, adapter) {
   api.get("/projects/:id/waveform/*", async (c) => {
@@ -4590,10 +4658,10 @@ function registerWaveformRoutes(api, adapter) {
     if (!isWithinProjectRoot2(project.dir, audioPath)) {
       return c.json({ error: "file not found" }, 404);
     }
-    const stats = statSync8(audioPath, { throwIfNoEntry: false });
+    const stats = statSync7(audioPath, { throwIfNoEntry: false });
     if (!stats) return c.json({ error: "file not found" }, 404);
-    const cacheDir = join12(project.dir, ".waveform-cache");
-    const cachePath = join12(cacheDir, buildWaveformCacheKey(assetPath, stats));
+    const cacheDir = join13(project.dir, ".waveform-cache");
+    const cachePath = join13(cacheDir, buildWaveformCacheKey(assetPath, stats));
     try {
       if (isWaveformCacheDirectory(cacheDir) && existsSync8(cachePath)) {
         const peaks2 = JSON.parse(readFileSync13(cachePath, "utf-8"));
@@ -4879,8 +4947,8 @@ function registerSelectionRoutes(api, adapter) {
 
 // src/routes/media.ts
 import { streamSSE as streamSSE2 } from "hono/streaming";
-import { existsSync as existsSync9, mkdirSync as mkdirSync6 } from "fs";
-import { basename as basename2, dirname as dirname4, extname as extname2, join as join13 } from "path";
+import { existsSync as existsSync9, mkdirSync as mkdirSync7 } from "fs";
+import { basename as basename2, dirname as dirname5, extname as extname2, join as join14 } from "path";
 var VIDEO_EXTENSIONS = /* @__PURE__ */ new Set([
   ".mp4",
   ".mov",
@@ -4917,7 +4985,7 @@ function uniqueAssetPath(projectDir, assetPath) {
   const ext = extname2(assetPath);
   const withoutExt = assetPath.slice(0, -ext.length);
   let candidate = assetPath;
-  for (let index = 2; existsSync9(join13(projectDir, candidate)); index++) {
+  for (let index = 2; existsSync9(join14(projectDir, candidate)); index++) {
     candidate = `${withoutExt}-${index}${ext}`;
   }
   return candidate;
@@ -5024,8 +5092,8 @@ function registerMediaRoutes(api, adapter, options = {}) {
           return c.json({ error: "forbidden" }, 403);
         }
       }
-      mkdirSync6(dirname4(outputPath), { recursive: true });
-      if (backgroundOutputPath) mkdirSync6(dirname4(backgroundOutputPath), { recursive: true });
+      mkdirSync7(dirname5(outputPath), { recursive: true });
+      if (backgroundOutputPath) mkdirSync7(dirname5(backgroundOutputPath), { recursive: true });
       const jobId = makeJobId(project.id, mediaJobs);
       const state = adapter.startBackgroundRemoval({
         project,
@@ -5084,9 +5152,9 @@ function registerMediaRoutes(api, adapter, options = {}) {
 // src/routes/globalAssets.ts
 import { existsSync as existsSync10, readFileSync as readFileSync14 } from "fs";
 import { homedir } from "os";
-import { join as join14 } from "path";
+import { join as join15 } from "path";
 function readGlobalAssets(home = homedir()) {
-  const manifestPath = join14(home, ".media", "manifest.jsonl");
+  const manifestPath = join15(home, ".media", "manifest.jsonl");
   if (!existsSync10(manifestPath)) return [];
   const out = [];
   for (const line of readFileSync14(manifestPath, "utf8").split("\n")) {
@@ -5106,117 +5174,6 @@ function registerGlobalAssetRoutes(api) {
   api.get("/assets/global", (c) => c.json({ assets: readGlobalAssets().map(toPublicAsset) }));
 }
 
-// src/history/historyLog.ts
-import { closeSync as closeSync5, constants as constants3, mkdirSync as mkdirSync7, openSync as openSync5, readFileSync as readFileSync15, writeSync as writeSync2 } from "fs";
-import { dirname as dirname5 } from "path";
-var START = "start";
-function parseRecord(line) {
-  try {
-    return JSON.parse(line);
-  } catch {
-    return null;
-  }
-}
-function readLog(file, onUnreadable) {
-  let text2;
-  try {
-    text2 = readFileSync15(file, "utf-8");
-  } catch {
-    return null;
-  }
-  const log = { baseline: /* @__PURE__ */ new Map(), entries: [], pins: /* @__PURE__ */ new Set() };
-  const lines = text2.split("\n");
-  lines.forEach((line, index) => {
-    const record = line ? parseRecord(line) : null;
-    if (record) applyRecord(log, record);
-    else if (line && index < lines.length - 1) onUnreadable(index + 1);
-  });
-  return log;
-}
-function applyRecord(log, record) {
-  if (record.type === "baseline") log.baseline = new Map(Object.entries(record.files));
-  else if (record.type === "entry") log.entries.push(record.entry);
-  else if (record.pinned) log.pins.add(record.id);
-  else log.pins.delete(record.id);
-}
-function saveRecord(file, log, record) {
-  let fd;
-  try {
-    fd = openSync5(file, constants3.O_WRONLY | constants3.O_APPEND);
-  } catch (error) {
-    if (error.code !== "ENOENT") throw error;
-    return writeLog(file, log);
-  }
-  try {
-    writeSync2(fd, `${JSON.stringify(record)}
-`);
-  } finally {
-    closeSync5(fd);
-  }
-}
-function writeLog(file, log) {
-  const records = [
-    { type: "baseline", files: Object.fromEntries(log.baseline) },
-    ...log.entries.map((entry) => ({ type: "entry", entry })),
-    ...[...log.pins].map((id) => ({ type: "pin", id, pinned: true }))
-  ];
-  mkdirSync7(dirname5(file), { recursive: true });
-  replaceFileAtomically(file, records.map((r) => `${JSON.stringify(r)}
-`).join(""), 420);
-}
-function applyEntry(manifest, entry) {
-  for (const file of entry.files)
-    if (file.after === null) manifest.delete(file.path);
-    else manifest.set(file.path, file.after);
-}
-function manifestAt(log, point) {
-  const manifest = new Map(log.baseline);
-  if (point === START) return manifest;
-  for (const entry of log.entries) {
-    applyEntry(manifest, entry);
-    if (entry.id === point) return manifest;
-  }
-  return null;
-}
-function undoneIds(entries) {
-  const undone = /* @__PURE__ */ new Set();
-  for (let i = entries.length - 1; i >= 0; i -= 1) {
-    const entry = entries[i];
-    if (entry.undoes && !undone.has(entry.id)) undone.add(entry.undoes);
-  }
-  return undone;
-}
-function stepTarget(entries, direction) {
-  const undone = undoneIds(entries);
-  const byId = new Map(entries.map((entry) => [entry.id, entry]));
-  for (let i = entries.length - 1; i >= 0; i -= 1) {
-    const entry = entries[i];
-    const isChange = !entry.undoes;
-    if (direction === "back" && isChange && !undone.has(entry.id)) return entry;
-    if (direction !== "forward") continue;
-    if (isChange) return void 0;
-    const target = byId.get(entry.undoes);
-    if (!undone.has(entry.id) && target && !target.undoes) return entry;
-  }
-  return void 0;
-}
-function foldOldest(log) {
-  const oldest = log.entries[0];
-  if (!oldest || log.pins.has(oldest.id)) return false;
-  applyEntry(log.baseline, oldest);
-  log.entries.shift();
-  return true;
-}
-function referencedHashes(log, current) {
-  const keep = /* @__PURE__ */ new Set([...log.baseline.values(), ...current.values()]);
-  for (const entry of log.entries)
-    for (const file of entry.files) {
-      if (file.before) keep.add(file.before);
-      if (file.after) keep.add(file.after);
-    }
-  return keep;
-}
-
 // src/routes/history.ts
 var YOU = { kind: "person", name: "You" };
 var MAX_WINDOW_IDLE_MS = 10 * 6e4;
@@ -5229,12 +5186,23 @@ async function bodyOf(c) {
   return body && typeof body === "object" ? body : {};
 }
 var text = (value) => typeof value === "string" && value ? value : null;
+function writing(c) {
+  const header = c.req.header("X-Hyperframes-Write-Token");
+  return header ? { writeToken: createWriteToken(header) } : {};
+}
 function idleOf(body) {
   const idleMs = body.idleMs;
   return typeof idleMs === "number" && idleMs > 0 ? Math.min(idleMs, MAX_WINDOW_IDLE_MS) : void 0;
 }
-function nextStep(entries, direction) {
-  const target = stepTarget(entries, direction);
+function versionsOf(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const pairs = Object.entries(value).filter(
+    (pair) => typeof pair[1] === "string"
+  );
+  return pairs.length ? Object.fromEntries(pairs) : void 0;
+}
+function nextStep(history, direction) {
+  const target = history.next(direction);
   if (!target) return null;
   const paths = target.files.map((file) => file.path);
   return { id: target.id, label: target.label, endedAt: target.endedAt, paths };
@@ -5255,7 +5223,7 @@ function registerHistoryRoutes(api, adapter) {
     base,
     (c) => withHistory(adapter, c, (history) => {
       const entries = history.list();
-      return { entries, back: nextStep(entries, "back"), forward: nextStep(entries, "forward") };
+      return { entries, back: nextStep(history, "back"), forward: nextStep(history, "forward") };
     })
   );
   api.post(
@@ -5263,19 +5231,23 @@ function registerHistoryRoutes(api, adapter) {
     (c) => withHistory(
       adapter,
       c,
-      (history, body) => history.step(body.direction === "forward" ? "forward" : "back", YOU)
+      (history, body) => history.step(body.direction === "forward" ? "forward" : "back", YOU, writing(c))
     )
   );
   api.post(
     `${base}/undo`,
     (c) => withHistory(adapter, c, (history, body) => {
       const mode = body.mode === "just-this" || body.mode === "back-to-before" ? body.mode : void 0;
-      return history.undo(text(body.entryId) ?? "", { who: YOU, mode });
+      return history.undo(text(body.entryId) ?? "", { who: YOU, mode, ...writing(c) });
     })
   );
   api.post(
     `${base}/restore`,
-    (c) => withHistory(adapter, c, (history, body) => history.restore(text(body.point) ?? "", YOU))
+    (c) => withHistory(
+      adapter,
+      c,
+      (history, body) => history.restore(text(body.point) ?? "", YOU, writing(c))
+    )
   );
   api.get(
     `${base}/peek/:point`,
@@ -5294,9 +5266,11 @@ function registerHistoryRoutes(api, adapter) {
       const paths = Array.isArray(body.paths) ? body.paths.filter((path) => text(path)) : [];
       const coalesceKey = text(body.coalesceKey) ?? void 0;
       const idleMs = idleOf(body);
+      const overwrote = versionsOf(body.overwrote);
       const claimed = await history.claim(YOU, text(body.label) ?? "Edited in Studio", paths, {
         ...coalesceKey && { coalesceKey },
-        ...idleMs && { idleMs }
+        ...idleMs && { idleMs },
+        ...overwrote && { overwrote }
       });
       return { claimed };
     })
@@ -5346,18 +5320,20 @@ function createStudioApi(adapter) {
 }
 
 // src/history/projectHistory.ts
-import { randomUUID as randomUUID7 } from "crypto";
+import { randomUUID as randomUUID8 } from "crypto";
 import { rm as rm2 } from "fs/promises";
-import { existsSync as existsSync12, mkdirSync as mkdirSync9, readFileSync as readFileSync17 } from "fs";
-import { join as join17, relative as relative4, resolve as resolve7, sep as sep3 } from "path";
+import { existsSync as existsSync12, mkdirSync as mkdirSync11, readFileSync as readFileSync18 } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join19, relative as relative4, resolve as resolve7, sep as sep3 } from "path";
 
 // src/history/blobStore.ts
-import { createHash as createHash5, randomUUID as randomUUID5 } from "crypto";
-import { constants as constants4, createReadStream as createReadStream2 } from "fs";
+import { createHash as createHash6, randomUUID as randomUUID5 } from "crypto";
+import { constants as constants3, createReadStream as createReadStream2 } from "fs";
 import { copyFile, mkdir, readdir, readFile as readFile2, rename, rm, stat } from "fs/promises";
-import { dirname as dirname6, join as join15 } from "path";
+import { dirname as dirname6, join as join16 } from "path";
+var BLOB_HASH = /^[0-9a-f]{64}$/;
 async function hashFile(path) {
-  const hash = createHash5("sha256");
+  const hash = createHash6("sha256");
   for await (const chunk of createReadStream2(path)) hash.update(chunk);
   return hash.digest("hex");
 }
@@ -5365,7 +5341,7 @@ async function cloneOrCopy(from, to) {
   await mkdir(dirname6(to), { recursive: true });
   const temp = `${to}.${randomUUID5()}.tmp`;
   try {
-    await copyFile(from, temp, constants4.COPYFILE_FICLONE);
+    await copyFile(from, temp, constants3.COPYFILE_FICLONE);
     await rename(temp, to);
   } catch (error) {
     await rm(temp, { force: true });
@@ -5376,15 +5352,18 @@ async function openBlobStore(dir) {
   const sizes = /* @__PURE__ */ new Map();
   await mkdir(dir, { recursive: true });
   for (const shard of await readdir(dir))
-    for (const hash of await readdir(join15(dir, shard)).catch(() => []))
-      sizes.set(hash, (await stat(join15(dir, shard, hash))).size);
-  const pathOf = (hash) => join15(dir, hash.slice(0, 2), hash);
+    for (const hash of await readdir(join16(dir, shard)).catch(() => []))
+      sizes.set(hash, (await stat(join16(dir, shard, hash))).size);
+  const pathOf = (hash) => {
+    if (!BLOB_HASH.test(hash)) throw new Error("That is not a history blob.");
+    return join16(dir, hash.slice(0, 2), hash);
+  };
   let total = [...sizes.values()].reduce((sum, size) => sum + size, 0);
   return {
     async put(absPath) {
-      const temp = join15(dir, `incoming-${randomUUID5()}`);
+      const temp = join16(dir, `incoming-${randomUUID5()}`);
       await mkdir(dir, { recursive: true });
-      await copyFile(absPath, temp, constants4.COPYFILE_FICLONE);
+      await copyFile(absPath, temp, constants3.COPYFILE_FICLONE);
       const hash = await hashFile(temp);
       if (sizes.has(hash)) {
         await rm(temp, { force: true });
@@ -5397,8 +5376,9 @@ async function openBlobStore(dir) {
       total += size;
       return hash;
     },
-    read: (hash) => readFile2(pathOf(hash)),
-    writeTo: (hash, absPath) => cloneOrCopy(pathOf(hash), absPath),
+    has: (hash) => sizes.has(hash),
+    read: async (hash) => readFile2(pathOf(hash)),
+    writeTo: async (hash, absPath) => cloneOrCopy(pathOf(hash), absPath),
     bytes: () => total,
     size: (hash) => sizes.get(hash) ?? 0,
     async prune(keep) {
@@ -5414,13 +5394,13 @@ async function openBlobStore(dir) {
 
 // src/history/historyId.ts
 import { randomUUID as randomUUID6 } from "crypto";
-import { existsSync as existsSync11, mkdirSync as mkdirSync8, readFileSync as readFileSync16, writeFileSync as writeFileSync6 } from "fs";
-import { join as join16, resolve as resolve6 } from "path";
-var ID_PATH = join16(".hyperframes", "history-id");
+import { existsSync as existsSync11, mkdirSync as mkdirSync8, readFileSync as readFileSync15, writeFileSync as writeFileSync7 } from "fs";
+import { join as join17, resolve as resolve6 } from "path";
+var ID_PATH = join17(".hyperframes", "history-id");
 var ID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 function readId(projectDir) {
   try {
-    const id = readFileSync16(join16(projectDir, ID_PATH), "utf-8").trim();
+    const id = readFileSync15(join17(projectDir, ID_PATH), "utf-8").trim();
     return ID_SHAPE.test(id) ? id : null;
   } catch {
     return null;
@@ -5428,7 +5408,7 @@ function readId(projectDir) {
 }
 function recordedDir(historyDir) {
   try {
-    return JSON.parse(readFileSync16(join16(historyDir, "project.json"), "utf-8")).dir ?? null;
+    return JSON.parse(readFileSync15(join17(historyDir, "project.json"), "utf-8")).dir ?? null;
   } catch {
     return null;
   }
@@ -5436,23 +5416,225 @@ function recordedDir(historyDir) {
 function projectHistoryId(projectDir, historyRoot) {
   const dir = resolve6(projectDir);
   let id = readId(dir);
-  const was = id && recordedDir(join16(historyRoot, id));
+  const was = id && recordedDir(join17(historyRoot, id));
   if (!id || was && was !== dir && existsSync11(was) && readId(was) === id) {
     id = randomUUID6();
-    mkdirSync8(join16(dir, ".hyperframes"), { recursive: true });
-    writeFileSync6(join16(dir, ID_PATH), `${id}
+    mkdirSync8(join17(dir, ".hyperframes"), { recursive: true });
+    writeFileSync7(join17(dir, ID_PATH), `${id}
 `);
   }
-  mkdirSync8(join16(historyRoot, id), { recursive: true });
-  writeFileSync6(join16(historyRoot, id, "project.json"), JSON.stringify({ dir }));
+  mkdirSync8(join17(historyRoot, id), { recursive: true });
+  writeFileSync7(join17(historyRoot, id, "project.json"), JSON.stringify({ dir }));
   return id;
 }
 
+// src/history/ownerLock.ts
+import { randomUUID as randomUUID7 } from "crypto";
+import { linkSync, mkdirSync as mkdirSync9, readFileSync as readFileSync16, rmSync as rmSync5, writeFileSync as writeFileSync8 } from "fs";
+import { join as join18 } from "path";
+var HistoryBusyError = class extends Error {
+  constructor(pid) {
+    super(`This project's history is open in another process (pid ${pid}).`);
+    this.pid = pid;
+    this.name = "HistoryBusyError";
+  }
+  pid;
+};
+function alive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+function ownerOf(file) {
+  try {
+    const text2 = readFileSync16(file, "utf-8");
+    return /^\d+$/.test(text2) ? Number(text2) : Number.NaN;
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+function claim(file) {
+  const draft = `${file}-${randomUUID7()}.tmp`;
+  writeFileSync8(draft, String(process.pid));
+  try {
+    linkSync(draft, file);
+    return true;
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    return false;
+  } finally {
+    rmSync5(draft, { force: true });
+  }
+}
+function releaseOwn(file) {
+  if (ownerOf(file) === process.pid) rmSync5(file, { force: true });
+}
+function evictDeadOwner(file) {
+  const evictor = `${file}.evict`;
+  if (!claim(evictor)) {
+    const holder = ownerOf(evictor);
+    if (holder !== null && !alive(holder)) rmSync5(evictor, { force: true });
+    return false;
+  }
+  try {
+    const pid = ownerOf(file);
+    if (pid !== null && !alive(pid)) rmSync5(file, { force: true });
+    return true;
+  } finally {
+    releaseOwn(evictor);
+  }
+}
+async function takeHistoryOwnership(home, waitMs) {
+  const file = join18(home, "owner.pid");
+  const deadline = Date.now() + waitMs;
+  mkdirSync9(home, { recursive: true });
+  for (; ; ) {
+    if (claim(file)) {
+      let held = true;
+      return () => {
+        if (held) releaseOwn(file);
+        held = false;
+      };
+    }
+    const pid = ownerOf(file);
+    if (pid === null) continue;
+    if (!alive(pid) && evictDeadOwner(file)) continue;
+    if (Date.now() >= deadline) throw new HistoryBusyError(pid);
+    await new Promise((settle) => setTimeout(settle, 50));
+  }
+}
+
+// src/history/historyLog.ts
+import { closeSync as closeSync5, constants as constants4, mkdirSync as mkdirSync10, openSync as openSync5, readFileSync as readFileSync17, writeSync as writeSync2 } from "fs";
+import { dirname as dirname7 } from "path";
+var START = "start";
+function parseRecord(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+function readLog(file, onUnreadable) {
+  let text2;
+  try {
+    text2 = readFileSync17(file, "utf-8");
+  } catch {
+    return null;
+  }
+  const log = { baseline: /* @__PURE__ */ new Map(), entries: [], pins: /* @__PURE__ */ new Set() };
+  const lines = text2.split("\n");
+  lines.forEach((line, index) => {
+    const record = line ? parseRecord(line) : null;
+    if (record) applyRecord(log, record);
+    else if (line && index < lines.length - 1) onUnreadable(index + 1);
+  });
+  return log;
+}
+function applyRecord(log, record) {
+  if (record.type === "baseline") log.baseline = new Map(Object.entries(record.files));
+  else if (record.type === "entry") log.entries.push(record.entry);
+  else if (record.pinned) log.pins.add(record.id);
+  else log.pins.delete(record.id);
+}
+function saveRecord(file, log, record) {
+  let fd;
+  try {
+    fd = openSync5(file, constants4.O_WRONLY | constants4.O_APPEND);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    return writeLog(file, log);
+  }
+  try {
+    writeSync2(fd, `${JSON.stringify(record)}
+`);
+  } finally {
+    closeSync5(fd);
+  }
+}
+function writeLog(file, log) {
+  const records = [
+    { type: "baseline", files: Object.fromEntries(log.baseline) },
+    ...log.entries.map((entry) => ({ type: "entry", entry })),
+    ...[...log.pins].map((id) => ({ type: "pin", id, pinned: true }))
+  ];
+  mkdirSync10(dirname7(file), { recursive: true });
+  replaceFileAtomically(file, records.map((r) => `${JSON.stringify(r)}
+`).join(""), 420);
+}
+function applyEntry(manifest, entry) {
+  for (const file of entry.files)
+    if (file.after === null) manifest.delete(file.path);
+    else manifest.set(file.path, file.after);
+}
+function manifestAt(log, point) {
+  const manifest = new Map(log.baseline);
+  if (point === START) return manifest;
+  for (const entry of log.entries) {
+    applyEntry(manifest, entry);
+    if (entry.id === point) return manifest;
+  }
+  return null;
+}
+function undoneIds(entries) {
+  const undone = /* @__PURE__ */ new Set();
+  for (let i = entries.length - 1; i >= 0; i -= 1) {
+    const entry = entries[i];
+    if (entry.undoes && !undone.has(entry.id)) undone.add(entry.undoes);
+  }
+  return undone;
+}
+function stepTarget(entries, direction) {
+  const undone = undoneIds(entries);
+  const byId = new Map(entries.map((entry) => [entry.id, entry]));
+  for (let i = entries.length - 1; i >= 0; i -= 1) {
+    const entry = entries[i];
+    const isChange = !entry.undoes;
+    if (direction === "back" && isChange && !undone.has(entry.id)) return entry;
+    if (direction !== "forward") continue;
+    if (isChange) return void 0;
+    const target = byId.get(entry.undoes);
+    if (!undone.has(entry.id) && target && !target.undoes) return entry;
+  }
+  return void 0;
+}
+function foldOldest(log) {
+  const oldest = log.entries[0];
+  if (!oldest || log.pins.has(oldest.id)) return false;
+  applyEntry(log.baseline, oldest);
+  log.entries.shift();
+  return true;
+}
+function referencedHashes(log, current) {
+  const keep = /* @__PURE__ */ new Set([...log.baseline.values(), ...current.values()]);
+  for (const entry of log.entries)
+    for (const file of entry.files) {
+      if (file.before) keep.add(file.before);
+      if (file.after) keep.add(file.after);
+    }
+  return keep;
+}
+
 // src/history/projectHistory.ts
+var DEFAULT_HISTORY_ROOT = join19(homedir2(), ".cache", "hyperframes", "history");
 var OUTSIDE = { kind: "outside", name: "Outside" };
 var OUTSIDE_LABEL = "Changed outside the app";
 var RACY_MS = 2e3;
 var statKey = (file, sweptAt) => sweptAt - Math.max(file.mtimeMs, file.ctimeMs) < RACY_MS ? "" : `${file.size}:${file.mtimeMs}:${file.ctimeMs}`;
+var sameWho = (a, b) => a.kind === b.kind && a.name === b.name;
+function splitAt(change, at, kept) {
+  if (at === change.after) return [change, null];
+  if (!at || at === change.before || !kept) return [null, change];
+  return [
+    { ...change, after: at },
+    { ...change, before: at }
+  ];
+}
 function addChange(group, path, before, after) {
   const earlier = group.changes.get(path);
   const from = earlier ? earlier.before : before;
@@ -5465,7 +5647,7 @@ var Engine = class {
     this.projectId = projectId;
     this.blobs = blobs;
     this.dir = resolve7(options.projectDir);
-    this.home = join17(options.historyRoot, projectId);
+    this.home = join19(options.historyRoot, projectId);
   }
   options;
   projectId;
@@ -5478,13 +5660,14 @@ var Engine = class {
   outside = null;
   /** A coalescing claim, open until another key, its idle timer, or an operation commits it. */
   claimed = null;
+  writeToken;
   quietTimer;
   maxTimer;
   notedTimer = null;
   listeners = /* @__PURE__ */ new Set();
   tail = Promise.resolve();
   get logFile() {
-    return join17(this.home, "log.jsonl");
+    return join19(this.home, "log.jsonl");
   }
   now() {
     return (this.options.now ?? Date.now)();
@@ -5517,7 +5700,7 @@ var Engine = class {
     const sweptAt = Date.now();
     for (const file of listProjectFiles(this.dir))
       this.tracked.set(file.path, {
-        hash: await this.blobs.put(join17(this.dir, file.path)),
+        hash: await this.blobs.put(join19(this.dir, file.path)),
         stat: statKey(file, sweptAt)
       });
     this.log.baseline = this.manifest();
@@ -5529,7 +5712,7 @@ var Engine = class {
   }
   readStatCache() {
     try {
-      const files = JSON.parse(readFileSync17(join17(this.home, "stat.json"), "utf-8"));
+      const files = JSON.parse(readFileSync18(join19(this.home, "stat.json"), "utf-8"));
       return new Map(Object.entries(files));
     } catch {
       return /* @__PURE__ */ new Map();
@@ -5537,8 +5720,8 @@ var Engine = class {
   }
   saveStatCache() {
     const files = JSON.stringify(Object.fromEntries(this.tracked));
-    mkdirSync9(this.home, { recursive: true });
-    replaceFileAtomically(join17(this.home, "stat.json"), files, 420);
+    mkdirSync11(this.home, { recursive: true });
+    replaceFileAtomically(join19(this.home, "stat.json"), files, 420);
   }
   /**
    * Takes in every write since the last sweep and files each change to its writer. ponytail: always the whole
@@ -5563,7 +5746,7 @@ var Engine = class {
   /** The file's hash once copied in; null when it was removed before the copy (the next sweep records that). */
   async storeIfPresent(path) {
     try {
-      return await this.blobs.put(join17(this.dir, path));
+      return await this.blobs.put(join19(this.dir, path));
     } catch (error) {
       if (error.code === "ENOENT") return null;
       throw error;
@@ -5583,37 +5766,80 @@ var Engine = class {
     if (window) this.touch(window);
     addChange(window ?? this.outsideGroup(), path, before, after);
   }
-  /**
-   * ponytail: a claim takes every uncommitted outside change to its paths, so another writer's write to the same file
-   * between Studio's write and its claim (milliseconds) folds into Studio's entry. Per-write tokens would split them.
-   * A write filed to another writer's open window stays that window's.
-   */
-  async claimNow(who, label, paths, { coalesceKey, idleMs }) {
+  /** ponytail: another's write between Studio's write and its sweep folds into Studio's entry (per-write tokens). */
+  async claimNow(who, label, paths, { coalesceKey, idleMs, overwrote = {} }) {
     await this.sweep();
-    const taken = this.takeOutside(paths);
-    if (!taken.length) return null;
-    const group = await this.claimGroup(who, label, coalesceKey);
+    const { taken, cut } = this.takeClaimed(who, paths, overwrote);
+    if (!taken.length) {
+      if (coalesceKey !== this.claimed?.key) await this.commitClaim();
+      return null;
+    }
+    const held = this.heldFor(coalesceKey, taken);
+    if (!held) await this.commitClaim();
+    await this.commitOlder(cut);
+    const group = held ?? this.newGroup(who, label);
     for (const change of taken) addChange(group, change.path, change.before, change.after);
     if (coalesceKey) return this.holdClaim(group, coalesceKey, idleMs);
     const entry = await this.commit(group);
     return entry && { id: entry.id };
   }
-  /** The held claim when the key matches; otherwise it is committed and a new group starts. */
-  async claimGroup(who, label, key) {
-    if (key && this.claimed?.key === key) return this.claimed.group;
-    await this.commitClaim();
-    return this.newGroup(who, label);
-  }
-  /** Removes and returns the uncommitted outside changes to `paths` (project-relative or absolute). */
-  takeOutside(paths) {
-    const outside = this.outside;
-    if (!outside) return [];
-    const wanted = new Set(
-      paths.map((path) => relative4(this.dir, resolve7(this.dir, path)).split(sep3).join("/"))
+  async commitOlder(cut) {
+    if (this.outside) cut.delete(this.outside);
+    await this.commitOutside();
+    for (const [window, paths] of cut) await this.commitCut(window, paths);
+  }
+  /** The held claim `taken` continues: same key, each file from its own last change, no held file changed since. */
+  heldFor(key, taken) {
+    const group = key && this.claimed?.key === key ? this.claimed.group : null;
+    const after = (path, before) => {
+      const own = group?.changes.get(path);
+      return own ? own.after : before;
+    };
+    const takenPaths = new Set(taken.map((change) => change.path));
+    const untouched = (change) => takenPaths.has(change.path) || (this.tracked.get(change.path)?.hash ?? null) === change.after;
+    return group && taken.every((change) => after(change.path, change.before) === change.before) && [...group.changes.values()].every(untouched) ? group : null;
+  }
+  logPath(path) {
+    return relative4(this.dir, resolve7(this.dir, path)).split(sep3).join("/");
+  }
+  /** Takes `paths`' uncommitted changes from others, cut at what `who` overwrote; `cut`: paths each group keeps. */
+  takeClaimed(who, paths, overwrote) {
+    const wanted = new Set(paths.map((path) => this.logPath(path)));
+    const at = new Map(
+      Object.entries(overwrote).map(([path, version]) => [
+        this.logPath(path),
+        hashOfVersion(version)
+      ])
     );
-    const taken = [...outside.changes.values()].filter((change) => wanted.has(change.path));
-    for (const change of taken) outside.changes.delete(change.path);
-    return taken;
+    const others = this.windows.filter((open) => !sameWho(open.who, who));
+    const groups = this.outside ? [this.outside, ...others] : others;
+    const taken = [];
+    const cut = /* @__PURE__ */ new Map();
+    for (const group of groups) {
+      for (const change of [...group.changes.values()]) {
+        if (!wanted.has(change.path)) continue;
+        const [kept, claimed] = this.cutOut(group, change, at.get(change.path));
+        if (claimed) taken.push(claimed);
+        if (kept && claimed) cut.set(group, [...cut.get(group) ?? [], change.path]);
+      }
+    }
+    return { taken, cut };
+  }
+  cutOut(group, change, cut) {
+    const [kept, claimed] = splitAt(change, cut, cut !== void 0 && this.blobs.has(cut));
+    group.changes.delete(change.path);
+    if (kept) group.changes.set(kept.path, kept);
+    return [kept, claimed];
+  }
+  /** Commits the window's cut `paths` as their own entry, other files staying: a window holds one change per file,
+   * so the writer's next write to a cut file would otherwise span the claimer's edit. */
+  async commitCut(window, paths) {
+    const part = { ...this.newGroup(window.who, window.label), startedAt: window.startedAt };
+    for (const path of paths) {
+      part.changes.set(path, window.changes.get(path));
+      window.changes.delete(path);
+    }
+    window.entry = await this.commit(part);
   }
   holdClaim(group, key, idleMs = this.options.quietMs ?? 2e3) {
     clearTimeout(this.claimed?.timer);
@@ -5645,7 +5871,7 @@ var Engine = class {
     return this.outside;
   }
   newGroup(who, label) {
-    return { id: randomUUID7(), who, label, startedAt: this.now(), changes: /* @__PURE__ */ new Map() };
+    return { id: randomUUID8(), who, label, startedAt: this.now(), changes: /* @__PURE__ */ new Map() };
   }
   async commitOutside() {
     clearTimeout(this.quietTimer);
@@ -5656,9 +5882,9 @@ var Engine = class {
   }
   async commit(group, extra = {}) {
     if (!group.changes.size) return null;
-    const { changes, ...rest } = group;
+    const { id, who, label, startedAt, changes } = group;
     const files = [...changes.values()].sort((a, b) => a.path.localeCompare(b.path));
-    const entry = { ...rest, endedAt: this.now(), files, ...extra };
+    const entry = { id, who, label, startedAt, endedAt: this.now(), files, ...extra };
     this.log.entries.push(entry);
     try {
       saveRecord(this.logFile, this.log, { type: "entry", entry });
@@ -5732,7 +5958,7 @@ var Engine = class {
     if (!this.windows.includes(window)) return window.entry ?? null;
     clearTimeout(window.idleTimer);
     this.windows = this.windows.filter((open) => open !== window);
-    window.entry = await this.commit(window);
+    window.entry = await this.commit(window) ?? window.entry ?? null;
     return window.entry;
   }
   /** Every pending write, open window and outside group, committed: for flush and close. */
@@ -5748,9 +5974,8 @@ var Engine = class {
     this.windows.push(group);
     try {
       for (const [path, hash] of target) {
-        if ((this.tracked.get(path)?.hash ?? null) === hash) continue;
-        if (hash === null) await rm2(join17(this.dir, path), { force: true });
-        else await this.blobs.writeTo(hash, join17(this.dir, path));
+        if ((this.tracked.get(path)?.hash ?? null) !== hash)
+          await this.writeProjectFile(path, hash);
       }
       await this.sweep();
     } finally {
@@ -5758,6 +5983,17 @@ var Engine = class {
     }
     return this.commit(group, extra);
   }
+  /** Writes one project file (null deletes it), first leaving the running operation's receipt for its echo. */
+  async writeProjectFile(path, hash) {
+    const absPath = join19(this.dir, path);
+    const { writeToken } = this;
+    if (writeToken) {
+      const version = hash === null ? DELETED_VERSION : hashVersion(hash);
+      recordFileWriteReceipt(absPath, { path, version, writeToken });
+    }
+    if (hash === null) await rm2(absPath, { force: true });
+    else await this.blobs.writeTo(hash, absPath);
+  }
   entry(id) {
     const entry = this.log.entries.find((candidate) => candidate.id === id);
     if (!entry) throw new Error("That change is no longer kept in this project's history.");
@@ -5770,9 +6006,7 @@ var Engine = class {
   }
   async undoNow(id, who, mode) {
     const entry = this.entry(id);
-    const changed = entry.files.filter(
-      (file) => (this.tracked.get(file.path)?.hash ?? null) !== file.after
-    );
+    const changed = this.movedOn(entry);
     if (changed.length && !mode) return { ok: false, conflict: this.conflict(entry, changed) };
     if (mode === "back-to-before") {
       const index = this.log.entries.indexOf(entry);
@@ -5788,6 +6022,19 @@ var Engine = class {
       entry: await this.writeAs(who, this.undoLabel(entry), target, { undoes: id })
     };
   }
+  movedOn(entry) {
+    return entry.files.filter((file) => (this.tracked.get(file.path)?.hash ?? null) !== file.after);
+  }
+  /** Back reverts the newest change in effect, unless its files moved on under an earlier-ending edit (a held drag
+   * committed after an agent's turn): then that edit, if it still applies. */
+  next(direction) {
+    const top = stepTarget(this.log.entries, direction);
+    const moved = new Set(top && direction === "back" ? this.movedOn(top).map((f) => f.path) : []);
+    if (!top || !moved.size) return top;
+    const undone = undoneIds(this.log.entries);
+    const under = this.log.entries.slice(0, this.log.entries.indexOf(top)).reverse().find((e) => !e.undoes && !undone.has(e.id) && e.files.some((f) => moved.has(f.path)));
+    return under && !this.movedOn(under).length ? under : top;
+  }
   conflict(entry, changed) {
     const paths = new Set(changed.map((file) => file.path));
     const after = this.log.entries.slice(this.log.entries.indexOf(entry) + 1);
@@ -5803,6 +6050,18 @@ var Engine = class {
     for (const [path, hash] of files) target.set(path, hash);
     return this.writeAs(who, label, target, { restoredTo: point });
   }
+  /** Settles, then runs `task` with its writes labelled `writeToken`. */
+  operation(writeToken, task) {
+    return this.queue(async () => {
+      await this.settle();
+      this.writeToken = writeToken;
+      try {
+        return await task();
+      } finally {
+        this.writeToken = void 0;
+      }
+    });
+  }
   pointLabel(point) {
     return point === START ? "the start" : this.entry(point).label;
   }
@@ -5820,23 +6079,20 @@ var Engine = class {
           undone: undone.has(entry.id)
         }));
       },
-      step: (direction, who) => this.queue(async () => {
-        await this.settle();
-        const target = stepTarget(this.log.entries, direction);
+      step: (direction, who, { writeToken } = {}) => this.operation(writeToken, async () => {
+        const target = this.next(direction);
         return target ? this.undoNow(target.id, who) : { ok: true, entry: null };
       }),
-      undo: (id, { who, mode }) => this.queue(async () => {
-        await this.settle();
-        return this.undoNow(id, who, mode);
-      }),
-      restore: (point, who) => this.queue(async () => {
-        await this.settle();
-        return this.restoreNow(point, who, `Restored: ${this.pointLabel(point)}`);
-      }),
+      undo: (id, { who, mode, writeToken }) => this.operation(writeToken, () => this.undoNow(id, who, mode)),
+      restore: (point, who, { writeToken } = {}) => this.operation(
+        writeToken,
+        () => this.restoreNow(point, who, `Restored: ${this.pointLabel(point)}`)
+      ),
       peek: (point) => {
         const files = manifestAt(this.log, point);
         return files && Object.fromEntries(files);
       },
+      next: (direction) => this.next(direction),
       readBlob: (hash) => this.blobs.read(hash),
       pin: (id, pinned) => {
         this.entry(id);
@@ -5858,14 +6114,27 @@ var Engine = class {
 };
 async function openProjectHistory(options) {
   const projectId = projectHistoryId(options.projectDir, options.historyRoot);
-  const blobs = await openBlobStore(join17(options.historyRoot, projectId, "blobs"));
-  const engine = new Engine(options, projectId, blobs);
-  await engine.queue(() => engine.start());
-  return engine.api();
+  const release = await takeHistoryOwnership(
+    join19(options.historyRoot, projectId),
+    options.ownerWaitMs ?? 5e3
+  );
+  try {
+    const blobs = await openBlobStore(join19(options.historyRoot, projectId, "blobs"));
+    const engine = new Engine(options, projectId, blobs);
+    await engine.queue(() => engine.start());
+    const api = engine.api();
+    return {
+      ...api,
+      close: () => api.close().finally(release)
+    };
+  } catch (error) {
+    release();
+    throw error;
+  }
 }
 
 // src/helpers/duplicateElement.ts
-import { ensureHfIds as ensureHfIds3 } from "@hyperframes/parsers/hf-ids";
+import { ensureHfIds as ensureHfIds4 } from "@hyperframes/parsers/hf-ids";
 function duplicateElementInHtml(source, target, newId, at) {
   const { document, wrappedFragment } = parseSourceDocument(source);
   const element = findTargetElement(document, target);
@@ -5885,7 +6154,7 @@ function duplicateElementInHtml(source, target, newId, at) {
   clone.setAttribute("data-start", String(at));
   element.parentElement.insertBefore(clone, element.nextSibling);
   const html = wrappedFragment ? document.body.innerHTML || "" : document.toString();
-  return { html: ensureHfIds3(html), matched: true, newId: uniqueId };
+  return { html: ensureHfIds4(html), matched: true, newId: uniqueId };
 }
 function nextUniqueId(document, newId) {
   let uniqueId = newId;
@@ -5915,6 +6184,35 @@ function numericAttribute(element, name) {
   return Number.isFinite(value) ? value : null;
 }
 
+// src/helpers/previewDocumentStore.ts
+import { createHash as createHash7 } from "crypto";
+import { mkdirSync as mkdirSync12, readFileSync as readFileSync19, readdirSync as readdirSync7, rmSync as rmSync6 } from "fs";
+import { join as join20 } from "path";
+function createPreviewDocumentStore(dir, salt) {
+  const fileFor = (key) => join20(dir, `${createHash7("sha256").update(`${salt}
+${key}`).digest("hex").slice(0, 32)}.html`);
+  return {
+    read(key) {
+      try {
+        return readFileSync19(fileFor(key), "utf-8");
+      } catch {
+        return null;
+      }
+    },
+    write(key, html) {
+      try {
+        mkdirSync12(dir, { recursive: true });
+        const file = fileFor(key);
+        replaceFileAtomically(file, html, 420);
+        for (const name of readdirSync7(dir)) {
+          if (join20(dir, name) !== file) rmSync6(join20(dir, name), { force: true });
+        }
+      } catch {
+      }
+    }
+  };
+}
+
 // src/helpers/thumbnailOutput.ts
 function thumbnailDeviceScaleFactor({
   width,
@@ -5983,7 +6281,10 @@ function updateBackgroundRemovalProgress(state, event) {
   state.avgMsPerFrame = event.avgMsPerFrame;
 }
 export {
+  DEFAULT_HISTORY_ROOT,
+  DELETED_VERSION,
   START as HISTORY_START,
+  HistoryBusyError,
   MIME_TYPES,
   PREVIEW_BUNDLE_OPTIONS,
   STUDIO_MANUAL_EDITS_PATH,
@@ -5994,6 +6295,7 @@ export {
   compositionsAffectedBy,
   consumeFileWriteReceipt,
   createBackgroundRemovalJob,
+  createPreviewDocumentStore,
   createProjectSignature,
   createStudioApi,
   createStudioManualEditsRenderBodyScript,
@@ -6014,6 +6316,7 @@ export {
   requestSubPath,
   settledFileTag,
   splitElementInHtml,
+  stampProjectHfIds,
   thumbnailDeviceScaleFactor,
   walkDir
 };