@hyperframes/studio-server 0.8.201 → 0.8.203

package/dist/{chunk-C2RFW2FX.js → chunk-JKPLDWAB.js}

@@ -125,6 +125,30 @@ function sourceFactsOf(stream, formatBitrate) {
     bitrate: Number.isFinite(bitrate) ? bitrate : 0
   };
 }
+var STREAM_SUMMARY_MAX = 12;
+function summarizeStream(stream) {
+  const flags = Object.entries(stream.disposition ?? {}).filter(([, on]) => on === 1).map(([name]) => name);
+  return `${stream.codec_type ?? "?"}:${stream.codec_name ?? "?"}[${flags.join(",")}]`;
+}
+function metadataFromProbe(kind, parsed) {
+  const stream = parsed.streams?.find((item) => {
+    if (kind === "image") return item.codec_type === "video";
+    return item.codec_type === kind && item.disposition?.attached_pic !== 1;
+  });
+  const metadata = {
+    kind,
+    color: classifyMediaColor(stream),
+    streams: (parsed.streams ?? []).slice(0, STREAM_SUMMARY_MAX).map(summarizeStream)
+  };
+  if (kind === "video") {
+    metadata.hasAudio = (parsed.streams ?? []).some((item) => item.codec_type === "audio");
+    metadata.hasAlpha = stream !== void 0 && videoStreamHasAlpha(stream);
+    const duration = Number(parsed.format?.duration);
+    if (Number.isFinite(duration) && duration > 0) metadata.durationSeconds = duration;
+    metadata.source = sourceFactsOf(stream, parsed.format?.bit_rate);
+  }
+  return metadata;
+}
 async function probeMediaMetadata(filePath, runner = execFileRunner) {
   const kind = inferKindFromPath(filePath);
   if (kind === "audio" || kind === "unknown") {
@@ -140,7 +164,7 @@ async function probeMediaMetadata(filePath, runner = execFileRunner) {
       "-v",
       "error",
       "-show_entries",
-      "stream=codec_type,codec_name,profile,pix_fmt,color_space,color_transfer,color_primaries,bits_per_raw_sample,width,height,bit_rate:stream_disposition=attached_pic:stream_tags=alpha_mode:format=duration,bit_rate",
+      "stream=codec_type,codec_name,profile,pix_fmt,color_space,color_transfer,color_primaries,bits_per_raw_sample,width,height,bit_rate:stream_disposition:stream_tags=alpha_mode:format=duration,bit_rate",
       "-of",
       "json",
       "--",
@@ -155,20 +179,7 @@ async function probeMediaMetadata(filePath, runner = execFileRunner) {
     return { kind, color: classifyMediaColor(null), probeError: "ffprobe failed" };
   }
   try {
-    const parsed = JSON.parse(String(result.stdout || "{}"));
-    const stream = parsed.streams?.find((item) => {
-      if (kind === "image") return item.codec_type === "video";
-      return item.codec_type === kind && item.disposition?.attached_pic !== 1;
-    });
-    const metadata = { kind, color: classifyMediaColor(stream) };
-    if (kind === "video") {
-      metadata.hasAudio = (parsed.streams ?? []).some((item) => item.codec_type === "audio");
-      metadata.hasAlpha = stream !== void 0 && videoStreamHasAlpha(stream);
-      const duration = Number(parsed.format?.duration);
-      if (Number.isFinite(duration) && duration > 0) metadata.durationSeconds = duration;
-      metadata.source = sourceFactsOf(stream, parsed.format?.bit_rate);
-    }
-    return metadata;
+    return metadataFromProbe(kind, JSON.parse(String(result.stdout || "{}")));
   } catch {
     return { kind, color: classifyMediaColor(null), probeError: "ffprobe returned invalid json" };
   }
@@ -348,7 +359,7 @@ async function scanProjectMedia(projectDir, htmlSources, options = {}) {
   const scan = { codecMap: {}, sourceFacts: {} };
   for (const [pathname, facts] of await probeProjectAssets(projectDir, htmlSources, options)) {
     if (facts?.browserHostile) scan.codecMap[pathname] = facts;
-    if (facts?.source) scan.sourceFacts[pathname] = facts.source;
+    if (facts?.source) scan.sourceFacts[pathname] = { ...facts.source, codec: facts.codecName };
   }
   return scan;
 }

package/dist/{chunk-5UEDEOD2.js → chunk-MNJZQCBL.js}

@@ -2,7 +2,7 @@ import {
   PROXY_VARIANT_CONFIG,
   probeFirstFrameColour,
   probeMediaMetadata
-} from "./chunk-C2RFW2FX.js";
+} from "./chunk-JKPLDWAB.js";
 import {
   mkdirWithinProject,
   realProjectRoot,
@@ -11,23 +11,19 @@ import {
 
 // src/helpers/proxyTranscoder.ts
 import { spawn } from "child_process";
-import { createHash, randomUUID } from "crypto";
+import { randomUUID } from "crypto";
 import {
-  existsSync as existsSync2,
+  existsSync as existsSync4,
   mkdtempSync,
   renameSync,
-  rmSync,
-  statSync as statSync2,
+  rmSync as rmSync2,
   unlinkSync as unlinkSync2,
   utimesSync,
-  writeFileSync
+  writeFileSync as writeFileSync2
 } from "fs";
 import { availableParallelism, tmpdir, totalmem } from "os";
-import { basename, dirname, extname as extname2, isAbsolute, join as join2, relative, resolve, sep } from "path";
-import {
-  formatPreviewProxyBox,
-  hdrToSdrToneMapFilter
-} from "@hyperframes/core";
+import { basename as basename3, dirname as dirname3, extname as extname3, isAbsolute, join as join4, relative, resolve, sep } from "path";
+import { hdrToSdrToneMapFilter } from "@hyperframes/core";
 import { findFfBinary } from "@hyperframes/parsers/ff-binaries";
 import { alphaDecoderFor } from "@hyperframes/parsers/media-alpha";
 
@@ -143,6 +139,148 @@ function cleanupProxyCache(cacheDir, options = {}) {
   };
 }
 
+// src/helpers/proxyCacheKey.ts
+import { createHash } from "crypto";
+import {
+  closeSync,
+  createReadStream,
+  existsSync as existsSync2,
+  fstatSync,
+  openSync,
+  readFileSync,
+  statSync as statSync2,
+  writeFileSync
+} from "fs";
+import { basename, dirname, extname as extname2, join as join2 } from "path";
+import { formatPreviewProxyBox } from "@hyperframes/core";
+var SMALL_FILE_BYTES = 16 * 1024 * 1024;
+var COPY_NAME = /^[0-9a-f]{64}\.(?:mp4|webm)$/;
+function digest(...parts) {
+  return createHash("sha256").update(parts.join("\0")).digest("hex");
+}
+function boxPart(box) {
+  return box ? formatPreviewProxyBox(box) : "";
+}
+function fastCopyKey(sourcePath, version, variant, box) {
+  const stat = statSync2(sourcePath);
+  return digest(
+    sourcePath,
+    String(stat.mtimeMs),
+    String(stat.size),
+    version,
+    variant,
+    boxPart(box)
+  );
+}
+async function contentCopyKey(sourcePath, version, variant, box, signal) {
+  const hash = createHash("sha256");
+  const fd = openSync(sourcePath, "r");
+  try {
+    if (fstatSync(fd).size <= SMALL_FILE_BYTES) hash.update(readFileSync(fd));
+    else
+      for await (const chunk of createReadStream(sourcePath, { fd, autoClose: false, signal }))
+        hash.update(chunk);
+  } finally {
+    closeSync(fd);
+  }
+  return digest(hash.digest("hex"), version, variant, boxPart(box));
+}
+function sourceSizeBytes(sourcePath) {
+  try {
+    const fd = openSync(sourcePath, "r");
+    try {
+      return fstatSync(fd).size;
+    } finally {
+      closeSync(fd);
+    }
+  } catch {
+    return void 0;
+  }
+}
+function fastIndexPath(cachePath) {
+  return join2(dirname(cachePath), `.fast-${basename(cachePath, extname2(cachePath))}`);
+}
+function contentIndexPath(cacheDir, contentKey) {
+  return join2(cacheDir, `.content-${contentKey}`);
+}
+function readCopyIndex(indexPath) {
+  try {
+    const name = readFileSync(indexPath, "utf8").trim();
+    const target = join2(dirname(indexPath), name);
+    return COPY_NAME.test(name) && existsSync2(target) ? target : null;
+  } catch {
+    return null;
+  }
+}
+function writeCopyIndex(indexPath, copyPath) {
+  writeFileSync(indexPath, basename(copyPath));
+}
+
+// src/helpers/proxyLock.ts
+import {
+  closeSync as closeSync2,
+  existsSync as existsSync3,
+  openSync as openSync2,
+  readFileSync as readFileSync2,
+  rmSync,
+  statSync as statSync3,
+  writeSync
+} from "fs";
+import { basename as basename2, dirname as dirname2, join as join3 } from "path";
+var POLL_MS = 500;
+var UNREADABLE_LOCK_MS = 1e4;
+function lockPathFor(cachePath) {
+  return join3(dirname2(cachePath), `.lock-${basename2(cachePath)}`);
+}
+function ownerIsAlive(lockPath) {
+  try {
+    const pid = Number(readFileSync2(lockPath, "utf8"));
+    if (!Number.isInteger(pid) || pid <= 0) {
+      return Date.now() - statSync3(lockPath).mtimeMs < UNREADABLE_LOCK_MS;
+    }
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (err) {
+      return err.code === "EPERM";
+    }
+  } catch {
+    return false;
+  }
+}
+function pause(ms, signal) {
+  return new Promise((resolve2, reject) => {
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve2();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal.reason);
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function acquireCopyLock(cachePath, signal) {
+  const lockPath = lockPathFor(cachePath);
+  for (; ; ) {
+    signal.throwIfAborted();
+    if (existsSync3(cachePath)) return null;
+    try {
+      const fd = openSync2(lockPath, "wx");
+      writeSync(fd, String(process.pid));
+      closeSync2(fd);
+      if (!existsSync3(cachePath)) return () => rmSync(lockPath, { force: true });
+      rmSync(lockPath, { force: true });
+      return null;
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+    }
+    if (ownerIsAlive(lockPath)) await pause(POLL_MS, signal);
+    else rmSync(lockPath, { force: true });
+  }
+}
+
 // src/helpers/proxyTranscoder.ts
 var PROXY_PARAMS_VERSION = "v7";
 var CACHE_DIR_NAME = ".transcode-cache";
@@ -235,33 +373,16 @@ function canonicalizeProxySource(projectDir, absoluteSourcePath) {
   if (requestedRelativePath === ".." || requestedRelativePath.startsWith(`..${sep}`) || isAbsolute(requestedRelativePath)) {
     throw new ProxySourceOutsideProjectError();
   }
-  const canonicalProjectDir = realProjectRoot(projectDir);
-  const canonicalSourcePath = realpath(absoluteSourcePath);
-  const canonicalRelativePath = relative(canonicalProjectDir, canonicalSourcePath);
-  const sourceIsInsideCanonicalProject = canonicalRelativePath !== ".." && !canonicalRelativePath.startsWith(`..${sep}`) && !isAbsolute(canonicalRelativePath);
-  return {
-    projectDir: canonicalProjectDir,
-    sourcePath: canonicalSourcePath,
-    relativePath: requestedRelativePath.normalize("NFC"),
-    // An external target needs a stable identity in addition to its project-local
-    // symlink path, otherwise retargeting the link can reuse an unrelated proxy.
-    cacheIdentity: (sourceIsInsideCanonicalProject ? canonicalRelativePath : canonicalSourcePath).normalize("NFC")
-  };
-}
-function buildProxyCacheKey(source, variant, box) {
-  const stat = statSync2(source.sourcePath);
-  const size = box ? `\0${formatPreviewProxyBox(box)}` : "";
-  return createHash("sha256").update(
-    `${source.relativePath}\0${source.cacheIdentity}\0${stat.mtimeMs}\0${stat.size}\0${PROXY_PARAMS_VERSION}\0${variant}${size}`
-  ).digest("hex");
+  return { projectDir: realProjectRoot(projectDir), sourcePath: realpath(absoluteSourcePath) };
 }
 function getCanonicalProxyCachePath(source, variant, box) {
-  const key = buildProxyCacheKey(source, variant, box);
-  return join2(
+  const key = fastCopyKey(source.sourcePath, PROXY_PARAMS_VERSION, variant, box);
+  const made = join4(
     source.projectDir,
     CACHE_DIR_NAME,
     `${key}${PROXY_VARIANT_CONFIG[variant].extension}`
   );
+  return existsSync4(made) ? made : readCopyIndex(fastIndexPath(made)) ?? made;
 }
 function getProxyCachePath(projectDir, absoluteSourcePath, variant = "h264", box) {
   return getCanonicalProxyCachePath(
@@ -406,11 +527,53 @@ function proxyScaleFilter(box) {
   return `scale=${width}:${height}`;
 }
 var STDERR_ERROR_LINE = /error|invalid|denied|no space|not found|unknown/i;
-function stderrReason(stderrTail) {
-  const lines = stderrTail.split("\n").map((line2) => line2.trim()).filter(Boolean);
-  const errorLines = lines.filter((line2) => STDERR_ERROR_LINE.test(line2));
-  const line = errorLines.at(-1) ?? lines.at(-1);
-  return line ? `: ${line.replace(/[.!]+$/, "")}` : "";
+var OPEN_OUTPUT_LINE = /^Error opening output file /;
+var ABSOLUTE_PATH = /(?:[A-Za-z]:)?(?:[\\/][^\\/\s'"]+){2,}/g;
+var REASON_LINES = 3;
+function stderrReason(stderrTail, knownPaths) {
+  const lines = stderrTail.split("\n").map((line) => line.trim()).filter(Boolean);
+  const openedAt = lines.map((candidate) => OPEN_OUTPUT_LINE.test(candidate)).lastIndexOf(true);
+  const causes = lines.filter(
+    (line, index) => !OPEN_OUTPUT_LINE.test(line) && (STDERR_ERROR_LINE.test(line) || index === openedAt - 1)
+  );
+  const shown = (causes.length ? causes : lines.slice(-1)).slice(-REASON_LINES);
+  const byLength = knownPaths.filter(isAbsolute).sort((a, b) => b.length - a.length);
+  const reason = shown.map(
+    (line) => byLength.reduce((text, path) => text.split(path).join("<path>"), line).replace(ABSOLUTE_PATH, "<path>").replace(/[.!]+$/, "")
+  );
+  return reason.length ? `: ${reason.join("; ")}` : "";
+}
+var CLOUD_FOLDER = /\/(?:Library\/CloudStorage|Dropbox|OneDrive|Google Drive)(?:[ \-/]|$)/i;
+function sourceFolderKind(sourcePath) {
+  const path = sourcePath.replace(/\\/g, "/");
+  if (path.includes("/Library/Mobile Documents/")) return "icloud";
+  if (CLOUD_FOLDER.test(path)) return "cloud-storage";
+  return path.startsWith("/Volumes/") ? "external-volume" : "local";
+}
+function describeSource(sourcePath, metadata) {
+  const { codecName, pixelFormat, colorTransfer } = metadata.color;
+  const megabytes = sourceSizeBytes(sourcePath);
+  return [
+    metadata.kind,
+    codecName,
+    pixelFormat,
+    colorTransfer,
+    metadata.hasAudio ? "with audio" : "no audio",
+    metadata.streams?.length ? `streams ${metadata.streams.join(" ")}` : void 0,
+    metadata.durationSeconds ? `${Math.round(metadata.durationSeconds)}s` : void 0,
+    megabytes === void 0 ? "missing" : `${Math.round(megabytes / 1e6)} MB`,
+    sourceFolderKind(sourcePath)
+  ].filter(Boolean).join(", ");
+}
+function withSource(err, describe) {
+  if (err instanceof ProxyTranscodeError && err.name === "ProxyTranscodeError") {
+    return new ProxyTranscodeError(
+      `${err.message} (source: ${describe()})`,
+      err.exitCode,
+      err.stderrTail
+    );
+  }
+  return err;
 }
 function chunkRanges(durationSeconds) {
   if (!durationSeconds || durationSeconds <= PROXY_CHUNK_SECONDS * 1.5) return null;
@@ -456,9 +619,9 @@ function createPieceGate(size) {
 }
 async function encodeInChunks(ranges, chunkPrefix, tempPath, encode, concat, signal, gate, onDone = () => {
 }) {
-  const extension = extname2(tempPath);
+  const extension = extname3(tempPath);
   const pieces = ranges.map((_, index) => `${chunkPrefix}${index}${extension}`);
-  const pending = ranges.flatMap((_, index) => existsSync2(pieces[index]) ? [] : [index]);
+  const pending = ranges.flatMap((_, index) => existsSync4(pieces[index]) ? [] : [index]);
   let doneSeconds = 0;
   for (const [index, range] of ranges.entries()) {
     if (!pending.includes(index)) doneSeconds += range.lengthSeconds;
@@ -477,7 +640,7 @@ async function encodeInChunks(ranges, chunkPrefix, tempPath, encode, concat, sig
         const index = pending[cursor++];
         const range = ranges[index];
         const piece = pieces[index];
-        const pieceTemp = join2(dirname(piece), `.tmp-${randomUUID()}-${basename(piece)}`);
+        const pieceTemp = join4(dirname3(piece), `.tmp-${randomUUID()}-${basename3(piece)}`);
         try {
           await encode(pieceTemp, range, pieceSignal, (encodedSeconds) => {
             inFlight2.set(index, encodedSeconds);
@@ -488,7 +651,7 @@ async function encodeInChunks(ranges, chunkPrefix, tempPath, encode, concat, sig
           doneSeconds += range.lengthSeconds;
           onDone(doneSeconds);
         } finally {
-          if (existsSync2(pieceTemp)) unlinkSync2(pieceTemp);
+          if (existsSync4(pieceTemp)) unlinkSync2(pieceTemp);
         }
       } finally {
         gate.release();
@@ -505,19 +668,19 @@ async function encodeInChunks(ranges, chunkPrefix, tempPath, encode, concat, sig
     )
   );
   if (failure !== void 0) throw failure;
-  const listDir = mkdtempSync(join2(tmpdir(), "hf-proxy-join-"));
+  const listDir = mkdtempSync(join4(tmpdir(), "hf-proxy-join-"));
   try {
-    const listPath = join2(listDir, "pieces.txt");
-    writeFileSync(
+    const listPath = join4(listDir, "pieces.txt");
+    writeFileSync2(
       listPath,
       pieces.map((piece) => `file '${piece.replace(/\\/g, "/").replace(/'/g, "'\\''")}'
 `).join("")
     );
     await concat(listPath, tempPath);
   } finally {
-    rmSync(listDir, { recursive: true, force: true });
+    rmSync2(listDir, { recursive: true, force: true });
   }
-  for (const piece of pieces) if (existsSync2(piece)) unlinkSync2(piece);
+  for (const piece of pieces) if (existsSync4(piece)) unlinkSync2(piece);
 }
 var KEYFRAME_EVERY_SECOND_ARGS = ["-force_key_frames", "expr:gte(t,n_forced*1)"];
 var H264_ARGS = [
@@ -627,24 +790,28 @@ async function runFfmpeg(sourcePath, outputPath, chunkPrefix, variant, box, sign
     onEncoded
   );
   const ranges = chunkRanges(totalSeconds);
-  if (!ranges) {
-    return encode(
+  try {
+    if (!ranges) {
+      return await encode(
+        outputPath,
+        void 0,
+        signal,
+        (encodedSeconds) => onProgress({ doneSeconds: encodedSeconds, totalSeconds })
+      );
+    }
+    await encodeInChunks(
+      ranges,
+      chunkPrefix,
       outputPath,
-      void 0,
+      encode,
+      (listPath, target) => spawnFfmpeg(ffmpegPath, concatArgs(listPath, target, variant), CONCAT_TIMEOUT_MS, signal),
       signal,
-      (encodedSeconds) => onProgress({ doneSeconds: encodedSeconds, totalSeconds })
+      gate,
+      (doneSeconds) => onProgress({ doneSeconds, totalSeconds })
     );
+  } catch (err) {
+    throw withSource(err, () => describeSource(sourcePath, metadata));
   }
-  await encodeInChunks(
-    ranges,
-    chunkPrefix,
-    outputPath,
-    encode,
-    (listPath, target) => spawnFfmpeg(ffmpegPath, concatArgs(listPath, target, variant), CONCAT_TIMEOUT_MS, signal),
-    signal,
-    gate,
-    (doneSeconds) => onProgress({ doneSeconds, totalSeconds })
-  );
 }
 function concatArgs(listPath, target, variant) {
   return [
@@ -725,7 +892,7 @@ function spawnFfmpeg(ffmpegPath, args, stallMs, signal, onProgress) {
       } else {
         reject(
           new ProxyTranscodeError(
-            `ffmpeg exited with code ${code}${stderrReason(stderrTail)}`,
+            `ffmpeg exited with code ${code}${stderrReason(stderrTail, args)}`,
             code,
             stderrTail
           )
@@ -737,14 +904,31 @@ function spawnFfmpeg(ffmpegPath, args, stallMs, signal, onProgress) {
 async function transcodeToCache(job, projectDir, absoluteSourcePath, cachePath, variant, box) {
   await acquireSlot(job);
   try {
-    if (existsSync2(cachePath)) return cachePath;
-    const cacheDir = dirname(cachePath);
+    if (existsSync4(cachePath)) return cachePath;
+    const cacheDir = dirname3(cachePath);
     mkdirWithinProject(projectDir, cacheDir);
-    const tempPath = join2(cacheDir, `.tmp-${randomUUID()}-${basename(cachePath)}`);
+    const contentIndex = contentIndexPath(
+      cacheDir,
+      await contentCopyKey(
+        absoluteSourcePath,
+        PROXY_PARAMS_VERSION,
+        variant,
+        box,
+        job.abandoned.signal
+      )
+    );
+    const sameContent = readCopyIndex(contentIndex);
+    if (sameContent) {
+      writeCopyIndex(fastIndexPath(cachePath), sameContent);
+      return sameContent;
+    }
+    const release = await acquireCopyLock(cachePath, job.abandoned.signal);
+    if (!release) return cachePath;
+    const tempPath = join4(cacheDir, `.tmp-${randomUUID()}-${basename3(cachePath)}`);
     try {
-      const chunkPrefix = join2(
+      const chunkPrefix = join4(
         cacheDir,
-        `${CHUNK_PREFIX}${basename(cachePath, extname2(cachePath))}-`
+        `${CHUNK_PREFIX}${basename3(cachePath, extname3(cachePath))}-`
       );
       await runFfmpeg(
         absoluteSourcePath,
@@ -756,19 +940,30 @@ async function transcodeToCache(job, projectDir, absoluteSourcePath, cachePath,
         (progress) => reportProgress(job, progress)
       );
       renameSync(tempPath, cachePath);
+      writeCopyIndex(contentIndex, cachePath);
       maintainProxyCache(cacheDir);
       return cachePath;
     } finally {
-      if (existsSync2(tempPath)) unlinkSync2(tempPath);
+      if (existsSync4(tempPath)) unlinkSync2(tempPath);
+      release();
     }
   } finally {
     releaseSlot();
   }
 }
+function proxyCopyProgress(projectDir, absoluteSourcePath, variant, box) {
+  const source = canonicalizeProxySource(projectDir, absoluteSourcePath);
+  const progress = inFlight.get(getCanonicalProxyCachePath(source, variant, box))?.job.lastProgress;
+  return progress?.totalSeconds ? Math.min(1, progress.doneSeconds / progress.totalSeconds) : void 0;
+}
+function retryProxyCopy(projectDir, absoluteSourcePath, variant, box) {
+  const source = canonicalizeProxySource(projectDir, absoluteSourcePath);
+  failedTranscodes.delete(getCanonicalProxyCachePath(source, variant, box));
+}
 var proxyActivity = 0;
 function proxyActivityMark(projectDir) {
-  if (!existsSync2(projectDir)) return String(proxyActivity);
-  const cacheDir = join2(realpath(projectDir), CACHE_DIR_NAME) + sep;
+  if (!existsSync4(projectDir)) return String(proxyActivity);
+  const cacheDir = join4(realpath(projectDir), CACHE_DIR_NAME) + sep;
   for (const cachePath of inFlight.keys()) if (cachePath.startsWith(cacheDir)) return null;
   return String(proxyActivity);
 }
@@ -776,9 +971,9 @@ async function resolveProxy(projectDir, absoluteSourcePath, variant = "h264", bo
   options.signal?.throwIfAborted();
   const source = canonicalizeProxySource(projectDir, absoluteSourcePath);
   const cachePath = getCanonicalProxyCachePath(source, variant, box);
-  if (existsSync2(cachePath)) {
+  if (existsSync4(cachePath)) {
     markCacheEntryUsed(cachePath);
-    maintainProxyCache(dirname(cachePath));
+    maintainProxyCache(dirname3(cachePath));
     return cachePath;
   }
   const rememberedFailure = failedTranscodes.get(cachePath);
@@ -835,7 +1030,7 @@ async function resolveProxies(projectDir, sources, onSettled = () => {
   const first = sources[0];
   if (first) {
     maintainProxyCache(
-      dirname(getProxyCachePath(projectDir, first.sourcePath, first.variant)),
+      dirname3(getProxyCachePath(projectDir, first.sourcePath, first.variant)),
       Math.min(
         Number(process.env.HYPERFRAMES_PROXY_CACHE_STALE_TEMP_MS) || UNTOUCHED_TEMP_IS_DEAD_MS,
         UNTOUCHED_TEMP_IS_DEAD_MS
@@ -891,6 +1086,9 @@ export {
   waitForProxy,
   getProxyCachePath,
   clearFailedTranscodesForTest,
+  sourceFolderKind,
+  proxyCopyProgress,
+  retryProxyCopy,
   proxyActivityMark,
   resolveProxy,
   resolveProxies

package/dist/{chunk-HZCA2O76.js → chunk-OAHY2RQP.js}

@@ -1,14 +1,14 @@
 import {
   PROXY_PARAMS_VERSION,
   resolveProxy
-} from "./chunk-5UEDEOD2.js";
+} from "./chunk-MNJZQCBL.js";
 import {
   createMediaCodecProbeCache,
   proxyVariantFor,
   recordProxyPrewarm,
   scanProjectMedia,
   shouldPrewarmProxy
-} from "./chunk-C2RFW2FX.js";
+} from "./chunk-JKPLDWAB.js";
 
 // src/helpers/mediaProxyPreview.ts
 import { resolve } from "path";

package/dist/helpers/mediaCodecMap.js

@@ -14,7 +14,7 @@ import {
   scanProjectMedia,
   scanProjectMediaCodecMap,
   shouldPrewarmProxy
-} from "../chunk-C2RFW2FX.js";
+} from "../chunk-JKPLDWAB.js";
 import "../chunk-QF7MFJJU.js";
 import "../chunk-SVQFE44C.js";
 import "../chunk-L3HJVTQE.js";

package/dist/helpers/mediaProxyPreview.js

@@ -4,9 +4,9 @@ import {
   isAutoProxyEnabled,
   proxyEtagSalt,
   resolvePreviewMediaCodecProbeCache
-} from "../chunk-HZCA2O76.js";
-import "../chunk-5UEDEOD2.js";
-import "../chunk-C2RFW2FX.js";
+} from "../chunk-OAHY2RQP.js";
+import "../chunk-MNJZQCBL.js";
+import "../chunk-JKPLDWAB.js";
 import "../chunk-QF7MFJJU.js";
 import "../chunk-SVQFE44C.js";
 import "../chunk-L3HJVTQE.js";

package/dist/helpers/proxyTranscoder.d.ts

@@ -59,6 +59,11 @@ interface ProxyProgress {
 /** Test hook: forget remembered transcode failures (module state persists
  * across tests that don't reload the module). */
 declare function clearFailedTranscodesForTest(): void;
+type SourceFolderKind = "icloud" | "cloud-storage" | "external-volume" | "local";
+/** Where a source lives, in the terms that decide whether its file can be read and written normally. */
+declare function sourceFolderKind(sourcePath: string): SourceFolderKind;
+declare function proxyCopyProgress(projectDir: string, absoluteSourcePath: string, variant: ProxyVariant, box?: PreviewProxyBox): number | undefined;
+declare function retryProxyCopy(projectDir: string, absoluteSourcePath: string, variant: ProxyVariant, box?: PreviewProxyBox): void;
 /** Null while this project has a copy in progress; otherwise a mark that moves when any copy finishes or is refused. */
 declare function proxyActivityMark(projectDir: string): string | null;
 /**
@@ -89,4 +94,4 @@ interface ResolveProxyOptions {
     onProgress?: (progress: ProxyProgress) => void;
 }
 
-export { CACHE_DIR_NAME, DEFAULT_PROXY_WAIT_TIMEOUT_MS, FfmpegMissingFilterError, FfmpegUnavailableError, PROXY_CHUNK_SECONDS, PROXY_PARAMS_VERSION, PROXY_PENDING_RETRY_AFTER_SECONDS, ProxyCapacityError, type ProxyProgress, ProxySourceOutsideProjectError, ProxyTranscodeError, ProxyWaitTimeoutError, type ResolveProxyOptions, TRANSCODE_STALL_MS, clearFailedTranscodesForTest, getProxyCachePath, proxyActivityMark, resolveProxies, resolveProxy, waitForProxy };
+export { CACHE_DIR_NAME, DEFAULT_PROXY_WAIT_TIMEOUT_MS, FfmpegMissingFilterError, FfmpegUnavailableError, PROXY_CHUNK_SECONDS, PROXY_PARAMS_VERSION, PROXY_PENDING_RETRY_AFTER_SECONDS, ProxyCapacityError, type ProxyProgress, ProxySourceOutsideProjectError, ProxyTranscodeError, ProxyWaitTimeoutError, type ResolveProxyOptions, type SourceFolderKind, TRANSCODE_STALL_MS, clearFailedTranscodesForTest, getProxyCachePath, proxyActivityMark, proxyCopyProgress, resolveProxies, resolveProxy, retryProxyCopy, sourceFolderKind, waitForProxy };

package/dist/helpers/proxyTranscoder.js

@@ -14,11 +14,14 @@ import {
   clearFailedTranscodesForTest,
   getProxyCachePath,
   proxyActivityMark,
+  proxyCopyProgress,
   resolveProxies,
   resolveProxy,
+  retryProxyCopy,
+  sourceFolderKind,
   waitForProxy
-} from "../chunk-5UEDEOD2.js";
-import "../chunk-C2RFW2FX.js";
+} from "../chunk-MNJZQCBL.js";
+import "../chunk-JKPLDWAB.js";
 import "../chunk-QF7MFJJU.js";
 import "../chunk-SVQFE44C.js";
 import "../chunk-L3HJVTQE.js";
@@ -38,7 +41,10 @@ export {
   clearFailedTranscodesForTest,
   getProxyCachePath,
   proxyActivityMark,
+  proxyCopyProgress,
   resolveProxies,
   resolveProxy,
+  retryProxyCopy,
+  sourceFolderKind,
   waitForProxy
 };

package/dist/index.js

@@ -82,7 +82,7 @@ import {
   isAutoProxyEnabled,
   proxyEtagSalt,
   resolvePreviewMediaCodecProbeCache
-} from "./chunk-HZCA2O76.js";
+} from "./chunk-OAHY2RQP.js";
 import {
   CACHE_DIR_NAME,
   PROXY_PENDING_RETRY_AFTER_SECONDS,
@@ -91,9 +91,11 @@ import {
   ProxyWaitTimeoutError,
   cleanupProxyCache,
   proxyActivityMark,
+  proxyCopyProgress,
   resolveProxy,
+  retryProxyCopy,
   waitForProxy
-} from "./chunk-5UEDEOD2.js";
+} from "./chunk-MNJZQCBL.js";
 import {
   PROXY_VARIANT_CONFIG,
   decideMediaProxyEligibility,
@@ -102,7 +104,7 @@ import {
   probeMediaMetadata,
   recordProxyRequest,
   resolveProxyVariantRequest
-} from "./chunk-C2RFW2FX.js";
+} from "./chunk-JKPLDWAB.js";
 import {
   folderGone,
   isInHiddenOrVendorDir,
@@ -3888,6 +3890,8 @@ import {
 import {
   PREVIEW_PROXY_BOX_PARAM,
   PREVIEW_PROXY_LIGHT_PARAM,
+  PREVIEW_PROXY_PROGRESS_HEADER,
+  PREVIEW_PROXY_RETRY_PARAM,
   parsePreviewProxyBox
 } from "@hyperframes/core";
 import {
@@ -4539,12 +4543,17 @@ ${etag}`;
     let servedContentType = contentType;
     if (proxyVariant !== void 0) {
       try {
+        if (c.req.query(PREVIEW_PROXY_RETRY_PARAM) !== void 0) {
+          retryProxyCopy(project.dir, file, proxyVariant, proxyBox);
+        }
         servedPath = await waitForProxy(resolveProxy(project.dir, file, proxyVariant, proxyBox), 0);
       } catch (err) {
         if (err instanceof ProxyWaitTimeoutError) {
+          const progress = proxyCopyProgress(project.dir, file, proxyVariant, proxyBox);
           return c.text("media proxy is being made", 202, {
-            "Retry-After": String(PROXY_PENDING_RETRY_AFTER_SECONDS),
-            "Cache-Control": "no-store"
+            "Retry-After": progress === void 0 ? String(PROXY_PENDING_RETRY_AFTER_SECONDS) : "1",
+            "Cache-Control": "no-store",
+            ...progress !== void 0 && { [PREVIEW_PROXY_PROGRESS_HEADER]: progress.toFixed(3) }
           });
         }
         if (err instanceof ProxyCapacityError) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio-server",
-  "version": "0.8.201",
+  "version": "0.8.203",
   "repository": {
     "type": "git",
     "url": "https://github.com/heygen-com/hyperframes",
@@ -84,8 +84,8 @@
     "linkedom": "^0.18.12",
     "postcss": "^8.5.8",
     "postcss-selector-parser": "^7.1.2",
-    "@hyperframes/core": "0.8.201",
-    "@hyperframes/parsers": "0.8.201"
+    "@hyperframes/core": "0.8.203",
+    "@hyperframes/parsers": "0.8.203"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",