@hyperframes/studio-server 0.8.199 → 0.8.201

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

@@ -2,7 +2,7 @@ import {
   PROXY_VARIANT_CONFIG,
   probeFirstFrameColour,
   probeMediaMetadata
-} from "./chunk-XMNHDWQI.js";
+} from "./chunk-C2RFW2FX.js";
 import {
   mkdirWithinProject,
   realProjectRoot,
@@ -22,7 +22,7 @@ import {
   utimesSync,
   writeFileSync
 } from "fs";
-import { availableParallelism, tmpdir } from "os";
+import { availableParallelism, tmpdir, totalmem } from "os";
 import { basename, dirname, extname as extname2, isAbsolute, join as join2, relative, resolve, sep } from "path";
 import {
   formatPreviewProxyBox,
@@ -144,7 +144,7 @@ function cleanupProxyCache(cacheDir, options = {}) {
 }
 
 // src/helpers/proxyTranscoder.ts
-var PROXY_PARAMS_VERSION = "v6";
+var PROXY_PARAMS_VERSION = "v7";
 var CACHE_DIR_NAME = ".transcode-cache";
 function boundedEnvInteger(name, fallback, min, max) {
   const raw = process.env[name]?.trim();
@@ -420,28 +420,91 @@ function chunkRanges(durationSeconds) {
     lengthSeconds: index === count - 1 ? durationSeconds - index * PROXY_CHUNK_SECONDS : PROXY_CHUNK_SECONDS
   }));
 }
-async function encodeInChunks(ranges, chunkPrefix, tempPath, encode, concat, onDone = () => {
+var UNGATED = { size: 1, acquire: async () => {
+}, release: () => {
+} };
+function createPieceGate(size) {
+  let free = size;
+  const waiters = [];
+  return {
+    size,
+    acquire: (signal) => {
+      signal.throwIfAborted();
+      if (free > 0) {
+        free--;
+        return Promise.resolve();
+      }
+      return new Promise((resolve2, reject) => {
+        const grant = () => {
+          signal.removeEventListener("abort", onAbort);
+          resolve2();
+        };
+        const onAbort = () => {
+          waiters.splice(waiters.indexOf(grant), 1);
+          reject(signal.reason);
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        waiters.push(grant);
+      });
+    },
+    release: () => {
+      const next = waiters.shift();
+      if (next) next();
+      else free++;
+    }
+  };
+}
+async function encodeInChunks(ranges, chunkPrefix, tempPath, encode, concat, signal, gate, onDone = () => {
 }) {
   const extension = extname2(tempPath);
   const pieces = ranges.map((_, index) => `${chunkPrefix}${index}${extension}`);
+  const pending = ranges.flatMap((_, index) => existsSync2(pieces[index]) ? [] : [index]);
   let doneSeconds = 0;
   for (const [index, range] of ranges.entries()) {
-    if (existsSync2(pieces[index])) doneSeconds += range.lengthSeconds;
+    if (!pending.includes(index)) doneSeconds += range.lengthSeconds;
   }
   if (doneSeconds) onDone(doneSeconds);
-  for (const [index, range] of ranges.entries()) {
-    const piece = pieces[index];
-    if (existsSync2(piece)) continue;
-    const pieceTemp = join2(dirname(piece), `.tmp-${randomUUID()}-${basename(piece)}`);
-    try {
-      await encode(pieceTemp, range);
-      renameSync(pieceTemp, piece);
-      doneSeconds += range.lengthSeconds;
-      onDone(doneSeconds);
-    } finally {
-      if (existsSync2(pieceTemp)) unlinkSync2(pieceTemp);
+  const inFlight2 = /* @__PURE__ */ new Map();
+  const stop = new AbortController();
+  const pieceSignal = AbortSignal.any([signal, stop.signal]);
+  let failure;
+  let cursor = 0;
+  const work = async () => {
+    for (; ; ) {
+      await gate.acquire(pieceSignal);
+      try {
+        if (cursor >= pending.length) return;
+        const index = pending[cursor++];
+        const range = ranges[index];
+        const piece = pieces[index];
+        const pieceTemp = join2(dirname(piece), `.tmp-${randomUUID()}-${basename(piece)}`);
+        try {
+          await encode(pieceTemp, range, pieceSignal, (encodedSeconds) => {
+            inFlight2.set(index, encodedSeconds);
+            onDone(doneSeconds + [...inFlight2.values()].reduce((sum, seconds) => sum + seconds, 0));
+          });
+          renameSync(pieceTemp, piece);
+          inFlight2.delete(index);
+          doneSeconds += range.lengthSeconds;
+          onDone(doneSeconds);
+        } finally {
+          if (existsSync2(pieceTemp)) unlinkSync2(pieceTemp);
+        }
+      } finally {
+        gate.release();
+      }
     }
-  }
+  };
+  await Promise.all(
+    Array.from(
+      { length: Math.min(gate.size, pending.length) },
+      () => work().catch((error) => {
+        failure ??= error;
+        stop.abort();
+      })
+    )
+  );
+  if (failure !== void 0) throw failure;
   const listDir = mkdtempSync(join2(tmpdir(), "hf-proxy-join-"));
   try {
     const listPath = join2(listDir, "pieces.txt");
@@ -456,6 +519,7 @@ async function encodeInChunks(ranges, chunkPrefix, tempPath, encode, concat, onD
   }
   for (const piece of pieces) if (existsSync2(piece)) unlinkSync2(piece);
 }
+var KEYFRAME_EVERY_SECOND_ARGS = ["-force_key_frames", "expr:gte(t,n_forced*1)"];
 var H264_ARGS = [
   "-c:v",
   "libx264",
@@ -478,7 +542,11 @@ var H264_ARGS = [
   "-movflags",
   "+faststart"
 ];
-var VP8_THREADS = String(Math.min(4, availableParallelism()));
+var CORES = availableParallelism();
+var PIECE_MEMORY_BYTES = 3 * 1024 ** 3;
+var ALPHA_PIECE_GATE = createPieceGate(
+  Math.max(1, Math.min(4, CORES - 1, Math.floor(totalmem() / PIECE_MEMORY_BYTES)))
+);
 var VP8_ARGS = [
   "-c:v",
   "libvpx",
@@ -498,8 +566,6 @@ var VP8_ARGS = [
   "bt709",
   "-cpu-used",
   "4",
-  "-threads",
-  VP8_THREADS,
   "-auto-alt-ref",
   "0",
   "-metadata:s:v:0",
@@ -533,7 +599,12 @@ async function runFfmpeg(sourcePath, outputPath, chunkPrefix, variant, box, sign
   const alphaDecoder = keepsAlpha ? alphaDecoderFor(metadata.color.codecName) : null;
   const decoderArgs = alphaDecoder ? ["-c:v", alphaDecoder] : [];
   const totalSeconds = metadata.durationSeconds;
-  const encode = (target, range) => spawnFfmpeg(
+  const gate = keepsAlpha ? ALPHA_PIECE_GATE : UNGATED;
+  const vp8Threads = (pieces) => [
+    "-threads",
+    String(Math.min(4, Math.floor(CORES / pieces)))
+  ];
+  const encode = (target, range, pieceSignal, onEncoded) => spawnFfmpeg(
     ffmpegPath,
     [
       "-y",
@@ -547,21 +618,31 @@ async function runFfmpeg(sourcePath, outputPath, chunkPrefix, variant, box, sign
       ...range ? ["-t", String(range.lengthSeconds)] : [],
       "-vf",
       videoFilter,
-      ...variant === "vp8" ? VP8_ARGS : H264_ARGS,
+      ...KEYFRAME_EVERY_SECOND_ARGS,
+      ...keepsAlpha ? [...VP8_ARGS, ...vp8Threads(range ? gate.size : 1)] : H264_ARGS,
       target
     ],
     TRANSCODE_STALL_MS,
-    signal,
-    (encodedSeconds) => onProgress({ doneSeconds: (range?.startSeconds ?? 0) + encodedSeconds, totalSeconds })
+    pieceSignal,
+    onEncoded
   );
   const ranges = chunkRanges(totalSeconds);
-  if (!ranges) return encode(outputPath);
+  if (!ranges) {
+    return encode(
+      outputPath,
+      void 0,
+      signal,
+      (encodedSeconds) => onProgress({ doneSeconds: encodedSeconds, totalSeconds })
+    );
+  }
   await encodeInChunks(
     ranges,
     chunkPrefix,
     outputPath,
     encode,
     (listPath, target) => spawnFfmpeg(ffmpegPath, concatArgs(listPath, target, variant), CONCAT_TIMEOUT_MS, signal),
+    signal,
+    gate,
     (doneSeconds) => onProgress({ doneSeconds, totalSeconds })
   );
 }

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

@@ -13,6 +13,9 @@ import {
   isUnresolvedAssetPlaceholder,
   resolveExistingLocalAsset as resolveAsset
 } from "@hyperframes/parsers/asset-resolution";
+import {
+  isHeavyForPreview
+} from "@hyperframes/core";
 
 // src/helpers/mediaMetadata.ts
 import { execFile } from "child_process";
@@ -106,6 +109,22 @@ async function probeFirstFrameColour(filePath, runner = execFileRunner) {
   });
   return result.status === 0 ? parseFirstFrameColour(String(result.stderr)) : {};
 }
+function bitDepthOf(stream) {
+  const raw = Number(stream.bits_per_raw_sample);
+  if (Number.isFinite(raw) && raw > 0) return raw;
+  const suffixed = /(\d{1,3})(?:le|be)$/.exec(stream.pix_fmt ?? "");
+  return suffixed ? Number(suffixed[1]) : 8;
+}
+function sourceFactsOf(stream, formatBitrate) {
+  if (!stream?.width || !stream.height) return void 0;
+  const bitrate = Number(stream.bit_rate ?? formatBitrate);
+  return {
+    width: stream.width,
+    height: stream.height,
+    bitDepth: bitDepthOf(stream),
+    bitrate: Number.isFinite(bitrate) ? bitrate : 0
+  };
+}
 async function probeMediaMetadata(filePath, runner = execFileRunner) {
   const kind = inferKindFromPath(filePath);
   if (kind === "audio" || kind === "unknown") {
@@ -121,7 +140,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:stream_disposition=attached_pic:stream_tags=alpha_mode:format=duration",
+      "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",
       "-of",
       "json",
       "--",
@@ -147,6 +166,7 @@ async function probeMediaMetadata(filePath, runner = execFileRunner) {
       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;
   } catch {
@@ -219,18 +239,22 @@ function resolveProxyVariantRequest(request, facts) {
   const expected = proxyVariantFor(facts);
   return request === "auto" || request === expected ? expected : null;
 }
-function decideMediaProxyEligibility(facts) {
+function decideMediaProxyEligibility(facts, lightBox) {
   if (!facts) return { eligible: false, reason: "unknown_codec" };
-  if (!facts.browserHostile) return { eligible: false, reason: "browser_safe_codec" };
-  return { eligible: true };
+  if (facts.browserHostile) return { eligible: true };
+  if (lightBox && facts.source && isHeavyForPreview(facts.source, lightBox)) {
+    return { eligible: true };
+  }
+  return { eligible: false, reason: "browser_safe_codec" };
 }
-function codecFactsFor(codecName, hasAlpha) {
+function codecFactsFor(codecName, hasAlpha, source) {
   const hostile = hostileCodecEntry(codecName);
   return {
     codecName,
     browserHostile: hostile !== void 0,
     representativeMime: hostile?.representativeMime ?? null,
-    hasAlpha
+    hasAlpha,
+    ...source && { source }
   };
 }
 async function probeCodecFacts(filePath, runner) {
@@ -239,7 +263,7 @@ async function probeCodecFacts(filePath, runner) {
   if (metadata.kind !== "video") return null;
   const codecName = metadata.color.codecName;
   if (!codecName) return null;
-  return codecFactsFor(codecName, metadata.hasAlpha === true);
+  return codecFactsFor(codecName, metadata.hasAlpha === true, metadata.source);
 }
 function createMediaCodecProbeCache() {
   return /* @__PURE__ */ new Map();
@@ -301,9 +325,8 @@ function collectLocalVideoAssets(projectDir, htmlSources) {
   return candidates;
 }
 var PROBE_CONCURRENCY = 8;
-async function scanProjectMediaCodecMap(projectDir, htmlSources, options = {}) {
+async function probeProjectAssets(projectDir, htmlSources, options) {
   const candidates = collectLocalVideoAssets(projectDir, htmlSources);
-  if (candidates.size === 0) return {};
   const cache = options.cache ?? defaultProbeCache;
   const entries = [...candidates.entries()];
   const facts = new Array(entries.length).fill(null);
@@ -319,12 +342,18 @@ async function scanProjectMediaCodecMap(projectDir, htmlSources, options = {}) {
       }
     })
   );
-  const map = {};
-  entries.forEach(([, pathname], index) => {
-    const entryFacts = facts[index];
-    if (entryFacts?.browserHostile) map[pathname] = entryFacts;
-  });
-  return map;
+  return entries.map(([, pathname], index) => [pathname, facts[index] ?? null]);
+}
+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;
+  }
+  return scan;
+}
+async function scanProjectMediaCodecMap(projectDir, htmlSources, options = {}) {
+  return (await scanProjectMedia(projectDir, htmlSources, options)).codecMap;
 }
 
 export {
@@ -343,5 +372,6 @@ export {
   decideMediaProxyEligibility,
   createMediaCodecProbeCache,
   probeAssetCodec,
+  scanProjectMedia,
   scanProjectMediaCodecMap
 };

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

@@ -1,14 +1,14 @@
 import {
   PROXY_PARAMS_VERSION,
   resolveProxy
-} from "./chunk-URMIRXBS.js";
+} from "./chunk-5UEDEOD2.js";
 import {
   createMediaCodecProbeCache,
   proxyVariantFor,
   recordProxyPrewarm,
-  scanProjectMediaCodecMap,
+  scanProjectMedia,
   shouldPrewarmProxy
-} from "./chunk-XMNHDWQI.js";
+} from "./chunk-C2RFW2FX.js";
 
 // src/helpers/mediaProxyPreview.ts
 import { resolve } from "path";
@@ -25,17 +25,15 @@ function proxyEtagSalt(raw, box) {
   return `:proxy:${raw}:${PROXY_PARAMS_VERSION}${box ? `:${formatPreviewProxyBox(box)}` : ""}`;
 }
 async function injectMediaCodecMapIntoHtml(html, projectDir, htmlSources, probeCache, prewarm = true, signal, box) {
-  let map;
+  let scan;
   try {
-    map = await scanProjectMediaCodecMap(
-      projectDir,
-      htmlSources,
-      probeCache ? { cache: probeCache } : {}
-    );
+    scan = await scanProjectMedia(projectDir, htmlSources, probeCache ? { cache: probeCache } : {});
   } catch {
     return html;
   }
-  if (Object.keys(map).length === 0) return html;
+  const { codecMap: map, sourceFacts } = scan;
+  const hasMap = Object.keys(map).length > 0;
+  if (!hasMap && Object.keys(sourceFacts).length === 0) return html;
   for (const [rootRelativePathname, facts] of Object.entries(map)) {
     if (!prewarm || !shouldPrewarmProxy(facts)) continue;
     recordProxyPrewarm();
@@ -48,8 +46,12 @@ async function injectMediaCodecMapIntoHtml(html, projectDir, htmlSources, probeC
     ).catch(() => {
     });
   }
-  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>`;
+  const safeJson = (value) => JSON.stringify(value).replace(/</g, "\\u003c").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+  const assignments = [
+    ...hasMap ? [`window.__HF_MEDIA_CODEC_MAP__=${safeJson(map)};`] : [],
+    `window.__HF_MEDIA_SOURCE_FACTS__=${safeJson(sourceFacts)};`
+  ];
+  const tag = `<script data-hf-media-codec-map>${assignments.join("")}</script>`;
   return insertBeforeCloseTag(html, "head", `${tag}
 `) ?? `${tag}
 ${html}`;

package/dist/{chunk-VKQTZKGA.js → chunk-OSZE5WT3.js}

@@ -106,6 +106,7 @@ import { isAbsolute, relative, resolve, sep } from "path";
 import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
 
 // src/history/ownerLock.ts
+import { spawnSync } from "child_process";
 import { randomUUID as randomUUID2 } from "crypto";
 import {
   linkSync,
@@ -116,6 +117,7 @@ import {
   statSync,
   writeFileSync
 } from "fs";
+import { uptime } from "os";
 import { join } from "path";
 var HistoryBusyError = class extends Error {
   constructor(pid, url) {
@@ -130,6 +132,7 @@ var HistoryBusyError = class extends Error {
 var WINDOWS_BUSY = /* @__PURE__ */ new Set(["EPERM", "EBUSY", "EACCES"]);
 var NO_HARD_LINKS = /* @__PURE__ */ new Set(["ENOTSUP", "EOPNOTSUPP", "ENOSYS", "EPERM"]);
 var TAKING_MS = 2e3;
+var BOOT_SLACK_MS = 6e4;
 function busyOnWindows(error) {
   return process.platform === "win32" && WINDOWS_BUSY.has(error.code ?? "");
 }
@@ -142,6 +145,48 @@ function alive(pid) {
     return error.code === "EPERM";
   }
 }
+function processStart(pid) {
+  try {
+    if (process.platform === "linux") {
+      const stat4 = readFileSync(`/proc/${pid}/stat`, "utf-8");
+      return stat4.slice(stat4.lastIndexOf(")") + 2).split(" ")[19] ?? null;
+    }
+    if (process.platform === "win32") return null;
+    const ps = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+      encoding: "utf-8",
+      env: { ...process.env, LC_ALL: "C" }
+    });
+    return ps.status === 0 ? ps.stdout.trim() || null : null;
+  } catch {
+    return null;
+  }
+}
+function recordedStart(file, pid) {
+  try {
+    const [owner, ...start] = readFileSync(`${file}.start`, "utf-8").split("\n");
+    return Number(owner) === pid && start.length > 0 ? start.join("\n") : null;
+  } catch {
+    return null;
+  }
+}
+function recordStart(file) {
+  const start = processStart(process.pid);
+  if (start) writeFileSync(`${file}.start`, `${process.pid}
+${start}`);
+}
+function holdsLock(file, pid) {
+  if (!alive(pid)) return false;
+  const recorded = recordedStart(file, pid);
+  if (recorded !== null) {
+    const now = processStart(pid);
+    return now === null || now === recorded;
+  }
+  try {
+    return statSync(file).mtimeMs > Date.now() - uptime() * 1e3 - BOOT_SLACK_MS;
+  } catch {
+    return true;
+  }
+}
 function ownerOf(file) {
   try {
     const text = readFileSync(file, "utf-8");
@@ -160,13 +205,14 @@ function beingTaken(file) {
   }
 }
 function deadHolder(file, pid) {
-  return !alive(pid) && !beingTaken(file);
+  return !holdsLock(file, pid) && !beingTaken(file);
 }
 function claim(file) {
   const draft = `${file}-${process.pid}-${randomUUID2()}.tmp`;
   writeFileSync(draft, String(process.pid));
   try {
     linkSync(draft, file);
+    recordStart(file);
     return true;
   } catch (error) {
     const code = error.code ?? "";
@@ -180,6 +226,7 @@ function claim(file) {
 function createExclusively(file) {
   try {
     writeFileSync(file, String(process.pid), { flag: "wx" });
+    recordStart(file);
     return true;
   } catch (error) {
     if (error.code !== "EEXIST") throw error;
@@ -187,7 +234,9 @@ function createExclusively(file) {
   }
 }
 function releaseOwn(file) {
-  if (ownerOf(file) === process.pid) rmSync(file, { force: true });
+  if (ownerOf(file) !== process.pid) return;
+  rmSync(file, { force: true });
+  rmSync(`${file}.start`, { force: true });
 }
 function evictDeadOwner(file) {
   const evictor = `${file}.evict`;
@@ -198,7 +247,10 @@ function evictDeadOwner(file) {
   }
   try {
     const pid = ownerOf(file);
-    if (pid !== null && deadHolder(file, pid)) rmSync(file, { force: true });
+    if (pid !== null && deadHolder(file, pid)) {
+      rmSync(file, { force: true });
+      rmSync(`${file}.start`, { force: true });
+    }
     return true;
   } finally {
     releaseOwn(evictor);
@@ -213,7 +265,7 @@ function advertise(urlFile, url) {
 function servedBy(file, urlFile, pid) {
   try {
     const said = JSON.parse(readFileSync(urlFile, "utf-8"));
-    const live = said.pid === pid && alive(pid) && ownerOf(file) === pid;
+    const live = said.pid === pid && holdsLock(file, pid) && ownerOf(file) === pid;
     return live && typeof said.url === "string" ? said.url : void 0;
   } catch {
     return void 0;

package/dist/helpers/mediaCodecMap.d.ts

@@ -1,3 +1,5 @@
+import { PreviewSourceFacts, PreviewProxyBox } from '@hyperframes/core';
+
 interface FfprobeRunResult {
     status: number | null;
     stdout: string | Buffer;
@@ -31,6 +33,8 @@ interface AssetCodecFacts {
     /** Source carries an alpha channel (`MediaMetadata.hasAlpha`). Alpha sources use a
      * VP8/WebM proxy so their transparency is preserved across Chromium builds. */
     hasAlpha: boolean;
+    /** Size, bit depth and bitrate, for deciding whether a playable file deserves a lighter copy. */
+    source?: PreviewSourceFacts;
 }
 /** Server-root-relative URL pathname -> that asset's codec facts. */
 type MediaCodecMap = Record<string, AssetCodecFacts>;
@@ -96,8 +100,11 @@ type MediaProxyEligibility = {
     eligible: false;
     reason: MediaProxyIneligibilityReason;
 };
-/** Single policy gate shared by proactive scans and on-demand proxy routes. */
-declare function decideMediaProxyEligibility(facts: AssetCodecFacts | null): MediaProxyEligibility;
+/**
+ * Single policy gate shared by proactive scans and on-demand proxy routes. A file Chrome can play is
+ * eligible only for a lighter copy (`lightBox`, the box that request asks for) and only when it is heavy there.
+ */
+declare function decideMediaProxyEligibility(facts: AssetCodecFacts | null, lightBox?: PreviewProxyBox): MediaProxyEligibility;
 interface CachedAssetProbe {
     /** The file a symlinked path pointed at, so retargeting the link is a miss. */
     target: string;
@@ -126,12 +133,15 @@ interface ScanProjectMediaCodecMapOptions {
     cache?: MediaCodecProbeCache;
     runner?: FfprobeRunner;
 }
-/**
- * Scans a project's composition HTML for local `<video src>` references and
- * returns the injection map: root-relative URL pathname -> codec facts.
- * Best-effort throughout — a video whose codec can't be determined (missing
- * ffprobe, probe error, no video stream) is simply omitted, never thrown.
- */
+/** What a scan of a project's local videos finds: the hostile ones for the proxy map, and every readable one's size. */
+interface ProjectMediaScan {
+    codecMap: MediaCodecMap;
+    /** Root-relative URL pathname -> size, bit depth and bitrate. */
+    sourceFacts: Record<string, PreviewSourceFacts>;
+}
+/** Scans composition HTML for local `<video src>` references; a video that can't be probed is omitted. */
+declare function scanProjectMedia(projectDir: string, htmlSources: HtmlSourceLike[], options?: ScanProjectMediaCodecMapOptions): Promise<ProjectMediaScan>;
+/** The injection map alone: root-relative URL pathname -> codec facts of the hostile videos. */
 declare function scanProjectMediaCodecMap(projectDir: string, htmlSources: HtmlSourceLike[], options?: ScanProjectMediaCodecMapOptions): Promise<MediaCodecMap>;
 
-export { type AssetCodecFacts, BROWSER_HOSTILE_CODECS, type BrowserHostileCodec, type HtmlSourceLike, type MediaCodecMap, type MediaCodecProbeCache, type MediaProxyEligibility, type MediaProxyIneligibilityReason, PROXY_VARIANT_CONFIG, type ProxyVariant, type ProxyVariantRequest, type ScanProjectMediaCodecMapOptions, createMediaCodecProbeCache, decideMediaProxyEligibility, isProxyVariant, isProxyVariantRequest, mediaProxyDemand, probeAssetCodec, proxyVariantFor, recordProxyPrewarm, recordProxyRequest, resolveProxyVariantRequest, scanProjectMediaCodecMap, shouldPrewarmProxy };
+export { type AssetCodecFacts, BROWSER_HOSTILE_CODECS, type BrowserHostileCodec, type HtmlSourceLike, type MediaCodecMap, type MediaCodecProbeCache, type MediaProxyEligibility, type MediaProxyIneligibilityReason, PROXY_VARIANT_CONFIG, type ProjectMediaScan, type ProxyVariant, type ProxyVariantRequest, type ScanProjectMediaCodecMapOptions, createMediaCodecProbeCache, decideMediaProxyEligibility, isProxyVariant, isProxyVariantRequest, mediaProxyDemand, probeAssetCodec, proxyVariantFor, recordProxyPrewarm, recordProxyRequest, resolveProxyVariantRequest, scanProjectMedia, scanProjectMediaCodecMap, shouldPrewarmProxy };

package/dist/helpers/mediaCodecMap.js

@@ -11,9 +11,10 @@ import {
   recordProxyPrewarm,
   recordProxyRequest,
   resolveProxyVariantRequest,
+  scanProjectMedia,
   scanProjectMediaCodecMap,
   shouldPrewarmProxy
-} from "../chunk-XMNHDWQI.js";
+} from "../chunk-C2RFW2FX.js";
 import "../chunk-QF7MFJJU.js";
 import "../chunk-SVQFE44C.js";
 import "../chunk-L3HJVTQE.js";
@@ -30,6 +31,7 @@ export {
   recordProxyPrewarm,
   recordProxyRequest,
   resolveProxyVariantRequest,
+  scanProjectMedia,
   scanProjectMediaCodecMap,
   shouldPrewarmProxy
 };

package/dist/helpers/mediaProxyPreview.js

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

package/dist/helpers/proxyTranscoder.d.ts

@@ -11,7 +11,7 @@ import { ProxyVariant } from './mediaCodecMap.js';
  * caller's `signal` detaches that caller; once no caller is left, the copy is
  * dropped from the queue or its ffmpeg is killed.
  */
-declare const PROXY_PARAMS_VERSION = "v6";
+declare const PROXY_PARAMS_VERSION = "v7";
 declare const CACHE_DIR_NAME = ".transcode-cache";
 /** A copy that makes no progress this long is ended: a hung encode, not a slow one. */
 declare const TRANSCODE_STALL_MS: number;

package/dist/helpers/proxyTranscoder.js

@@ -17,8 +17,8 @@ import {
   resolveProxies,
   resolveProxy,
   waitForProxy
-} from "../chunk-URMIRXBS.js";
-import "../chunk-XMNHDWQI.js";
+} from "../chunk-5UEDEOD2.js";
+import "../chunk-C2RFW2FX.js";
 import "../chunk-QF7MFJJU.js";
 import "../chunk-SVQFE44C.js";
 import "../chunk-L3HJVTQE.js";

package/dist/history/index.js

@@ -22,7 +22,7 @@ import {
   recordRenderSuccess,
   registerRenderOutput,
   retainSnapshotOutput
-} from "../chunk-VKQTZKGA.js";
+} from "../chunk-OSZE5WT3.js";
 import "../chunk-QF7MFJJU.js";
 import "../chunk-SVQFE44C.js";
 import "../chunk-L3HJVTQE.js";

package/dist/index.d.ts

@@ -93,7 +93,7 @@ interface DuplicateElementResult {
     matched: boolean;
     newId: string | null;
 }
-declare function duplicateElementInHtml(source: string, target: SourceMutationTarget, newId: string, at: number): DuplicateElementResult;
+declare function duplicateElementInHtml(source: string, target: SourceMutationTarget, newId: string, at: number, fallbackDuration?: number): DuplicateElementResult;
 
 interface FileMutationInput {
     sourceFile: string;

package/dist/index.js

@@ -62,7 +62,7 @@ import {
   resolveProjectSignature,
   retainSnapshotOutput,
   settledFileTag
-} from "./chunk-VKQTZKGA.js";
+} from "./chunk-OSZE5WT3.js";
 import {
   clearElementScreenshotIsolation,
   getElementScreenshotClip
@@ -82,7 +82,7 @@ import {
   isAutoProxyEnabled,
   proxyEtagSalt,
   resolvePreviewMediaCodecProbeCache
-} from "./chunk-ZCCJNXS7.js";
+} from "./chunk-HZCA2O76.js";
 import {
   CACHE_DIR_NAME,
   PROXY_PENDING_RETRY_AFTER_SECONDS,
@@ -93,7 +93,7 @@ import {
   proxyActivityMark,
   resolveProxy,
   waitForProxy
-} from "./chunk-URMIRXBS.js";
+} from "./chunk-5UEDEOD2.js";
 import {
   PROXY_VARIANT_CONFIG,
   decideMediaProxyEligibility,
@@ -102,7 +102,7 @@ import {
   probeMediaMetadata,
   recordProxyRequest,
   resolveProxyVariantRequest
-} from "./chunk-XMNHDWQI.js";
+} from "./chunk-C2RFW2FX.js";
 import {
   folderGone,
   isInHiddenOrVendorDir,
@@ -3885,7 +3885,11 @@ import {
   STUDIO_PREVIEW_MARK_META,
   STUDIO_PREVIEW_ERRORS
 } from "@hyperframes/core/studio-preview-mark";
-import { PREVIEW_PROXY_BOX_PARAM, parsePreviewProxyBox } from "@hyperframes/core";
+import {
+  PREVIEW_PROXY_BOX_PARAM,
+  PREVIEW_PROXY_LIGHT_PARAM,
+  parsePreviewProxyBox
+} from "@hyperframes/core";
 import {
   GSAP_BASE_URL_META,
   gsapCdnDist as gsapCdnDist2,
@@ -4502,7 +4506,8 @@ ${etag}`;
     const proxyParam = c.req.query("hf-proxy");
     const boxParam = c.req.query(PREVIEW_PROXY_BOX_PARAM);
     const proxyBox = boxParam === void 0 ? void 0 : parsePreviewProxyBox(boxParam);
-    if (proxyBox === null || proxyBox && proxyParam === void 0) {
+    const lightRequested = c.req.query(PREVIEW_PROXY_LIGHT_PARAM) !== void 0;
+    if (proxyBox === null || proxyBox && proxyParam === void 0 || lightRequested && !proxyBox) {
       return c.text("not found", 404);
     }
     let proxyVariant;
@@ -4511,7 +4516,7 @@ ${etag}`;
         return c.text("not found", 404);
       }
       const facts = await probeAssetCodec(file, void 0, mediaCodecProbeCache);
-      const eligibility = decideMediaProxyEligibility(facts);
+      const eligibility = decideMediaProxyEligibility(facts, lightRequested ? proxyBox : void 0);
       if (!eligibility.eligible) {
         return c.text(`media proxy unavailable: ${eligibility.reason}`, 422);
       }
@@ -6648,9 +6653,29 @@ function registerHistoryRoutes(api, adapter) {
   );
 }
 
+// src/helpers/previewErrorPage.ts
+import { STUDIO_PREVIEW_ERRORS as STUDIO_PREVIEW_ERRORS2 } from "@hyperframes/core/studio-preview-mark";
+function previewErrorPage(status) {
+  const message = `The preview page could not be loaded (HTTP ${status}).`;
+  return `<!doctype html><meta charset="utf-8"><script>window.${STUDIO_PREVIEW_ERRORS2}=[${JSON.stringify(message)}]</script><p>${message}</p>`;
+}
+
 // src/createStudioApi.ts
+async function answerRefusedFrameWithPage(c, next) {
+  await next();
+  if (c.req.header("sec-fetch-dest") !== "iframe" || c.res.status < 400) return;
+  const headers = new Headers(c.res.headers);
+  headers.set("content-type", "text/html; charset=utf-8");
+  headers.delete("content-length");
+  c.res = new Response(previewErrorPage(c.res.status), {
+    status: c.res.status,
+    headers
+  });
+}
 function createStudioApi(adapter) {
   const api = new Hono();
+  api.use("/projects/:id/preview/*", answerRefusedFrameWithPage);
+  api.use("/projects/:id/preview", answerRefusedFrameWithPage);
   api.use(async function answerProjectDirMissingAfterErrorHandlers(c, next) {
     const hostHeaders = new Headers(c.res.headers);
     await next();
@@ -6701,13 +6726,14 @@ function createStudioApi(adapter) {
 // src/helpers/duplicateElement.ts
 import { sameInstant } from "@hyperframes/core/clip-facts";
 import { ensureHfIds as ensureHfIds4 } from "@hyperframes/parsers/hf-ids";
-function duplicateElementInHtml(source, target, newId, at) {
+function duplicateElementInHtml(source, target, newId, at, fallbackDuration = 0) {
   const { document, wrappedFragment } = parseSourceDocument(source);
   const element = findTargetElement(document, target);
   if (!element || !element.parentElement) return { html: source, matched: false, newId: null };
-  const duration = numericAttribute(element, "data-duration");
+  const duration = element.hasAttribute("data-duration") ? numericAttribute(element, "data-duration") : fallbackDuration;
+  const start = numericAttribute(element, "data-start");
   const track = numericAttribute(element, "data-track-index") ?? 0;
-  if (duration === null || numericAttribute(element, "data-start") === null) {
+  if (duration === null || start === null) {
     return { html: source, matched: false, newId: null };
   }
   const uniqueId = nextUniqueId(document, newId);
@@ -6717,13 +6743,13 @@ function duplicateElementInHtml(source, target, newId, at) {
   clone.setAttribute("id", uniqueId);
   dedupeClonedCompositionId(document, clone);
   stripStableIds(clone);
-  clone.setAttribute("data-start", String(at));
+  moveElementStart(clone, start, at);
   element.parentElement.insertBefore(clone, element.nextSibling);
   const html = wrappedFragment ? document.body.innerHTML || "" : document.toString();
   return { html: ensureHfIds4(html), matched: true, newId: uniqueId };
 }
 function rippleElements(document, element, at, duration, track) {
-  for (const candidate of Array.from(document.querySelectorAll("[data-start][data-duration]"))) {
+  for (const candidate of Array.from(document.querySelectorAll("[data-start]"))) {
     if (candidate === element || candidate.getAttribute("data-track-index") !== String(track)) {
       continue;
     }
@@ -6731,9 +6757,15 @@ function rippleElements(document, element, at, duration, track) {
     if (start === null) continue;
     const metInsertionPoint = sameInstant(start, at);
     if (start < at && !metInsertionPoint) continue;
-    candidate.setAttribute("data-start", String((metInsertionPoint ? at : start) + duration));
+    moveElementStart(candidate, start, (metInsertionPoint ? at : start) + duration);
   }
 }
+function moveElementStart(element, start, nextStart) {
+  element.setAttribute("data-start", String(nextStart));
+  if (!element.hasAttribute("data-end")) return;
+  const end = numericAttribute(element, "data-end");
+  if (end !== null) element.setAttribute("data-end", String(end + (nextStart - start)));
+}
 function stripStableIds(element) {
   element.removeAttribute("data-hf-id");
   for (const child of Array.from(element.querySelectorAll("[data-hf-id]"))) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio-server",
-  "version": "0.8.199",
+  "version": "0.8.201",
   "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/parsers": "0.8.199",
-    "@hyperframes/core": "0.8.199"
+    "@hyperframes/core": "0.8.201",
+    "@hyperframes/parsers": "0.8.201"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",