@hyperframes/studio-server 0.8.78 → 0.8.79

package/dist/index.js

@@ -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;
@@ -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);
@@ -753,22 +769,38 @@ 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,
@@ -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") {
@@ -3348,6 +3432,7 @@ import { Readable } from "stream";
 import { join as join9, resolve as resolve4 } 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(
@@ -3744,7 +3827,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) => ({
@@ -3794,6 +3878,7 @@ ${runtimeTag}`;
         mainCompositionPath,
         mediaCodecProbeCache
       );
+      bundled = addScenePartsManifest(bundled, [`meta[name="${PROJECT_SIGNATURE_META}"]`]);
       rememberPreview(builtKey, bundled);
       adapter.previewDocuments?.write(builtKey, bundled);
       return bundled;
@@ -3871,7 +3956,7 @@ ${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 || !existsSync5(compFile) || !statSync4(compFile).isFile()) {
       return c.text("not found", 404);
     }
@@ -4105,7 +4190,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;
@@ -4238,7 +4323,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);
@@ -4322,7 +4407,7 @@ function projectReader(projectDir) {
   const sources = /* @__PURE__ */ new Map();
   return (compPath) => {
     if (!sources.has(compPath)) {
-      const file = resolveWithinProject(projectDir, compPath);
+      const file = resolveWithinProject2(projectDir, compPath);
       let source = null;
       try {
         source = file ? readFileSync11(file, "utf-8") : null;
@@ -4547,7 +4632,7 @@ 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 htmlFile = resolveWithinProject2(project.dir, compPath);
     const source = htmlFile ? readCompositionSource(htmlFile) : "not-a-file";
     if (source === "not-a-file") return c.json({ error: "not found" }, 404);
     const inputSignature = compositionInputSignature(project.dir, compPath, projectSignature);
@@ -4971,7 +5056,7 @@ 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 { basename as basename3, dirname as dirname6, extname as extname2, join as join14 } from "path";
 var VIDEO_EXTENSIONS = /* @__PURE__ */ new Set([
   ".mp4",
   ".mov",
@@ -5001,7 +5086,7 @@ 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) {
@@ -5057,7 +5142,7 @@ 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);
     return c.json({ path: assetPath, metadata: await readMediaMetadata(filePath) });
@@ -5079,7 +5164,7 @@ 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);
       const inputIsVideo = isVideoPath(inputAssetPath);
@@ -5091,11 +5176,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 +5195,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(dirname6(outputPath), { recursive: true });
+      if (backgroundOutputPath) mkdirSync7(dirname6(backgroundOutputPath), { recursive: true });
       const jobId = makeJobId(project.id, mediaJobs);
       const state = adapter.startBackgroundRemoval({
         project,
@@ -5199,28 +5284,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 existsSync12,
+  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 dirname9, isAbsolute as isAbsolute3, join as join19, relative as relative5, resolve as resolve7, 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 { constants as constants3, createReadStream as createReadStream2, renameSync as renameSync4 } 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 { dirname as dirname7, join as join16 } from "path";
 var BLOB_HASH = /^[0-9a-f]{64}$/;
 async function hashFile(path) {
   const hash = createHash6("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(dirname7(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;
@@ -5247,7 +5342,7 @@ async function openBlobStore(dir) {
         await rm(temp, { force: true });
         return hash;
       }
-      await mkdir(dirname6(pathOf(hash)), { recursive: true });
+      await mkdir(dirname7(pathOf(hash)), { recursive: true });
       const size = (await stat(temp)).size;
       await rename(temp, pathOf(hash));
       sizes.set(hash, size);
@@ -5256,7 +5351,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,7 +5367,7 @@ 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 { existsSync as existsSync11, mkdirSync as mkdirSync8, readFileSync as readFileSync15, statSync as statSync8, writeFileSync as writeFileSync7 } from "fs";
 import { join as join17, resolve as resolve6 } from "path";
 var ID_PATH = join17(".hyperframes", "history-id");
 var ID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
@@ -5284,27 +5379,33 @@ function readId(projectDir) {
     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(join17(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 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 || existsSync11(join17(historyRoot, id)) && !isRecordedFolder(join17(historyRoot, id), folder)) {
     id = randomUUID6();
     mkdirSync8(join17(dir, ".hyperframes"), { recursive: true });
     writeFileSync7(join17(dir, ID_PATH), `${id}
 `);
   }
-  mkdirSync8(join17(historyRoot, id), { recursive: true });
-  writeFileSync7(join17(historyRoot, id, "project.json"), JSON.stringify({ dir }));
+  recordProject(join17(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(join17(historyDir, "project.json"), JSON.stringify(record), 420);
+}
 
 // src/history/ownerLock.ts
 import { randomUUID as randomUUID7 } from "crypto";
@@ -5389,7 +5490,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 dirname8 } from "path";
 var START = "start";
 function parseRecord(line) {
   try {
@@ -5441,21 +5542,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(dirname8(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 +5572,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;
 }
@@ -5501,6 +5617,7 @@ function referencedHashes(log, current) {
 // src/history/projectHistory.ts
 var DEFAULT_HISTORY_ROOT = join19(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 +5631,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(join19(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(join19(dir, entry.name), path, deleted) : deleted.has(path) ? void 0 : path;
+    if (left) return left;
+  }
+  return void 0;
+}
+function ignoresCase(dir) {
+  const self = statSync9(join19(dir, ID_PATH), { throwIfNoEntry: false });
+  const other = statSync9(join19(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);
@@ -5528,17 +5672,24 @@ var Engine = class {
     this.blobs = blobs;
     this.dir = resolve7(options.projectDir);
     this.home = join19(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,6 +5697,12 @@ 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");
   }
@@ -5554,10 +5711,37 @@ var Engine = class {
   }
   /** 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 (!existsSync12(join19(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 +5758,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 +5768,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() {
@@ -5616,19 +5798,32 @@ var Engine = class {
    * 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();
@@ -5646,7 +5841,7 @@ var Engine = class {
     const known = this.tracked.get(path) ?? { hash: null, stat: null };
     if (stat2 && known.stat === stat2) return false;
     const hash = await this.storeIfPresent(path);
-    if (hash === null) return false;
+    if (hash === null || this.whereFolder() !== "here") return false;
     this.tracked.set(path, { hash, stat: stat2 });
     if (known.hash !== hash) await this.record(path, known.hash, hash, at);
     return known.hash !== hash || known.stat !== stat2;
@@ -5662,28 +5857,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((open) => open.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 +5894,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 relative5(this.dir, resolve7(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]) => [
@@ -5706,23 +5907,50 @@ var Engine = class {
     );
     const others = this.windows.filter((open) => !sameWho(open.who, who));
     const groups = this.outside ? [this.outside, ...others] : others;
-    const taken = [];
-    const cut = /* @__PURE__ */ new Map();
-    for (const group of groups) {
-      for (const change of [...group.changes.values()]) {
-        if (!wanted.has(change.path)) continue;
-        const [kept, claimed] = this.cutOut(group, change, at.get(change.path));
-        if (claimed) taken.push(claimed);
-        if (kept && claimed) cut.set(group, [...cut.get(group) ?? [], change.path]);
-      }
+    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(
+        join19(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 = join19(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 = join19(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 +5964,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 +5995,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 +6004,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,15 +6030,24 @@ 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) {
@@ -5823,11 +6059,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,6 +6092,7 @@ var Engine = class {
   async endWindow(window) {
     if (!this.windows.includes(window)) return window.entry ?? null;
     clearTimeout(window.idleTimer);
+    await this.commitClaim();
     this.windows = this.windows.filter((open) => open !== window);
     window.entry = await this.commit(window) ?? window.entry ?? null;
     return window.entry;
@@ -5865,15 +6104,39 @@ 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 stat2 = lstatSync4(join19(this.dir, at), { throwIfNoEntry: false });
+      if (!stat2) return void 0;
+      if (at === path || !stat2.isDirectory()) return { at, stat: stat2 };
+    }
+    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(join19(this.dir, standing.at));
+    const at = relative5(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);
@@ -5882,14 +6145,20 @@ var Engine = class {
   }
   /** Writes one project file (null deletes it), first leaving the running operation's receipt for its echo. */
   async writeProjectFile(path, hash) {
+    this.assertWritable();
     const absPath = join19(this.dir, path);
     const { writeToken } = this;
     if (writeToken) {
       const version = hash === null ? DELETED_VERSION : hashVersion(hash);
       recordFileWriteReceipt(absPath, { path, version, writeToken });
     }
-    if (hash === null) await rm2(absPath, { force: true });
-    else await this.blobs.writeTo(hash, absPath);
+    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 +6182,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 +6193,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 +6242,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 +6255,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,30 +6264,76 @@ 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 (!existsSync12(this.dir)) throw new Error(`The project folder is gone: ${this.dir}`);
+        const dest = resolve7(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, join19(dest, path));
+        } catch (error) {
+          for (const name of await readdir2(dest).catch(() => []))
+            await rm2(join19(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 = resolve7(path);
+  while (!existsSync12(probe) && dirname9(probe) !== probe) probe = dirname9(probe);
+  const rel = relative5(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 (!existsSync12(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),
@@ -6062,7 +6386,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 +6421,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 +6457,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 };
@@ -6187,6 +6509,30 @@ function createStudioApi(adapter) {
   return api;
 }
 
+// src/history/historyCache.ts
+function historyCache(open) {
+  const histories = /* @__PURE__ */ new Map();
+  const get = async (projectDir) => {
+    let cached = histories.get(projectDir);
+    if (!cached) histories.set(projectDir, cached = open(projectDir));
+    const opened = await cached;
+    if (!opened?.replacedAtPath()) return opened;
+    const reopen = () => open(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 { ensureHfIds as ensureHfIds4 } from "@hyperframes/parsers/hf-ids";
 function duplicateElementInHtml(source, target, newId, at) {
@@ -6240,7 +6586,7 @@ 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 { mkdirSync as mkdirSync12, readFileSync as readFileSync19, readdirSync as readdirSync8, rmSync as rmSync7 } from "fs";
 import { join as join20 } from "path";
 function createPreviewDocumentStore(dir, salt) {
   const fileFor = (key) => join20(dir, `${createHash7("sha256").update(`${salt}
@@ -6258,8 +6604,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 (join20(dir, name) !== file) rmSync7(join20(dir, name), { force: true });
         }
       } catch {
       }
@@ -6339,11 +6685,13 @@ 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,
   affectsProjectSignature,
   applyFileMutations,
   buildSubCompositionHtml,
@@ -6362,6 +6710,7 @@ export {
   findTargetElement,
   getElementScreenshotClip,
   getMimeType,
+  historyCache,
   identifyFileWrite,
   isSafePath,
   openProjectHistory,