@hyperframes/studio-server 0.8.76 → 0.8.77

package/dist/{chunk-5PGWTBCL.js → chunk-X3T65KC2.js}

@@ -12,6 +12,7 @@ import {
 
 // src/helpers/mediaProxyPreview.ts
 import { resolve } from "path";
+import { insertBeforeCloseTag } from "@hyperframes/core/compiler/html-document";
 function isAutoProxyEnabled(adapter) {
   return adapter.autoProxy !== false;
 }
@@ -22,12 +23,6 @@ function proxyEtagSalt(raw) {
   if (raw === void 0) return "";
   return `:proxy:${raw}:${PROXY_PARAMS_VERSION}`;
 }
-function injectScriptTagIntoHead(html, scriptTag) {
-  if (html.includes("</head>")) return html.replace("</head>", `${scriptTag}
-</head>`);
-  return `${scriptTag}
-${html}`;
-}
 async function injectMediaCodecMapIntoHtml(html, projectDir, htmlSources, probeCache) {
   let map;
   try {
@@ -52,7 +47,9 @@ async function injectMediaCodecMapIntoHtml(html, projectDir, htmlSources, probeC
   }
   const json = JSON.stringify(map).replace(/</g, "\\u003c").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
   const tag = `<script data-hf-media-codec-map>window.__HF_MEDIA_CODEC_MAP__=${json};</script>`;
-  return injectScriptTagIntoHead(html, tag);
+  return insertBeforeCloseTag(html, "head", `${tag}
+`) ?? `${tag}
+${html}`;
 }
 async function injectMediaCodecMap(html, adapter, projectDir, compSrcPath, probeCache) {
   if (!isAutoProxyEnabled(adapter)) return html;
@@ -66,4 +63,4 @@ export {
   injectMediaCodecMapIntoHtml,
   injectMediaCodecMap
 };
-//# sourceMappingURL=chunk-5PGWTBCL.js.map
+//# sourceMappingURL=chunk-X3T65KC2.js.map

package/dist/chunk-X3T65KC2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/helpers/mediaProxyPreview.ts"],"sourcesContent":["import { resolve } from \"node:path\";\nimport { insertBeforeCloseTag } from \"@hyperframes/core/compiler/html-document\";\nimport type { StudioApiAdapter } from \"../types.js\";\nimport {\n  createMediaCodecProbeCache,\n  proxyVariantFor,\n  recordProxyPrewarm,\n  scanProjectMediaCodecMap,\n  shouldPrewarmProxy,\n  type HtmlSourceLike,\n  type MediaCodecMap,\n  type MediaCodecProbeCache,\n} from \"./mediaCodecMap.js\";\nimport { resolveProxy, PROXY_PARAMS_VERSION } from \"./proxyTranscoder.js\";\n\n/**\n * Transparent-media-proxy wiring shared by `routes/preview.ts`\n * (docs/plans/2026-07-14-002-feat-transparent-media-proxies-plan.md, unit U3).\n * Split out of the route module to keep it under the repo's 600-line file cap.\n */\n\n/**\n * Preview-route-local adapter surface for the auto-proxy feature. Both\n * fields are optional so any existing `StudioApiAdapter` value remains\n * structurally assignable without editing the shared interface:\n * `autoProxy` defaults to true (on) when omitted — a later unit wires the\n * CLI `--no-proxy` flag / `hyperframes.json` setting through it;\n * `mediaCodecProbeCache` lets a host share one probe cache across\n * preview/play/static-server surfaces instead of each constructing its own.\n */\nexport type PreviewApiAdapter = StudioApiAdapter & {\n  autoProxy?: boolean;\n  mediaCodecProbeCache?: MediaCodecProbeCache;\n  /** Keeps built preview documents across restarts, keyed by project id and preview ETag. */\n  previewDocuments?: PreviewDocumentStore;\n};\n\nexport interface PreviewDocumentStore {\n  read(key: string): string | null;\n  write(key: string, html: string): void;\n}\n\nexport function isAutoProxyEnabled(adapter: PreviewApiAdapter): boolean {\n  return adapter.autoProxy !== false;\n}\n\n/** One probe cache per server instance — construct once in `registerPreviewRoutes`\n * and reuse across every request so the mtime-cache benefit in\n * `scanProjectMediaCodecMap` actually applies. A host that wants to share the\n * cache across other surfaces (play, static project server) can pass its own\n * via `adapter.mediaCodecProbeCache`. */\nexport function resolvePreviewMediaCodecProbeCache(\n  adapter: PreviewApiAdapter,\n): MediaCodecProbeCache {\n  return adapter.mediaCodecProbeCache ?? createMediaCodecProbeCache();\n}\n\n/**\n * ETag salt for `?hf-proxy=` asset requests, mirroring `variablesEtagSalt` in\n * preview.ts: salted by the raw param value plus the transcoder's params\n * version, so a future proxy-recipe change (which bumps `PROXY_PARAMS_VERSION`)\n * or a different proxy variant invalidates cached 304s without needing to\n * touch the proxy file itself.\n */\nexport function proxyEtagSalt(raw: string | undefined): string {\n  if (raw === undefined) return \"\";\n  return `:proxy:${raw}:${PROXY_PARAMS_VERSION}`;\n}\n\n/**\n * Injects `window.__HF_MEDIA_CODEC_MAP__` (the U1 codec-facts scan) into\n * served composition HTML, and fire-and-forget pre-warms `resolveProxy` for\n * every entry whose codec no browser decodes, so an element's proactive swap\n * usually hits a warm cache (KTD: protects the per-origin connection budget\n * under held responses). Conditionally hostile codecs are injected but NOT\n * pre-warmed: the requesting browser usually plays them, and the transcode\n * runs concurrently with its first layout. No second concurrency limiter here\n * — the transcoder's own global bound throttles both pre-warm and\n * element-triggered calls. Pre-warm failures are swallowed; an actual\n * `?hf-proxy=` request surfaces them as a 502 and transcodes lazily.\n * Alpha-bearing entries pre-warm their VP8/WebM variant.\n *\n * The single shared implementation for every auto-proxy surface — the studio\n * preview route (via `injectMediaCodecMap` below) and the CLI's composition /\n * static project servers (via the `./media-proxy-preview` subpath export).\n * Empty maps leave HTML untouched, preserving the normal no-hostile-media\n * preview path. On-demand proxy requests enforce the same eligibility gate.\n */\nexport async function injectMediaCodecMapIntoHtml(\n  html: string,\n  projectDir: string,\n  htmlSources: HtmlSourceLike[],\n  probeCache?: MediaCodecProbeCache,\n): Promise<string> {\n  let map: MediaCodecMap;\n  try {\n    map = await scanProjectMediaCodecMap(\n      projectDir,\n      htmlSources,\n      probeCache ? { cache: probeCache } : {},\n    );\n  } catch {\n    // Best-effort: a scan failure must never block serving the page.\n    return html;\n  }\n  if (Object.keys(map).length === 0) return html;\n  for (const [rootRelativePathname, facts] of Object.entries(map)) {\n    if (!shouldPrewarmProxy(facts)) continue;\n    recordProxyPrewarm();\n    resolveProxy(\n      projectDir,\n      resolve(projectDir, rootRelativePathname.replace(/^\\/+/, \"\")),\n      proxyVariantFor(facts),\n    ).catch(() => {\n      // Swallowed: the pre-warm is best-effort. A real `?hf-proxy=` request\n      // for this asset re-attempts the transcode and reports failure (502).\n    });\n  }\n  // <-escape prevents a src path containing \"</script>\" from breaking out of\n  // the injected tag, mirroring injectPreviewVariables in helpers/previewVariables.ts.\n  const json = JSON.stringify(map)\n    .replace(/</g, \"\\\\u003c\")\n    .replace(/\\u2028/g, \"\\\\u2028\")\n    .replace(/\\u2029/g, \"\\\\u2029\");\n  const tag = `<script data-hf-media-codec-map>window.__HF_MEDIA_CODEC_MAP__=${json};</script>`;\n  return insertBeforeCloseTag(html, \"head\", `${tag}\\n`) ?? `${tag}\\n${html}`;\n}\n\n/**\n * Adapter-aware wrapper used by the studio preview routes: skipped entirely\n * (no scan, no injection) when auto-proxy is off for this adapter.\n */\nexport async function injectMediaCodecMap(\n  html: string,\n  adapter: PreviewApiAdapter,\n  projectDir: string,\n  compSrcPath: string,\n  probeCache: MediaCodecProbeCache,\n): Promise<string> {\n  if (!isAutoProxyEnabled(adapter)) return html;\n  return injectMediaCodecMapIntoHtml(html, projectDir, [{ html, compSrcPath }], probeCache);\n}\n"],"mappings":";;;;;;;;;;;;;AAAA,SAAS,eAAe;AACxB,SAAS,4BAA4B;AAyC9B,SAAS,mBAAmB,SAAqC;AACtE,SAAO,QAAQ,cAAc;AAC/B;AAOO,SAAS,mCACd,SACsB;AACtB,SAAO,QAAQ,wBAAwB,2BAA2B;AACpE;AASO,SAAS,cAAc,KAAiC;AAC7D,MAAI,QAAQ,OAAW,QAAO;AAC9B,SAAO,UAAU,GAAG,IAAI,oBAAoB;AAC9C;AAqBA,eAAsB,4BACpB,MACA,YACA,aACA,YACiB;AACjB,MAAI;AACJ,MAAI;AACF,UAAM,MAAM;AAAA,MACV;AAAA,MACA;AAAA,MACA,aAAa,EAAE,OAAO,WAAW,IAAI,CAAC;AAAA,IACxC;AAAA,EACF,QAAQ;AAEN,WAAO;AAAA,EACT;AACA,MAAI,OAAO,KAAK,GAAG,EAAE,WAAW,EAAG,QAAO;AAC1C,aAAW,CAAC,sBAAsB,KAAK,KAAK,OAAO,QAAQ,GAAG,GAAG;AAC/D,QAAI,CAAC,mBAAmB,KAAK,EAAG;AAChC,uBAAmB;AACnB;AAAA,MACE;AAAA,MACA,QAAQ,YAAY,qBAAqB,QAAQ,QAAQ,EAAE,CAAC;AAAA,MAC5D,gBAAgB,KAAK;AAAA,IACvB,EAAE,MAAM,MAAM;AAAA,IAGd,CAAC;AAAA,EACH;AAGA,QAAM,OAAO,KAAK,UAAU,GAAG,EAC5B,QAAQ,MAAM,SAAS,EACvB,QAAQ,WAAW,SAAS,EAC5B,QAAQ,WAAW,SAAS;AAC/B,QAAM,MAAM,iEAAiE,IAAI;AACjF,SAAO,qBAAqB,MAAM,QAAQ,GAAG,GAAG;AAAA,CAAI,KAAK,GAAG,GAAG;AAAA,EAAK,IAAI;AAC1E;AAMA,eAAsB,oBACpB,MACA,SACA,YACA,aACA,YACiB;AACjB,MAAI,CAAC,mBAAmB,OAAO,EAAG,QAAO;AACzC,SAAO,4BAA4B,MAAM,YAAY,CAAC,EAAE,MAAM,YAAY,CAAC,GAAG,UAAU;AAC1F;","names":[]}

package/dist/helpers/mediaProxyPreview.d.ts

@@ -1,4 +1,4 @@
-export { g as PreviewApiAdapter, P as PreviewDocumentStore, n as injectMediaCodecMap, p as injectMediaCodecMapIntoHtml, q as isAutoProxyEnabled, r as proxyEtagSalt, s as resolvePreviewMediaCodecProbeCache } from '../mediaProxyPreview-DZD3iu_2.js';
+export { g as PreviewApiAdapter, P as PreviewDocumentStore, n as injectMediaCodecMap, p as injectMediaCodecMapIntoHtml, q as isAutoProxyEnabled, r as proxyEtagSalt, s as resolvePreviewMediaCodecProbeCache } from '../mediaProxyPreview-CIayJ4Y4.js';
 import './mediaCodecMap.js';
 import '@hyperframes/core';
 import '@hyperframes/parsers';

package/dist/helpers/mediaProxyPreview.js

@@ -4,7 +4,7 @@ import {
   isAutoProxyEnabled,
   proxyEtagSalt,
   resolvePreviewMediaCodecProbeCache
-} from "../chunk-5PGWTBCL.js";
+} from "../chunk-X3T65KC2.js";
 import "../chunk-45POWYFS.js";
 import "../chunk-4MNTZVVZ.js";
 export {

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Hono } from 'hono';
-import { S as StudioApiAdapter, P as PreviewDocumentStore, M as MediaProcessingJobState } from './mediaProxyPreview-DZD3iu_2.js';
-export { D as DEFAULT_HISTORY_ROOT, a as HISTORY_START, H as HistoryEntry, b as HistoryFileChange, c as HistoryListItem, d as HistoryResult, e as HistoryWho, f as HistoryWindow, L as LintResult, g as PreviewApiAdapter, h as ProjectHistory, i as ProjectHistoryOptions, R as RenderJobState, j as ResolvedProject, k as StudioSelectionResponse, l as StudioSelectionSnapshot, m as StudioSelectionTextField, o as openProjectHistory } from './mediaProxyPreview-DZD3iu_2.js';
+import { S as StudioApiAdapter, P as PreviewDocumentStore, M as MediaProcessingJobState } from './mediaProxyPreview-CIayJ4Y4.js';
+export { D as DEFAULT_HISTORY_ROOT, a as HISTORY_START, H as HistoryEntry, b as HistoryFileChange, c as HistoryListItem, d as HistoryResult, e as HistoryWho, f as HistoryWindow, L as LintResult, g as PreviewApiAdapter, h as ProjectHistory, i as ProjectHistoryOptions, R as RenderJobState, j as ResolvedProject, k as StudioSelectionResponse, l as StudioSelectionSnapshot, m as StudioSelectionTextField, o as openProjectHistory } from './mediaProxyPreview-CIayJ4Y4.js';
 import { SourceMutationTarget } from './helpers/sourceMutation.js';
 export { PatchOperation, dedupeClonedCompositionId, findTargetElement, parseSourceDocument, patchElementInHtml, removeElementFromHtml, splitElementInHtml } from './helpers/sourceMutation.js';
 export { ScreenshotClip, getElementScreenshotClip } from './helpers/screenshotClip.js';
@@ -52,6 +52,11 @@ declare function createProjectSignature(projectDir: string, excluding?: Readonly
  */
 declare function compositionsAffectedBy(projectDir: string, changedPath: string): string[] | null;
 
+declare class HistoryBusyError extends Error {
+    readonly pid: number;
+    constructor(pid: number);
+}
+
 /** Recursively walk a directory and return relative file paths. */
 declare function walkDir(dir: string, prefix?: string): string[];
 
@@ -199,4 +204,4 @@ type BackgroundRemovalRender = (options: {
 }>;
 declare function createBackgroundRemovalJob(opts: BackgroundRemovalJobOptions, render: BackgroundRemovalRender): MediaProcessingJobState;
 
-export { type AppliedFileMutation, type BackgroundRemovalRender, DELETED_VERSION, type DuplicateElementResult, type FileMutationInput, type FileWriteReceipt, MIME_TYPES, MediaProcessingJobState, PREVIEW_BUNDLE_OPTIONS, SourceMutationTarget, StudioApiAdapter, type ThumbnailOutputDimensions, affectsProjectSignature, applyFileMutations, buildSubCompositionHtml, compositionsAffectedBy, consumeFileWriteReceipt, createBackgroundRemovalJob, createPreviewDocumentStore, createProjectSignature, createStudioApi, duplicateElementInHtml, fileContentVersion, getMimeType, identifyFileWrite, requestSubPath, settledFileTag, stampProjectHfIds, thumbnailDeviceScaleFactor, walkDir };
+export { type AppliedFileMutation, type BackgroundRemovalRender, DELETED_VERSION, type DuplicateElementResult, type FileMutationInput, type FileWriteReceipt, HistoryBusyError, MIME_TYPES, MediaProcessingJobState, PREVIEW_BUNDLE_OPTIONS, SourceMutationTarget, StudioApiAdapter, type ThumbnailOutputDimensions, affectsProjectSignature, applyFileMutations, buildSubCompositionHtml, compositionsAffectedBy, consumeFileWriteReceipt, createBackgroundRemovalJob, createPreviewDocumentStore, createProjectSignature, createStudioApi, duplicateElementInHtml, fileContentVersion, getMimeType, identifyFileWrite, requestSubPath, settledFileTag, stampProjectHfIds, thumbnailDeviceScaleFactor, walkDir };

package/dist/index.js

@@ -22,7 +22,7 @@ import {
   isAutoProxyEnabled,
   proxyEtagSalt,
   resolvePreviewMediaCodecProbeCache
-} from "./chunk-5PGWTBCL.js";
+} from "./chunk-X3T65KC2.js";
 import {
   ProxyCapacityError,
   ProxyTranscodeError,
@@ -1133,6 +1133,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 +1680,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 +3326,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 +3552,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 +3578,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 +3749,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/`;
@@ -5320,11 +5320,11 @@ function createStudioApi(adapter) {
 }
 
 // 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 +5428,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 +5523,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 +5563,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 +5621,7 @@ 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 OUTSIDE = { kind: "outside", name: "Outside" };
 var OUTSIDE_LABEL = "Changed outside the app";
 var RACY_MS = 2e3;
@@ -5566,7 +5647,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 +5667,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)();
@@ -5619,7 +5700,7 @@ var Engine = class {
     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 +5712,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 +5720,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
@@ -5665,7 +5746,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(join18(this.dir, path));
+      return await this.blobs.put(join19(this.dir, path));
     } catch (error) {
       if (error.code === "ENOENT") return null;
       throw error;
@@ -5790,7 +5871,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);
@@ -5904,7 +5985,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 +6114,23 @@ 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/helpers/duplicateElement.ts
@@ -6092,26 +6186,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 +6284,7 @@ export {
   DEFAULT_HISTORY_ROOT,
   DELETED_VERSION,
   START as HISTORY_START,
+  HistoryBusyError,
   MIME_TYPES,
   PREVIEW_BUNDLE_OPTIONS,
   STUDIO_MANUAL_EDITS_PATH,