npm - @hyperframes/studio-server - Versions diffs - 0.8.78 → 0.8.80 - Mend

@hyperframes/studio-server 0.8.78 → 0.8.80

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/dist/{chunk-45POWYFS.js → chunk-56JREE33.js} +2 -2
package/dist/{chunk-4MNTZVVZ.js → chunk-KOB22VPG.js} +14 -10
package/dist/chunk-KOB22VPG.js.map +1 -0
package/dist/{chunk-QYDRVMJ6.js → chunk-P5EJPIH3.js} +5 -3
package/dist/chunk-P5EJPIH3.js.map +1 -0
package/dist/{chunk-X3T65KC2.js → chunk-YGANSFUU.js} +3 -3
package/dist/helpers/mediaCodecMap.d.ts +7 -7
package/dist/helpers/mediaCodecMap.js +1 -1
package/dist/helpers/mediaProxyPreview.d.ts +1 -1
package/dist/helpers/mediaProxyPreview.js +3 -3
package/dist/helpers/proxyTranscoder.js +2 -2
package/dist/helpers/sourceMutation.js +1 -1
package/dist/index.d.ts +17 -4
package/dist/index.js +1024 -483
package/dist/index.js.map +1 -1
package/dist/{mediaProxyPreview-BmJ8AmLd.d.ts → mediaProxyPreview-B7ckRI-l.d.ts} +20 -10
package/package.json +4 -3
package/dist/chunk-4MNTZVVZ.js.map +0 -1
package/dist/chunk-QYDRVMJ6.js.map +0 -1
/package/dist/{chunk-45POWYFS.js.map → chunk-56JREE33.js.map} +0 -0
/package/dist/{chunk-X3T65KC2.js.map → chunk-YGANSFUU.js.map} +0 -0

package/dist/index.js CHANGED Viewed

@@ -13,7 +13,7 @@ import {
   splitElementInHtml,
   unwrapElementsFromHtml,
   wrapElementsInHtml
-} from "./chunk-QYDRVMJ6.js";
+} from "./chunk-P5EJPIH3.js";
 import {
   getElementScreenshotClip
 } from "./chunk-W2SBTCO2.js";
@@ -22,12 +22,12 @@ import {
   isAutoProxyEnabled,
   proxyEtagSalt,
   resolvePreviewMediaCodecProbeCache
-} from "./chunk-X3T65KC2.js";
+} from "./chunk-YGANSFUU.js";
 import {
   ProxyCapacityError,
   ProxyTranscodeError,
   resolveProxy
-} from "./chunk-45POWYFS.js";
+} from "./chunk-56JREE33.js";
 import {
   PROXY_VARIANT_CONFIG,
   decideMediaProxyEligibility,
@@ -36,7 +36,7 @@ import {
   probeMediaMetadata,
   recordProxyRequest,
   resolveProxyVariantRequest
-} from "./chunk-4MNTZVVZ.js";
+} from "./chunk-KOB22VPG.js";
 import {
   STUDIO_MANUAL_EDITS_PATH,
   createStudioManualEditsRenderBodyScript,
@@ -55,9 +55,25 @@ import { readFile } from "fs/promises";
 import { join as join3 } from "path";
 // src/helpers/safePath.ts
-import { join } from "path";
-import { readdirSync } from "fs";
-import { isSafePath, resolveWithinProject } from "@hyperframes/core";
+import { basename, dirname, isAbsolute, join, relative, sep } from "path";
+import { readdirSync, realpathSync } from "fs";
+import { resolveWithinProject } from "@hyperframes/core";
+import { isSafePath, resolveWithinProject as resolveWithinProject2 } from "@hyperframes/core";
+function realFilePath(filePath) {
+  try {
+    return realpathSync(filePath);
+  } catch {
+    const dir = dirname(filePath);
+    return dir === filePath ? filePath : join(realFilePath(dir), basename(filePath));
+  }
+}
+function pinWithinProject(base, relativePath) {
+  const checked = resolveWithinProject(base, relativePath);
+  if (!checked) return null;
+  const inside = relative(realFilePath(base), realFilePath(checked));
+  const escapes = inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside);
+  return escapes ? null : join(base, inside);
+}
 var IGNORE_DIRS = /* @__PURE__ */ new Set([
   ".thumbnails",
   ".transcode-cache",
@@ -107,7 +123,7 @@ import {
   readFileSync,
   writeFileSync
 } from "fs";
-import { dirname, join as join2 } from "path";
+import { dirname as dirname2, join as join2 } from "path";
 // src/helpers/atomicFile.ts
 import * as fs from "fs";
@@ -157,7 +173,7 @@ function stampProjectHfIds(projectDir) {
     next[file] = hash;
   }
   try {
-    mkdirSync(dirname(recordPath), { recursive: true });
+    mkdirSync(dirname2(recordPath), { recursive: true });
     writeFileSync(recordPath, JSON.stringify(next));
   } catch {
   }
@@ -211,7 +227,7 @@ function stampFileHfIds(filePath) {
 // 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";
+import { extname, isAbsolute as isAbsolute2, relative as relative2, resolve, sep as sep2 } from "path";
 var SIGNATURE_TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
   ".cjs",
   ".css",
@@ -246,18 +262,18 @@ var STUDIO_SIGNATURE_MANIFEST_PATHS = [
   ".hyperframes/studio-motion.json"
 ];
 function affectsProjectSignature(projectDir, changedPath) {
-  const relativePath = relative(resolve(projectDir), resolve(changedPath));
-  if (relativePath === "" || relativePath.startsWith("..") || isAbsolute(relativePath)) {
+  const relativePath = relative2(resolve(projectDir), resolve(changedPath));
+  if (relativePath === "" || relativePath.startsWith("..") || isAbsolute2(relativePath)) {
     return false;
   }
-  const segments = relativePath.split(sep);
+  const segments = relativePath.split(sep2);
   if (STUDIO_SIGNATURE_MANIFEST_PATHS.includes(segments.join("/"))) return true;
   return !segments.some((segment) => SIGNATURE_EXCLUDED_DIRS.has(segment));
 }
 var projectSignatureCache = /* @__PURE__ */ new Map();
 function isPathWithin(parentDir, childPath) {
-  const childRelativePath = relative(parentDir, childPath);
-  return childRelativePath === "" || !childRelativePath.startsWith("..") && !isAbsolute(childRelativePath);
+  const childRelativePath = relative2(parentDir, childPath);
+  return childRelativePath === "" || !childRelativePath.startsWith("..") && !isAbsolute2(childRelativePath);
 }
 function isTextContentEligible(file, size) {
   return SIGNATURE_TEXT_EXTENSIONS.has(extname(file).toLowerCase()) && size <= MAX_SIGNATURE_TEXT_BYTES;
@@ -273,22 +289,22 @@ function collectProjectSignatureFiles(projectDir, dir, files) {
     if (SIGNATURE_EXCLUDED_DIRS.has(entry)) continue;
     const file = resolve(dir, entry);
     if (!isPathWithin(projectDir, file)) continue;
-    let stat2;
+    let stat3;
     try {
-      stat2 = lstatSync(file);
+      stat3 = lstatSync(file);
     } catch {
       continue;
     }
-    if (stat2.isSymbolicLink()) continue;
-    if (stat2.isDirectory()) {
+    if (stat3.isSymbolicLink()) continue;
+    if (stat3.isDirectory()) {
       collectProjectSignatureFiles(projectDir, file, files);
-    } else if (stat2.isFile()) {
+    } else if (stat3.isFile()) {
       files.push({
         file,
-        mtimeMs: stat2.mtimeMs,
-        ctimeMs: stat2.ctimeMs,
-        size: stat2.size,
-        textContentEligible: isTextContentEligible(file, stat2.size)
+        mtimeMs: stat3.mtimeMs,
+        ctimeMs: stat3.ctimeMs,
+        size: stat3.size,
+        textContentEligible: isTextContentEligible(file, stat3.size)
       });
     }
   }
@@ -298,19 +314,19 @@ function collectProjectSignatureManifestFiles(projectDir, files) {
   for (const manifestPath of STUDIO_SIGNATURE_MANIFEST_PATHS) {
     const file = resolve(projectDir, manifestPath);
     if (seen.has(file) || !isPathWithin(projectDir, file)) continue;
-    let stat2;
+    let stat3;
     try {
-      stat2 = lstatSync(file);
+      stat3 = lstatSync(file);
     } catch {
       continue;
     }
-    if (stat2.isSymbolicLink() || !stat2.isFile()) continue;
+    if (stat3.isSymbolicLink() || !stat3.isFile()) continue;
     files.push({
       file,
-      mtimeMs: stat2.mtimeMs,
-      ctimeMs: stat2.ctimeMs,
-      size: stat2.size,
-      textContentEligible: isTextContentEligible(file, stat2.size)
+      mtimeMs: stat3.mtimeMs,
+      ctimeMs: stat3.ctimeMs,
+      size: stat3.size,
+      textContentEligible: isTextContentEligible(file, stat3.size)
     });
     seen.add(file);
   }
@@ -318,7 +334,7 @@ function collectProjectSignatureManifestFiles(projectDir, files) {
 function createProjectFingerprint(projectDir, files) {
   const hash = createHash2("sha256");
   for (const entry of files) {
-    hash.update(relative(projectDir, entry.file));
+    hash.update(relative2(projectDir, entry.file));
     hash.update("\0");
     hash.update(String(entry.size));
     hash.update("\0");
@@ -340,7 +356,7 @@ function collectProjectFiles(normalizedProjectDir) {
 function listProjectFiles(projectDir) {
   const normalizedProjectDir = resolve(projectDir);
   return collectProjectFiles(normalizedProjectDir).map((entry) => ({
-    path: relative(normalizedProjectDir, entry.file).split(sep).join("/"),
+    path: relative2(normalizedProjectDir, entry.file).split(sep2).join("/"),
     size: entry.size,
     mtimeMs: entry.mtimeMs,
     ctimeMs: entry.ctimeMs
@@ -358,7 +374,7 @@ function createProjectSignature(projectDir, excluding = /* @__PURE__ */ new Set(
   const normalizedProjectDir = resolve(projectDir);
   const collected = collectProjectFiles(normalizedProjectDir);
   const files = collected.filter(
-    (entry) => !excluding.has(relative(normalizedProjectDir, entry.file).split(sep).join("/"))
+    (entry) => !excluding.has(relative2(normalizedProjectDir, entry.file).split(sep2).join("/"))
   );
   files.sort((a, b) => a.file.localeCompare(b.file));
   const fingerprint = createProjectFingerprint(normalizedProjectDir, files);
@@ -367,7 +383,7 @@ function createProjectSignature(projectDir, excluding = /* @__PURE__ */ new Set(
   if (cached?.fingerprint === fingerprint) return cached.signature;
   const hash = createHash2("sha256");
   for (const entry of files) {
-    const relativePath = relative(normalizedProjectDir, entry.file);
+    const relativePath = relative2(normalizedProjectDir, entry.file);
     hash.update(relativePath);
     hash.update("\0");
     hash.update(String(entry.size));
@@ -450,7 +466,7 @@ import {
   renameSync as renameSync2,
   readdirSync as readdirSync4
 } from "fs";
-import { resolve as resolve3, dirname as dirname4, join as join7 } from "path";
+import { resolve as resolve3, dirname as dirname5, join as join7 } from "path";
 // src/helpers/mime.ts
 var MIME_TYPES = {
@@ -510,7 +526,7 @@ import {
   rmSync,
   statSync
 } from "fs";
-import { dirname as dirname2, join as join4 } from "path";
+import { dirname as dirname3, join as join4 } from "path";
 import { findFfBinary } from "@hyperframes/parsers/ff-binaries";
 var SAMPLE_RATE = 4e3;
 var PEAK_COUNT = 4e3;
@@ -590,7 +606,7 @@ function isWaveformCacheDirectory(cacheDir) {
   return lstatSync2(cacheDir, { throwIfNoEntry: false })?.isDirectory() ?? false;
 }
 function writeWaveformCache(cachePath, peaks) {
-  const cacheDir = dirname2(cachePath);
+  const cacheDir = dirname3(cachePath);
   try {
     mkdirSync2(cacheDir, { mode: 448 });
   } catch (error) {
@@ -616,7 +632,7 @@ function writeWaveformCache(cachePath, peaks) {
 import { spawnSync } from "child_process";
 import { mkdtempSync as mkdtempSync2, rmSync as rmSync2, writeFileSync as writeFileSync3 } from "fs";
 import { tmpdir } from "os";
-import { basename, join as join5 } from "path";
+import { basename as basename2, 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) {
@@ -654,7 +670,7 @@ function validateUploadedMedia(filePath, runner = spawnSync) {
 }
 function validateUploadedMediaBuffer(fileName, buffer, runner = spawnSync) {
   const tempDir = mkdtempSync2(join5(tmpdir(), "hyperframes-upload-"));
-  const tempPath = join5(tempDir, basename(fileName));
+  const tempPath = join5(tempDir, basename2(fileName));
   try {
     writeFileSync3(tempPath, buffer);
     return validateUploadedMedia(tempPath, runner);
@@ -666,7 +682,7 @@ function validateUploadedMediaBuffer(fileName, buffer, runner = spawnSync) {
 // src/helpers/backupJournal.ts
 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 join6, relative as relative2 } from "path";
+import { join as join6, relative as relative3 } from "path";
 var DEFAULT_KEEP_PER_FILE = 10;
 function backupKeyForPath(path) {
   return Buffer2.from(path, "utf-8").toString("base64url");
@@ -676,7 +692,7 @@ function timestampPrefix() {
 }
 function backupPathForResponse(projectDir, backupPath) {
   if (!backupPath) return null;
-  const rel = relative2(projectDir, backupPath);
+  const rel = relative3(projectDir, backupPath);
   if (!rel || rel.startsWith("..")) return null;
   return rel.split("\\").join("/");
 }
@@ -684,7 +700,7 @@ function snapshotBeforeWrite(projectDir, absPath, options = {}) {
   if (!isSafePath(projectDir, absPath)) return { backupPath: null };
   try {
     const content = readFileSync3(absPath);
-    const relativePath = relative2(projectDir, absPath);
+    const relativePath = relative3(projectDir, absPath);
     const backupDir = join6(projectDir, ".hyperframes", "backup");
     mkdirSync3(backupDir, { recursive: true });
     const backupKey = backupKeyForPath(relativePath);
@@ -745,30 +761,46 @@ function hashVersion(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;
-  return [stat2.ino, stat2.ctimeMs, stat2.size].map((n) => n.toString(36)).join("-");
+function settledFileTag(stat3, now = Date.now()) {
+  if (now - stat3.ctimeMs < 3e3) return null;
+  return [stat3.ino, stat3.ctimeMs, stat3.size].map((n) => n.toString(36)).join("-");
 }
 function createWriteToken(requestToken) {
   const token = requestToken?.trim();
   return token && token.length <= 200 ? token : randomUUID2();
 }
-function recordFileWriteReceipt(absPath, receipt) {
+function recordFileWriteReceipt(filePath, receipt) {
+  const absPath = realFilePath(filePath);
   const now = Date.now();
-  const current = (receipts.get(absPath) ?? []).filter(
-    (entry) => now - entry.recordedAt < RECEIPT_TTL_MS
-  );
-  current.push({ ...receipt, recordedAt: now });
-  receipts.set(absPath, current);
+  for (const [path, list] of receipts) {
+    const live = list.filter((entry) => now - entry.recordedAt < RECEIPT_TTL_MS);
+    if (live.length > 0) receipts.set(path, live);
+    else receipts.delete(path);
+  }
+  receipts.set(absPath, [...receipts.get(absPath) ?? [], { ...receipt, recordedAt: now }]);
 }
-function clearFileWriteReceipt(absPath, version, writeToken) {
+function clearFileWriteReceipt(filePath, version, writeToken) {
+  const absPath = realFilePath(filePath);
   const current = (receipts.get(absPath) ?? []).filter(
     (entry) => entry.version !== version || entry.writeToken !== writeToken
   );
   if (current.length > 0) receipts.set(absPath, current);
   else receipts.delete(absPath);
 }
-function identifyFileWrite(absPath, expectedVersion) {
+function identifyFileWrite(filePath, expectedVersion) {
+  const receipt = newestReceipt(realFilePath(filePath), expectedVersion);
+  if (!receipt) return null;
+  const { path, version, writeToken } = receipt;
+  return { path, version, writeToken };
+}
+function bytesOverwrittenBy(filePath, version) {
+  return newestReceipt(realFilePath(filePath), version)?.overwrote;
+}
+function forgetOverwrittenBytes(filePath, versions) {
+  for (const receipt of receipts.get(realFilePath(filePath)) ?? [])
+    if (versions.has(receipt.version)) delete receipt.overwrote;
+}
+function newestReceipt(absPath, expectedVersion) {
   const now = Date.now();
   const current = (receipts.get(absPath) ?? []).filter(
     (entry) => now - entry.recordedAt < RECEIPT_TTL_MS
@@ -779,15 +811,13 @@ function identifyFileWrite(absPath, expectedVersion) {
   for (let i = current.length - 1; i >= 0 && !receipt; i -= 1) {
     if (current[i]?.version === expectedVersion) receipt = current[i];
   }
-  if (!receipt) return null;
-  const { path, version, writeToken } = receipt;
-  return { path, version, writeToken };
+  return receipt;
 }
 var consumeFileWriteReceipt = identifyFileWrite;
 // src/helpers/applyFileMutations.ts
 import { readFileSync as readFileSync4, statSync as statSync2 } from "fs";
-function applyFileMutations(projectDir, mutations, requestToken, writeFile = (path, content) => replaceFileAtomically(path, content, statSync2(path).mode)) {
+function applyFileMutations(projectDir, mutations, requestToken, writeFile2 = (path, content) => replaceFileAtomically(path, content, statSync2(path).mode)) {
   const prepared = mutations.map((mutation) => ({
     ...mutation,
     before: mutation.before ?? readFileSync4(mutation.absPath, "utf-8")
@@ -795,10 +825,10 @@ function applyFileMutations(projectDir, mutations, requestToken, writeFile = (pa
   const results = [];
   const attempted = [];
   for (const mutation of prepared)
-    assertExpectedVersion(mutation.expectedVersion, readFileSync4(mutation.absPath, "utf-8"));
+    assertExpectedVersion(mutation, readFileSync4(mutation.absPath, "utf-8"));
   try {
     for (const mutation of prepared) {
-      results.push(applyOneMutation(projectDir, mutation, requestToken, writeFile, attempted));
+      results.push(applyOneMutation(projectDir, mutation, requestToken, writeFile2, attempted));
     }
     return results;
   } catch (error) {
@@ -806,7 +836,7 @@ function applyFileMutations(projectDir, mutations, requestToken, writeFile = (pa
     for (const mutation of attempted.reverse()) {
       try {
         if (!mutation.written || readFileSync4(mutation.absPath, "utf-8") === mutation.after)
-          writeFile(mutation.absPath, mutation.before, "utf-8");
+          writeFile2(mutation.absPath, mutation.before, "utf-8");
         clearFileWriteReceipt(mutation.absPath, mutation.version, mutation.writeToken);
       } catch (rollbackError) {
         rollbackErrors.push(rollbackError);
@@ -821,9 +851,9 @@ function applyFileMutations(projectDir, mutations, requestToken, writeFile = (pa
     throw error;
   }
 }
-function applyOneMutation(projectDir, mutation, requestToken, writeFile, attempted) {
+function applyOneMutation(projectDir, mutation, requestToken, writeFile2, attempted) {
   const current = readFileSync4(mutation.absPath, "utf-8");
-  assertExpectedVersion(mutation.expectedVersion, current);
+  assertExpectedVersion(mutation, current);
   if (mutation.after === mutation.before) {
     return {
       ...mutation,
@@ -836,17 +866,19 @@ function applyOneMutation(projectDir, mutation, requestToken, writeFile, attempt
   }
   const backup = snapshotBeforeWrite(projectDir, mutation.absPath);
   if (backup.error) throw new Error(`backup failed: ${backup.error}`);
+  assertExpectedVersion(mutation, readFileSync4(mutation.absPath, "utf-8"));
   const before = current;
   const version = fileContentVersion(mutation.after);
   const writeToken = createWriteToken(requestToken);
   const attempt = { ...mutation, before, version, writeToken, written: false };
   attempted.push(attempt);
-  writeFile(mutation.absPath, mutation.after, "utf-8");
+  writeFile2(mutation.absPath, mutation.after, "utf-8");
   attempt.written = true;
   recordFileWriteReceipt(mutation.absPath, {
     path: mutation.sourceFile,
     version,
-    writeToken
+    writeToken,
+    overwrote: before
   });
   return {
     ...mutation,
@@ -857,10 +889,16 @@ function applyOneMutation(projectDir, mutation, requestToken, writeFile, attempt
     writeToken
   };
 }
-function assertExpectedVersion(expectedVersion, current) {
-  if (expectedVersion !== void 0 && fileContentVersion(current) !== expectedVersion) {
-    throw new Error("file changed since the timeline was read");
+var FileChangedError = class extends Error {
+  constructor(sourceFile) {
+    super("file changed since the timeline was read");
+    this.sourceFile = sourceFile;
   }
+  sourceFile;
+};
+function assertExpectedVersion(mutation, current) {
+  const stale = mutation.expectedVersion === void 0 ? current !== mutation.before : fileContentVersion(current) !== mutation.expectedVersion;
+  if (stale) throw new FileChangedError(mutation.sourceFile);
 }
 // src/routes/files.ts
@@ -899,9 +937,9 @@ 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 readFileSync5, realpathSync } from "fs";
+import { existsSync as existsSync2, readFileSync as readFileSync5, realpathSync as realpathSync2 } from "fs";
 import { randomUUID as randomUUID3 } from "crypto";
-import { dirname as dirname3, relative as relative3, resolve as resolve2, sep as sep2 } from "path";
+import { dirname as dirname4, relative as relative4, resolve as resolve2, sep as sep3 } from "path";
 import { parseHTML } from "linkedom";
 var CompositionInsertionError = class extends Error {
   constructor(message, status) {
@@ -937,8 +975,8 @@ function canonicalProjectPath(projectDir, candidate) {
   if (!existsSync2(candidate)) {
     throw new CompositionInsertionError("Composition source was not found", 404);
   }
-  const canonical = realpathSync(candidate);
-  if (!isSafePath(realpathSync(projectDir), canonical)) {
+  const canonical = realpathSync2(candidate);
+  if (!isSafePath(realpathSync2(projectDir), canonical)) {
     throw new CompositionInsertionError("Composition source escapes the project", 400);
   }
   return canonical;
@@ -950,13 +988,13 @@ function validateSourcePath(sourcePath) {
 }
 function canonicalProjectFile(projectDir, sourcePath) {
   validateSourcePath(sourcePath);
-  return canonicalProjectPath(projectDir, resolveWithinProject(projectDir, sourcePath));
+  return canonicalProjectPath(projectDir, resolveWithinProject2(projectDir, sourcePath));
 }
 function canonicalDependency(projectDir, ownerAbs, sourcePath) {
   validateSourcePath(sourcePath);
   return canonicalProjectPath(
     projectDir,
-    resolveWithinProject(projectDir, relative3(projectDir, resolve2(dirname3(ownerAbs), sourcePath)))
+    resolveWithinProject2(projectDir, relative4(projectDir, resolve2(dirname4(ownerAbs), sourcePath)))
   );
 }
 function validateDependencyGraph(projectDir, targetAbs, sourceAbs) {
@@ -1029,7 +1067,7 @@ function uniqueHostId(root, base) {
   return `${base}_${suffix}`;
 }
 function relativeSourcePath(targetAbs, sourceAbs) {
-  return relative3(dirname3(targetAbs), sourceAbs).split(sep2).join("/");
+  return relative4(dirname4(targetAbs), sourceAbs).split(sep3).join("/");
 }
 function insertCompositionIntoSource(input) {
   const targetAbs = canonicalProjectFile(input.projectDir, input.targetPath);
@@ -1161,7 +1199,7 @@ async function loadGsapParser() {
   return import("@hyperframes/parsers/gsap-parser-recast");
 }
 function isDanglingSymlinkInProject(projectDir, lexicalPath) {
-  if (!isSafePath(projectDir, dirname4(lexicalPath))) return false;
+  if (!isSafePath(projectDir, dirname5(lexicalPath))) return false;
   let stats;
   try {
     stats = lstatSync3(lexicalPath);
@@ -1169,7 +1207,7 @@ function isDanglingSymlinkInProject(projectDir, lexicalPath) {
     return false;
   }
   if (!stats.isSymbolicLink()) return false;
-  const target = resolve3(dirname4(lexicalPath), readlinkSync(lexicalPath));
+  const target = resolve3(dirname5(lexicalPath), readlinkSync(lexicalPath));
   if (!isSafePath(projectDir, target)) return false;
   try {
     statSync3(lexicalPath);
@@ -1193,7 +1231,7 @@ async function resolveProjectPath(c, adapter, route, opts) {
   if (filePath.includes("\0")) {
     return { error: c.json({ error: "forbidden", why: "nul" }, 403) };
   }
-  const absPath = resolveWithinProject(project.dir, filePath);
+  const absPath = (opts?.pin ? pinWithinProject : resolveWithinProject2)(project.dir, filePath);
   if (!absPath) {
     if (isDanglingSymlinkInProject(project.dir, resolve3(project.dir, filePath))) {
       return { error: c.json({ error: "not found", why: "dangling_symlink" }, 404) };
@@ -1209,7 +1247,7 @@ function resolveProjectFile(c, adapter, opts) {
   return resolveProjectPath(c, adapter, "files", opts);
 }
 function resolveFileMutationContext(c, adapter, operation) {
-  return resolveProjectPath(c, adapter, `file-mutations/${operation}`);
+  return resolveProjectPath(c, adapter, `file-mutations/${operation}`, { pin: true });
 }
 function isOptionalInteger(value) {
   return value === void 0 || Number.isInteger(value);
@@ -1258,11 +1296,23 @@ function foldElementPatches(originalContent, patches) {
   }
   return { content, matched };
 }
-function commitElementPatchBatches(projectDir, batches, writeFile = (path, content) => replaceFileAtomically(path, content, statSync3(path).mode), requestToken) {
+var PATCH_CONFLICT_ATTEMPTS = 3;
+function commitElementPatchBatches(projectDir, batches, writeFile2 = (path, content) => replaceFileAtomically(path, content, statSync3(path).mode), requestToken) {
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return foldAndCommitElementPatchBatches(projectDir, batches, writeFile2, requestToken);
+    } catch (error) {
+      if (!(error instanceof FileChangedError)) throw error;
+      if (attempt === PATCH_CONFLICT_ATTEMPTS)
+        return { error: "conflict", sourceFile: error.sourceFile };
+    }
+  }
+}
+function foldAndCommitElementPatchBatches(projectDir, batches, writeFile2, requestToken) {
   const resolvedPaths = /* @__PURE__ */ new Set();
   const prepared = [];
   for (const batch of batches) {
-    const absPath = resolveWithinProject(projectDir, batch.sourceFile);
+    const absPath = pinWithinProject(projectDir, batch.sourceFile);
     if (!absPath) return { error: "forbidden", sourceFile: batch.sourceFile };
     if (resolvedPaths.has(absPath)) return { error: "duplicate", sourceFile: batch.sourceFile };
     resolvedPaths.add(absPath);
@@ -1303,7 +1353,7 @@ function commitElementPatchBatches(projectDir, batches, writeFile = (path, conte
       after
     })),
     requestToken,
-    writeFile
+    writeFile2
   );
   const files = applied.map((file, index) => ({
     sourceFile: file.sourceFile,
@@ -1319,23 +1369,24 @@ function commitElementPatchBatchesWithReceipts(c, projectDir, batches) {
   return commitElementPatchBatches(
     projectDir,
     batches,
-    writeFileSync5,
+    void 0,
     c.req.header("X-Hyperframes-Write-Token")
   );
 }
-function recordMutationReceipt(c, filePath, absPath, html) {
+function writeFileWithReceipt(c, filePath, absPath, html) {
+  const overwrote = readFileSync6(absPath);
+  replaceFileAtomically(absPath, html, statSync3(absPath).mode);
   const version = fileContentVersion(html);
   const writeToken = createWriteToken(c.req.header("X-Hyperframes-Write-Token"));
-  recordFileWriteReceipt(absPath, { path: filePath, version, writeToken });
+  recordFileWriteReceipt(absPath, { path: filePath, version, writeToken, overwrote });
   return { version, writeToken };
 }
-function writeFileWithReceipt(c, filePath, absPath, html) {
-  replaceFileAtomically(absPath, html, statSync3(absPath).mode);
-  return recordMutationReceipt(c, filePath, absPath, html);
-}
-function writeMutationResult(c, projectDir, filePath, absPath, html) {
+function writeMutationResult(c, projectDir, filePath, absPath, html, original) {
   const backup = snapshotBeforeWrite(projectDir, absPath);
   if (backup.error) return c.json({ error: `backup failed: ${backup.error}` }, 500);
+  if (readFileSync6(absPath, "utf-8") !== original) {
+    return c.json({ error: "file changed", conflict: true, path: filePath }, 409);
+  }
   const { version } = writeFileWithReceipt(c, filePath, absPath, html);
   return { backupPath: backupPathForResponse(projectDir, backup.backupPath), version };
 }
@@ -1343,7 +1394,7 @@ function writeIfChanged(c, projectDir, filePath, absPath, original, next) {
   if (next === original) {
     return c.json({ ok: true, changed: false, content: original, path: filePath });
   }
-  const mutationResult = writeMutationResult(c, projectDir, filePath, absPath, next);
+  const mutationResult = writeMutationResult(c, projectDir, filePath, absPath, next, original);
   if (mutationResult instanceof Response) return mutationResult;
   const { backupPath } = mutationResult;
   return c.json({
@@ -1365,6 +1416,8 @@ function rejectUnsafeMutationValues(c, unsafeFields) {
   );
 }
 function elementPatchBatchCommitErrorResponse(c, error, sourceFile) {
+  if (error === "conflict")
+    return c.json({ error: "file changed", conflict: true, sourceFile }, 409);
   if (error === "not-found") return c.json({ error, sourceFile }, 404);
   if (error === "forbidden") return c.json({ error, sourceFile }, 403);
   return c.json({ error: "duplicate source file", sourceFile }, 400);
@@ -1377,7 +1430,7 @@ async function parseMutationBody(c) {
   return { target: body.target, body };
 }
 function ensureDir(filePath) {
-  const dir = dirname4(filePath);
+  const dir = dirname5(filePath);
   if (!existsSync3(dir)) mkdirSync4(dir, { recursive: true });
 }
 function generateCopyPath(projectDir, originalPath) {
@@ -1765,7 +1818,8 @@ async function applyGsapMutations(c, res, mutations) {
       res.project.dir,
       res.filePath,
       res.absPath,
-      newHtml
+      newHtml,
+      beforeHtml
     );
     if (mutationResult instanceof Response) return mutationResult;
     backupPath = mutationResult.backupPath;
@@ -2598,7 +2652,7 @@ function registerFileRoutes(api, adapter) {
     }
   });
   api.put("/projects/:id/files/*", async (c) => {
-    const res = await resolveProjectFile(c, adapter);
+    const res = await resolveProjectFile(c, adapter, { pin: true });
     if ("error" in res) return res.error;
     const body = Buffer.from(await c.req.arrayBuffer());
     const expectedVersion = c.req.header("If-Match")?.trim() ?? null;
@@ -2623,6 +2677,7 @@ function registerFileRoutes(api, adapter) {
       );
     }
     let backup = { backupPath: null };
+    let overwrote;
     if (createOnly) {
       ensureDir(res.absPath);
       let fd;
@@ -2668,6 +2723,7 @@ function registerFileRoutes(api, adapter) {
       }
       try {
         const currentContent = readFileSync6(fd);
+        overwrote = currentContent;
         const currentVersion = fileContentVersion(currentContent);
         if (expectedVersion !== currentVersion) {
           return c.json(
@@ -2692,7 +2748,7 @@ function registerFileRoutes(api, adapter) {
     }
     const version = fileContentVersion(body);
     const writeToken = createWriteToken(c.req.header("X-Hyperframes-Write-Token"));
-    recordFileWriteReceipt(res.absPath, { path: res.filePath, version, writeToken });
+    recordFileWriteReceipt(res.absPath, { path: res.filePath, version, writeToken, overwrote });
     c.header("ETag", version);
     return c.json({
       ok: true,
@@ -2720,10 +2776,10 @@ function registerFileRoutes(api, adapter) {
   api.delete("/projects/:id/files/*", async (c) => {
     const res = await resolveProjectFile(c, adapter, { mustExist: true });
     if ("error" in res) return res.error;
-    const stat2 = statSync3(res.absPath);
+    const stat3 = statSync3(res.absPath);
     const backup = snapshotBeforeWrite(res.project.dir, res.absPath);
     if (backup.error) return c.json({ error: `backup failed: ${backup.error}` }, 500);
-    if (stat2.isDirectory()) {
+    if (stat3.isDirectory()) {
       rmSync3(res.absPath, { recursive: true });
     } else {
       unlinkSync2(res.absPath);
@@ -2771,6 +2827,11 @@ function registerFileRoutes(api, adapter) {
     }
     const backup = snapshotBeforeWrite(ctx.project.dir, ctx.absPath);
     if (backup.error) return c.json({ error: `backup failed: ${backup.error}` }, 500);
+    const current = readFileSync6(ctx.absPath, "utf-8");
+    if (current !== before) {
+      const currentVersion2 = fileContentVersion(current);
+      return c.json({ error: "file conflict", currentVersion: currentVersion2, currentContent: current }, 409);
+    }
     const { version, writeToken } = writeFileWithReceipt(
       c,
       ctx.filePath,
@@ -2847,7 +2908,7 @@ function registerFileRoutes(api, adapter) {
       const seen = /* @__PURE__ */ new Set();
       const prepared = [];
       for (const file of files) {
-        const absPath = resolveWithinProject(project.dir, file.path);
+        const absPath = pinWithinProject(project.dir, file.path);
         if (!absPath) return c.json({ error: `forbidden path: ${file.path}` }, 403);
         if (seen.has(absPath)) return c.json({ error: `duplicate path: ${file.path}` }, 400);
         seen.add(absPath);
@@ -2915,7 +2976,8 @@ function registerFileRoutes(api, adapter) {
           recordFileWriteReceipt(file.absPath, {
             path: file.path,
             version: fileContentVersion(file.after),
-            writeToken
+            writeToken,
+            overwrote: file.before
           });
         }
       } catch (error) {
@@ -2997,7 +3059,8 @@ function registerFileRoutes(api, adapter) {
       ctx.project.dir,
       ctx.filePath,
       ctx.absPath,
-      result.html
+      result.html,
+      originalContent
     );
     if (mutationResult instanceof Response) return mutationResult;
     const { version, backupPath } = mutationResult;
@@ -3024,48 +3087,54 @@ function registerFileRoutes(api, adapter) {
     if (unsafeFields.length > 0) {
       return rejectUnsafeMutationValues(c, unsafeFields);
     }
-    let originalContent;
-    try {
-      originalContent = readFileSync6(ctx.absPath, "utf-8");
-    } catch {
-      return c.json({ error: "not found" }, 404);
-    }
-    const { html: patched, matched } = patchElementInHtml(
-      originalContent,
-      parsed.target,
-      parsed.body.operations
-    );
-    if (patched === originalContent) {
-      const version2 = fileContentVersion(originalContent);
-      c.header("ETag", version2);
+    for (let attempt = 1; ; attempt += 1) {
+      let originalContent;
+      try {
+        originalContent = readFileSync6(ctx.absPath, "utf-8");
+      } catch {
+        return c.json({ error: "not found" }, 404);
+      }
+      const { html: patched, matched } = patchElementInHtml(
+        originalContent,
+        parsed.target,
+        parsed.body.operations
+      );
+      if (patched === originalContent) {
+        const version2 = fileContentVersion(originalContent);
+        c.header("ETag", version2);
+        return c.json({
+          ok: true,
+          changed: false,
+          matched,
+          content: originalContent,
+          path: ctx.filePath,
+          version: version2
+        });
+      }
+      const mutationResult = writeMutationResult(
+        c,
+        ctx.project.dir,
+        ctx.filePath,
+        ctx.absPath,
+        patched,
+        originalContent
+      );
+      if (mutationResult instanceof Response) {
+        if (mutationResult.status === 409 && attempt < PATCH_CONFLICT_ATTEMPTS) continue;
+        return mutationResult;
+      }
+      const { backupPath, version } = mutationResult;
+      c.header("ETag", version);
       return c.json({
         ok: true,
-        changed: false,
+        changed: true,
         matched,
-        content: originalContent,
+        content: patched,
         path: ctx.filePath,
-        version: version2
+        version,
+        backupPath
       });
     }
-    const mutationResult = writeMutationResult(
-      c,
-      ctx.project.dir,
-      ctx.filePath,
-      ctx.absPath,
-      patched
-    );
-    if (mutationResult instanceof Response) return mutationResult;
-    const { backupPath, version } = mutationResult;
-    c.header("ETag", version);
-    return c.json({
-      ok: true,
-      changed: true,
-      matched,
-      content: patched,
-      path: ctx.filePath,
-      version,
-      backupPath
-    });
   });
   api.post("/projects/:id/file-mutations/patch-element-batches", async (c) => {
     const project = await adapter.resolveProject(c.req.param("id"));
@@ -3155,7 +3224,8 @@ function registerFileRoutes(api, adapter) {
       ctx.project.dir,
       ctx.filePath,
       ctx.absPath,
-      result.html
+      result.html,
+      originalContent
     );
     if (mutationResult instanceof Response) return mutationResult;
     const { backupPath } = mutationResult;
@@ -3225,7 +3295,7 @@ function registerFileRoutes(api, adapter) {
     if (!body.newPath || body.newPath.includes("\0")) {
       return c.json({ error: "newPath required" }, 400);
     }
-    const newAbs = resolveWithinProject(res.project.dir, body.newPath);
+    const newAbs = resolveWithinProject2(res.project.dir, body.newPath);
     if (!newAbs) {
       return c.json({ error: "forbidden" }, 403);
     }
@@ -3244,17 +3314,24 @@ function registerFileRoutes(api, adapter) {
     if (!body.path || body.path.includes("\0")) {
       return c.json({ error: "path required" }, 400);
     }
-    const srcAbs = resolveWithinProject(project.dir, body.path);
+    const srcAbs = resolveWithinProject2(project.dir, body.path);
     if (!srcAbs || !existsSync3(srcAbs)) {
       return c.json({ error: "not found" }, 404);
     }
     const copyPath = generateCopyPath(project.dir, body.path);
-    const destAbs = resolveWithinProject(project.dir, copyPath);
+    const destAbs = resolveWithinProject2(project.dir, copyPath);
     if (!destAbs) {
       return c.json({ error: "forbidden" }, 403);
     }
     ensureDir(destAbs);
-    writeFileSync5(destAbs, readFileSync6(srcAbs));
+    try {
+      writeFileSync5(destAbs, readFileSync6(srcAbs), { flag: "wx" });
+    } catch (error) {
+      if (!error || typeof error !== "object" || !("code" in error) || error.code !== "EEXIST") {
+        throw error;
+      }
+      return c.json({ error: "already exists" }, 409);
+    }
     return c.json({ ok: true, path: copyPath }, 201);
   });
   const MAX_UPLOAD_BYTES = 500 * 1024 * 1024;
@@ -3268,7 +3345,7 @@ function registerFileRoutes(api, adapter) {
       const project = await adapter.resolveProject(c.req.param("id"));
       if (!project) return c.json({ error: "not found" }, 404);
       const subDir = c.req.query("dir") ?? "";
-      const targetDir = subDir ? resolveWithinProject(project.dir, subDir) : project.dir;
+      const targetDir = subDir ? resolveWithinProject2(project.dir, subDir) : project.dir;
       if (!targetDir) return c.json({ error: "forbidden" }, 403);
       if (subDir && !existsSync3(targetDir)) mkdirSync4(targetDir, { recursive: true });
       const formData = await c.req.formData();
@@ -3304,7 +3381,8 @@ function registerFileRoutes(api, adapter) {
   });
   api.post("/projects/:id/gsap-mutations/*", async (c) => {
     const res = await resolveProjectPath(c, adapter, "gsap-mutations", {
-      mustExist: true
+      mustExist: true,
+      pin: true
     });
     if ("error" in res) return res.error;
     const body = await c.req.json().catch(() => null);
@@ -3314,7 +3392,10 @@ function registerFileRoutes(api, adapter) {
     return applyGsapMutations(c, res, [body]);
   });
   api.post("/projects/:id/gsap-mutations-batch/*", async (c) => {
-    const res = await resolveProjectPath(c, adapter, "gsap-mutations-batch", { mustExist: true });
+    const res = await resolveProjectPath(c, adapter, "gsap-mutations-batch", {
+      mustExist: true,
+      pin: true
+    });
     if ("error" in res) return res.error;
     const body = await c.req.json().catch(() => null);
     if (!body || !Array.isArray(body.mutations) || body.mutations.length === 0) {
@@ -3327,7 +3408,10 @@ function registerFileRoutes(api, adapter) {
     return applyGsapMutations(c, res, body.mutations);
   });
   api.post("/projects/:id/gsap-mutation-rollback/*", async (c) => {
-    const res = await resolveProjectPath(c, adapter, "gsap-mutation-rollback", { mustExist: true });
+    const res = await resolveProjectPath(c, adapter, "gsap-mutation-rollback", {
+      mustExist: true,
+      pin: true
+    });
     if ("error" in res) return res.error;
     const body = await c.req.json().catch(() => null);
     if (!body || typeof body.expected !== "string" || typeof body.restore !== "string") {
@@ -3345,9 +3429,10 @@ function registerFileRoutes(api, adapter) {
 // src/routes/preview.ts
 import { createReadStream, existsSync as existsSync5, readFileSync as readFileSync8, statSync as statSync4 } from "fs";
 import { Readable } from "stream";
-import { join as join9, resolve as resolve4 } from "path";
+import { join as join10, resolve as resolve5 } from "path";
 import { createHash as createHash4 } from "crypto";
 import {
+  addScenePartsManifest,
   injectScriptsIntoHtml,
   insertBeforeCloseTag as insertBeforeCloseTag2,
   stripEmbeddedRuntimeScripts as stripEmbeddedRuntimeScripts2
@@ -3364,9 +3449,7 @@ import {
   rewriteInlineStyleAssetUrls
 } from "@hyperframes/core";
 import { stripEmbeddedRuntimeScripts } from "@hyperframes/core/compiler";
-function isFullHtmlDocument(html) {
-  return /^\s*(?:<!doctype\s|<html[\s>])/i.test(html);
-}
+import { isFullHtmlDocument } from "@hyperframes/core/compiler/html-document";
 function rewriteRelativePaths(root, compPath, projectDir) {
   const assetExists = (path) => existsSync4(join8(projectDir, path));
   rewriteAssetPaths(
@@ -3539,6 +3622,83 @@ function hasBaseElement(html) {
 // src/routes/preview.ts
 import { ensureHfIds as ensureHfIds3 } from "@hyperframes/parsers/hf-ids";
+// src/helpers/previewReads.ts
+import { readlinkSync as readlinkSync2 } from "fs";
+import { dirname as dirname6, join as join9, parse, relative as relative5, resolve as resolve4 } from "path";
+var ALWAYS_AFFECTS = ["hyperframes.json", ...STUDIO_SIGNATURE_MANIFEST_PATHS];
+var REFERENCE = /\b(?:src|href|poster|data-composition-src)\s*=\s*(?:"([^"\n]*)"|'([^'\n]*)')|url\(\s*(?:"([^"\n]*)"|'([^'\n]*)'|([^"'\s)]+))/gi;
+var pathKey = process.platform === "darwin" || process.platform === "win32" ? (path) => resolve4(path).toLowerCase() : (path) => resolve4(path);
+var readsByProject = /* @__PURE__ */ new Map();
+var builtProjects = /* @__PURE__ */ new Set();
+var projectKey = (projectDir) => pathKey(realFilePath(resolve4(projectDir)));
+var inRealProject = (projectDir, path) => join9(realFilePath(resolve4(projectDir)), relative5(resolve4(projectDir), resolve4(projectDir, path)));
+var readLink = (path) => {
+  try {
+    return readlinkSync2(path);
+  } catch {
+    return null;
+  }
+};
+function linksOnTheWay(path) {
+  const passed = [];
+  let at = parse(path).root;
+  let rest = path.slice(at.length).split(/[\\/]+/);
+  for (let hops = 0; rest.length > 0; ) {
+    const part = rest.shift();
+    if (!part || part === ".") continue;
+    if (part === "..") {
+      at = dirname6(at);
+      continue;
+    }
+    const next = join9(at, part);
+    const target = hops < 40 ? readLink(next) : null;
+    if (target === null) {
+      at = next;
+      continue;
+    }
+    hops++;
+    passed.push(next);
+    const root = parse(target).root;
+    if (root) at = root;
+    rest = [...target.slice(root.length).split(/[\\/]+/), ...rest];
+  }
+  passed.push(at);
+  return passed;
+}
+function recordPreviewRead(projectDir, filePath) {
+  const key = projectKey(projectDir);
+  let reads = readsByProject.get(key);
+  if (!reads) readsByProject.set(key, reads = /* @__PURE__ */ new Set());
+  const read = inRealProject(projectDir, filePath);
+  for (const found of [read, ...linksOnTheWay(read)]) {
+    for (let path = pathKey(found); !reads.has(path); path = dirname6(path)) reads.add(path);
+  }
+}
+function recordPreviewReferences(projectDir, html) {
+  const named = /* @__PURE__ */ new Set();
+  for (const match of html.matchAll(REFERENCE)) {
+    const url = (match[1] ?? match[2] ?? match[3] ?? match[4] ?? match[5] ?? "").trim();
+    if (!url || /^(?:[a-z][a-z0-9+.-]*:|[/#])/i.test(url)) continue;
+    const path = url.split(/[?#]/)[0] ?? "";
+    let decoded = path;
+    try {
+      decoded = decodeURIComponent(path);
+    } catch {
+    }
+    if (decoded) named.add(decoded);
+  }
+  for (const path of named) recordPreviewRead(projectDir, path);
+}
+function recordPreviewBuilt(projectDir) {
+  for (const path of ALWAYS_AFFECTS) recordPreviewRead(projectDir, path);
+  builtProjects.add(projectKey(projectDir));
+}
+function affectsPreview(projectDir, changedPath) {
+  const key = projectKey(projectDir);
+  if (!builtProjects.has(key)) return true;
+  return readsByProject.get(key)?.has(pathKey(inRealProject(projectDir, changedPath))) ?? false;
+}
 // src/helpers/variablesPayload.ts
 var VARIABLES_PAYLOAD_ERROR = "variables must be a JSON object of {variableId: value}";
 function isVariablesPayload(value) {
@@ -3580,7 +3740,7 @@ function injectProjectSignature(html, signature) {
 ${html}`;
 }
 function readStudioMotionManifestContent(projectDir) {
-  const manifestPath = join9(projectDir, STUDIO_MOTION_PATH);
+  const manifestPath = join10(projectDir, STUDIO_MOTION_PATH);
   if (!existsSync5(manifestPath)) return "";
   try {
     return readFileSync8(manifestPath, "utf-8");
@@ -3696,9 +3856,9 @@ function variablesEtagSalt(raw) {
   return `:vars:${createHash4("sha1").update(raw).digest("hex").slice(0, 12)}`;
 }
 function previewVariablesFromRequest(rawVariables) {
-  const parse = parsePreviewVariablesParam(rawVariables);
-  if (!parse.ok) return { error: parse.error };
-  return { raw: rawVariables, values: parse.values };
+  const parse2 = parsePreviewVariablesParam(rawVariables);
+  if (!parse2.ok) return { error: parse2.error };
+  return { raw: rawVariables, values: parse2.values };
 }
 function injectStudioPreviewAugmentations(html, adapter, projectDir, activeCompositionPath) {
   return injectStudioMotionScript(
@@ -3725,14 +3885,16 @@ async function transformPreviewHtml(html, adapter, project, activeCompositionPat
   }
 }
 function resolveProjectMainHtml(projectDir, projectId) {
-  const indexPath = join9(projectDir, "index.html");
+  const indexPath = join10(projectDir, "index.html");
+  const blockHtmlPath = join10(projectDir, `${projectId}.html`);
+  recordPreviewRead(projectDir, indexPath);
+  recordPreviewRead(projectDir, blockHtmlPath);
   if (existsSync5(indexPath)) {
     return {
       html: readFileSync8(indexPath, "utf-8"),
       compositionPath: "index.html"
     };
   }
-  const blockHtmlPath = join9(projectDir, `${projectId}.html`);
   if (existsSync5(blockHtmlPath)) {
     return {
       html: readFileSync8(blockHtmlPath, "utf-8"),
@@ -3744,7 +3906,8 @@ function resolveProjectMainHtml(projectDir, projectId) {
 var PREVIEW_BUNDLE_OPTIONS = {
   runtime: "placeholder",
   inlineAssets: false,
-  staticGuard: false
+  staticGuard: false,
+  sceneParts: true
 };
 function registerPreviewRoutes(api, adapter) {
   const previewCacheHeaders = (etag) => ({
@@ -3763,13 +3926,18 @@ function registerPreviewRoutes(api, adapter) {
     const diskMain = resolveProjectMainHtml(project.dir, project.id);
     const normalizedDisk = diskMain ? ensureHfIds3(diskMain.html) : null;
     try {
-      let bundled = await adapter.bundle(project.dir, { stampHfIds: true });
+      let bundled = await adapter.bundle(project.dir, {
+        stampHfIds: true,
+        onRead: (filePath) => recordPreviewRead(project.dir, filePath)
+      });
       let mainCompositionPath = "index.html";
       if (!bundled) {
         if (!diskMain) return null;
         bundled = stripEmbeddedRuntimeScripts2(normalizedDisk ?? diskMain.html);
         mainCompositionPath = diskMain.compositionPath;
       }
+      recordPreviewReferences(project.dir, bundled);
+      recordPreviewBuilt(project.dir);
       if (!bundled.includes("hyperframe.runtime") && !bundled.includes("hyperframes-preview-runtime")) {
         const runtimeTag = `<script src="${adapter.runtimeUrl}"></script>`;
         bundled = insertBeforeCloseTag2(bundled, "body", `${runtimeTag}
@@ -3794,6 +3962,7 @@ ${runtimeTag}`;
         mainCompositionPath,
         mediaCodecProbeCache
       );
+      bundled = addScenePartsManifest(bundled, [`meta[name="${PROJECT_SIGNATURE_META}"]`]);
       rememberPreview(builtKey, bundled);
       adapter.previewDocuments?.write(builtKey, bundled);
       return bundled;
@@ -3871,7 +4040,9 @@ ${etag}`;
     if (vars.error !== void 0) return c.json({ error: vars.error }, 400);
     const previewVariables = vars.values;
     const compPath = requestSubPath(c.req.url, "projects/:id/preview/comp");
-    const compFile = resolveWithinProject(project.dir, compPath);
+    const compFile = resolveWithinProject2(project.dir, compPath);
+    if (compFile) recordPreviewRead(project.dir, compFile);
+    recordPreviewRead(project.dir, "index.html");
     if (!compFile || !existsSync5(compFile) || !statSync4(compFile).isFile()) {
       return c.text("not found", 404);
     }
@@ -3895,6 +4066,7 @@ ${etag}`;
       stamped
     );
     if (!html) return c.text("not found", 404);
+    recordPreviewReferences(project.dir, html);
     html = ensureHfIds3(await transformPreviewHtml(html, adapter, project, compPath));
     html = injectStudioPreviewAugmentations(html, adapter, project.dir, compPath);
     if (previewVariables) html = injectPreviewVariables(html, previewVariables);
@@ -3905,13 +4077,14 @@ ${etag}`;
     const project = await adapter.resolveProject(c.req.param("id"));
     if (!project) return c.json({ error: "not found" }, 404);
     const subPath = requestSubPath(c.req.url, "projects/:id/preview");
-    const candidate = resolve4(project.dir, subPath);
+    const candidate = resolve5(project.dir, subPath);
     const file = isWithinProjectRoot(project.dir, candidate) ? candidate : null;
     if (!file) {
       return c.text("not found", 404);
     }
-    const stat2 = existsSync5(file) ? statSync4(file) : null;
-    if (!stat2?.isFile()) {
+    recordPreviewRead(project.dir, file);
+    const stat3 = existsSync5(file) ? statSync4(file) : null;
+    if (!stat3?.isFile()) {
       return c.text("not found", 404);
     }
     const contentType = getMimeType(subPath);
@@ -3922,7 +4095,7 @@ ${etag}`;
       if (!isProxyVariantRequest(proxyParam) || !contentType.startsWith("video/") || !isAutoProxyEnabled(adapter)) {
         return c.text("not found", 404);
       }
-      const facts = await probeAssetCodec(file);
+      const facts = await probeAssetCodec(file, void 0, mediaCodecProbeCache);
       const eligibility = decideMediaProxyEligibility(facts);
       if (!eligibility.eligible) {
         return c.text(`media proxy unavailable: ${eligibility.reason}`, 422);
@@ -3933,7 +4106,7 @@ ${etag}`;
         return c.text("media proxy variant does not match asset", 422);
       }
     }
-    const tag = settledFileTag(stat2);
+    const tag = settledFileTag(stat3);
     const etag = tag && `"${tag}${proxyEtagSalt(proxyVariant)}"`;
     const cacheHeaders = isText ? { "Cache-Control": "no-store" } : { "Cache-Control": "private, no-cache", ...etag && { ETag: etag } };
     if (!isText && etag) {
@@ -4002,7 +4175,7 @@ ${etag}`;
 // src/routes/lint.ts
 import { readFileSync as readFileSync9 } from "fs";
-import { join as join10 } from "path";
+import { join as join11 } from "path";
 async function collectProjectFindings(adapter, projectDir) {
   const findings = [];
   const coveredFiles = /* @__PURE__ */ new Set();
@@ -4020,7 +4193,7 @@ async function lintUncoveredHtml(adapter, projectDir, htmlFiles, coveredFiles) {
   const findings = [];
   for (const file of htmlFiles) {
     if (coveredFiles.has(file)) continue;
-    const content = readFileSync9(join10(projectDir, file), "utf-8");
+    const content = readFileSync9(join11(projectDir, file), "utf-8");
     const result = await adapter.lint(content, { filePath: file, isSubComposition: true });
     for (const finding of result?.findings ?? []) {
       findings.push({ ...finding, file });
@@ -4054,7 +4227,7 @@ function registerLintRoutes(api, adapter) {
 // src/routes/render.ts
 import { streamSSE } from "hono/streaming";
 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 { join as join12 } from "path";
 import { VALID_CANVAS_RESOLUTIONS } from "@hyperframes/parsers";
 import { formatRenderOutputTimestamp, parseFps } from "@hyperframes/core";
 var VALID_RESOLUTIONS = new Set(VALID_CANVAS_RESOLUTIONS);
@@ -4105,7 +4278,7 @@ function registerRenderRoutes(api, adapter) {
     const outputResolution = VALID_RESOLUTIONS.has(body.resolution ?? "") ? body.resolution : void 0;
     let composition;
     if (typeof body.composition === "string" && body.composition.length > 0) {
-      if (!resolveWithinProject(project.dir, body.composition)) {
+      if (!resolveWithinProject2(project.dir, body.composition)) {
         return c.json({ error: "composition path must be within the project directory" }, 400);
       }
       composition = body.composition;
@@ -4122,7 +4295,7 @@ function registerRenderRoutes(api, adapter) {
     const rendersDir = adapter.rendersDir(project);
     if (!existsSync6(rendersDir)) mkdirSync5(rendersDir, { recursive: true });
     const ext = FORMAT_EXT[format] ?? ".mp4";
-    const outputPath = join11(rendersDir, `${jobId}${ext}`);
+    const outputPath = join12(rendersDir, `${jobId}${ext}`);
     const jobState = adapter.startRender({
       project,
       outputPath,
@@ -4223,7 +4396,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 = join11(dir, `${jobId}${ext}`);
+          const fp = join12(dir, `${jobId}${ext}`);
           if (existsSync6(fp)) unlinkSync3(fp);
         }
         break;
@@ -4238,7 +4411,7 @@ function registerRenderRoutes(api, adapter) {
     const filename = c.req.path.split("/renders/file/")[1];
     if (!filename) return c.json({ error: "missing filename" }, 400);
     const rendersDir = adapter.rendersDir(project);
-    const fp = resolveWithinProject(rendersDir, filename);
+    const fp = resolveWithinProject2(rendersDir, filename);
     if (!fp) return c.json({ error: "forbidden" }, 403);
     if (!existsSync6(fp)) return c.json({ error: "not found" }, 404);
     const contentType = renderContentType(fp);
@@ -4258,10 +4431,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 = join11(rendersDir, f);
-      const stat2 = statSync5(fp);
+      const fp = join12(rendersDir, f);
+      const stat3 = statSync5(fp);
       const rid = f.replace(/\.(mp4|webm|mov)$/, "");
-      const metaPath = join11(rendersDir, `${rid}.meta.json`);
+      const metaPath = join12(rendersDir, `${rid}.meta.json`);
       let status = "complete";
       let durationMs;
       if (existsSync6(metaPath)) {
@@ -4275,8 +4448,8 @@ function registerRenderRoutes(api, adapter) {
       return {
         id: rid,
         filename: f,
-        size: stat2.size,
-        createdAt: stat2.mtimeMs,
+        size: stat3.size,
+        createdAt: stat3.mtimeMs,
         status,
         durationMs
       };
@@ -4287,7 +4460,7 @@ function registerRenderRoutes(api, adapter) {
           id: file.id,
           status: file.status,
           progress: 100,
-          outputPath: join11(rendersDir, file.filename),
+          outputPath: join12(rendersDir, file.filename),
           createdAt: file.createdAt
         });
       }
@@ -4296,80 +4469,11 @@ function registerRenderRoutes(api, adapter) {
   });
 }
-// src/routes/thumbnail.ts
-import {
-  closeSync as closeSync3,
-  existsSync as existsSync7,
-  fstatSync as fstatSync3,
-  openSync as openSync3,
-  mkdirSync as mkdirSync6,
-  readFileSync as readFileSync12,
-  readdirSync as readdirSync6,
-  renameSync as renameSync3,
-  rmSync as rmSync4,
-  statSync as statSync6,
-  unlinkSync as unlinkSync4,
-  writeFileSync as writeFileSync6
-} from "fs";
-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";
-var ROOT_COMPOSITION = "index.html";
-var COMPOSITION_SRC = /\bdata-composition-src\s*=\s*(["'])(.*?)\1/g;
-function projectReader(projectDir) {
-  const sources = /* @__PURE__ */ new Map();
-  return (compPath) => {
-    if (!sources.has(compPath)) {
-      const file = resolveWithinProject(projectDir, compPath);
-      let source = null;
-      try {
-        source = file ? readFileSync11(file, "utf-8") : null;
-      } catch {
-      }
-      sources.set(compPath, source);
-    }
-    return sources.get(compPath) ?? null;
-  };
-}
-function normalizeSource(src) {
-  if (/^[a-z][a-z0-9+.-]*:/i.test(src) || src.startsWith("//")) return null;
-  const path = src.split(/[?#]/)[0]?.replace(/^\.?\//, "") ?? "";
-  return path || null;
-}
-function closureOf(read, compPath) {
-  const closure = /* @__PURE__ */ new Set();
-  const visit = (path) => {
-    if (closure.has(path)) return;
-    closure.add(path);
-    for (const match of (read(path) ?? "").matchAll(COMPOSITION_SRC)) {
-      const mounted = normalizeSource(match[2] ?? "");
-      if (mounted) visit(mounted);
-    }
-  };
-  visit(compPath);
-  return closure;
-}
-var inputSignatures = /* @__PURE__ */ new Map();
-function compositionInputSignature(projectDir, compPath, projectSignature) {
-  const key = `${projectDir}\0${compPath}`;
-  const known = inputSignatures.get(key);
-  if (known?.projectSignature === projectSignature) return known.inputSignature;
-  const read = projectReader(projectDir);
-  const inputs = closureOf(read, normalizeSource(compPath) ?? compPath).add(ROOT_COMPOSITION);
-  const siblings = [...closureOf(read, ROOT_COMPOSITION)].filter((path) => !inputs.has(path));
-  const inputSignature = createProjectSignature(projectDir, new Set(siblings));
-  inputSignatures.set(key, { projectSignature, inputSignature });
-  return inputSignature;
-}
-function compositionsAffectedBy(projectDir, changedPath) {
-  const changed = changedPath.replace(/\\/g, "/");
-  const read = projectReader(projectDir);
-  const mounted = closureOf(read, ROOT_COMPOSITION);
-  if (changed === ROOT_COMPOSITION || !mounted.has(changed)) return null;
-  return [...mounted].filter((path) => closureOf(read, path).has(changed));
-}
+// src/routes/imageThumbnail.ts
+import { HTTPException } from "hono/http-exception";
+import { open, stat } from "fs/promises";
+import { createHash as createHash5 } from "crypto";
+import sharp from "sharp";
 // src/routes/thumbnailGenerationCoordinator.ts
 var ThumbnailGenerationCoordinator = class {
@@ -4388,10 +4492,10 @@ var ThumbnailGenerationCoordinator = class {
     if (signal.aborted) return Promise.reject(new DOMException("Aborted", "AbortError"));
     let entry = this.entries.get(key);
     if (!entry) {
-      let resolve8;
+      let resolve9;
       let reject;
       const promise = new Promise((resolvePromise, rejectPromise) => {
-        resolve8 = resolvePromise;
+        resolve9 = resolvePromise;
         reject = rejectPromise;
       });
       entry = {
@@ -4401,7 +4505,7 @@ var ThumbnailGenerationCoordinator = class {
         state: "queued",
         work,
         promise,
-        resolve: resolve8,
+        resolve: resolve9,
         reject
       };
       this.entries.set(key, entry);
@@ -4415,7 +4519,7 @@ var ThumbnailGenerationCoordinator = class {
     return /* @__PURE__ */ new Set([...this.entries.keys(), ...[...this.activeEntries].map((entry) => entry.key)]);
   }
   lease(entry, signal) {
-    return new Promise((resolve8, reject) => {
+    return new Promise((resolve9, reject) => {
       let released = false;
       const release = () => {
         if (released) return;
@@ -4439,7 +4543,7 @@ var ThumbnailGenerationCoordinator = class {
       entry.promise.then(
         (value) => {
           release();
-          resolve8(value);
+          resolve9(value);
         },
         (reason) => {
           release();
@@ -4474,6 +4578,171 @@ var ThumbnailGenerationCoordinator = class {
 };
 var thumbnailGenerationCoordinator = new ThumbnailGenerationCoordinator(1);
+// src/routes/imageThumbnail.ts
+var MAX_SOURCE_BYTES = 64 * 1024 * 1024;
+var MAX_CACHE_BYTES = 8 * 1024 * 1024;
+async function generateThumbnail(path, signal) {
+  const file = await open(path, "r");
+  try {
+    const info = await file.stat();
+    if (!info.isFile() || info.size > MAX_SOURCE_BYTES) throw new Error("Unsupported image");
+    const source = Buffer.alloc(info.size);
+    let offset = 0;
+    while (offset < source.length) {
+      signal.throwIfAborted();
+      const { bytesRead } = await file.read(source, offset, source.length - offset, offset);
+      if (!bytesRead) break;
+      offset += bytesRead;
+    }
+    if (source[0] !== 255 || source[1] !== 216) throw new Error("Unsupported image");
+    const image = sharp(source.subarray(0, offset), { limitInputPixels: 4e7 });
+    if ((await image.metadata()).format !== "jpeg") throw new Error("Unsupported image");
+    signal.throwIfAborted();
+    const result = await image.rotate().resize(240, 135, { fit: "inside", withoutEnlargement: true }).jpeg({ quality: 80 }).toBuffer();
+    signal.throwIfAborted();
+    return result;
+  } finally {
+    await file.close();
+  }
+}
+async function resolveSource(adapter, id, url) {
+  const project = await adapter.resolveProject(id);
+  if (!project) throw new HTTPException(404);
+  let relative7;
+  try {
+    relative7 = requestSubPath(url, "projects/:id/image-thumbnail");
+  } catch {
+    throw new HTTPException(400);
+  }
+  if (!/\.jpe?g$/i.test(relative7)) throw new HTTPException(415);
+  const path = pinWithinProject(project.dir, relative7);
+  if (!path) throw new HTTPException(404);
+  const info = await stat(path).catch(() => {
+    throw new HTTPException(404);
+  });
+  if (!info.isFile()) throw new HTTPException(404);
+  if (info.size > MAX_SOURCE_BYTES) throw new HTTPException(413);
+  return { path, info };
+}
+function registerImageThumbnailRoutes(api, adapter) {
+  const coordinator = new ThumbnailGenerationCoordinator(2);
+  const cache = /* @__PURE__ */ new Map();
+  let cacheBytes = 0;
+  const remember = (key, image) => {
+    cacheBytes -= cache.get(key)?.byteLength ?? 0;
+    cache.delete(key);
+    cache.set(key, image);
+    cacheBytes += image.byteLength;
+    while (cacheBytes > MAX_CACHE_BYTES || cache.size > 128) {
+      const oldest = cache.keys().next().value;
+      if (oldest === void 0) break;
+      cacheBytes -= cache.get(oldest)?.byteLength ?? 0;
+      cache.delete(oldest);
+    }
+  };
+  api.get("/projects/:id/image-thumbnail/*", async (c) => {
+    try {
+      const { path, info } = await resolveSource(adapter, c.req.param("id"), c.req.url);
+      const key = createHash5("sha256").update(JSON.stringify([path, info.dev, info.ino, info.size, info.mtimeMs, info.ctimeMs])).digest("hex");
+      const etag = `"${key}"`;
+      c.header("ETag", etag);
+      c.header("Cache-Control", "private, no-cache");
+      c.header("X-Content-Type-Options", "nosniff");
+      if (c.req.header("If-None-Match") === etag) return c.body(null, 304);
+      let result = cache.get(key);
+      if (result) remember(key, result);
+      else {
+        if (coordinator.protectedKeys().size >= 32) return c.text("thumbnail queue full", 429);
+        result = await coordinator.acquire(key, c.req.raw.signal, async (signal) => {
+          const image = await generateThumbnail(path, signal);
+          remember(key, image);
+          return image;
+        }) ?? void 0;
+      }
+      if (!result) return c.text("image unavailable", 422);
+      c.header("Content-Type", "image/jpeg");
+      return c.body(new Uint8Array(result));
+    } catch (error) {
+      if (error instanceof HTTPException) return error.getResponse();
+      return c.text("image unavailable", 422);
+    }
+  });
+}
+// src/routes/thumbnail.ts
+import {
+  closeSync as closeSync3,
+  fstatSync as fstatSync3,
+  openSync as openSync3,
+  mkdirSync as mkdirSync6,
+  readFileSync as readFileSync12,
+  readdirSync as readdirSync6,
+  renameSync as renameSync3,
+  rmSync as rmSync4,
+  statSync as statSync6,
+  unlinkSync as unlinkSync4,
+  writeFileSync as writeFileSync6
+} from "fs";
+import { join as join13 } from "path";
+import { createHash as createHash6, randomUUID as randomUUID4 } from "crypto";
+// src/helpers/compositionInputs.ts
+import { readFileSync as readFileSync11 } from "fs";
+var ROOT_COMPOSITION = "index.html";
+var COMPOSITION_SRC = /\bdata-composition-src\s*=\s*(["'])(.*?)\1/g;
+function projectReader(projectDir) {
+  const sources = /* @__PURE__ */ new Map();
+  return (compPath) => {
+    if (!sources.has(compPath)) {
+      const file = resolveWithinProject2(projectDir, compPath);
+      let source = null;
+      try {
+        source = file ? readFileSync11(file, "utf-8") : null;
+      } catch {
+      }
+      sources.set(compPath, source);
+    }
+    return sources.get(compPath) ?? null;
+  };
+}
+function normalizeSource(src) {
+  if (/^[a-z][a-z0-9+.-]*:/i.test(src) || src.startsWith("//")) return null;
+  const path = src.split(/[?#]/)[0]?.replace(/^\.?\//, "") ?? "";
+  return path || null;
+}
+function closureOf(read, compPath) {
+  const closure = /* @__PURE__ */ new Set();
+  const visit = (path) => {
+    if (closure.has(path)) return;
+    closure.add(path);
+    for (const match of (read(path) ?? "").matchAll(COMPOSITION_SRC)) {
+      const mounted = normalizeSource(match[2] ?? "");
+      if (mounted) visit(mounted);
+    }
+  };
+  visit(compPath);
+  return closure;
+}
+var inputSignatures = /* @__PURE__ */ new Map();
+function compositionInputSignature(projectDir, compPath, projectSignature) {
+  const key = `${projectDir}\0${compPath}`;
+  const known = inputSignatures.get(key);
+  if (known?.projectSignature === projectSignature) return known.inputSignature;
+  const read = projectReader(projectDir);
+  const inputs = closureOf(read, normalizeSource(compPath) ?? compPath).add(ROOT_COMPOSITION);
+  const siblings = [...closureOf(read, ROOT_COMPOSITION)].filter((path) => !inputs.has(path));
+  const inputSignature = createProjectSignature(projectDir, new Set(siblings));
+  inputSignatures.set(key, { projectSignature, inputSignature });
+  return inputSignature;
+}
+function compositionsAffectedBy(projectDir, changedPath) {
+  const changed = changedPath.replace(/\\/g, "/");
+  const read = projectReader(projectDir);
+  const mounted = closureOf(read, ROOT_COMPOSITION);
+  if (changed === ROOT_COMPOSITION || !mounted.has(changed)) return null;
+  return [...mounted].filter((path) => closureOf(read, path).has(changed));
+}
 // src/routes/thumbnail.ts
 var THUMBNAIL_CACHE_VERSION = "v4";
 var THUMBNAIL_MAX_OUTPUT_WIDTH = 240;
@@ -4482,10 +4751,16 @@ var THUMBNAIL_CACHE_MAX_BYTES = 512 * 1024 * 1024;
 var THUMBNAIL_CACHE_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1e3;
 var prunedCacheDirs = /* @__PURE__ */ new Set();
 function pruneThumbnailCache(cacheDir, protectedPaths, now = Date.now()) {
-  if (!existsSync7(cacheDir)) return;
-  const files = readdirSync6(cacheDir, { withFileTypes: true }).flatMap((entry) => {
+  let entries;
+  try {
+    entries = readdirSync6(cacheDir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === "ENOENT") return;
+    throw err;
+  }
+  const files = entries.flatMap((entry) => {
     if (!entry.isFile()) return [];
-    const path = join12(cacheDir, entry.name);
+    const path = join13(cacheDir, entry.name);
     try {
       const stats = statSync6(path);
       return [{ path, bytes: stats.size, mtimeMs: stats.mtimeMs }];
@@ -4521,22 +4796,30 @@ function writeThumbnailAtomically(path, buffer) {
     rmSync4(temporaryPath, { force: true });
   }
 }
-function readCompositionSource(file) {
+function readFileOnce(file) {
   let fd;
   try {
     fd = openSync3(file, "r");
   } catch (err) {
-    if (err.code === "ENOENT") return "missing";
+    const code = err.code;
+    if (code === "ENOENT") return "missing";
+    if (code === "ENOTDIR") return "not-a-file";
     throw err;
   }
   try {
-    const stat2 = fstatSync3(fd);
-    if (!stat2.isFile()) return "not-a-file";
-    return { html: readFileSync12(fd, "utf-8"), mtimeMs: stat2.mtimeMs };
+    const stat3 = fstatSync3(fd);
+    if (!stat3.isFile()) return "not-a-file";
+    return { data: readFileSync12(fd), mtimeMs: stat3.mtimeMs };
   } finally {
     closeSync3(fd);
   }
 }
+function manifestKey(file) {
+  const manifest = readFileOnce(file);
+  if (typeof manifest === "string") return { key: "", mtimeMs: -Infinity };
+  const hash = createHash6("sha1").update(manifest.data).digest("hex").slice(0, 16);
+  return { key: `_${hash}`, mtimeMs: Math.round(manifest.mtimeMs) };
+}
 function registerThumbnailRoutes(api, adapter) {
   api.get("/projects/:id/thumbnail/*", async (c) => {
     if (!adapter.generateThumbnail) {
@@ -4547,8 +4830,8 @@ function registerThumbnailRoutes(api, adapter) {
     const { project, signature: projectSignature } = resolved;
     let compPath = requestSubPath(c.req.url, "projects/:id/thumbnail");
     if (compPath && !compPath.includes(".")) compPath += ".html";
-    const htmlFile = resolveWithinProject(project.dir, compPath);
-    const source = htmlFile ? readCompositionSource(htmlFile) : "not-a-file";
+    const htmlFile = resolveWithinProject2(project.dir, compPath);
+    const source = htmlFile ? readFileOnce(htmlFile) : "not-a-file";
     if (source === "not-a-file") return c.json({ error: "not found" }, 404);
     const inputSignature = compositionInputSignature(project.dir, compPath, projectSignature);
     const url = new URL(c.req.url, `http://${c.req.header("host") || "localhost"}`);
@@ -4570,8 +4853,8 @@ function registerThumbnailRoutes(api, adapter) {
     let sourceMtime = 0;
     let sourceKey = "";
     if (source !== "missing") {
-      const { html } = source;
-      sourceKey = `_${createHash5("sha1").update(html).digest("hex").slice(0, 16)}`;
+      const html = source.data.toString("utf-8");
+      sourceKey = `_${createHash6("sha1").update(html).digest("hex").slice(0, 16)}`;
       sourceMtime = Math.round(source.mtimeMs);
       if (!vpWidth) {
         const wMatch = html.match(/data-width=["'](\d+)["']/);
@@ -4580,31 +4863,20 @@ function registerThumbnailRoutes(api, adapter) {
         if (hMatch?.[1]) compH = parseInt(hMatch[1]);
       }
     }
-    const manualEditsFile = join12(project.dir, STUDIO_MANUAL_EDITS_PATH);
-    let manualEditsKey = "";
-    if (existsSync7(manualEditsFile)) {
-      const manualEditsContent = readFileSync12(manualEditsFile, "utf-8");
-      manualEditsKey = `_${createHash5("sha1").update(manualEditsContent).digest("hex").slice(0, 16)}`;
-      sourceMtime = Math.max(sourceMtime, Math.round(statSync6(manualEditsFile).mtimeMs));
-    }
-    const motionFile = join12(project.dir, STUDIO_MOTION_PATH);
-    let motionKey = "";
-    if (existsSync7(motionFile)) {
-      const motionContent = readFileSync12(motionFile, "utf-8");
-      motionKey = `_${createHash5("sha1").update(motionContent).digest("hex").slice(0, 16)}`;
-      sourceMtime = Math.max(sourceMtime, Math.round(statSync6(motionFile).mtimeMs));
-    }
+    const manualEdits = manifestKey(join13(project.dir, STUDIO_MANUAL_EDITS_PATH));
+    const motion = manifestKey(join13(project.dir, STUDIO_MOTION_PATH));
+    sourceMtime = Math.max(sourceMtime, manualEdits.mtimeMs, motion.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 = join12(project.dir, ".thumbnails");
+    const cacheDir = join13(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 = `_${createHash5("sha1").update(inputSignature).digest("hex").slice(0, 16)}`;
+    const inputSignatureKey = `_${createHash6("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 = join12(cacheDir, cacheKey);
+    const cacheKey = `${THUMBNAIL_CACHE_VERSION}${urlVersionKey}${inputSignatureKey}${manualEdits.key}${motion.key}${sourceKey}_${format}_${outputMode}_${compPath.replace(/\//g, "_")}_${compW}x${compH}_${outputWidth}x${outputHeight}_${sourceMtime}_${seekTime.toFixed(2)}${selectorKey}.${format === "png" ? "png" : "jpg"}`;
+    const cachePath = join13(cacheDir, cacheKey);
     if (!prunedCacheDirs.has(cacheDir)) {
       prunedCacheDirs.add(cacheDir);
       pruneThumbnailCache(
@@ -4612,8 +4884,9 @@ function registerThumbnailRoutes(api, adapter) {
         /* @__PURE__ */ new Set([...thumbnailGenerationCoordinator.protectedKeys(), cachePath])
       );
     }
-    if (existsSync7(cachePath)) {
-      return new Response(new Uint8Array(readFileSync12(cachePath)), {
+    const cached = readFileOnce(cachePath);
+    if (typeof cached === "object") {
+      return new Response(new Uint8Array(cached.data), {
         headers: { "Content-Type": contentType, "Cache-Control": "no-cache" }
       });
     }
@@ -4643,7 +4916,7 @@ function registerThumbnailRoutes(api, adapter) {
           if (afterGeneration?.project.dir !== project.dir || !inputsUnchanged(afterGeneration.signature) || !inputsUnchanged(createProjectSignature(project.dir))) {
             return generated;
           }
-          if (!existsSync7(cacheDir)) mkdirSync6(cacheDir, { recursive: true });
+          mkdirSync6(cacheDir, { recursive: true });
           writeThumbnailAtomically(cachePath, generated);
           return generated;
         }
@@ -4669,24 +4942,24 @@ function registerThumbnailRoutes(api, adapter) {
 }
 // src/routes/waveform.ts
-import { existsSync as existsSync8, readFileSync as readFileSync13, statSync as statSync7 } from "fs";
-import { join as join13, resolve as resolve5 } from "path";
+import { existsSync as existsSync7, readFileSync as readFileSync13, statSync as statSync7 } from "fs";
+import { join as join14, resolve as resolve6 } from "path";
 import { isWithinProjectRoot as isWithinProjectRoot2 } from "@hyperframes/parsers/asset-resolution";
 function registerWaveformRoutes(api, adapter) {
   api.get("/projects/:id/waveform/*", async (c) => {
     const project = await adapter.resolveProject(c.req.param("id"));
     if (!project) return c.json({ error: "not found" }, 404);
     const assetPath = requestSubPath(c.req.url, "projects/:id/waveform");
-    const audioPath = resolve5(project.dir, assetPath);
+    const audioPath = resolve6(project.dir, assetPath);
     if (!isWithinProjectRoot2(project.dir, audioPath)) {
       return c.json({ error: "file not found" }, 404);
     }
     const stats = statSync7(audioPath, { throwIfNoEntry: false });
     if (!stats) return c.json({ error: "file not found" }, 404);
-    const cacheDir = join13(project.dir, ".waveform-cache");
-    const cachePath = join13(cacheDir, buildWaveformCacheKey(assetPath, stats));
+    const cacheDir = join14(project.dir, ".waveform-cache");
+    const cachePath = join14(cacheDir, buildWaveformCacheKey(assetPath, stats));
     try {
-      if (isWaveformCacheDirectory(cacheDir) && existsSync8(cachePath)) {
+      if (isWaveformCacheDirectory(cacheDir) && existsSync7(cachePath)) {
         const peaks2 = JSON.parse(readFileSync13(cachePath, "utf-8"));
         return c.json({ peaks: peaks2 });
       }
@@ -4819,12 +5092,12 @@ function registerFontRoutes(api) {
       return c.json({ error: "font file not accessible" }, 404);
     }
     try {
-      const stat2 = fstatSync4(fd);
-      if (stat2.size > SYSTEM_FONT_SIZE_LIMIT) {
+      const stat3 = fstatSync4(fd);
+      if (stat3.size > SYSTEM_FONT_SIZE_LIMIT) {
         return c.json({ error: "font file too large" }, 413);
       }
-      const buffer = Buffer.alloc(stat2.size);
-      readSync(fd, buffer, 0, stat2.size, 0);
+      const buffer = Buffer.alloc(stat3.size);
+      readSync(fd, buffer, 0, stat3.size, 0);
       const mimeType = located.format === "otf" ? "font/otf" : located.format === "woff2" ? "font/woff2" : located.format === "woff" ? "font/woff" : located.format === "ttc" ? "font/collection" : "font/ttf";
       const fileName = `${family.replace(/[^a-zA-Z0-9 -]/g, "")}.${located.format}`;
       return new Response(buffer, {
@@ -4852,7 +5125,7 @@ function registerRegistryRoutes(api, adapter) {
   });
   api.post("/projects/:id/registry/install", async (c) => {
     if (!adapter.installRegistryBlock) {
-      return c.json({ error: "Registry install not available" }, 501);
+      return c.json({ error: "Installing catalog items needs hyperframes preview" }, 501);
     }
     const project = await adapter.resolveProject(c.req.param("id"));
     if (!project) return c.json({ error: "Project not found" }, 404);
@@ -4970,8 +5243,8 @@ function registerSelectionRoutes(api, adapter) {
 // src/routes/media.ts
 import { streamSSE as streamSSE2 } from "hono/streaming";
-import { existsSync as existsSync9, mkdirSync as mkdirSync7 } from "fs";
-import { basename as basename2, dirname as dirname5, extname as extname2, join as join14 } from "path";
+import { existsSync as existsSync8, mkdirSync as mkdirSync7 } from "fs";
+import { basename as basename3, dirname as dirname7, extname as extname2, join as join15 } from "path";
 var VIDEO_EXTENSIONS = /* @__PURE__ */ new Set([
   ".mp4",
   ".mov",
@@ -5001,14 +5274,14 @@ function containsNullByte(path) {
   return path.includes("\0");
 }
 function slugFileBase(path) {
-  const name = basename2(path, extname2(path)).replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+  const name = basename3(path, extname2(path)).replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
   return name || "media";
 }
 function uniqueAssetPath(projectDir, assetPath) {
   const ext = extname2(assetPath);
   const withoutExt = assetPath.slice(0, -ext.length);
   let candidate = assetPath;
-  for (let index = 2; existsSync9(join14(projectDir, candidate)); index++) {
+  for (let index = 2; existsSync8(join15(projectDir, candidate)); index++) {
     candidate = `${withoutExt}-${index}${ext}`;
   }
   return candidate;
@@ -5057,9 +5330,9 @@ function registerMediaRoutes(api, adapter, options = {}) {
     if (/^(?:https?:|data:|blob:)/i.test(assetPath)) {
       return c.json({ error: "media metadata requires a project-local asset" }, 400);
     }
-    const filePath = resolveWithinProject(project.dir, assetPath);
+    const filePath = resolveWithinProject2(project.dir, assetPath);
     if (!filePath) return c.json({ error: "forbidden" }, 403);
-    if (!existsSync9(filePath)) return c.json({ error: "media not found" }, 404);
+    if (!existsSync8(filePath)) return c.json({ error: "media not found" }, 404);
     return c.json({ path: assetPath, metadata: await readMediaMetadata(filePath) });
   });
   api.post(
@@ -5079,9 +5352,9 @@ function registerMediaRoutes(api, adapter, options = {}) {
       if (/^(?:https?:|data:|blob:)/i.test(inputAssetPath)) {
         return c.json({ error: "background removal requires a project-local media asset" }, 400);
       }
-      const inputPath = resolveWithinProject(project.dir, inputAssetPath);
+      const inputPath = resolveWithinProject2(project.dir, inputAssetPath);
       if (!inputPath) return c.json({ error: "forbidden" }, 403);
-      if (!existsSync9(inputPath)) return c.json({ error: "input media not found" }, 404);
+      if (!existsSync8(inputPath)) return c.json({ error: "input media not found" }, 404);
       const inputIsVideo = isVideoPath(inputAssetPath);
       const inputIsImage = isImagePath(inputAssetPath);
       if (!inputIsVideo && !inputIsImage) {
@@ -5091,11 +5364,11 @@ function registerMediaRoutes(api, adapter, options = {}) {
       if (requestedOutput && containsNullByte(requestedOutput)) {
         return c.json({ error: "forbidden" }, 403);
       }
-      if (requestedOutput && !resolveWithinProject(project.dir, requestedOutput)) {
+      if (requestedOutput && !resolveWithinProject2(project.dir, requestedOutput)) {
         return c.json({ error: "forbidden" }, 403);
       }
       const outputAssetPath = requestedOutput ? uniqueAssetPath(project.dir, requestedOutput) : defaultOutputPath(project.dir, inputAssetPath);
-      const outputPath = resolveWithinProject(project.dir, outputAssetPath);
+      const outputPath = resolveWithinProject2(project.dir, outputAssetPath);
       if (!outputPath) return c.json({ error: "forbidden" }, 403);
       if (inputIsVideo && !VIDEO_OUTPUT_EXTENSIONS.has(extname2(outputAssetPath).toLowerCase())) {
         return c.json({ error: "video background removal output must be .webm or .mov" }, 400);
@@ -5110,13 +5383,13 @@ function registerMediaRoutes(api, adapter, options = {}) {
           return c.json({ error: "background plates are only supported for video inputs" }, 400);
         }
         backgroundOutputAssetPath = defaultPlatePath(project.dir, inputAssetPath);
-        backgroundOutputPath = resolveWithinProject(project.dir, backgroundOutputAssetPath) ?? void 0;
+        backgroundOutputPath = resolveWithinProject2(project.dir, backgroundOutputAssetPath) ?? void 0;
         if (!backgroundOutputPath) {
           return c.json({ error: "forbidden" }, 403);
         }
       }
-      mkdirSync7(dirname5(outputPath), { recursive: true });
-      if (backgroundOutputPath) mkdirSync7(dirname5(backgroundOutputPath), { recursive: true });
+      mkdirSync7(dirname7(outputPath), { recursive: true });
+      if (backgroundOutputPath) mkdirSync7(dirname7(backgroundOutputPath), { recursive: true });
       const jobId = makeJobId(project.id, mediaJobs);
       const state = adapter.startBackgroundRemoval({
         project,
@@ -5173,12 +5446,12 @@ function registerMediaRoutes(api, adapter, options = {}) {
 }
 // src/routes/globalAssets.ts
-import { existsSync as existsSync10, readFileSync as readFileSync14 } from "fs";
+import { existsSync as existsSync9, readFileSync as readFileSync14 } from "fs";
 import { homedir } from "os";
-import { join as join15 } from "path";
+import { join as join16 } from "path";
 function readGlobalAssets(home = homedir()) {
-  const manifestPath = join15(home, ".media", "manifest.jsonl");
-  if (!existsSync10(manifestPath)) return [];
+  const manifestPath = join16(home, ".media", "manifest.jsonl");
+  if (!existsSync9(manifestPath)) return [];
   const out = [];
   for (const line of readFileSync14(manifestPath, "utf8").split("\n")) {
     if (!line.trim()) continue;
@@ -5199,28 +5472,38 @@ function registerGlobalAssetRoutes(api) {
 // src/history/projectHistory.ts
 import { randomUUID as randomUUID8 } from "crypto";
-import { rm as rm2 } from "fs/promises";
-import { existsSync as existsSync12, mkdirSync as mkdirSync11, readFileSync as readFileSync18 } from "fs";
+import { readdir as readdir2, rm as rm2, rmdir, writeFile } from "fs/promises";
+import {
+  existsSync as existsSync11,
+  lstatSync as lstatSync4,
+  statSync as statSync9,
+  mkdirSync as mkdirSync11,
+  readdirSync as readdirSync7,
+  readFileSync as readFileSync18,
+  realpathSync as realpathSync3,
+  rmSync as rmSync6
+} from "fs";
 import { homedir as homedir2 } from "os";
-import { join as join19, relative as relative4, resolve as resolve7, sep as sep3 } from "path";
+import { dirname as dirname10, isAbsolute as isAbsolute3, join as join20, relative as relative6, resolve as resolve8, sep as sep4 } from "path";
 // src/history/blobStore.ts
-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 join16 } from "path";
+import { createHash as createHash7, randomUUID as randomUUID5 } from "crypto";
+import { constants as constants3, createReadStream as createReadStream2, renameSync as renameSync4 } from "fs";
+import { copyFile, mkdir, readdir, readFile as readFile2, rename, rm, stat as stat2 } from "fs/promises";
+import { dirname as dirname8, join as join17 } from "path";
 var BLOB_HASH = /^[0-9a-f]{64}$/;
 async function hashFile(path) {
-  const hash = createHash6("sha256");
+  const hash = createHash7("sha256");
   for await (const chunk of createReadStream2(path)) hash.update(chunk);
   return hash.digest("hex");
 }
-async function cloneOrCopy(from, to) {
-  await mkdir(dirname6(to), { recursive: true });
+async function cloneOrCopy(from, to, beforeReplace) {
+  await mkdir(dirname8(to), { recursive: true });
   const temp = `${to}.${randomUUID5()}.tmp`;
   try {
     await copyFile(from, temp, constants3.COPYFILE_FICLONE);
-    await rename(temp, to);
+    beforeReplace?.();
+    renameSync4(temp, to);
   } catch (error) {
     await rm(temp, { force: true });
     throw error;
@@ -5230,16 +5513,16 @@ 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(join16(dir, shard)).catch(() => []))
-      sizes.set(hash, (await stat(join16(dir, shard, hash))).size);
+    for (const hash of await readdir(join17(dir, shard)).catch(() => []))
+      sizes.set(hash, (await stat2(join17(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);
+    return join17(dir, hash.slice(0, 2), hash);
   };
   let total = [...sizes.values()].reduce((sum, size) => sum + size, 0);
   return {
     async put(absPath) {
-      const temp = join16(dir, `incoming-${randomUUID5()}`);
+      const temp = join17(dir, `incoming-${randomUUID5()}`);
       await mkdir(dir, { recursive: true });
       await copyFile(absPath, temp, constants3.COPYFILE_FICLONE);
       const hash = await hashFile(temp);
@@ -5247,8 +5530,8 @@ async function openBlobStore(dir) {
         await rm(temp, { force: true });
         return hash;
       }
-      await mkdir(dirname6(pathOf(hash)), { recursive: true });
-      const size = (await stat(temp)).size;
+      await mkdir(dirname8(pathOf(hash)), { recursive: true });
+      const size = (await stat2(temp)).size;
       await rename(temp, pathOf(hash));
       sizes.set(hash, size);
       total += size;
@@ -5256,7 +5539,7 @@ async function openBlobStore(dir) {
     },
     has: (hash) => sizes.has(hash),
     read: async (hash) => readFile2(pathOf(hash)),
-    writeTo: async (hash, absPath) => cloneOrCopy(pathOf(hash), absPath),
+    writeTo: async (hash, absPath, beforeReplace) => cloneOrCopy(pathOf(hash), absPath, beforeReplace),
     bytes: () => total,
     size: (hash) => sizes.get(hash) ?? 0,
     async prune(keep) {
@@ -5272,44 +5555,50 @@ async function openBlobStore(dir) {
 // src/history/historyId.ts
 import { randomUUID as randomUUID6 } from "crypto";
-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");
+import { existsSync as existsSync10, mkdirSync as mkdirSync8, readFileSync as readFileSync15, statSync as statSync8, writeFileSync as writeFileSync7 } from "fs";
+import { join as join18, resolve as resolve7 } from "path";
+var ID_PATH = join18(".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 = readFileSync15(join17(projectDir, ID_PATH), "utf-8").trim();
+    const id = readFileSync15(join18(projectDir, ID_PATH), "utf-8").trim();
     return ID_SHAPE.test(id) ? id : null;
   } catch {
     return null;
   }
 }
-function recordedDir(historyDir) {
+var sameFolder = (a, b) => a.ino === b.ino && a.birthtimeMs === b.birthtimeMs;
+function isRecordedFolder(historyDir, folder) {
   try {
-    return JSON.parse(readFileSync15(join17(historyDir, "project.json"), "utf-8")).dir ?? null;
+    const was = JSON.parse(readFileSync15(join18(historyDir, "project.json"), "utf-8"));
+    return sameFolder({ ino: was.ino, birthtimeMs: was.born }, folder);
   } catch {
-    return null;
+    return false;
   }
 }
 function projectHistoryId(projectDir, historyRoot) {
-  const dir = resolve6(projectDir);
+  const dir = resolve7(projectDir);
+  const folder = statSync8(dir);
   let id = readId(dir);
-  const was = id && recordedDir(join17(historyRoot, id));
-  if (!id || was && was !== dir && existsSync11(was) && readId(was) === id) {
+  if (!id || existsSync10(join18(historyRoot, id)) && !isRecordedFolder(join18(historyRoot, id), folder)) {
     id = randomUUID6();
-    mkdirSync8(join17(dir, ".hyperframes"), { recursive: true });
-    writeFileSync7(join17(dir, ID_PATH), `${id}
+    mkdirSync8(join18(dir, ".hyperframes"), { recursive: true });
+    writeFileSync7(join18(dir, ID_PATH), `${id}
 `);
   }
-  mkdirSync8(join17(historyRoot, id), { recursive: true });
-  writeFileSync7(join17(historyRoot, id, "project.json"), JSON.stringify({ dir }));
+  recordProject(join18(historyRoot, id), dir, folder);
   return id;
 }
+function recordProject(historyDir, dir, folder) {
+  const record = { dir, ino: folder.ino, born: folder.birthtimeMs };
+  mkdirSync8(historyDir, { recursive: true });
+  replaceFileAtomically(join18(historyDir, "project.json"), JSON.stringify(record), 420);
+}
 // 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";
+import { join as join19 } from "path";
 var HistoryBusyError = class extends Error {
   constructor(pid) {
     super(`This project's history is open in another process (pid ${pid}).`);
@@ -5368,7 +5657,7 @@ function evictDeadOwner(file) {
   }
 }
 async function takeHistoryOwnership(home, waitMs) {
-  const file = join18(home, "owner.pid");
+  const file = join19(home, "owner.pid");
   const deadline = Date.now() + waitMs;
   mkdirSync9(home, { recursive: true });
   for (; ; ) {
@@ -5389,7 +5678,7 @@ async function takeHistoryOwnership(home, waitMs) {
 // 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";
+import { dirname as dirname9 } from "path";
 var START = "start";
 function parseRecord(line) {
   try {
@@ -5441,21 +5730,25 @@ function writeLog(file, log) {
     ...log.entries.map((entry) => ({ type: "entry", entry })),
     ...[...log.pins].map((id) => ({ type: "pin", id, pinned: true }))
   ];
-  mkdirSync10(dirname7(file), { recursive: true });
+  mkdirSync10(dirname9(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 applyEntry(manifest, entry, side) {
+  for (const file of entry.files) {
+    const hash = file[side];
+    if (hash === null) manifest.delete(file.path);
+    else manifest.set(file.path, hash);
+  }
 }
 function manifestAt(log, point) {
+  return point === START ? new Map(log.baseline) : manifestAround(log, point, "after");
+}
+function manifestAround(log, id, side) {
   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;
+    applyEntry(manifest, entry, entry.id === id ? side : "after");
+    if (entry.id === id) return manifest;
   }
   return null;
 }
@@ -5467,24 +5760,35 @@ function undoneIds(entries) {
   }
   return undone;
 }
-function stepTarget(entries, direction) {
+function stepTarget(entries, direction, mine) {
   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 owns = ownerOf2(entries, byId, mine);
+  const newestFirst = [...entries].reverse();
+  if (direction === "back")
+    return newestFirst.find((entry) => !entry.undoes && !undone.has(entry.id) && owns(entry));
+  for (const entry of newestFirst) {
+    if (!entry.undoes) {
+      if (owns(entry)) return void 0;
+      continue;
+    }
     const target = byId.get(entry.undoes);
-    if (!undone.has(entry.id) && target && !target.undoes) return entry;
+    if (mine(entry) && !undone.has(entry.id) && target && !target.undoes) return entry;
   }
   return void 0;
 }
+function ownerOf2(entries, byId, mine) {
+  const redoneBy = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const target = entry.undoes ? byId.get(entry.undoes) : void 0;
+    if (target?.undoes) redoneBy.set(target.undoes, entry);
+  }
+  return (entry) => mine(entry) || mine(redoneBy.get(entry.id) ?? entry);
+}
 function foldOldest(log) {
   const oldest = log.entries[0];
   if (!oldest || log.pins.has(oldest.id)) return false;
-  applyEntry(log.baseline, oldest);
+  applyEntry(log.baseline, oldest, "after");
   log.entries.shift();
   return true;
 }
@@ -5499,8 +5803,9 @@ function referencedHashes(log, current) {
 }
 // src/history/projectHistory.ts
-var DEFAULT_HISTORY_ROOT = join19(homedir2(), ".cache", "hyperframes", "history");
+var DEFAULT_HISTORY_ROOT = join20(homedir2(), ".cache", "hyperframes", "history");
 var MAX_WINDOW_IDLE_MS = 10 * 6e4;
+var UNDO_MODES = ["just-this", "back-to-before", "keep-later-edits"];
 var OUTSIDE = { kind: "outside", name: "Outside" };
 var OUTSIDE_LABEL = "Changed outside the app";
 var RACY_MS = 2e3;
@@ -5514,6 +5819,33 @@ function splitAt(change, at, kept) {
     { ...change, before: at }
   ];
 }
+var isMissingFolder = (error) => ["ENOENT", "ENOTDIR"].includes(error.code ?? "");
+async function removeEmptyFolders(dir) {
+  let entries;
+  try {
+    entries = await readdir2(dir, { withFileTypes: true });
+  } catch (error) {
+    if (isMissingFolder(error)) return;
+    throw error;
+  }
+  for (const entry of entries)
+    if (entry.isDirectory()) await removeEmptyFolders(join20(dir, entry.name));
+  await rmdir(dir);
+}
+function fileLeftIn(dir, at, deleted) {
+  for (const entry of readdirSync7(dir, { withFileTypes: true })) {
+    const path = `${at}/${entry.name}`;
+    const left = entry.isDirectory() ? fileLeftIn(join20(dir, entry.name), path, deleted) : deleted.has(path) ? void 0 : path;
+    if (left) return left;
+  }
+  return void 0;
+}
+function ignoresCase(dir) {
+  const self = statSync9(join20(dir, ID_PATH), { throwIfNoEntry: false });
+  const other = statSync9(join20(dir, ID_PATH.toUpperCase()), { throwIfNoEntry: false });
+  return self !== void 0 && other?.ino === self.ino && other.dev === self.dev;
+}
+var blocks = (removed, added) => added.startsWith(`${removed}/`) || removed.startsWith(`${added}/`);
 var takesWrite = (window, at) => window.idleMs === void 0 || at - (window.lastWriteAt ?? at) <= window.idleMs;
 function addChange(group, path, before, after) {
   const earlier = group.changes.get(path);
@@ -5526,19 +5858,26 @@ var Engine = class {
     this.options = options;
     this.projectId = projectId;
     this.blobs = blobs;
-    this.dir = resolve7(options.projectDir);
-    this.home = join19(options.historyRoot, projectId);
+    this.dir = resolve8(options.projectDir);
+    this.home = join20(options.historyRoot, projectId);
+    this.foldsCase = ignoresCase(this.dir);
+    const folder = statSync9(this.dir, { throwIfNoEntry: false });
+    if (!folder || readId(this.dir) !== projectId || !isRecordedFolder(this.home, folder))
+      throw this.replaced();
+    this.folder = { dev: folder.dev, ino: folder.ino, birthtimeMs: folder.birthtimeMs };
   }
   options;
   projectId;
   blobs;
   dir;
+  foldsCase;
+  folder;
   home;
   log = { baseline: /* @__PURE__ */ new Map(), entries: [], pins: /* @__PURE__ */ new Set() };
   tracked = /* @__PURE__ */ new Map();
   windows = [];
   outside = null;
-  /** A coalescing claim, open until another key, its idle timer, or an operation commits it. */
+  /** A coalescing claim, open until another key, its idle timer, an operation, a window, or another write. */
   claimed = null;
   writeToken;
   quietTimer;
@@ -5546,18 +5885,51 @@ var Engine = class {
   notedTimer = null;
   listeners = /* @__PURE__ */ new Set();
   tail = Promise.resolve();
+  closed = false;
+  closing;
+  /** A path as the project's disk compares names: folded where `A` and `a` are one name. */
+  nameKey(path) {
+    return this.foldsCase ? path.toLowerCase() : path;
+  }
   get logFile() {
-    return join19(this.home, "log.jsonl");
+    return join20(this.home, "log.jsonl");
   }
   now() {
     return (this.options.now ?? Date.now)();
   }
   /** One operation at a time, in order: sweeps, windows and undos never interleave. */
   queue(task) {
+    if (this.closed)
+      return Promise.reject(new HistoryClosedError("This project's history is closed."));
     const run = this.tail.then(task);
     this.tail = run.catch(() => void 0);
     return run;
   }
+  /** Another project if the folder or its id changed, or the id is gone: a recreated folder may reuse the inode. */
+  whereFolder() {
+    const now = statSync9(this.dir, { throwIfNoEntry: false });
+    if (!now) return "gone";
+    const same = now.dev === this.folder.dev && sameFolder(now, this.folder);
+    return same && readId(this.dir) === this.projectId ? "here" : "replaced";
+  }
+  assertWritable() {
+    const folder = this.whereFolder();
+    if (folder === "gone") throw new Error(`The project folder is gone: ${this.dir}`);
+    if (folder === "replaced") throw this.replaced();
+  }
+  persistLog(record) {
+    if (record) saveRecord(this.logFile, this.log, record);
+    else writeLog(this.logFile, this.log);
+    if (!existsSync11(join20(this.home, "project.json")))
+      recordProject(this.home, this.dir, this.folder);
+  }
+  replaced() {
+    return new HistoryClosedError(`${this.dir} is now another project.`);
+  }
+  assertOpen() {
+    if (this.closed) throw new HistoryClosedError("This project's history is closed.");
+    if (this.whereFolder() === "replaced") throw this.replaced();
+  }
   async start() {
     const log = readLog(
       this.logFile,
@@ -5574,9 +5946,7 @@ var Engine = class {
       this.tracked.set(path, { hash, stat: cached?.hash === hash ? cached.stat : "" });
     }
     this.reopenClosedWindow();
-    await this.sweep();
-    for (const window of [...this.windows]) await this.endWindow(window);
-    await this.commitOutside();
+    await this.settleAll();
   }
   reopenClosedWindow() {
     const closed = this.options.closedWindow;
@@ -5586,13 +5956,13 @@ var Engine = class {
   }
   async firstOpen() {
     const sweptAt = Date.now();
-    for (const file of listProjectFiles(this.dir))
-      this.tracked.set(file.path, {
-        hash: await this.blobs.put(join19(this.dir, file.path)),
-        stat: statKey(file, sweptAt)
-      });
+    for (const file of listProjectFiles(this.dir)) {
+      const hash = await this.storeIfPresent(file.path);
+      if (this.whereFolder() !== "here") throw this.replaced();
+      if (hash !== null) this.tracked.set(file.path, { hash, stat: statKey(file, sweptAt) });
+    }
     this.log.baseline = this.manifest();
-    writeLog(this.logFile, this.log);
+    this.persistLog();
     this.saveStatCache();
   }
   manifest() {
@@ -5600,7 +5970,7 @@ var Engine = class {
   }
   readStatCache() {
     try {
-      const files = JSON.parse(readFileSync18(join19(this.home, "stat.json"), "utf-8"));
+      const files = JSON.parse(readFileSync18(join20(this.home, "stat.json"), "utf-8"));
       return new Map(Object.entries(files));
     } catch {
       return /* @__PURE__ */ new Map();
@@ -5609,26 +5979,39 @@ var Engine = class {
   saveStatCache() {
     const files = JSON.stringify(Object.fromEntries(this.tracked));
     mkdirSync11(this.home, { recursive: true });
-    replaceFileAtomically(join19(this.home, "stat.json"), files, 420);
+    replaceFileAtomically(join20(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
    * project (a stat per file, a hash only when the stat moved); per-path sweeps if projects reach tens of thousands.
    */
   async sweep() {
-    if (!existsSync12(this.dir)) return;
+    if (this.whereFolder() !== "here") return;
     const sweptAt = Date.now();
     const changedAt = (file) => Math.min(sweptAt, Math.max(file.mtimeMs, file.ctimeMs));
-    const seen = listProjectFiles(this.dir).sort((a, b) => changedAt(a) - changedAt(b));
-    let changed = false;
-    for (const file of seen)
-      changed = await this.observe(file.path, statKey(file, sweptAt), changedAt(file)) || changed;
+    const seen = listProjectFiles(this.dir);
     const present = new Set(seen.map((file) => file.path));
-    for (const [path, known] of this.tracked) {
-      if (present.has(path)) continue;
+    const removed = [...this.tracked.keys()].filter((path) => !present.has(path)).map((path) => {
+      const standing = this.standingAt(path);
+      return { at: standing ? changedAt(standing.stat) : sweptAt, path, file: null };
+    });
+    const appearedAt = (file) => Math.max(
+      changedAt(file),
+      ...removed.filter((gone) => blocks(this.nameKey(gone.path), this.nameKey(file.path))).map((gone) => gone.at)
+    );
+    const events = [
+      ...removed,
+      ...seen.map((file) => ({ at: appearedAt(file), path: file.path, file }))
+    ].sort((a, b) => a.at - b.at);
+    let changed = false;
+    for (const { at, path, file } of events) {
+      if (file) {
+        changed = await this.observe(path, statKey(file, sweptAt), at) || changed;
+        continue;
+      }
+      const known = this.tracked.get(path);
       this.tracked.delete(path);
-      const removedAt = sweptAt;
-      await this.record(path, known.hash, null, removedAt);
+      await this.record(path, known.hash, null, at);
       changed = true;
     }
     if (changed) this.saveStatCache();
@@ -5636,23 +6019,23 @@ 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(join19(this.dir, path));
+      return await this.blobs.put(join20(this.dir, path));
     } catch (error) {
       if (error.code === "ENOENT") return null;
       throw error;
     }
   }
-  async observe(path, stat2, at) {
+  async observe(path, stat3, at) {
     const known = this.tracked.get(path) ?? { hash: null, stat: null };
-    if (stat2 && known.stat === stat2) return false;
+    if (stat3 && known.stat === stat3) return false;
     const hash = await this.storeIfPresent(path);
-    if (hash === null) return false;
-    this.tracked.set(path, { hash, stat: stat2 });
+    if (hash === null || this.whereFolder() !== "here") return false;
+    this.tracked.set(path, { hash, stat: stat3 });
     if (known.hash !== hash) await this.record(path, known.hash, hash, at);
-    return known.hash !== hash || known.stat !== stat2;
+    return known.hash !== hash || known.stat !== stat3;
   }
   async record(path, before, after, at) {
-    const endedBeforeThisWrite = this.windows.filter((open) => !takesWrite(open, at));
+    const endedBeforeThisWrite = this.windows.filter((open2) => !takesWrite(open2, at));
     if (endedBeforeThisWrite.length) await this.commitOutside();
     for (const window2 of endedBeforeThisWrite) await this.endWindow(window2);
     const window = this.windows.at(-1);
@@ -5662,28 +6045,34 @@ var Engine = class {
   /** 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, cut } = this.takeClaimed(who, paths, overwrote);
-    if (!taken.length) {
-      if (coalesceKey !== this.claimed?.key) await this.commitClaim();
-      return null;
-    }
+    const taken = await this.takeClaimed(who, paths, overwrote);
+    if (!taken.length) return this.claimNothing(coalesceKey);
     const held = this.heldFor(coalesceKey, taken);
     if (!held) await this.commitClaim();
-    await this.commitOlder(cut);
+    await this.commitPending();
     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 };
   }
-  async commitOlder(cut) {
-    if (this.outside) cut.delete(this.outside);
+  /** A claim that took nothing still ends a held claim under another key. */
+  async claimNothing(coalesceKey) {
+    if (coalesceKey !== this.claimed?.key) await this.commitClaim();
+    return null;
+  }
+  /** Commits every other writer's pending changes, oldest first; open windows stay open. */
+  async commitPending() {
     await this.commitOutside();
-    for (const [window, paths] of cut) await this.commitCut(window, paths);
+    for (const window of [...this.windows])
+      if (window.changes.size) await this.commitCut(window, [...window.changes.keys()]);
+  }
+  pendingElsewhere() {
+    return Boolean(this.outside?.changes.size) || this.windows.some((open2) => open2.changes.size > 0);
   }
   /** 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 group = key && this.claimed?.key === key && !this.pendingElsewhere() ? this.claimed.group : null;
     const after = (path, before) => {
       const own = group?.changes.get(path);
       return own ? own.after : before;
@@ -5693,10 +6082,10 @@ var Engine = class {
     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("/");
+    return relative6(this.dir, resolve8(this.dir, path)).split(sep4).join("/");
   }
-  /** Takes `paths`' uncommitted changes from others, cut at what `who` overwrote; `cut`: paths each group keeps. */
-  takeClaimed(who, paths, overwrote) {
+  /** Takes `paths`' uncommitted changes from others, cut at what `who` overwrote. */
+  async takeClaimed(who, paths, overwrote) {
     const wanted = new Set(paths.map((path) => this.logPath(path)));
     const at = new Map(
       Object.entries(overwrote).map(([path, version]) => [
@@ -5704,25 +6093,52 @@ var Engine = class {
         hashOfVersion(version)
       ])
     );
-    const others = this.windows.filter((open) => !sameWho(open.who, who));
+    const others = this.windows.filter((open2) => !sameWho(open2.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]);
-      }
+    const hits = groups.flatMap(
+      (group) => [...group.changes.values()].filter((change) => wanted.has(change.path)).map((change) => ({ group, change }))
+    );
+    const cuts = [];
+    const walked = hits.map(() => /* @__PURE__ */ new Set());
+    for (const [i, { change }] of hits.entries()) {
+      const told = at.get(change.path);
+      cuts.push(await this.overwrittenBy(change, told, walked[i]) ?? told);
+    }
+    hits.forEach(
+      ({ change }, i) => forgetOverwrittenBytes(
+        join20(this.dir, change.path),
+        new Set([...walked[i]].map(hashVersion))
+      )
+    );
+    return hits.flatMap(({ group, change }, i) => this.cutOut(group, change, cuts[i]) ?? []);
+  }
+  /** Walks the server's writes back from `change.after` to the bytes they replaced, stored so an undo restores them. */
+  async overwrittenBy(change, told, seen) {
+    const absPath = join20(this.dir, change.path);
+    let bytes;
+    for (let hash = change.after; hash; ) {
+      if (seen.has(hash)) return void 0;
+      seen.add(hash);
+      const replaced = bytesOverwrittenBy(absPath, hashVersion(hash));
+      if (replaced === void 0) break;
+      bytes = replaced;
+      hash = hashOfVersion(fileContentVersion(replaced));
+      if (hash === change.before || hash === told) return hash;
+    }
+    if (bytes === void 0) return void 0;
+    const staged = join20(this.home, `overwrote-${randomUUID8()}`);
+    await writeFile(staged, bytes);
+    try {
+      return await this.blobs.put(staged);
+    } finally {
+      await rm2(staged, { force: true });
     }
-    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];
+    return 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. */
@@ -5736,8 +6152,8 @@ var Engine = class {
   }
   holdClaim(group, key, idleMs = this.options.quietMs ?? 2e3) {
     clearTimeout(this.claimed?.timer);
-    const timer = setTimeout(() => this.background(() => this.commitClaim()), idleMs);
-    timer.unref?.();
+    const timer = Number.isFinite(idleMs) ? setTimeout(() => this.background(() => this.commitClaim()), idleMs) : void 0;
+    timer?.unref?.();
     this.claimed = { group, key, timer };
     return group.changes.size ? { id: group.id } : null;
   }
@@ -5767,6 +6183,7 @@ var Engine = class {
     return { id: randomUUID8(), who, label, startedAt: this.now(), changes: /* @__PURE__ */ new Map() };
   }
   async commitOutside() {
+    if (this.outside?.changes.size) await this.commitClaim();
     clearTimeout(this.quietTimer);
     clearTimeout(this.maxTimer);
     const group = this.outside;
@@ -5775,14 +6192,12 @@ var Engine = class {
   }
   async commit(group, extra = {}) {
     if (!group.changes.size) return null;
-    const { id, who, label, startedAt, lastWriteAt, changes } = group;
-    const files = [...changes.values()].sort((a, b) => a.path.localeCompare(b.path));
-    const previousEnd = this.log.entries.at(-1)?.endedAt ?? 0;
-    const endedAt = Math.max(lastWriteAt ?? this.now(), previousEnd);
-    const entry = { id, who, label, startedAt, endedAt, files, ...extra };
+    const pending = this.pendingEntry(group);
+    const endedAt = Math.max(pending.endedAt, this.log.entries.at(-1)?.endedAt ?? 0);
+    const entry = { ...pending, endedAt, ...extra };
     this.log.entries.push(entry);
     try {
-      saveRecord(this.logFile, this.log, { type: "entry", entry });
+      this.persistLog({ type: "entry", entry });
     } catch (error) {
       this.log.entries.pop();
       throw error;
@@ -5803,19 +6218,28 @@ var Engine = class {
     let folded = false;
     while (this.historyBytes() > budget && foldOldest(this.log)) {
       folded = true;
-      await this.blobs.prune(referencedHashes(this.log, this.manifest()));
+      await this.blobs.prune(
+        /* @__PURE__ */ new Set([...referencedHashes(this.log, this.manifest()), ...this.pendingHashes()])
+      );
     }
-    if (folded) writeLog(this.logFile, this.log);
+    if (folded) this.persistLog();
+  }
+  /** Hashes only pending changes point at yet, such as a claim's stored cut. */
+  pendingHashes() {
+    const changes = [...this.windows, this.outside, this.claimed?.group].flatMap((group) => [
+      ...group?.changes.values() ?? []
+    ]);
+    return changes.flatMap((change) => [change.before, change.after]).filter((hash) => hash !== null);
   }
-  /** Before an operation: every write so far is filed, and the outside group is closed so it sorts first. */
+  /** Before an operation or a window: every write is filed and every pending change committed, in write order. */
   async settle() {
     await this.sweep();
     await this.commitClaim();
-    await this.commitOutside();
+    await this.commitPending();
   }
   /** A watcher saw a write: one sweep per burst takes it in (a deleted folder is reported by its name alone). */
   noteChange(path) {
-    if (this.notedTimer || !affectsProjectSignature(this.dir, resolve7(this.dir, path))) return;
+    if (this.notedTimer || !affectsProjectSignature(this.dir, resolve8(this.dir, path))) return;
     this.notedTimer = setTimeout(() => {
       this.notedTimer = null;
       this.background(() => this.sweep());
@@ -5823,11 +6247,13 @@ var Engine = class {
     this.notedTimer.unref?.();
   }
   background(task) {
-    this.queue(task).catch((error) => this.options.onError?.(error));
+    this.queue(task).catch((error) => {
+      if (!(error instanceof HistoryClosedError)) this.options.onError?.(error);
+    });
   }
   beginWindow(who, label, idleMs) {
     return this.queue(async () => {
-      await this.sweep();
+      await this.settle();
       const window = { ...this.newGroup(who, label), idleMs };
       this.windows.push(window);
       this.touch(window, Date.now());
@@ -5854,7 +6280,8 @@ var Engine = class {
   async endWindow(window) {
     if (!this.windows.includes(window)) return window.entry ?? null;
     clearTimeout(window.idleTimer);
-    this.windows = this.windows.filter((open) => open !== window);
+    await this.commitClaim();
+    this.windows = this.windows.filter((open2) => open2 !== window);
     window.entry = await this.commit(window) ?? window.entry ?? null;
     return window.entry;
   }
@@ -5865,31 +6292,61 @@ var Engine = class {
     for (const window of [...this.windows]) await this.endWindow(window);
     await this.commitOutside();
   }
+  /** What took a removed path's place, dating its removal: an entry at the path, or a file at a folder above it. */
+  standingAt(path) {
+    const parts = path.split("/");
+    for (let depth = 1; depth <= parts.length; depth += 1) {
+      const at = parts.slice(0, depth).join("/");
+      const stat3 = lstatSync4(join20(this.dir, at), { throwIfNoEntry: false });
+      if (!stat3) return void 0;
+      if (at === path || !stat3.isDirectory()) return { at, stat: stat3 };
+    }
+    return void 0;
+  }
+  /** What a write of `path` would have to delete: a file or link at or above it, or a file in a folder at it. */
+  inTheWay(path, deleted) {
+    const standing = this.standingAt(path);
+    if (!standing) return void 0;
+    if (standing.stat.isSymbolicLink()) return standing.at;
+    if (standing.at === path && !standing.stat.isDirectory()) return void 0;
+    const real = realpathSync3.native(join20(this.dir, standing.at));
+    const at = relative6(realpathSync3.native(this.dir), real).split(sep4).join("/");
+    if (standing.at !== path) return deleted.has(at) ? void 0 : at;
+    return fileLeftIn(real, at, deleted);
+  }
   /** Writes `target` (path to hash, null deletes) as one entry of `who`'s. */
   async writeAs(who, label, target, extra) {
+    this.assertWritable();
+    const changes = [...target].filter(([path, hash]) => (this.tracked.get(path)?.hash ?? null) !== hash).sort(([, a], [, b]) => Number(a !== null) - Number(b !== null));
+    const deleted = new Set(changes.filter(([, hash]) => hash === null).map(([path]) => path));
+    const blocked = changes.filter(([, hash]) => hash !== null).map(([path]) => this.inTheWay(path, deleted)).find(Boolean);
+    if (blocked) throw new Error(`${blocked} is in the way; move or delete it, then try again.`);
     const group = this.newGroup(who, label);
     this.windows.push(group);
     try {
-      for (const [path, hash] of target) {
-        if ((this.tracked.get(path)?.hash ?? null) !== hash)
-          await this.writeProjectFile(path, hash);
-      }
+      for (const [path, hash] of changes) await this.writeProjectFile(path, hash);
       await this.sweep();
     } finally {
-      this.windows = this.windows.filter((open) => open !== group);
+      this.windows = this.windows.filter((open2) => open2 !== group);
     }
     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);
+    this.assertWritable();
+    const absPath = join20(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);
+    if (hash === null) {
+      this.assertWritable();
+      rmSync6(absPath, { force: true });
+    } else {
+      await removeEmptyFolders(absPath);
+      await this.blobs.writeTo(hash, absPath, () => this.assertWritable());
+    }
   }
   entry(id) {
     const entry = this.log.entries.find((candidate) => candidate.id === id);
@@ -5913,7 +6370,9 @@ var Engine = class {
         entry: await this.restoreNow(point, who, `Went back to before: ${entry.label}`)
       };
     }
-    const target = new Map(entry.files.map((file) => [file.path, file.before]));
+    const target = new Map(
+      entry.files.filter((file) => mode !== "keep-later-edits" || !changed.includes(file)).map((file) => [file.path, file.before])
+    );
     return {
       ok: true,
       entry: await this.writeAs(who, this.undoLabel(entry), target, { undoes: id })
@@ -5922,15 +6381,19 @@ var Engine = class {
   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;
+  next(direction, who) {
+    const mine = (author) => sameWho(author, who) || sameWho(author, OUTSIDE);
+    const pending = [...[...this.windows].reverse(), this.outside, this.claimed?.group].find(
+      (group) => group?.changes.size && mine(group.who)
+    );
+    if (pending) return direction === "back" ? this.pendingEntry(pending) : void 0;
+    return stepTarget(this.log.entries, direction, (entry) => mine(entry.who));
+  }
+  /** A pending group as the entry it becomes once committed (a window's part gets a fresh id). */
+  pendingEntry(group) {
+    const files = [...group.changes.values()].sort((a, b) => a.path.localeCompare(b.path));
+    const { id, who, label, startedAt, lastWriteAt } = group;
+    return { id, who, label, startedAt, endedAt: lastWriteAt ?? this.now(), files };
   }
   conflict(entry, changed) {
     const paths = new Set(changed.map((file) => file.path));
@@ -5967,8 +6430,11 @@ var Engine = class {
       projectId: this.projectId,
       beginWindow: (who, label, options = {}) => this.beginWindow(who, label, options.idleMs ?? this.options.maxGroupMs ?? 3e4),
       claim: (who, label, paths, options = {}) => this.queue(() => this.claimNow(who, label, paths, options)),
-      noteChange: (path) => this.noteChange(path),
+      noteChange: (path) => {
+        if (!this.closed) this.noteChange(path);
+      },
       list: () => {
+        this.assertOpen();
         const undone = undoneIds(this.log.entries);
         return this.log.entries.map((entry) => ({
           ...entry,
@@ -5977,7 +6443,7 @@ var Engine = class {
         }));
       },
       step: (direction, who, { writeToken } = {}) => this.operation(writeToken, async () => {
-        const target = this.next(direction);
+        const target = this.next(direction, who);
         return target ? this.undoNow(target.id, who) : { ok: true, entry: null };
       }),
       undo: (id, { who, mode, writeToken }) => this.operation(writeToken, () => this.undoNow(id, who, mode)),
@@ -5986,37 +6452,83 @@ var Engine = class {
         () => this.restoreNow(point, who, `Restored: ${this.pointLabel(point)}`)
       ),
       peek: (point) => {
+        this.assertOpen();
         const files = manifestAt(this.log, point);
         return files && Object.fromEntries(files);
       },
-      next: (direction) => this.next(direction),
-      readBlob: (hash) => this.blobs.read(hash),
+      checkout: (entryId, side, emptyDir) => this.queue(async () => {
+        this.entry(entryId);
+        if (!existsSync11(this.dir)) throw new Error(`The project folder is gone: ${this.dir}`);
+        const dest = resolve8(emptyDir);
+        if (isWithin(this.dir, dest))
+          throw new Error(`Checkout writes outside the project only: ${dest}`);
+        if ((await readdir2(dest).catch(missingIsEmpty)).length > 0)
+          throw new Error(`Checkout writes into an empty folder only: ${dest}`);
+        const files = manifestAround(this.log, entryId, side);
+        try {
+          for (const [path, hash] of files) await this.blobs.writeTo(hash, join20(dest, path));
+        } catch (error) {
+          for (const name of await readdir2(dest).catch(() => []))
+            await rm2(join20(dest, name), { recursive: true, force: true });
+          throw error;
+        }
+      }),
+      next: (direction, who) => {
+        this.assertOpen();
+        return this.next(direction, who);
+      },
+      readBlob: async (hash) => {
+        this.assertOpen();
+        return this.blobs.read(hash);
+      },
       pin: (id, pinned) => {
+        this.assertOpen();
         this.entry(id);
         if (pinned) this.log.pins.add(id);
         else this.log.pins.delete(id);
-        saveRecord(this.logFile, this.log, { type: "pin", id, pinned });
+        this.persistLog({ type: "pin", id, pinned });
       },
       onEntry: (listener) => {
         this.listeners.add(listener);
         return () => this.listeners.delete(listener);
       },
       flush: () => this.queue(() => this.settleAll()),
-      close: async () => {
+      replacedAtPath: () => this.whereFolder() === "replaced",
+      close: () => this.closing ??= (async () => {
         if (this.notedTimer) clearTimeout(this.notedTimer);
-        await this.queue(() => this.settleAll());
-      }
+        const settled = this.queue(() => this.settleAll());
+        this.closed = true;
+        await settled;
+      })()
     };
   }
 };
+function isWithin(dir, path) {
+  let probe = resolve8(path);
+  while (!existsSync11(probe) && dirname10(probe) !== probe) probe = dirname10(probe);
+  const rel = relative6(realpathSync3.native(dir), realpathSync3.native(probe));
+  return rel === "" || rel !== ".." && !rel.startsWith(`..${sep4}`) && !isAbsolute3(rel);
+}
+function missingIsEmpty(error) {
+  if (error.code === "ENOENT") return [];
+  throw error;
+}
+var HistoryClosedError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "HistoryClosedError";
+  }
+};
 async function openProjectHistory(options) {
+  if (!existsSync11(options.projectDir))
+    throw new HistoryClosedError(`${options.projectDir} is gone or now another project.`);
   const projectId = projectHistoryId(options.projectDir, options.historyRoot);
   const release = await takeHistoryOwnership(
-    join19(options.historyRoot, projectId),
+    join20(options.historyRoot, projectId),
     options.ownerWaitMs ?? 5e3
   );
   try {
-    const blobs = await openBlobStore(join19(options.historyRoot, projectId, "blobs"));
+    const blobs = await openBlobStore(join20(options.historyRoot, projectId, "blobs"));
     const engine = new Engine(options, projectId, blobs);
     await engine.queue(() => engine.start());
     const api = engine.api();
@@ -6062,7 +6574,7 @@ function versionsOf(value) {
   return pairs.length ? Object.fromEntries(pairs) : void 0;
 }
 function nextStep(history, direction) {
-  const target = history.next(direction);
+  const target = history.next(direction, YOU);
   if (!target) return null;
   const paths = target.files.map((file) => file.path);
   return { id: target.id, label: target.label, endedAt: target.endedAt, paths };
@@ -6097,7 +6609,7 @@ function registerHistoryRoutes(api, adapter) {
   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;
+      const mode = UNDO_MODES.find((known) => known === body.mode);
       return history.undo(text(body.entryId) ?? "", { who: whoOf(body), mode, ...writing(c) });
     })
   );
@@ -6133,11 +6645,9 @@ function registerHistoryRoutes(api, adapter) {
     (c) => withHistory(adapter, c, async (history, body) => {
       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 },
+        ...coalesceKey && { coalesceKey, idleMs: idleOf(body) ?? Infinity },
         ...overwrote && { overwrote }
       });
       return { claimed };
@@ -6177,6 +6687,7 @@ function createStudioApi(adapter) {
   registerLintRoutes(api, adapter);
   registerRenderRoutes(api, adapter);
   registerThumbnailRoutes(api, adapter);
+  registerImageThumbnailRoutes(api, adapter);
   registerSelectionRoutes(api, adapter);
   registerMediaRoutes(api, adapter);
   registerWaveformRoutes(api, adapter);
@@ -6187,7 +6698,32 @@ function createStudioApi(adapter) {
   return api;
 }
+// src/history/historyCache.ts
+function historyCache(open2) {
+  const histories = /* @__PURE__ */ new Map();
+  const get = async (projectDir) => {
+    let cached = histories.get(projectDir);
+    if (!cached) histories.set(projectDir, cached = open2(projectDir));
+    const opened = await cached;
+    if (!opened?.replacedAtPath()) return opened;
+    const reopen = () => open2(projectDir);
+    if (histories.get(projectDir) === cached)
+      histories.set(projectDir, opened.close().then(reopen, reopen));
+    return get(projectDir);
+  };
+  return {
+    get,
+    /** The history if one was opened, without opening it. */
+    peek: (projectDir) => histories.get(projectDir),
+    forget: (projectDir) => histories.delete(projectDir),
+    closeAll: () => Promise.all(
+      [...histories.values()].map((opened) => opened.then((history) => history?.close()))
+    )
+  };
+}
 // src/helpers/duplicateElement.ts
+import { sameInstant } from "@hyperframes/core/clip-facts";
 import { ensureHfIds as ensureHfIds4 } from "@hyperframes/parsers/hf-ids";
 function duplicateElementInHtml(source, target, newId, at) {
   const { document, wrappedFragment } = parseSourceDocument(source);
@@ -6222,9 +6758,10 @@ function rippleElements(document, element, at, duration, track) {
       continue;
     }
     const start = numericAttribute(candidate, "data-start");
-    if (start !== null && start >= at) {
-      candidate.setAttribute("data-start", String(start + duration));
-    }
+    if (start === null) continue;
+    const metInsertionPoint = sameInstant(start, at);
+    if (start < at && !metInsertionPoint) continue;
+    candidate.setAttribute("data-start", String((metInsertionPoint ? at : start) + duration));
   }
 }
 function stripStableIds(element) {
@@ -6239,11 +6776,11 @@ function numericAttribute(element, name) {
 }
 // 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";
+import { createHash as createHash8 } from "crypto";
+import { mkdirSync as mkdirSync12, readFileSync as readFileSync19, readdirSync as readdirSync8, rmSync as rmSync7 } from "fs";
+import { join as join21 } from "path";
 function createPreviewDocumentStore(dir, salt) {
-  const fileFor = (key) => join20(dir, `${createHash7("sha256").update(`${salt}
+  const fileFor = (key) => join21(dir, `${createHash8("sha256").update(`${salt}
 ${key}`).digest("hex").slice(0, 32)}.html`);
   return {
     read(key) {
@@ -6258,8 +6795,8 @@ ${key}`).digest("hex").slice(0, 32)}.html`);
         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 });
+        for (const name of readdirSync8(dir)) {
+          if (join21(dir, name) !== file) rmSync7(join21(dir, name), { force: true });
         }
       } catch {
       }
@@ -6339,11 +6876,14 @@ export {
   DELETED_VERSION,
   START as HISTORY_START,
   HistoryBusyError,
+  HistoryClosedError,
   MAX_WINDOW_IDLE_MS,
   MIME_TYPES,
   PREVIEW_BUNDLE_OPTIONS,
   STUDIO_MANUAL_EDITS_PATH,
   STUDIO_MOTION_PATH,
+  UNDO_MODES,
+  affectsPreview,
   affectsProjectSignature,
   applyFileMutations,
   buildSubCompositionHtml,
@@ -6362,6 +6902,7 @@ export {
   findTargetElement,
   getElementScreenshotClip,
   getMimeType,
+  historyCache,
   identifyFileWrite,
   isSafePath,
   openProjectHistory,