@hyperframes/studio-server 0.8.106 → 0.8.108

package/dist/index.js

@@ -43,10 +43,17 @@ import {
   resolveProjectAndSignature,
   resolveProjectSignature,
   settledFileTag
-} from "./chunk-IQK4ANAI.js";
+} from "./chunk-KUEG5MYA.js";
 import {
   getElementScreenshotClip
 } from "./chunk-W2SBTCO2.js";
+import {
+  DEFAULT_TARGET_LUFS,
+  absoluteLoudnessPlan,
+  measureAudio,
+  requiredFfmpeg,
+  resolveLocalAudioPath
+} from "./chunk-TEYDBVSK.js";
 import {
   injectMediaCodecMap,
   isAutoProxyEnabled,
@@ -587,6 +594,33 @@ import {
   syncPositionHoldsBeforeKeyframes,
   clipQueryRoot
 } from "@hyperframes/parsers/gsap-writer-acorn";
+
+// src/helpers/studioFontFace.ts
+var FONT_STYLE_RE = /<style\b[^>]*data-hf-studio-fonts=(["'])true\1[^>]*>([\s\S]*?)<\/style>/i;
+var ONE_FONT_FACE_RULE = /^@font-face \{(?:[^{}<"'\\]|"(?:[^"\\<\n\r\f]|\\[^<\n\r\f])*"|'(?:[^'\\<\n\r\f]|\\[^<\n\r\f])*')*\}$/;
+function isStudioFontFaceCss(css) {
+  return typeof css === "string" && ONE_FONT_FACE_RULE.test(css);
+}
+function ensureStudioFontFaceCss(html, css) {
+  if (html.includes(css)) return html;
+  const block = FONT_STYLE_RE.exec(html);
+  if (block) {
+    const next = `${(block[2] ?? "").trim()}
+${css}`.trim();
+    return html.replace(block[0], () => `<style data-hf-studio-fonts="true">
+${next}
+</style>`);
+  }
+  const styleTag = `<style data-hf-studio-fonts="true">
+${css}
+</style>`;
+  if (/<\/head>/i.test(html)) return html.replace(/<\/head>/i, () => `  ${styleTag}
+  </head>`);
+  return `${styleTag}
+${html}`;
+}
+
+// src/routes/files.ts
 import { parseHTML as parseHTML2 } from "linkedom";
 import { ensureHfIds } from "@hyperframes/parsers/hf-ids";
 
@@ -1221,7 +1255,7 @@ function bakeGroupTransformIntoMembers(html, groupId, members, groupCenter) {
   const rad = grot * Math.PI / 180;
   const cos = Math.cos(rad);
   const sin = Math.sin(rad);
-  const round3 = (n) => Math.round(n * 1e3) / 1e3;
+  const round32 = (n) => Math.round(n * 1e3) / 1e3;
   let script = block.scriptText;
   for (const m of members) {
     const memberSel = `#${m.id}`;
@@ -1238,27 +1272,27 @@ function bakeGroupTransformIntoMembers(html, groupId, members, groupCenter) {
     const visY = groupCenter.cy + gscale * (sin * dx + cos * dy) + gy;
     const newProps = {
       ...mProps,
-      x: round3(visX - m.cx),
-      y: round3(visY - m.cy)
+      x: round32(visX - m.cx),
+      y: round32(visY - m.cy)
     };
     if (gz !== 0) newProps.z = (typeof mProps.z === "number" ? mProps.z : 0) + gz;
     if (grot !== 0) {
-      newProps.rotation = round3(
+      newProps.rotation = round32(
         (typeof mProps.rotation === "number" ? mProps.rotation : 0) + grot
       );
     }
     if (gscale !== 1) {
-      newProps.scale = round3((typeof mProps.scale === "number" ? mProps.scale : 1) * gscale);
+      newProps.scale = round32((typeof mProps.scale === "number" ? mProps.scale : 1) * gscale);
     }
     const pivoted = /* @__PURE__ */ new Set(["x", "y", "z", "rotation", "scale"]);
     for (const [k, v] of Object.entries(gt)) {
       if (pivoted.has(k) || typeof v !== "number") continue;
       if (k === "scaleX" || k === "scaleY") {
-        if (v !== 1) newProps[k] = round3((typeof mProps[k] === "number" ? mProps[k] : 1) * v);
+        if (v !== 1) newProps[k] = round32((typeof mProps[k] === "number" ? mProps[k] : 1) * v);
       } else if (k === "transformPerspective") {
         if (typeof mProps[k] !== "number") newProps[k] = v;
       } else if (v !== 0) {
-        newProps[k] = round3((typeof mProps[k] === "number" ? mProps[k] : 0) + v);
+        newProps[k] = round32((typeof mProps[k] === "number" ? mProps[k] : 0) + v);
       }
     }
     for (const s of [...sets].reverse()) {
@@ -1439,6 +1473,7 @@ async function prepareGsapMutationScript(c, res, firstMutation) {
       "</script>"
     ].join("\n");
     html = insertBeforeCloseTag(html, "body", `${bootstrap}
+`) ?? insertBeforeCloseTag(html, "template", `${bootstrap}
 `) ?? `${html}
 ${bootstrap}`;
     block = extractGsapScriptBlock(html);
@@ -2767,6 +2802,10 @@ function registerFileRoutes(api, adapter) {
     if (!Array.isArray(parsed.body.operations) || parsed.body.operations.length === 0) {
       return c.json({ error: "target and operations required" }, 400);
     }
+    const { fontFaceCss } = parsed.body;
+    if (fontFaceCss !== void 0 && !isStudioFontFaceCss(fontFaceCss)) {
+      return c.json({ error: "fontFaceCss must be one @font-face rule" }, 400);
+    }
     const unsafeFields = findUnsafeDomPatchValues(parsed.body);
     if (unsafeFields.length > 0) {
       return rejectUnsafeMutationValues(c, unsafeFields);
@@ -2778,11 +2817,9 @@ function registerFileRoutes(api, adapter) {
       } catch {
         return c.json({ error: "not found" }, 404);
       }
-      const { html: patched, matched } = patchElementInHtml(
-        originalContent,
-        parsed.target,
-        parsed.body.operations
-      );
+      const element = patchElementInHtml(originalContent, parsed.target, parsed.body.operations);
+      const { matched } = element;
+      const patched = matched && isStudioFontFaceCss(fontFaceCss) ? ensureStudioFontFaceCss(element.html, fontFaceCss) : element.html;
       if (patched === originalContent) {
         const version2 = fileContentVersion(originalContent);
         c.header("ETag", version2);
@@ -4066,7 +4103,8 @@ function registerRenderRoutes(api, adapter) {
             progress: current.progress,
             status: current.status,
             stage: current.stage,
-            error: current.error
+            error: current.error,
+            ...current.status === "complete" && current.audioLoweredDb !== void 0 ? { audioLoweredDb: current.audioLoweredDb } : {}
           })
         });
         if (current.status !== "rendering") break;
@@ -4175,11 +4213,13 @@ function registerRenderRoutes(api, adapter) {
       const metaPath = join10(rendersDir, `${rid}.meta.json`);
       let status = "complete";
       let durationMs;
+      let audioLoweredDb;
       if (existsSync6(metaPath)) {
         try {
           const meta = JSON.parse(readFileSync7(metaPath, "utf-8"));
           if (meta.status === "failed" && !existsSync6(fp)) status = "failed";
           if (meta.durationMs) durationMs = meta.durationMs;
+          if (typeof meta.audioLoweredDb === "number") audioLoweredDb = meta.audioLoweredDb;
         } catch {
         }
       }
@@ -4189,7 +4229,8 @@ function registerRenderRoutes(api, adapter) {
         size: stat2.size,
         createdAt: stat2.mtimeMs,
         status,
-        durationMs
+        durationMs,
+        ...audioLoweredDb !== void 0 ? { audioLoweredDb } : {}
       };
     }).sort((a, b) => b.createdAt - a.createdAt);
     for (const file of files) {
@@ -4229,10 +4270,10 @@ var ThumbnailGenerationCoordinator = class {
     if (signal.aborted) return Promise.reject(new DOMException("Aborted", "AbortError"));
     let entry = this.entries.get(key);
     if (!entry) {
-      let resolve6;
+      let resolve7;
       let reject;
       const promise = new Promise((resolvePromise, rejectPromise) => {
-        resolve6 = resolvePromise;
+        resolve7 = resolvePromise;
         reject = rejectPromise;
       });
       entry = {
@@ -4242,7 +4283,7 @@ var ThumbnailGenerationCoordinator = class {
         state: "queued",
         work,
         promise,
-        resolve: resolve6,
+        resolve: resolve7,
         reject
       };
       this.entries.set(key, entry);
@@ -4256,7 +4297,7 @@ var ThumbnailGenerationCoordinator = class {
     return /* @__PURE__ */ new Set([...this.entries.keys(), ...[...this.activeEntries].map((entry) => entry.key)]);
   }
   lease(entry, signal) {
-    return new Promise((resolve6, reject) => {
+    return new Promise((resolve7, reject) => {
       let released = false;
       const release = () => {
         if (released) return;
@@ -4280,7 +4321,7 @@ var ThumbnailGenerationCoordinator = class {
       entry.promise.then(
         (value) => {
           release();
-          resolve6(value);
+          resolve7(value);
         },
         (reason) => {
           release();
@@ -4357,14 +4398,14 @@ async function generateThumbnail(path, signal) {
 async function resolveSource(adapter, id, url) {
   const project = await adapter.resolveProject(id);
   if (!project) throw new HTTPException(404);
-  let relative4;
+  let relative5;
   try {
-    relative4 = requestSubPath(url, "projects/:id/image-thumbnail");
+    relative5 = requestSubPath(url, "projects/:id/image-thumbnail");
   } catch {
     throw new HTTPException(400);
   }
-  if (!/\.jpe?g$/i.test(relative4)) throw new HTTPException(415);
-  const path = pinWithinProject(project.dir, relative4);
+  if (!/\.jpe?g$/i.test(relative5)) throw new HTTPException(415);
+  const path = pinWithinProject(project.dir, relative5);
   if (!path) throw new HTTPException(404);
   const info = await stat(path).catch(() => {
     throw new HTTPException(404);
@@ -4732,6 +4773,523 @@ function registerWaveformRoutes(api, adapter) {
   });
 }
 
+// src/routes/freezeFrame.ts
+import { execFile } from "child_process";
+import { existsSync as existsSync8, readFileSync as readFileSync11, statSync as statSync8 } from "fs";
+import { dirname as dirname5, join as join13, relative as relative4, sep as sep2 } from "path";
+import { findFfBinary as findFfBinary3 } from "@hyperframes/parsers/ff-binaries";
+import { replaceFileAtomically as replaceFileAtomically3 } from "@hyperframes/core/atomic-file";
+
+// src/helpers/freezeFrame.ts
+import { createHash as createHash4, randomBytes } from "crypto";
+import { ensureHfIds as ensureHfIds3 } from "@hyperframes/parsers/hf-ids";
+import { readMediaOffsetSeconds } from "@hyperframes/parsers/media-duration";
+import { resolveRateSpec, sourceTimeAt } from "@hyperframes/core/speed-ramp";
+var FREEZE_HOLD_SECONDS = 2;
+var LINK_ATTR = "data-link";
+var EPSILON = 1e-3;
+var round3 = (value) => Math.round(value * 1e3) / 1e3;
+function numberAttr(el, name) {
+  const raw = el.getAttribute(name);
+  if (raw === null || raw.trim() === "") return null;
+  const value = Number(raw);
+  return Number.isFinite(value) ? value : null;
+}
+function trackOf(el) {
+  return numberAttr(el, "data-track-index") ?? numberAttr(el, "data-layer") ?? 0;
+}
+function freezeFrameMediaTime(input) {
+  const rate = resolveRateSpec(input.automation, input.playbackRate);
+  return input.mediaStart + sourceTimeAt(rate, Math.max(0, input.playhead - input.clipStart));
+}
+function freezeExtractArgs(src, mediaTime, output) {
+  return ["-n", "-ss", String(round3(mediaTime)), "-i", src, "-frames:v", "1", output];
+}
+var randomStillToken = () => randomBytes(4).toString("hex");
+function freezeStillFileName(clipId, playhead, token = randomStillToken()) {
+  const stem = clipId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 48) || "clip";
+  const idHash = createHash4("sha256").update(clipId).digest("hex").slice(0, 10);
+  return `${stem}-${idHash}-${Math.round(playhead * 1e3)}-${token}.png`;
+}
+function readFreezeSource(html, target, playhead) {
+  const { document } = parseSourceDocument(html);
+  const el = findTargetElement(document, target);
+  if (!el || el.tagName.toLowerCase() !== "video") return null;
+  const src = el.getAttribute("src");
+  const start = numberAttr(el, "data-start");
+  const duration = numberAttr(el, "data-duration");
+  if (!src || start === null || duration === null) return null;
+  if (playhead <= start + EPSILON || playhead >= start + duration - EPSILON) return null;
+  return {
+    id: el.getAttribute("id") || "clip",
+    src,
+    mediaTime: freezeFrameMediaTime({
+      clipStart: start,
+      playhead,
+      mediaStart: readMediaOffsetSeconds((name) => el.getAttribute(name)),
+      playbackRate: numberAttr(el, "data-playback-rate") ?? 1,
+      automation: el.getAttribute("data-automation")
+    })
+  };
+}
+function targetOf(el) {
+  const hfId = el.getAttribute("data-hf-id");
+  return { ...hfId ? { hfId } : {}, id: el.getAttribute("id") };
+}
+function spans(el, time) {
+  const start = numberAttr(el, "data-start");
+  const duration = numberAttr(el, "data-duration");
+  if (start === null || duration === null) return false;
+  return time > start + EPSILON && time < start + duration - EPSILON;
+}
+function uniqueId(document, base) {
+  let id = base;
+  for (let n = 2; document.getElementById(id); n++) id = `${base}-${n}`;
+  return id;
+}
+function shiftTracks(document, tracks, from, by) {
+  for (const el of document.querySelectorAll("[data-start]")) {
+    if (el.hasAttribute("data-composition-id") || !tracks.has(trackOf(el))) continue;
+    const start = numberAttr(el, "data-start");
+    if (start === null || start < from - EPSILON) continue;
+    el.setAttribute("data-start", String(round3(start + by)));
+  }
+}
+function growRootToFit(document) {
+  const root = document.querySelector("[data-composition-id]");
+  const rootDuration = root ? numberAttr(root, "data-duration") : null;
+  if (!root || rootDuration === null) return;
+  let end = rootDuration;
+  for (const el of root.querySelectorAll("[data-start][data-duration]")) {
+    const start = numberAttr(el, "data-start");
+    const duration = numberAttr(el, "data-duration");
+    if (start !== null && duration !== null) end = Math.max(end, start + duration);
+  }
+  if (end > rootDuration + EPSILON) root.setAttribute("data-duration", String(round3(end)));
+}
+var COPIED_PICTURE_ATTRS = ["class", "style", "data-color-grading"];
+function buildStill(document, video, input) {
+  const img = document.createElement("img");
+  img.setAttribute("id", input.id);
+  for (const name of COPIED_PICTURE_ATTRS) {
+    const value = video.getAttribute(name);
+    if (value !== null) img.setAttribute(name, value);
+  }
+  if (!img.classList.contains("clip")) img.classList.add("clip");
+  img.setAttribute("src", input.imageSrc);
+  img.setAttribute("alt", "");
+  img.setAttribute("data-start", String(round3(input.playhead)));
+  img.setAttribute("data-duration", String(input.holdSeconds));
+  img.setAttribute("data-track-index", String(trackOf(video)));
+  img.setAttribute("data-timeline-label", "Freeze");
+  return img;
+}
+function linkedPartners(document, video) {
+  const link = video.getAttribute(LINK_ATTR);
+  if (!link) return [];
+  return Array.from(document.querySelectorAll(`[${LINK_ATTR}]`)).filter(
+    (el) => el !== video && el.getAttribute(LINK_ATTR) === link
+  );
+}
+function splitAll(html, elements, time) {
+  const rightHalfIds = [];
+  let next = html;
+  for (const el of elements) {
+    const split = splitElementInHtml(
+      next,
+      targetOf(el),
+      time,
+      `${el.getAttribute("id") || "clip"}-split`,
+      {
+        start: numberAttr(el, "data-start") ?? 0,
+        duration: numberAttr(el, "data-duration") ?? 0,
+        track: trackOf(el)
+      }
+    );
+    if (!split.matched || !split.newId) return null;
+    next = split.html;
+    rightHalfIds.push(split.newId);
+  }
+  return { html: next, rightHalfIds };
+}
+function relinkRightHalves(document, link, ids) {
+  if (!link) return;
+  const rightLink = uniqueLink(document, link);
+  for (const id of ids) document.getElementById(id)?.setAttribute(LINK_ATTR, rightLink);
+}
+function applyFreezeFrameToHtml(html, input) {
+  const hold = input.holdSeconds ?? FREEZE_HOLD_SECONDS;
+  const { document: before } = parseSourceDocument(html);
+  const video = findTargetElement(before, input.target);
+  if (!video || !isHTMLElement(video) || !spans(video, input.playhead)) return null;
+  const partners = linkedPartners(before, video);
+  const tracks = /* @__PURE__ */ new Set([trackOf(video), ...partners.map(trackOf)]);
+  const cut = splitAll(
+    html,
+    [video, ...partners.filter((el) => spans(el, input.playhead))],
+    input.playhead
+  );
+  if (!cut) return null;
+  const { document, wrappedFragment } = parseSourceDocument(cut.html);
+  relinkRightHalves(document, video.getAttribute(LINK_ATTR), cut.rightHalfIds);
+  shiftTracks(document, tracks, input.playhead, hold);
+  const leftHalf = findTargetElement(document, input.target);
+  if (!leftHalf?.parentElement) return null;
+  const freezeId = uniqueId(document, `${video.getAttribute("id") || "clip"}-freeze`);
+  const still = buildStill(document, leftHalf, {
+    id: freezeId,
+    imageSrc: input.imageSrc,
+    playhead: input.playhead,
+    holdSeconds: hold
+  });
+  leftHalf.parentElement.insertBefore(still, leftHalf.nextSibling);
+  growRootToFit(document);
+  return {
+    html: ensureHfIds3(wrappedFragment ? document.body.innerHTML || "" : document.toString()),
+    freezeId
+  };
+}
+function uniqueLink(document, base) {
+  const taken = new Set(
+    Array.from(document.querySelectorAll(`[${LINK_ATTR}]`)).map((el) => el.getAttribute(LINK_ATTR))
+  );
+  let candidate = `${base}-2`;
+  for (let n = 3; taken.has(candidate); n++) candidate = `${base}-${n}`;
+  return candidate;
+}
+
+// src/routes/freezeFrame.ts
+var EXTRACT_TIMEOUT_MS = 3e4;
+var ffmpegExtractor = (args) => {
+  const ffmpeg = findFfBinary3("ffmpeg", { configuredMustExist: true });
+  if (!ffmpeg) return Promise.resolve({ ok: false, error: "ffmpeg not found" });
+  return new Promise((resolvePromise) => {
+    execFile(
+      ffmpeg,
+      args,
+      { timeout: EXTRACT_TIMEOUT_MS, windowsHide: true },
+      (error, _o, stderr) => resolvePromise(
+        error ? { ok: false, error: String(stderr || error.message) } : { ok: true }
+      )
+    );
+  });
+};
+function isFreezeFrameRequest(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const body = value;
+  return typeof body.path === "string" && body.path.length > 0 && typeof body.expectedVersion === "string" && typeof body.target === "object" && body.target !== null && typeof body.playhead === "number" && Number.isFinite(body.playhead);
+}
+var FREEZE_DIR = ["assets", "freeze"];
+function readExpected(absPath, expectedVersion) {
+  let content;
+  try {
+    content = readFileSync11(absPath, "utf-8");
+  } catch {
+    return { error: "not found", status: 404 };
+  }
+  return fileContentVersion(content) === expectedVersion ? { content } : { error: "file conflict", status: 409 };
+}
+async function extractStill(projectDir, absPath, source, playhead, tools) {
+  const fileDir = dirname5(absPath);
+  const mediaPath = pinWithinProject(projectDir, relative4(projectDir, join13(fileDir, source.src)));
+  if (!mediaPath) return { error: `forbidden media path: ${source.src}`, status: 403 };
+  const freezeDir = join13(projectDir, ...FREEZE_DIR);
+  const fileName = freezeStillFileName(source.id, playhead, tools.stillToken());
+  mkdirWithinProject(projectDir, freezeDir);
+  const imagePath = pinWithinProject(projectDir, join13(...FREEZE_DIR, fileName));
+  if (!imagePath || dirname5(imagePath) !== freezeDir) {
+    return { error: `forbidden freeze path: ${fileName}`, status: 403 };
+  }
+  if (existsSync8(imagePath))
+    return { error: `freeze still already exists: ${fileName}`, status: 409 };
+  const extracted = await tools.extract(freezeExtractArgs(mediaPath, source.mediaTime, imagePath));
+  if (!extracted.ok) {
+    return {
+      error: `Could not extract the frame: ${extracted.error ?? "ffmpeg failed"}`,
+      status: 500
+    };
+  }
+  const depth = relative4(projectDir, fileDir).split(sep2).filter(Boolean).length;
+  return { imageSrc: `${"../".repeat(depth)}${FREEZE_DIR.join("/")}/${fileName}` };
+}
+function writeFolded(projectDir, absPath, path, before, after, options) {
+  if (readFileSync11(absPath, "utf-8") !== before) {
+    return { error: `file conflict: ${path}`, status: 409 };
+  }
+  const backup = snapshotBeforeWrite(projectDir, absPath);
+  if (backup.error) return { error: `Failed to create backup: ${backup.error}`, status: 500 };
+  const writeToken = createWriteToken(options.token);
+  replaceFileAtomically3(absPath, after, statSync8(absPath).mode);
+  const version = fileContentVersion(after);
+  recordFileWriteReceipt(absPath, { path, version, writeToken, overwrote: before });
+  return { version, writeToken, backupPath: backupPathForResponse(projectDir, backup.backupPath) };
+}
+function registerFreezeFrameRoutes(api, adapter, extract = ffmpegExtractor, stillToken = randomStillToken) {
+  api.post("/projects/:id/file-mutations/freeze-frame", async (c) => {
+    const body = await c.req.json().catch(() => null);
+    if (!isFreezeFrameRequest(body)) {
+      return c.json({ error: "path, expectedVersion, target and playhead required" }, 400);
+    }
+    const project = await adapter.resolveProject(c.req.param("id"));
+    if (!project) return c.json({ error: "not found" }, 404);
+    const absPath = pinWithinProject(project.dir, body.path);
+    if (!absPath) return c.json({ error: `forbidden path: ${body.path}` }, 403);
+    const read = readExpected(absPath, body.expectedVersion);
+    if ("error" in read) return c.json({ error: `${read.error}: ${body.path}` }, read.status);
+    const before = read.content;
+    const source = readFreezeSource(before, body.target, body.playhead);
+    if (!source) return c.json({ error: "Move the playhead inside a video clip to freeze" }, 400);
+    const still = await extractStill(project.dir, absPath, source, body.playhead, {
+      extract,
+      stillToken
+    });
+    if ("error" in still) return c.json({ error: still.error }, still.status);
+    const { imageSrc } = still;
+    const folded = applyFreezeFrameToHtml(before, {
+      target: body.target,
+      playhead: body.playhead,
+      imageSrc
+    });
+    if (!folded) return c.json({ error: "Freeze target was not found in the file" }, 400);
+    const written = writeFolded(project.dir, absPath, body.path, before, folded.html, {
+      token: body.transactionToken ?? c.req.header("X-Hyperframes-Write-Token")
+    });
+    if ("error" in written) return c.json({ error: written.error }, written.status);
+    const { version, writeToken, backupPath } = written;
+    return c.json({
+      ok: true,
+      path: body.path,
+      before,
+      after: folded.html,
+      version,
+      writeToken,
+      backupPath,
+      freezeId: folded.freezeId,
+      imageSrc
+    });
+  });
+}
+
+// src/routes/loudness.ts
+import { existsSync as existsSync9 } from "fs";
+var defaultMeasure = (file, window) => measureAudio(requiredFfmpeg(), file, window);
+var InvalidField = class extends Error {
+};
+function numberField(body, name, fallback, valid) {
+  const raw = body[name];
+  if (raw === void 0 || raw === null) return fallback;
+  if (typeof raw === "number" && Number.isFinite(raw) && valid(raw)) return raw;
+  throw new InvalidField(`${name} is out of range`);
+}
+function readNormalizeRequest(body) {
+  const src = typeof body.src === "string" ? body.src.trim() : "";
+  if (!src) throw new InvalidField("src is required");
+  const duration = numberField(body, "duration", 0, (v) => v > 0);
+  return {
+    id: typeof body.id === "string" && body.id ? body.id : src,
+    src,
+    window: {
+      mediaStart: numberField(body, "mediaStart", 0, (v) => v >= 0),
+      duration: duration > 0 ? duration : null,
+      playbackRate: numberField(body, "playbackRate", 1, (v) => v > 0)
+    },
+    volume: numberField(body, "volume", 1, (v) => v >= 0),
+    targetLufs: numberField(body, "targetLufs", DEFAULT_TARGET_LUFS, (v) => v < 0)
+  };
+}
+function parseNormalizeRequest(body) {
+  try {
+    return readNormalizeRequest(body);
+  } catch (error) {
+    if (error instanceof InvalidField) return error.message;
+    throw error;
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function registerLoudnessRoutes(api, adapter, measure = defaultMeasure) {
+  api.post("/projects/:id/loudness/normalize", async (c) => {
+    const project = await adapter.resolveProject(c.req.param("id"));
+    if (!project) return c.json({ error: "not found" }, 404);
+    const body = await c.req.json().catch(() => null);
+    if (!isRecord(body)) return c.json({ error: "invalid body" }, 400);
+    const request = parseNormalizeRequest(body);
+    if (typeof request === "string") return c.json({ error: request }, 400);
+    let file;
+    try {
+      file = resolveLocalAudioPath(project.dir, request.src);
+    } catch (error) {
+      return c.json({ error: error instanceof Error ? error.message : String(error) }, 400);
+    }
+    if (!existsSync9(file)) return c.json({ error: "file not found" }, 404);
+    try {
+      const measurement = await measure(file, request.window);
+      const plan = absoluteLoudnessPlan(
+        { id: request.id, volume: request.volume, ...measurement },
+        request.targetLufs
+      );
+      return c.json({ plan });
+    } catch (error) {
+      return c.json({ error: error instanceof Error ? error.message : String(error) }, 422);
+    }
+  });
+}
+
+// src/routes/peaks.ts
+import { existsSync as existsSync10, readFileSync as readFileSync12, statSync as statSync9 } from "fs";
+import { join as join14, resolve as resolve6 } from "path";
+import { isWithinProjectRoot as isWithinProjectRoot3 } from "@hyperframes/parsers/asset-resolution";
+
+// src/helpers/peakMap.ts
+import { execFile as execFile2, spawn as spawn2 } from "child_process";
+import { promisify } from "util";
+import { findFfBinary as findFfBinary4 } from "@hyperframes/parsers/ff-binaries";
+var PEAK_BIN_SECONDS = 0.05;
+var PEAK_SAMPLE_RATE = 48e3;
+var execFileAsync = promisify(execFile2);
+var PEAK_MAP_CACHE_VERSION = "peaks-v2";
+function createPeakAccumulator(sampleRate = PEAK_SAMPLE_RATE, binSeconds = PEAK_BIN_SECONDS, channels = 2) {
+  return {
+    bins: [],
+    frame: 0,
+    carry: Buffer.alloc(0),
+    framesPerBin: Math.max(1, Math.round(sampleRate * binSeconds)),
+    channels: Math.max(1, channels)
+  };
+}
+function framePeak(data, offset, channels) {
+  let peak = 0;
+  for (let ch = 0; ch < channels; ch++) {
+    peak = Math.max(peak, Math.abs(data.readFloatLE(offset + ch * 4)));
+  }
+  return peak;
+}
+function accumulatePeaks(acc, chunk) {
+  const data = acc.carry.length > 0 ? Buffer.concat([acc.carry, chunk]) : chunk;
+  const frameBytes = 4 * acc.channels;
+  const whole = data.length - data.length % frameBytes;
+  for (let offset = 0; offset < whole; offset += frameBytes) {
+    const peak = framePeak(data, offset, acc.channels);
+    const bin = Math.floor(acc.frame / acc.framesPerBin);
+    if (acc.bins.length <= bin) acc.bins.push(0);
+    if (peak > (acc.bins[bin] ?? 0)) acc.bins[bin] = peak;
+    acc.frame += 1;
+  }
+  acc.carry = Buffer.from(data.subarray(whole));
+}
+function finishPeaks(acc) {
+  return acc.bins.map((peak) => Number(peak.toFixed(4)));
+}
+async function probeChannels(mediaPath) {
+  const { stdout } = await execFileAsync(
+    findFfBinary4("ffprobe") ?? "ffprobe",
+    [
+      "-v",
+      "error",
+      "-select_streams",
+      "a:0",
+      "-show_entries",
+      "stream=channels",
+      "-of",
+      "csv=p=0",
+      "--",
+      mediaPath
+    ],
+    { encoding: "utf8", timeout: 3e4, windowsHide: true }
+  );
+  const channels = Number.parseInt(stdout.trim(), 10);
+  if (!Number.isFinite(channels) || channels < 1) throw new Error("no audio stream");
+  return channels;
+}
+async function decodePeakMap(mediaPath) {
+  const channels = await probeChannels(mediaPath);
+  return new Promise((resolvePromise, reject) => {
+    const proc = spawn2(
+      findFfBinary4("ffmpeg") ?? "ffmpeg",
+      [
+        "-v",
+        "error",
+        "-i",
+        mediaPath,
+        "-map",
+        "0:a:0",
+        "-vn",
+        "-ar",
+        String(PEAK_SAMPLE_RATE),
+        "-f",
+        "f32le",
+        "pipe:1"
+      ],
+      { stdio: ["ignore", "pipe", "ignore"], windowsHide: true }
+    );
+    const acc = createPeakAccumulator(PEAK_SAMPLE_RATE, PEAK_BIN_SECONDS, channels);
+    proc.stdout?.on("data", (chunk) => accumulatePeaks(acc, chunk));
+    proc.on("close", (code) => {
+      if (code !== 0) {
+        reject(new Error(`ffmpeg failed decoding audio (exit ${code})`));
+        return;
+      }
+      if (acc.frame === 0) {
+        reject(new Error("ffmpeg produced no audio samples"));
+        return;
+      }
+      resolvePromise(finishPeaks(acc));
+    });
+    proc.on("error", reject);
+  });
+}
+function buildPeakMapCacheKey(assetPath, fingerprint) {
+  const name = assetPath.replace(/[/\\]/g, "_");
+  return `${PEAK_MAP_CACHE_VERSION}_${name}_${fingerprint.size}-${Math.round(fingerprint.mtimeMs)}.json`;
+}
+
+// src/routes/peaks.ts
+var decodesInFlight = /* @__PURE__ */ new Map();
+function decodeOnce(cachePath, mediaPath, decode) {
+  const pending = decodesInFlight.get(cachePath);
+  if (pending) return pending;
+  const started = decode(mediaPath).finally(() => decodesInFlight.delete(cachePath));
+  decodesInFlight.set(cachePath, started);
+  return started;
+}
+function readCachedBins(cacheDir, cachePath) {
+  try {
+    if (!isWaveformCacheDirectory(cacheDir) || !existsSync10(cachePath)) return null;
+    const parsed = JSON.parse(readFileSync12(cachePath, "utf-8"));
+    return Array.isArray(parsed) && parsed.every((n) => typeof n === "number") ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function registerPeakRoutes(api, adapter, decode = decodePeakMap) {
+  api.get("/projects/:id/peaks/*", async (c) => {
+    const project = await adapter.resolveProject(c.req.param("id"));
+    if (!project) return c.json({ error: "not found" }, 404);
+    const assetPath = requestSubPath(c.req.url, "projects/:id/peaks");
+    const mediaPath = resolve6(project.dir, assetPath);
+    if (!isWithinProjectRoot3(project.dir, mediaPath))
+      return c.json({ error: "file not found" }, 404);
+    const stats = statSync9(mediaPath, { throwIfNoEntry: false });
+    if (!stats?.isFile()) return c.json({ error: "file not found" }, 404);
+    const cacheDir = join14(project.dir, ".waveform-cache");
+    const cachePath = join14(cacheDir, buildPeakMapCacheKey(assetPath, stats));
+    const cached = readCachedBins(cacheDir, cachePath);
+    if (cached) return c.json({ binSeconds: PEAK_BIN_SECONDS, bins: cached });
+    let bins;
+    try {
+      bins = await decodeOnce(cachePath, mediaPath, decode);
+    } catch {
+      return c.json({ error: "failed to decode audio" }, 500);
+    }
+    try {
+      writeWaveformCache(cachePath, bins);
+    } catch {
+    }
+    return c.json({ binSeconds: PEAK_BIN_SECONDS, bins });
+  });
+}
+
 // src/routes/fonts.ts
 import { closeSync as closeSync3, constants, fstatSync as fstatSync3, openSync as openSync3, readSync } from "fs";
 import {
@@ -4768,7 +5326,7 @@ var GOOGLE_FONT_FALLBACKS = [
   "Outfit",
   "JetBrains Mono"
 ];
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null;
 }
 function collectFontsFromDir(dir) {
@@ -4792,10 +5350,10 @@ function listInstalledFontFamilies() {
   return cachedFonts;
 }
 function parseGoogleFontMetadata(value) {
-  if (!isRecord(value) || !Array.isArray(value.familyMetadataList)) return [];
+  if (!isRecord2(value) || !Array.isArray(value.familyMetadataList)) return [];
   const families = [];
   for (const entry of value.familyMetadataList) {
-    if (!isRecord(entry) || typeof entry.family !== "string") continue;
+    if (!isRecord2(entry) || typeof entry.family !== "string") continue;
     families.push(entry.family);
   }
   return families;
@@ -4899,14 +5457,14 @@ function registerRegistryRoutes(api, adapter) {
 }
 
 // src/routes/selection.ts
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isFiniteNumber(value) {
   return typeof value === "number" && Number.isFinite(value);
 }
 function isStringRecord(value) {
-  return isRecord2(value) && Object.values(value).every((v) => typeof v === "string");
+  return isRecord3(value) && Object.values(value).every((v) => typeof v === "string");
 }
 function hasString(value, key) {
   return typeof value[key] === "string";
@@ -4924,20 +5482,20 @@ function hasOptionalNumber(value, key) {
   return value[key] === void 0 || isFiniteNumber(value[key]);
 }
 function isBoundingBox(value) {
-  return isRecord2(value) && ["x", "y", "width", "height"].every((key) => isFiniteNumber(value[key]));
+  return isRecord3(value) && ["x", "y", "width", "height"].every((key) => isFiniteNumber(value[key]));
 }
 function isTarget(value) {
-  if (!isRecord2(value)) return false;
+  if (!isRecord3(value)) return false;
   return hasOptionalNullableString(value, "id") && hasOptionalString(value, "hfId") && hasOptionalString(value, "selector") && hasOptionalNumber(value, "selectorIndex");
 }
 function isTextField(value) {
-  return isRecord2(value) && hasRequiredStrings(value, ["key", "label", "value", "tagName"]) && ["self", "child", "text-node"].includes(value.source);
+  return isRecord3(value) && hasRequiredStrings(value, ["key", "label", "value", "tagName"]) && ["self", "child", "text-node"].includes(value.source);
 }
 function isTextFields(value) {
   return Array.isArray(value) && value.every(isTextField);
 }
 function isSelectionSnapshot(value) {
-  if (!isRecord2(value)) return false;
+  if (!isRecord3(value)) return false;
   const checks = [
     value.schemaVersion === 1 && hasRequiredStrings(value, [
       "projectId",
@@ -4955,7 +5513,7 @@ function isSelectionSnapshot(value) {
     isStringRecord(value.inlineStyles),
     isStringRecord(value.computedStyles),
     isTextFields(value.textFields),
-    isRecord2(value.capabilities)
+    isRecord3(value.capabilities)
   ];
   return checks.every(Boolean);
 }
@@ -4979,7 +5537,7 @@ function registerSelectionRoutes(api, adapter) {
     } catch {
       return c.json({ error: "invalid json" }, 400);
     }
-    if (!isRecord2(body) || !("selection" in body)) {
+    if (!isRecord3(body) || !("selection" in body)) {
       return c.json({ error: "missing selection" }, 400);
     }
     if (body.selection === null) {
@@ -4998,8 +5556,8 @@ function registerSelectionRoutes(api, adapter) {
 
 // src/routes/media.ts
 import { streamSSE as streamSSE2 } from "hono/streaming";
-import { existsSync as existsSync8 } from "fs";
-import { basename as basename2, dirname as dirname5, extname, join as join13, posix } from "path";
+import { existsSync as existsSync11 } from "fs";
+import { basename as basename2, dirname as dirname6, extname, join as join15, posix } from "path";
 var VIDEO_EXTENSIONS = /* @__PURE__ */ new Set([
   ".mp4",
   ".mov",
@@ -5036,7 +5594,7 @@ function uniqueAssetPath(projectDir, assetPath, taken) {
   const ext = extname(assetPath);
   const withoutExt = assetPath.slice(0, -ext.length);
   let candidate = assetPath;
-  for (let index = 2; taken.has(candidate) || existsSync8(join13(projectDir, candidate)); index++) {
+  for (let index = 2; taken.has(candidate) || existsSync11(join15(projectDir, candidate)); index++) {
     candidate = `${withoutExt}-${index}${ext}`;
   }
   return candidate;
@@ -5097,7 +5655,7 @@ function registerMediaRoutes(api, adapter, options = {}) {
     }
     const filePath = resolveWithinProject(project.dir, assetPath);
     if (!filePath) return c.json({ error: "forbidden" }, 403);
-    if (!existsSync8(filePath)) return c.json({ error: "media not found" }, 404);
+    if (!existsSync11(filePath)) return c.json({ error: "media not found" }, 404);
     return c.json({ path: assetPath, metadata: await readMediaMetadata(filePath) });
   });
   api.post(
@@ -5119,7 +5677,7 @@ function registerMediaRoutes(api, adapter, options = {}) {
       }
       const inputPath = resolveWithinProject(project.dir, inputAssetPath);
       if (!inputPath) return c.json({ error: "forbidden" }, 403);
-      if (!existsSync8(inputPath)) return c.json({ error: "input media not found" }, 404);
+      if (!existsSync11(inputPath)) return c.json({ error: "input media not found" }, 404);
       const inputIsVideo = isVideoPath(inputAssetPath);
       const inputIsImage = isImagePath(inputAssetPath);
       if (!inputIsVideo && !inputIsImage) {
@@ -5155,8 +5713,8 @@ function registerMediaRoutes(api, adapter, options = {}) {
           return c.json({ error: "forbidden" }, 403);
         }
       }
-      mkdirWithinProject(project.dir, dirname5(outputPath));
-      if (backgroundOutputPath) mkdirWithinProject(project.dir, dirname5(backgroundOutputPath));
+      mkdirWithinProject(project.dir, dirname6(outputPath));
+      if (backgroundOutputPath) mkdirWithinProject(project.dir, dirname6(backgroundOutputPath));
       const jobId = makeJobId(project.id, mediaJobs);
       const state = adapter.startBackgroundRemoval({
         project,
@@ -5213,14 +5771,14 @@ function registerMediaRoutes(api, adapter, options = {}) {
 }
 
 // src/routes/globalAssets.ts
-import { existsSync as existsSync9, readFileSync as readFileSync11 } from "fs";
+import { existsSync as existsSync12, readFileSync as readFileSync13 } from "fs";
 import { homedir } from "os";
-import { join as join14 } from "path";
+import { join as join16 } from "path";
 function readGlobalAssets(home = homedir()) {
-  const manifestPath = join14(home, ".media", "manifest.jsonl");
-  if (!existsSync9(manifestPath)) return [];
+  const manifestPath = join16(home, ".media", "manifest.jsonl");
+  if (!existsSync12(manifestPath)) return [];
   const out = [];
-  for (const line of readFileSync11(manifestPath, "utf8").split("\n")) {
+  for (const line of readFileSync13(manifestPath, "utf8").split("\n")) {
     if (!line.trim()) continue;
     try {
       const rec = JSON.parse(line);
@@ -5407,6 +5965,9 @@ function createStudioApi(adapter) {
   registerSelectionRoutes(api, adapter);
   registerMediaRoutes(api, adapter);
   registerWaveformRoutes(api, adapter);
+  registerFreezeFrameRoutes(api, adapter);
+  registerLoudnessRoutes(api, adapter);
+  registerPeakRoutes(api, adapter);
   registerFontRoutes(api);
   registerRegistryRoutes(api, adapter);
   registerGlobalAssetRoutes(api);
@@ -5416,7 +5977,7 @@ function createStudioApi(adapter) {
 
 // src/helpers/duplicateElement.ts
 import { sameInstant } from "@hyperframes/core/clip-facts";
-import { ensureHfIds as ensureHfIds3 } from "@hyperframes/parsers/hf-ids";
+import { ensureHfIds as ensureHfIds4 } from "@hyperframes/parsers/hf-ids";
 function duplicateElementInHtml(source, target, newId, at) {
   const { document, wrappedFragment } = parseSourceDocument(source);
   const element = findTargetElement(document, target);
@@ -5426,23 +5987,23 @@ function duplicateElementInHtml(source, target, newId, at) {
   if (duration === null || numericAttribute(element, "data-start") === null) {
     return { html: source, matched: false, newId: null };
   }
-  const uniqueId = nextUniqueId(document, newId);
+  const uniqueId2 = nextUniqueId(document, newId);
   rippleElements(document, element, at, duration, track);
   const clone = element.cloneNode(true);
   if (!isHTMLElement(clone)) return { html: source, matched: false, newId: null };
-  clone.setAttribute("id", uniqueId);
+  clone.setAttribute("id", uniqueId2);
   dedupeClonedCompositionId(document, clone);
   stripStableIds(clone);
   clone.setAttribute("data-start", String(at));
   element.parentElement.insertBefore(clone, element.nextSibling);
   const html = wrappedFragment ? document.body.innerHTML || "" : document.toString();
-  return { html: ensureHfIds3(html), matched: true, newId: uniqueId };
+  return { html: ensureHfIds4(html), matched: true, newId: uniqueId2 };
 }
 function nextUniqueId(document, newId) {
-  let uniqueId = newId;
+  let uniqueId2 = newId;
   let suffix = 2;
-  while (document.getElementById(uniqueId)) uniqueId = `${newId}-${suffix++}`;
-  return uniqueId;
+  while (document.getElementById(uniqueId2)) uniqueId2 = `${newId}-${suffix++}`;
+  return uniqueId2;
 }
 function rippleElements(document, element, at, duration, track) {
   for (const candidate of Array.from(document.querySelectorAll("[data-start][data-duration]"))) {
@@ -5468,18 +6029,18 @@ function numericAttribute(element, name) {
 }
 
 // src/helpers/previewDocumentStore.ts
-import { createHash as createHash4 } from "crypto";
-import { readFileSync as readFileSync12, readdirSync as readdirSync5, rmSync as rmSync5 } from "fs";
-import { join as join15 } from "path";
-import { replaceFileAtomically as replaceFileAtomically3 } from "@hyperframes/core/atomic-file";
+import { createHash as createHash5 } from "crypto";
+import { readFileSync as readFileSync14, readdirSync as readdirSync5, rmSync as rmSync5 } from "fs";
+import { join as join17 } from "path";
+import { replaceFileAtomically as replaceFileAtomically4 } from "@hyperframes/core/atomic-file";
 function createPreviewDocumentStore(projectDir, salt) {
-  const dir = join15(projectDir, ".hyperframes", "preview");
-  const fileFor = (key) => join15(dir, `${createHash4("sha256").update(`${salt}
+  const dir = join17(projectDir, ".hyperframes", "preview");
+  const fileFor = (key) => join17(dir, `${createHash5("sha256").update(`${salt}
 ${key}`).digest("hex").slice(0, 32)}.html`);
   return {
     read(key) {
       try {
-        return readFileSync12(fileFor(key), "utf-8");
+        return readFileSync14(fileFor(key), "utf-8");
       } catch {
         return null;
       }
@@ -5488,9 +6049,9 @@ ${key}`).digest("hex").slice(0, 32)}.html`);
       try {
         mkdirWithinProject(projectDir, dir);
         const file = fileFor(key);
-        replaceFileAtomically3(file, html, 420);
+        replaceFileAtomically4(file, html, 420);
         for (const name of readdirSync5(dir)) {
-          if (join15(dir, name) !== file) rmSync5(join15(dir, name), { force: true });
+          if (join17(dir, name) !== file) rmSync5(join17(dir, name), { force: true });
         }
       } catch {
       }