Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { resolve } from "node:path";
import { formatPreviewProxyBox, type PreviewProxyBox } from "@hyperframes/core";
import { insertBeforeCloseTag } from "@hyperframes/core/compiler/html-document";
import type { StudioApiAdapter } from "../types.js";
import {
createMediaCodecProbeCache,
proxyVariantFor,
recordProxyPrewarm,
scanProjectMediaCodecMap,
shouldPrewarmProxy,
type HtmlSourceLike,
type MediaCodecMap,
type MediaCodecProbeCache,
} from "./mediaCodecMap.js";
import { resolveProxy, PROXY_PARAMS_VERSION } from "./proxyTranscoder.js";
/**
* Transparent-media-proxy wiring shared by `routes/preview.ts`
* (docs/plans/2026-07-14-002-feat-transparent-media-proxies-plan.md, unit U3).
* Split out of the route module to keep it under the repo's 600-line file cap.
*/
/**
* Preview-route-local adapter surface for the auto-proxy feature. Both
* fields are optional so any existing `StudioApiAdapter` value remains
* structurally assignable without editing the shared interface:
* `autoProxy` defaults to true (on) when omitted — a later unit wires the
* CLI `--no-proxy` flag / `hyperframes.json` setting through it;
* `mediaCodecProbeCache` lets a host share one probe cache across
* preview/play/static-server surfaces instead of each constructing its own.
*/
export type PreviewApiAdapter = StudioApiAdapter & {
autoProxy?: boolean;
mediaCodecProbeCache?: MediaCodecProbeCache;
/** Keeps built preview documents across restarts, keyed by project id and preview ETag. */
previewDocuments?: PreviewDocumentStore;
};
export interface PreviewDocumentStore {
read(key: string): string | null;
write(key: string, html: string): void;
}
export function isAutoProxyEnabled(adapter: PreviewApiAdapter): boolean {
return adapter.autoProxy !== false;
}
/** One probe cache per server instance — construct once in `registerPreviewRoutes`
* and reuse across every request so the mtime-cache benefit in
* `scanProjectMediaCodecMap` actually applies. A host that wants to share the
* cache across other surfaces (play, static project server) can pass its own
* via `adapter.mediaCodecProbeCache`. */
export function resolvePreviewMediaCodecProbeCache(
adapter: PreviewApiAdapter,
): MediaCodecProbeCache {
return adapter.mediaCodecProbeCache ?? createMediaCodecProbeCache();
}
/**
* ETag salt for `?hf-proxy=` asset requests, mirroring `variablesEtagSalt` in
* preview.ts: salted by the raw param value plus the transcoder's params
* version, so a future proxy-recipe change (which bumps `PROXY_PARAMS_VERSION`)
* or a different proxy variant invalidates cached 304s without needing to
* touch the proxy file itself.
*/
export function proxyEtagSalt(raw: string | undefined, box?: PreviewProxyBox): string {
if (raw === undefined) return "";
return `:proxy:${raw}:${PROXY_PARAMS_VERSION}${box ? `:${formatPreviewProxyBox(box)}` : ""}`;
}
/**
* Injects `window.__HF_MEDIA_CODEC_MAP__` (the U1 codec-facts scan) into
* served composition HTML, and fire-and-forget pre-warms `resolveProxy` for
* every entry whose codec no browser decodes, so an element's proactive swap
* usually hits a warm cache (KTD: protects the per-origin connection budget
* under held responses). Conditionally hostile codecs are injected but NOT
* pre-warmed: the requesting browser usually plays them, and the transcode
* runs concurrently with its first layout. No second concurrency limiter here
* — the transcoder's own global bound throttles both pre-warm and
* element-triggered calls. Pre-warm failures are swallowed; an actual
* `?hf-proxy=` request surfaces them as a 502 and transcodes lazily.
* Alpha-bearing entries pre-warm their VP8/WebM variant.
*
* The single shared implementation for every auto-proxy surface — the studio
* preview route (via `injectMediaCodecMap` below) and the CLI's composition /
* static project servers (via the `./media-proxy-preview` subpath export).
* Empty maps leave HTML untouched, preserving the normal no-hostile-media
* preview path. On-demand proxy requests enforce the same eligibility gate.
*/
export async function injectMediaCodecMapIntoHtml(
html: string,
projectDir: string,
htmlSources: HtmlSourceLike[],
probeCache?: MediaCodecProbeCache,
prewarm = true,
/** Aborting it stops the pre-warms nobody else waits for. */
signal?: AbortSignal,
): Promise<string> {
let map: MediaCodecMap;
try {
map = await scanProjectMediaCodecMap(
projectDir,
htmlSources,
probeCache ? { cache: probeCache } : {},
);
} catch {
// Best-effort: a scan failure must never block serving the page.
return html;
}
if (Object.keys(map).length === 0) return html;
for (const [rootRelativePathname, facts] of Object.entries(map)) {
if (!prewarm || !shouldPrewarmProxy(facts)) continue;
recordProxyPrewarm();
resolveProxy(
projectDir,
resolve(projectDir, rootRelativePathname.replace(/^\/+/, "")),
proxyVariantFor(facts),
undefined,
{ signal },
).catch(() => {
// Swallowed: the pre-warm is best-effort. A real `?hf-proxy=` request
// for this asset hears the remembered failure (502) or re-attempts it.
});
}
// <-escape prevents a src path containing "</script>" from breaking out of
// the injected tag, mirroring injectPreviewVariables in helpers/previewVariables.ts.
const json = JSON.stringify(map)
.replace(/</g, "\\u003c")
.replace(/\u2028/g, "\\u2028")
.replace(/\u2029/g, "\\u2029");
const tag = `<script data-hf-media-codec-map>window.__HF_MEDIA_CODEC_MAP__=${json};</script>`;
return insertBeforeCloseTag(html, "head", `${tag}\n`) ?? `${tag}\n${html}`;
}
/**
* Adapter-aware wrapper used by the studio preview routes: skipped entirely
* (no scan, no injection) when auto-proxy is off for this adapter.
*/
export async function injectMediaCodecMap(
html: string,
adapter: PreviewApiAdapter,
projectDir: string,
compSrcPath: string,
probeCache: MediaCodecProbeCache,
): Promise<string> {
if (!isAutoProxyEnabled(adapter)) return html;
return injectMediaCodecMapIntoHtml(html, projectDir, [{ html, compSrcPath }], probeCache, false);
}