@hyperframes/studio-server 0.8.73 → 0.8.74

package/dist/index.js

@@ -151,22 +151,22 @@ function collectProjectSignatureFiles(projectDir, dir, files) {
     if (SIGNATURE_EXCLUDED_DIRS.has(entry)) continue;
     const file = resolve(dir, entry);
     if (!isPathWithin(projectDir, file)) continue;
-    let stat;
+    let stat2;
     try {
-      stat = lstatSync(file);
+      stat2 = lstatSync(file);
     } catch {
       continue;
     }
-    if (stat.isSymbolicLink()) continue;
-    if (stat.isDirectory()) {
+    if (stat2.isSymbolicLink()) continue;
+    if (stat2.isDirectory()) {
       collectProjectSignatureFiles(projectDir, file, files);
-    } else if (stat.isFile()) {
+    } else if (stat2.isFile()) {
       files.push({
         file,
-        mtimeMs: stat.mtimeMs,
-        ctimeMs: stat.ctimeMs,
-        size: stat.size,
-        textContentEligible: isTextContentEligible(file, stat.size)
+        mtimeMs: stat2.mtimeMs,
+        ctimeMs: stat2.ctimeMs,
+        size: stat2.size,
+        textContentEligible: isTextContentEligible(file, stat2.size)
       });
     }
   }
@@ -176,19 +176,19 @@ function collectProjectSignatureManifestFiles(projectDir, files) {
   for (const manifestPath of STUDIO_SIGNATURE_MANIFEST_PATHS) {
     const file = resolve(projectDir, manifestPath);
     if (seen.has(file) || !isPathWithin(projectDir, file)) continue;
-    let stat;
+    let stat2;
     try {
-      stat = lstatSync(file);
+      stat2 = lstatSync(file);
     } catch {
       continue;
     }
-    if (stat.isSymbolicLink() || !stat.isFile()) continue;
+    if (stat2.isSymbolicLink() || !stat2.isFile()) continue;
     files.push({
       file,
-      mtimeMs: stat.mtimeMs,
-      ctimeMs: stat.ctimeMs,
-      size: stat.size,
-      textContentEligible: isTextContentEligible(file, stat.size)
+      mtimeMs: stat2.mtimeMs,
+      ctimeMs: stat2.ctimeMs,
+      size: stat2.size,
+      textContentEligible: isTextContentEligible(file, stat2.size)
     });
     seen.add(file);
   }
@@ -209,6 +209,21 @@ function createProjectFingerprint(projectDir, files) {
   }
   return hash.digest("hex").slice(0, 24);
 }
+function collectProjectFiles(normalizedProjectDir) {
+  const collected = [];
+  collectProjectSignatureFiles(normalizedProjectDir, normalizedProjectDir, collected);
+  collectProjectSignatureManifestFiles(normalizedProjectDir, collected);
+  return collected;
+}
+function listProjectFiles(projectDir) {
+  const normalizedProjectDir = resolve(projectDir);
+  return collectProjectFiles(normalizedProjectDir).map((entry) => ({
+    path: relative(normalizedProjectDir, entry.file).split(sep).join("/"),
+    size: entry.size,
+    mtimeMs: entry.mtimeMs,
+    ctimeMs: entry.ctimeMs
+  }));
+}
 function resolveProjectSignature(adapter, projectDir) {
   return adapter.getProjectSignature?.(projectDir) ?? createProjectSignature(projectDir);
 }
@@ -219,9 +234,7 @@ async function resolveProjectAndSignature(adapter, projectId) {
 }
 function createProjectSignature(projectDir, excluding = /* @__PURE__ */ new Set()) {
   const normalizedProjectDir = resolve(projectDir);
-  const collected = [];
-  collectProjectSignatureFiles(normalizedProjectDir, normalizedProjectDir, collected);
-  collectProjectSignatureManifestFiles(normalizedProjectDir, collected);
+  const collected = collectProjectFiles(normalizedProjectDir);
   const files = collected.filter(
     (entry) => !excluding.has(relative(normalizedProjectDir, entry.file).split(sep).join("/"))
   );
@@ -622,9 +635,9 @@ var receipts = /* @__PURE__ */ new Map();
 function fileContentVersion(content) {
   return `"sha256:${createHash2("sha256").update(content).digest("hex")}"`;
 }
-function settledFileTag(stat, now = Date.now()) {
-  if (now - stat.ctimeMs < 3e3) return null;
-  return [stat.ino, stat.ctimeMs, stat.size].map((n) => n.toString(36)).join("-");
+function settledFileTag(stat2, now = Date.now()) {
+  if (now - stat2.ctimeMs < 3e3) return null;
+  return [stat2.ino, stat2.ctimeMs, stat2.size].map((n) => n.toString(36)).join("-");
 }
 function createWriteToken(requestToken) {
   const token = requestToken?.trim();
@@ -2590,10 +2603,10 @@ function registerFileRoutes(api, adapter) {
   api.delete("/projects/:id/files/*", async (c) => {
     const res = await resolveProjectFile(c, adapter, { mustExist: true });
     if ("error" in res) return res.error;
-    const stat = statSync3(res.absPath);
+    const stat2 = statSync3(res.absPath);
     const backup = snapshotBeforeWrite(res.project.dir, res.absPath);
     if (backup.error) return c.json({ error: `backup failed: ${backup.error}` }, 500);
-    if (stat.isDirectory()) {
+    if (stat2.isDirectory()) {
       rmSync3(res.absPath, { recursive: true });
     } else {
       unlinkSync2(res.absPath);
@@ -3373,7 +3386,7 @@ function buildSubCompositionHtml(projectDir, compPath, runtimeUrl, baseHref, raw
     const headMatch = indexHtml.match(/<head[^>]*>([\s\S]*?)<\/head>/i);
     headContent = headMatch?.[1] ?? "";
   }
-  if (baseHref && !headContent.includes("<base")) {
+  if (baseHref && !hasBaseElement(headContent)) {
     headContent = `<base href="${baseHref}">
 ${headContent}`;
   }
@@ -3401,6 +3414,9 @@ ${rewrittenContent}
 </body>
 </html>`;
 }
+function hasBaseElement(html) {
+  return parseHTML3(html).document.querySelector("base") !== null;
+}
 
 // src/routes/preview.ts
 import { ensureHfIds as ensureHfIds2 } from "@hyperframes/parsers/hf-ids";
@@ -3707,7 +3723,7 @@ function registerPreviewRoutes(api, adapter) {
 ${runtimeTag}`;
       }
       const baseHref = `/api/projects/${project.id}/preview/`;
-      if (!bundled.includes("<base")) {
+      if (!hasBaseElement(bundled)) {
         bundled = bundled.replace(/<head>/i, `<head><base href="${baseHref}">`);
       }
       bundled = injectStudioPreviewAugmentations(
@@ -3804,8 +3820,8 @@ ${runtimeTag}`;
     if (!file) {
       return c.text("not found", 404);
     }
-    const stat = existsSync5(file) ? statSync5(file) : null;
-    if (!stat?.isFile()) {
+    const stat2 = existsSync5(file) ? statSync5(file) : null;
+    if (!stat2?.isFile()) {
       return c.text("not found", 404);
     }
     const contentType = getMimeType(subPath);
@@ -3827,7 +3843,7 @@ ${runtimeTag}`;
         return c.text("media proxy variant does not match asset", 422);
       }
     }
-    const tag = settledFileTag(stat);
+    const tag = settledFileTag(stat2);
     const etag = tag && `"${tag}${proxyEtagSalt(proxyVariant)}"`;
     const cacheHeaders = isText ? { "Cache-Control": "no-store" } : { "Cache-Control": "private, no-cache", ...etag && { ETag: etag } };
     if (!isText && etag) {
@@ -4153,7 +4169,7 @@ function registerRenderRoutes(api, adapter) {
     if (!existsSync6(rendersDir)) return c.json({ renders: [] });
     const files = readdirSync5(rendersDir).filter((f) => f.endsWith(".mp4") || f.endsWith(".webm") || f.endsWith(".mov")).map((f) => {
       const fp = join10(rendersDir, f);
-      const stat = statSync6(fp);
+      const stat2 = statSync6(fp);
       const rid = f.replace(/\.(mp4|webm|mov)$/, "");
       const metaPath = join10(rendersDir, `${rid}.meta.json`);
       let status = "complete";
@@ -4169,8 +4185,8 @@ function registerRenderRoutes(api, adapter) {
       return {
         id: rid,
         filename: f,
-        size: stat.size,
-        createdAt: stat.mtimeMs,
+        size: stat2.size,
+        createdAt: stat2.mtimeMs,
         status,
         durationMs
       };
@@ -4282,10 +4298,10 @@ var ThumbnailGenerationCoordinator = class {
     if (signal.aborted) return Promise.reject(new DOMException("Aborted", "AbortError"));
     let entry = this.entries.get(key);
     if (!entry) {
-      let resolve6;
+      let resolve8;
       let reject;
       const promise = new Promise((resolvePromise, rejectPromise) => {
-        resolve6 = resolvePromise;
+        resolve8 = resolvePromise;
         reject = rejectPromise;
       });
       entry = {
@@ -4295,7 +4311,7 @@ var ThumbnailGenerationCoordinator = class {
         state: "queued",
         work,
         promise,
-        resolve: resolve6,
+        resolve: resolve8,
         reject
       };
       this.entries.set(key, entry);
@@ -4309,7 +4325,7 @@ var ThumbnailGenerationCoordinator = class {
     return /* @__PURE__ */ new Set([...this.entries.keys(), ...[...this.activeEntries].map((entry) => entry.key)]);
   }
   lease(entry, signal) {
-    return new Promise((resolve6, reject) => {
+    return new Promise((resolve8, reject) => {
       let released = false;
       const release = () => {
         if (released) return;
@@ -4333,7 +4349,7 @@ var ThumbnailGenerationCoordinator = class {
       entry.promise.then(
         (value) => {
           release();
-          resolve6(value);
+          resolve8(value);
         },
         (reason) => {
           release();
@@ -4424,9 +4440,9 @@ function readCompositionSource(file) {
     throw err;
   }
   try {
-    const stat = fstatSync3(fd);
-    if (!stat.isFile()) return "not-a-file";
-    return { html: readFileSync12(fd, "utf-8"), mtimeMs: stat.mtimeMs };
+    const stat2 = fstatSync3(fd);
+    if (!stat2.isFile()) return "not-a-file";
+    return { html: readFileSync12(fd, "utf-8"), mtimeMs: stat2.mtimeMs };
   } finally {
     closeSync3(fd);
   }
@@ -4712,12 +4728,12 @@ function registerFontRoutes(api) {
       return c.json({ error: "font file not accessible" }, 404);
     }
     try {
-      const stat = fstatSync4(fd);
-      if (stat.size > SYSTEM_FONT_SIZE_LIMIT) {
+      const stat2 = fstatSync4(fd);
+      if (stat2.size > SYSTEM_FONT_SIZE_LIMIT) {
         return c.json({ error: "font file too large" }, 413);
       }
-      const buffer = Buffer.alloc(stat.size);
-      readSync(fd, buffer, 0, stat.size, 0);
+      const buffer = Buffer.alloc(stat2.size);
+      readSync(fd, buffer, 0, stat2.size, 0);
       const mimeType = located.format === "otf" ? "font/otf" : located.format === "woff2" ? "font/woff2" : located.format === "woff" ? "font/woff" : located.format === "ttc" ? "font/collection" : "font/ttf";
       const fileName = `${family.replace(/[^a-zA-Z0-9 -]/g, "")}.${located.format}`;
       return new Response(buffer, {
@@ -5090,6 +5106,80 @@ function registerGlobalAssetRoutes(api) {
   api.get("/assets/global", (c) => c.json({ assets: readGlobalAssets().map(toPublicAsset) }));
 }
 
+// src/routes/history.ts
+var YOU = { kind: "person", name: "You" };
+async function historyOf(adapter, c) {
+  const project = await adapter.resolveProject(c.req.param("id") ?? "");
+  return project ? await adapter.history?.(project) ?? null : null;
+}
+async function bodyOf(c) {
+  const body = await c.req.json().catch(() => null);
+  return body && typeof body === "object" ? body : {};
+}
+var text = (value) => typeof value === "string" && value ? value : null;
+async function withHistory(adapter, c, task) {
+  const history = await historyOf(adapter, c);
+  if (!history) return c.json({ error: "This project has no history here." }, 404);
+  try {
+    return c.json(await task(history, await bodyOf(c)) ?? null);
+  } catch (error) {
+    return c.json({ error: error instanceof Error ? error.message : String(error) }, 409);
+  }
+}
+function registerHistoryRoutes(api, adapter) {
+  const windows = /* @__PURE__ */ new Map();
+  const base = "/projects/:id/history";
+  api.get(base, (c) => withHistory(adapter, c, (history) => ({ entries: history.list() })));
+  api.post(
+    `${base}/step`,
+    (c) => withHistory(
+      adapter,
+      c,
+      (history, body) => history.step(body.direction === "forward" ? "forward" : "back", YOU)
+    )
+  );
+  api.post(
+    `${base}/undo`,
+    (c) => withHistory(adapter, c, (history, body) => {
+      const mode = body.mode === "just-this" || body.mode === "back-to-before" ? body.mode : void 0;
+      return history.undo(text(body.entryId) ?? "", { who: YOU, mode });
+    })
+  );
+  api.post(
+    `${base}/restore`,
+    (c) => withHistory(adapter, c, (history, body) => history.restore(text(body.point) ?? "", YOU))
+  );
+  api.get(
+    `${base}/peek/:point`,
+    (c) => withHistory(adapter, c, (history) => ({ files: history.peek(c.req.param("point")) }))
+  );
+  api.post(
+    `${base}/pin`,
+    (c) => withHistory(adapter, c, (history, body) => {
+      history.pin(text(body.entryId) ?? "", body.pinned === true);
+      return { ok: true };
+    })
+  );
+  api.post(
+    `${base}/window`,
+    (c) => withHistory(adapter, c, async (history, body) => {
+      const window = await history.beginWindow(YOU, text(body.label) ?? "Edited in Studio");
+      windows.set(window.id, { history, window });
+      return { windowId: window.id };
+    })
+  );
+  api.post(
+    `${base}/window/:windowId/close`,
+    (c) => withHistory(adapter, c, async (history) => {
+      const id = c.req.param("windowId") ?? "";
+      const held = windows.get(id);
+      if (held?.history !== history) throw new Error("That window is not open in this project.");
+      windows.delete(id);
+      return { entry: await held.window.close() };
+    })
+  );
+}
+
 // src/createStudioApi.ts
 function createStudioApi(adapter) {
   const api = new Hono();
@@ -5105,9 +5195,587 @@ function createStudioApi(adapter) {
   registerFontRoutes(api);
   registerRegistryRoutes(api, adapter);
   registerGlobalAssetRoutes(api);
+  registerHistoryRoutes(api, adapter);
   return api;
 }
 
+// src/history/projectHistory.ts
+import { randomUUID as randomUUID7 } from "crypto";
+import { rm as rm2 } from "fs/promises";
+import { existsSync as existsSync12, mkdirSync as mkdirSync9, readFileSync as readFileSync17 } from "fs";
+import { join as join17, resolve as resolve7 } from "path";
+
+// src/history/blobStore.ts
+import { createHash as createHash5, randomUUID as randomUUID5 } from "crypto";
+import { constants as constants3, createReadStream as createReadStream2 } from "fs";
+import { copyFile, mkdir, readdir, readFile as readFile2, rename, rm, stat } from "fs/promises";
+import { dirname as dirname5, join as join15 } from "path";
+async function hashFile(path) {
+  const hash = createHash5("sha256");
+  for await (const chunk of createReadStream2(path)) hash.update(chunk);
+  return hash.digest("hex");
+}
+async function cloneOrCopy(from, to) {
+  await mkdir(dirname5(to), { recursive: true });
+  const temp = `${to}.${randomUUID5()}.tmp`;
+  try {
+    await copyFile(from, temp, constants3.COPYFILE_FICLONE);
+    await rename(temp, to);
+  } catch (error) {
+    await rm(temp, { force: true });
+    throw error;
+  }
+}
+async function openBlobStore(dir) {
+  const sizes = /* @__PURE__ */ new Map();
+  await mkdir(dir, { recursive: true });
+  for (const shard of await readdir(dir))
+    for (const hash of await readdir(join15(dir, shard)).catch(() => []))
+      sizes.set(hash, (await stat(join15(dir, shard, hash))).size);
+  const pathOf = (hash) => join15(dir, hash.slice(0, 2), hash);
+  let total = [...sizes.values()].reduce((sum, size) => sum + size, 0);
+  return {
+    async put(absPath) {
+      const temp = join15(dir, `incoming-${randomUUID5()}`);
+      await mkdir(dir, { recursive: true });
+      await copyFile(absPath, temp, constants3.COPYFILE_FICLONE);
+      const hash = await hashFile(temp);
+      if (sizes.has(hash)) {
+        await rm(temp, { force: true });
+        return hash;
+      }
+      await mkdir(dirname5(pathOf(hash)), { recursive: true });
+      const size = (await stat(temp)).size;
+      await rename(temp, pathOf(hash));
+      sizes.set(hash, size);
+      total += size;
+      return hash;
+    },
+    read: (hash) => readFile2(pathOf(hash)),
+    writeTo: (hash, absPath) => cloneOrCopy(pathOf(hash), absPath),
+    bytes: () => total,
+    size: (hash) => sizes.get(hash) ?? 0,
+    async prune(keep) {
+      for (const [hash, size] of sizes) {
+        if (keep.has(hash)) continue;
+        await rm(pathOf(hash), { force: true });
+        sizes.delete(hash);
+        total -= size;
+      }
+    }
+  };
+}
+
+// src/history/historyId.ts
+import { randomUUID as randomUUID6 } from "crypto";
+import { existsSync as existsSync11, mkdirSync as mkdirSync7, readFileSync as readFileSync15, writeFileSync as writeFileSync6 } from "fs";
+import { join as join16, resolve as resolve6 } from "path";
+var ID_PATH = join16(".hyperframes", "history-id");
+var ID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+function readId(projectDir) {
+  try {
+    const id = readFileSync15(join16(projectDir, ID_PATH), "utf-8").trim();
+    return ID_SHAPE.test(id) ? id : null;
+  } catch {
+    return null;
+  }
+}
+function recordedDir(historyDir) {
+  try {
+    return JSON.parse(readFileSync15(join16(historyDir, "project.json"), "utf-8")).dir ?? null;
+  } catch {
+    return null;
+  }
+}
+function projectHistoryId(projectDir, historyRoot) {
+  const dir = resolve6(projectDir);
+  let id = readId(dir);
+  const was = id && recordedDir(join16(historyRoot, id));
+  if (!id || was && was !== dir && existsSync11(was) && readId(was) === id) {
+    id = randomUUID6();
+    mkdirSync7(join16(dir, ".hyperframes"), { recursive: true });
+    writeFileSync6(join16(dir, ID_PATH), `${id}
+`);
+  }
+  mkdirSync7(join16(historyRoot, id), { recursive: true });
+  writeFileSync6(join16(historyRoot, id, "project.json"), JSON.stringify({ dir }));
+  return id;
+}
+
+// src/history/historyLog.ts
+import { closeSync as closeSync5, constants as constants4, mkdirSync as mkdirSync8, openSync as openSync5, readFileSync as readFileSync16, writeSync as writeSync2 } from "fs";
+import { dirname as dirname6 } from "path";
+var START = "start";
+function parseRecord(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+function readLog(file, onUnreadable) {
+  let text2;
+  try {
+    text2 = readFileSync16(file, "utf-8");
+  } catch {
+    return null;
+  }
+  const log = { baseline: /* @__PURE__ */ new Map(), entries: [], pins: /* @__PURE__ */ new Set() };
+  const lines = text2.split("\n");
+  lines.forEach((line, index) => {
+    const record = line ? parseRecord(line) : null;
+    if (record) applyRecord(log, record);
+    else if (line && index < lines.length - 1) onUnreadable(index + 1);
+  });
+  return log;
+}
+function applyRecord(log, record) {
+  if (record.type === "baseline") log.baseline = new Map(Object.entries(record.files));
+  else if (record.type === "entry") log.entries.push(record.entry);
+  else if (record.pinned) log.pins.add(record.id);
+  else log.pins.delete(record.id);
+}
+function saveRecord(file, log, record) {
+  let fd;
+  try {
+    fd = openSync5(file, constants4.O_WRONLY | constants4.O_APPEND);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    return writeLog(file, log);
+  }
+  try {
+    writeSync2(fd, `${JSON.stringify(record)}
+`);
+  } finally {
+    closeSync5(fd);
+  }
+}
+function writeLog(file, log) {
+  const records = [
+    { type: "baseline", files: Object.fromEntries(log.baseline) },
+    ...log.entries.map((entry) => ({ type: "entry", entry })),
+    ...[...log.pins].map((id) => ({ type: "pin", id, pinned: true }))
+  ];
+  mkdirSync8(dirname6(file), { recursive: true });
+  replaceFileAtomically(file, records.map((r) => `${JSON.stringify(r)}
+`).join(""), 420);
+}
+function applyEntry(manifest, entry) {
+  for (const file of entry.files)
+    if (file.after === null) manifest.delete(file.path);
+    else manifest.set(file.path, file.after);
+}
+function manifestAt(log, point) {
+  const manifest = new Map(log.baseline);
+  if (point === START) return manifest;
+  for (const entry of log.entries) {
+    applyEntry(manifest, entry);
+    if (entry.id === point) return manifest;
+  }
+  return null;
+}
+function undoneIds(entries) {
+  const undone = /* @__PURE__ */ new Set();
+  for (let i = entries.length - 1; i >= 0; i -= 1) {
+    const entry = entries[i];
+    if (entry.undoes && !undone.has(entry.id)) undone.add(entry.undoes);
+  }
+  return undone;
+}
+function stepTarget(entries, direction) {
+  const undone = undoneIds(entries);
+  const byId = new Map(entries.map((entry) => [entry.id, entry]));
+  for (let i = entries.length - 1; i >= 0; i -= 1) {
+    const entry = entries[i];
+    const isChange = !entry.undoes;
+    if (direction === "back" && isChange && !undone.has(entry.id)) return entry;
+    if (direction !== "forward") continue;
+    if (isChange) return void 0;
+    const target = byId.get(entry.undoes);
+    if (!undone.has(entry.id) && target && !target.undoes) return entry;
+  }
+  return void 0;
+}
+function foldOldest(log) {
+  const oldest = log.entries[0];
+  if (!oldest || log.pins.has(oldest.id)) return false;
+  applyEntry(log.baseline, oldest);
+  log.entries.shift();
+  return true;
+}
+function referencedHashes(log, current) {
+  const keep = /* @__PURE__ */ new Set([...log.baseline.values(), ...current.values()]);
+  for (const entry of log.entries)
+    for (const file of entry.files) {
+      if (file.before) keep.add(file.before);
+      if (file.after) keep.add(file.after);
+    }
+  return keep;
+}
+
+// src/history/projectHistory.ts
+var OUTSIDE = { kind: "outside", name: "Outside" };
+var OUTSIDE_LABEL = "Changed outside the app";
+var RACY_MS = 2e3;
+var statKey = (file, sweptAt) => sweptAt - Math.max(file.mtimeMs, file.ctimeMs) < RACY_MS ? "" : `${file.size}:${file.mtimeMs}:${file.ctimeMs}`;
+var Engine = class {
+  constructor(options, projectId, blobs) {
+    this.options = options;
+    this.projectId = projectId;
+    this.blobs = blobs;
+    this.dir = resolve7(options.projectDir);
+    this.home = join17(options.historyRoot, projectId);
+  }
+  options;
+  projectId;
+  blobs;
+  dir;
+  home;
+  log = { baseline: /* @__PURE__ */ new Map(), entries: [], pins: /* @__PURE__ */ new Set() };
+  tracked = /* @__PURE__ */ new Map();
+  windows = [];
+  outside = null;
+  quietTimer;
+  maxTimer;
+  notedTimer = null;
+  listeners = /* @__PURE__ */ new Set();
+  tail = Promise.resolve();
+  get logFile() {
+    return join17(this.home, "log.jsonl");
+  }
+  now() {
+    return (this.options.now ?? Date.now)();
+  }
+  /** One operation at a time, in order: sweeps, windows and undos never interleave. */
+  queue(task) {
+    const run = this.tail.then(task);
+    this.tail = run.catch(() => void 0);
+    return run;
+  }
+  async start() {
+    const log = readLog(
+      this.logFile,
+      (line) => this.options.onError?.(
+        new Error(`History log line ${line} could not be read and was skipped.`)
+      )
+    );
+    if (!log) return this.firstOpen();
+    this.log = log;
+    const cache = this.readStatCache();
+    const last = this.log.entries.at(-1)?.id ?? START;
+    for (const [path, hash] of manifestAt(this.log, last) ?? []) {
+      const cached = cache.get(path);
+      this.tracked.set(path, { hash, stat: cached?.hash === hash ? cached.stat : "" });
+    }
+    await this.sweep();
+    await this.commitOutside();
+  }
+  async firstOpen() {
+    const sweptAt = Date.now();
+    for (const file of listProjectFiles(this.dir))
+      this.tracked.set(file.path, {
+        hash: await this.blobs.put(join17(this.dir, file.path)),
+        stat: statKey(file, sweptAt)
+      });
+    this.log.baseline = this.manifest();
+    writeLog(this.logFile, this.log);
+    this.saveStatCache();
+  }
+  manifest() {
+    return new Map([...this.tracked].map(([path, file]) => [path, file.hash]));
+  }
+  readStatCache() {
+    try {
+      const files = JSON.parse(readFileSync17(join17(this.home, "stat.json"), "utf-8"));
+      return new Map(Object.entries(files));
+    } catch {
+      return /* @__PURE__ */ new Map();
+    }
+  }
+  saveStatCache() {
+    const files = JSON.stringify(Object.fromEntries(this.tracked));
+    mkdirSync9(this.home, { recursive: true });
+    replaceFileAtomically(join17(this.home, "stat.json"), files, 420);
+  }
+  /**
+   * Takes in every write since the last sweep and files each change to its writer. ponytail: always the whole
+   * project (a stat per file, a hash only when the stat moved); per-path sweeps if projects reach tens of thousands.
+   */
+  async sweep() {
+    if (!existsSync12(this.dir)) return;
+    const sweptAt = Date.now();
+    const seen = listProjectFiles(this.dir);
+    let changed = false;
+    for (const file of seen)
+      changed = await this.observe(file.path, statKey(file, sweptAt)) || changed;
+    const present = new Set(seen.map((file) => file.path));
+    for (const [path, known] of this.tracked) {
+      if (present.has(path)) continue;
+      this.tracked.delete(path);
+      this.record(path, known.hash, null);
+      changed = true;
+    }
+    if (changed) this.saveStatCache();
+  }
+  /** The file's hash once copied in; null when it was removed before the copy (the next sweep records that). */
+  async storeIfPresent(path) {
+    try {
+      return await this.blobs.put(join17(this.dir, path));
+    } catch (error) {
+      if (error.code === "ENOENT") return null;
+      throw error;
+    }
+  }
+  async observe(path, stat2) {
+    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;
+    this.tracked.set(path, { hash, stat: stat2 });
+    if (known.hash !== hash) this.record(path, known.hash, hash);
+    return known.hash !== hash || known.stat !== stat2;
+  }
+  record(path, before, after) {
+    const window = this.windows.at(-1);
+    if (window) this.touch(window);
+    const group = window ?? this.outsideGroup();
+    const earlier = group.changes.get(path);
+    const from = earlier ? earlier.before : before;
+    if (from === after) group.changes.delete(path);
+    else group.changes.set(path, { path, before: from, after });
+  }
+  outsideGroup() {
+    const { quietMs = 2e3, maxGroupMs = 3e4 } = this.options;
+    const closeIn = (ms) => {
+      const timer = setTimeout(() => this.background(() => this.commitOutside()), ms);
+      timer.unref?.();
+      return timer;
+    };
+    if (!this.outside) {
+      this.outside = this.newGroup(OUTSIDE, OUTSIDE_LABEL);
+      this.maxTimer = closeIn(maxGroupMs);
+    }
+    clearTimeout(this.quietTimer);
+    this.quietTimer = closeIn(quietMs);
+    return this.outside;
+  }
+  newGroup(who, label) {
+    return { id: randomUUID7(), who, label, startedAt: this.now(), changes: /* @__PURE__ */ new Map() };
+  }
+  async commitOutside() {
+    clearTimeout(this.quietTimer);
+    clearTimeout(this.maxTimer);
+    const group = this.outside;
+    this.outside = null;
+    if (group) await this.commit(group);
+  }
+  async commit(group, extra = {}) {
+    if (!group.changes.size) return null;
+    const { changes, ...rest } = group;
+    const files = [...changes.values()].sort((a, b) => a.path.localeCompare(b.path));
+    const entry = { ...rest, endedAt: this.now(), files, ...extra };
+    this.log.entries.push(entry);
+    try {
+      saveRecord(this.logFile, this.log, { type: "entry", entry });
+    } catch (error) {
+      this.log.entries.pop();
+      throw error;
+    }
+    for (const listener of this.listeners) listener(entry);
+    await this.keepWithinBudget();
+    return entry;
+  }
+  /** Stored bytes beyond what the current files need: a project larger than the budget still keeps its history. */
+  historyBytes() {
+    let current = 0;
+    for (const hash of new Set([...this.tracked.values()].map((file) => file.hash)))
+      current += this.blobs.size(hash);
+    return this.blobs.bytes() - current;
+  }
+  async keepWithinBudget() {
+    const budget = this.options.budgetBytes ?? 2 * 1024 ** 3;
+    let folded = false;
+    while (this.historyBytes() > budget && foldOldest(this.log)) {
+      folded = true;
+      await this.blobs.prune(referencedHashes(this.log, this.manifest()));
+    }
+    if (folded) writeLog(this.logFile, this.log);
+  }
+  /** Before an operation: every write so far is filed, and the outside group is closed so it sorts first. */
+  async settle() {
+    await this.sweep();
+    await this.commitOutside();
+  }
+  /** A watcher saw a write: one sweep per burst takes it in (a deleted folder is reported by its name alone). */
+  noteChange(path) {
+    if (this.notedTimer || !affectsProjectSignature(this.dir, resolve7(this.dir, path))) return;
+    this.notedTimer = setTimeout(() => {
+      this.notedTimer = null;
+      this.background(() => this.sweep());
+    }, 20);
+    this.notedTimer.unref?.();
+  }
+  background(task) {
+    this.queue(task).catch((error) => this.options.onError?.(error));
+  }
+  beginWindow(who, label, idleMs) {
+    return this.queue(async () => {
+      await this.sweep();
+      const window = { ...this.newGroup(who, label), idleMs };
+      this.windows.push(window);
+      this.touch(window);
+      return { id: window.id, close: () => this.queue(() => this.sweepAndEnd(window)) };
+    });
+  }
+  /** A window with no write for its idleMs ends, so a close that never comes cannot hold every later write. */
+  touch(window) {
+    clearTimeout(window.idleTimer);
+    if (window.idleMs === void 0 || !Number.isFinite(window.idleMs)) return;
+    window.idleTimer = setTimeout(
+      () => this.background(() => this.sweepAndEnd(window)),
+      window.idleMs
+    );
+    window.idleTimer.unref?.();
+  }
+  async sweepAndEnd(window) {
+    await this.sweep();
+    return this.endWindow(window);
+  }
+  /** Commits an open window once; ending it again returns the entry it became. */
+  async endWindow(window) {
+    if (!this.windows.includes(window)) return window.entry ?? null;
+    clearTimeout(window.idleTimer);
+    this.windows = this.windows.filter((open) => open !== window);
+    window.entry = await this.commit(window);
+    return window.entry;
+  }
+  /** Every pending write, open window and outside group, committed: for flush and close. */
+  async settleAll() {
+    await this.sweep();
+    for (const window of [...this.windows]) await this.endWindow(window);
+    await this.commitOutside();
+  }
+  /** Writes `target` (path to hash, null deletes) as one entry of `who`'s. */
+  async writeAs(who, label, target, extra) {
+    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) continue;
+        if (hash === null) await rm2(join17(this.dir, path), { force: true });
+        else await this.blobs.writeTo(hash, join17(this.dir, path));
+      }
+      await this.sweep();
+    } finally {
+      this.windows = this.windows.filter((open) => open !== group);
+    }
+    return this.commit(group, extra);
+  }
+  entry(id) {
+    const entry = this.log.entries.find((candidate) => candidate.id === id);
+    if (!entry) throw new Error("That change is no longer kept in this project's history.");
+    return entry;
+  }
+  undoLabel(entry) {
+    if (!entry.undoes) return `Undid: ${entry.label}`;
+    const original = this.log.entries.find((candidate) => candidate.id === entry.undoes);
+    return `Redid: ${original?.label ?? entry.label}`;
+  }
+  async undoNow(id, who, mode) {
+    const entry = this.entry(id);
+    const changed = entry.files.filter(
+      (file) => (this.tracked.get(file.path)?.hash ?? null) !== file.after
+    );
+    if (changed.length && !mode) return { ok: false, conflict: this.conflict(entry, changed) };
+    if (mode === "back-to-before") {
+      const index = this.log.entries.indexOf(entry);
+      const point = index > 0 ? this.log.entries[index - 1].id : START;
+      return {
+        ok: true,
+        entry: await this.restoreNow(point, who, `Went back to before: ${entry.label}`)
+      };
+    }
+    const target = new Map(entry.files.map((file) => [file.path, file.before]));
+    return {
+      ok: true,
+      entry: await this.writeAs(who, this.undoLabel(entry), target, { undoes: id })
+    };
+  }
+  conflict(entry, changed) {
+    const paths = new Set(changed.map((file) => file.path));
+    const after = this.log.entries.slice(this.log.entries.indexOf(entry) + 1);
+    const newer = after.filter((later) => later.files.some((file) => paths.has(file.path)));
+    return { files: [...paths], newer: newer.map((later) => later.id) };
+  }
+  async restoreNow(point, who, label) {
+    const files = manifestAt(this.log, point);
+    if (!files) throw new Error("That point is no longer kept in this project's history.");
+    const target = new Map(
+      [...this.tracked.keys()].map((path) => [path, null])
+    );
+    for (const [path, hash] of files) target.set(path, hash);
+    return this.writeAs(who, label, target, { restoredTo: point });
+  }
+  pointLabel(point) {
+    return point === START ? "the start" : this.entry(point).label;
+  }
+  api() {
+    return {
+      projectId: this.projectId,
+      beginWindow: (who, label, options = {}) => this.beginWindow(who, label, options.idleMs ?? this.options.maxGroupMs ?? 3e4),
+      noteChange: (path) => this.noteChange(path),
+      list: () => {
+        const undone = undoneIds(this.log.entries);
+        return this.log.entries.map((entry) => ({
+          ...entry,
+          pinned: this.log.pins.has(entry.id),
+          undone: undone.has(entry.id)
+        }));
+      },
+      step: (direction, who) => this.queue(async () => {
+        await this.settle();
+        const target = stepTarget(this.log.entries, direction);
+        return target ? this.undoNow(target.id, who) : { ok: true, entry: null };
+      }),
+      undo: (id, { who, mode }) => this.queue(async () => {
+        await this.settle();
+        return this.undoNow(id, who, mode);
+      }),
+      restore: (point, who) => this.queue(async () => {
+        await this.settle();
+        return this.restoreNow(point, who, `Restored: ${this.pointLabel(point)}`);
+      }),
+      peek: (point) => {
+        const files = manifestAt(this.log, point);
+        return files && Object.fromEntries(files);
+      },
+      readBlob: (hash) => this.blobs.read(hash),
+      pin: (id, pinned) => {
+        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 });
+      },
+      onEntry: (listener) => {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+      },
+      flush: () => this.queue(() => this.settleAll()),
+      close: async () => {
+        if (this.notedTimer) clearTimeout(this.notedTimer);
+        await this.queue(() => this.settleAll());
+      }
+    };
+  }
+};
+async function openProjectHistory(options) {
+  const projectId = projectHistoryId(options.projectDir, options.historyRoot);
+  const blobs = await openBlobStore(join17(options.historyRoot, projectId, "blobs"));
+  const engine = new Engine(options, projectId, blobs);
+  await engine.queue(() => engine.start());
+  return engine.api();
+}
+
 // src/helpers/duplicateElement.ts
 import { ensureHfIds as ensureHfIds3 } from "@hyperframes/parsers/hf-ids";
 function duplicateElementInHtml(source, target, newId, at) {
@@ -5227,6 +5895,7 @@ function updateBackgroundRemovalProgress(state, event) {
   state.avgMsPerFrame = event.avgMsPerFrame;
 }
 export {
+  START as HISTORY_START,
   MIME_TYPES,
   PREVIEW_BUNDLE_OPTIONS,
   STUDIO_MANUAL_EDITS_PATH,
@@ -5250,6 +5919,7 @@ export {
   getMimeType,
   identifyFileWrite,
   isSafePath,
+  openProjectHistory,
   parseSourceDocument,
   patchElementInHtml,
   removeElementFromHtml,