@hyperframes/studio-server 0.8.158 → 0.8.160

package/dist/{chunk-66HD2HFT.js → chunk-SZF3L5MT.js}

@@ -10,16 +10,16 @@ import { randomUUID as randomUUID7 } from "crypto";
 import { mkdir as mkdir2, readdir as readdir3, rm as rm3, rmdir, writeFile } from "fs/promises";
 import {
   existsSync as existsSync3,
-  lstatSync as lstatSync3,
+  lstatSync as lstatSync4,
   statSync as statSync4,
-  mkdirSync as mkdirSync4,
-  readdirSync as readdirSync3,
-  readFileSync as readFileSync9,
+  mkdirSync as mkdirSync5,
+  readdirSync as readdirSync4,
+  readFileSync as readFileSync10,
   realpathSync,
-  rmSync as rmSync2
+  rmSync as rmSync3
 } from "fs";
 import { homedir } from "os";
-import { dirname as dirname4, isAbsolute as isAbsolute5, join as join7, relative as relative4, resolve as resolve6, sep as sep4 } from "path";
+import { dirname as dirname5, isAbsolute as isAbsolute5, join as join8, relative as relative5, resolve as resolve7, sep as sep5 } from "path";
 import { replaceFileAtomically as replaceFileAtomically5 } from "@hyperframes/core/atomic-file";
 
 // src/helpers/fileVersion.ts
@@ -411,9 +411,10 @@ function createProjectSignature(projectDir, excluding = /* @__PURE__ */ new Set(
 
 // src/history/blobStore.ts
 import { createHash as createHash3, randomUUID as randomUUID3 } from "crypto";
-import { constants, createReadStream, renameSync } from "fs";
+import { constants, createReadStream, createWriteStream, renameSync } from "fs";
 import { copyFile, mkdir, readdir, readFile, rename, rm, stat } from "fs/promises";
 import { dirname, join as join2 } from "path";
+import { pipeline } from "stream/promises";
 import { atomicTempPath } from "@hyperframes/core/atomic-file";
 var BLOB_HASH = /^[0-9a-f]{64}$/;
 function blobPath(dir, hash) {
@@ -426,6 +427,14 @@ async function hashFile(path) {
   for await (const chunk of createReadStream(path)) hash.update(chunk);
   return hash.digest("hex");
 }
+async function cloneOrStream(from, to) {
+  try {
+    await copyFile(from, to, constants.COPYFILE_FICLONE_FORCE);
+  } catch {
+    const { mode } = await stat(from);
+    await pipeline(createReadStream(from), createWriteStream(to, { mode }));
+  }
+}
 async function cloneOrCopy(from, to, beforeReplace) {
   await mkdir(dirname(to), { recursive: true });
   const temp = atomicTempPath(to);
@@ -450,7 +459,10 @@ async function openBlobStore(dir) {
     async put(absPath) {
       const temp = join2(dir, `incoming-${randomUUID3()}`);
       await mkdir(dir, { recursive: true });
-      await copyFile(absPath, temp, constants.COPYFILE_FICLONE);
+      await cloneOrStream(absPath, temp).catch(async (error) => {
+        await rm(temp, { force: true });
+        throw error;
+      });
       const hash = await hashFile(temp);
       if (sizes.has(hash)) {
         await rm(temp, { force: true });
@@ -704,8 +716,8 @@ function pruneGoneProjectHistoriesDaily(historyRoot, now, { onError, budgetMs }
 
 // src/history/videoState.ts
 import { createHash as createHash5, randomUUID as randomUUID6 } from "crypto";
-import { createReadStream as createReadStream2, existsSync as existsSync2, readFileSync as readFileSync7, renameSync as renameSync3, statSync as statSync3 } from "fs";
-import { isAbsolute as isAbsolute4, join as join6, resolve as resolve5 } from "path";
+import { createReadStream as createReadStream2, existsSync as existsSync2, readFileSync as readFileSync8, renameSync as renameSync3, statSync as statSync3 } from "fs";
+import { isAbsolute as isAbsolute4, join as join7, resolve as resolve6 } from "path";
 import { replaceFileAtomically as replaceFileAtomically3 } from "@hyperframes/core/atomic-file";
 
 // src/history/artifactCleanup.ts
@@ -824,6 +836,253 @@ function finishArtifactCleanup(projectDir, state) {
   updateLatest(state);
 }
 
+// src/history/snapshotRuns.ts
+import {
+  closeSync as closeSync2,
+  constants as constants3,
+  fstatSync as fstatSync2,
+  lstatSync as lstatSync3,
+  openSync as openSync2,
+  mkdirSync as mkdirSync3,
+  readFileSync as readFileSync7,
+  readdirSync as readdirSync3,
+  rmSync as rmSync2,
+  ftruncateSync,
+  writeSync,
+  writeFileSync as writeFileSync4
+} from "fs";
+import { dirname as dirname3, join as join6, relative as relative4, resolve as resolve5, sep as sep4 } from "path";
+var SNAPSHOT_RUNS_TO_KEEP = 10;
+var SNAPSHOT_GRACE_MS = 24 * 60 * 60 * 1e3;
+var OWNER = ".capture-owner.json";
+var ownedMarkers = /* @__PURE__ */ new Map();
+var UUID = /^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/i;
+var rootOf = (project) => join6(resolve5(project), ".hyperframes", "artifacts", "snapshots");
+function ordinaryPath(project, path) {
+  const root = resolve5(project);
+  const rel = relative4(root, path);
+  if (rel === ".." || rel.startsWith(`..${sep4}`)) return false;
+  let current = root;
+  for (const part of rel.split(sep4).filter(Boolean)) {
+    current = join6(current, part);
+    try {
+      if (lstatSync3(current).isSymbolicLink()) return false;
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+function createSnapshotParents(project, path) {
+  let parent = resolve5(project);
+  for (const part of relative4(parent, path).split(sep4).filter(Boolean)) {
+    parent = join6(parent, part);
+    try {
+      mkdirSync3(parent);
+    } catch (error) {
+      if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw error;
+    }
+    if (!ordinaryPath(project, parent)) throw new Error("Snapshot storage must not use symlinks.");
+  }
+}
+function ownSnapshotRun(project, path) {
+  const root = rootOf(project);
+  if (dirname3(path) !== root || !UUID.test(path.slice(root.length + 1))) return;
+  createSnapshotParents(project, root);
+  mkdirSync3(path);
+  const marker = join6(path, OWNER);
+  const fd = openSync2(marker, "wx");
+  try {
+    writeFileSync4(fd, JSON.stringify({ version: 1, pid: process.pid }));
+    ownedMarkers.set(marker, fstatSync2(fd));
+  } finally {
+    closeSync2(fd);
+  }
+}
+function missingFile(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function retainedOutput(path) {
+  try {
+    lstatSync3(join6(path, ".user-output"));
+    return true;
+  } catch (error) {
+    return !missingFile(error);
+  }
+}
+function processIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return !(error instanceof Error && "code" in error && error.code === "ESRCH");
+  }
+}
+function ownerPid(owner) {
+  if (!owner || typeof owner !== "object" || !("pid" in owner)) return null;
+  const pid = owner.pid;
+  return typeof pid === "number" && Number.isSafeInteger(pid) && pid > 0 ? pid : null;
+}
+function ordinaryOwner(stat2) {
+  return stat2.isFile() && stat2.nlink === 1;
+}
+function sameOwnerFile(before, current) {
+  return current.dev === before.dev && current.ino === before.ino;
+}
+function openOwner(marker, access) {
+  const fd = openSync2(marker, access | (constants3.O_NOFOLLOW ?? 0) | (constants3.O_NONBLOCK ?? 0));
+  try {
+    const current = fstatSync2(fd);
+    const named = lstatSync3(marker);
+    if (!ordinaryOwner(current) || !ordinaryOwner(named) || !sameOwnerFile(named, current))
+      throw new Error("Snapshot owner changed while opening.");
+    return fd;
+  } catch (error) {
+    closeSync2(fd);
+    throw error;
+  }
+}
+function readOwner(marker) {
+  const fd = openOwner(marker, constants3.O_RDONLY);
+  try {
+    return JSON.parse(readFileSync7(fd, "utf8"));
+  } finally {
+    closeSync2(fd);
+  }
+}
+function releasedOwner(owner) {
+  return !!owner && typeof owner === "object" && "released" in owner && owner.released === true && ownerPid(owner) !== null;
+}
+function liveOwner(path) {
+  if (retainedOutput(path)) return true;
+  try {
+    const marker = join6(path, OWNER);
+    const owner = readOwner(marker);
+    if (releasedOwner(owner)) return false;
+    const pid = ownerPid(owner);
+    return pid === null || processIsAlive(pid);
+  } catch (error) {
+    return !missingFile(error);
+  }
+}
+function recordsOf(state) {
+  return [...Object.values(state.snapshots.revisions).flat(), ...state.snapshots.unversioned];
+}
+function containingRun(root, path) {
+  if (!path) return null;
+  const name = relative4(root, resolve5(path)).split(sep4)[0];
+  return name && UUID.test(name) ? join6(root, name) : null;
+}
+function keepContainingRun(keep, root, path) {
+  const run = containingRun(root, path);
+  if (run) keep.add(run);
+}
+function protectedRuns(root, state, records2) {
+  const keep = /* @__PURE__ */ new Set();
+  for (const revision of [state.currentRevision, ...state.renders?.retainedRevisions ?? []]) {
+    const latest2 = records2.filter((record) => record.revision === revision && record.status !== "cleaned").sort((a, b) => b.createdAt - a.createdAt)[0];
+    keepContainingRun(keep, root, latest2?.image);
+  }
+  const latest = records2.find((record) => record.id === state.snapshots.latest?.id);
+  keepContainingRun(keep, root, latest?.image);
+  for (const item of state.pendingArtifactCleanup ?? []) keepContainingRun(keep, root, item.path);
+  return keep;
+}
+function runsOnDisk(root) {
+  let entries;
+  try {
+    entries = readdirSync3(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries.filter((entry) => entry.isDirectory() && UUID.test(entry.name)).flatMap((entry) => {
+    const path = join6(root, entry.name);
+    try {
+      const stat2 = lstatSync3(path);
+      return [{ path, stat: stat2 }];
+    } catch {
+      return [];
+    }
+  }).sort((a, b) => b.stat.mtimeMs - a.stat.mtimeMs || a.path.localeCompare(b.path));
+}
+function planSnapshotCleanup(project, state, now = Date.now()) {
+  const root = rootOf(project);
+  if (!ordinaryPath(project, root)) return [];
+  const records2 = recordsOf(state);
+  const keep = protectedRuns(root, state, records2);
+  const runs = runsOnDisk(root);
+  for (const run of runs.slice(0, SNAPSHOT_RUNS_TO_KEEP)) keep.add(run.path);
+  const pending = [];
+  for (const { path, stat: stat2 } of runs) {
+    if (keep.has(path) || now - stat2.mtimeMs < SNAPSHOT_GRACE_MS || liveOwner(path)) continue;
+    try {
+      const run = { path, dev: stat2.dev, ino: stat2.ino, mtimeMs: stat2.mtimeMs };
+      if (!unchangedRun(project, run)) continue;
+      pending.push(run);
+      retireReferences(records2, root, path);
+    } catch {
+    }
+  }
+  return pending;
+}
+function retireReferences(records2, root, path) {
+  for (const record of records2) {
+    if (containingRun(root, record.image) !== path) continue;
+    delete record.image;
+    record.status = "cleaned";
+  }
+}
+function unchangedRun(project, run) {
+  if (!ordinaryPath(project, run.path)) return false;
+  const current = lstatSync3(run.path);
+  return current.isDirectory() && current.dev === run.dev && current.ino === run.ino && current.mtimeMs === run.mtimeMs;
+}
+function finishSnapshotCleanup(project, runs) {
+  for (const run of runs) {
+    try {
+      if (!unchangedRun(project, run) || liveOwner(run.path)) continue;
+      rmSync2(run.path, { recursive: true });
+    } catch {
+    }
+  }
+}
+function releaseSnapshotRun(project, path) {
+  const marker = join6(path, OWNER);
+  const expected = ownedMarkers.get(marker);
+  if (!expected) return;
+  try {
+    if (dirname3(path) !== rootOf(project) || !ordinaryPath(project, path)) return;
+    const fd = openOwner(marker, constants3.O_RDWR);
+    try {
+      if (!sameOwnerFile(expected, fstatSync2(fd))) return;
+      const owner = JSON.parse(readFileSync7(fd, "utf8"));
+      if (ownerPid(owner) !== process.pid) return;
+      ftruncateSync(fd, 0);
+      writeSync(fd, JSON.stringify({ version: 1, pid: process.pid, released: true }), 0, "utf8");
+    } finally {
+      closeSync2(fd);
+    }
+  } catch {
+  } finally {
+    ownedMarkers.delete(marker);
+  }
+}
+function retainSnapshotOutput(project, path) {
+  const root = rootOf(project);
+  const run = containingRun(root, path);
+  if (!run) return;
+  createSnapshotParents(project, resolve5(path));
+  try {
+    writeFileSync4(
+      join6(run, ".user-output"),
+      "Explicit --output; retained until manual cleanup.\n",
+      { flag: "wx" }
+    );
+  } catch (error) {
+    if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw error;
+  }
+}
+
 // src/history/videoState.ts
 function statePath(dir) {
   const path = pinProjectRecord(dir, ".hyperframes/video-state.json");
@@ -843,7 +1102,7 @@ var emptyState = () => ({
 });
 function readState(dir) {
   if (!existsSync2(statePath(dir))) return emptyState();
-  const state = JSON.parse(readFileSync7(statePath(dir), "utf8"));
+  const state = JSON.parse(readFileSync8(statePath(dir), "utf8"));
   if (state.version !== 1 || !state.checks || !state.snapshots || !state.revisions || !state.files)
     throw new Error("Unsupported video-state schema.");
   return state;
@@ -868,7 +1127,7 @@ async function updateState(dir, update) {
   }
 }
 async function writeHistoryState(projectDir, historyId, historyDirectory, entries, currentFiles, committedFiles) {
-  const blob = (hash) => hash === null ? null : resolve5(historyDirectory, "blobs", hash.slice(0, 2), hash);
+  const blob = (hash) => hash === null ? null : resolve6(historyDirectory, "blobs", hash.slice(0, 2), hash);
   await updateState(projectDir, (state) => {
     if (state.historyId && state.historyId !== historyId) {
       state.checks = collection();
@@ -920,7 +1179,7 @@ async function fileHashes(dir) {
   const files = {};
   for (const { path } of listProjectFiles(dir).sort((a, b) => a.path.localeCompare(b.path))) {
     const hash = createHash5("sha256");
-    for await (const chunk of createReadStream2(join6(dir, path))) hash.update(chunk);
+    for await (const chunk of createReadStream2(join7(dir, path))) hash.update(chunk);
     files[path] = hash.digest("hex");
   }
   return files;
@@ -943,10 +1202,11 @@ async function recordArtifacts(projectDir, capture, artifactsToRecord) {
   for (const artifact of artifactsToRecord) {
     const path = artifact.kind === "check" ? artifact.report : artifact.image;
     if (!path || !isAbsolute4(path)) throw new Error("Artifact needs an absolute output path.");
-    hashes.set(artifact.id, createHash5("sha256").update(readFileSync7(path)).digest("hex"));
+    hashes.set(artifact.id, createHash5("sha256").update(readFileSync8(path)).digest("hex"));
   }
   const after = await beginArtifactCapture(projectDir);
   const unchanged = after.fingerprint === capture.fingerprint;
+  let cleanup = [];
   await updateState(projectDir, (state) => {
     const revision = unchanged ? knownRevision(state, capture.revision) : null;
     const attribution = attributionOf(unchanged, revision);
@@ -968,7 +1228,9 @@ async function recordArtifacts(projectDir, capture, artifactsToRecord) {
       records2.push(record);
       artifacts.latest = { revision, id: record.id };
     }
+    cleanup = planSnapshotCleanup(projectDir, state);
   });
+  finishSnapshotCleanup(projectDir, cleanup);
   return records2;
 }
 function knownRevision(state, revision) {
@@ -996,7 +1258,7 @@ function listsOf(artifacts) {
   return [...Object.values(artifacts.revisions), artifacts.unversioned];
 }
 async function forgetRecordedArtifacts(projectDir, paths) {
-  const gone = new Set(paths.map((path) => resolve5(path)));
+  const gone = new Set(paths.map((path) => resolve6(path)));
   if (gone.size === 0) return;
   await updateState(projectDir, (state) => {
     for (const artifacts of [state.checks, state.snapshots]) {
@@ -1004,7 +1266,7 @@ async function forgetRecordedArtifacts(projectDir, paths) {
         for (let i = list.length - 1; i >= 0; i--) {
           const record = list[i];
           const path = record.image ?? record.report;
-          if (path && gone.has(resolve5(path))) list.splice(i, 1);
+          if (path && gone.has(resolve6(path))) list.splice(i, 1);
         }
       }
       if (artifacts.latest && !listsOf(artifacts).some(
@@ -1016,7 +1278,9 @@ async function forgetRecordedArtifacts(projectDir, paths) {
   });
 }
 function artifactDirectory(projectDir, kind) {
-  return join6(resolve5(projectDir), ".hyperframes", "artifacts", kind, randomUUID6());
+  const path = join7(resolve6(projectDir), ".hyperframes", "artifacts", kind, randomUUID6());
+  if (kind === "snapshots") ownSnapshotRun(projectDir, path);
+  return path;
 }
 function retainRevision(retained, revision) {
   if (!revision) return [...retained];
@@ -1030,7 +1294,7 @@ async function recordRenderSuccess(projectDir, output, status = "completed", cap
   const record = {
     id: randomUUID6(),
     completedAt: Date.now(),
-    output: resolve5(output),
+    output: resolve6(output),
     status
   };
   const unchanged = Boolean(capture && after?.fingerprint === capture.fingerprint);
@@ -1048,10 +1312,18 @@ async function recordRenderSuccess(projectDir, output, status = "completed", cap
   });
   return record;
 }
+async function finishSnapshotRun(projectDir, path) {
+  releaseSnapshotRun(projectDir, path);
+  let cleanup = [];
+  await updateState(projectDir, (state) => {
+    cleanup = planSnapshotCleanup(projectDir, state);
+  });
+  finishSnapshotCleanup(projectDir, cleanup);
+}
 
 // src/history/historyLog.ts
-import { closeSync as closeSync2, constants as constants3, mkdirSync as mkdirSync3, openSync as openSync2, readFileSync as readFileSync8, writeSync } from "fs";
-import { dirname as dirname3 } from "path";
+import { closeSync as closeSync3, constants as constants4, mkdirSync as mkdirSync4, openSync as openSync3, readFileSync as readFileSync9, writeSync as writeSync2 } from "fs";
+import { dirname as dirname4 } from "path";
 import { replaceFileAtomically as replaceFileAtomically4 } from "@hyperframes/core/atomic-file";
 var START = "start";
 function parseRecord(line) {
@@ -1064,7 +1336,7 @@ function parseRecord(line) {
 function readLog(file, onUnreadable) {
   let text;
   try {
-    text = readFileSync8(file, "utf-8");
+    text = readFileSync9(file, "utf-8");
   } catch {
     return null;
   }
@@ -1088,16 +1360,16 @@ function applyRecord(log, record) {
 function saveRecord(file, log, record) {
   let fd;
   try {
-    fd = openSync2(file, constants3.O_WRONLY | constants3.O_APPEND);
+    fd = openSync3(file, constants4.O_WRONLY | constants4.O_APPEND);
   } catch (error) {
     if (error.code !== "ENOENT") throw error;
     return writeLog(file, log);
   }
   try {
-    writeSync(fd, `${JSON.stringify(record)}
+    writeSync2(fd, `${JSON.stringify(record)}
 `);
   } finally {
-    closeSync2(fd);
+    closeSync3(fd);
   }
 }
 function baselineRecord(log) {
@@ -1113,7 +1385,7 @@ function writeLog(file, log) {
     ...log.entries.map((entry) => ({ type: "entry", entry })),
     ...[...log.pins].map((id) => ({ type: "pin", id, pinned: true }))
   ];
-  mkdirSync3(dirname3(file), { recursive: true });
+  mkdirSync4(dirname4(file), { recursive: true });
   replaceFileAtomically4(file, records2.map((r) => `${JSON.stringify(r)}
 `).join(""), 420);
 }
@@ -1186,7 +1458,7 @@ function referencedHashes(log, current) {
 }
 
 // src/history/projectHistory.ts
-var DEFAULT_HISTORY_ROOT = join7(homedir(), ".cache", "hyperframes", "history");
+var DEFAULT_HISTORY_ROOT = join8(homedir(), ".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" };
@@ -1199,7 +1471,7 @@ function isHistoryPath(path) {
   if (KEPT_HIDDEN_PATHS.has(path)) return true;
   return !path.split("/").some((segment) => segment.startsWith("."));
 }
-var logFileIn = (home) => join7(home, "log.jsonl");
+var logFileIn = (home) => join8(home, "log.jsonl");
 function listOf(log) {
   const undone = undoneIds(log.entries);
   return log.entries.map((entry) => ({
@@ -1239,20 +1511,20 @@ async function removeEmptyFolders(dir) {
     throw error;
   }
   for (const entry of entries)
-    if (entry.isDirectory()) await removeEmptyFolders(join7(dir, entry.name));
+    if (entry.isDirectory()) await removeEmptyFolders(join8(dir, entry.name));
   await rmdir(dir);
 }
 function fileLeftIn(dir, at, deleted) {
-  for (const entry of readdirSync3(dir, { withFileTypes: true })) {
+  for (const entry of readdirSync4(dir, { withFileTypes: true })) {
     const path = `${at}/${entry.name}`;
-    const left = entry.isDirectory() ? fileLeftIn(join7(dir, entry.name), path, deleted) : deleted.has(path) ? void 0 : path;
+    const left = entry.isDirectory() ? fileLeftIn(join8(dir, entry.name), path, deleted) : deleted.has(path) ? void 0 : path;
     if (left) return left;
   }
   return void 0;
 }
 function ignoresCase(dir) {
-  const self = statSync4(join7(dir, ID_PATH), { throwIfNoEntry: false });
-  const other = statSync4(join7(dir, ID_PATH.toUpperCase()), { throwIfNoEntry: false });
+  const self = statSync4(join8(dir, ID_PATH), { throwIfNoEntry: false });
+  const other = statSync4(join8(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}/`);
@@ -1289,8 +1561,8 @@ var Engine = class {
     this.options = options;
     this.projectId = projectId;
     this.blobs = blobs;
-    this.dir = resolve6(options.projectDir);
-    this.home = join7(options.historyRoot, projectId);
+    this.dir = resolve7(options.projectDir);
+    this.home = join8(options.historyRoot, projectId);
     this.foldsCase = ignoresCase(this.dir);
     const folder = statSync4(this.dir, { throwIfNoEntry: false });
     if (!folder || readId(this.dir) !== projectId || !isRecordedFolder(this.home, folder))
@@ -1370,7 +1642,7 @@ var Engine = class {
   persistLog(record) {
     if (record) saveRecord(this.logFile, this.log, record);
     else writeLog(this.logFile, this.log);
-    if (!existsSync3(join7(this.home, "project.json")))
+    if (!existsSync3(join8(this.home, "project.json")))
       recordProject(this.home, this.dir, this.folder);
   }
   replaced() {
@@ -1409,7 +1681,7 @@ var Engine = class {
       if (!after || !affectsProjectSignature(realDir, absPath)) return;
       const replaced = hashOfVersion(fileContentVersion(bytes));
       if (!replaced || replaced === after) return;
-      const path = relative4(realDir, absPath).split(sep4).join("/");
+      const path = relative5(realDir, absPath).split(sep5).join("/");
       if (!isHistoryPath(path)) return;
       this.overwritten.set(
         path,
@@ -1421,7 +1693,7 @@ var Engine = class {
     });
   }
   async storeBytes(bytes) {
-    const staged = join7(this.home, `overwrote-${randomUUID7()}`);
+    const staged = join8(this.home, `overwrote-${randomUUID7()}`);
     await mkdir2(this.home, { recursive: true });
     await writeFile(staged, bytes);
     try {
@@ -1475,9 +1747,9 @@ var Engine = class {
     this.saveAdopting();
   }
   saveAdopting() {
-    const file = join7(this.home, "adopting.json");
-    if (!this.adopting.size) return rmSync2(file, { force: true });
-    mkdirSync4(this.home, { recursive: true });
+    const file = join8(this.home, "adopting.json");
+    if (!this.adopting.size) return rmSync3(file, { force: true });
+    mkdirSync5(this.home, { recursive: true });
     replaceFileAtomically5(file, JSON.stringify([...this.adopting.keys()]), 420);
   }
   async adopt(file, sweptAt) {
@@ -1511,7 +1783,7 @@ var Engine = class {
   }
   readStatCache() {
     try {
-      const files = JSON.parse(readFileSync9(join7(this.home, "stat.json"), "utf-8"));
+      const files = JSON.parse(readFileSync10(join8(this.home, "stat.json"), "utf-8"));
       return new Map(Object.entries(files));
     } catch {
       return /* @__PURE__ */ new Map();
@@ -1520,7 +1792,7 @@ var Engine = class {
   readAdopting() {
     try {
       return new Set(
-        JSON.parse(readFileSync9(join7(this.home, "adopting.json"), "utf-8"))
+        JSON.parse(readFileSync10(join8(this.home, "adopting.json"), "utf-8"))
       );
     } catch {
       return /* @__PURE__ */ new Set();
@@ -1528,8 +1800,8 @@ var Engine = class {
   }
   saveStatCache() {
     const files = JSON.stringify(Object.fromEntries(this.tracked));
-    mkdirSync4(this.home, { recursive: true });
-    replaceFileAtomically5(join7(this.home, "stat.json"), files, 420);
+    mkdirSync5(this.home, { recursive: true });
+    replaceFileAtomically5(join8(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
@@ -1571,7 +1843,7 @@ var Engine = class {
   /** The file's hash once copied in; null when it was removed before the copy (the next sweep records that). */
   async storeIfPresent(path) {
     try {
-      return await this.blobs.put(join7(this.dir, path));
+      return await this.blobs.put(join8(this.dir, path));
     } catch (error) {
       if (error.code === "ENOENT") return null;
       throw error;
@@ -1645,7 +1917,7 @@ 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, resolve6(this.dir, path)).split(sep4).join("/");
+    return relative5(this.dir, resolve7(this.dir, path)).split(sep5).join("/");
   }
   /** Takes `paths`' uncommitted changes from others, cut at what `who` overwrote. */
   async takeClaimed(who, paths, overwrote) {
@@ -1806,9 +2078,9 @@ var Engine = class {
   }
   /** A watcher saw a write: one sweep per burst takes it in (a deleted folder is reported by its name alone). */
   noteChange(path) {
-    const absolute = resolve6(this.dir, path);
+    const absolute = resolve7(this.dir, path);
     if (this.notedTimer || !affectsProjectSignature(this.dir, absolute)) return;
-    if (!isHistoryPath(relative4(this.dir, absolute).split(sep4).join("/"))) return;
+    if (!isHistoryPath(relative5(this.dir, absolute).split(sep5).join("/"))) return;
     this.notedTimer = setTimeout(() => {
       this.notedTimer = null;
       this.background(() => this.sweep());
@@ -1884,7 +2156,7 @@ var Engine = class {
     const parts = path.split("/");
     for (let depth = 1; depth <= parts.length; depth += 1) {
       const at = parts.slice(0, depth).join("/");
-      const stat2 = lstatSync3(join7(this.dir, at), { throwIfNoEntry: false });
+      const stat2 = lstatSync4(join8(this.dir, at), { throwIfNoEntry: false });
       if (!stat2) return void 0;
       if (at === path || !stat2.isDirectory()) return { at, stat: stat2 };
     }
@@ -1896,8 +2168,8 @@ var Engine = class {
     if (!standing) return void 0;
     if (standing.stat.isSymbolicLink()) return standing.at;
     if (standing.at === path && !standing.stat.isDirectory()) return void 0;
-    const real = realpathSync.native(join7(this.dir, standing.at));
-    const at = relative4(realpathSync.native(this.dir), real).split(sep4).join("/");
+    const real = realpathSync.native(join8(this.dir, standing.at));
+    const at = relative5(realpathSync.native(this.dir), real).split(sep5).join("/");
     if (standing.at !== path) return deleted.has(at) ? void 0 : at;
     return fileLeftIn(real, at, deleted);
   }
@@ -1921,7 +2193,7 @@ 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 = join7(this.dir, path);
+    const absPath = join8(this.dir, path);
     const { writeToken } = this;
     if (writeToken) {
       const version = hash === null ? DELETED_VERSION : hashVersion(hash);
@@ -1929,7 +2201,7 @@ var Engine = class {
     }
     if (hash === null) {
       this.assertWritable();
-      rmSync2(absPath, { force: true });
+      rmSync3(absPath, { force: true });
     } else {
       await removeEmptyFolders(absPath);
       await this.blobs.writeTo(hash, absPath, () => this.assertWritable());
@@ -2065,17 +2337,17 @@ var Engine = class {
       checkout: (entryId, side, emptyDir) => this.queue(async () => {
         this.entry(entryId);
         if (!existsSync3(this.dir)) throw new Error(`The project folder is gone: ${this.dir}`);
-        const dest = resolve6(emptyDir);
+        const dest = resolve7(emptyDir);
         if (isWithin(this.dir, dest))
           throw new Error(`Checkout writes outside the project only: ${dest}`);
         if ((await readdir3(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, join7(dest, path));
+          for (const [path, hash] of files) await this.blobs.writeTo(hash, join8(dest, path));
         } catch (error) {
           for (const name of await readdir3(dest).catch(() => []))
-            await rm3(join7(dest, name), { recursive: true, force: true });
+            await rm3(join8(dest, name), { recursive: true, force: true });
           throw error;
         }
       }),
@@ -2113,10 +2385,10 @@ var Engine = class {
   }
 };
 function isWithin(dir, path) {
-  let probe = resolve6(path);
-  while (!existsSync3(probe) && dirname4(probe) !== probe) probe = dirname4(probe);
-  const rel = relative4(realpathSync.native(dir), realpathSync.native(probe));
-  return rel === "" || rel !== ".." && !rel.startsWith(`..${sep4}`) && !isAbsolute5(rel);
+  let probe = resolve7(path);
+  while (!existsSync3(probe) && dirname5(probe) !== probe) probe = dirname5(probe);
+  const rel = relative5(realpathSync.native(dir), realpathSync.native(probe));
+  return rel === "" || rel !== ".." && !rel.startsWith(`..${sep5}`) && !isAbsolute5(rel);
 }
 function missingIsEmpty(error) {
   if (error.code === "ENOENT") return [];
@@ -2133,11 +2405,11 @@ async function openProjectHistory(options) {
     throw new HistoryClosedError(`${options.projectDir} is gone or now another project.`);
   const projectId = projectHistoryId(options.projectDir, options.historyRoot);
   const release = await takeHistoryOwnership(
-    join7(options.historyRoot, projectId),
+    join8(options.historyRoot, projectId),
     options.ownerWaitMs ?? 5e3
   );
   try {
-    const blobs = await openBlobStore(join7(options.historyRoot, projectId, "blobs"));
+    const blobs = await openBlobStore(join8(options.historyRoot, projectId, "blobs"));
     const closedWindow = options.closedWindowAfterOwnership?.() ?? options.closedWindow;
     const engine = new Engine({ ...options, closedWindow }, projectId, blobs);
     await engine.queue(async () => {
@@ -2159,9 +2431,9 @@ async function openProjectHistory(options) {
   }
 }
 function readProjectHistory(options) {
-  const dir = resolve6(options.projectDir);
+  const dir = resolve7(options.projectDir);
   const id = readId(dir);
-  const home = id && isRecordedFolder(join7(options.historyRoot, id), statSync4(dir)) ? join7(options.historyRoot, id) : null;
+  const home = id && isRecordedFolder(join8(options.historyRoot, id), statSync4(dir)) ? join8(options.historyRoot, id) : null;
   const read = home && readLog(logFileIn(home), () => {
   });
   const log = withoutHiddenPaths(read || { baseline: /* @__PURE__ */ new Map(), entries: [], pins: /* @__PURE__ */ new Set() });
@@ -2170,7 +2442,7 @@ function readProjectHistory(options) {
     peek: (point) => peekOf(log, point),
     readBlob: async (hash) => {
       if (!home) throw new Error("That is not a history blob.");
-      return readBlob(join7(home, "blobs"), hash);
+      return readBlob(join8(home, "blobs"), hash);
     }
   };
 }
@@ -2218,12 +2490,14 @@ export {
   HistoryIdError,
   listProjectHistories,
   pruneGoneProjectHistories,
+  retainSnapshotOutput,
   beginArtifactCapture,
   recordArtifact,
   recordArtifacts,
   forgetRecordedArtifacts,
   artifactDirectory,
   recordRenderSuccess,
+  finishSnapshotRun,
   START,
   DEFAULT_HISTORY_ROOT,
   MAX_WINDOW_IDLE_MS,

package/dist/history/index.d.ts

@@ -130,7 +130,11 @@ declare function recordArtifacts(projectDir: string, capture: ArtifactCapture, a
 declare function forgetRecordedArtifacts(projectDir: string, paths: readonly string[]): Promise<void>;
 declare function artifactDirectory(projectDir: string, kind: "checks" | "snapshots"): string;
 declare function recordRenderSuccess(projectDir: string, output: string, status?: RenderRecord["status"], capture?: ArtifactCapture): Promise<RenderRecord>;
+declare function finishSnapshotRun(projectDir: string, path: string): Promise<void>;
 
 declare function registerRenderOutput(projectDir: string, output: string): Promise<void>;
 
-export { type ArtifactCapture, type ArtifactInput, type ArtifactRecord, HistoryBusyError, HistoryIdError, HistoryTarget, HistoryWho, ProjectHistory, type ProjectHistoryRecord, type PrunedHistory, type RenderRecord, type VideoState, artifactDirectory, beginArtifactCapture, forgetRecordedArtifacts, historyCache, listProjectHistories, pruneGoneProjectHistories, recordArtifact, recordArtifacts, recordRenderSuccess, registerRenderOutput };
+/** Explicit outputs remain user evidence even when reusing a managed UUID folder. */
+declare function retainSnapshotOutput(project: string, path: string): void;
+
+export { type ArtifactCapture, type ArtifactInput, type ArtifactRecord, HistoryBusyError, HistoryIdError, HistoryTarget, HistoryWho, ProjectHistory, type ProjectHistoryRecord, type PrunedHistory, type RenderRecord, type VideoState, artifactDirectory, beginArtifactCapture, finishSnapshotRun, forgetRecordedArtifacts, historyCache, listProjectHistories, pruneGoneProjectHistories, recordArtifact, recordArtifacts, recordRenderSuccess, registerRenderOutput, retainSnapshotOutput };

package/dist/history/index.js

@@ -8,6 +8,7 @@ import {
   UNDO_MODES,
   artifactDirectory,
   beginArtifactCapture,
+  finishSnapshotRun,
   forgetRecordedArtifacts,
   historyCache,
   listProjectHistories,
@@ -17,8 +18,9 @@ import {
   recordArtifact,
   recordArtifacts,
   recordRenderSuccess,
-  registerRenderOutput
-} from "../chunk-66HD2HFT.js";
+  registerRenderOutput,
+  retainSnapshotOutput
+} from "../chunk-SZF3L5MT.js";
 import "../chunk-K56J3CL7.js";
 import "../chunk-SVQFE44C.js";
 import "../chunk-L3HJVTQE.js";
@@ -32,6 +34,7 @@ export {
   UNDO_MODES,
   artifactDirectory,
   beginArtifactCapture,
+  finishSnapshotRun,
   forgetRecordedArtifacts,
   historyCache,
   listProjectHistories,
@@ -41,5 +44,6 @@ export {
   recordArtifact,
   recordArtifacts,
   recordRenderSuccess,
-  registerRenderOutput
+  registerRenderOutput,
+  retainSnapshotOutput
 };

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { Hono } from 'hono';
 import { S as StudioApiAdapter, P as PreviewDocumentStore, M as MediaProcessingJobState } from './mediaProxyPreview-J8vlAvrx.js';
 export { L as LintResult, a as PreviewApiAdapter, R as RenderJobState, b as ResolvedProject, c as StudioSelectionResponse, d as StudioSelectionSnapshot, e as StudioSelectionTextField } from './mediaProxyPreview-J8vlAvrx.js';
 export { C as ClosedWindow, D as DEFAULT_HISTORY_ROOT, S as HISTORY_START, H as HistoryClosedError, a as HistoryEntry, b as HistoryEntrySide, c as HistoryFileChange, d as HistoryListItem, e as HistoryResult, f as HistoryTarget, g as HistoryWho, h as HistoryWindow, M as MAX_WINDOW_IDLE_MS, P as ProjectHistory, i as ProjectHistoryOptions, j as ProjectHistoryView, U as UNDO_MODES, k as UndoMode, o as openProjectHistory, r as readProjectHistory } from './projectHistory-C5dpCjPU.js';
-export { ArtifactCapture, ArtifactInput, ArtifactRecord, HistoryBusyError, HistoryIdError, ProjectHistoryRecord, PrunedHistory, RenderRecord, VideoState, artifactDirectory, beginArtifactCapture, forgetRecordedArtifacts, historyCache, listProjectHistories, pruneGoneProjectHistories, recordArtifact, recordArtifacts, recordRenderSuccess, registerRenderOutput } from './history/index.js';
+export { ArtifactCapture, ArtifactInput, ArtifactRecord, HistoryBusyError, HistoryIdError, ProjectHistoryRecord, PrunedHistory, RenderRecord, VideoState, artifactDirectory, beginArtifactCapture, finishSnapshotRun, forgetRecordedArtifacts, historyCache, listProjectHistories, pruneGoneProjectHistories, recordArtifact, recordArtifacts, recordRenderSuccess, registerRenderOutput, retainSnapshotOutput } from './history/index.js';
 export { CACHE_DIR_NAME as PROXY_CACHE_DIR_NAME } from './helpers/proxyTranscoder.js';
 export { walkDir } from './helpers/safePath.js';
 export { stampProjectHfIds } from './helpers/hfIdPersist.js';

package/dist/index.js

@@ -43,6 +43,7 @@ import {
   createProjectSignature,
   createWriteToken,
   fileContentVersion,
+  finishSnapshotRun,
   forgetRecordedArtifacts,
   historyCache,
   identifyFileWrite,
@@ -57,8 +58,9 @@ import {
   registerRenderOutput,
   resolveProjectAndSignature,
   resolveProjectSignature,
+  retainSnapshotOutput,
   settledFileTag
-} from "./chunk-66HD2HFT.js";
+} from "./chunk-SZF3L5MT.js";
 import {
   clearElementScreenshotIsolation,
   getElementScreenshotClip
@@ -6754,6 +6756,7 @@ export {
   duplicateElementInHtml,
   fileContentVersion,
   findTargetElement,
+  finishSnapshotRun,
   forgetRecordedArtifacts,
   getElementScreenshotClip,
   getMimeType,
@@ -6772,6 +6775,7 @@ export {
   registerRenderOutput,
   removeElementFromHtml,
   requestSubPath,
+  retainSnapshotOutput,
   settledFileTag,
   splitElementInHtml,
   stampProjectHfIds,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio-server",
-  "version": "0.8.158",
+  "version": "0.8.160",
   "repository": {
     "type": "git",
     "url": "https://github.com/heygen-com/hyperframes",
@@ -85,8 +85,8 @@
     "postcss": "^8.5.8",
     "postcss-selector-parser": "^7.1.2",
     "sharp": "^0.35.0",
-    "@hyperframes/core": "0.8.158",
-    "@hyperframes/parsers": "0.8.158"
+    "@hyperframes/core": "0.8.160",
+    "@hyperframes/parsers": "0.8.160"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",