@hyperframes/studio-server 0.8.76 → 0.8.78

package/dist/index.js

@@ -22,7 +22,7 @@ import {
   isAutoProxyEnabled,
   proxyEtagSalt,
   resolvePreviewMediaCodecProbeCache
-} from "./chunk-5PGWTBCL.js";
+} from "./chunk-X3T65KC2.js";
 import {
   ProxyCapacityError,
   ProxyTranscodeError,
@@ -72,9 +72,18 @@ function isInHiddenOrVendorDir(relPath) {
   const segments = relPath.split("/");
   return segments.slice(0, -1).some((seg) => seg.startsWith(".") || seg === "node_modules");
 }
+var UNREADABLE_DIR_CODES = /* @__PURE__ */ new Set(["EACCES", "EPERM", "ENOENT", "ENOTDIR"]);
 function walkDir(dir, prefix = "") {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    const code = err.code;
+    if (!prefix || !code || !UNREADABLE_DIR_CODES.has(code)) throw err;
+    return [];
+  }
   const files = [];
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+  for (const entry of entries) {
     const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
     if (IGNORE_DIRS.has(entry.name) || shouldIgnoreDir(rel)) continue;
     if (entry.isDirectory()) {
@@ -161,6 +170,15 @@ function openNoFollow(filePath, flags) {
     return null;
   }
 }
+function isUnchanged(filePath, expected) {
+  const fd = openNoFollow(filePath, constants.O_RDONLY);
+  if (fd === null) return false;
+  try {
+    return readFileSync(fd, "utf-8") === expected;
+  } finally {
+    closeSync(fd);
+  }
+}
 function stampFileHfIds(filePath) {
   let fd = openNoFollow(filePath, constants.O_RDWR);
   let writable = true;
@@ -179,7 +197,7 @@ function stampFileHfIds(filePath) {
       const mode = fstatSync(fd).mode;
       closeSync(fd);
       fd = null;
-      replaceFileAtomically(filePath, normalized, mode);
+      if (isUnchanged(filePath, html)) replaceFileAtomically(filePath, normalized, mode);
     }
     return normalized;
   } catch (err) {
@@ -776,6 +794,8 @@ function applyFileMutations(projectDir, mutations, requestToken, writeFile = (pa
   }));
   const results = [];
   const attempted = [];
+  for (const mutation of prepared)
+    assertExpectedVersion(mutation.expectedVersion, readFileSync4(mutation.absPath, "utf-8"));
   try {
     for (const mutation of prepared) {
       results.push(applyOneMutation(projectDir, mutation, requestToken, writeFile, attempted));
@@ -785,7 +805,8 @@ function applyFileMutations(projectDir, mutations, requestToken, writeFile = (pa
     const rollbackErrors = [];
     for (const mutation of attempted.reverse()) {
       try {
-        writeFile(mutation.absPath, mutation.before, "utf-8");
+        if (!mutation.written || readFileSync4(mutation.absPath, "utf-8") === mutation.after)
+          writeFile(mutation.absPath, mutation.before, "utf-8");
         clearFileWriteReceipt(mutation.absPath, mutation.version, mutation.writeToken);
       } catch (rollbackError) {
         rollbackErrors.push(rollbackError);
@@ -818,8 +839,10 @@ function applyOneMutation(projectDir, mutation, requestToken, writeFile, attempt
   const before = current;
   const version = fileContentVersion(mutation.after);
   const writeToken = createWriteToken(requestToken);
-  attempted.push({ ...mutation, before, version, writeToken });
+  const attempt = { ...mutation, before, version, writeToken, written: false };
+  attempted.push(attempt);
   writeFile(mutation.absPath, mutation.after, "utf-8");
+  attempt.written = true;
   recordFileWriteReceipt(mutation.absPath, {
     path: mutation.sourceFile,
     version,
@@ -1133,6 +1156,7 @@ function requestSubPath(url, route) {
 }
 
 // src/routes/files.ts
+import { insertBeforeCloseTag } from "@hyperframes/core/compiler/html-document";
 async function loadGsapParser() {
   return import("@hyperframes/parsers/gsap-parser-recast");
 }
@@ -1679,8 +1703,8 @@ async function prepareGsapMutationScript(c, res, firstMutation) {
       `window.__timelines["${compId}"] = tl;`,
       "</script>"
     ].join("\n");
-    html = html.includes("</body>") ? html.replace("</body>", `${bootstrap}
-</body>`) : `${html}
+    html = insertBeforeCloseTag(html, "body", `${bootstrap}
+`) ?? `${html}
 ${bootstrap}`;
     block = extractGsapScriptBlock(html);
   }
@@ -3325,6 +3349,7 @@ import { join as join9, resolve as resolve4 } from "path";
 import { createHash as createHash4 } from "crypto";
 import {
   injectScriptsIntoHtml,
+  insertBeforeCloseTag as insertBeforeCloseTag2,
   stripEmbeddedRuntimeScripts as stripEmbeddedRuntimeScripts2
 } from "@hyperframes/core/compiler";
 import { isWithinProjectRoot } from "@hyperframes/parsers/asset-resolution";
@@ -3550,9 +3575,8 @@ function injectProjectSignature(html, signature) {
       tag
     );
   }
-  if (html.includes("</head>")) return html.replace("</head>", `${tag}
-</head>`);
-  return `${tag}
+  return insertBeforeCloseTag2(html, "head", `${tag}
+`) ?? `${tag}
 ${html}`;
 }
 function readStudioMotionManifestContent(projectDir) {
@@ -3577,9 +3601,8 @@ function parseStudioMotionManifestContent(content) {
   }
 }
 function injectScriptTagIntoHead(html, scriptTag) {
-  if (html.includes("</head>")) return html.replace("</head>", `${scriptTag}
-</head>`);
-  return `${scriptTag}
+  return insertBeforeCloseTag2(html, "head", `${scriptTag}
+`) ?? `${scriptTag}
 ${html}`;
 }
 function htmlHasGsap(html) {
@@ -3749,8 +3772,8 @@ function registerPreviewRoutes(api, adapter) {
       }
       if (!bundled.includes("hyperframe.runtime") && !bundled.includes("hyperframes-preview-runtime")) {
         const runtimeTag = `<script src="${adapter.runtimeUrl}"></script>`;
-        bundled = bundled.includes("</body>") ? bundled.replace("</body>", `${runtimeTag}
-</body>`) : bundled + `
+        bundled = insertBeforeCloseTag2(bundled, "body", `${runtimeTag}
+`) ?? `${bundled}
 ${runtimeTag}`;
       }
       const baseHref = `/api/projects/${project.id}/preview/`;
@@ -5174,157 +5197,12 @@ function registerGlobalAssetRoutes(api) {
   api.get("/assets/global", (c) => c.json({ assets: readGlobalAssets().map(toPublicAsset) }));
 }
 
-// src/routes/history.ts
-var YOU = { kind: "person", name: "You" };
-var MAX_WINDOW_IDLE_MS = 10 * 6e4;
-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;
-function writing(c) {
-  const header = c.req.header("X-Hyperframes-Write-Token");
-  return header ? { writeToken: createWriteToken(header) } : {};
-}
-function idleOf(body) {
-  const idleMs = body.idleMs;
-  return typeof idleMs === "number" && idleMs > 0 ? Math.min(idleMs, MAX_WINDOW_IDLE_MS) : void 0;
-}
-function versionsOf(value) {
-  if (!value || typeof value !== "object") return void 0;
-  const pairs = Object.entries(value).filter(
-    (pair) => typeof pair[1] === "string"
-  );
-  return pairs.length ? Object.fromEntries(pairs) : void 0;
-}
-function nextStep(history, direction) {
-  const target = history.next(direction);
-  if (!target) return null;
-  const paths = target.files.map((file) => file.path);
-  return { id: target.id, label: target.label, endedAt: target.endedAt, paths };
-}
-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) => {
-      const entries = history.list();
-      return { entries, back: nextStep(history, "back"), forward: nextStep(history, "forward") };
-    })
-  );
-  api.post(
-    `${base}/step`,
-    (c) => withHistory(
-      adapter,
-      c,
-      (history, body) => history.step(body.direction === "forward" ? "forward" : "back", YOU, writing(c))
-    )
-  );
-  api.post(
-    `${base}/undo`,
-    (c) => withHistory(adapter, c, (history, body) => {
-      const mode = body.mode === "just-this" || body.mode === "back-to-before" ? body.mode : void 0;
-      return history.undo(text(body.entryId) ?? "", { who: YOU, mode, ...writing(c) });
-    })
-  );
-  api.post(
-    `${base}/restore`,
-    (c) => withHistory(
-      adapter,
-      c,
-      (history, body) => history.restore(text(body.point) ?? "", YOU, writing(c))
-    )
-  );
-  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}/claim`,
-    (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 },
-        ...overwrote && { overwrote }
-      });
-      return { claimed };
-    })
-  );
-  api.post(
-    `${base}/window`,
-    (c) => withHistory(adapter, c, async (history, body) => {
-      const idleMs = idleOf(body);
-      const window = await history.beginWindow(
-        YOU,
-        text(body.label) ?? "Edited in Studio",
-        idleMs ? { idleMs } : void 0
-      );
-      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();
-  registerProjectRoutes(api, adapter);
-  registerFileRoutes(api, adapter);
-  registerPreviewRoutes(api, adapter);
-  registerLintRoutes(api, adapter);
-  registerRenderRoutes(api, adapter);
-  registerThumbnailRoutes(api, adapter);
-  registerSelectionRoutes(api, adapter);
-  registerMediaRoutes(api, adapter);
-  registerWaveformRoutes(api, adapter);
-  registerFontRoutes(api);
-  registerRegistryRoutes(api, adapter);
-  registerGlobalAssetRoutes(api);
-  registerHistoryRoutes(api, adapter);
-  return api;
-}
-
 // src/history/projectHistory.ts
-import { randomUUID as randomUUID7 } from "crypto";
+import { randomUUID as randomUUID8 } from "crypto";
 import { rm as rm2 } from "fs/promises";
-import { existsSync as existsSync12, mkdirSync as mkdirSync10, readFileSync as readFileSync17 } from "fs";
+import { existsSync as existsSync12, mkdirSync as mkdirSync11, readFileSync as readFileSync18 } from "fs";
 import { homedir as homedir2 } from "os";
-import { join as join18, relative as relative4, resolve as resolve7, sep as sep3 } from "path";
+import { join as join19, relative as relative4, resolve as resolve7, sep as sep3 } from "path";
 
 // src/history/blobStore.ts
 import { createHash as createHash6, randomUUID as randomUUID5 } from "crypto";
@@ -5428,8 +5306,89 @@ function projectHistoryId(projectDir, historyRoot) {
   return id;
 }
 
+// src/history/ownerLock.ts
+import { randomUUID as randomUUID7 } from "crypto";
+import { linkSync, mkdirSync as mkdirSync9, readFileSync as readFileSync16, rmSync as rmSync5, writeFileSync as writeFileSync8 } from "fs";
+import { join as join18 } from "path";
+var HistoryBusyError = class extends Error {
+  constructor(pid) {
+    super(`This project's history is open in another process (pid ${pid}).`);
+    this.pid = pid;
+    this.name = "HistoryBusyError";
+  }
+  pid;
+};
+function alive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+function ownerOf(file) {
+  try {
+    const text2 = readFileSync16(file, "utf-8");
+    return /^\d+$/.test(text2) ? Number(text2) : Number.NaN;
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+function claim(file) {
+  const draft = `${file}-${randomUUID7()}.tmp`;
+  writeFileSync8(draft, String(process.pid));
+  try {
+    linkSync(draft, file);
+    return true;
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    return false;
+  } finally {
+    rmSync5(draft, { force: true });
+  }
+}
+function releaseOwn(file) {
+  if (ownerOf(file) === process.pid) rmSync5(file, { force: true });
+}
+function evictDeadOwner(file) {
+  const evictor = `${file}.evict`;
+  if (!claim(evictor)) {
+    const holder = ownerOf(evictor);
+    if (holder !== null && !alive(holder)) rmSync5(evictor, { force: true });
+    return false;
+  }
+  try {
+    const pid = ownerOf(file);
+    if (pid !== null && !alive(pid)) rmSync5(file, { force: true });
+    return true;
+  } finally {
+    releaseOwn(evictor);
+  }
+}
+async function takeHistoryOwnership(home, waitMs) {
+  const file = join18(home, "owner.pid");
+  const deadline = Date.now() + waitMs;
+  mkdirSync9(home, { recursive: true });
+  for (; ; ) {
+    if (claim(file)) {
+      let held = true;
+      return () => {
+        if (held) releaseOwn(file);
+        held = false;
+      };
+    }
+    const pid = ownerOf(file);
+    if (pid === null) continue;
+    if (!alive(pid) && evictDeadOwner(file)) continue;
+    if (Date.now() >= deadline) throw new HistoryBusyError(pid);
+    await new Promise((settle) => setTimeout(settle, 50));
+  }
+}
+
 // src/history/historyLog.ts
-import { closeSync as closeSync5, constants as constants4, mkdirSync as mkdirSync9, openSync as openSync5, readFileSync as readFileSync16, writeSync as writeSync2 } from "fs";
+import { closeSync as closeSync5, constants as constants4, mkdirSync as mkdirSync10, openSync as openSync5, readFileSync as readFileSync17, writeSync as writeSync2 } from "fs";
 import { dirname as dirname7 } from "path";
 var START = "start";
 function parseRecord(line) {
@@ -5442,7 +5401,7 @@ function parseRecord(line) {
 function readLog(file, onUnreadable) {
   let text2;
   try {
-    text2 = readFileSync16(file, "utf-8");
+    text2 = readFileSync17(file, "utf-8");
   } catch {
     return null;
   }
@@ -5482,7 +5441,7 @@ function writeLog(file, log) {
     ...log.entries.map((entry) => ({ type: "entry", entry })),
     ...[...log.pins].map((id) => ({ type: "pin", id, pinned: true }))
   ];
-  mkdirSync9(dirname7(file), { recursive: true });
+  mkdirSync10(dirname7(file), { recursive: true });
   replaceFileAtomically(file, records.map((r) => `${JSON.stringify(r)}
 `).join(""), 420);
 }
@@ -5540,7 +5499,8 @@ function referencedHashes(log, current) {
 }
 
 // src/history/projectHistory.ts
-var DEFAULT_HISTORY_ROOT = join18(homedir2(), ".cache", "hyperframes", "history");
+var DEFAULT_HISTORY_ROOT = join19(homedir2(), ".cache", "hyperframes", "history");
+var MAX_WINDOW_IDLE_MS = 10 * 6e4;
 var OUTSIDE = { kind: "outside", name: "Outside" };
 var OUTSIDE_LABEL = "Changed outside the app";
 var RACY_MS = 2e3;
@@ -5554,6 +5514,7 @@ function splitAt(change, at, kept) {
     { ...change, before: at }
   ];
 }
+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);
   const from = earlier ? earlier.before : before;
@@ -5566,7 +5527,7 @@ var Engine = class {
     this.projectId = projectId;
     this.blobs = blobs;
     this.dir = resolve7(options.projectDir);
-    this.home = join18(options.historyRoot, projectId);
+    this.home = join19(options.historyRoot, projectId);
   }
   options;
   projectId;
@@ -5586,7 +5547,7 @@ var Engine = class {
   listeners = /* @__PURE__ */ new Set();
   tail = Promise.resolve();
   get logFile() {
-    return join18(this.home, "log.jsonl");
+    return join19(this.home, "log.jsonl");
   }
   now() {
     return (this.options.now ?? Date.now)();
@@ -5612,14 +5573,22 @@ var Engine = class {
       const cached = cache.get(path);
       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();
   }
+  reopenClosedWindow() {
+    const closed = this.options.closedWindow;
+    if (!closed || this.log.entries.some((entry) => entry.id === closed.id)) return;
+    const { id, who, label, startedAt, lastWriteAt, idleMs } = closed;
+    this.windows.push({ id, who, label, startedAt, lastWriteAt, idleMs, changes: /* @__PURE__ */ new Map() });
+  }
   async firstOpen() {
     const sweptAt = Date.now();
     for (const file of listProjectFiles(this.dir))
       this.tracked.set(file.path, {
-        hash: await this.blobs.put(join18(this.dir, file.path)),
+        hash: await this.blobs.put(join19(this.dir, file.path)),
         stat: statKey(file, sweptAt)
       });
     this.log.baseline = this.manifest();
@@ -5631,7 +5600,7 @@ var Engine = class {
   }
   readStatCache() {
     try {
-      const files = JSON.parse(readFileSync17(join18(this.home, "stat.json"), "utf-8"));
+      const files = JSON.parse(readFileSync18(join19(this.home, "stat.json"), "utf-8"));
       return new Map(Object.entries(files));
     } catch {
       return /* @__PURE__ */ new Map();
@@ -5639,8 +5608,8 @@ var Engine = class {
   }
   saveStatCache() {
     const files = JSON.stringify(Object.fromEntries(this.tracked));
-    mkdirSync10(this.home, { recursive: true });
-    replaceFileAtomically(join18(this.home, "stat.json"), files, 420);
+    mkdirSync11(this.home, { recursive: true });
+    replaceFileAtomically(join19(this.home, "stat.json"), files, 420);
   }
   /**
    * Takes in every write since the last sweep and files each change to its writer. ponytail: always the whole
@@ -5649,15 +5618,17 @@ var Engine = class {
   async sweep() {
     if (!existsSync12(this.dir)) return;
     const sweptAt = Date.now();
-    const seen = listProjectFiles(this.dir);
+    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)) || changed;
+      changed = await this.observe(file.path, statKey(file, sweptAt), changedAt(file)) || 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);
+      const removedAt = sweptAt;
+      await this.record(path, known.hash, null, removedAt);
       changed = true;
     }
     if (changed) this.saveStatCache();
@@ -5665,24 +5636,27 @@ 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(join18(this.dir, path));
+      return await this.blobs.put(join19(this.dir, path));
     } catch (error) {
       if (error.code === "ENOENT") return null;
       throw error;
     }
   }
-  async observe(path, stat2) {
+  async observe(path, stat2, at) {
     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);
+    if (known.hash !== hash) await this.record(path, known.hash, hash, at);
     return known.hash !== hash || known.stat !== stat2;
   }
-  record(path, before, after) {
+  async record(path, before, after, at) {
+    const endedBeforeThisWrite = this.windows.filter((open) => !takesWrite(open, at));
+    if (endedBeforeThisWrite.length) await this.commitOutside();
+    for (const window2 of endedBeforeThisWrite) await this.endWindow(window2);
     const window = this.windows.at(-1);
-    if (window) this.touch(window);
+    if (window) this.touch(window, at);
     addChange(window ?? this.outsideGroup(), path, before, after);
   }
   /** ponytail: another's write between Studio's write and its sweep folds into Studio's entry (per-write tokens). */
@@ -5790,7 +5764,7 @@ var Engine = class {
     return this.outside;
   }
   newGroup(who, label) {
-    return { id: randomUUID7(), who, label, startedAt: this.now(), changes: /* @__PURE__ */ new Map() };
+    return { id: randomUUID8(), who, label, startedAt: this.now(), changes: /* @__PURE__ */ new Map() };
   }
   async commitOutside() {
     clearTimeout(this.quietTimer);
@@ -5801,9 +5775,11 @@ var Engine = class {
   }
   async commit(group, extra = {}) {
     if (!group.changes.size) return null;
-    const { id, who, label, startedAt, changes } = group;
+    const { id, who, label, startedAt, lastWriteAt, changes } = group;
     const files = [...changes.values()].sort((a, b) => a.path.localeCompare(b.path));
-    const entry = { id, who, label, startedAt, endedAt: this.now(), files, ...extra };
+    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 };
     this.log.entries.push(entry);
     try {
       saveRecord(this.logFile, this.log, { type: "entry", entry });
@@ -5854,12 +5830,14 @@ var Engine = class {
       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)) };
+      this.touch(window, Date.now());
+      const close = () => this.queue(() => this.sweepAndEnd(window));
+      return { id: window.id, startedAt: window.startedAt, close };
     });
   }
   /** A window with no write for its idleMs ends, so a close that never comes cannot hold every later write. */
-  touch(window) {
+  touch(window, at) {
+    window.lastWriteAt = Math.max(window.lastWriteAt ?? at, at);
     clearTimeout(window.idleTimer);
     if (window.idleMs === void 0 || !Number.isFinite(window.idleMs)) return;
     window.idleTimer = setTimeout(
@@ -5904,7 +5882,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) {
-    const absPath = join18(this.dir, path);
+    const absPath = join19(this.dir, path);
     const { writeToken } = this;
     if (writeToken) {
       const version = hash === null ? DELETED_VERSION : hashVersion(hash);
@@ -6033,10 +6011,180 @@ var Engine = class {
 };
 async function openProjectHistory(options) {
   const projectId = projectHistoryId(options.projectDir, options.historyRoot);
-  const blobs = await openBlobStore(join18(options.historyRoot, projectId, "blobs"));
-  const engine = new Engine(options, projectId, blobs);
-  await engine.queue(() => engine.start());
-  return engine.api();
+  const release = await takeHistoryOwnership(
+    join19(options.historyRoot, projectId),
+    options.ownerWaitMs ?? 5e3
+  );
+  try {
+    const blobs = await openBlobStore(join19(options.historyRoot, projectId, "blobs"));
+    const engine = new Engine(options, projectId, blobs);
+    await engine.queue(() => engine.start());
+    const api = engine.api();
+    return {
+      ...api,
+      close: () => api.close().finally(release)
+    };
+  } catch (error) {
+    release();
+    throw error;
+  }
+}
+
+// src/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;
+function writing(c) {
+  const header = c.req.header("X-Hyperframes-Write-Token");
+  return header ? { writeToken: createWriteToken(header) } : {};
+}
+function whoOf(body) {
+  const who = body.who;
+  const name = text(who?.name);
+  return who?.kind === "agent" && name ? { kind: "agent", name } : YOU;
+}
+function idleOf(body) {
+  const idleMs = body.idleMs;
+  return typeof idleMs === "number" && idleMs > 0 ? Math.min(idleMs, MAX_WINDOW_IDLE_MS) : void 0;
+}
+function versionsOf(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const pairs = Object.entries(value).filter(
+    (pair) => typeof pair[1] === "string"
+  );
+  return pairs.length ? Object.fromEntries(pairs) : void 0;
+}
+function nextStep(history, direction) {
+  const target = history.next(direction);
+  if (!target) return null;
+  const paths = target.files.map((file) => file.path);
+  return { id: target.id, label: target.label, endedAt: target.endedAt, paths };
+}
+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) => {
+      const entries = history.list();
+      return { entries, back: nextStep(history, "back"), forward: nextStep(history, "forward") };
+    })
+  );
+  api.post(
+    `${base}/step`,
+    (c) => withHistory(
+      adapter,
+      c,
+      (history, body) => history.step(body.direction === "forward" ? "forward" : "back", YOU, writing(c))
+    )
+  );
+  api.post(
+    `${base}/undo`,
+    (c) => withHistory(adapter, c, (history, body) => {
+      const mode = body.mode === "just-this" || body.mode === "back-to-before" ? body.mode : void 0;
+      return history.undo(text(body.entryId) ?? "", { who: whoOf(body), mode, ...writing(c) });
+    })
+  );
+  api.post(
+    `${base}/restore`,
+    (c) => withHistory(
+      adapter,
+      c,
+      (history, body) => history.restore(text(body.point) ?? "", whoOf(body), writing(c))
+    )
+  );
+  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.get(`${base}/blob/:hash`, async (c) => {
+    const history = await historyOf(adapter, c);
+    const hash = c.req.param("hash") ?? "";
+    const missing = () => c.json({ error: "That file is not kept in this project's history." }, 404);
+    if (!history || !/^[0-9a-f]{64}$/.test(hash)) return missing();
+    const bytes = await history.readBlob(hash).catch(() => null);
+    return bytes ? c.body(new Uint8Array(bytes)) : missing();
+  });
+  api.post(
+    `${base}/claim`,
+    (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 },
+        ...overwrote && { overwrote }
+      });
+      return { claimed };
+    })
+  );
+  api.post(
+    `${base}/window`,
+    (c) => withHistory(adapter, c, async (history, body) => {
+      const idleMs = idleOf(body);
+      const window = await history.beginWindow(
+        whoOf(body),
+        text(body.label) ?? "Edited in Studio",
+        idleMs ? { idleMs } : void 0
+      );
+      windows.set(window.id, { history, window });
+      return { windowId: window.id, startedAt: window.startedAt };
+    })
+  );
+  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();
+  registerProjectRoutes(api, adapter);
+  registerFileRoutes(api, adapter);
+  registerPreviewRoutes(api, adapter);
+  registerLintRoutes(api, adapter);
+  registerRenderRoutes(api, adapter);
+  registerThumbnailRoutes(api, adapter);
+  registerSelectionRoutes(api, adapter);
+  registerMediaRoutes(api, adapter);
+  registerWaveformRoutes(api, adapter);
+  registerFontRoutes(api);
+  registerRegistryRoutes(api, adapter);
+  registerGlobalAssetRoutes(api);
+  registerHistoryRoutes(api, adapter);
+  return api;
 }
 
 // src/helpers/duplicateElement.ts
@@ -6092,26 +6240,26 @@ function numericAttribute(element, name) {
 
 // src/helpers/previewDocumentStore.ts
 import { createHash as createHash7 } from "crypto";
-import { mkdirSync as mkdirSync11, readFileSync as readFileSync18, readdirSync as readdirSync7, rmSync as rmSync5 } from "fs";
-import { join as join19 } from "path";
+import { mkdirSync as mkdirSync12, readFileSync as readFileSync19, readdirSync as readdirSync7, rmSync as rmSync6 } from "fs";
+import { join as join20 } from "path";
 function createPreviewDocumentStore(dir, salt) {
-  const fileFor = (key) => join19(dir, `${createHash7("sha256").update(`${salt}
+  const fileFor = (key) => join20(dir, `${createHash7("sha256").update(`${salt}
 ${key}`).digest("hex").slice(0, 32)}.html`);
   return {
     read(key) {
       try {
-        return readFileSync18(fileFor(key), "utf-8");
+        return readFileSync19(fileFor(key), "utf-8");
       } catch {
         return null;
       }
     },
     write(key, html) {
       try {
-        mkdirSync11(dir, { recursive: true });
+        mkdirSync12(dir, { recursive: true });
         const file = fileFor(key);
         replaceFileAtomically(file, html, 420);
         for (const name of readdirSync7(dir)) {
-          if (join19(dir, name) !== file) rmSync5(join19(dir, name), { force: true });
+          if (join20(dir, name) !== file) rmSync6(join20(dir, name), { force: true });
         }
       } catch {
       }
@@ -6190,6 +6338,8 @@ export {
   DEFAULT_HISTORY_ROOT,
   DELETED_VERSION,
   START as HISTORY_START,
+  HistoryBusyError,
+  MAX_WINDOW_IDLE_MS,
   MIME_TYPES,
   PREVIEW_BUNDLE_OPTIONS,
   STUDIO_MANUAL_EDITS_PATH,