Skip to content

Write HTML. Render video. Built for agents.

30.1 KB
Raw Blame
import type { Hono } from "hono";
import { parseHTML } from "linkedom";
import { createReadStream, existsSync, readFileSync, statSync } from "node:fs";
import { Readable } from "node:stream";
import { join, resolve } from "node:path";
import { createHash } from "node:crypto";
import {
  AFTER_FONTS_SCRIPT_TYPE,
  addScenePartsManifest,
  RUNTIME_BOOTSTRAP_ATTR,
  insertBeforeCloseTag,
  insertRuntimeTag,
  stripEmbeddedRuntimeScripts,
  type BundleOptions,
} from "@hyperframes/core/compiler";
import {
  STUDIO_PREVIEW_MARK_META,
  STUDIO_PREVIEW_ERRORS,
} from "@hyperframes/core/studio-preview-mark";
import { PREVIEW_PROXY_BOX_PARAM, parsePreviewProxyBox } from "@hyperframes/core";
import { gsapCdnDist, motionPathPluginUrl } from "@hyperframes/core/gsap-cdn";
import { findStartTags, injectTagsAtHeadStart } from "@hyperframes/core/compiler/html-document";
import { isWithinProjectRoot } from "@hyperframes/parsers/asset-resolution";
import type { ResolvedProject, StudioApiAdapter } from "../types.js";
import {
  isPrivateProjectFile,
  isProjectRootMissing,
  resolveWithinProject,
} from "../helpers/safePath.js";
import { getMimeType } from "../helpers/mime.js";
import { buildSubCompositionHtml, hasBaseElement } from "../helpers/subComposition.js";
import {
  createProjectSignature,
  resolveProjectAndSignature,
  resolveProjectSignature,
} from "../helpers/projectSignature.js";
import {
  createStudioMotionRenderBodyScript,
  STUDIO_MOTION_PATH,
} from "../helpers/studioMotionRenderScript.js";
import { ensureHfIds } from "@hyperframes/parsers/hf-ids";
import { settledFileTag } from "../helpers/fileVersion.js";
import {
  recordPreviewBuilt,
  recordPreviewRead,
  recordPreviewReferences,
} from "../helpers/previewReads.js";
import { isVariablesPayload, VARIABLES_PAYLOAD_ERROR } from "../helpers/variablesPayload.js";
import { injectPreviewVariables } from "../helpers/previewVariables.js";
import {
  resolveProxy,
  waitForProxy,
  ProxyCapacityError,
  ProxyTranscodeError,
  ProxyWaitTimeoutError,
  PROXY_PENDING_RETRY_AFTER_SECONDS,
} from "../helpers/proxyTranscoder.js";
import {
  decideMediaProxyEligibility,
  isProxyVariantRequest,
  probeAssetCodec,
  recordProxyRequest,
  resolveProxyVariantRequest,
  PROXY_VARIANT_CONFIG,
  type ProxyVariant,
} from "../helpers/mediaCodecMap.js";
import {
  isAutoProxyEnabled,
  injectMediaCodecMap,
  proxyEtagSalt,
  resolvePreviewMediaCodecProbeCache,
  type PreviewApiAdapter,
} from "../helpers/mediaProxyPreview.js";
import { requestSubPath } from "../helpers/requestSubPath.js";
import { lazyPreviewImages } from "../helpers/lazyPreviewImages.js";

const PROJECT_SIGNATURE_META = "hyperframes-project-signature";
const GSAP_CDN_SCRIPT = `<script src="${gsapCdnDist()}gsap.min.js"></script>`;
const GSAP_CUSTOM_EASE_CDN_SCRIPT = `<script src="${gsapCdnDist()}CustomEase.min.js"></script>`;
const GSAP_MOTION_PATH_CDN_SCRIPT = `<script src="${motionPathPluginUrl()}"></script>`;

function injectProjectSignature(html: string, signature: string): string {
  const tag = `<meta name="${PROJECT_SIGNATURE_META}" content="${signature}">`;
  if (html.includes(`name="${PROJECT_SIGNATURE_META}"`)) {
    return html.replace(
      new RegExp(`<meta\\s+name=["']${PROJECT_SIGNATURE_META}["'][^>]*>`, "i"),
      tag,
    );
  }
  return insertBeforeCloseTag(html, "head", `${tag}\n`) ?? `${tag}\n${html}`;
}

function readStudioMotionManifestContent(projectDir: string): string {
  const manifestPath = join(projectDir, STUDIO_MOTION_PATH);
  if (!existsSync(manifestPath)) return "";
  try {
    return readFileSync(manifestPath, "utf-8");
  } catch {
    return "";
  }
}

function parseStudioMotionManifestContent(content: string): {
  hasMotion: boolean;
  hasCustomEase: boolean;
} {
  try {
    const parsed = JSON.parse(content) as {
      motions?: Array<{ customEase?: unknown }>;
    };
    const motions = Array.isArray(parsed.motions) ? parsed.motions : [];
    return {
      hasMotion: motions.length > 0,
      hasCustomEase: motions.some((motion) => Boolean(motion?.customEase)),
    };
  } catch {
    return { hasMotion: false, hasCustomEase: false };
  }
}

/** Swaps any runtime already in the page for the preview runtime, placed as the bundler places it. */
function withPreviewRuntime(html: string, runtimeUrl: string): string {
  const tag = `<script ${RUNTIME_BOOTSTRAP_ATTR}="1" src="${runtimeUrl}"></script>`;
  return insertRuntimeTag(stripEmbeddedRuntimeScripts(html), tag);
}

function injectScriptTagIntoHead(html: string, scriptTag: string): string {
  return insertBeforeCloseTag(html, "head", `${scriptTag}\n`) ?? `${scriptTag}\n${html}`;
}

function htmlHasGsap(html: string): boolean {
  // Only match GSAP references outside <template> elements — scripts inside
  // templates are inert when cloned and don't make GSAP globally available.
  const outsideTemplates = html.replace(/<template\b[^>]*>[\s\S]*?<\/template>/gi, "");
  return (
    /<script\b[^>]*src=["'][^"']*gsap/i.test(outsideTemplates) ||
    /\/\*\s*inlined:.*gsap/i.test(outsideTemplates) ||
    /\b(GreenSock|_gsScope)\b/.test(outsideTemplates) ||
    /\bgsap\.(config|defaults|registerPlugin|version)\b/.test(outsideTemplates)
  );
}

function htmlHasCustomEase(html: string): boolean {
  return (
    /<script\b[^>]*src=["'][^"']*CustomEase/i.test(html) ||
    /\bwindow\.CustomEase\b/.test(html) ||
    /\bCustomEase\s*=\s*/.test(html)
  );
}

// A composition that drives motion via GSAP's `motionPath` (e.g. a studio-created
// motion path written into the single-source timeline) needs MotionPathPlugin
// registered before the timeline first renders — otherwise the initial seek
// throws "Invalid property motionPath ... Missing plugin?". Detect it anywhere in
// the bundle (the plugin registers globally, so sub-composition usage counts too).
function htmlUsesMotionPath(html: string): boolean {
  return /motionPath\s*[:{]/.test(html);
}

function htmlHasMotionPathPlugin(html: string): boolean {
  return (
    /<script\b[^>]*src=["'][^"']*MotionPathPlugin/i.test(html) ||
    /\bwindow\.MotionPathPlugin\b/.test(html) ||
    /\bMotionPathPlugin\s*=\s*/.test(html)
  );
}

function injectMotionPathPluginIfNeeded(html: string): string {
  if (!htmlUsesMotionPath(html) || htmlHasMotionPathPlugin(html)) return html;
  // The plugin registers onto an already-loaded gsap, so it must come AFTER the
  // core gsap script — which often lives at body-end, not <head>. Insert it
  // directly after the gsap script tag; only fall back to <head> if none is found
  // (e.g. gsap is inlined).
  const gsap = findGsapCoreScript(html);
  if (gsap) {
    const version = gsap.src.match(/gsap@([\d.]+)/)?.[1];
    const ordering = `${gsap.type ? ` type="${gsap.type}"` : ""}${gsap.defer ? " defer" : ""}`;
    const pluginTag = `<script${ordering} src="${motionPathPluginUrl(version)}"></script>`;
    return html.slice(0, gsap.end) + "\n" + pluginTag + html.slice(gsap.end);
  }
  return injectScriptTagIntoHead(html, GSAP_MOTION_PATH_CDN_SCRIPT);
}

function isGsapCoreUrl(src: string): boolean {
  const base = "http://localhost/";
  return URL.canParse(src, base) && /\/gsap(\.min)?\.js$/i.test(new URL(src, base).pathname);
}

type GsapCoreScript = { src: string; type: string | null; defer: boolean; end: number };

function findGsapCoreScript(html: string): GsapCoreScript | null {
  const scripts = [...parseHTML(html).document.querySelectorAll("script")];
  // The scanner skips comments, raw text and templates, so its `<script` offsets line up with the DOM's scripts.
  const starts = findStartTags(html, "script");
  if (starts.length !== scripts.length) return null;
  const at = scripts.findIndex((script) =>
    isGsapCoreUrl(lowerCaseAttributes(script).get("src") ?? ""),
  );
  if (at === -1) return null;
  const attributes = lowerCaseAttributes(scripts[at]!);
  const end = scriptCloseEnd(html, starts[at]!);
  if (end === 0) return null;
  return {
    src: attributes.get("src")!,
    type: attributes.get("type") ?? null,
    defer: attributes.has("defer"),
    end,
  };
}

function lowerCaseAttributes(el: Element): Map<string, string> {
  return new Map([...el.attributes].map((a) => [a.name.toLowerCase(), a.value]));
}

/** Index just past the `</script>` that closes the script starting at `start`; 0 when it never closes. */
function scriptCloseEnd(html: string, start: number): number {
  const close = /<\/script/gi;
  close.lastIndex = start;
  const closeAt = close.exec(html)?.index;
  return closeAt === undefined ? 0 : html.indexOf(">", closeAt) + 1;
}

function injectStudioMotionDependencies(html: string, manifestContent: string): string {
  const manifest = parseStudioMotionManifestContent(manifestContent);
  if (!manifest.hasMotion) return html;
  let next = html;
  if (!htmlHasGsap(next)) next = injectScriptTagIntoHead(next, GSAP_CDN_SCRIPT);
  if (manifest.hasCustomEase && !htmlHasCustomEase(next)) {
    next = injectScriptTagIntoHead(next, GSAP_CUSTOM_EASE_CDN_SCRIPT);
  }
  return next;
}

function injectStudioMotionScript(
  html: string,
  projectDir: string,
  activeCompositionPath: string,
): string {
  const manifestContent = readStudioMotionManifestContent(projectDir);
  const script = createStudioMotionRenderBodyScript(manifestContent, {
    activeCompositionPath,
  });
  if (!script) return html;
  const withDependencies = injectStudioMotionDependencies(html, manifestContent);
  const tag = `<script type="${AFTER_FONTS_SCRIPT_TYPE}">${script.replace(/<\/script/gi, "<\\/script")}</script>`;
  return insertBeforeCloseTag(withDependencies, "body", tag) ?? `${withDependencies}${tag}`;
}

const GSAP_FALLBACK_ATTR = "data-hf-gsap-fallback";
const GSAP_CDN_FALLBACK_SCRIPT = `<script ${GSAP_FALLBACK_ATTR}>
(function(){
  var cdnBase="${gsapCdnDist()}";
  var loaded={};
  function loadFallback(file){
    if(loaded[file])return loaded[file];
    return loaded[file]=new Promise(function(ok,fail){
      var s=document.createElement("script");
      s.src=cdnBase+file;s.hfGsapFallback=true;s.onload=ok;s.onerror=fail;
      document.head.appendChild(s);
    });
  }
  document.addEventListener("error",function(e){
    var t=e.target;
    if(!t||t.tagName!=="SCRIPT"||!t.src||t.hfGsapFallback)return;
    var m=t.src.match(/gsap[^/]*\\/dist\\/(.+\\.js)/);
    if(m)loadFallback(m[1]).catch(function(){
      reportError(new Error("GSAP could not load from "+t.src+" or "+cdnBase+m[1]+", so this preview's animations will not play."));
    });
  },true);
})();
</script>`;

function injectGsapCdnFallback(html: string): string {
  if (html.includes(GSAP_FALLBACK_ATTR)) return html;
  if (html.includes("<head>")) return html.replace("<head>", "<head>" + GSAP_CDN_FALLBACK_SCRIPT);
  return GSAP_CDN_FALLBACK_SCRIPT + html;
}

/**
 * Parse the `?variables=` query param. Absent/empty → null (no injection).
 * Invalid JSON or a non-object payload is a caller error — surfaced as a 400
 * by the routes rather than silently previewing with defaults.
 */
function parsePreviewVariablesParam(
  raw: string | undefined,
): { ok: true; values: Record<string, unknown> | null } | { ok: false; error: string } {
  if (raw === undefined || raw === "") return { ok: true, values: null };
  let parsed: unknown;
  try {
    parsed = JSON.parse(raw);
  } catch {
    return { ok: false, error: "variables must be valid JSON" };
  }
  if (!isVariablesPayload(parsed)) {
    return { ok: false, error: VARIABLES_PAYLOAD_ERROR };
  }
  return { ok: true, values: parsed };
}

/** ETag salt so cached previews revalidate when the variable values change. */
function variablesEtagSalt(raw: string | undefined): string {
  if (!raw) return "";
  return `:vars:${createHash("sha1").update(raw).digest("hex").slice(0, 12)}`;
}

/**
 * Read + parse `?variables=` for a preview route. `error` present → the
 * route should 400; otherwise `values` is the override object (or null when
 * the param is absent) and `raw` feeds the ETag salt.
 */
function previewVariablesFromRequest(rawVariables: string | undefined):
  | { error: string }
  | {
      error?: undefined;
      raw: string | undefined;
      values: Record<string, unknown> | null;
    } {
  const parse = parsePreviewVariablesParam(rawVariables);
  if (!parse.ok) return { error: parse.error };
  return { raw: rawVariables, values: parse.values };
}

/** Captures screenshot right after a seek, so they get every image eager and no preview mark. */
export const PREVIEW_CAPTURE_PARAM = "hf-capture";

// Studio's console capture attaches at the iframe's load; this keeps what was raised before it.
const EARLY_ERRORS_SCRIPT = `<script>(function(){var seen=window.${STUDIO_PREVIEW_ERRORS}=[];
addEventListener("error",function(e){seen.push(e.message||String(e))});})();</script>`;

function injectStudioPreviewAugmentations(
  html: string,
  adapter: StudioApiAdapter,
  projectDir: string,
  activeCompositionPath: string,
  capture: boolean,
): string {
  const marked = capture
    ? html
    : injectTagsAtHeadStart(
        lazyPreviewImages(html),
        `<meta name="${STUDIO_PREVIEW_MARK_META}">${EARLY_ERRORS_SCRIPT}`,
      );
  return injectStudioMotionScript(
    injectMotionPathPluginIfNeeded(
      injectGsapCdnFallback(
        injectProjectSignature(marked, resolveProjectSignature(adapter, projectDir)),
      ),
    ),
    projectDir,
    activeCompositionPath,
  );
}

async function transformPreviewHtml(
  html: string,
  adapter: StudioApiAdapter,
  project: { id: string; dir: string; title?: string; sessionId?: string },
  activeCompositionPath: string,
): Promise<string> {
  if (!adapter.transformPreviewHtml) return html;
  try {
    return await adapter.transformPreviewHtml({
      html,
      project,
      activeCompositionPath,
    });
  } catch (err) {
    console.warn("[Studio] preview transform failed, using original HTML:", err);
    return html;
  }
}

function resolveProjectMainHtml(
  projectDir: string,
  projectId: string,
): { html: string; compositionPath: string } | null {
  const indexPath = join(projectDir, "index.html");
  const blockHtmlPath = join(projectDir, `${projectId}.html`);
  recordPreviewRead(projectDir, indexPath);
  recordPreviewRead(projectDir, blockHtmlPath);
  if (existsSync(indexPath)) {
    return {
      html: readFileSync(indexPath, "utf-8"),
      compositionPath: "index.html",
    };
  }
  if (existsSync(blockHtmlPath)) {
    return {
      html: readFileSync(blockHtmlPath, "utf-8"),
      compositionPath: `${projectId}.html`,
    };
  }
  return null;
}

/** The bundler options every adapter's `bundle()` uses. This route serves project files under a
 * `<base href>`, so assets keep their URLs: inlined base64 multiplies the document per reference.
 * The lint route owns linting, so the bundle skips its own contract lint. */
export const PREVIEW_BUNDLE_OPTIONS = {
  runtime: "placeholder",
  inlineAssets: false,
  staticGuard: false,
  sceneParts: true,
} as const satisfies BundleOptions;

const previewBaseHref = (projectId: string) =>
  `/api/projects/${encodeURIComponent(projectId)}/preview/`;

const withPreviewBase = (html: string, projectId: string) =>
  hasBaseElement(html)
    ? html
    : injectTagsAtHeadStart(html, `<base href="${previewBaseHref(projectId)}">`);

export function registerPreviewRoutes(api: Hono, adapter: PreviewApiAdapter): void {
  const previewCacheHeaders = (etag: string) => ({
    "Cache-Control": "private, no-cache",
    ETag: etag,
  });

  // One probe cache per server instance (this function runs once per
  // registered API), reused across every preview request so the mtime-cache
  // benefit in scanProjectMediaCodecMap actually applies.
  const mediaCodecProbeCache = resolvePreviewMediaCodecProbeCache(adapter);

  // A build is a function of the project content its ETag names, so it is served again until the
  // content changes, to a cold browser as well as a revalidating one.
  const builtPreviews = new Map<string, string>();
  const rememberPreview = (key: string, html: string) => {
    builtPreviews.delete(key);
    builtPreviews.set(key, html);
    if (builtPreviews.size > 4) builtPreviews.delete(builtPreviews.keys().next().value!);
  };

  // Concurrent requests for one document (an early prefetch and the player's own load) share a build.
  const previewBuilds = new Map<string, Promise<string | null>>();

  // fallow-ignore-next-line complexity
  async function buildPreview(
    project: ResolvedProject,
    previewVariables: Record<string, unknown> | null,
    builtKey: string,
    capture: boolean,
    signature: string,
  ): Promise<string | null> {
    const diskMain = resolveProjectMainHtml(project.dir, project.id);

    try {
      let bundled = await adapter.bundle(project.dir, {
        stampHfIds: true,
        onRead: (filePath) => recordPreviewRead(project.dir, filePath),
      });
      let mainCompositionPath = "index.html";
      if (!bundled) {
        if (!diskMain) return null;
        bundled = ensureHfIds(diskMain.html);
        mainCompositionPath = diskMain.compositionPath;
      }
      bundled = withPreviewRuntime(bundled, adapter.runtimeUrl);
      recordPreviewReferences(project.dir, bundled);
      recordPreviewBuilt(project.dir);

      // Inject <base> for relative asset resolution
      bundled = withPreviewBase(bundled, project.id);

      // Also covers elements the adapter injected; ids already present are kept.
      bundled = injectStudioPreviewAugmentations(
        ensureHfIds(await transformPreviewHtml(bundled, adapter, project, mainCompositionPath)),
        adapter,
        project.dir,
        mainCompositionPath,
        capture,
      );
      if (previewVariables) bundled = injectPreviewVariables(bundled, previewVariables);
      bundled = await injectMediaCodecMap(
        bundled,
        adapter,
        project.dir,
        mainCompositionPath,
        mediaCodecProbeCache,
      );
      bundled = addScenePartsManifest(bundled, [`meta[name="${PROJECT_SIGNATURE_META}"]`]);
      if (createProjectSignature(project.dir) === signature) {
        rememberPreview(builtKey, bundled);
        if (!capture) adapter.previewDocuments?.write(builtKey, bundled);
      }
      return bundled;
    } catch {
      // Re-read disk on bundle failure so we serve the latest file content,
      // not the pre-request snapshot that may have been saved over.
      const fallback = resolveProjectMainHtml(project.dir, project.id);
      if (fallback) {
        const fallbackHtml = withPreviewBase(
          withPreviewRuntime(ensureHfIds(fallback.html), adapter.runtimeUrl),
          project.id,
        );
        let fallbackAugmented = injectStudioPreviewAugmentations(
          await transformPreviewHtml(fallbackHtml, adapter, project, fallback.compositionPath),
          adapter,
          project.dir,
          fallback.compositionPath,
          capture,
        );
        if (previewVariables) {
          fallbackAugmented = injectPreviewVariables(fallbackAugmented, previewVariables);
        }
        fallbackAugmented = await injectMediaCodecMap(
          fallbackAugmented,
          adapter,
          project.dir,
          fallback.compositionPath,
          mediaCodecProbeCache,
        );
        return fallbackAugmented;
      }
      return null;
    }
  }

  // Bundled composition preview
  // fallow-ignore-next-line complexity
  api.get("/projects/:id/preview", async (c) => {
    const resolved = await resolveProjectAndSignature(adapter, c.req.param("id"));
    if (!resolved) return c.json({ error: "not found" }, 404);
    const { project, signature } = resolved;

    // fallow-ignore-next-line code-duplication
    const vars = previewVariablesFromRequest(c.req.query("variables"));
    if (vars.error !== undefined) return c.json({ error: vars.error }, 400);
    const previewVariables = vars.values;
    const capture = c.req.query(PREVIEW_CAPTURE_PARAM) !== undefined;

    const etag = `"preview:${signature}${variablesEtagSalt(vars.raw)}${capture ? ":capture" : ""}"`;
    const ifNoneMatch = c.req.header("If-None-Match");
    if (ifNoneMatch === etag) {
      return new Response(null, {
        status: 304,
        headers: previewCacheHeaders(etag),
      });
    }
    const builtKey = `${project.id}\n${etag}`;
    const cached = builtPreviews.get(builtKey) ?? adapter.previewDocuments?.read(builtKey);
    if (cached) {
      rememberPreview(builtKey, cached);
      return c.html(cached, 200, previewCacheHeaders(etag));
    }
    let pending = previewBuilds.get(builtKey);
    if (!pending) {
      pending = buildPreview(project, previewVariables, builtKey, capture, signature).finally(() =>
        previewBuilds.delete(builtKey),
      );
      previewBuilds.set(builtKey, pending);
    }
    const html = await pending;
    if (!html) return c.text("not found", 404);
    return c.html(html, 200, previewCacheHeaders(etag));
  });

  /** Ids minted from the raw file before the build rewrites attributes, so they match the source's;
   * in memory only, since a write here reaches the watcher as an outside edit. null: the file vanished. */
  function pinSubCompHfIds(compFile: string, compPath: string): string | undefined | null {
    if (!/\.html?$/i.test(compPath)) return undefined;
    try {
      return ensureHfIds(readFileSync(compFile, "utf-8"));
    } catch {
      return null;
    }
  }

  // Sub-composition preview
  // fallow-ignore-next-line complexity
  api.get("/projects/:id/preview/comp/*", async (c) => {
    const resolved = await resolveProjectAndSignature(adapter, c.req.param("id"));
    if (!resolved) return c.json({ error: "not found" }, 404);
    const { project, signature } = resolved;

    // fallow-ignore-next-line code-duplication
    const vars = previewVariablesFromRequest(c.req.query("variables"));
    if (vars.error !== undefined) return c.json({ error: vars.error }, 400);
    const previewVariables = vars.values;
    const compPath = requestSubPath(c.req.url, "projects/:id/preview/comp");
    const compFile = resolveWithinProject(project.dir, compPath);
    if (compFile) recordPreviewRead(project.dir, compFile);
    // The sub-composition document takes its head from the root.
    recordPreviewRead(project.dir, "index.html");
    if (!compFile || !existsSync(compFile) || !statSync(compFile).isFile()) {
      return c.text("not found", 404);
    }

    // "v2" salts the etag for the hf-id-pinning change below: a client holding
    // a pre-pin cached response (preview-only ids, unstamped disk file) must
    // not revalidate to a 304 that skips the pin.
    const compPathHash = createHash("sha1").update(compPath).digest("hex");
    const capture = c.req.query(PREVIEW_CAPTURE_PARAM) !== undefined;
    const etag = `"comp:v2:${compPathHash}:${signature}${variablesEtagSalt(vars.raw)}${capture ? ":capture" : ""}"`;
    const ifNoneMatch = c.req.header("If-None-Match");
    if (ifNoneMatch === etag) {
      return new Response(null, {
        status: 304,
        headers: previewCacheHeaders(etag),
      });
    }

    const stamped = pinSubCompHfIds(compFile, compPath);
    if (stamped === null) return c.text("not found", 404); // file removed between stat and read

    const baseHref = previewBaseHref(project.id);
    let html = buildSubCompositionHtml(
      project.dir,
      compPath,
      adapter.runtimeUrl,
      baseHref,
      stamped,
    );
    if (!html) return c.text("not found", 404);
    recordPreviewReferences(project.dir, html);
    html = ensureHfIds(await transformPreviewHtml(html, adapter, project, compPath));
    html = injectStudioPreviewAugmentations(html, adapter, project.dir, compPath, capture);
    if (previewVariables) html = injectPreviewVariables(html, previewVariables);
    html = await injectMediaCodecMap(html, adapter, project.dir, compPath, mediaCodecProbeCache);
    return c.html(html, 200, previewCacheHeaders(etag));
  });

  // Static asset serving (with range request support for audio/video seeking)
  // fallow-ignore-next-line complexity
  api.get("/projects/:id/preview/*", async (c) => {
    const project = await adapter.resolveProject(c.req.param("id"));
    if (!project) return c.json({ error: "not found" }, 404);
    const subPath = requestSubPath(c.req.url, "projects/:id/preview");
    // Assets are read-only and should mirror the renderer: permit a path that
    // is lexically inside the project even if an explicit project symlink
    // targets a shared directory outside it. Composition source files still
    // use resolveWithinProject because saves write their data-hf-id values.
    const candidate = resolve(project.dir, subPath);
    const file = isWithinProjectRoot(project.dir, candidate) ? candidate : null;
    if (!file || isPrivateProjectFile(project.dir, file)) {
      return c.text("not found", 404);
    }
    recordPreviewRead(project.dir, file);
    const stat = existsSync(file) ? statSync(file) : null;
    if (!stat?.isFile()) {
      return c.text("not found", 404);
    }
    const contentType = getMimeType(subPath);
    const isText = /\.(html|css|js|json|svg|txt|md|cube)$/i.test(subPath);

    // `?hf-proxy=` follows the asset's alpha-aware proxy variant. The
    // param value must be recognized (matching play/staticProjectServer),
    // only a video asset can be proxied, and only when auto-proxy is enabled
    // for this adapter/project. Checked BEFORE any transcode or 304 shortcut
    // so a bogus/disabled request never spawns ffmpeg.
    const proxyParam = c.req.query("hf-proxy");
    const boxParam = c.req.query(PREVIEW_PROXY_BOX_PARAM);
    const proxyBox = boxParam === undefined ? undefined : parsePreviewProxyBox(boxParam);
    if (proxyBox === null || (proxyBox && proxyParam === undefined)) {
      return c.text("not found", 404);
    }
    let proxyVariant: ProxyVariant | undefined;
    if (proxyParam !== undefined) {
      if (
        !isProxyVariantRequest(proxyParam) ||
        !contentType.startsWith("video/") ||
        !isAutoProxyEnabled(adapter)
      ) {
        return c.text("not found", 404);
      }
      const facts = await probeAssetCodec(file, undefined, mediaCodecProbeCache);
      const eligibility = decideMediaProxyEligibility(facts);
      if (!eligibility.eligible) {
        return c.text(`media proxy unavailable: ${eligibility.reason}`, 422);
      }
      if (!facts) return c.text("media proxy unavailable: unknown_codec", 422);
      proxyVariant = resolveProxyVariantRequest(proxyParam, facts) ?? undefined;
      if (!proxyVariant) {
        return c.text("media proxy variant does not match asset", 422);
      }
    }

    const tag = settledFileTag(stat);
    const etag = tag && `"${tag}${proxyEtagSalt(proxyVariant, proxyBox)}"`;
    const cacheHeaders: Record<string, string> = isText
      ? { "Cache-Control": "no-store" }
      : { "Cache-Control": "private, no-cache", ...(etag && { ETag: etag }) };

    if (!isText && etag) {
      const ifNoneMatch = c.req.header("If-None-Match");
      if (ifNoneMatch === etag) {
        return new Response(null, { status: 304, headers: cacheHeaders });
      }
    }

    // Resolve to the cached proxy (transcoding on miss) only after the 404/304
    // shortcuts above — the source's own mtime+size already salts the etag,
    // so a 304 never needs to await a transcode at all.
    let servedPath = file;
    let servedContentType = contentType;
    if (proxyVariant !== undefined) {
      try {
        // A cached copy settles before any timer; a transcode never holds one of
        // the browser's few connections to this host. 202 until the copy lands.
        servedPath = await waitForProxy(resolveProxy(project.dir, file, proxyVariant, proxyBox), 0);
      } catch (err) {
        if (err instanceof ProxyWaitTimeoutError) {
          return c.text("media proxy is being made", 202, {
            "Retry-After": String(PROXY_PENDING_RETRY_AFTER_SECONDS),
            "Cache-Control": "no-store",
          });
        }
        if (err instanceof ProxyCapacityError) {
          return c.text(err.message, 503, { "Retry-After": "5" });
        }
        if (isProjectRootMissing(err)) throw err;
        const message = err instanceof ProxyTranscodeError ? err.message : "proxy transcode failed";
        return c.text(message, 502);
      }
      // After the wait, not at the eligibility gate: one count per served proxy shares
      // a unit with `prewarmsRequested`; a 304, a 202 or a failure serves none.
      recordProxyRequest();
      servedContentType = PROXY_VARIANT_CONFIG[proxyVariant].contentType;
    }

    // Text is small and keeps its utf-8 round trip in memory. Binary media
    // streams only the requested window: Chrome refills a playing <video> or
    // <audio> with a fresh Range request every few hundred milliseconds, and a
    // 1KB slice of a multi-hundred-MB source must not readFileSync the whole
    // file on each one. The full read also blocked the event loop, so every
    // other Studio request (SSE, saves, the voice track) waited behind it.
    const textBuffer = isText ? Buffer.from(readFileSync(file, "utf-8"), "utf-8") : null;
    const totalSize = textBuffer ? textBuffer.length : statSync(servedPath).size;
    const bodyFor = (start: number, end: number): BodyInit =>
      textBuffer
        ? new Uint8Array(textBuffer.subarray(start, end + 1))
        : // Node's web stream type and the DOM one do not overlap for tsc on
          // every platform's lib set; the double cast is the documented bridge.
          (Readable.toWeb(
            createReadStream(servedPath, { start, end }),
          ) as unknown as ReadableStream);

    // Support byte-range requests so browsers can seek audio/video elements.
    const rangeHeader = c.req.header("Range");
    const match = rangeHeader ? /bytes=(\d+)-(\d*)/.exec(rangeHeader) : null;
    if (match) {
      const start = parseInt(match[1]!, 10);
      const end = match[2] ? parseInt(match[2], 10) : totalSize - 1;
      const safeEnd = Math.min(end, totalSize - 1);
      if (start > safeEnd) {
        return new Response(null, {
          status: 416,
          headers: { ...cacheHeaders, "Content-Range": `bytes */${totalSize}` },
        });
      }
      return new Response(bodyFor(start, safeEnd), {
        status: 206,
        headers: {
          ...cacheHeaders,
          "Content-Type": servedContentType,
          "Content-Range": `bytes ${start}-${safeEnd}/${totalSize}`,
          "Accept-Ranges": "bytes",
          "Content-Length": String(safeEnd - start + 1),
        },
      });
    }

    return new Response(totalSize > 0 ? bodyFor(0, totalSize - 1) : null, {
      headers: {
        ...cacheHeaders,
        "Content-Type": servedContentType,
        "Accept-Ranges": "bytes",
        "Content-Length": String(totalSize),
      },
    });
  });
}