Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
/**
* Shader transition option types, constants, and pure helper functions for
* injecting shader capture scale and loading mode parameters into composition
* URLs and srcdoc HTML.
*/
import { ensureRuntimeBeforeBodyScripts } from "./runtime-in-srcdoc.js";
import { RUNTIME_CDN_URL } from "./runtime-url.js";
export const SHADER_CAPTURE_SCALE_ATTR = "shader-capture-scale";
export const SHADER_LOADING_ATTR = "shader-loading";
export const RUNTIME_SRC_ATTR = "runtime-src";
const SHADER_CAPTURE_SCALE_PARAM = "__hf_shader_capture_scale";
const SHADER_LOADING_PARAM = "__hf_shader_loading";
export const SHADER_LOADING_PHRASES = [
"Preparing scene transitions",
"Sampling outgoing scene motion",
"Sampling incoming scene motion",
"Caching transition frames",
"Finalizing transition preview",
];
export type ShaderLoadingMode = "composition" | "player" | "none";
export interface ShaderTransitionState {
ready?: boolean;
progress?: number;
total?: number;
currentTransition?: number;
transitionTotal?: number;
transitionFrame?: number;
transitionFrames?: number;
phase?: "cached" | "capturing" | "finalizing";
loading?: boolean;
}
function normalizeShaderCaptureScale(value: string | null): string | null {
if (value === null) return null;
const parsed = Number(value);
if (!Number.isFinite(parsed) || parsed <= 0) return null;
return String(Math.min(1, Math.max(0.25, parsed)));
}
function normalizeShaderLoadingMode(value: string | null): ShaderLoadingMode {
if (value === null || value.trim() === "") return "composition";
const normalized = value.trim().toLowerCase();
if (
normalized === "none" ||
normalized === "false" ||
normalized === "0" ||
normalized === "off"
) {
return "none";
}
if (
normalized === "player" ||
normalized === "true" ||
normalized === "1" ||
normalized === "on"
) {
return "player";
}
return "composition";
}
/** Drop one of our own keys from raw `a=1&b=2` pairs, matched by name so that
* nothing around it has to be decoded. */
function withoutParam(pairs: string[], key: string): string[] {
return pairs.filter((pair) => pair !== "" && pair.split("=")[0] !== key);
}
/**
* The player's own params, appended to the query the composition author wrote
* rather than merged into a re-serialized copy of it.
*
* `new URLSearchParams(query).toString()` is a form-encoding round trip: it
* re-encodes the *whole* query as application/x-www-form-urlencoded, which
* writes every space as `+`. A composition reading its own query with
* `decodeURIComponent` — percent-decoding, which leaves `+` alone — cannot undo
* that, so a value of "Ship it today" arrived on the page as "Ship+it+today".
* The two codecs are not inverses, and the player has no business picking one
* for a query it is only passing along. The author's bytes now travel through
* byte-identical; only our two keys are rewritten.
*/
function withShaderQueryParams(
src: string,
scale: string | null,
loadingMode: ShaderLoadingMode,
): string {
const hashIndex = src.indexOf("#");
const beforeHash = hashIndex >= 0 ? src.slice(0, hashIndex) : src;
const hash = hashIndex >= 0 ? src.slice(hashIndex) : "";
const queryIndex = beforeHash.indexOf("?");
const path = queryIndex >= 0 ? beforeHash.slice(0, queryIndex) : beforeHash;
const query = queryIndex >= 0 ? beforeHash.slice(queryIndex + 1) : "";
let pairs = withoutParam(query.split("&"), SHADER_CAPTURE_SCALE_PARAM);
pairs = withoutParam(pairs, SHADER_LOADING_PARAM);
if (scale !== null) pairs.push(`${SHADER_CAPTURE_SCALE_PARAM}=${encodeURIComponent(scale)}`);
if (loadingMode !== "composition") {
pairs.push(`${SHADER_LOADING_PARAM}=${encodeURIComponent(loadingMode)}`);
}
const nextQuery = pairs.join("&");
return `${path}${nextQuery ? `?${nextQuery}` : ""}${hash}`;
}
function injectShaderOptionsIntoSrcdoc(
html: string,
scale: string | null,
loadingMode: ShaderLoadingMode,
): string {
if (scale === null && loadingMode === "composition") return html;
const lines: string[] = [];
if (scale !== null) lines.push(`window.__HF_SHADER_CAPTURE_SCALE=${JSON.stringify(scale)};`);
if (loadingMode !== "composition") {
lines.push(`window.__HF_SHADER_LOADING=${JSON.stringify(loadingMode)};`);
}
const script = `<script data-hyperframes-player-shader-options>${lines.join("")}</script>`;
if (/<head\b[^>]*>/i.test(html))
return html.replace(/<head\b[^>]*>/i, (match) => `${match}${script}`);
if (/<html\b[^>]*>/i.test(html))
return html.replace(/<html\b[^>]*>/i, (match) => `${match}${script}`);
return `${script}${html}`;
}
/**
* Convenience wrappers that read shader attributes directly from an element,
* avoiding boilerplate in the web component class body.
*/
export function getShaderModeFromElement(el: Element): ShaderLoadingMode {
return normalizeShaderLoadingMode(el.getAttribute(SHADER_LOADING_ATTR));
}
export function getShaderCaptureScaleFromElement(el: Element): number {
return Number(normalizeShaderCaptureScale(el.getAttribute(SHADER_CAPTURE_SCALE_ATTR)) ?? "1");
}
export function prepareSrcForElement(el: Element, src: string): string {
return withShaderQueryParams(
src,
normalizeShaderCaptureScale(el.getAttribute(SHADER_CAPTURE_SCALE_ATTR)),
getShaderModeFromElement(el),
);
}
export function prepareSrcdocForElement(el: Element, srcdoc: string): string {
// Runtime first, and in the head: a component's inline script reads its
// variables while the body is parsing, long before the probe's own injection
// could land. See runtime-in-srcdoc.ts.
return ensureRuntimeBeforeBodyScripts(
injectShaderOptionsIntoSrcdoc(
srcdoc,
normalizeShaderCaptureScale(el.getAttribute(SHADER_CAPTURE_SCALE_ATTR)),
getShaderModeFromElement(el),
),
runtimeSrcFromElement(el),
);
}
export function runtimeSrcFromElement(el: Element): string {
const configured = el.getAttribute(RUNTIME_SRC_ATTR)?.trim();
if (!configured) return RUNTIME_CDN_URL;
try {
const url = new URL(configured, document.baseURI);
// A srcdoc frame runs with `allow-same-origin` by default, so it inherits the embedder's
// origin. An unrestricted host here would therefore be arbitrary script execution in the
// embedding page, reachable through a prop bag since React spreads unknown props onto
// custom elements. Loopback and same-origin cover the local rig this exists for; a foreign
// origin has to be a deliberate, named opt-in rather than a scheme check falling through.
const okScheme = url.protocol === "http:" || url.protocol === "https:";
const loopback =
url.hostname === "127.0.0.1" || url.hostname === "localhost" || url.hostname === "[::1]";
return okScheme && (loopback || url.origin === location.origin) ? url.href : RUNTIME_CDN_URL;
} catch {
return RUNTIME_CDN_URL;
}
}